@codyswann/lisa 2.260.2 → 2.262.0

package/package.json

@@ -105,7 +105,7 @@
     "form-data": ">=4.0.6"
   },
   "name": "@codyswann/lisa",
-  "version": "2.260.2",
+  "version": "2.262.0",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {

package/plugins/lisa/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.260.2",
+  "version": "2.262.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.260.2",
+  "version": "2.262.0",
   "description": "Universal governance: agents, skills, commands, hooks, and rules for all projects.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/skills/lisa-implement/SKILL.md

@@ -228,22 +228,52 @@ Before shutting down the team, execute the Verify flow:
 
 1. Run quality gates: lint, typecheck, tests — all must pass. These are prerequisites, NOT verification.
 2. `verification-specialist`: verify locally by running the actual system and observing results (empirical proof that the change works). This is the real verification step. For UI-surface bugs, the proof must observe the UI surface with browser/device automation against the target environment whenever such a harness exists; unit-level or API-only proof cannot satisfy the empirical verification contract for a UI-surface defect.
-2a. **Record the verification verdict** — the independent, machine-readable proof that gates completion. The `verification-specialist` writes `${CLAUDE_PROJECT_DIR:-.}/.lisa/verification-status.json` with one entry per acceptance criterion, each carrying the proof command's observed evidence:
+2a. **Record the verification verdict** — the independent, machine-readable proof that gates completion. The `verification-specialist` writes `${CLAUDE_PROJECT_DIR:-.}/.lisa/verification-status.json` in **schema v2**, which binds every claim to the *boundary* it asserts and to the evidence *kinds* that reach that boundary, per the `claim-evidence-mapping` rule:
 
     ```json
     {
+      "schema_version": 2,
       "plan": "<plan-name>",
-      "status": "pass | fail | blocked | in_progress",
+      "artifact": {
+        "repository": "<owner/repo>", "base_sha": "<sha>", "head_sha": "<sha of what will ship>",
+        "build_id": "<build/run id>", "environment": "<where it was observed>", "observed_at": "<ISO8601 UTC>"
+      },
+      "claims": [
+        {
+          "claim_id": "AC-1",
+          "statement": "<the claim, in the operator's language>",
+          "boundary": "code-unit | browser | http-api | cli | data | deploy-health | performance | standards-compat",
+          "required_for_gate": true,
+          "required_evidence_kinds": ["<kinds that reach this boundary, e.g. screenshot, recording>"],
+          "status": "established | not-established",
+          "evidence_refs": ["EV-1"],
+          "not_established": ["<what this claim does NOT cover>"]
+        }
+      ],
+      "evidence": [
+        {
+          "evidence_id": "EV-1",
+          "kind": "screenshot | recording | http-transcript | cli-output | log-snippet | db-query-output | perf-trace | test-run-log | deploy-log | state-dump",
+          "locator": "evidence/<ticket>/<file>", "sha256": "<hash>",
+          "captured_at": "<ISO8601 UTC>", "artifact_head_sha": "<sha the artifact was captured at>"
+        }
+      ],
+      "not_established_reviewed": true,
       "criteria": [
         { "task": "<task id or title>", "criterion": "<the completion condition>", "status": "pass | fail | blocked", "evidence": "<the proof command run and the observed result; for a blocked criterion, the blocker diagnosis (e.g. the missing access and the probe that must pass)>" }
       ],
+      "status": "pass | fail | blocked | in_progress",
       "updated_at": "<ISO8601 UTC>"
     }
     ```
 
+    Rules for v2: a claim is established **only** by evidence whose `kind` reaches its `boundary` — a unit `test-run-log` reaches only `code-unit` and can never establish a `browser`, `http-api`, or `deploy-health` claim. `not_established_reviewed` must always be present (the `not_established` list may be empty, but the flag may never be omitted). `artifact.head_sha` names what will ship, and each evidence entry's `artifact_head_sha` must match it. The legacy `criteria[]` array is retained and still read, but under v2 it is **display-only** — it can never establish a v2 claim.
+
+    **v1 is still accepted during the compatibility window.** A verdict that omits `schema_version` (or sets it to `1`) carries only `plan` / `status` / `criteria[]` / `updated_at` and is judged exactly as before: terminal `status` plus no failing criterion plus freshness. Write v2 for new work; nothing in flight breaks.
+
     Set `status: "pass"` only when every criterion is `pass` with real evidence (output from running the system, not a claim). The verdict must be judged by an agent that did NOT implement the change (the `verification-specialist`), never self-certified by the implementer. This is runtime scratch — it is gitignored and MUST NOT be committed (treat it like the secrets exclusion in the commit step).
 
-    On Claude, the `enforce-verification-gate.sh` Stop hook reads this file and **will not let the flow stop** until it shows a terminal, all-`pass` verdict — carrying over the non-bypassable completion gate of the `/goal` primitive, but checked deterministically against real evidence rather than by a transcript-only evaluator model. If you must stop before completion, write the verdict with `status: "blocked"` and the reason — marking each criterion whose proof is blocked as `status: "blocked"` with the blocker diagnosis as its `evidence`, while unaffected criteria keep their real `pass`/`fail` result — that records the outcome and releases the gate instead of leaving it to spin. But a `blocked` verdict is a last resort, not a shortcut around fillable work: **first resolve every gap you can resolve yourself.** If the work item is thin — missing its Validation Journey, acceptance criteria, or other derivable detail — enrich it: derive the missing detail from the ticket context and the codebase, write it back, and proceed. Do **not** block on a gap you could have filled. Only a blocker that survives that attempt is real, and it is one of two kinds:
+    On Claude, the `enforce-verification-gate.sh` Stop hook reads this file — both v1 and v2 — and **will not let the flow stop** until it shows a terminal, all-`pass` verdict. The v2 claim/evidence checks are **advisory-first**: a boundary or identity violation is reported to stderr but does not block until `verification.gate.enforceBoundaries` is set to `true` in `.lisa.config.json` (default `false`, promoted via the threshold ratchet). Treat an advisory warning as a defect to fix now, not a warning to ignore — it becomes blocking on the ratchet. The gate — carrying over the non-bypassable completion gate of the `/goal` primitive, but checked deterministically against real evidence rather than by a transcript-only evaluator model. If you must stop before completion, write the verdict with `status: "blocked"` and the reason — marking each criterion whose proof is blocked as `status: "blocked"` with the blocker diagnosis as its `evidence`, while unaffected criteria keep their real `pass`/`fail` result — that records the outcome and releases the gate instead of leaving it to spin. But a `blocked` verdict is a last resort, not a shortcut around fillable work: **first resolve every gap you can resolve yourself.** If the work item is thin — missing its Validation Journey, acceptance criteria, or other derivable detail — enrich it: derive the missing detail from the ticket context and the codebase, write it back, and proceed. Do **not** block on a gap you could have filled. Only a blocker that survives that attempt is real, and it is one of two kinds:
 
     - **Actionable blocker** — an unresolved dependency or fixable technical gap that some team or repository could build (a missing or changed schema field, an unbuilt sibling work item, a required upstream fix), **including cross-repo dependencies**. Before writing the blocked verdict you MUST (1) file a build-ready fix/dependency ticket capturing the diagnosis — in the dependency's own repository/tracker when it is cross-repo (e.g. a `[<repo>] …` ticket in the shared project, or the sibling tracker) — and (2) link the current work item to it as `is blocked by`. Only then write the verdict. This is the same discipline as the regression-spec blocker and the remote-verification-fail exits above, and it is what makes the block machine-recoverable: `repair-intake` re-dispatches a blocked item once its linked `is blocked by` dependency closes, but it cannot act on a prose-only comment. Recommending the ticket "as a human follow-up" without filing and linking it is **not** a permitted exit.
     - **Human-only blocker** — an input the agent genuinely cannot obtain or produce no matter what it does: credentials, secrets, or **tool access** it does not have (AWS/CloudWatch, Figma, Jam, Sentry, SonarCloud, a database, a protected deploy target, …), or a product/design decision only a human can make. For missing tool access, follow the `tool-access-gate` rule's break-out protocol: post the "Access Needed" comment naming the exact credential/role/env var to grant and the probe that must pass — never work around the gap by substituting weaker verification, mocking the inaccessible system, or narrowing scope. Record the blocked verdict, mark it `human_needed` (the marker `repair-intake` recognizes, so it won't churn re-dispatching it), and surface or reassign to a human; do **not** fabricate a build-ready ticket, because there is no build-ready work.

