@codyswann/lisa 2.353.0 → 3.0.0

package/plugins/lisa-agy/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-agy/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-agy/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-agy/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:

package/plugins/lisa-agy/skills/lisa-jira-write-ticket/SKILL.md

@@ -238,11 +238,21 @@ Before create/update, verify each field is populated where applicable:
 
 ### Build-ready control input (`build_ready`)
 
-`build_ready` is an optional write-control input (default: **omitted**). It governs whether a **leaf** work unit is promoted to the build-ready role on create. It never overrides `leaf-only-lifecycle` — a container is never promoted regardless of `build_ready`. Unlike the label-based trackers, JIRA tickets are **already created not-ready** (in the project's default initial status, e.g. `TODO`/`Backlog`); the build-ready role is the configured `ready` status (`jira.workflow.ready`, default `Ready`), reached by an explicit transition.
+`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 promoted to the build-ready role on create. It never overrides `leaf-only-lifecycle` — a container is never promoted regardless of `build_ready`. Unlike the label-based trackers, JIRA tickets are **already created not-ready** (in the project's default initial status, e.g. `TODO`/`Backlog`); the build-ready role is the configured `ready` status (`jira.workflow.ready`, default `Ready`), reached by an explicit transition. JIRA is the vendor whose behavior the other two converged onto — this arm is unchanged by that normalization.
 
-- **Omitted** or **`build_ready: false`** → current behavior: leave the ticket in the project's default created status. No transition. A human (or `build_ready: true`) promotes it to the `ready` status later.
+- **Omitted** → **not build-ready**: leave the ticket in the project's default created status. No transition. Ready is an explicit claim, never a vendor default.
+- **`build_ready: false`** → same outcome as omitted, stated deliberately: the ticket waits in the project's default status for a human to promote it.
 - **`build_ready: true`** → after create, transition the **leaf** to the resolved `ready` role so `lisa-intake` / `lisa-jira-build-intake` auto-picks it up (see Phase 6 CREATE step). Resolve the role name with the standard pattern (`.jira.workflow.ready` // `Ready`, local overrides global). Best-effort: if the transition is unreachable, record it and leave the ticket in its default status rather than failing the write.
 
+**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 status means nothing ever claims it. When `human_gate` is supplied, stamp the hold on the ticket 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 status rolls up from children, so they need neither.
+
 ## Phase 5.5 — Validate (Pre-write Gate)
 
 Before any write, invoke `lisa-jira-validate-ticket` with the full proposed spec assembled from Phases 2 / 3 / 4 / 5. Pass it as a YAML block per the `lisa-jira-validate-ticket` schema, including `runtime_behavior_change`, `authenticated_surface`, and `artifacts_attached` flags so the right gates run.

package/plugins/lisa-agy/skills/lisa-learnings-audit/SKILL.md

@@ -172,7 +172,12 @@ audits the auditor without re-running it.
 
 All project-tracker writes go through **`lisa-tracker-write`** so gardener
 tickets pass the same validation gates as all factory work. Nothing is created
-`status:ready` — the human flips.
+`status:ready` — the human flips. Per `ready-role-filing` that hold is
+**declared, not implied**: every gardener ticket passes
+`human_gate: "a human decides whether this knowledge is promoted, demoted, or
+retired"` so the writer stamps the auditable `[lisa-human-gate]` marker. An
+omitted flag would be indistinguishable from the accidental non-ready filing
+the rule exists to catch.
 
 **Per-item tickets — PROMOTE / DEMOTE** (`issue_type: Task`; GitHub trackers
 carry the `type:Task` label) — one ticket per recommendation, capped by

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

@@ -203,6 +203,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 Issue per the vendor-neutral `claim-archaeology` rule, with the rejection classification above as its input. All shared semantics — ancestry signals, classification, learning-loop exclusion, cost budget, candidate derivation, marker dedupe, and the never-block degrade — live in that one slug; change them there, never here. Linear wiring only: the native relations are already in the read bundle; text-similarity searches run through `lisa-linear-access operation: list-issues` filtered to recently-closed Issues; the fallback candidate comment is posted via `lisa-linear-access operation: save-comment`.
 
+**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. Linear 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: set `stateId` to the configured blocked state via `lisa-linear-access operation: save-issue` (resolved from `linear.workflow.blocked` per `config-resolution`), post the operator-readable comment naming both attempts via `save-comment`, 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 "<IDENTIFIER>"` and the merged/open PRs referencing `<IDENTIFIER>` (`gh pr list --state all --search "<IDENTIFIER>"` in the bound repo; Linear's own GitHub attachments in the read bundle are the cheaper first look). 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-linear-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 Issue) and not `claim-archaeology` (a *different* ancestor Issue); it is this Issue's own work already having shipped without a transition.
+
 Transition the Issue via `lisa-linear-access operation: save-issue` by setting `stateId` to the `$CLAIMED` state. Resolve state IDs via `list-workflow-states`; a missing `$CLAIMED` state is a setup defect (see the pre-flight check) — never create one here.
 
 **Assign to the authenticated user when the Issue is unassigned.** A claim must be attributable. If the Issue has no assignee, set its `assigneeId` to the authenticated viewer (resolve the viewer's id via the Linear MCP identity — e.g. `get_user` for the current actor) through `lisa-linear-access operation: save-issue`. Leave an already-assigned Issue's assignee untouched — never reassign work that already has an owner.

package/plugins/lisa-agy/skills/lisa-linear-create/SKILL.md

@@ -124,7 +124,9 @@ Items must be created in parent-before-child order so each child can be passed i
 
 1. Invoke `lisa-linear-write-issue` for the Epic (Project). Capture the returned Project ID.
 2. For each Story, invoke `lisa-linear-write-issue` with the Project ID as `parent_project_id`. Capture each Issue identifier.
-3. For each Sub-task, invoke `lisa-linear-write-issue` with the Story Issue ID as `parent_issue_id`.
+3. For each Sub-task, invoke `lisa-linear-write-issue` with the Story Issue ID as `parent_issue_id` 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-linear-write-issue` rejects it.
 
 ### What to pass to each invocation
 

package/plugins/lisa-agy/skills/lisa-linear-to-tracker/SKILL.md

@@ -340,7 +340,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.
 
@@ -408,6 +408,7 @@ produces broken tickets that downstream skills (triage, journey, evidence) canno
 
 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-agy/skills/lisa-linear-write-issue/SKILL.md

@@ -31,7 +31,7 @@ Linear's data model maps Epic / Story / Sub-task to **different entity types**.
 | `Bug` | **Issue** | `lisa-linear-access operation: save-issue` | `projectId` if part of an Epic; else top-level |
 | `Spike` | **Issue** | `lisa-linear-access operation: save-issue` | `projectId` if part of an Epic; else top-level |
 
-The build lifecycle uses native **workflow states** (`Ready`, `In Progress`, `In Review`, `Blocked`, `On Dev`, `On Stg`, `Done`), resolved per role from `linear.workflow` — see "Why Linear uses states, not labels" in `config-resolution`. A new **leaf** work unit is created in the configured `ready` state by default; `build_ready: false` leaves it in the team's default backlog state instead, and a container is never put in `ready` at all (see the Build-ready control input below).
+The build lifecycle uses native **workflow states** (`Ready`, `In Progress`, `In Review`, `Blocked`, `On Dev`, `On Stg`, `Done`), resolved per role from `linear.workflow` — see "Why Linear uses states, not labels" in `config-resolution`. A new **leaf** work unit is created in the configured `ready` state only on explicit `build_ready: true`; omitted or `false` leaves it in the team's default backlog state, and a container is never put in `ready` at all (see the Build-ready control input below).
 
 ## Phase 1 — Resolve Intent
 
@@ -242,7 +242,7 @@ If the item modifies an existing user-facing surface, a `lisa-product-walkthroug
 
 Before create/update, verify each field is populated where applicable:
 
-- **Workflow state**: set the resolved `ready` state (`linear.workflow.ready`, default `Ready`) on a new **leaf** work unit (Bug / Task / Sub-task / Improvement with no child work) per `leaf-only-lifecycle`, **unless `build_ready: false`** (see the Build-ready control input below). A container (Epic Project / Story with sub-issues / Spike) is never put in the build-ready state.
+- **Workflow state**: set the resolved `ready` state (`linear.workflow.ready`, default `Ready`) on a new **leaf** work unit (Bug / Task / Sub-task / Improvement with no child work) per `leaf-only-lifecycle`, **only on explicit `build_ready: true`** (see the Build-ready control input below). A container (Epic Project / Story with sub-issues / Spike) is never put in the build-ready state.
 - **Labels**: taxonomy only — `type:<Kind>`, `repo:<name>`, `component:<name>`, and the `prd-intake-feedback` sentinel. Lifecycle is **not** a label on Linear; do not add `status:*` labels.
 - **Native priority field**: 0–4 per Linear's scale; explicit, not "unset".
 - **Native estimate**: per Linear's team-configured estimate scale (often 0–8 Fibonacci); skip for Epic / Spike.
@@ -254,12 +254,21 @@ For Bug / Task / Sub-task, ensure the summary is prefixed with `[<repo-name>]`.
 
 ### Build-ready control input (`build_ready`)
 
-`build_ready` is an optional write-control input (default: **omitted**). It governs whether a **leaf** work unit is created **in the resolved `ready` workflow state**. It never overrides `leaf-only-lifecycle` — a container is never stamped build-ready regardless of `build_ready`. "Not build-ready" is not a special state: the Issue is simply left in the team's default backlog/unstarted state, which a human can promote later. This mirrors `lisa-jira-write-ticket`, because Linear is a state-driven tracker like JIRA, not a label-driven one like GitHub.
+`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 created **in the resolved `ready` workflow state**. It never overrides `leaf-only-lifecycle` — a container is never stamped build-ready regardless of `build_ready`. "Not build-ready" is not a special state: the Issue is simply left in the team's default backlog/unstarted state, which a human can promote later. This mirrors `lisa-jira-write-ticket`, because Linear is a state-driven tracker like JIRA, not a label-driven one like GitHub.
 
-- **Omitted** → current behavior: a leaf work unit is created in the resolved `ready` state. Preserves what every existing caller (`lisa-plan`, the `*-to-tracker` skills) relies on.
+- **Omitted** → **not build-ready**: the leaf is left in the team's default backlog state. Ready is an explicit claim, never a vendor default. **This is a breaking change** — Linear previously created a leaf directly in the `ready` state on omission, so a caller that relied on that must now pass `build_ready: true`.
 - **`build_ready: false`** → create the leaf **without** the `ready` state, leaving it in the team's default backlog state so it waits for a human to review and promote it into the queue.
 - **`build_ready: true`** → transition the **leaf** to the resolved `ready` state (`.linear.workflow.ready`) so `lisa-intake` / `lisa-linear-build-intake` auto-picks it up. Best-effort: if the state cannot be resolved or the transition is rejected, do not fail the write — leave the Issue in its default state and record the reason.
 
+**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-linear-validate-issue` with the full proposed spec assembled from Phases 2 / 3 / 4 / 5. Pass it as a YAML block per the `lisa-linear-validate-issue` schema, including `runtime_behavior_change`, `authenticated_surface`, and `artifacts_attached` flags so the right gates run.

package/plugins/lisa-agy/skills/lisa-notion-to-tracker/SKILL.md

@@ -342,7 +342,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.
 
 **Verification plan examples by stack:**
 - **Backend APIs**: curl GraphQL/REST calls with auth token, database queries, checking audit entries
@@ -426,6 +426,7 @@ produces broken tickets that downstream skills (triage, journey, evidence) canno
 
 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
 - parent: the parent story key
 - project_key: [PROJECT]
 - prd_source: [the originating PRD URL — mandatory; arms the S16 traceability gate]

package/plugins/lisa-agy/skills/lisa-persist-learning/SKILL.md

@@ -112,7 +112,7 @@ This disposition completes the SLL-5 loop (#1583): on a Lisa-attributed failure
 
    Resolve the upstream repo from `.lisa.config.json` `hardening.upstreamRepo` (default `CodySwannGT/lisa`). Search **all issue states** for an existing issue carrying the marker — a closed marker-bearing ticket still owns this root cause, and searching only open issues would mint a duplicate the moment the original closes. Match on the **MARKER, never the title** — with the same eventual-consistency guard as above (`gh issue list -R <upstream> --state all --search '"<marker>" in:body' --json number,state,url`, and when the search index returns nothing, also `gh issue list -R <upstream> --state all --json number,state,body` and grep the bodies for the marker before concluding no ticket exists).
 
-   - **No existing ticket** → compose the body EXCLUSIVELY through the executable builder, then file its stdout verbatim via `lisa-github-write-issue` targeting the upstream repo with the `self-hardening` label:
+   - **No existing ticket** → compose the body EXCLUSIVELY through the executable builder, then file its stdout verbatim via `lisa-github-write-issue` targeting the upstream repo with the `self-hardening` label and explicit `build_ready: true` (per `ready-role-filing`; the upstream repo runs its own build queue off the ready role, and an omitted flag would strand the hardening ticket there):
 
      ```bash
      bunx @codyswann/lisa file-upstream --input filing-event.json   # or pipe the JSON on stdin

package/plugins/lisa-agy/skills/lisa-prd-source-write/SKILL.md

@@ -48,8 +48,10 @@ ideation_ledger_payload:              # optional; forwarded unchanged to the ven
 - **`ready`** → the PRD is created in the source's `ready` PRD role (`prd-ready`), so the PRD-side of
   `lisa-intake` / the `*-prd-intake` scanner auto-claims it on the next cycle.
 
-There is no "omitted = legacy behavior" mode (unlike the ticket-side `build_ready`): there was no
-prior PRD-source-write behavior to preserve, so omitted means `draft`.
+Omitted means `draft` — the not-ready default. This matches the ticket-side `build_ready` contract
+in `ready-role-filing`: on both sides of the pipeline, entering a queue is an **explicit claim** and
+omission is the safe direction. (The ticket side reached that position by removing a per-vendor
+legacy default; the PRD side never had one to remove.)
 
 ## Workflow
 

package/plugins/lisa-agy/skills/lisa-qa-fail/SKILL.md

@@ -20,7 +20,9 @@ plus any screenshots).
   recently-closed tickets in the affected area, and the current QA-queue set. If an existing ticket
   covers it, that ticket is the target — update it, never file a twin. Only when the
   search documents no match, create a new Bug via `lisa-tracker-write` (which enforces
-  the full quality gates) and treat it as the target. Report which path was taken.
+  the full quality gates) with explicit `build_ready: true` per the `ready-role-filing`
+  rule — omitted is NOT build-ready on any tracker, and a rework Bug nothing claims is
+  an incomplete handoff — and treat it as the target. Report which path was taken.
 
 ## Phase 2 — Structured failure report
 

