@codyswann/lisa 3.4.0 → 3.5.0

package/plugins/lisa/.codex-plugin/skills/lisa-posthog-access/SKILL.md

@@ -40,15 +40,38 @@ works interactively and headlessly — which is why it leads. The REST tier uses
 
 ```bash
 POSTHOG_HOST=${POSTHOG_HOST:-https://app.posthog.com}
+
+# Resolve the key through the chokepoint before giving up on the environment.
+# `$POSTHOG_PERSONAL_API_KEY` is the documented fallback, not the only rung:
+# without this, a project that keeps its credentials in Bitwarden, Doppler, or
+# AWS has no tier 1 path at all and silently resolves through the interactive
+# MCP — the exact divergence `credential-substrate-precedence` exists to remove.
+read_posthog_key() {
+  [ -n "${POSTHOG_PERSONAL_API_KEY:-}" ] && { echo "$POSTHOG_PERSONAL_API_KEY"; return; }
+  local resolver
+  for resolver in .claude/skills/lisa-secrets-access/scripts/resolve-secret.mjs \
+                  .agents/skills/lisa-secrets-access/scripts/resolve-secret.mjs; do
+    if [ -f "$resolver" ]; then
+      local via_lisa
+      via_lisa=$(node "$resolver" get POSTHOG_PERSONAL_API_KEY 2>/dev/null) \
+        && [ -n "$via_lisa" ] && { echo "$via_lisa"; return; }
+      break
+    fi
+  done
+  return 1
+}
+
 posthog_api() {
   local path="$1"
   local method="${2:-GET}"
   local body="${3:-}"
-  [ -n "$POSTHOG_PERSONAL_API_KEY" ] || {
-    echo "Error: POSTHOG_PERSONAL_API_KEY is not set." >&2
+  local key
+  key=$(read_posthog_key) || {
+    echo "Error: no PostHog key. Set POSTHOG_PERSONAL_API_KEY, or store it as" >&2
+    echo "POSTHOG_PERSONAL_API_KEY in this project's secrets provider." >&2
     return 1
   }
-  local args=(-sS -X "$method" -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY")
+  local args=(-sS -X "$method" -H "Authorization: Bearer $key")
   [ -n "$body" ] && args+=(-H "Content-Type: application/json" --data-binary "$body")
   curl "${args[@]}" "${POSTHOG_HOST%/}/api${path}"
 }
@@ -60,11 +83,25 @@ If neither tier works, fail with:
 Error: no PostHog access substrate available. Authenticate the PostHog MCP or set POSTHOG_PERSONAL_API_KEY.
 ```
 
+## Mutation boundary
+
+Every operation in the Invocation Contract is **read-only** — analytics
+retrieval. `query` is an HTTP POST, but it reads: it submits a query body and
+changes no PostHog state. So the `credential-substrate-precedence` guarded
+fallback for mutating operations (write, read back, assert the tenant from the
+response, roll back on mismatch) is not engaged here, and a failed tier is
+simply skipped. Adding a genuinely mutating operation — creating an insight,
+editing a feature flag — pulls that protocol in: a write of unknown outcome MUST
+reconcile by read-back before any retry.
+
 ## Invariants
 
 - 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.
+- The key is resolved through `lisa-secrets-access`, with the bare
+  `POSTHOG_PERSONAL_API_KEY` environment variable as the documented fallback.
+  Never read a second credential store directly.
 - `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/.codex-plugin/skills/lisa-sentry-access/SKILL.md

@@ -39,28 +39,69 @@ 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
+# Resolve the token through the chokepoint before giving up on the environment.
+# `$SENTRY_AUTH_TOKEN` is the documented fallback, not the only rung: without
+# this, a project that keeps its credentials in Bitwarden, Doppler, or AWS has
+# no tier 1 path at all and silently resolves through the interactive MCP —
+# the exact divergence `credential-substrate-precedence` exists to remove.
+# Mirrors `linear-access`, `atlassian-access`, and `notion-access`.
+read_sentry_token() {
+  [ -n "${SENTRY_AUTH_TOKEN:-}" ] && { echo "$SENTRY_AUTH_TOKEN"; return; }
+  local resolver
+  for resolver in .claude/skills/lisa-secrets-access/scripts/resolve-secret.mjs \
+                  .agents/skills/lisa-secrets-access/scripts/resolve-secret.mjs; do
+    if [ -f "$resolver" ]; then
+      local via_lisa
+      via_lisa=$(node "$resolver" get SENTRY_AUTH_TOKEN 2>/dev/null) \
+        && [ -n "$via_lisa" ] && { echo "$via_lisa"; return; }
+      break
+    fi
+  done
+  return 1
+}
+
 sentry_api() {
   local path="$1"
-  [ -n "$SENTRY_AUTH_TOKEN" ] || {
-    echo "Error: SENTRY_AUTH_TOKEN is not set." >&2
+  local token
+  token=$(read_sentry_token) || {
+    echo "Error: no Sentry auth token. Set SENTRY_AUTH_TOKEN, or store it as" >&2
+    echo "SENTRY_AUTH_TOKEN in this project's secrets provider." >&2
     return 1
   }
   curl -sS "https://sentry.io/api/0${path}" \
-    -H "Authorization: Bearer $SENTRY_AUTH_TOKEN"
+    -H "Authorization: Bearer $token"
 }
 ```
 
