@codyswann/lisa 2.266.0 → 2.268.0

package/package.json

@@ -91,7 +91,8 @@
     "ws": ">=8.21.0",
     "multer": ">=2.2.0",
     "undici": ">=6.27.0",
-    "form-data": ">=4.0.6"
+    "form-data": ">=4.0.6",
+    "brace-expansion": ">=5.0.6"
   },
   "overrides": {
     "@isaacs/brace-expansion": "^5.0.1",
@@ -104,10 +105,11 @@
     "ws": ">=8.21.0",
     "multer": ">=2.2.0",
     "undici": ">=6.27.0",
-    "form-data": ">=4.0.6"
+    "form-data": ">=4.0.6",
+    "brace-expansion": ">=5.0.6"
   },
   "name": "@codyswann/lisa",
-  "version": "2.266.0",
+  "version": "2.268.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.266.0",
+  "version": "2.268.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.266.0",
+  "version": "2.268.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

@@ -278,7 +278,28 @@ Before shutting down the team, execute the Verify flow:
     - **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.
 
-    Other harnesses fall back to this prose obligation.
+    **Harnesses that do not fire a Stop hook enforce the same discipline by convention.** The
+    `enforce-verification-gate.sh` Stop hook is a **Claude-only** surface — Codex, Cursor, Antigravity,
+    Copilot, and OpenCode carry the skills, agents, and (where the runtime has a rules surface) the
+    `claim-evidence-mapping` rule, but nothing on those runtimes can refuse to stop. That is a known
+    **representation gap**, documented here rather than dropped: on those harnesses this prose gate
+    *is* the gate, and the flow may not declare completion until it has written the same v2 verdict
+    and self-checked it against the same expectations the hook would have applied:
+
+    - `schema_version: 2` is written, with `plan`, `status`, and `updated_at` terminal and fresh.
+    - Every claim carries a `claim_id`, a `boundary` from the closed set, and the
+      `required_evidence_kinds` that reach that boundary — and its `evidence_refs` resolve to evidence
+      whose `kind` is one of them. A unit `test-run-log` cited for a `browser`, `http-api`, or
+      `deploy-health` claim is the failure this check exists to catch.
+    - `artifact.head_sha` names what will ship, and every evidence entry's `artifact_head_sha` matches
+      it, with a `sha256` digest and `captured_at` recorded as values, never placeholders.
+    - The `not_established` list is present on every claim and `not_established_reviewed` is `true` —
+      an empty list is fine, an omitted flag is not.
+
+    Record the self-check in the completion summary the way the hook would have reported it: name the
+    boundary each claim reached, or name the violation. Where the runtime lacks the rules surface (the
+    agy artifacts carry no rules tree), the obligation still travels in this skill — cite the
+    `claim-evidence-mapping` contract by slug and continue; never block on the absent surface.
 3. Write the highest-practical-observation regression test encoding the verification. For user-visible bugs or user-visible Build changes with an available browser/device/e2e harness, this means a deterministic spec on the reported surface — and for frontend work, once the validation journey is verified, codification into **every supported UI runner**: a Playwright spec in the Playwright runner AND a Maestro flow when the project supports Maestro, per `codify-verification`. Prove the new spec actually executed and passed in PR CI by recording a named spec log/reporter line or equivalent execution record; green CI without that named evidence does not satisfy this step.
 4. Record Implement usage on the originating work artifact via `lisa-usage-accounting` so the work item (or other implementation-owned artifact) gains a direct `lisa-implement` usage entry in the canonical `## Lisa Usage` section. If the parent / child graph is already known, prefer `record_and_rollup` so ancestor totals refresh in the same write; otherwise still write the direct entry, and if runtime usage is unavailable, use `source: unavailable` with nullable token/cost fields instead of skipping the row.
 5. Commit ALL outstanding changes in logical batches on the branch (minus sensitive data/information) — not just changes made by the agent team. This includes pre-existing uncommitted changes that were on the branch before the plan started. Do NOT filter commits to only "task-related" files. If it shows up in git status, it gets committed (unless it contains secrets).

package/plugins/lisa/.codex-plugin/skills/lisa-spec-conformance/SKILL.md

@@ -67,11 +67,28 @@ Gather evidence of what was actually shipped:
    git diff "${BASE_BRANCH}"...HEAD -- '**/*.test.*' '**/*.spec.*'
    ```
 4. **Empirical evidence** — output of `verification-specialist` if available (proof artifacts, API captures, UI screenshots, DB queries). If that report isn't in context, ask the caller for it before proceeding — do not substitute reading code for running the system.
+4a. **The machine-readable verdict** — `Read` `${CLAUDE_PROJECT_DIR:-.}/.lisa/verification-status.json`. Under **schema v2** it is the structured form of the evidence above, and it is what lets you check a claim's *reach* instead of taking "verified" at its word. Load `artifact` (`repository`, `head_sha`, `environment`), `claims[]` (`claim_id`, `statement`, `boundary`, `required_evidence_kinds`, `status`, `evidence_refs`, `not_established`), `evidence[]` (`evidence_id`, `kind`, `locator`, `sha256`, `captured_at`, `artifact_head_sha`), and the `not_established_reviewed` flag.
 5. **PR description** — `gh pr view --json title,body,files` if a PR exists.
 6. **Deployed state** — if the verification phase already hit a deployed environment, use those captures.
 
 Do NOT run the system yourself — that's the verification-specialist's job. Your job is to map their evidence to the spec.
 
+## Phase 3b — Cross-Check Claims Against Their Boundaries
+
+The `claim-evidence-mapping` rule is the contract: **every claim declares a boundary, and a claim is established only by evidence of a kind that reaches that boundary.** Conformance is not just "was it built" — it is also "does the proof offered actually reach the thing the requirement asserts." A unit `test-run-log` cited for a requirement about browser-visible behavior is a conformance defect even when the code is perfect.
+
+For every v2 claim loaded in Phase 3 step 4a, run three checks:
+
+| Check | Rule | Failure |
+|-------|------|---------|
+| **Boundary reach** | Each `evidence_refs` entry resolves to an `evidence[]` row whose `kind` appears in that claim's `required_evidence_kinds` — and those kinds are the ones the `claim-evidence-mapping` taxonomy binds to the claim's `boundary` | `BOUNDARY_MISMATCH` |
+| **Artifact identity** | Every cited evidence row's `artifact_head_sha` equals `artifact.head_sha` — the claim applies only to the artifact the evidence was collected against | `BOUNDARY_MISMATCH`, noting both SHAs |
+| **Not established** | `not_established_reviewed` is present and `true`, and every claim carries a `not_established` list (possibly empty) | `BOUNDARY_MISMATCH` on the verdict as a whole |
+
+Then bind the verdict back to the spec: map each `claim_id` to the requirement row it discharges. A requirement whose only supporting claim fails a check is **not** `MATCH`, no matter what the verification report's prose said. A requirement with no claim at all is `MISSING`, not `PARTIAL`.
+
+**Degrade, never block.** If `.lisa/verification-status.json` is absent, or carries **v1** (no `schema_version`, or `schema_version: 1` — only `plan` / `status` / `criteria[]` / `updated_at`), the boundary cross-check is not available. Say so explicitly in the report ("v2 verdict not present — boundary reach unverified"), fall back to the prose evidence from Phase 3, and cap the verdict at `PARTIAL` for any requirement whose boundary you cannot confirm. Do not invent a mismatch you could not check, and do not silently upgrade an unchecked claim to `MATCH`.
+
 ## Phase 4 — Build Coverage Matrix
 
 For every requirement extracted in Phase 2, produce one row:
@@ -81,8 +98,10 @@ For every requirement extracted in Phase 2, produce one row:
 | Requirement ID | Stable identifier (e.g. `AC-1`, `OOS-2`, `ASSERT-3`) |
 | Classification | `acceptance` / `excluded` / `technical` / `assertion` / `deliverable` / `task` / `blocker` |
 | Requirement Text | Verbatim from spec |
-| Evidence | Specific pointer — file:line, test name, verification report section, PR file, screenshot name |
-| Status | `MATCH` / `PARTIAL` / `MISSING` / `SCOPE_CREEP_VIOLATION` |
+| Evidence | Specific pointer — file:line, test name, verification report section, PR file, screenshot name. When a v2 verdict exists, also name the `claim_id` and `evidence_id` that discharge it |
+| Boundary | The claim's `boundary` from the v2 verdict (`code-unit` / `browser` / `http-api` / `cli` / `data` / `deploy-health` / `performance` / `standards-compat`), or `—` when no v2 claim maps to this row |
+| Evidence kind | The `kind` of each cited evidence row, so a reader sees the reach without opening the verdict |
+| Status | `MATCH` / `PARTIAL` / `MISSING` / `BOUNDARY_MISMATCH` / `SCOPE_CREEP_VIOLATION` |
 | Notes | One line — why partial, what's missing, or where evidence is thin |
 
 ### Status definitions
@@ -90,6 +109,7 @@ For every requirement extracted in Phase 2, produce one row:
 - **`MATCH`** — requirement is implemented AND there is empirical evidence it works (test + verification report).
 - **`PARTIAL`** — implementation exists but evidence is incomplete (e.g. code present, no test; or test present, no run-time verification).
 - **`MISSING`** — requirement has no corresponding implementation OR no evidence at all.
+- **`BOUNDARY_MISMATCH`** — the requirement was implemented and evidence was cited, but the evidence does not *reach* the claim's boundary (a unit `test-run-log` offered for a `browser` claim), or its `artifact_head_sha` does not match `artifact.head_sha`, or the verdict omits the required Not-established review. This is a distinct failure from a miss: the work may be right and the proof still does not establish it. A `BOUNDARY_MISMATCH` row forces the verdict to `DIVERGES` — it can never render as `CONFORMS` or `PARTIAL`. Name the boundary, the kind cited, and the kind(s) required, citing the `claim-evidence-mapping` taxonomy.
 - **`SCOPE_CREEP_VIOLATION`** — used for `excluded` classification only. An Out-of-Scope item appears to have been shipped anyway. This is a different failure than a miss — it means the agent exceeded the spec.
 
 ### Scope creep detection
@@ -106,9 +126,9 @@ Untraceable changes are not automatic failures. They become findings the human r
 
 Produce exactly one verdict:
 
-- **`CONFORMS`** — every requirement is `MATCH`. No `SCOPE_CREEP_VIOLATION`. Untraceable changes, if any, are clearly refactors or test support.
-- **`PARTIAL`** — some requirements are `PARTIAL` but none are `MISSING` or `SCOPE_CREEP_VIOLATION`. Work is mostly there but evidence is thin.
-- **`DIVERGES`** — at least one requirement is `MISSING`, OR at least one `SCOPE_CREEP_VIOLATION` exists, OR there are substantive untraceable changes that materially alter behavior.
+- **`CONFORMS`** — every requirement is `MATCH`. No `SCOPE_CREEP_VIOLATION`, no `BOUNDARY_MISMATCH`. Untraceable changes, if any, are clearly refactors or test support.
+- **`PARTIAL`** — some requirements are `PARTIAL` but none are `MISSING`, `BOUNDARY_MISMATCH`, or `SCOPE_CREEP_VIOLATION`. Work is mostly there but evidence is thin.
+- **`DIVERGES`** — at least one requirement is `MISSING`, OR at least one `BOUNDARY_MISMATCH` exists, OR at least one `SCOPE_CREEP_VIOLATION` exists, OR there are substantive untraceable changes that materially alter behavior.
 
 A verdict of `PARTIAL` or `DIVERGES` blocks task completion. The caller must resolve the gaps (implement the miss, remove the creep, add the missing evidence) before re-running.
 
@@ -121,15 +141,24 @@ Structure the report so it can be pasted into a PR comment or JIRA ticket:
 
 **Spec source:** <plan file / JIRA key / Linear / GitHub issue / PRD>
 **Shipped scope:** <N commits, M files, K tests on branch <branch> vs <default-branch>>
+**Verdict artifact:** <.lisa/verification-status.json schema v2, artifact.head_sha <sha> — or "v2 verdict not present — boundary reach unverified">
 
 ### Coverage Matrix
 
-| ID | Class | Requirement | Evidence | Status | Notes |
-|----|-------|-------------|----------|--------|-------|
-| AC-1 | acceptance | [text] | [pointer] | MATCH | |
-| AC-2 | acceptance | [text] | — | MISSING | No corresponding code or test |
-| OOS-1 | excluded | [text] | src/foo.ts:42 | SCOPE_CREEP_VIOLATION | Added anyway |
-| ASSERT-1 | assertion | [text] | verification-report §2 | PARTIAL | Asserted in code, not run in verification |
+| ID | Class | Requirement | Evidence | Boundary | Evidence kind | Status | Notes |
+|----|-------|-------------|----------|----------|---------------|--------|-------|
+| AC-1 | acceptance | [text] | [pointer] (AC-1 / EV-1) | browser | screenshot | MATCH | |
+| AC-2 | acceptance | [text] | — | — | — | MISSING | No corresponding code or test |
+| AC-3 | acceptance | [text] | EV-4 | browser | test-run-log | BOUNDARY_MISMATCH | Unit log cannot establish a browser claim — needs screenshot or recording |
+| OOS-1 | excluded | [text] | src/foo.ts:42 | — | — | SCOPE_CREEP_VIOLATION | Added anyway |
+| ASSERT-1 | assertion | [text] | verification-report §2 | http-api | — | PARTIAL | Asserted in code, not run in verification |
+
+### Not Established
+
+Reproduce the verdict's `not_established` entries verbatim, grouped by claim, plus anything the matrix could not confirm. This section is **never omitted and never blank**: with nothing outstanding it renders `None outstanding — reviewed`. State whether `not_established_reviewed` was `true`.
+
+- AC-1 — not exercised on mobile viewports; Safari not tested
+- AC-4 — offline behavior consciously out of scope for this ticket
 
 ### Untraceable Changes
 - src/utils/helpers.ts — extracted shared regex constant (refactor, no behavior change)
@@ -140,6 +169,7 @@ Structure the report so it can be pasted into a PR comment or JIRA ticket:
 **Matches:** N/Total
 **Partial:** N
 **Missing:** N
+**Boundary mismatches:** N
 **Scope creep violations:** N
 **Untraceable changes flagged for review:** N
 
@@ -152,6 +182,8 @@ Structure the report so it can be pasted into a PR comment or JIRA ticket:
 
 - Never substitute "I read the code and it looks right" for empirical evidence. If verification-specialist hasn't run yet, request its report before producing a verdict.
 - Never mark a requirement `MATCH` based on the presence of code alone — evidence means test + runtime observation.
+- Never mark a requirement `MATCH` on evidence that does not **reach** its claim's boundary. Per the `claim-evidence-mapping` contract, a unit `test-run-log` establishes only `code-unit` behavior; cited for a `browser`, `http-api`, `deploy-health`, or `standards-compat` claim it is a `BOUNDARY_MISMATCH`, not a match.
+- Always report the Not-established section, even when empty. A report that lists only what passed is unreadable at a gate.
 - Always surface scope creep separately from misses. They are distinct failures.
 - Always surface untraceable changes — even benign refactors — so the human can confirm intent.
 - The Out of Scope section is load-bearing. If the spec has one, every item must appear in the matrix as `excluded`.

package/plugins/lisa/agents/spec-conformance-specialist.md

@@ -30,8 +30,9 @@ Follow the `spec-conformance` skill end-to-end:
 
 1. Resolve the spec source (plan file, JIRA key, Linear, GitHub issue, PRD).
 2. Extract every requirement into a structured list — acceptance criteria, Out of Scope, technical commitments, Validation Journey assertions, deliverables.
-3. Inspect shipped work (diff, tests, PR body, verification-specialist evidence).
-4. Build the coverage matrix — every requirement gets a row with a status.
+3. Inspect shipped work (diff, tests, PR body, verification-specialist evidence) **and load the machine-readable verdict** at `.lisa/verification-status.json`.
+3b. Cross-check every claim against its **boundary** — the `claim-evidence-mapping` contract's taxonomy — plus artifact identity and the Not-established review.
+4. Build the coverage matrix — every requirement gets a row with a boundary, an evidence kind, and a status.
 5. Detect scope creep and untraceable changes separately.
 6. Produce the verdict.
 
@@ -42,6 +43,8 @@ Return the structured report defined in the skill. Never summarize or drop rows.
 ## Rules
 
 - **Require empirical evidence.** A requirement is not `MATCH` because code exists. It is `MATCH` only when there is a test AND runtime observation (captured by verification-specialist).
+- **A cited-evidence-boundary mismatch is a conformance finding.** The `claim-evidence-mapping` rule binds every claim to a boundary and every boundary to the evidence kinds that reach it. When a v2 verdict cites evidence whose `kind` does not reach the claim's `boundary` — a unit `test-run-log` for a `browser` claim — or whose `artifact_head_sha` does not match `artifact.head_sha`, or when the verdict omits the Not-established review, the row is `BOUNDARY_MISMATCH` and the verdict is `DIVERGES`. Name the boundary, the kind cited, and the kind(s) required. This is not the same failure as a miss: the work may be correct and the proof still not establish it.
+- **Degrade, never block, on an absent or v1 verdict.** If no v2 verdict exists, say so in the report, cap affected rows at `PARTIAL`, and do not invent a mismatch you could not check.
 - **Scope creep is a distinct failure.** Do not fold `SCOPE_CREEP_VIOLATION` into "missing" or "untraceable." Scope creep means Out of Scope was violated — it blocks shipping.
 - **Untraceable changes get surfaced, not judged.** Refactors and test helpers often land here. Surface them so the human can confirm intent; do not automatically fail.
 - **If the spec itself is inadequate** (no acceptance criteria, no Out of Scope, no Validation Journey for runtime changes), the verdict is `DIVERGES` until the spec is tightened. Do not paper over an ambiguous spec with a generous match.

package/plugins/lisa/agents/verification-specialist.md

@@ -12,7 +12,7 @@ skills:
 
 You are a verification specialist. Your job is to **prove empirically** that work is done -- not by reading code, but by running the actual system and observing the results.
 
-Read `.claude/rules/verification.md` at the start of every investigation for the full verification framework, types, and lifecycle.
+Read `.claude/rules/verification.md` at the start of every investigation for the full verification framework, types, and lifecycle. Read `.claude/rules/claim-evidence-mapping.md` alongside it: it binds every claim to the **boundary** it asserts and every boundary to the evidence **kinds** that reach it. The verdict you write is what `spec-conformance-specialist` cross-checks — record each claim's `boundary`, its `required_evidence_kinds`, its `evidence_refs`, and its `not_established` list so a boundary mismatch is catchable rather than invisible.
 
 ## Core Philosophy
 

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

@@ -81,6 +81,20 @@
 #     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)
+#   - every evidence entry that records BOTH a "sha256" and a "locator"
+#     resolving to a file on disk still hashes to that digest
+#     ("evidence_digest_mismatch"). A locator that is not on disk at stop time
+#     is NOT judged here: the Stop hook sees only the working tree, and evidence
+#     may legitimately live outside it. The absent-artifact arm of that check
+#     belongs to the read-side review surfaces, which see the committed
+#     evidence directory.
+#   - the claim/evidence structure is EVALUABLE at all: a v2 verdict whose
+#     "claims"/"evidence"/"artifact" are not the shapes the schema defines
+#     (claims as a string, evidence as a scalar) is reported as
+#     could-not-evaluate. Could-not-evaluate is NOT the same as no-violations:
+#     a verdict the gate cannot read may never be treated as a clean one, or a
+#     structurally-wrong verdict would sail past the gate the moment
+#     enforcement is ratcheted on.
 #
 # ADVISORY-FIRST: those v2 checks report to stderr but do NOT block unless
 # "verification.gate.enforceBoundaries" is true in .lisa.config.json (default
@@ -90,11 +104,15 @@
 # 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 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.
+# Fail-open: a 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.
+#
+# That fail-open posture bounds the BLAST RADIUS of a gate failure; it is not a
+# licence to read an unreadable verdict as a clean one. So a v2 verdict whose
+# claim structure cannot be evaluated is reported like any other violation —
+# advisory while the ratchet is off, blocking (still MAX_BLOCKS-bounded, so it
+# can never hard-wedge a session) once it is on.
 
 set -uo pipefail
 
@@ -225,9 +243,39 @@ boundary_enforcement_enabled() {
   [ "$value" = "true" ]
 }
 
+# Prints the sha256 of a file using whichever tool this machine has. Prints
+# nothing when neither exists — an unrecomputable digest is not a violation.
+sha256_of() {
+  if command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 "$1" 2>/dev/null | awk '{print $1}'
+  elif command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$1" 2>/dev/null | awk '{print $1}'
+  fi
+}
+
+# Emits one line per evidence entry whose bytes no longer hash to the digest the
+# verdict recorded. Only entries recording BOTH a sha256 and a locator that
+# resolves to a file on disk are judged; see the header for why an absent
+# locator is out of this hook's scope.
+v2_digest_violations() {
+  jq -r '
+    (.evidence // [])[]
+    | select(((.sha256 // "") | length) > 0)
+    | select(((.locator // "") | length) > 0)
+    | "\(.evidence_id // "?")\t\(.locator)\t\(.sha256)"
+  ' "$VERDICT_FILE" 2>/dev/null | while IFS=$'\t' read -r eid locator recorded; do
+    evidence_path="${PROJECT_DIR}/${locator}"
+    [ -f "$evidence_path" ] || continue
+    actual=$(sha256_of "$evidence_path")
+    [ -n "$actual" ] || continue
+    [ "$actual" = "$recorded" ] && continue
+    echo "evidence ${eid} (${locator}) no longer matches its recorded digest: recorded ${recorded}, bytes now hash to ${actual}"
+  done
+}
+
 # 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).
+# the verdict satisfies the contract. A jq evaluation failure is NOT empty
+# output — see v2_evaluate_contract, which turns it into its own violation.
 v2_contract_violations() {
   jq -r '
     . as $v
@@ -263,7 +311,32 @@ v2_contract_violations() {
         )
       ]
     | .[]
-  ' "$VERDICT_FILE" 2>/dev/null || true
+  ' "$VERDICT_FILE" 2>/dev/null
+}
+
+# Set by v2_evaluate_contract: every violation line, or empty when the verdict
+# satisfies the contract. A global rather than a return value because a command
+# substitution would swallow the could-not-evaluate signal along with it.
+V2_VIOLATIONS=""
+
+# Evaluates the full v2 contract into V2_VIOLATIONS.
+#
+# The load-bearing distinction: jq returns NOTHING on an evaluation error, which
+# is byte-identical to "this verdict is clean". A parseable v2 verdict whose
+# claims/evidence are the wrong SHAPE (claims as a string, evidence as a scalar)
+# therefore used to read as violation-free — harmless while advisory, a genuine
+# bypass of the gate the moment enforcement is ratcheted on. So a non-zero jq
+# exit becomes its own, named violation.
+v2_evaluate_contract() {
+  local structural digests
+  structural=$(v2_contract_violations)
+  if [ "$?" -ne 0 ]; then
+    V2_VIOLATIONS="the v2 claim/evidence structure could not be evaluated - \"claims\" and \"evidence\" must be arrays of objects and \"artifact\" an object. A verdict the gate cannot read is not a verdict with no violations"
+    return 0
+  fi
+
+  digests=$(v2_digest_violations)
+  V2_VIOLATIONS=$(printf '%s\n%s' "$structural" "$digests" | sed '/^[[:space:]]*$/d')
 }
 
 # v2 = the v1 decision PLUS the claim->evidence contract, the latter advisory
@@ -277,7 +350,8 @@ verdict_is_terminal_v2() {
   status=$(jq -r '.status // empty' "$VERDICT_FILE" 2>/dev/null || true)
   [ "$status" = "pass" ] || return 0
 
-  violations=$(v2_contract_violations)
+  v2_evaluate_contract
+  violations="$V2_VIOLATIONS"
   [ -n "$violations" ] || return 0
 
   if boundary_enforcement_enabled; then

package/plugins/lisa/rules/eager/readiness-rubric.md

@@ -0,0 +1,58 @@
+# Repository Readiness Rubric (load-bearing)
+
+**"Lisa is installed correctly" and "an agent fleet may run here unattended" are two different
+questions.** Doctor's shipped grouped checks answer the first — *installation readiness*. This rubric
+answers the second — *repository readiness* — and it is the only place that question is written down.
+A green test suite is not an answer to it.
+
+## Eight ownership dimensions
+
+Repository readiness is assessed across exactly eight dimensions, never fewer, and a dimension with
+no applicable evidence renders `SKIP` **with a reason** rather than a blank:
+
+1. **context/routing** — can an agent recover the real job from what is written down?
+2. **capabilities/tools** — is every tool the work needs *provably* reachable, not merely installed?
+3. **domain ownership** — are the business rules, glossary, and danger zones owned and written down?
+4. **execution/proof** — can the claimed user-visible outcome be proved by running the system?
+5. **feedback/guardrails** — does a failing loop produce a named outcome and a runbook?
+6. **dependencies/supply chain** — is there a confidence model for what the repo depends on?
+7. **delivery/authority** — does the thing that ships equal the thing that was validated, and does
+   the credential that ships it carry only the authority it needs?
+8. **proportionality** — is the machinery proportional to the job, or is there scaffolding to
+   subtract?
+
+## Seven ship blockers (closed set, v1)
+
+A **ship blocker** is a condition that, standing alone, means the answer to "may an unattended fleet
+run here?" is no. The set is closed in v1 — seven, no more — and extended only by editing this rule:
+
+- **B1** a realistic path causes **silent data loss**
+- **B2** a **release path bypasses the validated artifact**
+- **B3** **credentials carry material unintended authority**
+- **B4** a **consequential operation has no gate and no recovery**
+- **B5** an **owned compatibility or security surface has no confidence model**
+- **B6** **documentation overstates enforced guarantees**
+- **B7** there is **no way to prove the claimed user-visible outcome**
+
+## Verdict and narrowed claim
+
+The verdict reuses the shipped `READY` / `READY_WITH_WARNINGS` / `NOT_READY` ladder — cite doctor's
+ladder, never fork a parallel enum. **A standing blocker is `NOT_READY`**, and the report must also
+state the **narrowed claim**: what the repository *is* ready for, in operator language ("ready for
+supervised single-ticket work; not ready for unattended fleet operation, because …").
+
+## Ordering
+
+**Report section order stays stable and never silently omits a section; findings are ordered by
+consequence** — highest-consequence first — within and across sections. The two contracts do not
+collide: sections are fixed, findings are ranked.
+
+## Warn-only
+
+This rubric **gates a claim, not a process**. No Lisa surface hard-blocks on the verdict: a standing
+blocker narrows what may be claimed and files tracker work; it never stops `lisa apply`, intake
+dispatch, or cron registration. Where a surface this rule names is not installed in a given branch,
+name what you can and continue — degrade, never block. Written to be read by someone who does not
+code (`factory-model` rule 5).
+
+Full rubric (eight-dimension table, seven ship blockers, consequence ordering, worked example): [reference/readiness-rubric.md](../reference/readiness-rubric.md).

package/plugins/lisa/rules/reference/readiness-rubric.md

@@ -0,0 +1,179 @@
+# Repository Readiness Rubric
+
+Lisa can already tell you whether it is *installed* correctly. It cannot tell you whether a
+repository is somewhere an agent fleet can safely operate **unattended**. Those are two different
+questions, and conflating them is how a brownfield onboarding ends in "we built a wiki, looks good"
+instead of a verdict someone can act on.
+
+This document writes the second question down once: **eight ownership dimensions** with concrete
+warning signs, and **seven ship blockers** that, if any one of them stands, mean the answer is no.
+It is documentation. Nothing here executes — the later tickets of PRD #1739 instantiate this rubric
+rather than redefine it.
+
+## Two readinesses, one report
+
+| | Installation readiness | Repository readiness |
+|---|---|---|
+| Question | is Lisa installed and wired correctly here? | may an agent fleet operate here unattended? |
+| Owner | `lisa doctor`'s shipped grouped checks (project detection, config, distribution, tracker preflight, automation prerequisites, …) | this rubric's eight dimensions |
+| Answer shape | the shipped verdict ladder | the same shipped verdict ladder, plus a narrowed claim |
+
+They are **orthogonal** — a repository can be perfectly installed and completely unready, or ready in
+substance while Lisa's own wiring is incomplete. Both render in the same report, under separately
+titled sections, so a reader is never left guessing which question a verdict answered. The doctor
+mode that renders the repository-readiness group ships with **RRR-3 (#1855)**; do not assume that
+surface is present in this branch.
+
+## The eight ownership dimensions
+
+Exactly eight, always reported, never silently omitted. Each row names what the dimension asks,
+concrete warning signs an assessor can look for, and the **existing** Lisa rule or wiki page that
+supplies its evidence. Cite those slugs; do not restate them, and do not invent a parallel vocabulary
+for a concept another rule already owns.
+
+| # | Dimension | The question | Warning signs | Evidence source (existing) |
+|---|---|---|---|---|
+| 1 | context/routing | Can an agent recover the real job from what is written down? | no canonical entry document; routing decided by tribal knowledge; ambiguous config resolution; a README that describes a system that no longer exists | `integration-access-layer`, `wiki-knowledge-source`, `config-resolution` |
+| 2 | capabilities/tools | Is every tool the work needs *provably* reachable, not merely installed? | presence-on-PATH treated as access; no read-only probe before the work starts; agents inventing workarounds instead of breaking out | `tool-access-gate` |
+| 3 | domain ownership | Are the business rules, glossary, and danger zones owned and written down? | undocumented money paths; migrations with no owner; irreversible jobs nobody has described | the wiki pages agent-ready's domain phase already produces |
+| 4 | execution/proof | Can the claimed user-visible outcome be proved by running the system? | claims backed only by unit tests; no representative end-to-end journey; "verified" that names no boundary | `verification`, `empirical-inquiry`, `claim-evidence-mapping` |
+| 5 | feedback/guardrails | Does a failing loop produce a named outcome and a runbook? | silent failures; no run-outcome vocabulary; no observability on the loops that run unattended | `automation-runbook-contract`, `observability-audit` |
+| 6 | dependencies/supply chain | Is there a confidence model for what the repo depends on? | unpinned or unowned dependencies; no trust class; no decision record for why a risky dependency stays | `security-audit-handling` |
+| 7 | delivery/authority | Does the thing that ships equal the thing that was validated, and does the credential that ships it carry only the authority it needs? | a release path that bypasses the validated artifact; broad-scope tokens; deploy credentials shared across environments | `claim-archaeology`, `security-audit-handling` |
+| 8 | proportionality | Is the machinery proportional to the job, or is there scaffolding to subtract? | redundant checks that assert the same thing twice; abandoned harnesses still running in CI | `repo-scope-split`, and the scaffolding-subtraction candidates the journey work of **#1742** already surfaces |
+
+**`SKIP` carries a reason and is never blank.** A dimension with no applicable evidence renders
+`SKIP with a reason` — "no deployment target configured, so delivery/authority was not assessed" —
+never an empty cell and never a silent omission. An unassessed dimension is a known unknown, and the
+report says so.
+
+## The seven ship blockers
+
+A **ship blocker** is a condition that, standing alone, makes the claim "an unattended fleet may run
+here" false. Each has a one-line test an assessor can apply and the dimension that owns it.
+
+| # | Blocker | The test an assessor applies | Owning dimension |
+|---|---|---|---|
+| B1 | A realistic path causes **silent data loss** | can you name a plausible sequence that destroys or corrupts data with no error surfaced and no recovery path? | 3 |
+| B2 | A **release path bypasses the validated artifact** | can something reach production that is not the artifact CI actually validated? | 7 |
+| B3 | **Credentials carry material unintended authority** | does any credential used by automation grant authority materially beyond the job it does? | 7 |
+| B4 | A **consequential operation has no gate and no recovery** | is there an irreversible or expensive operation reachable without a gate, with no way back? | 3, 5 |
+| B5 | An **owned compatibility or security surface has no confidence model** | for a surface this repo owns, is there any basis beyond hope for believing it still works? | 6 |
+| B6 | **Documentation overstates enforced guarantees** | does the written word claim something is enforced that nothing actually enforces? | 1 |
+| B7 | There is **no way to prove the claimed user-visible outcome** | can the headline user-visible claim be demonstrated by running the system, at the boundary it claims? | 4 |
+
+### The set is a closed set in v1
+
+Seven, and only seven, in v1. The set is **not configurable** — there is no config key, no
+host-defined blockers, no severity dial. Extending it is a deliberate **rule edit** here plus a
+version bump, not a configuration surface to design, migrate, and support. Host-specific concerns
+surface as *findings within a dimension*, which is enough to make them visible without fragmenting
+the vocabulary.
+
+### "Ship blocker" is net-new vocabulary
+
+It is deliberately distinct from three terms other rules already own, and it never replaces them:
+
+- `convergent-review`'s **blocking finding** — a review-level judgment about one change.
+- `tool-access-gate`'s **break-out** — the escalation when a required tool is not provably reachable.
+- `leaf-only-lifecycle`'s **safe-block** — a lifecycle-state repair on a work item.
+
+A ship blocker is none of these: it is a property of the *repository*, asserted about *unattended
+operation*, and it gates a claim rather than a change, a tool call, or a ticket.
+
+## Verdict: the shipped ladder, plus a narrowed claim
+
+The rubric reuses the shipped `READY` / `READY_WITH_WARNINGS` / `NOT_READY` verdict ladder that
+`lisa doctor` already emits. There is **no new verdict** value and no new severity level — inventing
+a parallel enum would make two reports disagree about what "ready" means.
+
+- **`READY`** — eight dimensions assessed, no blocker stands, no warnings material to unattended
+  operation.
+- **`READY_WITH_WARNINGS`** — no blocker stands, but findings exist that a human should see.
+- **`NOT_READY`** — **at least one ship blocker stands.**
+
+**The narrowed claim is the net-new field.** When the verdict is `NOT_READY`, the report must also
+state, in operator language, **what the repository IS ready for** — never just what it is not. A
+verdict that only says no is unactionable at the gate; a narrowed claim tells the operator exactly
+which mode of operation remains available and what would widen it.
+
+## Consequence ordering
+
+Two ordering contracts meet here, and they do not collide:
+
+- **Section order stays stable.** The report renders its sections in a fixed order and **never
+  silently omits** one — the discipline `lisa doctor`'s grouped output already guarantees.
+- **Findings are ordered by consequence.** Within and across sections, the finding with the largest
+  consequence if left standing comes first. Alphabetical, chronological, and discovery order are all
+  wrong: the reader at the gate has limited attention, and it belongs on the worst thing first.
+
+### The five fields a readiness finding carries
+
+On top of the severity / blocking / failure-scenario / evidence / smallest-fix fields
+`convergent-review` already requires, a readiness finding names:
+
+| Field | What it states |
+|---|---|
+| `invariant_violated` | the invariant actually at risk, stated as a property of the system |
+| `evidence` | what was observed that establishes the finding, at a boundary that reaches the claim (`claim-evidence-mapping`) |
+| `why_proof_missed` | why the existing proof machinery did not catch this |
+| `root_correction` | the correction at the **owning boundary**, not a patch at the symptom |
+| `machinery_to_remove` | redundant machinery the correction makes unnecessary, if any |
+
+Two of these — `invariant_violated` and `machinery_to_remove` — are folded into the shared
+`convergent-review` finding shape by **RRR-2 (#1854)**; that extension ships with that ticket, so do
+not assume the shared shape carries them in this branch.
+
+### Worked example
+
+```text
+Repository: acme/checkout-service
+
+  Verdict          NOT_READY
+  Standing blocker B2 — a release path bypasses the validated artifact
+  Owning dimension 7 (delivery/authority)
+
+  invariant_violated   What ships to production is the artifact CI validated.
+  evidence             The deploy job rebuilds from source at deploy time rather than
+                       promoting the CI-built image; the deployed digest never matches
+                       the one the test job signed off on.
+  why_proof_missed     Every check is green — they all ran against a different artifact
+                       than the one that shipped. Nothing compared the two.
+  root_correction      Promote the validated image by digest at the delivery boundary.
+  machinery_to_remove  The duplicate deploy-time build step.
+
+  Narrowed claim   This repository IS ready for supervised, single-ticket agent work with a
+                   human approving each release. It is NOT ready for unattended fleet
+                   operation, because a release can ship code no check ever ran against.
+```
+
+## Where the evidence comes from
+
+The rubric consumes evidence that already exists; it commissions no second harness.
+
+- **execution/proof** consumes the existing qualification evidence recorded by the worker-epoch
+  requalification path and, when that evidence is absent or stale, triggers a journey run through the
+  shipped `lisa-use-the-product` skill — the machinery **#1742** already ships. There is no second
+  journey harness, and the evidence is recorded in the shape `claim-evidence-mapping` defines. That
+  wiring ships with **RRR-6 (#1858)**.
+- **domain ownership** sources its findings from the danger-zone wiki pages agent-ready's domain
+  phase already produces; the readiness assessment that reads them, and files standing blockers as
+  tracker work rather than in-session questions, ships with **RRR-4 (#1856)**.
+- The persisted report at `.lisa/readiness.json` (schema-versioned, read through a single resolver)
+  and the doctor render group ship with **RRR-3 (#1855)**; the blocker gate that emits the narrowed
+  claim ships with **RRR-5 (#1857)**; the `setup-automations` warning, six-agent parity fan-out, and
+  vocabulary documentation ship with **RRR-7 (#1859)**. Each of those surfaces may not yet be present
+  in a given branch — name what you can and continue.
+
+## Warn-only, always
+
+This rubric **gates a claim, not a process**. It is **warn-only** everywhere: no Lisa surface
+hard-blocks on the readiness verdict. `lisa apply`, intake dispatch, and cron registration are
+unaffected; the automation setup flow warns with the standing blocker count and the narrowed claim
+and still completes, consistent with the shipped never-block-always-degrade posture. Where a surface
+named here is not installed, **degrade, never block**: state what was assessed, state what was not,
+and continue.
+
+Read the eight dimension titles and the seven blockers to someone who has never seen Lisa. They
+should be able to say, unprompted, why "the tests pass" is not the same as "an agent fleet can run
+here unattended" — that is the bar this document is written to (`factory-model` rule 5).

package/plugins/lisa/rules/reference/verification.md

@@ -177,6 +177,8 @@ The list may be empty; the flag may not be missing. An absent `not_established_r
 
 The boundary each artifact type reaches — and therefore which claim a captured artifact can discharge — is the `claim-evidence-mapping` rule's taxonomy; the type table above is its evidence-kind source.
 
+The verdict is read twice. The Claude-only `enforce-verification-gate.sh` Stop hook reads it to decide whether the flow may stop; `lisa-spec-conformance` (run by `spec-conformance-specialist` in the verification phase) reads it to decide whether each shipped requirement's proof actually reaches its boundary — a cited-evidence-boundary mismatch is a `BOUNDARY_MISMATCH` conformance finding there, caught alongside empirical verification rather than after it. On harnesses without a Stop hook, `lisa-implement`'s prose gate carries the same v2 expectations by convention. The whole system, operator-readable end to end, is written up as the Lisa wiki's **Bounded-Claims Evidence System** concept page (`wiki/concepts/bounded-claims-evidence-system.md` upstream).
+
 ### Cross-work-item evidence references are non-claiming
 
 When prose needs to point at evidence declared by another work item, use the dedicated reference form: