@codyswann/lisa 2.353.0 → 3.1.0

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

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

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

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

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

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

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

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

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