+Tier 1a authenticates `sentry-cli` from the **same resolved token**
+(`SENTRY_AUTH_TOKEN=$(read_sentry_token) sentry-cli …`) — never from a second
+credential store, and never from an interactive `sentry-cli login` keychain.
+
 If neither tier works, fail with:
 
 ```text
 Error: no Sentry access substrate available. Authenticate Sentry MCP/CLI or set SENTRY_AUTH_TOKEN.
 ```
 
+## Mutation boundary
+
+Every operation in the Invocation Contract is **read-only** — issue, event, and
+release retrieval. So the `credential-substrate-precedence` guarded fallback for
+mutating operations (write, read back, assert the tenant from the response, roll
+back on mismatch) is not engaged here, and a failed tier is simply skipped. Any
+future operation that mutates Sentry state — resolving an issue, editing a
+release — is a write and MUST reconcile by read-back under that protocol before
+any retry; do not add one to the contract without it.
+
 ## Invariants
 
 - 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.
+- The token is resolved through `lisa-secrets-access`, with the bare
+  `SENTRY_AUTH_TOKEN` environment variable as the documented fallback. Never read
+  a second credential store (OS keychain, `~/.sentryclirc` token) directly — the
+  one-store rule lives at the chokepoint.
 - 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/.codex-plugin/skills/lisa-sonarcloud-access/SKILL.md

@@ -34,6 +34,49 @@ SonarQube Cloud org. Do **not** substitute the raw MCP-image names
 running the Docker image directly, and the `sonar` CLI ignores them (auth exits
 non-zero). The CI scan gate's `SONAR_TOKEN` is a third, separate name.
 
+### Where those variables come from
+
+The `sonar` CLI reads them **from the environment only** — it has no provider
+integration of its own — so on a surface that deliberately materializes nothing
+to disk the credential can be provisioned and unreachable at the same time.
+Resolve it through `lisa-secrets-access` and export it into the launching
+process, exactly as the shared `sonar-secrets.sh` hook already does. The bare
+`$SONARQUBE_CLI_TOKEN` in the environment is the documented **fallback** rung,
+not the only one:
+
+```bash
+# Preferred: the one sanctioned reader. Without this rung a project keeping its
+# credentials in Bitwarden, Doppler, or AWS cannot authenticate the MCP at all,
+# and Sonar access degrades to "run `sonar auth login` in a browser" — dead in
+# cron, CI, and cloud sessions. See `credential-substrate-precedence`.
+read_sonar_secret() {
+  local name="$1"
+  [ -n "${!name:-}" ] && { echo "${!name}"; return; }
+  local resolver
+  for resolver in .claude/skills/lisa-secrets-access/scripts/resolve-secret.mjs \
+                  .agents/skills/lisa-secrets-access/scripts/resolve-secret.mjs; do
+    if [ -f "$resolver" ]; then
+      local via_lisa
+      via_lisa=$(node "$resolver" get "$name" 2>/dev/null) \
+        && [ -n "$via_lisa" ] && { echo "$via_lisa"; return; }
+      break
+    fi
+  done
+  return 1
+}
+
+# Exported into this process only. Writing it anywhere durable would create a
+# second live copy of a credential whose single store is the provider.
+SONARQUBE_CLI_TOKEN=$(read_sonar_secret SONARQUBE_CLI_TOKEN) && export SONARQUBE_CLI_TOKEN
+SONARQUBE_CLI_ORG=$(read_sonar_secret SONARQUBE_CLI_ORG) && export SONARQUBE_CLI_ORG
+```
+
+`sonar-secrets.sh` runs the same resolution with a longer search path (it also
+probes `.codex/skills/…` and `node_modules/@codyswann/lisa/plugins/lisa/…`,
+because a hook fires in checkouts that never installed an agent plugin) and with
+a timeout, because it sits in front of every prompt. Use its search order
+verbatim when this skill runs inside a hook.
+
 Wiring is performed once by `/lisa:setup:sonar` (which drives `sonar integrate
 <agent>`); this access layer assumes the MCP is already wired. This is distinct
 from the CI `SONAR_TOKEN` secret that authenticates the SonarCloud scan job in
@@ -79,9 +122,22 @@ Pass the project key through the tool's `projectKey` argument (or rely on a
 server-configured `SONARQUBE_PROJECT_KEY`); pass `branch` / `pullRequest` where the
 tool accepts them.
 
+## Mutation boundary
+
+Every operation in the map above is **read-only** — quality, coverage, and
+security data. So the `credential-substrate-precedence` guarded fallback for
+mutating operations (write, read back, assert the tenant from the response, roll
+back on mismatch) is not engaged here; with one substrate there is nothing to
+fall back to in any case. A future operation that mutates Sonar state — marking
+a hotspot safe, changing an issue's status — is a write and MUST reconcile by
+read-back before any retry.
+
 ## Invariants
 
 - The official SonarQube MCP is the only substrate; there is no REST fallback.
+- `SONARQUBE_CLI_*` values are resolved through `lisa-secrets-access` and
+  exported in-process, with the bare environment variables as the documented
+  fallback. Never write them to a dotfile or a `.env` on a local surface.
 - Auth is env-var only (`SONARQUBE_CLI_TOKEN` [+ `SONARQUBE_CLI_ORG` | `SONARQUBE_CLI_SERVER`]);
   never the interactive `sonar auth login` keychain flow inside a factory.
 - Sonar host access requires the host (`sonarcloud.io`, `sonarqube.us`, or the

package/plugins/lisa/.codex-plugin/skills/lisa-track/SKILL.md

@@ -47,7 +47,7 @@ This is intentionally conservative: ambiguity creates one explicit work item ins
 2. Persist only the canonical reference in worktree-local machine state:
 
    ```bash
-   node scripts/lisa-work-item.mjs bind <canonical-ref>
+   node scripts/lisa-work-item.mjs link <canonical-ref>
    ```
 
 3. Read the binding back through `node scripts/lisa-work-item.mjs current` and require it to equal the canonical reference. If binding fails, stop before durable project work.

package/plugins/lisa/hooks/block-no-verify.agy.sh

@@ -102,16 +102,65 @@ def disables_verification(token):
         and NO_VERIFY.startswith(token)
     )
 
+# The only relocations that keep a repo's own hooks in play. Anything else —
+# including "" and /dev/null, which are simply the two most obvious members of
+# the blocked set rather than special cases — is refused.
+PERMITTED_HOOKS_PATHS = {".husky", ".githooks"}
+
+
+def is_permitted_hooks_path(value):
+    """Whether a core.hooksPath value relocates hooks rather than disabling them.
+
+    Args:
+        value: The raw core.hooksPath value as it appeared on the command line.
+
+    Returns:
+        True if the path is an established in-repo hooks directory.
+    """
+    cleaned = value.strip().strip("'\"")
+    if cleaned.startswith("./"):
+        cleaned = cleaned[2:]
+    return cleaned.rstrip("/") in PERMITTED_HOOKS_PATHS
+
+
 for i, token in enumerate(normalized_tokens):
     if disables_verification(token):
         sys.exit(1)
     if token == "HUSKY=0" or token.startswith("HUSKY_SKIP_HOOKS="):
         sys.exit(1)
-    if token.startswith("core.hooksPath="):
-        value = token.split("=", 1)[1]
-        if value in ("", "/dev/null"):
+    # Allowlist the destinations, do not denylist the disabling ones: hooks are
+    # disabled just as completely by any directory that happens to contain none
+    # (`-c core.hooksPath=/tmp/empty`), so the set that DISABLES hooks is
+    # unbounded while the set that legitimately relocates them is tiny. Matched
+    # case-insensitively because git config names are.
+    lowered = token.lower()
+    if lowered.startswith("core.hookspath="):
+        if not is_permitted_hooks_path(token.split("=", 1)[1]):
+            sys.exit(1)
+    if lowered == "core.hookspath" and i + 1 < len(normalized_tokens):
+        if not is_permitted_hooks_path(normalized_tokens[i + 1]):
+            sys.exit(1)
+    # `--config-env=core.hooksPath=SOMEVAR` reads the path out of the named env
+    # var, so it is not in the command at all and cannot be allowlisted.
+    if lowered.startswith("--config-env="):
+        spec = token.split("=", 1)[1]
+        if spec.split("=", 1)[0].strip().lower() == "core.hookspath":
+            sys.exit(1)
+    # git also accepts `--config-env <name>=<envvar>` as two tokens. Guarding
+    # only the `=` spelling let the trailing `core.hooksPath=.husky` fall
+    # through to the allowlist above, which reads `.husky` as a path — but here
+    # it names an ENVIRONMENT VARIABLE, which can hold /dev/null. Checked at the
+    # `--config-env` token, which the loop reaches first.
+    if lowered == "--config-env" and i + 1 < len(normalized_tokens):
+        spec = normalized_tokens[i + 1]
+        if spec.split("=", 1)[0].strip().strip("'\"").lower() == "core.hookspath":
             sys.exit(1)
-    if token == "core.hooksPath" and i + 1 < len(normalized_tokens) and normalized_tokens[i + 1] in ("", "/dev/null"):
+    # `GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=core.hooksPath
+    # GIT_CONFIG_VALUE_0=/dev/null git ...` sets the same command-scope config
+    # via env-var-style assignments. The index is arbitrary below
+    # GIT_CONFIG_COUNT, so it is matched as `\d+` rather than pinned to 0.
+    key_match = re.match(r"git_config_key_\d+=(.*)$", lowered, re.DOTALL)
+    if key_match and key_match.group(1).strip().strip("'\"") == "core.hookspath":
         sys.exit(1)
 
 sys.exit(0)

package/plugins/lisa/hooks/block-no-verify.sh

@@ -186,6 +186,37 @@ for i, token in enumerate(normalized_tokens):
         spec = token.split("=", 1)[1]
         if spec.split("=", 1)[0].strip().lower() == "core.hookspath":
             sys.exit(1)
+    # git accepts `--config-env <name>=<envvar>` as TWO tokens as well as one,
+    # and guarding only the `=` spelling was worse than missing the separate
+    # form outright: the trailing `core.hooksPath=.husky` then fell through to
+    # the allowlist above, which reads `.husky` as a PATH and permits it. But
+    # here it is an ENVIRONMENT VARIABLE NAME, and `env '.husky=/dev/null' git
+    # --config-env core.hooksPath=.husky` really does resolve hooksPath to
+    # /dev/null. The allowlist was being used as the bypass.
+    #
+    # Checked at the `--config-env` token, which the loop reaches first, so the
+    # refusal happens before the value token can be mistaken for a path.
+    if lowered == "--config-env" and i + 1 < len(normalized_tokens):
+        spec = normalized_tokens[i + 1]
+        if spec.split("=", 1)[0].strip().strip("'\"").lower() == "core.hookspath":
+            sys.exit(1)
+    # `GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=core.hooksPath
+    # GIT_CONFIG_VALUE_0=/dev/null git commit` sets command-scope config the
+    # same way `-c core.hooksPath=...` does — env-var-style assignments ahead of
+    # the invocation instead of a flag — so it disables every hook just as
+    # completely while matching none of the token shapes above. Upstream missed
+    # this until a downstream fork hardened its own copy against it, which is
+    # the one direction a guard must never be caught in.
+    #
+    # The index is matched as `\d+` rather than pinned to 0: git accepts any
+    # index below GIT_CONFIG_COUNT, so a single-index check is evaded by typing
+    # a 1. Refused outright, like --config-env=, because the path lives in a
+    # separate GIT_CONFIG_VALUE_<n> token that can be exported earlier,
+    # reordered, or left out entirely — there is nothing here to allowlist
+    # against.
+    key_match = re.match(r"git_config_key_\d+=(.*)$", lowered, re.DOTALL)
+    if key_match and key_match.group(1).strip().strip("'\"") == "core.hookspath":
+        sys.exit(1)
 
 sys.exit(0)
 PY

package/plugins/lisa/rules/eager/credential-substrate-precedence.md

@@ -20,7 +20,9 @@ scope for that skill's work.
    `lisa-secrets-access`, chosen whenever its bootstrap credential is available **and**
    the resolved substrate identity-matches the configured tenant/workspace/site.
    `lisa-secrets-access` is the single chokepoint — never read an OS keychain a second
-   time.
+   time. The two legacy OS-keychain rungs that remain (`lisa-atlassian-access`,
+   `lisa-notion-access`) are a dated migration ramp with a **removal date of
+   2026-11-01**, not a standing exemption; no new access skill may add one.
 2. **Tier 2 — interactive MCP**, used only when tier 1 is *genuinely* unavailable:
    no bootstrap, no adapter for the operation (per-operation, not per-session), or a
    provider outage. "The MCP happens to be authenticated" and "tier 1 is slower" are

package/plugins/lisa/rules/eager/tracked-work.md

@@ -2,6 +2,6 @@
 
 Before the first durable project mutation (code, tests, config, docs, committed research/plans/findings, commits, or PRs), establish exactly one live tracker leaf through `lisa-track`. Read-only discussion and orientation are exempt only while they produce no durable artifact.
 
-The mandatory order is: live-validate an explicit ref, or conservatively search and create exactly one valid leaf through `lisa-tracker-write` when no unique match exists; idempotently claim it through `lisa-tracker-claim`; then persist and verify the worktree-local binding with `node scripts/lisa-work-item.mjs bind <ref>`. A tracker that answers no, and any claim or binding failure, blocks durable work; a tracker that cannot be reached does not block a commit — the offline checks still run, the skip is loud on stderr, and the required `Work-Item Traceability` check re-runs the live checks with credentials before anything merges.
+The mandatory order is: live-validate an explicit ref, or conservatively search and create exactly one valid leaf through `lisa-tracker-write` when no unique match exists; idempotently claim it through `lisa-tracker-claim`; then persist and verify the worktree-local binding with `node scripts/lisa-work-item.mjs link <ref>`. A tracker that answers no, and any claim or binding failure, blocks durable work; a tracker that cannot be reached does not block a commit — the offline checks still run, the skip is loud on stderr, and the required `Work-Item Traceability` check re-runs the live checks with credentials before anything merges.
 
 Carry that canonical ref through the branch, every ordinary commit's `Work-Item:` trailer, the PR, usage/evidence, and `lisa-tracker-sync`. Hooks and CI never create tickets. Keep the binding through interruptions or blocked outcomes; run `node scripts/lisa-work-item.mjs clear` only after merge/deploy/verification, two-way linkage/evidence, and the tracker item have all reached true terminal completion.

package/plugins/lisa/rules/reference/credential-substrate-precedence.md

@@ -139,6 +139,26 @@ operation, the fallback is guarded — never the normal path:
 A successful pre-flight switch is not sufficient for tenant safety — another process can
 mutate global state between the check and the write.
 
+## Legacy OS-keychain fallback — removal date 2026-11-01
+
+Two access skills (`lisa-atlassian-access`, `lisa-notion-access`) still read an
+OS keychain as a last rung below the chokepoint, because the guided
+`/lisa:setup:atlassian` and `/lisa:setup:notion` flows wrote credentials there
+before `lisa-secrets-access` existed. That rung is a **migration ramp with a
+removal date, not a standing exemption**: it is a second reader of the same
+credential, which is exactly how one credential ends up living in two places and
+drifting, and a keychain entry is machine-local ambient state that no headless
+surface can reach — so a project resting on it has no working tier 1 in cron, CI,
+or a cloud session.
+
+**Both rungs are deleted on 2026-11-01.** Before then, projects still on the
+keychain path move the credential into their configured provider — re-running
+`/lisa:setup:<vendor>` stores it through the chokepoint. After removal, a
+keychain-only project fails loudly with the exact variable named (tier 3), which
+is the intended outcome: it can never silently resolve through a substrate
+authenticated elsewhere. No new access skill may add a keychain rung; a credential
+the chokepoint cannot answer for is a setup gap to fix, not a store to add.
+
 ## Consequences to expect
 
 - **A stale or wrong token now fails identity-match instead of silently succeeding

package/plugins/lisa/rules/reference/tracked-work.md

@@ -9,9 +9,11 @@ Use `lisa-track` as the single entry point:
 1. An explicit ticket is live-read through `lisa-tracker-read` and rejected if it is missing, inaccessible, terminal, a container, outside the configured project, or outside the current repository.
 2. A plain-text request or specification file is searched conservatively within the configured project. Reuse only one uniquely high-confidence matching live leaf. If no unique match exists, create exactly one complete single-repository leaf through `lisa-tracker-write`; never create a thin placeholder or a container.
 3. Idempotently claim the resolved leaf through `lisa-tracker-claim`, which reuses the vendor build-intake claim semantics and post-read verifies the claimed-or-later state.
-4. Before any durable repository work, persist the canonical reference with `node scripts/lisa-work-item.mjs bind <ref>` and verify the worktree-local binding.
+4. Before any durable repository work, persist the canonical reference with `node scripts/lisa-work-item.mjs link <ref>` and verify the worktree-local binding.
 
-The sequence is strict: **live validate/create -> claim -> bind -> durable work**. A tracker answer of no, and any claim or binding failure, blocks the work. A tracker that cannot be reached — `gh` absent, or its credential refused — does not block a commit: the offline checks still run, the skip is loud on stderr, and the required `Work-Item Traceability` check re-runs the live checks with credentials before anything merges. Any other tracker failure still blocks. Tool presence or stale session text is not access.
+`link` is the spelling to use. `bind` is accepted as a permanent alias for the identical operation, but some agent harnesses — Claude Code's worktree isolation among them — refuse any command line containing the bare token `bind`, because it names a shell builtin that evaluates a string. Inside an isolated worktree that refusal makes the `bind` spelling unrunnable, so reach for `link` and never work around a blocked binding by hand-writing `Work-Item:` trailers.
+
+The sequence is strict: **live validate/create -> claim -> link -> durable work**. A tracker answer of no, and any claim or binding failure, blocks the work. A tracker that cannot be reached — `gh` absent, or its credential refused — does not block a commit: the offline checks still run, the skip is loud on stderr, and the required `Work-Item Traceability` check re-runs the live checks with credentials before anything merges. Any other tracker failure still blocks. Tool presence or stale session text is not access.
 
 ## One canonical identity
 

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

@@ -69,6 +69,13 @@ read_atlassian_token() {
   # Legacy fallback: the OS keychain written by the guided /lisa:setup:atlassian
   # flow, for projects that have not adopted a credentials provider. Reached only
   # when the chokepoint is absent or has no entry.
+  #
+  # This rung is REMOVED ON 2026-11-01 — a dated migration ramp, not a standing
+  # exemption (see credential-substrate-precedence, "Legacy OS-keychain fallback
+  # — removal date"). A keychain entry is machine-local ambient state no headless
+  # surface can reach, so a project resting on it has no working tier 1 in cron,
+  # CI, or a cloud session. Re-run /lisa:setup:atlassian before that date to
+  # store ATLASSIAN_API_TOKEN through the chokepoint instead.
   case "$(uname -s)" in
     Darwin)  security find-generic-password -s lisa-atlassian -a "$email" -w 2>/dev/null ;;
     Linux)   command -v secret-tool >/dev/null && secret-tool lookup service lisa-atlassian account "$email" 2>/dev/null ;;

package/plugins/lisa/skills/lisa-implement/SKILL.md

@@ -64,7 +64,7 @@ The input-resolver invokes `lisa-track $ARGUMENTS` and owns its complete resolve
 - **Bind before durable work:** only after the verified claim, run:
 
   ```bash
-  node scripts/lisa-work-item.mjs bind <canonical-ref>
+  node scripts/lisa-work-item.mjs link <canonical-ref>
   ```
 
   Require a successful readback of that worktree-local binding. On detached HEAD, `branch: null` is the expected pending binding; after branch creation the mandatory `attach-branch` step below must replace it before any commit. Tracker or binding failure stops the flow; never continue untracked.

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

@@ -39,20 +39,55 @@ headlessly — which is why it leads. The CLI tier uses:
 ```bash
 curl -fsSL https://native.jam.dev/install | bash
 export PATH="$HOME/.local/bin:$PATH"
-printf '%s' "$JAM_PAT" | jam auth login --token
+
+# Resolve the PAT through the chokepoint before giving up on the environment.
+# `$JAM_PAT` is the documented fallback, not the only rung: without this, a
+# project that keeps its credentials in Bitwarden, Doppler, or AWS has no tier 1
+# path at all and silently resolves through the interactive MCP — the exact
+# divergence `credential-substrate-precedence` exists to remove.
+read_jam_pat() {
+  [ -n "${JAM_PAT:-}" ] && { echo "$JAM_PAT"; return; }
+  local resolver
+  for resolver in .claude/skills/lisa-secrets-access/scripts/resolve-secret.mjs \
+                  .agents/skills/lisa-secrets-access/scripts/resolve-secret.mjs; do
+    if [ -f "$resolver" ]; then
+      local via_lisa
+      via_lisa=$(node "$resolver" get JAM_PAT 2>/dev/null) \
+        && [ -n "$via_lisa" ] && { echo "$via_lisa"; return; }
+      break
+    fi
+  done
+  return 1
+}
+
+# Piped, never written to disk and never passed as an argv token: a PAT on a
+# command line is readable from the process table by every user on the host.
+read_jam_pat | jam auth login --token
 jam skills install
 ```
 
 If neither tier works, fail with:
 
 ```text
-Error: no Jam access substrate available. Authenticate the Jam MCP or set JAM_PAT.
+Error: no Jam access substrate available. Authenticate the Jam MCP, set JAM_PAT, or store JAM_PAT in this project's secrets provider.
 ```
 
+## Mutation boundary
+
+Every operation in the Invocation Contract is **read-only** — fetching a trace,
+a recording, or a bug report. So the `credential-substrate-precedence` guarded
+fallback for mutating operations (write, read back, assert the tenant from the
+response, roll back on mismatch) is not engaged here, and a failed tier is
+simply skipped. A future operation that mutates Jam state — commenting on or
+deleting a Jam — is a write and MUST reconcile by read-back before any retry.
+
 ## Invariants
 
 - 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.
+- The PAT is resolved through `lisa-secrets-access`, with the bare `JAM_PAT`
+  environment variable as the documented fallback. Never read a second
+  credential store directly.
 - Never commit a Jam PAT into `.mcp.json` or any generated setup artifact.
 - Headless Jam access requires `native.jam.dev` for the installer and
   `api.jam.dev` for CLI/API calls in any custom remote network allowlist.

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

@@ -70,6 +70,13 @@ read_notion_token() {
   # Legacy fallback: the OS keychain written by the guided /lisa:setup:notion
   # flow, for projects that have not adopted a credentials provider. Reached only
   # when the chokepoint is absent or has no entry.
+  #
+  # This rung is REMOVED ON 2026-11-01 — a dated migration ramp, not a standing
+  # exemption (see credential-substrate-precedence, "Legacy OS-keychain fallback
+  # — removal date"). A keychain entry is machine-local ambient state no headless
+  # surface can reach, so a project resting on it has no working tier 1 in cron,
+  # CI, or a cloud session. Re-run /lisa:setup:notion before that date to store
+  # NOTION_API_TOKEN through the chokepoint instead.
   case "$(uname -s)" in
     Darwin)  security find-generic-password -s lisa-notion -a "$workspace" -w 2>/dev/null ;;
     Linux)   command -v secret-tool >/dev/null && \

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

@@ -40,15 +40,38 @@ works interactively and headlessly — which is why it leads. The REST tier uses
 
 ```bash
 POSTHOG_HOST=${POSTHOG_HOST:-https://app.posthog.com}
+
+# Resolve the key through the chokepoint before giving up on the environment.
+# `$POSTHOG_PERSONAL_API_KEY` is the documented fallback, not the only rung:
+# without this, a project that keeps its credentials in Bitwarden, Doppler, or
+# AWS has no tier 1 path at all and silently resolves through the interactive
+# MCP — the exact divergence `credential-substrate-precedence` exists to remove.
+read_posthog_key() {
+  [ -n "${POSTHOG_PERSONAL_API_KEY:-}" ] && { echo "$POSTHOG_PERSONAL_API_KEY"; return; }
+  local resolver
+  for resolver in .claude/skills/lisa-secrets-access/scripts/resolve-secret.mjs \
+                  .agents/skills/lisa-secrets-access/scripts/resolve-secret.mjs; do
+    if [ -f "$resolver" ]; then
+      local via_lisa
+      via_lisa=$(node "$resolver" get POSTHOG_PERSONAL_API_KEY 2>/dev/null) \
+        && [ -n "$via_lisa" ] && { echo "$via_lisa"; return; }
+      break
+    fi
+  done
+  return 1
+}
+
 posthog_api() {
   local path="$1"
   local method="${2:-GET}"
   local body="${3:-}"
-  [ -n "$POSTHOG_PERSONAL_API_KEY" ] || {
-    echo "Error: POSTHOG_PERSONAL_API_KEY is not set." >&2
+  local key
+  key=$(read_posthog_key) || {
+    echo "Error: no PostHog key. Set POSTHOG_PERSONAL_API_KEY, or store it as" >&2
+    echo "POSTHOG_PERSONAL_API_KEY in this project's secrets provider." >&2
     return 1
   }
-  local args=(-sS -X "$method" -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY")
+  local args=(-sS -X "$method" -H "Authorization: Bearer $key")
   [ -n "$body" ] && args+=(-H "Content-Type: application/json" --data-binary "$body")
   curl "${args[@]}" "${POSTHOG_HOST%/}/api${path}"
 }
@@ -60,11 +83,25 @@ If neither tier works, fail with:
 Error: no PostHog access substrate available. Authenticate the PostHog MCP or set POSTHOG_PERSONAL_API_KEY.
 ```
 
