@codyswann/lisa 2.353.0 → 3.1.0

package/plugins/lisa/rules/reference/ready-role-filing.md

@@ -0,0 +1,66 @@
+# Ready-Role Filing
+
+A work item that is filed but never given the ready role is an **incomplete handoff**. No other agent will ever pick it up: build-intake scans the ready lane and nothing else. The originating failure is small and entirely typical — an agent closed a ticket it could not reproduce, filed the real defect it found beside it, and left the new ticket sitting. The defect was correct, the write succeeded, and the work still died.
+
+This rule makes the ready role an **explicit claim** at every filing site, and makes omission mean the same thing on every tracker.
+
+## The one normalization
+
+**An omitted `build_ready` means NOT build-ready — on JIRA, on GitHub, and on Linear alike.**
+
+Before this rule the three writers disagreed, and the disagreement was invisible at the call site:
+
+| Tracker | Omitted `build_ready` (before) | Omitted `build_ready` (now) |
+|---|---|---|
+| JIRA | project's default created status — **not ready** | unchanged — **not ready** |
+| GitHub | `status:ready` applied — **ready** | **not ready** |
+| Linear | created in the configured `ready` state — **ready** | **not ready** |
+
+So the same vendor-neutral `lisa-tracker-write` call produced a different lifecycle outcome depending on which tracker a project had configured. That is a leak in the abstraction the shim exists to provide: switching trackers must not change behavior.
+
+**This is a breaking change for GitHub and Linear callers.** Any caller that omitted `build_ready` and relied on implicit ready must now pass it explicitly. That is the point rather than a cost of it: the only paths affected are ones that were silently depending on a provider-specific default, which is exactly the class of bug this rule exists to eliminate. `lisa-github-validate-issue` F4's compensating normalization (omitted → `true`) is removed with it — a validator that re-introduces the old default would simply move the leak.
+
+The safe direction is the implicit one. A ticket that reaches a build queue by accident is worse than one that waits, because the queue is what agents act on autonomously.
+
+## Every filing declares one of two things
+
+A writer accepts a filing only when it carries **one** of:
+
+- **`build_ready: true`** — the item is complete enough to build and enters the ready lane for auto-pickup. This is the correct answer for a complete defect found during other work.
+- **`human_gate: "<why a human must judge this first>"`** — the item is deliberately held outside the queue because a human product call is pending. The writer stamps a visible marker on the item so the hold is auditable rather than indistinguishable from an accident:
+
+  ```text
+  Held for a human product call: <reason>.
+  <!-- [lisa-human-gate] reason=<short-slug> -->
+  ```
+
+Filed, not ready, and no `human_gate` is the **incomplete handoff** case: the writer rejects it and names the two ways to resolve it. `build_ready: false` without a `human_gate` reason is the same failure spelled differently — it is not a gate, it is an omission with a value attached.
+
+`build_ready` remains strictly subordinate to `leaf-only-lifecycle`: a container is never build-ready regardless of what a caller passes, and a container needs no `human_gate` because its state rolls up from its children rather than being claimed.
+
+## Complete defects found during other work are filed build-ready
+
+Any defect discovered while doing something else, which is complete enough to build, is filed through `lisa-track` / `lisa-tracker-write` with **explicit `build_ready: true`**. It must be claimable by build-intake on the next cycle with no human flipping status. "Complete enough to build" is the `work-item-definition-of-ready` bar — reproduction, observed-versus-expected, and Gherkin acceptance criteria — not a placeholder to be fleshed out later.
+
+The same explicitness applies in the other direction. A filing that is genuinely a human product call declares `human_gate`; it does not simply omit the flag and hope the tracker default is the merciful one.
+
+## The named exception: `lisa-exploratory-qa`
+
+`lisa-exploratory-qa` files its findings **not** build-ready by default, and that is **correct** — it is the named human-gate exception under this rule, not drift to be repaired.
+
+Exploratory QA is a first-time-user experience pass. Its findings are *candidate* defects and usability observations whose product significance a human should judge; auto-readying them would push judgment work into the build queue, which is precisely the failure the gate model exists to prevent. Its `ready=false` is therefore paired with an explicit `human_gate` reason and stamped with `[lisa-human-gate]` — an explicit human-gate marker, never a bare omission.
+
+The sibling `e2e-coverage-gaps` skills are the contrast: a missing automated test is not a product question, so they file `build_ready: true` by default.
+
+Other legitimate human-gate filings follow the same shape — `lisa-learnings-audit` promotion/demotion tickets, `lisa-improve-harness` intervention proposals, automation-retirement proposals, and provisioning tickets for access a human must grant. Each declares its `human_gate` reason rather than relying on a default.
+
+## Recovery
+
+`lisa-repair-intake` sweeps for the failure this rule prevents: recently filed items that are open, not in the configured ready role, and carrying **no** `[lisa-human-gate]` marker. Each is an incomplete handoff — surfaced with its filing context so an operator can promote it or gate it deliberately. The sweep reports rather than guesses: it never silently promotes an item into the queue, because a filing whose readiness nobody declared is exactly the input the gate model says a human should see.
+
+## Related
+
+- **`leaf-only-lifecycle`** — the prohibition `build_ready` is always subordinate to. Containers are never build-ready.
+- **`work-item-definition-of-ready`** — what "complete enough to build" means.
+- **`tracked-work`** — the filing entry point (`lisa-track`) this rule governs the readiness of.
+- **`factory-model`** — why the ready flip is a gate standing outside the factory rather than a field inside it.

package/plugins/lisa/skills/lisa-agent-ready/SKILL.md

@@ -217,9 +217,11 @@ vocabulary; it consumes it.
 
 3. **File each standing blocker as a tracker work item — never an in-session question.** For every
    standing ship blocker, create **one** Lisa work item through the vendor-neutral `lisa-tracker-write`
-   skill (never a vendor write skill directly), carrying the five finding fields in the body. Label it
-   **build-ready** when the correction is mechanical; mark it **human-needed** when it is a genuine
-   human decision. This is the skill's **only tracker write**, and it creates Lisa's *own* work item —
+   skill (never a vendor write skill directly), carrying the five finding fields in the body. Per the `ready-role-filing` rule each
+   create declares its readiness explicitly: pass **`build_ready: true`** when the correction is
+   mechanical (an omitted flag is NOT build-ready on any tracker, so the mechanical branch would
+   otherwise file work nothing ever claims), and pass **`human_gate: "<the decision only a human can
+   make>"`** plus the `human-needed` marker when it is a genuine human decision. This is the skill's **only tracker write**, and it creates Lisa's *own* work item —
    it **never edits, comments on, transitions, or otherwise mutates any ingested source** (see the
    connected-source safety boundary above). The shipped never-ask posture is preserved: a blocker
    becomes a filed ticket, **never** a prompt, and the session **never pauses to ask a human anything**,