package/plugins/lisa/hooks/enforce-verification-gate.sh

@@ -27,7 +27,33 @@
 #                        by a per-session block counter so a genuinely-stuck flow
 #                        ESCALATES instead of looping forever.
 #
-# The verdict artifact lives at "$CLAUDE_PROJECT_DIR/.lisa/verification-status.json":
+# The verdict artifact lives at "$CLAUDE_PROJECT_DIR/.lisa/verification-status.json".
+#
+# SCHEMA v2 (current) binds every claim to a boundary and to the evidence kinds
+# that reach it, per the claim-evidence-mapping contract:
+#   {
+#     "schema_version": 2,
+#     "plan": "<plan-name>",
+#     "artifact": { "repository": "owner/repo", "base_sha": "...", "head_sha": "...",
+#                   "build_id": "...", "environment": "...", "observed_at": "<ISO8601 UTC>" },
+#     "claims": [
+#       { "claim_id": "AC-1", "statement": "...", "boundary": "browser",
+#         "required_for_gate": true, "required_evidence_kinds": ["screenshot","recording"],
+#         "status": "established" | "not-established", "evidence_refs": ["EV-1"],
+#         "not_established": ["<what this claim does NOT cover>"] }
+#     ],
+#     "evidence": [
+#       { "evidence_id": "EV-1", "kind": "screenshot", "locator": "evidence/1836/x.png",
+#         "sha256": "...", "captured_at": "<ISO8601 UTC>", "artifact_head_sha": "..." }
+#     ],
+#     "not_established_reviewed": true,
+#     "criteria": [ ... legacy, display-only ... ],
+#     "status": "pass" | "fail" | "blocked" | "in_progress",
+#     "updated_at": "<ISO8601 UTC>"
+#   }
+#
+# SCHEMA v1 (legacy, still accepted during the compatibility window) omits
+# "schema_version" or sets it to 1, and carries only:
 #   {
 #     "plan": "<plan-name>",
 #     "status": "pass" | "fail" | "blocked" | "in_progress",
@@ -36,15 +62,39 @@
 #     ],
 #     "updated_at": "<ISO8601 UTC>"
 #   }
-# status "pass" (all criteria pass) or "blocked" (flow recorded a blocker and is
-# stopping deliberately) are terminal and release the gate. "fail"/"in_progress"
-# or a missing/stale file keep it closed.
+#
+# In BOTH schemas, status "pass" (all criteria pass) or "blocked" (flow recorded
+# a blocker and is stopping deliberately) are terminal and release the gate.
+# "fail"/"in_progress" or a missing/stale file keep it closed.
+#
+# Compatibility window: the gate branches on "schema_version". Absent or 1 takes
+# the v1 path unchanged — byte-for-byte the pre-v2 decision. 2 takes the v1 path
+# PLUS the claim->evidence checks below. Legacy "criteria" is display-only under
+# v2 and can never establish a v2 claim.
+#
+# v2 claim checks (only ever applied to an overall "pass"; a deliberate
+# "blocked" stop is terminal on the v1 conditions alone):
+#   - every claim with "required_for_gate": true is "status": "established"
+#   - each such claim's "evidence_refs" resolve to "evidence[]" entries, at
+#     least one of whose "kind" is in the claim's "required_evidence_kinds"
+#   - "not_established_reviewed": true is present (the list may be empty, but
+#     the flag may never be omitted)
+#   - "artifact.head_sha" exists and no evidence entry declares a different
+#     "artifact_head_sha" (reconciliation with the MERGED head is BCE-4)
+#
+# ADVISORY-FIRST: those v2 checks report to stderr but do NOT block unless
+# "verification.gate.enforceBoundaries" is true in .lisa.config.json (default
+# false at ship, promoted via the threshold ratchet). While it is false, a v2
+# verdict releases on exactly the v1-equivalent conditions.
 #
 # Per-session state lives under "$STATE_DIR" as flag files keyed by session_id.
 # Stale state (>24h) is cleaned on each invocation.
 #