+## Mutation boundary
+
+Every operation in the Invocation Contract is **read-only** — analytics
+retrieval. `query` is an HTTP POST, but it reads: it submits a query body and
+changes no PostHog state. So the `credential-substrate-precedence` guarded
+fallback for mutating operations (write, read back, assert the tenant from the
+response, roll back on mismatch) is not engaged here, and a failed tier is
+simply skipped. Adding a genuinely mutating operation — creating an insight,
+editing a feature flag — pulls that protocol in: a write of unknown outcome MUST
+reconcile by read-back before any retry.
+
 ## Invariants
 
 - 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.
+- The key is resolved through `lisa-secrets-access`, with the bare
+  `POSTHOG_PERSONAL_API_KEY` environment variable as the documented fallback.
+  Never read a second credential store directly.
 - `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-sentry-access/SKILL.md

@@ -39,28 +39,69 @@ 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
+# Resolve the token through the chokepoint before giving up on the environment.
+# `$SENTRY_AUTH_TOKEN` is the documented fallback, not the only rung: without
+# this, a project that keeps its credentials in Bitwarden, Doppler, or AWS has
+# no tier 1 path at all and silently resolves through the interactive MCP —
+# the exact divergence `credential-substrate-precedence` exists to remove.
+# Mirrors `linear-access`, `atlassian-access`, and `notion-access`.
+read_sentry_token() {
+  [ -n "${SENTRY_AUTH_TOKEN:-}" ] && { echo "$SENTRY_AUTH_TOKEN"; return; }
+  local resolver
+  for resolver in .claude/skills/lisa-secrets-access/scripts/resolve-secret.mjs \
+                  .agents/skills/lisa-secrets-access/scripts/resolve-secret.mjs; do
+    if [ -f "$resolver" ]; then
+      local via_lisa
+      via_lisa=$(node "$resolver" get SENTRY_AUTH_TOKEN 2>/dev/null) \
+        && [ -n "$via_lisa" ] && { echo "$via_lisa"; return; }
+      break
+    fi
+  done
+  return 1
+}
+
 sentry_api() {
   local path="$1"
-  [ -n "$SENTRY_AUTH_TOKEN" ] || {
-    echo "Error: SENTRY_AUTH_TOKEN is not set." >&2
+  local token
+  token=$(read_sentry_token) || {
+    echo "Error: no Sentry auth token. Set SENTRY_AUTH_TOKEN, or store it as" >&2
+    echo "SENTRY_AUTH_TOKEN in this project's secrets provider." >&2
     return 1
   }
   curl -sS "https://sentry.io/api/0${path}" \
-    -H "Authorization: Bearer $SENTRY_AUTH_TOKEN"
+    -H "Authorization: Bearer $token"
 }
 ```
 
+Tier 1a authenticates `sentry-cli` from the **same resolved token**
+(`SENTRY_AUTH_TOKEN=$(read_sentry_token) sentry-cli …`) — never from a second
+credential store, and never from an interactive `sentry-cli login` keychain.
+
 If neither tier works, fail with:
 
 ```text
 Error: no Sentry access substrate available. Authenticate Sentry MCP/CLI or set SENTRY_AUTH_TOKEN.
 ```
 
+## Mutation boundary
+
+Every operation in the Invocation Contract is **read-only** — issue, event, and
+release retrieval. So the `credential-substrate-precedence` guarded fallback for
+mutating operations (write, read back, assert the tenant from the response, roll
+back on mismatch) is not engaged here, and a failed tier is simply skipped. Any
+future operation that mutates Sentry state — resolving an issue, editing a
+release — is a write and MUST reconcile by read-back under that protocol before
+any retry; do not add one to the contract without it.
+
 ## Invariants
 
 - 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.
+- The token is resolved through `lisa-secrets-access`, with the bare
+  `SENTRY_AUTH_TOKEN` environment variable as the documented fallback. Never read
+  a second credential store (OS keychain, `~/.sentryclirc` token) directly — the
+  one-store rule lives at the chokepoint.
 - 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.