package/plugins/lisa/skills/lisa-atlassian-access/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lisa-atlassian-access
-description: "Vendor-neutral access layer for Atlassian (JIRA + Confluence). Every jira-* and confluence-* skill MUST delegate through this skill rather than calling Atlassian directly. Resolves a substrate per operation, binding JIRA writes to the configured cloudId via Atlassian REST whenever token auth is available and using acli only for reads or as a guarded fallback. For non-write acli operations, acli is used when installed and switchable to a profile matching the configured site; mismatched active profiles are skipped only after switch plus re-verification fails."
+description: "Vendor-neutral access layer for Atlassian (JIRA + Confluence). Every jira-* and confluence-* skill MUST delegate through this skill rather than calling Atlassian directly. Per the credential-substrate-precedence contract, resolves a substrate per operation with the ATLASSIAN_API_TOKEN curl path first for reads and writes alike whenever the token is present and identity-matched — binding JIRA writes to the configured cloudId — then acli, then the Atlassian MCP as fallbacks. acli is used when installed and switchable to a profile matching the configured site; mismatched active profiles are skipped only after switch plus re-verification fails, and acli writes are a guarded fallback with post-write tenant assertions."
 allowed-tools: ["Bash", "Read", "Skill"]
 ---
 
@@ -35,46 +35,17 @@ EMAIL=$(jq -r '.atlassian.email // empty' .lisa.config.local.json 2>/dev/null)
 [ -z "$CLOUDID" ] && { echo "Error: atlassian.cloudId not set. Run /lisa:setup:atlassian." >&2; exit 1; }
 ```
 
-Probe each tier in order; the first that's ready AND identity-matches is the substrate for this operation. Identity-match is verified before any operation; substrates authenticated as a different Atlassian account are switched to the configured profile when one exists, then skipped only if the switch fails or re-verification still mismatches.
+Probe each tier in order; the first that's ready AND identity-matches is the substrate for this operation. The ordering is the shared `credential-substrate-precedence` contract — the configured-provider token substrate leads for **reads and writes alike**, with acli and the MCP as identity-matched fallbacks — not an Atlassian-local choice. Identity-match is verified before any operation; substrates authenticated as a different Atlassian account are switched to the configured profile when one exists, then skipped only if the switch fails or re-verification still mismatches.
 
 ```bash
 substrate=""
 
