@codyswann/lisa 2.353.0 → 3.1.0

package/plugins/lisa/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/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/skills/lisa-linear-access/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lisa-linear-access
-description: "Vendor-neutral access layer for Linear. Linear skills MUST delegate through this skill rather than calling Linear MCP tools or Linear GraphQL directly. Resolves Linear MCP first when authenticated, then falls back to LINEAR_API_KEY + Linear GraphQL in headless environments."
+description: "Vendor-neutral access layer for Linear. Linear skills MUST delegate through this skill rather than calling Linear MCP tools or Linear GraphQL directly. Per the credential-substrate-precedence contract, resolves LINEAR_API_KEY + Linear GraphQL first — ahead of the Linear MCP — whenever the key is present and identity-matches the configured workspace/team, and falls back to the Linear MCP when the token path is unavailable. Identity-match is mandatory on both substrates."
 allowed-tools: ["Bash", "Read", "Skill"]
 ---
 
@@ -46,15 +46,27 @@ WORKSPACE=$(jq -r '.linear.workspace // empty' .lisa.config.json 2>/dev/null)
 TEAM_KEY=$(jq -r '.linear.teamKey // empty' .lisa.config.json 2>/dev/null)
 ```
 
-Probe in order:
-
-1. Linear MCP, if `mcp__linear-server__list_teams` is available and can list the
-   configured workspace/team.
-2. `LINEAR_API_KEY` with Linear GraphQL (`https://api.linear.app/graphql`).
+Probe in order — the ordering is the shared `credential-substrate-precedence`
+contract, not a Linear-local choice. The first tier that is ready **and**
+identity-matches wins; a substrate authenticated against a different
+workspace/team is **skipped, never used**, at either tier.
+
+1. **Tier 1 — configured-provider substrate: `LINEAR_API_KEY` with Linear GraphQL**
+   (`https://api.linear.app/graphql`), resolved through `lisa-secrets-access`.
+   Identity-match by querying `viewer { organization { urlKey } }` (plus
+   `teams` when `linear.teamKey` is configured) and comparing to
+   `.lisa.config.json`. A key that resolves to a different organization fails the
+   gate — warn, skip the tier, and continue down the ladder.
+2. **Tier 2 — interactive MCP fallback: Linear MCP**, if
+   `mcp__linear-server__list_teams` is available and can list the configured
+   workspace/team (that listing *is* the identity match). Used when tier 1 is
+   genuinely unavailable: no `LINEAR_API_KEY`, no GraphQL adapter for the
+   operation, or a Linear API outage.
 
 The Linear GraphQL docs support personal API keys for scripts and authenticate