package/plugins/lisa-agy/skills/lisa-repair-intake/SKILL.md

@@ -752,6 +752,34 @@ with labels like `build-ready`, or with no Lisa status label at all, that are in
    applied. Include the normalization result in the loop-prevention fingerprint so repeated repair
    cycles do not spam comments.
 
+### Ungated non-ready filing → surface as an incomplete handoff (read-only)
+
+The recovery net for the failure `ready-role-filing` prevents: an agent files a real defect it found
+during other work, never gives it the ready role, and the ticket sits forever because build-intake
+scans the ready lane and nothing else. Under that rule every filing declares either
+`build_ready: true` or a `human_gate` reason; an item carrying neither is an **incomplete handoff**.
+
+1. Enumerate open items filed recently (within the configured staleness window — same resolution as
+   every other candidate class) that are **not** in the configured `ready` role for their lifecycle
+   and are not in a claimed / blocked / terminal role either. On GitHub that is the absence of the
+   configured build `ready` label; on JIRA and Linear it is a status/state outside the configured
+   `ready` role. Items whose role is simply "the tracker's default created lane" are the target.
+2. Exclude anything carrying the `[lisa-human-gate]` marker — those are deliberate holds and the rule
+   ratifies them. Exclude containers (their state rolls up per `leaf-only-lifecycle`), and exclude
+   `[lisa-exploratory-qa]`-marked findings, which are the rule's **named** human-gate exception even
+   on an older item written before the marker existed.
+3. **Report each survivor read-only; never promote it.** Name the item, when it was filed, and what
+   filed it, and state the two ways to resolve it — flip it to the configured `ready` role, or mark
+   it as a deliberate human gate. A filing whose readiness nobody declared is exactly the input the
+   gate model says a human should see, so guessing "it was probably meant to be ready" would
+   re-introduce the accidental-queue-entry failure this rule exists to eliminate.
+4. Post at most one idempotent `[lisa-repair-intake]` note per item and include the finding in the
+   loop-prevention fingerprint so repeated cycles do not spam.
+
+This is distinct from the GitHub label-normalization repair above, which targets items carrying **no
+Lisa lifecycle label at all** (created by older tools or by hand) and does normalize them. This sweep
+targets items inside the Lisa lifecycle whose readiness was never declared.
+
 ## Blocker classification & clearing (conservative, vendor-specific extraction)
 
 A `blocked` build item is held by one or more of three blocker classes. Identify which are present

package/plugins/lisa-agy/skills/lisa-rework-triage/SKILL.md

@@ -96,8 +96,8 @@ Lisa work item.
 |---------------|-------------|--------|
 | `decomposition-infidelity` | **Upstream Lisa issue** | The decomposition pipeline produced an unfaithful ticket and every gate passed it — that is a harness defect. File per "Filing upstream" below, citing the PRD text, the distorted ticket AC, and which gate should have caught it. |
 | `verification-gap` | **Upstream Lisa issue** | The verification lifecycle passed work it should have failed. File per "Filing upstream", citing the missed failure class and the weak/missing codified test. |
-| `missing-tool-access` | Project tracker | Create a provisioning ticket via `lisa-tracker-write` (`issue_type: Task`, labeled `type:tooling`) describing the missing tool/credential/environment and which flow needs it. Link it `blocks` the rework ticket. |
-| `environment-data` | Project tracker | Create an environment-hardening ticket via `lisa-tracker-write` citing the drift/fixture/shared-state evidence. Link `relates to` the rework ticket. |
+| `missing-tool-access` | Project tracker | Create a provisioning ticket via `lisa-tracker-write` (`issue_type: Task`, labeled `type:tooling`) describing the missing tool/credential/environment and which flow needs it. Link it `blocks` the rework ticket. Pass `human_gate: "a human must grant the missing access"` per `ready-role-filing` — the factory cannot provision its own credentials, so this is a declared gate rather than an unclaimed filing. |
+| `environment-data` | Project tracker | Create an environment-hardening ticket via `lisa-tracker-write` citing the drift/fixture/shared-state evidence. Link `relates to` the rework ticket. Pass `build_ready: true` when the hardening is a code/fixture change the factory can make, or `human_gate: "<the shared-environment decision a human owns>"` when it is not — per `ready-role-filing`, never neither. |
 | `prd-defect` | Source PRD | Comment on the PRD (via the `lisa-prd-backlink` lineage) quoting the defective requirement and the QA failure; flag for product review. Do NOT silently edit the PRD — spec changes are a human gate. |
 | `implementation-defect` (no secondary) | None | Normal fix path; the classification comment is the record. Pass the pattern to the `learner` phase — repeated implementation defects of the same shape escalate to `verification-gap`. |
 

package/plugins/lisa-agy/skills/lisa-tracker-build-intake/SKILL.md

@@ -83,4 +83,5 @@ If the canonical fix is merged but not yet on the production branch, the close c
 - **Leaf-only dispatch, every vendor.** Per the `leaf-only-lifecycle` rule, each vendor scanner dispatches leaf work units only and moves or safe-blocks a container (open child work, or a childless Epic) carrying a stale build-ready role according to its lifecycle semantics. This shim does not re-implement the gate — it relies on the vendor scanner's Phase 3a — but the contract is uniform across `jira`, `github`, and `linear` so behavior never drifts by tracker.
 - **Terminal native closure, every capable vendor.** Per the same rule, each vendor scanner finalizes native open/closed state only at the true terminal `done` value. This shim never performs native closure itself, but callers can rely on the dispatched vendor scanner to apply the contract.
 - **Duplicate already fixed, every vendor.** Auto-close without a PR is allowed only for `DUPLICATE_ALREADY_FIXED` with canonical reference and empirical base-branch evidence. Do not conflate this with `BLOCKED`.
+- **Claim-time guards, every vendor.** Per the `claim-time-guards` rule, each vendor scanner runs both guards inside its Phase 3b before the claim transition: an item whose own key already appears in git history or an open/merged PR routes to **verify-and-close** rather than being built twice, and the **`two-failed-attempts`** valve moves an item with two `[lisa-build-attempt]` markers to the configured blocked role and stops the cycle. This shim does not re-implement either guard; it forwards the contract so behavior never drifts by tracker.
 - Never run two intake cycles concurrently against overlapping queues — the scheduling layer is responsible for serialization.

package/plugins/lisa-agy/skills/lisa-tracker-create/SKILL.md

@@ -24,4 +24,5 @@ See the `config-resolution` rule for configuration and dispatch table.
 ## Rules
 
 - All vendor skills delegate every individual ticket write through `lisa-tracker-write`. They never call vendor-specific write tools directly.
+- **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-tracker-write` rejects it.
 - This shim is for ad-hoc creation from code files / descriptions. PRD-driven creation goes through the `*-to-tracker` skills (notion / confluence / linear / github).

package/plugins/lisa-agy/skills/lisa-tracker-write/SKILL.md

@@ -52,3 +52,4 @@ See the `config-resolution` rule for the full configuration schema and skill-map
 - Never accept a tracker value outside `{jira, github, linear}`.
 - Never mutate `$ARGUMENTS` between layers. The vendor skills define their own input contract.
 - Never inline gate logic here. All validation rules live in the vendor skills (`lisa-jira-validate-ticket` / `lisa-github-validate-issue` / `lisa-linear-validate-issue`); this skill only routes.
+- **Readiness is the caller's explicit claim, not this shim's default.** Per the `ready-role-filing` rule, an omitted `build_ready` is **not build-ready** on every vendor, so a caller filing work it expects build-intake to pick up must pass `build_ready: true`, and a caller deliberately holding work outside the queue must pass a `human_gate` reason. This shim normalizes nothing — it forwards `$ARGUMENTS` verbatim and the vendor writers enforce the contract — which is exactly why the caller cannot rely on a vendor default here.

package/plugins/lisa-agy/skills/lisa-verify/SKILL.md

@@ -35,7 +35,7 @@ Treat the first successful lead-spawn request (or, on the Codex fallback, the fi
 
 Execute the **Verify** flow as defined in the `intent-routing` rule (loaded via the lisa plugin). The flow includes:
 
-1. **Pre-flight: codification gate** — confirm that every passing local empirical verification on this branch was codified as a regression test (the Implement flow's codify step). If any verification has no committed test and no allowed skip reason (PR / Documentation / Deploy / Investigate-Only), invoke `codify-verification` now and amend the PR before shipping. For frontend work the gate additionally enforces the `bdd-e2e-coverage` rule: the shipped behavior exists as a Gherkin scenario with a stable ID, every required scenario-platform obligation has aligned automation in the project's configured runner for that platform or a dated waiver, and the project's coverage gate passes with the matrix regenerated. A missing runner is never a bare recorded absence — it needs a dated `platformWaivers` entry (per the rule) and, where the runner could reasonably be added, a linked build-ready follow-up ticket referenced from it; never a silent skip. Missing BDD coverage is a verification failure that blocks the ship, not a warning. A change cannot ship until its verifications are guarded. For work that adds or changes persistent state the gate additionally enforces the `reset-seed-coverage` rule: every entity the work introduces or changes is classified in the project's state contract, anything `fixture-owned` has an ownership predicate and a sweep, and the state-classification check passes — an unclassified entity fails closed and blocks the ship exactly as missing BDD coverage does.
+1. **Pre-flight: codification gate** — confirm that every passing local empirical verification on this branch was codified as a regression test (the Implement flow's codify step). If any verification has no committed test and no allowed skip reason (PR / Documentation / Deploy / Investigate-Only), invoke `codify-verification` now and amend the PR before shipping. For frontend work the gate additionally enforces the `bdd-e2e-coverage` rule: the shipped behavior exists as a Gherkin scenario with a stable ID, every required scenario-platform obligation has aligned automation in the project's configured runner for that platform or a dated waiver, and the project's coverage gate passes with the matrix regenerated. A missing runner is never a bare recorded absence — it needs a dated `platformWaivers` entry (per the rule) and, where the runner could reasonably be added, a linked build-ready follow-up ticket referenced from it — filed through `lisa-tracker-write` with explicit `build_ready: true` per `ready-role-filing`, since an omitted flag is NOT build-ready on any tracker and the waiver would then point at work nothing claims; never a silent skip. Missing BDD coverage is a verification failure that blocks the ship, not a warning. A change cannot ship until its verifications are guarded. For work that adds or changes persistent state the gate additionally enforces the `reset-seed-coverage` rule: every entity the work introduces or changes is classified in the project's state contract, anything `fixture-owned` has an ownership predicate and a sweep, and the state-classification check passes — an unclassified entity fails closed and blocks the ship exactly as missing BDD coverage does.
 2. **Commit** any pending changes via `lisa-git-commit`
 3. **Push and PR** via `lisa-git-submit-pr`
 4. **PR Watch Loop** — drive the PR to MERGED via `lisa-drive-pr-to-merge`, the single source of truth for clearing every blocker: auto-merge with direct-merge fallback, `BEHIND` re-sync, conflict resolution, failing-check fixes, human + bot review-comment handling with thread resolution (it invokes `lisa-pull-request-review` itself), stale `CHANGES_REQUESTED` dismissal, and post-merge ancestry verification. Do not re-implement the loop or its terminal conditions.

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.353.0",
+  "version": "3.0.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.353.0",
+  "version": "3.0.0",
   "description": "AWS CDK-specific Lisa plugin.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.353.0",
+  "version": "3.0.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.353.0",
+  "version": "3.0.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.353.0",
+  "version": "3.0.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

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

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

package/plugins/lisa-copilot/rules/eager/bdd-e2e-coverage.md

@@ -15,7 +15,7 @@ Default locations (a project that already has an equivalent contract keeps its o
 | Artifact | Default path | What it is |
 |---|---|---|
 | Scenarios | `bdd/features/*.feature` | Gherkin, the product-level behavior contract |
-| Coverage map | `bdd/coverage-map.json` | scenario → runner/platform/file/evidence mappings, plus waivers |
+| Coverage map | `bdd/coverage-map.json` | scenario → runner/platform/file/evidence mappings, plus waivers, per-runner test-discovery roots, and exclusions |
 | Generated matrix | `docs/bdd-scenario-matrix.md` | regenerated, never hand-edited |
 | Burndown | `docs/e2e-bdd-coverage.md` | current coverage per platform |
 
@@ -36,6 +36,8 @@ The last three are out of the denominator. Deleting a committed capability to ma
 
 Coverage is counted per **required scenario-platform obligation**, and an obligation is sealed only by **aligned e2e automation in the project's configured runner for that platform** — the runner→platform mapping is project configuration (e.g. a web runner covering `web`, a device runner covering `ios`/`android`), never named by this contract. A unit test, a route boot, a screenshot, a fixture, an API test, or a passing test on a *different* platform never seals an obligation: they prove something else. Each mapping names the runner, the platforms, the file, and the evidence string inside it, so the gate can prove the mapping still resolves.
 
+**The gate reads in both directions.** It also walks the test roots the project declares per runner, so an e2e test that exists but that the contract never mentions is a violation — map it to a scenario, or record an exclusion stating why it aligns to no product behavior. Roots are configuration: a subflow or helper directory left undeclared is structurally invisible, which is the same failure as having no gate for it.
+
 **Waivers are dated IOUs, never coverage.** An obligation whose runner genuinely cannot decide it today (no camera on the simulator, no request interception, no provisioned provider credential) is recorded with scenario, platforms, reason, and `recordedAt`. It leaves the denominator; it never counts as covered, and nothing about it asserts the behavior works. A waiver is invalid — and fails the gate — when it names a nonexistent scenario or an undeclared platform, covers an already-excluded scenario, or masks a scenario-platform that already has a mapping. Revisit a waiver when its reason dies.
 
 ## Definition of done

package/plugins/lisa-copilot/rules/eager/claim-time-guards.md

@@ -0,0 +1,30 @@
+# Claim-Time Guards (load-bearing)
+
+Two guards that run when build-intake claims a ready item, both from failures observed in the fleet: an item built twice because it had already shipped, and a loop burning cycles re-attempting an item that was never going to succeed.
+
+**One vendor-neutral contract, cited by every build-intake arm** (the `leaf-only-lifecycle` / `repo-scope-split` / `rejection-detection` / `claim-archaeology` precedent: one shared slug, never three divergent implementations).
+
+## When they run
+
+Inside build-intake step `3b`, after `rejection-detection` and `claim-archaeology`, still before the `$READY → $CLAIMED` transition. The `two-failed-attempts` valve runs first — it is cheaper and it is the only pass that can stop the claim outright.
+
+## `already-implemented` → `verify-and-close`
+
+A ready item may already be implemented, because agents ship without transitioning. Before implementing, probe for the item's **own** key:
+
+```bash
+git log --all --grep "<key>" --format='%H %aI %s' -n 10
+gh pr list --repo <org>/<repo> --state all --search "<key>" --json number,state,mergedAt,url
+```
+
+On a hit, do not build it twice — switch `3c` to **verify-and-close**: verify what shipped against this item's acceptance criteria, post evidence naming the shipping PR/commit, then run the ordinary `3d` transition and rollup. If the shipped change only partially satisfies the criteria, implement the remaining gap instead of closing.
+
+Distinct from `claim-archaeology` (finds a **different** ancestor issue) and from `DUPLICATE_ALREADY_FIXED` (a **different** canonical issue). Unreadable history degrades to "no hit"; the guard never blocks the claim.
+
+## `two-failed-attempts` → blocked
+
+Every non-success terminal outcome records a durable marker on the item — a visible line plus `<!-- [lisa-build-attempt] n=<N> outcome=<outcome> -->` (match on the marker, never the title). A cron holds no memory between cycles, so the item carries the count.
+
+With **two or more** markers at claim time: do not claim. Move the item to the configured `blocked` role (resolved per `config-resolution`, never hardcoded), post an operator-readable comment naming both attempts and what a human must decide or supply, and **stop the loop** for this cycle. Recovery is deliberate — a human or a `lisa-repair-intake` cycle with the blocker provably cleared returns it to the queue.
+
+Full contract (probe bounds, verify-and-close steps, partial-hit handling, marker mechanics): [reference/claim-time-guards.md](../reference/claim-time-guards.md).

package/plugins/lisa-copilot/rules/eager/ready-role-filing.md

@@ -0,0 +1,22 @@
+# Ready-Role Filing (load-bearing)
+
+Filing a work item without the ready role is an **incomplete handoff** — build-intake scans the ready lane and nothing else, so the item is never picked up. A correct write plus a missing role still loses the work.
+
+## Omitted means NOT ready — on every tracker
+
+**An omitted `build_ready` is NOT build-ready on JIRA, GitHub, and Linear alike.** Ready is an explicit claim, never an accident of which tracker a project configured. This is a **breaking change** for GitHub and Linear callers, which previously treated omission as ready; `lisa-github-validate-issue` F4's compensating omitted → `true` normalization is removed with it.
+
+## Every filing declares one of two things
+
+- **`build_ready: true`** — complete enough to build; enters the ready lane for auto-pickup. Required for any complete defect found during other work, so it is claimable next cycle with no human flipping status.
+- **`human_gate: "<why a human must judge this first>"`** — deliberately held outside the queue. The writer stamps a visible line plus `<!-- [lisa-human-gate] reason=<short-slug> -->` so the hold is auditable.
+
+Filed, not ready, and no `human_gate` is the **incomplete handoff** case — writers reject it and name both ways to resolve it. `build_ready: false` with no reason is the same omission with a value attached. `build_ready` stays subordinate to `leaf-only-lifecycle`: a container is never build-ready and needs no gate.
+
+## The named exception
+
+`lisa-exploratory-qa` files findings not-ready **by design** — its findings are candidate defects whose product significance a human should judge. It is the named human-gate exception, not drift: it pairs `ready=false` with an explicit `human_gate` reason. The sibling `e2e-coverage-gaps` skills are the contrast (a missing test is not a product question, so they file build-ready).
+
+`lisa-repair-intake` sweeps for open items that are neither in the ready role nor marked `[lisa-human-gate]`, and surfaces them rather than promoting them.
+
+Full contract (the per-vendor before/after table, marker format, and recovery sweep): [reference/ready-role-filing.md](../reference/ready-role-filing.md).

package/plugins/lisa-copilot/rules/reference/automation-runbook-contract.md

@@ -159,7 +159,14 @@ fleet verdict.
 
 A loop that cannot proceed escalates by filing a tracker item (through `lisa-tracker-write`, per
 `tracked-work` and `integration-access-layer`) labeled **`status:blocked`** and **`human-needed`**,
-containing exactly these fields:
+containing exactly these fields.
+
+Every escalation is a **declared human gate** under `ready-role-filing`: it passes
+`human_gate: "<the smallest unresolved choice>"` so the writer stamps the auditable
+`[lisa-human-gate]` marker. An escalation is precisely a filing whose readiness a human owns, so
+omitting the flag and relying on a tracker default would make a deliberate gate indistinguishable
+from the accidental non-ready filing that rule exists to catch.
+
 
 | Field | Content |
 |---|---|