-# Fail-open: any unexpected jq parse failure or missing field exits 0 rather
-# than blocking. A broken gate must never brick a session.
+# Fail-open: any unexpected jq parse failure or missing field degrades to the
+# LESS strict outcome rather than inventing a new hard failure, and the
+# MAX_BLOCKS escalation below guarantees the gate always releases eventually. A
+# broken gate must never brick a session. In particular, a v2 verdict whose
+# claim structure cannot be evaluated is judged on the v1 conditions alone.
 
 set -uo pipefail
 
@@ -137,9 +187,14 @@ fi
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
 VERDICT_FILE="${PROJECT_DIR}/.lisa/verification-status.json"
 
+# Set by the v2 path when a claim/evidence violation is what closed the gate,
+# so the block message can state the real reason instead of the v1 fallback.
+V2_BLOCK_REASON=""
+
 # A terminal verdict (pass or blocked) with no failing criterion, written AFTER
-# the flow was armed, releases the gate.
-verdict_is_terminal() {
+# the flow was armed, releases the gate. This is the v1 decision, unchanged, and
+# it remains the floor for v2 as well.
+verdict_is_terminal_v1() {
   [ -f "$VERDICT_FILE" ] || return 1
 
   local status fails
@@ -160,6 +215,101 @@ verdict_is_terminal() {
   return 0
 }
 
+# True when the project has ratcheted the v2 claim checks from advisory to
+# blocking. Default false: a missing/unreadable config is advisory-only.
+boundary_enforcement_enabled() {
+  local config_file value
+  config_file="${PROJECT_DIR}/.lisa.config.json"
+  [ -f "$config_file" ] || return 1
+  value=$(jq -r '.verification.gate.enforceBoundaries // false' "$config_file" 2>/dev/null || printf 'false')
+  [ "$value" = "true" ]
+}
+
+# Emits one line per v2 claim->evidence contract violation. Empty output means
+# the verdict satisfies the contract (or could not be evaluated, which degrades
+# to the v1 decision rather than to a new hard failure).
+v2_contract_violations() {
+  jq -r '
+    . as $v
+    | ($v.evidence // []) as $ev
+    | (($v.artifact // {}).head_sha // "") as $head
+    | [
+        (if ($v.not_established_reviewed == true) then empty
+         else "not_established_reviewed is absent or not true - the flag may never be omitted" end),
+        (if ($head | length) > 0 then empty
+         else "artifact.head_sha is missing - required for a v2 pass" end),
+        ( $ev[]
+          | select(($head | length) > 0)
+          | select(((.artifact_head_sha // "") | length) > 0)
+          | select(.artifact_head_sha != $head)
+          | "evidence \(.evidence_id // "?") was captured at \(.artifact_head_sha) but artifact.head_sha is \($head)" ),
+        ( ($v.claims // [])[]
+          | select((.required_for_gate // false) == true)
+          | . as $c
+          | ($c.claim_id // "?") as $cid
+          | ($c.boundary // "?") as $bnd
+          | ($c.required_evidence_kinds // []) as $req
+          | ($req | join(", ")) as $reqs
+          | ([ ($c.evidence_refs // [])[] as $r | $ev[] | select((.evidence_id // "") == $r) ]) as $res
+          | (
+              (if (($c.status // "") == "established") then empty
+               else "claim \($cid) [boundary \($bnd)] is not established (status: \($c.status // "missing"); required kinds: \($reqs))" end),
+              (if ($res | length) == 0
+               then "claim \($cid) [boundary \($bnd)] cites no resolvable evidence (required kinds: \($reqs))"
+               elif ([ $res[].kind // "" ] | map(select(. as $k | $req | index($k))) | length) == 0
+               then "claim \($cid) [boundary \($bnd)] cited evidence kinds [\([$res[].kind // "?"] | join(", "))] do not reach the boundary (required kinds: \($reqs))"
+               else empty end)
+            )
+        )
+      ]
+    | .[]
+  ' "$VERDICT_FILE" 2>/dev/null || true
+}
+
+# v2 = the v1 decision PLUS the claim->evidence contract, the latter advisory
+# until verification.gate.enforceBoundaries is ratcheted on.
+verdict_is_terminal_v2() {
+  verdict_is_terminal_v1 || return 1
+
+  # Only a "pass" asserts that claims are established. A deliberate "blocked"
+  # stop records an outcome and is terminal on the v1 conditions alone.
+  local status violations
+  status=$(jq -r '.status // empty' "$VERDICT_FILE" 2>/dev/null || true)
+  [ "$status" = "pass" ] || return 0
+
+  violations=$(v2_contract_violations)
+  [ -n "$violations" ] || return 0
+
+  if boundary_enforcement_enabled; then
+    # Hand the diagnosis to the block message below so the operator reads one
+    # coherent reason instead of this plus a generic v1-shaped fallback.
+    V2_BLOCK_REASON=$(printf '%s\n' "$violations" | sed 's/^/  - /')
+    return 1
+  fi
+
+  {
+    echo "Verification gate (advisory): the v2 claim/evidence contract is not"
+    echo "satisfied. Releasing anyway because verification.gate.enforceBoundaries"
+    echo "is false. These become blocking when the flag is ratcheted on:"
+    printf '%s\n' "$violations" | sed 's/^/  - /'
+  } >&2
+  return 0
+}
+
+# Compatibility window: branch on schema_version. Absent or 1 -> the v1 decision
+# unchanged; 2 -> v1 plus the claim->evidence contract. An unrecognized or
+# unparseable value degrades to v1 rather than to a new failure mode.
+verdict_is_terminal() {
+  [ -f "$VERDICT_FILE" ] || return 1
+
+  local schema_version
+  schema_version=$(jq -r '.schema_version // empty' "$VERDICT_FILE" 2>/dev/null || true)
+  case "$schema_version" in
+    2) verdict_is_terminal_v2 ;;
+    *) verdict_is_terminal_v1 ;;
+  esac
+}
+
 if verdict_is_terminal; then
   # Gate satisfied — disarm so a follow-up stop in the same session is not
   # re-gated against the now-consumed verdict, and allow the stop.
@@ -205,6 +355,16 @@ fi
     echo "failed, base branch missing, unresolved dependency), write the verdict"
     echo "with status \"blocked\" and the reason instead. That records the"
     echo "outcome and releases this gate."
+  elif [ -n "$V2_BLOCK_REASON" ]; then
+    echo "The verdict claims to pass, but its evidence does not establish every"
+    echo "claim the gate requires:"
+    printf '%s\n' "$V2_BLOCK_REASON"
+    echo
+    echo "A claim counts only when the evidence cited for it is of a kind that"
+    echo "reaches that claim's boundary — a unit test log does not prove a"
+    echo "button works in a browser. Capture the reaching evidence and"
+    echo "re-verify, or — if genuinely blocked — set status \"blocked\" with the"
+    echo "reason."
   else
     echo "The verification verdict is not terminal-and-passing. Outstanding:"
     if [ -n "$REASON_DETAIL" ]; then

package/plugins/lisa/rules/eager/claim-evidence-mapping.md

@@ -0,0 +1,51 @@
+# 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. A claim with no reaching evidence is **Not established** (defined fully in
+**BCE-3 (#1837)**), an artifact's identity is pinned in **BCE-4 (#1838)**, and the conservative
+security-bucket default is set in **BCE-5 (#1839)** — each named here, defined there.
+
+## 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.
+
+Full contract (claim-boundary taxonomy, core inequality, worked example, field names): [reference/claim-evidence-mapping.md](../reference/claim-evidence-mapping.md).

package/plugins/lisa/rules/reference/claim-evidence-mapping.md

@@ -0,0 +1,132 @@
+# Claim → Evidence Mapping Contract
+
+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** —
+the concept is named here and defined fully, with its evidence templates, in **BCE-3 (#1837)**; do
+not assume that section is present in this branch. Artifact identity — what makes two captured
+artifacts the same or different — is pinned in **BCE-4 (#1838)**, and the conservative default
+bucket for a security-sensitive claim is set in **BCE-5 (#1839)**. Each is named here as the field
+BCE-2's schema will carry; none is defined by this contract. Each ships with that ticket — do not
+assume its section is present in this branch.
+
+### 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.
+```
+
+## 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. BCE-3 generalizes the *Not established* half of that
+discipline into a first-class report state.
+
+## 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.

package/plugins/lisa/skills/lisa-implement/SKILL.md

@@ -228,22 +228,52 @@ Before shutting down the team, execute the Verify flow:
 
 1. Run quality gates: lint, typecheck, tests — all must pass. These are prerequisites, NOT verification.
 2. `verification-specialist`: verify locally by running the actual system and observing results (empirical proof that the change works). This is the real verification step. For UI-surface bugs, the proof must observe the UI surface with browser/device automation against the target environment whenever such a harness exists; unit-level or API-only proof cannot satisfy the empirical verification contract for a UI-surface defect.
-2a. **Record the verification verdict** — the independent, machine-readable proof that gates completion. The `verification-specialist` writes `${CLAUDE_PROJECT_DIR:-.}/.lisa/verification-status.json` with one entry per acceptance criterion, each carrying the proof command's observed evidence:
+2a. **Record the verification verdict** — the independent, machine-readable proof that gates completion. The `verification-specialist` writes `${CLAUDE_PROJECT_DIR:-.}/.lisa/verification-status.json` in **schema v2**, which binds every claim to the *boundary* it asserts and to the evidence *kinds* that reach that boundary, per the `claim-evidence-mapping` rule:
 
     ```json
     {
+      "schema_version": 2,
       "plan": "<plan-name>",
-      "status": "pass | fail | blocked | in_progress",
+      "artifact": {
+        "repository": "<owner/repo>", "base_sha": "<sha>", "head_sha": "<sha of what will ship>",
+        "build_id": "<build/run id>", "environment": "<where it was observed>", "observed_at": "<ISO8601 UTC>"
+      },
+      "claims": [
+        {
+          "claim_id": "AC-1",
+          "statement": "<the claim, in the operator's language>",
+          "boundary": "code-unit | browser | http-api | cli | data | deploy-health | performance | standards-compat",
+          "required_for_gate": true,
+          "required_evidence_kinds": ["<kinds that reach this boundary, e.g. screenshot, recording>"],
+          "status": "established | not-established",
+          "evidence_refs": ["EV-1"],
+          "not_established": ["<what this claim does NOT cover>"]
+        }
+      ],
+      "evidence": [
+        {
+          "evidence_id": "EV-1",
+          "kind": "screenshot | recording | http-transcript | cli-output | log-snippet | db-query-output | perf-trace | test-run-log | deploy-log | state-dump",
+          "locator": "evidence/<ticket>/<file>", "sha256": "<hash>",
+          "captured_at": "<ISO8601 UTC>", "artifact_head_sha": "<sha the artifact was captured at>"
+        }
+      ],
+      "not_established_reviewed": true,
       "criteria": [
         { "task": "<task id or title>", "criterion": "<the completion condition>", "status": "pass | fail | blocked", "evidence": "<the proof command run and the observed result; for a blocked criterion, the blocker diagnosis (e.g. the missing access and the probe that must pass)>" }
       ],
+      "status": "pass | fail | blocked | in_progress",
       "updated_at": "<ISO8601 UTC>"
     }
     ```
 
+    Rules for v2: a claim is established **only** by evidence whose `kind` reaches its `boundary` — a unit `test-run-log` reaches only `code-unit` and can never establish a `browser`, `http-api`, or `deploy-health` claim. `not_established_reviewed` must always be present (the `not_established` list may be empty, but the flag may never be omitted). `artifact.head_sha` names what will ship, and each evidence entry's `artifact_head_sha` must match it. The legacy `criteria[]` array is retained and still read, but under v2 it is **display-only** — it can never establish a v2 claim.
+
+    **v1 is still accepted during the compatibility window.** A verdict that omits `schema_version` (or sets it to `1`) carries only `plan` / `status` / `criteria[]` / `updated_at` and is judged exactly as before: terminal `status` plus no failing criterion plus freshness. Write v2 for new work; nothing in flight breaks.
+
     Set `status: "pass"` only when every criterion is `pass` with real evidence (output from running the system, not a claim). The verdict must be judged by an agent that did NOT implement the change (the `verification-specialist`), never self-certified by the implementer. This is runtime scratch — it is gitignored and MUST NOT be committed (treat it like the secrets exclusion in the commit step).
 
-    On Claude, the `enforce-verification-gate.sh` Stop hook reads this file and **will not let the flow stop** until it shows a terminal, all-`pass` verdict — carrying over the non-bypassable completion gate of the `/goal` primitive, but checked deterministically against real evidence rather than by a transcript-only evaluator model. If you must stop before completion, write the verdict with `status: "blocked"` and the reason — marking each criterion whose proof is blocked as `status: "blocked"` with the blocker diagnosis as its `evidence`, while unaffected criteria keep their real `pass`/`fail` result — that records the outcome and releases the gate instead of leaving it to spin. But a `blocked` verdict is a last resort, not a shortcut around fillable work: **first resolve every gap you can resolve yourself.** If the work item is thin — missing its Validation Journey, acceptance criteria, or other derivable detail — enrich it: derive the missing detail from the ticket context and the codebase, write it back, and proceed. Do **not** block on a gap you could have filled. Only a blocker that survives that attempt is real, and it is one of two kinds:
+    On Claude, the `enforce-verification-gate.sh` Stop hook reads this file — both v1 and v2 — and **will not let the flow stop** until it shows a terminal, all-`pass` verdict. The v2 claim/evidence checks are **advisory-first**: a boundary or identity violation is reported to stderr but does not block until `verification.gate.enforceBoundaries` is set to `true` in `.lisa.config.json` (default `false`, promoted via the threshold ratchet). Treat an advisory warning as a defect to fix now, not a warning to ignore — it becomes blocking on the ratchet. The gate — carrying over the non-bypassable completion gate of the `/goal` primitive, but checked deterministically against real evidence rather than by a transcript-only evaluator model. If you must stop before completion, write the verdict with `status: "blocked"` and the reason — marking each criterion whose proof is blocked as `status: "blocked"` with the blocker diagnosis as its `evidence`, while unaffected criteria keep their real `pass`/`fail` result — that records the outcome and releases the gate instead of leaving it to spin. But a `blocked` verdict is a last resort, not a shortcut around fillable work: **first resolve every gap you can resolve yourself.** If the work item is thin — missing its Validation Journey, acceptance criteria, or other derivable detail — enrich it: derive the missing detail from the ticket context and the codebase, write it back, and proceed. Do **not** block on a gap you could have filled. Only a blocker that survives that attempt is real, and it is one of two kinds:
 
     - **Actionable blocker** — an unresolved dependency or fixable technical gap that some team or repository could build (a missing or changed schema field, an unbuilt sibling work item, a required upstream fix), **including cross-repo dependencies**. Before writing the blocked verdict you MUST (1) file a build-ready fix/dependency ticket capturing the diagnosis — in the dependency's own repository/tracker when it is cross-repo (e.g. a `[<repo>] …` ticket in the shared project, or the sibling tracker) — and (2) link the current work item to it as `is blocked by`. Only then write the verdict. This is the same discipline as the regression-spec blocker and the remote-verification-fail exits above, and it is what makes the block machine-recoverable: `repair-intake` re-dispatches a blocked item once its linked `is blocked by` dependency closes, but it cannot act on a prose-only comment. Recommending the ticket "as a human follow-up" without filing and linking it is **not** a permitted exit.
     - **Human-only blocker** — an input the agent genuinely cannot obtain or produce no matter what it does: credentials, secrets, or **tool access** it does not have (AWS/CloudWatch, Figma, Jam, Sentry, SonarCloud, a database, a protected deploy target, …), or a product/design decision only a human can make. For missing tool access, follow the `tool-access-gate` rule's break-out protocol: post the "Access Needed" comment naming the exact credential/role/env var to grant and the probe that must pass — never work around the gap by substituting weaker verification, mocking the inaccessible system, or narrowing scope. Record the blocked verdict, mark it `human_needed` (the marker `repair-intake` recognizes, so it won't churn re-dispatching it), and surface or reassign to a human; do **not** fabricate a build-ready ticket, because there is no build-ready work.

package/plugins/lisa-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.260.2",
+  "version": "2.262.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"