-with an `Authorization: <API_KEY>` header. Treat `LINEAR_API_KEY` as the
-headless substrate. If neither tier works, fail with:
+with an `Authorization: <API_KEY>` header, so the token tier works identically on
+a developer laptop, in CI, in a cloud routine, and in a subagent — which is why it
+leads. If neither tier works, fail with:
 
 ```text
 Error: no Linear access substrate available. Authenticate the Linear MCP or set LINEAR_API_KEY.
@@ -204,8 +216,16 @@ query($id:String!){
 
 ## Invariants
 
-- MCP is preferred when it is present and already authenticated.
-- GraphQL fallback runs only when `LINEAR_API_KEY` is present.
-- Missing MCP plus missing token is a hard failure naming `LINEAR_API_KEY`.
+- Tier order is the shared `credential-substrate-precedence` contract:
+  `LINEAR_API_KEY` + GraphQL first when present and identity-matched, then the
+  Linear MCP. Do not restate or locally override the ordering here.
+- The Linear MCP remains a first-class **fallback**, not a removed tier: it stays
+  the substrate whenever `LINEAR_API_KEY` is absent, the operation has no GraphQL
+  adapter, or the token path is failing.
+- Identity-match is mandatory on **both** substrates. A substrate authenticated
+  against a different Linear organization or team is skipped, never used — that
+  includes a present-but-wrong `LINEAR_API_KEY`, which fails the gate loudly
+  instead of silently deferring to an authenticated MCP.
+- Missing token plus missing MCP is a hard failure naming `LINEAR_API_KEY`.
 - Mutations send only the fields being changed, matching existing Linear skill
   guidance that `save_*` style updates should not clobber unrelated fields.

package/plugins/lisa/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/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/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/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/skills/lisa-notion-access/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lisa-notion-access
-description: "Vendor-neutral access layer for Notion. Every notion-* skill MUST delegate through this skill rather than invoking the Notion REST API or any Notion MCP directly. Resolves a substrate per operation in this order: (1) Notion MCP if authenticated and the configured prdDatabaseId is fetchable through it (identity-match), (2) curl + Bearer auth + internal-integration token. Verifies the active connection matches `.lisa.config.json` before every operation — substrates authenticated as a different Notion workspace are skipped, not used."
+description: "Vendor-neutral access layer for Notion. Every notion-* skill MUST delegate through this skill rather than invoking the Notion REST API or any Notion MCP directly. Per the credential-substrate-precedence contract, resolves a substrate per operation in this order: (1) curl + Bearer auth + internal-integration token when the token is present and identity-matches the configured workspace, (2) Notion MCP as fallback if authenticated and the configured prdDatabaseId is fetchable through it. Verifies the active connection matches `.lisa.config.json` before every operation — substrates authenticated as a different Notion workspace are skipped, not used."
 allowed-tools: ["Bash", "Read", "Skill"]
 ---
 
@@ -38,20 +38,15 @@ DB_ID=$(jq -r '.notion.prdDatabaseId // empty' .lisa.config.json)
 [ -z "$DB_ID" ]     && { echo "Error: notion.prdDatabaseId not set. Run /lisa:setup:notion." >&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 workspace are skipped, not used.
+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, the interactive MCP is the fallback — not a Notion-local choice. Identity-match is verified before any operation; substrates authenticated as a different workspace are skipped, not used, at **every** tier.
 
 ```bash
 substrate=""
 
-# Tier 1: Notion MCP (identity-matched by fetching the configured PRD database)
-# Pseudo-code; actual call is the MCP tool invocation.
-# Try to fetch DB_ID through the MCP. Success → MCP is authed to the right workspace.
-# 404 / object_not_found → MCP is authed elsewhere (or unauthenticated). Skip.
-if mcp_notion_can_fetch_database "$DB_ID"; then
-  substrate="mcp"
-fi
-
-# Tier 2: curl + API token
+# Tier 1: curl + API token — the configured-provider substrate, resolved through
+# lisa-secrets-access. Leads because it is identical on a laptop, in CI, in a cloud
+# routine, and in a subagent, and because its workspace binding travels with the
+# request instead of coming from ambient browser-session state.
 read_notion_token() {
   local workspace="$1"
   [ -n "$NOTION_API_TOKEN" ] && { echo "$NOTION_API_TOKEN"; return; }
@@ -120,12 +115,28 @@ if [ -n "$TOKEN" ]; then
               "https://api.notion.com/v1/users/me")
   me_workspace=$(echo "$me" | jq -r '.bot.workspace_name // .bot.workspace_id // empty')
   if [ -n "$me_workspace" ] && [ "$me_workspace" = "$WORKSPACE" ]; then
-    : ${substrate:=curl}
+    substrate="curl"
   elif [ -n "$me_workspace" ]; then
+    # A present-but-wrong token fails the gate rather than deferring to the MCP.
+    # Silently succeeding through an MCP authenticated elsewhere is the exact bug
+    # the precedence contract exists to surface.
     echo "Warning: Notion token belongs to workspace '$me_workspace' but config declares '$WORKSPACE'. Skipping curl tier." >&2
   fi
 fi
 
+# Tier 2: Notion MCP — first-class fallback, used when tier 1 is genuinely
+# unavailable (no token, no curl adapter for the operation, or Notion API outage).
+# Identity-matched by fetching the configured PRD database.
+# Pseudo-code; actual call is the MCP tool invocation.
+# Try to fetch DB_ID through the MCP. Success → MCP is authed to the right workspace.
+# 404 / object_not_found → MCP is authed elsewhere (or unauthenticated). Skip.
+if mcp_notion_can_fetch_database "$DB_ID"; then
+  : ${substrate:=mcp}
+  # Mark the MCP available even when curl already won tier 1 — the dispatch table
+  # falls through to it for operations curl has no adapter for.
+  mcp_available=true
+fi
+
 # Fail loudly with actionable remediation if nothing works.
 if [ -z "$substrate" ]; then
   # Detect plugin enablement state for the suggestion.
@@ -136,14 +147,19 @@ if [ -z "$substrate" ]; then
   cat >&2 <<EOF
 Error: no Notion access substrate available for workspace '$WORKSPACE'.
 
-Attempted:
-  MCP    — $([ "$plugin_enabled_global" = "true" ] || [ "$plugin_enabled_project" = "true" ] || [ "$plugin_enabled_local" = "true" ] && echo "plugin enabled but not authenticated or cannot fetch configured prdDatabaseId" || echo "plugin not enabled in any settings.json scope")
+Attempted (in credential-substrate-precedence order):
   curl   — no NOTION_API_TOKEN found for $WORKSPACE (env, slug-suffixed env, or keychain) OR token belongs to a different workspace
+  MCP    — $([ "$plugin_enabled_global" = "true" ] || [ "$plugin_enabled_project" = "true" ] || [ "$plugin_enabled_local" = "true" ] && echo "plugin enabled but not authenticated or cannot fetch configured prdDatabaseId" || echo "plugin not enabled in any settings.json scope")
+
+Remediation paths (the first is the contract's primary path):
 
-Remediation paths (pick one):
+1. Provision an internal-integration API token — works headless, in CI, and in
+   multi-workspace setups, and is the substrate this project resolves first.
 
-1. Install the Notion MCP plugin (local scope — per-developer, gitignored).
-   This is the simplest path for single-workspace developers.
+     Run /lisa:setup:notion — guided flow with clipboard-piped keychain store.
+
+2. Install the Notion MCP plugin (local scope — per-developer, gitignored).
+   The supported fallback when no credentials provider is configured.
 
    Run in your terminal:
 
@@ -157,10 +173,6 @@ Remediation paths (pick one):
    Also share the configured prdDatabaseId with the integration via
    the page's '•••' menu → Connections.
 
-2. Provision an internal-integration API token (headless / CI / multi-workspace).
-
-     Run /lisa:setup:notion — guided flow with clipboard-piped keychain store.
-
 EOF
   exit 1
 fi
@@ -225,14 +237,15 @@ exec_op() {
 ## Invariants
 
 - Caller skills never call `curl https://api.notion.com/...` or any `mcp__*notion*` tool directly. They invoke this skill via the Skill tool with an operation name and arguments.
-- Substrate is selected per skill invocation following the tier ladder. The first tier that's available AND identity-matches `notion.workspaceId` wins.
-- The connection-match check is mandatory at every tier. Skipping it (because "the user obviously meant this workspace") is forbidden — silent cross-workspace operations are exactly the multi-account hazard this design exists to prevent.
+- Substrate is selected per skill invocation following the tier ladder defined by the shared `credential-substrate-precedence` contract — internal-integration token first, Notion MCP as fallback. The first tier that's available AND identity-matches `notion.workspaceId` wins. Do not restate or locally override the ordering here.
+- The Notion MCP stays a first-class fallback, not a removed tier: it is the substrate whenever no token is configured, the operation has no curl adapter, or the Notion API is failing.
+- The connection-match check is mandatory at every tier. Skipping it (because "the user obviously meant this workspace") is forbidden — silent cross-workspace operations are exactly the multi-account hazard this design exists to prevent. A present-but-wrong token fails the gate rather than deferring to an MCP authenticated somewhere else.
 - API tokens never mutate. If the configured workspace's token is wrong or missing, fail loudly and tell the user to run `/lisa:setup:notion`.
 - `Notion-Version` is pinned to `2022-06-28` — the version every existing notion-* skill targets. Bumping it is a coordinated change across the access skill and all callers.
 
 ## Headless behavior
 
-In a headless / non-interactive context (no TTY, `CI=true`, or `-p` mode), the MCP tier is unavailable (its OAuth flow needs a browser). The ladder collapses to curl + `NOTION_API_TOKEN`. Same skill code runs identically; only the substrate changes.
+In a headless / non-interactive context (no TTY, `CI=true`, or `-p` mode), the MCP tier is unavailable (its OAuth flow needs a browser) and the ladder collapses to curl + `NOTION_API_TOKEN` — which is already tier 1 interactively. That is the point of the ordering: headless and interactive sessions take the **same primary path**, so a credential problem reproduces on a laptop instead of only in cron (`credential-substrate-precedence`, "headless parity"). Same skill code runs identically; only the availability of the fallback changes.
 
 ## Per-page sharing prerequisite
 

package/plugins/lisa/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/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/skills/lisa-posthog-access/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lisa-posthog-access
-description: "Vendor-neutral access layer for PostHog. PostHog skills and observability rules MUST delegate through this skill rather than calling PostHog MCP tools or REST directly. Resolves PostHog MCP first when available, then falls back to POSTHOG_PERSONAL_API_KEY bearer auth."
+description: "Vendor-neutral access layer for PostHog. PostHog skills and observability rules MUST delegate through this skill rather than calling PostHog MCP tools or REST directly. Per the credential-substrate-precedence contract, resolves POSTHOG_PERSONAL_API_KEY bearer auth first when present and identity-matched to the configured project, then falls back to the PostHog MCP."
 allowed-tools: ["Bash", "Read", "Skill"]
 ---
 
@@ -22,13 +22,21 @@ Return parsed JSON in a `<result>` block.
 
 ## Substrate Selection
 
-Probe in order:
+Probe in order — the ordering is the shared `credential-substrate-precedence`
+contract, not a PostHog-local choice. The first tier that is ready **and**
+identity-matches the configured project is used; a substrate authenticated against
+a different project is skipped, never used.
 
-1. PostHog MCP, if available and authenticated.
-2. `POSTHOG_PERSONAL_API_KEY` bearer token against the configured PostHog host.
+1. **Tier 1 — configured-provider substrate: `POSTHOG_PERSONAL_API_KEY`** bearer
+   token against the configured PostHog host, resolved through
+   `lisa-secrets-access`.
+2. **Tier 2 — interactive MCP fallback: PostHog MCP**, if available and
+   authenticated. Used when tier 1 is genuinely unavailable: no
+   `POSTHOG_PERSONAL_API_KEY`, no REST adapter for the operation, or a PostHog
+   outage.
 
-PostHog documents personal API keys and bearer authentication. The headless REST
-tier uses:
+PostHog documents personal API keys and bearer authentication, and the same key
+works interactively and headlessly — which is why it leads. The REST tier uses:
 
 ```bash
 POSTHOG_HOST=${POSTHOG_HOST:-https://app.posthog.com}
@@ -54,7 +62,9 @@ Error: no PostHog access substrate available. Authenticate the PostHog MCP or se
 
 ## Invariants
 
-- Fallback is gated on `POSTHOG_PERSONAL_API_KEY`.
+- Tier order is `credential-substrate-precedence`: `POSTHOG_PERSONAL_API_KEY`
+  first, the PostHog MCP as a preserved first-class fallback. Identity-match
+  against the configured project is mandatory on every tier.
 - `POSTHOG_HOST` defaults to PostHog Cloud but can point at a self-hosted
   deployment.
 - Consumer skills do not embed PostHog REST paths.

package/plugins/lisa/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/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/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/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/skills/lisa-secrets-access/SKILL.md

@@ -10,6 +10,14 @@ Single chokepoint for reading credentials. Caller skills MUST go through this
 
 The rule this exists to enforce: **a secret lives in exactly one store.** Every local cache is a copy that will eventually drift from its source, and a drifted copy is indistinguishable from a valid one until something fails in production.
 
+This skill is also the chokepoint that feeds **tier 1** of the shared
+`credential-substrate-precedence` contract: every `*-access` skill resolves its
+configured-provider token or CLI credential here, ahead of any interactive MCP. That
+is what makes "provider-first" actionable rather than aspirational — including the
+`tool:` note line below, which declares which CLI a given credential is expected to
+drive. This skill decides *where a credential comes from*; it never decides substrate
+ordering, which is settled once in that contract.
+
 ## Two axes, not one
 
 A **provider** is where secrets live. A **surface** is where the running code lives, and it determines how secrets reach that code. These are independent: the same Bitwarden project serves a laptop, a CI runner, and a remote agent container, but each obtains its values differently.

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

@@ -1,6 +1,6 @@
 ---
 name: lisa-sentry-access
-description: "Vendor-neutral access layer for Sentry. Sentry-oriented skills MUST delegate through this skill rather than calling Sentry MCP tools, sentry-cli, or REST directly. Resolves Sentry MCP/CLI first when available, then falls back to SENTRY_AUTH_TOKEN + Sentry REST API."
+description: "Vendor-neutral access layer for Sentry. Sentry-oriented skills MUST delegate through this skill rather than calling Sentry MCP tools, sentry-cli, or REST directly. Per the credential-substrate-precedence contract, resolves SENTRY_AUTH_TOKEN (REST, or sentry-cli authenticated from the same token) first when present and identity-matched to the configured org/project, then falls back to the Sentry MCP."
 allowed-tools: ["Bash", "Read", "Skill"]
 ---
 
@@ -22,13 +22,21 @@ Return parsed JSON in a `<result>` block.
 
 ## Substrate Selection
 
-Probe in order:
+Probe in order — the ordering is the shared `credential-substrate-precedence`
+contract, not a Sentry-local choice. The first tier that is ready **and**
+identity-matches the configured org/project is used; a substrate authenticated
+against a different org is skipped, never used.
 
-1. Sentry MCP, if available and authenticated.
-2. `sentry-cli`, if installed and authenticated to the requested org/project.
-3. `SENTRY_AUTH_TOKEN` bearer token against Sentry REST.
+1. **Tier 1 — configured-provider substrate: `SENTRY_AUTH_TOKEN`** bearer token
+   against Sentry REST, resolved through `lisa-secrets-access`.
+2. **Tier 1a — `sentry-cli`**, if installed and authenticated to the requested
+   org/project from that same token (the CLI arm of the provider substrate).
+3. **Tier 2 — interactive MCP fallback: Sentry MCP**, if available and
+   authenticated. Used when tier 1 is genuinely unavailable: no
+   `SENTRY_AUTH_TOKEN`, no REST/CLI adapter for the operation, or a Sentry outage.
 
-Sentry documents API auth tokens for REST API calls. The headless REST tier uses:
+Sentry documents API auth tokens for REST API calls, and the same token works
+interactively and headlessly — which is why it leads. The REST tier uses:
 
 ```bash
 sentry_api() {
@@ -50,7 +58,9 @@ Error: no Sentry access substrate available. Authenticate Sentry MCP/CLI or set
 
 ## Invariants
 
-- Fallback is gated on `SENTRY_AUTH_TOKEN`.
+- Tier order is `credential-substrate-precedence`: `SENTRY_AUTH_TOKEN` first, the
+  Sentry MCP as a preserved first-class fallback. Identity-match against the
+  configured org/project is mandatory on every tier.
 - Org/project come from `.sentryclirc`, `.lisa.config.json`, or explicit
   operation args; never infer by searching all accessible orgs.
 - Consumer skills do not embed Sentry REST paths.

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

@@ -15,7 +15,13 @@ this skill owns the tool selection.
 There is exactly one substrate: the **official SonarQube MCP server**, provided by
 the `sonarqube` plugin and launched by the `sonar` CLI (`sonar run mcp`). It
 authenticates headlessly from environment variables — no browser, no OS keychain —
-so it is the same substrate on a developer machine and in a headless cloud routine:
+so it is the same substrate on a developer machine and in a headless cloud routine.
+
+That makes this skill conformant with `credential-substrate-precedence` as a
+single-substrate access layer: this MCP **is** the configured-provider substrate
+(it is token-authenticated, not browser-OAuth), so there is no interactive tier to
+demote and no second REST tier to add. Identity-match against the configured org
+remains mandatory, as on every substrate.
 
 - `SONARQUBE_CLI_TOKEN` — required (Sonar user/analysis token).
 - `SONARQUBE_CLI_ORG` — required for SonarQube Cloud.

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