-# Tier 1: acli for reads and non-write operations only.
-#
-# Do not choose acli for JIRA writes when curl/token auth is available. acli stores
-# one machine-global active account and workitem writes cannot pin a cloudId per
-# invocation, so switch-then-write is a TOCTOU risk in multi-account or concurrent
-# sessions. Write operations prefer the cloudId-scoped REST URL below.
-if [ "$OP_KIND" != "jira-write" ] && command -v acli >/dev/null 2>&1 && acli auth status >/dev/null 2>&1; then
-  current_site=$(acli auth status 2>/dev/null | awk '/^  Site:/{print $2}')
-  if [ "$current_site" != "$SITE" ]; then
-    # acli installed but pointing at a different site. Try switching profiles.
-    acli auth switch --site "$SITE" ${EMAIL:+--email "$EMAIL"} >/dev/null 2>&1 || true
-    current_site=$(acli auth status 2>/dev/null | awk '/^  Site:/{print $2}')
-  fi
-  if [ "$current_site" = "$SITE" ]; then
-    substrate="acli"
-  fi
-fi
-
-# Tier 2: Atlassian MCP (if acli not ready OR the operation isn't acli-covered)
-# $OP_REQUIRES is a conceptual variable set by the dispatch table to "non-acli" for
-# operations that have no acli adapter (e.g. read-page-descendants). It is not a real
-# shell variable initialized here — the condition is illustrative pseudo-code.
-if [ -z "$substrate" ] || [ "$OP_REQUIRES" = "non-acli" ]; then
-  # Probe via mcp__plugin_atlassian_atlassian__getAccessibleAtlassianResources.
-  # (Pseudo-code; actual call is the MCP tool invocation, not a bash command.)
-  # If the MCP returns a list and $CLOUDID is in it, MCP is identity-matched.
-  # If the MCP is unauthenticated or $CLOUDID is NOT in the list, MCP is skipped.
-  if mcp_atlassian_authenticated_and_matches_cloudid "$CLOUDID"; then
-    : ${substrate:=mcp}
-    # Mark MCP as available even if acli already won tier 1 — used for ops acli can't do.
-    mcp_available=true
-  fi
-fi
-
-# Tier 3: curl + API token (headless / multi-account / scoped-token path)
+# Tier 1: curl + API token — the configured-provider substrate, resolved through
+# lisa-secrets-access. Leads for every operation because it is per-invocation-bound:
+# the cloudId-scoped gateway URL and the token's own account carry the tenant inside
+# the request, so no ambient machine-global state can redirect it. acli (one global
+# active account) and the MCP (browser OAuth session) are ambient-bound and therefore
+# TOCTOU-exposed — see credential-substrate-precedence, "tenant safety".
 read_atlassian_token() {
   local email="$1"
   [ -n "$ATLASSIAN_API_TOKEN" ] && { echo "$ATLASSIAN_API_TOKEN"; return; }
@@ -136,13 +107,50 @@ public static class LisaCred {
   esac
 }
 TOKEN=$(read_atlassian_token "$EMAIL")
-[ -n "$TOKEN" ] && curl_available=true && {
-  if [ "$OP_KIND" = "jira-write" ]; then
+if [ -n "$TOKEN" ]; then
+  # Identity-match before use: /rest/api/3/myself must report the configured account
+  # (Step 2). A present-but-wrong token fails the gate loudly instead of quietly
+  # deferring to an acli profile or MCP session authenticated somewhere else — that
+  # silent success is the bug class the precedence contract exists to surface.
+  if atlassian_token_matches_config "$TOKEN" "$EMAIL" "$CLOUDID"; then
+    curl_available=true
     substrate="curl"
   else
-    : ${substrate:=curl}
+    echo "Warning: ATLASSIAN_API_TOKEN does not match the configured account/site. Skipping curl tier." >&2
   fi
-}
+fi
+
+# Tier 2: acli — identity-matched fallback. Used when no token is available, or for
+# operations with no curl adapter. Never the primary path for JIRA writes when token
+# auth is available: acli stores one machine-global active account and workitem writes
+# cannot pin a cloudId per invocation, so switch-then-write is a TOCTOU risk in
+# multi-account or concurrent sessions. When a write does land here it is the *guarded*
+# fallback documented in the dispatch table (assert, write, re-read, assert, roll back).
+if command -v acli >/dev/null 2>&1 && acli auth status >/dev/null 2>&1; then
+  current_site=$(acli auth status 2>/dev/null | awk '/^  Site:/{print $2}')
+  if [ "$current_site" != "$SITE" ]; then
+    # acli installed but pointing at a different site. Try switching profiles.
+    acli auth switch --site "$SITE" ${EMAIL:+--email "$EMAIL"} >/dev/null 2>&1 || true
+    current_site=$(acli auth status 2>/dev/null | awk '/^  Site:/{print $2}')
+  fi
+  if [ "$current_site" = "$SITE" ]; then
+    acli_available=true
+    # Mark acli available even if curl already won tier 1 — used for ops curl can't do.
+    : ${substrate:=acli}
+  fi
+fi
+
+# Tier 3: Atlassian MCP — first-class interactive fallback, for when neither tier above
+# is available or covers the operation (e.g. an op with no curl and no acli adapter).
+# Probe via mcp__plugin_atlassian_atlassian__getAccessibleAtlassianResources.
+# (Pseudo-code; actual call is the MCP tool invocation, not a bash command.)
+# If the MCP returns a list and $CLOUDID is in it, MCP is identity-matched.
+# If the MCP is unauthenticated or $CLOUDID is NOT in the list, MCP is skipped.
+if mcp_atlassian_authenticated_and_matches_cloudid "$CLOUDID"; then
+  : ${substrate:=mcp}
+  # Mark MCP as available even if an earlier tier won — used for ops they can't do.
+  mcp_available=true
+fi
 
 # Fail loudly with actionable remediation if nothing works.
 if [ -z "$substrate" ]; then
@@ -154,15 +162,25 @@ if [ -z "$substrate" ]; then
   cat >&2 <<EOF
 Error: no Atlassian access substrate available for site $SITE.
 
-Attempted:
+Attempted (in credential-substrate-precedence order):
+  curl   — no ATLASSIAN_API_TOKEN found for $EMAIL (env, slug-suffixed env, or keychain) OR the token does not match the configured account/site
   acli   — $(command -v acli >/dev/null && echo "installed but identity mismatch or unauthenticated" || echo "not installed")
   MCP    — $([ "$plugin_enabled_global" = "true" ] || [ "$plugin_enabled_project" = "true" ] || [ "$plugin_enabled_local" = "true" ] && echo "plugin enabled but not authenticated or cloudId $CLOUDID not in accessible resources" || echo "plugin not enabled in any settings.json scope")
-  curl   — no ATLASSIAN_API_TOKEN found for $EMAIL (env, slug-suffixed env, or keychain)
 
-Remediation paths (pick one):
+Remediation paths (the first is the contract's primary path):
+
+1. Provision an API token — works headless, in CI, in subagents, and in
+   multi-account setups, and is the substrate this project resolves first.
+
+     Run /lisa:setup:atlassian — guided flow with clipboard-piped keychain store.
+
+2. Install acli and authenticate (identity-matched fallback for multi-account developers).
 
-1. Install the Atlassian MCP plugin (local scope — per-developer, gitignored).
-   This is the simplest path for single-account developers.
+     brew tap atlassian/homebrew-acli && brew install acli
+     acli auth login   # OAuth as the account matching $EMAIL
+
+3. Install the Atlassian MCP plugin (local scope — per-developer, gitignored).
+   The supported fallback when no credentials provider is configured.
 
    Run in your terminal:
 
@@ -174,25 +192,16 @@ Remediation paths (pick one):
    Then restart Claude Code (or run /restart-mcp) to load the plugin, and
    invoke 'mcp__plugin_atlassian_atlassian__authenticate' to complete OAuth.
 
-2. Install acli and authenticate (best for multi-account developers).
-
-     brew tap atlassian/homebrew-acli && brew install acli
-     acli auth login   # OAuth as the account matching $EMAIL
-
-3. Provision an API token (headless / CI / scoped-token environments).
-
-     Run /lisa:setup:atlassian — guided flow with clipboard-piped keychain store.
-
 EOF
   exit 1
 fi
 ```
 
-Operation dispatch then uses `$substrate` for the primary route. If the operation has no `acli` adapter and `$substrate=acli`, fall through to `$mcp_available` then `$curl_available` for the actual call. The fall-through stops at the first available tier that can perform the operation.
+Operation dispatch then uses `$substrate` for the primary route. If the operation has no adapter for the selected substrate, fall through in contract order — `$curl_available`, then `$acli_available`, then `$mcp_available` — skipping the tier already tried. The fall-through stops at the first available tier that can perform the operation. A tier that failed identity-match is never in the fall-through set.
 
 ### Step 2 — Connection-match check
 
-The active connection MUST point at the cloudId/site declared in `.lisa.config.json`. Step 1's substrate selection already tries to switch mismatched acli profiles and verifies the result before selection. This step repeats the assertion before any operation runs — defensive in case the substrate state changed since selection.
+The active connection MUST point at the cloudId/site declared in `.lisa.config.json`. Identity-match is mandatory on **every** substrate, tier 1 included (`credential-substrate-precedence`); the "curl mode check" below *is* the tier-1 gate referenced as `atlassian_token_matches_config` in Step 1. Step 1's substrate selection already validates the token account and tries to switch mismatched acli profiles before selection. This step repeats the assertion before any operation runs — defensive in case the substrate state changed since selection.
 
 Read configured site:
 
@@ -291,12 +300,12 @@ Rules:
 
 ### Step 3 — Operation dispatch
 
-Substrate column meanings:
+Substrate column meanings (ordering per `credential-substrate-precedence`):
 
-- **`acli`**: routes through `acli`. Preferred when available and identity-matched.
-- **`MCP`**: routes through the Atlassian MCP. Preferred when acli can't do the op and the MCP is identity-matched (cloudId in `getAccessibleAtlassianResources`).
-- **`curl`**: routes through curl + Basic auth + `ATLASSIAN_API_TOKEN`. Used when neither acli nor MCP is available.
-- Multiple cells filled means tier ordering applies — try acli, then MCP, then curl, taking the first that has an adapter for the op AND is identity-matched.
+- **`curl`**: routes through curl + Basic auth + `ATLASSIAN_API_TOKEN` — the configured-provider substrate. Preferred for every operation, read or write, whenever the token is present and identity-matched.
+- **`acli`**: routes through `acli`. Identity-matched fallback — used when no token is available or the op has no curl adapter. For JIRA writes it is the *guarded* fallback (see the tenant-safety rule below).
+- **`MCP`**: routes through the Atlassian MCP. First-class fallback for ops neither tier above covers, when identity-matched (cloudId in `getAccessibleAtlassianResources`).
+- Multiple cells filled means tier ordering applies — try curl, then acli, then MCP, taking the first that has an adapter for the op AND is identity-matched.
 - One cell means only that substrate can perform the op.
 
 `<SITE>` = `.atlassian.site` (e.g. `acme.atlassian.net`). `<CLOUDID>` = `.atlassian.cloudId`. `<AUTH>` = `Basic $(printf '%s:%s' "$email" "$ATLASSIAN_API_TOKEN" | base64)`. JIRA curl writes use the cloudId-bound Atlassian gateway `https://api.atlassian.com/ex/jira/<CLOUDID>/rest/api/3/...`; JIRA curl reads may use either that gateway or `https://<SITE>/rest/api/3/...` after the token account check. Confluence uses `/wiki/rest/api/...` (v1) or `/api/v2/...` (v2).
@@ -334,7 +343,7 @@ Substrate column meanings:
 
 **acli flag note:** acli's `--output` flag does not exist; the correct flag is `--json`. List commands require `--paginate` or `--limit` (no implicit fetch-all). `acli jira workitem view` defaults to a restricted field set (`key,issuetype,summary,status,assignee,description`), so `read-ticket` MUST pass `--fields '*all'` or an explicit equivalent that includes every downstream dependency: parent, subtasks, issue links, components, labels, priority, status, issue type, summary, description, fix versions, affected versions, attachments, comments, estimates, sprint/story-point fields, and project-required custom fields. Never rely on the default view fields; they hide parent/components/labels and corrupt leaf-only, relationship-search, build-ready, and required-custom-field gates. Several documented adapters are nominal — verify against `acli <subcmd> --help` before relying on them. When acli's adapter is broken or missing for a specific op, fall through to MCP (if identity-matched) then curl per the tier ordering.
 
-**JIRA write tenant-safety rule:** create, edit, transition, comment, and link are write operations. They MUST prefer the curl adapter whenever token auth is available because the URL includes `<CLOUDID>` and cannot be redirected by the user-global acli active account. If the flow must fall back to acli for a write, it is a guarded fallback, not the normal path:
+**JIRA write tenant-safety rule** — the Atlassian instance of the shared guarded-fallback protocol in `credential-substrate-precedence` (which states the general rule: prefer the per-invocation-bound substrate over the ambient-bound one, for reads and writes alike; the rationale is not restated here). Create, edit, transition, comment, and link are write operations. They MUST use the curl adapter whenever token auth is available because the URL includes `<CLOUDID>` and cannot be redirected by the user-global acli active account. If the flow must fall back to acli for a write, it is a guarded fallback, not the normal path:
 
 1. Switch and assert the active `acli auth status` site/email matches config immediately before the write.
 2. Execute the write.
@@ -378,15 +387,17 @@ Do not paraphrase substrate output beyond JSON normalization.
 ## Invariants
 
 - Caller skills never invoke `acli` or `curl` against Atlassian directly. They only invoke this skill.
+- Tier order is the shared `credential-substrate-precedence` contract — token curl first (reads **and** writes), then acli, then the Atlassian MCP. Do not restate or locally override the ordering here.
+- acli and the Atlassian MCP remain first-class **fallbacks**, not removed tiers: every adapter stays in the dispatch table, and a project with no credentials provider is fully functional on them.
 - Substrate is decided once per skill invocation and never switches mid-operation.
-- Connection match is mandatory. Operations that bypass it (because "the user obviously meant the configured site") are forbidden.
+- Connection match is mandatory on every tier, including the token tier. Operations that bypass it (because "the user obviously meant the configured site") are forbidden. A present-but-wrong token fails the gate rather than deferring to another substrate.
 - Profile mutations (`acli auth switch`) are allowed when acli is the active substrate. The curl substrate never mutates the token — if `ATLASSIAN_API_TOKEN` doesn't match the configured account, fail loud rather than silently substituting.
 - JIRA writes are cloudId-bound by default. `acli` write adapters are fallback-only and must perform post-write tenant assertions plus safe rollback on mismatch.
 - `.lisa.config.local.json` overrides `.lisa.config.json` per-key — the same precedence rule as every other consumer of project config.
 
 ## Headless behavior
 
-In a headless / non-interactive context, the MCP tier is unavailable (its OAuth flow needs a browser). The substrate ladder collapses to: acli (if pre-authenticated, e.g., a CI image baked with a service-account token) → curl + `ATLASSIAN_API_TOKEN`. Never block on interactive prompts. If both fail readiness checks, exit non-zero with a deterministic error.
+In a headless / non-interactive context, the MCP tier is unavailable (its OAuth flow needs a browser). The ladder collapses to: curl + `ATLASSIAN_API_TOKEN` → acli (if pre-authenticated, e.g., a CI image baked with a service-account token). Because curl is already tier 1 interactively, headless and interactive sessions take the **same primary path** — that is the "headless parity" arm of `credential-substrate-precedence`, and it is why a credential problem reproduces on a laptop instead of only in cron. Never block on interactive prompts. If both fail readiness checks, exit non-zero with a deterministic error.
 
 Treat all four of these as headless:
 

package/plugins/lisa/skills/lisa-confluence-to-tracker/SKILL.md

@@ -356,7 +356,7 @@ Each sub-task MUST:
 2. **Include an Empirical Verification Plan** — real user-like verification, NOT unit tests, linting, or typechecking
 3. **Carry its own `## Source Requirement` section** (shared format above) with the full verbatim quote(s) from the Phase 1.4 register — a leaf claimed by build-intake in isolation must be self-explanatory. When a sub-task is split per-repo, every split child inherits the same requirement quote(s).
 
-**Leaf-only build-ready (`leaf-only-lifecycle`)**: Sub-tasks are the **leaf work units** of the decomposition — they are the ONLY items in the hierarchy that receive the build-ready role. `lisa-tracker-write` applies the build-ready role here so downstream build intake (`lisa-tracker-build-intake`) claims the leaves and never the Epic or Stories. Apply the build-ready role to each Sub-task; never to its parent Story or Epic (Phases 3–4). `lisa-tracker-write` enforces the same invariant on the write side, so a Sub-task split into per-repo children (the cross-repo case above) carries build-ready on the children, not on any intermediate parent that gains child work.
+**Leaf-only build-ready (`leaf-only-lifecycle`)**: Sub-tasks are the **leaf work units** of the decomposition — they are the ONLY items in the hierarchy that receive the build-ready role. `lisa-tracker-write` applies the build-ready role here so downstream build intake (`lisa-tracker-build-intake`) claims the leaves and never the Epic or Stories. **Pass `build_ready: true` explicitly on every Sub-task create** — per the `ready-role-filing` rule an omitted `build_ready` is NOT build-ready on any tracker, so a decomposition that relies on a vendor default silently produces a queue nothing ever claims. Apply the build-ready role to each Sub-task; never to its parent Story or Epic (Phases 3–4). `lisa-tracker-write` enforces the same invariant on the write side, so a Sub-task split into per-repo children (the cross-repo case above) carries build-ready on the children, not on any intermediate parent that gains child work.
 
 Sub-tasks inherit their parent story's artifacts by reference (the parent link). Do not pass the same artifact list to every sub-task.
 
@@ -425,6 +425,7 @@ tickets that downstream skills (triage, journey, evidence) cannot use.
 
 For each sub-task, invoke `lisa-tracker-write` with:
 - issue_type: "Sub-task"
+- build_ready: true  # explicit per `ready-role-filing`; omitted is NOT build-ready on any tracker
 - prd_source: [the originating PRD URL — mandatory; arms the S16 traceability gate]
 - parent: the parent story key
 - project_key: [PROJECT]

package/plugins/lisa/skills/lisa-debrief-apply/SKILL.md

@@ -29,11 +29,11 @@ For every row marked **Accept**:
 | Edge case | Edge Case Brainstorm checklist in `intent-routing.md` | Append the new pattern + question to the matching group (Navigation, Data, Failure, Input, Auth, or a new group if none fit). Use the row's `Summary` and `Evidence` link as a citation comment. |
 | Recurring gotcha | Committed learnings ledger (via contract) | Persist a ledger entry per [Ledger persistence](#ledger-persistence-knowledge-categories). The `rule` is the recurring gotcha and the guard against it; `why` is the causal claim. |
 | Process friction | Committed learnings ledger (via contract) | Persist a ledger entry per [Ledger persistence](#ledger-persistence-knowledge-categories). The `rule` is the friction-avoiding guideline; `why` names the friction it prevents. |
-| Tooling gap | Configured tracker — or upstream Lisa when harness-level | **Split by level.** Project-level (a missing project script, hook, or automation) → create a ticket via `lisa-tracker-write` with `issue_type: Task`, summary derived from the row's `Summary`, description citing the evidence and the originating debrief doc, labeled `type:tooling` / `lifecycle-improvement`. Harness-level (a Lisa skill/gate/agent that should have caught the issue but didn't) → file an upstream Lisa issue exactly per the "Filing upstream" procedure in `lisa-rework-triage` (dedupe search first, three-audience description, evidence chain, `self-hardening` label; repo from `.lisa.config.json` `hardening.upstreamRepo`, default `CodySwannGT/lisa`). |
+| Tooling gap | Configured tracker — or upstream Lisa when harness-level | **Split by level.** Project-level (a missing project script, hook, or automation) → create a ticket via `lisa-tracker-write` with `issue_type: Task`, summary derived from the row's `Summary`, description citing the evidence and the originating debrief doc, labeled `type:tooling` / `lifecycle-improvement`, and explicit `build_ready: true` per `ready-role-filing` (a tooling gap the factory can close itself is queue work, and an omitted flag is NOT build-ready on any tracker). Harness-level (a Lisa skill/gate/agent that should have caught the issue but didn't) → file an upstream Lisa issue exactly per the "Filing upstream" procedure in `lisa-rework-triage` (dedupe search first, three-audience description, evidence chain, `self-hardening` label; repo from `.lisa.config.json` `hardening.upstreamRepo`, default `CodySwannGT/lisa`). |
 | Convention drift | Committed learnings ledger (via contract) | Persist a ledger entry per [Ledger persistence](#ledger-persistence-knowledge-categories). The `rule` is the correct convention; `why` records the drift it corrects. |
 | Decomposition infidelity | Upstream Lisa repo | File an upstream Lisa issue per the "Filing upstream" procedure in `lisa-rework-triage`, citing the PRD text vs. the distorted ticket AC and naming the gate that passed it. |
 | PRD defect | Source PRD | Comment on the PRD via the `lisa-prd-backlink` lineage quoting the defective requirement and the failure it missed; flag for product review. Never silently edit the spec. |
-| Missing tool access | Configured tracker | Create a provisioning ticket via `lisa-tracker-write` (`issue_type: Task`, `type:tooling`) describing the missing tool/credential/environment and which flow needs it. |
+| Missing tool access | Configured tracker | Create a provisioning ticket via `lisa-tracker-write` (`issue_type: Task`, `type:tooling`) describing the missing tool/credential/environment and which flow needs it. Pass `human_gate: "a human must grant the missing access"` per `ready-role-filing` — the factory cannot provision its own credentials. |
 | Uncategorized | **No route — requires reclassification** | `Uncategorized` records that the synthesizer could not fit the finding to a category; it is not itself a destination. Do NOT guess a route and do NOT silently skip the row. Leave the row unapplied, mark it `[!] Needs reclassification — <the synthesizer's "why no category fit" note>`, and list it under its own heading in the run summary so the human can retag it to one of the eight and re-run `apply`. A row that stays `Uncategorized` across runs is a signal the category set itself is missing a case — worth an upstream Lisa issue, not a forced fit. |
 
 For every row marked **Reject** or **Defer**: no action. Defer is a no-op for `apply` but worth surfacing in the run summary — the human may want to revisit at the next debrief.

package/plugins/lisa/skills/lisa-exploratory-qa/SKILL.md

@@ -70,7 +70,13 @@ Kane never files the work item itself. Even when it marks a failure as a confirm
 | User-visible **bug** (broken behavior) | `Bug` | the `ready` flag (default `false`) |
 | **Usability / UX / clarity issue** | `Improvement` | the `ready` flag (default `false`) |
 
-Each finding is a flat leaf, so `build_ready` applies directly — pass it explicitly on every create. Each ticket MUST be a complete spec (the validator rejects thin tickets): a **three-audience description**; for a **bug**, exact reproduction steps, observed-vs-expected, the env / account / interface it occurred at, and evidence; for a **usability issue**, the observed friction, who it affects, **where**, and the proposed improvement; and **Gherkin acceptance criteria** for the fixed behavior.
+Each finding is a flat leaf, so `build_ready` applies directly — pass it explicitly on every create.
+
+**This skill is the named human-gate exception under `ready-role-filing`.** Everywhere else in Lisa, a complete defect found during other work is filed with explicit `build_ready: true` so build-intake claims it next cycle. Exploratory QA is deliberately different, and that difference is ratified rather than drift: its findings are *candidate* defects and usability observations whose **product significance is a human call**, so auto-readying them would push judgment work into the build queue — precisely the failure the gate model exists to prevent. Its default `ready=false` is therefore an **explicit human-gate marker, never a bare omission**: every not-ready create passes `human_gate: "exploratory finding — product significance is a human product call"` alongside `build_ready: false`, and the writer stamps the auditable `[lisa-human-gate]` marker. An operator who wants a pass to feed the queue directly opts in with `ready=true`.
+
+(The sibling `e2e-coverage-gaps` skills are the contrast: a missing automated test is not a product question, so they file `build_ready: true` by default.)
+
+Each ticket MUST be a complete spec (the validator rejects thin tickets): a **three-audience description**; for a **bug**, exact reproduction steps, observed-vs-expected, the env / account / interface it occurred at, and evidence; for a **usability issue**, the observed friction, who it affects, **where**, and the proposed improvement; and **Gherkin acceptance criteria** for the fixed behavior.
 
 ### Idempotency — don't spam duplicates
 

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

@@ -258,6 +258,11 @@ A blocker is active if it is open and has no cleared status label. Treat `status
 
 **Claim-time archaeology runs second — after rejection detection, still before the relabel below.** Classify this item per the vendor-neutral `claim-archaeology` rule, with the rejection classification above as its input. All shared semantics — ancestry signals, classification, learning-loop exclusion, cost budget, candidate derivation, marker dedupe, and the never-block degrade — live in that one slug; change them there, never here. GitHub wiring only: the typed relations and `closingIssuesReferences` are already in the read bundle; text-similarity searches use `gh search issues` over recently-closed issues; the fallback candidate comment is posted with `gh issue comment`.
 
+**The two `claim-time-guards` run third and fourth — still before the relabel below.** Both semantics live in that one vendor-neutral slug; do not restate them here. GitHub wiring only:
+
+1. **`two-failed-attempts` valve.** Count `[lisa-build-attempt]` markers on the issue from the read bundle's comments (match on the marker, never the title). With two or more, do **not** claim: relabel to the configured blocked role (`gh issue edit <number> --repo <org>/<repo> --remove-label "$READY" --add-label "$BLOCKED"`, resolved from `github.labels.build.blocked` per `config-resolution`), post the operator-readable comment naming both attempts, and **stop the cycle** at Phase 3e. Every non-success terminal outcome recorded in 3c/3d also appends a fresh `<!-- [lisa-build-attempt] n=<N> outcome=<outcome> -->` marker so the next cycle can count it.
+2. **`already-implemented` check.** Probe for this issue's own key — `git log --all --grep "<org>/<repo>#<number>"` and `gh pr list --repo <org>/<repo> --state all --search "<org>/<repo>#<number>" --json number,state,mergedAt,url`. On a hit, claim as normal but route 3c to **verify-and-close** instead of `lisa-implement`: verify what shipped against the issue's acceptance criteria, post evidence via `lisa-github-evidence` naming the shipping PR/commit, then run the ordinary 3d transition and 3d.1 rollup. A partial hit implements only the remaining gap. An unreadable history degrades to "no hit" and the ordinary path proceeds — the guard never blocks the claim. This is not `DUPLICATE_ALREADY_FIXED` (a *different* canonical issue) and not `claim-archaeology` (a *different* ancestor issue); it is this issue's own work already having shipped without a transition.
+
 ```bash
 gh issue edit <number> --repo <org>/<repo> --remove-label "$READY" --add-label "$CLAIMED"
 # Assign to the authenticated user ONLY when the issue is currently unassigned (attributable claim;

package/plugins/lisa/skills/lisa-github-create/SKILL.md

@@ -80,7 +80,9 @@ Issues must be created in parent-before-child order:
 
 1. Invoke `lisa-github-write-issue` for the Epic. Capture the returned issue number.
 2. For each Story, invoke `lisa-github-write-issue` with the Epic ref as `parent_ref`. Capture each Story number.
-3. For each Sub-task, invoke `lisa-github-write-issue` with the Story ref as `parent_ref`.
+3. For each Sub-task, invoke `lisa-github-write-issue` with the Story ref as `parent_ref` and explicit `build_ready: true`.
+
+- **Declare readiness on every leaf write.** Per the `ready-role-filing` rule an omitted `build_ready` is **not build-ready** on any tracker, so pass `build_ready: true` on each Sub-task (the leaf work units this skill plans) and never on the Epic or Stories, which are containers per `leaf-only-lifecycle`. A leaf that is deliberately held instead passes `human_gate: "<why a human must judge this first>"`. Filing a leaf with neither is an incomplete handoff and `lisa-github-write-issue` rejects it.
 
 ### What to pass to each invocation
 

package/plugins/lisa/skills/lisa-github-to-tracker/SKILL.md

@@ -343,7 +343,7 @@ Each sub-task MUST:
 2. **Include an Empirical Verification Plan** — real user-like verification, NOT unit tests, linting, or typechecking.
 3. **Carry its own `## Source Requirement` section** (shared format above) with the full verbatim quote(s) from the Phase 1.4 register — a leaf claimed by build-intake in isolation must be self-explanatory. When a sub-task is split per-repo, every split child inherits the same requirement quote(s).
 
-**Leaf-only build-ready (`leaf-only-lifecycle`)**: Sub-tasks are the **leaf work units** of the decomposition — they are the ONLY items in the hierarchy that receive the build-ready label. `lisa-tracker-write` applies `status:ready` here so downstream build intake (`lisa-github-build-intake`) claims the leaves and never the Epic or Stories. Apply `status:ready` to each Sub-task; never to its parent Story or Epic (Phases 3–4). `lisa-github-write-issue` enforces the same invariant on the write side, so a Sub-task split into per-repo children (the cross-repo case above) carries build-ready on the children, not on any intermediate parent that gains child work.
+**Leaf-only build-ready (`leaf-only-lifecycle`)**: Sub-tasks are the **leaf work units** of the decomposition — they are the ONLY items in the hierarchy that receive the build-ready label. `lisa-tracker-write` applies `status:ready` here so downstream build intake (`lisa-github-build-intake`) claims the leaves and never the Epic or Stories. **Pass `build_ready: true` explicitly on every Sub-task create** — per the `ready-role-filing` rule an omitted `build_ready` is NOT build-ready on any tracker, so a decomposition that relies on a vendor default silently produces a queue nothing ever claims. Apply `status:ready` to each Sub-task; never to its parent Story or Epic (Phases 3–4). `lisa-github-write-issue` enforces the same invariant on the write side, so a Sub-task split into per-repo children (the cross-repo case above) carries build-ready on the children, not on any intermediate parent that gains child work.
 
 Sub-tasks inherit their parent Story's artifacts by reference (the parent link). Do not pass the same artifact list to every sub-task.
 
@@ -412,6 +412,7 @@ that downstream skills (triage, journey, evidence) cannot use.
 
 For each sub-task, invoke `lisa-tracker-write` with:
 - issue_type: "Sub-task"
+- build_ready: true  # explicit per `ready-role-filing`; omitted is NOT build-ready on any tracker
 - prd_source: [the originating PRD URL — mandatory; arms the S16 traceability gate]
 - parent_ref: the parent story ref
 - summary: prefixed with the repo in brackets, e.g. "[backend-api] Add audit log table"

package/plugins/lisa/skills/lisa-github-validate-issue/SKILL.md

@@ -382,13 +382,17 @@ Per `Phase 5` of `lisa-github-write-issue`, every issue MUST carry
 missing from the proposed spec or live issue, FAIL with the missing label name.
 
 The `status:*` requirement uses this validator's S15 leaf/container classification while preserving
-the writer's documented `build_ready` control-input defaults:
+the writer's documented `build_ready` control-input defaults, which the `ready-role-filing` rule
+fixes at "omitted is NOT build-ready" for every vendor:
 
 1. Classify the issue structurally using the S15 child-resolution rules. A container (any issue
    with child work, plus a childless `Epic`) may omit `status:*`; its state rolls up rather than
    being assigned directly.
-2. For a proposed leaf spec, normalize omitted `build_ready` to `true`, preserving the writer's
-   backward-compatible default-ready behavior. Explicit `build_ready: false` means backlog mode.
+2. For a proposed leaf spec, normalize omitted `build_ready` to `false`, per `ready-role-filing`:
+   ready is an explicit claim, so only `build_ready: true` asserts it. Explicit `build_ready: false`
+   means the same backlog mode. (This validator previously normalized omitted → `true` to mirror
+   GitHub's implicit-ready writer default; both were removed together, and re-introducing either
+   here would just move the leak.)
 3. For a live issue ref, derive `build_ready` from the labels (`true` exactly when the S15-resolved
    `READY_ROLE` from `github.labels.build.ready`, default `status:ready`, is present). A live backlog leaf without a status label
    therefore validates as `build_ready: false`; live data cannot distinguish an explicit false from

package/plugins/lisa/skills/lisa-github-write-issue/SKILL.md

@@ -253,12 +253,21 @@ For non-build-ready issues created fresh (Epics, Stories, and other containers),
 
 ### Build-ready control input (`build_ready`)
 
-`build_ready` is an optional write-control input (default: **omitted**). It governs whether a **leaf** work unit is stamped with the build-ready role on create. It never overrides `leaf-only-lifecycle` — a container is never stamped build-ready regardless of `build_ready`. "Not build-ready" is not a special status: it simply means the issue is created in its natural default (a plain open issue with **no `status:ready` label**), which a human can promote later.
+`build_ready` is a write-control input governed by the `ready-role-filing` rule — cite that slug for the full contract; do not restate its per-vendor normalization table here. It decides whether a **leaf** work unit is stamped with the build-ready role on create. It never overrides `leaf-only-lifecycle` — a container is never stamped build-ready regardless of `build_ready`. "Not build-ready" is not a special status: it simply means the issue is created in its natural default (a plain open issue with **no `status:ready` label**), which a human can promote later.
 
-- **Omitted** → current behavior: a leaf work unit receives `status:ready`. Preserves what every existing caller (`lisa-plan`, the `*-to-tracker` skills) relies on.
+- **Omitted** → **not build-ready**: the leaf is created without `status:ready`. Ready is an explicit claim, never a vendor default. **This is a breaking change** — GitHub previously applied `status:ready` on omission, so a caller that relied on that must now pass `build_ready: true`.
 - **`build_ready: false`** → create the leaf **without** `status:ready`, so it sits in the backlog for a human to review and promote into the queue.
 - **`build_ready: true`** → ensure the leaf carries `status:ready` so `lisa-intake` / `lisa-github-build-intake` auto-picks it up.
 
+**A filing with neither is an incomplete handoff.** A leaf that is not build-ready must carry an explicit `human_gate: "<why a human must judge this first>"`; nothing in the ready lane means nothing ever claims it. When `human_gate` is supplied, stamp the hold on the issue so it is auditable — a visible line plus the verbatim marker:
+
+```text
+Held for a human product call: <reason>.
+<!-- [lisa-human-gate] reason=<short-slug> -->
+```
+
+If a leaf arrives with `build_ready` omitted or `false` **and** no `human_gate`, do not create it: report the incomplete handoff and name both ways to resolve it (`build_ready: true`, or a `human_gate` reason). Containers are exempt — their state rolls up from children, so they need neither.
+
 ## Phase 5.5 — Validate (Pre-write Gate)
 
 Before any write, invoke `lisa-github-validate-issue` with the full proposed spec assembled from Phases 2 / 3 / 4 / 5. Pass it as a YAML block per the `lisa-github-validate-issue` schema, including `runtime_behavior_change`, `authenticated_surface`, and `artifacts_attached` flags so the right gates run.
@@ -271,9 +280,9 @@ If the validator reports `FAIL`, do NOT proceed to Phase 6. Fix the spec and re-
 
 ### CREATE
 
-1. Compose the body markdown from Phases 2/3/4 in a temp file (avoid quoting hell). Apply `status:ready` **only for a leaf work unit** per the Phase 5 leaf-only rule (`leaf-only-lifecycle`) — omit it for `Epic` / `Story` / `Spike` and any issue that has child work, **and** only when `build_ready` is not `false` (a leaf with `build_ready: false` is created without `status:ready`; see the Build-ready control input):
+1. Compose the body markdown from Phases 2/3/4 in a temp file (avoid quoting hell). Apply `status:ready` **only for a leaf work unit** per the Phase 5 leaf-only rule (`leaf-only-lifecycle`) — omit it for `Epic` / `Story` / `Spike` and any issue that has child work, **and** only when `build_ready` is explicitly `true` (a leaf with `build_ready` omitted or `false` is created without `status:ready`; see the Build-ready control input):
    ```bash
-   # Leaf work unit (Bug / Task / Sub-task / Improvement with no children), build_ready not false:
+   # Leaf work unit (Bug / Task / Sub-task / Improvement with no children), build_ready: true:
    gh issue create \
      --repo <org>/<repo> \
      --title "<summary>" \
@@ -282,9 +291,10 @@ If the validator reports `FAIL`, do NOT proceed to Phase 6. Fix the spec and re-
      [--label "component:<name>" ...] [--milestone "<milestone>"] \
      [--assignee "<login>"]
 
-   # Container (Epic / Story / Spike / any issue with child work), OR a leaf with build_ready: false:
+   # Container (Epic / Story / Spike / any issue with child work), OR a leaf whose build_ready is
+   # omitted or false (and which therefore carries an explicit human_gate):
    # identical, but WITHOUT --label "status:ready" — a container's state rolls up from children;
-   # a build_ready: false leaf waits in the backlog for a human to promote it.
+   # a human-gated leaf waits in the backlog for a human to promote it.
    gh issue create \
      --repo <org>/<repo> \
      --title "<summary>" \

package/plugins/lisa/skills/lisa-improve-harness/SKILL.md

@@ -191,7 +191,7 @@ authority — if any of these hold:
 **On any of those: file a proposed-intervention ticket via `lisa-tracker-write` and STOP.** The
 ticket carries the job contract, the earliest failed handoff, the gap classification with
 evidence, and the proposed change with its expected mechanism; labels `type:harness`,
-`status:blocked` (human-flipped to `status:ready` when approved). Post the result record with
+`status:blocked` plus an explicit `human_gate: "a human approves the proposed harness intervention"` per `ready-role-filing` (human-flipped to `status:ready` when approved). Post the result record with
 `Verdict: bounded-authority-stop`, `Decision: n/a (proposed-intervention, <url>)`, and
 terminate. Implementing it anyway is the failure mode this phase exists to prevent.
 

package/plugins/lisa/skills/lisa-jam-access/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lisa-jam-access
-description: "Vendor-neutral access layer for Jam. Jam triage rules and skills MUST delegate through this skill rather than calling Jam MCP tools directly. Resolves Jam MCP first when available, then falls back to the JAM_PAT-authenticated Jam CLI for headless routines."
+description: "Vendor-neutral access layer for Jam. Jam triage rules and skills MUST delegate through this skill rather than calling Jam MCP tools directly. Per the credential-substrate-precedence contract, resolves the JAM_PAT-authenticated Jam CLI first when the PAT is present and identity-matched, then falls back to the Jam MCP."
 allowed-tools: ["Bash", "Read", "Skill"]
 ---
 
@@ -21,13 +21,20 @@ Return parsed JSON or a concise structured summary in a `<result>` block.
 
 ## Substrate Selection
 
-Probe in order:
+Probe in order — the ordering is the shared `credential-substrate-precedence`
+contract, not a Jam-local choice. The first tier that is ready **and**
+identity-matches the configured Jam account is used; one authenticated elsewhere
+is skipped, never used.
 
-1. Jam MCP, if the tool is available and authenticated.
-2. Jam CLI authenticated with `JAM_PAT`.
+1. **Tier 1 — configured-provider substrate: Jam CLI authenticated with `JAM_PAT`**,
+   resolved through `lisa-secrets-access`.
+2. **Tier 2 — interactive MCP fallback: Jam MCP**, if the tool is available and
+   authenticated. Used when tier 1 is genuinely unavailable: no `JAM_PAT`, no CLI
+   adapter for the operation, or a Jam outage.
 
 Jam documents a PAT-authenticated CLI that is cleaner for remote routines than
-editing `.mcp.json` headers. The headless tier uses:
+editing `.mcp.json` headers, and it is the same substrate interactively and
+headlessly — which is why it leads. The CLI tier uses:
 
 ```bash
 curl -fsSL https://native.jam.dev/install | bash
@@ -44,7 +51,8 @@ Error: no Jam access substrate available. Authenticate the Jam MCP or set JAM_PA
 
 ## Invariants
 
-- Fallback is gated on `JAM_PAT`; do not retry Jam MCP failures blindly.
+- Tier order is `credential-substrate-precedence`: `JAM_PAT` CLI first, Jam MCP as
+  a preserved first-class fallback. Do not retry a failed tier blindly.
 - Never commit a Jam PAT into `.mcp.json` or any generated setup artifact.
 - Headless Jam access requires `native.jam.dev` for the installer and
   `api.jam.dev` for CLI/API calls in any custom remote network allowlist.

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

@@ -202,6 +202,11 @@ This gate never blocks a legitimate flat Task/Bug: those have no open children a
 
 **Claim-time archaeology runs second — after rejection detection, still before the transition below.** Classify this ticket per the vendor-neutral `claim-archaeology` rule, with the rejection classification above as its input. All shared semantics — ancestry signals, classification, learning-loop exclusion, cost budget, candidate derivation, marker dedupe, and the never-block degrade — live in that one slug; change them there, never here. JIRA wiring only: the typed relations are already in the read bundle; text-similarity searches run through `lisa-atlassian-access operation: search-issues jql:` over recently-closed tickets; the fallback candidate comment is posted via `lisa-atlassian-access operation: comment`.
 
+**The two `claim-time-guards` run third and fourth — still before the transition below.** Both semantics live in that one vendor-neutral slug; do not restate them here. JIRA wiring only:
+
+1. **`two-failed-attempts` valve.** Count `[lisa-build-attempt]` markers on the ticket from the read bundle's comments (match on the marker, never the summary). With two or more, do **not** claim: transition to the configured blocked status (`lisa-atlassian-access operation: transition to: "$BLOCKED"`, resolved from `jira.workflow.blocked` per `config-resolution`), post the operator-readable comment naming both attempts, and **stop the cycle** at Phase 3e. Every non-success terminal outcome recorded in 3c/3d also appends a fresh `<!-- [lisa-build-attempt] n=<N> outcome=<outcome> -->` marker so the next cycle can count it.
+2. **`already-implemented` check.** Probe for this ticket's own key — `git log --all --grep "<TICKET>"` and the merged/open PRs referencing `<TICKET>` (`gh pr list --state all --search "<TICKET>"` in the bound repo). On a hit, claim as normal but route 3c to **verify-and-close** instead of `lisa-implement`: verify what shipped against the ticket's acceptance criteria, post evidence via `lisa-jira-evidence` naming the shipping PR/commit, then run the ordinary 3d transition and rollup. A partial hit implements only the remaining gap. An unreadable history degrades to "no hit" and the ordinary path proceeds — the guard never blocks the claim. This is not `DUPLICATE_ALREADY_FIXED` (a *different* canonical ticket) and not `claim-archaeology` (a *different* ancestor ticket); it is this ticket's own work already having shipped without a transition.
+
 Transition the ticket from `$READY` to `$CLAIMED` by invoking `lisa-atlassian-access` `operation: transition key: <TICKET> to: "$CLAIMED"`.
 - **Assign to the authenticated user when the ticket is unassigned.** A claim must be attributable. If the ticket has no assignee, assign it to the authenticated account — prefer acli `--assignee @me` (resolves server-side to the authenticated user, which avoids the federated-`accountId` mis-assignment), or `write-ticket` with the `accountId` from the `/rest/api/3/myself` identity probe the access skill already documents. Leave an already-assigned ticket's assignee untouched — never reassign work that already has an owner.
 - Post a `[claude-build-intake]` comment via `lisa-atlassian-access` `operation: comment key: <TICKET> body: "Claimed by Claude. Starting build."`

package/plugins/lisa/skills/lisa-jira-create/SKILL.md

@@ -125,6 +125,8 @@ Exclude unless requested: migration plans, performance tests
 - Sign-in account and target environment recorded in description
 - Post-create verification
 
+**Declare readiness on every leaf write.** Per the `ready-role-filing` rule an omitted `build_ready` is **not build-ready** on any tracker, so pass `build_ready: true` on each Sub-task (the leaf work units this skill plans) and never on the Epic or Stories, which are containers per `leaf-only-lifecycle`. A leaf that is deliberately held instead passes `human_gate: "<why a human must judge this first>"`. Filing a leaf with neither is an incomplete handoff and `lisa-jira-write-ticket` rejects it.
+
 ### Invocation order
 
 Tickets must be created in parent-before-child order so each child can be passed its parent key: