@codyswann/lisa 2.21.1 → 2.23.1

package/plugins/lisa/rules/repo-scope-split.md

@@ -0,0 +1,41 @@
+# Repo Scope & Work-Time Splitting
+
+Leaf work units are single-repo. A **leaf work unit** is an individually implementable ticket with no child tickets — issue types **Bug, Task, Sub-task, Improvement**. Each must name exactly one repository. **Epic, Story, Spike** are coordination containers and may span repos.
+
+This invariant is enforced at three points: gate **S10** in the `*-validate-*` skills (write time), `task-decomposition` step 1.5 (PRD-decomposition time), and the work-time split procedure below (when an agent picks up an existing ticket to implement it).
+
+## Two splitting strategies, by phase
+
+The strategy depends on whether the tickets exist yet. Do not mix them.
+
+- **Decomposition-time (greenfield — no tickets exist yet).** Use `task-decomposition` step 1.5: create one work unit per repo and group them under a **parent Story** (the cross-repo coordination container). Children are per-repo; the parent stays cross-repo. This is the right shape when you are creating the tickets from a PRD in the first place.
+- **Work-time (a ticket already exists and an agent is about to implement it).** Use the procedure below: keep the original ticket, **narrow it to one repo**, spin off a **sibling** per additional repo, and link them with a dependency. Do **not** invent a new parent Story — re-homing an in-flight ticket's hierarchy is more disruptive than narrowing it. The siblings inherit the original's existing parent (Epic/Story/Project) if it has one.
+
+## Work-time split procedure
+
+When an agent reads an existing leaf work unit at the pre-flight gate (before any code is written) and the work touches more than one repo, it must STOP and split before proceeding. This is an agent-performed fix, not a product question — like auto-transitioning status, auto-splitting a cross-repo work unit is explicitly allowed (S10 is `product_relevant: false`: a cross-repo work unit is a decomposition error the agent owns, not something to bounce to the reporter).
+
+1. **Detect the repos.** Parse the description, acceptance criteria, and technical approach for repo references, and confirm against the actual code surfaces the change requires. If the work fits in one repo, proceed normally — no split.
+2. **Pick the repo the original keeps.** Default: the original retains the **consumer / user-facing repo** (e.g. frontend), because that is usually the ticket a stakeholder is watching and the one whose acceptance criteria describe the user-visible outcome. Each **producer repo** (e.g. backend) becomes a new sibling.
+3. **Create one sibling per additional repo, cloning the original's metadata.** Carry over: summary (re-prefixed `[repo-name]`), the three audience sections, priority, labels/components, parent (Epic/Story/Project) if the original has one, target backend environment, sign-in requirements, and a Validation Journey scoped to that repo. Scope the acceptance criteria to that repo only.
+4. **Link by dependency.** The producer repo **blocks** the consumer repo (`is blocked by` on the consumer / `blocks` on the producer), so execution order is explicit: the producing sibling ships first. When there is no clear producer/consumer direction, use `relates to`.
+5. **Narrow the original.** Edit its summary prefix, its `Repository` section, and its acceptance criteria down to the retained repo only. Remove every cross-repo reference ("and the backend should also…").
+6. **Comment on the original.** Note the split and link each new sibling so the history is auditable.
+7. **Re-validate.** Run `tracker-verify` (which runs S10) against the original and each new sibling. Every one must now PASS single-repo scope. If any still fails, the split was incomplete — fix it before proceeding.
+8. **Proceed in dependency order.** Implement the producer sibling(s) first, then the consumer (the narrowed original), respecting the `blocks` links.
+
+### When to block instead of split
+
+Auto-split only when the split is unambiguous. Fall back to the standard BLOCK + reassign-to-reporter path (see the pre-flight gate in `base-rules`) when:
+
+- The repos touched cannot be determined confidently from the ticket and the code.
+- Splitting would strand stakeholder context that only the reporter can re-scope (e.g. the acceptance criteria describe a single indivisible cross-repo behavior with no clean per-repo boundary).
+- The metadata required to clone (parent, environment, credentials) is itself missing — block on the missing metadata first; do not propagate gaps into the siblings.
+
+## Vendor mechanics
+
+The procedure is vendor-neutral; the create + link + edit mechanics differ:
+
+- **JIRA** — create via `mcp__atlassian__createJiraIssue` (clone fields, set the same epic parent); link via `mcp__atlassian__createIssueLink` with `Blocks` / `is blocked by` (resolve names via `mcp__atlassian__getIssueLinkTypes`); narrow the original via `mcp__atlassian__editJiraIssue`; comment via `mcp__atlassian__addCommentToJiraIssue`. See `jira-write-ticket` Phase 6.
+- **GitHub** — create the sibling issue with the same labels and parent sub-issue; encode the dependency in the body (`Blocked by #<n>` / `Blocks #<n>`) and via the sub-issue/parent graph where used; edit the original's body to narrow scope. See `github-write-issue` Phase 6.
+- **Linear** — create via `mcp__linear-server__save_issue` (clone fields, set the same `projectId`); add a blocking relation via the `relations` field or a paired relation call; edit the original to narrow scope. See `linear-write-issue` Phase 6.

package/plugins/lisa/rules/verification.md

@@ -96,6 +96,19 @@ Every change requires one or more verification types. Classify the change first,
 
 ---
 
+## Per-Work-Unit Evidence Contract
+
+Every **leaf work unit** — an individually implementable ticket with no child tickets (issue types Bug, Task, Sub-task, Improvement) — that changes runtime behavior must declare, at creation time, the exact evidence that proves it is done. Epics, Stories, and Spikes are coordination containers, not work units: their evidence is the rollup of their children, so this contract does not apply to them.
+
+The declaration is not a separate field — it is the set of `[EVIDENCE: name]` markers in the work unit's **Validation Journey**. Those markers are the work unit's **evidence manifest**: an enumerated, named list of the artifacts a verifier must capture. The manifest binds both ends of the ticket lifecycle:
+
+- **At creation** — the work unit cannot be written without a Validation Journey that names at least one `[EVIDENCE: name]` artifact (enforced by gate S14 in `tracker-validate` and the vendor `*-validate-*` skills). A behavior-changing unit should name both a success artifact and an error/edge artifact.
+- **At completion** — the work unit cannot be marked complete, nor transitioned to its review/Done state, until every `[EVIDENCE: name]` marker in its manifest has a captured, non-empty artifact attached to the ticket (enforced by the Task Completion Rules and Definition of Done in `verification-lifecycle`, and by the evidence-manifest gate in `tracker-evidence`). A manifest with a missing or empty artifact blocks completion exactly like a failed verification.
+
+The manifest is the single source of truth for "what evidence is required": authored once in the Validation Journey, enforced at write time, replayed during `tracker-journey`, and checked again before the ticket closes. There is no second list to keep in sync.
+
+---
+
 ## Local vs Remote Verification
 
 Verification happens at two stages in the workflow:

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

@@ -0,0 +1,260 @@
+---
+name: atlassian-access
+description: "Vendor-neutral access layer for Atlassian (JIRA + Confluence). Every jira-* and confluence-* skill MUST delegate through this skill rather than calling Atlassian directly. Resolves a substrate per operation in this order: (1) acli if installed and its active profile matches the configured site, (2) Atlassian MCP if authenticated and the configured cloudId is in its accessible resources, (3) curl + API-token Basic auth. Verifies the active connection matches `.lisa.config.json` before every operation — substrates authenticated as a different Atlassian account are skipped, not used."
+allowed-tools: ["Bash", "Read", "Skill"]
+---
+
+# Atlassian Access: $ARGUMENTS
+
+Single chokepoint for all Atlassian operations. Routes each op to a substrate, enforces connection match, returns structured result. Caller skills (`jira-*`, `confluence-*`) MUST go through this — they MUST NOT invoke `acli` directly, call Atlassian MCP tools directly, or curl the Atlassian REST API themselves.
+
+## Invocation contract
+
+The caller passes one operation plus its arguments. Operations are listed in the dispatch table below. The skill returns either the structured operation result (JSON when the substrate provides it) or a clear error.
+
+```text
+operation: read-ticket  key: PROJ-123
+operation: write-ticket payload: {...}
+operation: transition   key: PROJ-123  to: "In Review"
+operation: comment      key: PROJ-123  body: "..."
+operation: search-issues jql: "project = SE AND status = Open"
+operation: read-page    id: 12345
+operation: write-page   payload: {...}
+```
+
+## Workflow
+
+### Step 1 — Substrate selection (per operation)
+
+Read config:
+
+```bash
+SITE=$(jq -r '.atlassian.site // empty' .lisa.config.json)
+CLOUDID=$(jq -r '.atlassian.cloudId // empty' .lisa.config.json)
+EMAIL=$(jq -r '.atlassian.email // empty' .lisa.config.local.json 2>/dev/null)
+[ -z "$CLOUDID" ] && { echo "Error: atlassian.cloudId not set. Run /lisa:setup:atlassian." >&2; exit 1; }
+```
+
+Probe each tier in order; the first that's ready AND identity-matches is the substrate for this operation. Identity-match is verified before any operation; substrates authenticated as a different Atlassian account are skipped, not used.
+
+```bash
+substrate=""
+
+# Tier 1: acli
+if command -v acli >/dev/null 2>&1 && acli auth status >/dev/null 2>&1; then
+  current_site=$(acli auth status 2>/dev/null | awk '/^  Site:/{print $2}')
+  if [ "$current_site" = "$SITE" ]; then
+    substrate="acli"
+  else
+    # acli installed but pointing at a different site. Try switching profiles.
+    if acli auth switch --site "$SITE" ${EMAIL:+--email "$EMAIL"} >/dev/null 2>&1; then
+      substrate="acli"
+    fi
+  fi
+fi
+
+# Tier 2: Atlassian MCP (if acli not ready OR the operation isn't acli-covered)
+# $OP_REQUIRES is a conceptual variable set by the dispatch table to "non-acli" for
+# operations that have no acli adapter (e.g. read-page-descendants). It is not a real
+# shell variable initialized here — the condition is illustrative pseudo-code.
+if [ -z "$substrate" ] || [ "$OP_REQUIRES" = "non-acli" ]; then
+  # Probe via mcp__plugin_atlassian_atlassian__getAccessibleAtlassianResources.
+  # (Pseudo-code; actual call is the MCP tool invocation, not a bash command.)
+  # If the MCP returns a list and $CLOUDID is in it, MCP is identity-matched.
+  # If the MCP is unauthenticated or $CLOUDID is NOT in the list, MCP is skipped.
+  if mcp_atlassian_authenticated_and_matches_cloudid "$CLOUDID"; then
+    : ${substrate:=mcp}
+    # Mark MCP as available even if acli already won tier 1 — used for ops acli can't do.
+    mcp_available=true
+  fi
+fi
+
+# Tier 3: curl + API token (headless / multi-account / scoped-token path)
+read_atlassian_token() {
+  local email="$1"
+  [ -n "$ATLASSIAN_API_TOKEN" ] && { echo "$ATLASSIAN_API_TOKEN"; return; }
+  local slug=$(echo "$email" | tr '[:upper:]@.' '[:lower:]__')
+  local varname="ATLASSIAN_API_TOKEN_${slug}"
+  [ -n "${!varname}" ] && { echo "${!varname}"; return; }
+  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 ;;
+    MINGW*|MSYS*|CYGWIN*) cmdkey /list:"lisa-atlassian-${email}" 2>/dev/null | grep Password | awk '{print $NF}' ;;
+  esac
+}
+TOKEN=$(read_atlassian_token "$EMAIL")
+[ -n "$TOKEN" ] && curl_available=true && : ${substrate:=curl}
+
+# Fail loudly with actionable remediation if nothing works.
+if [ -z "$substrate" ]; then
+  # Detect plugin enablement state for the suggestion.
+  plugin_enabled_global=$(jq -r '.enabledPlugins["atlassian@claude-plugins-official"] // false' ~/.claude/settings.json 2>/dev/null || echo "false")
+  plugin_enabled_project=$(jq -r '.enabledPlugins["atlassian@claude-plugins-official"] // false' .claude/settings.json 2>/dev/null || echo "false")
+  plugin_enabled_local=$(jq -r '.enabledPlugins["atlassian@claude-plugins-official"] // false' .claude/settings.local.json 2>/dev/null || echo "false")
+
+  cat >&2 <<EOF
+Error: no Atlassian access substrate available for site $SITE.
+
+Attempted:
+  acli   — $(command -v acli >/dev/null && echo "installed but identity mismatch or unauthenticated" || echo "not installed")
+  MCP    — $([ "$plugin_enabled_global" = "true" ] || [ "$plugin_enabled_project" = "true" ] || [ "$plugin_enabled_local" = "true" ] && echo "plugin enabled but not authenticated or cloudId $CLOUDID not in accessible resources" || echo "plugin not enabled in any settings.json scope")
+  curl   — no ATLASSIAN_API_TOKEN found for $EMAIL (env, slug-suffixed env, or keychain)
+
+Remediation paths (pick one):
+
+1. Install the Atlassian MCP plugin (local scope — per-developer, gitignored).
+   This is the simplest path for single-account developers.
+
+   Run in your terminal:
+
+     jq '.enabledPlugins["atlassian@claude-plugins-official"] = true' \\
+       .claude/settings.local.json 2>/dev/null > /tmp/s && \\
+       mv /tmp/s .claude/settings.local.json || \\
+       echo '{"enabledPlugins":{"atlassian@claude-plugins-official":true}}' > .claude/settings.local.json
+
+   Then restart Claude Code (or run /restart-mcp) to load the plugin, and
+   invoke 'mcp__plugin_atlassian_atlassian__authenticate' to complete OAuth.
+
+2. Install acli and authenticate (best for multi-account developers).
+
+     brew tap atlassian/homebrew-acli && brew install acli
+     acli auth login   # OAuth as the account matching $EMAIL
+
+3. Provision an API token (headless / CI / scoped-token environments).
+
+     Run /lisa:setup:atlassian — guided flow with clipboard-piped keychain store.
+
+EOF
+  exit 1
+fi
+```
+
+Operation dispatch then uses `$substrate` for the primary route. If the operation has no `acli` adapter and `$substrate=acli`, fall through to `$mcp_available` then `$curl_available` for the actual call. The fall-through stops at the first available tier that can perform the operation.
+
+### Step 2 — Connection-match check
+
+The active connection MUST point at the cloudId/site declared in `.lisa.config.json`. Step 1's substrate selection already verifies this implicitly (substrates that don't match are skipped). This step is the explicit assertion before any operation runs — defensive in case the substrate state changed since selection.
+
+Read configured site:
+
+```bash
+cloudid=$(jq -r '.atlassian.cloudId // empty' .lisa.config.json)
+site=$(jq -r '.atlassian.site // empty' .lisa.config.json)   # optional human-readable site URL
+email=$(jq -r '.atlassian.email // empty' .lisa.config.json) # optional, for multi-account disambiguation
+
+if [ -z "$cloudid" ]; then
+  echo "Error: atlassian.cloudId not set in .lisa.config.json. Run /lisa:setup:atlassian." >&2
+  exit 1
+fi
+```
+
+**CLI mode check**:
+
+```bash
+# Compare active acli profile against config.
+current=$(acli auth status --json 2>/dev/null)
+current_site=$(echo "$current" | jq -r '.site // empty')
+current_email=$(echo "$current" | jq -r '.email // empty')
+
+if [ -n "$site" ] && [ "$current_site" != "$site" ]; then
+  # Profile mismatch — switch.
+  acli auth switch --site "$site" ${email:+--email "$email"}
+fi
+```
+
+If `acli auth switch` fails because no matching profile exists, surface the error verbatim and instruct the caller to run `/lisa:setup:atlassian` to add the profile.
+
+**curl mode check** (when the chosen op routes to curl):
+
+```bash
+# Validate the active ATLASSIAN_API_TOKEN points at the configured account by
+# hitting /rest/api/3/myself and comparing emailAddress.
+AUTH=$(printf '%s:%s' "$email" "$ATLASSIAN_API_TOKEN" | base64)
+myself=$(curl -s -H "Authorization: Basic $AUTH" \
+  "https://${site}/rest/api/3/myself")
+me_email=$(echo "$myself" | jq -r '.emailAddress // empty')
+
+if [ -z "$me_email" ]; then
+  echo "Error: ATLASSIAN_API_TOKEN failed authentication against $site. Run /lisa:setup:atlassian to re-issue." >&2
+  exit 1
+fi
+if [ "$me_email" != "$email" ]; then
+  echo "Error: ATLASSIAN_API_TOKEN belongs to '$me_email', but .lisa.config.local.json declares '$email'. Multi-account misconfiguration." >&2
+  exit 1
+fi
+```
+
+If validation fails, never silently proceed — abort and instruct the user to fix env.
+
+### Step 3 — Operation dispatch
+
+Substrate column meanings:
+
+- **`acli`**: routes through `acli`. Preferred when available and identity-matched.
+- **`MCP`**: routes through the Atlassian MCP. Preferred when acli can't do the op and the MCP is identity-matched (cloudId in `getAccessibleAtlassianResources`).
+- **`curl`**: routes through curl + Basic auth + `ATLASSIAN_API_TOKEN`. Used when neither acli nor MCP is available.
+- Multiple cells filled means tier ordering applies — try acli, then MCP, then curl, taking the first that has an adapter for the op AND is identity-matched.
+- One cell means only that substrate can perform the op.
+
+`<SITE>` = `.atlassian.site` (e.g. `propswap.atlassian.net`). `<CLOUDID>` = `.atlassian.cloudId`. `<AUTH>` = `Basic $(printf '%s:%s' "$email" "$ATLASSIAN_API_TOKEN" | base64)`. JIRA paths use `/rest/api/3/...`; Confluence uses `/wiki/rest/api/...` (v1) or `/api/v2/...` (v2).
+
+| Operation | acli adapter | MCP adapter | curl adapter |
+|---|---|---|---|
+| **JIRA ops** | | | |
+| `read-ticket key:<K>` | `acli jira workitem view <K> --json` | `mcp__plugin_atlassian_atlassian__getJiraIssue` | `GET https://<SITE>/rest/api/3/issue/<K>` |
+| `write-ticket payload:<P>` (create) | `acli jira workitem create --from-json <P>` | `mcp__plugin_atlassian_atlassian__createJiraIssue` | `POST https://<SITE>/rest/api/3/issue` body=`<P>` |
+| `write-ticket payload:<P>` (edit) | `acli jira workitem edit <K> --from-json <P>` | `mcp__plugin_atlassian_atlassian__editJiraIssue` | `PUT https://<SITE>/rest/api/3/issue/<K>` body=`<P>` |
+| `transition key:<K> to:<S>` | `acli jira workitem transition --key <K> --status "<S>" --yes` | `mcp__plugin_atlassian_atlassian__transitionJiraIssue` | resolve transition id then `POST .../issue/<K>/transitions` |
+| `transitions key:<K>` | (not exposed) | `mcp__plugin_atlassian_atlassian__getTransitionsForJiraIssue` | `GET https://<SITE>/rest/api/3/issue/<K>/transitions` |
+| `comment key:<K> body:<B>` | `acli jira workitem comment add --key <K> --body "<B>"` | `mcp__plugin_atlassian_atlassian__addCommentToJiraIssue` | `POST https://<SITE>/rest/api/3/issue/<K>/comment` |
+| `link from:<K> to:<K2> type:<T>` | `acli jira workitem link create --inward <K> --outward <K2> --type "<T>"` | `mcp__plugin_atlassian_atlassian__createJiraIssueLink` | `POST https://<SITE>/rest/api/3/issueLink` |
+| `remote-links key:<K>` | (not exposed) | `mcp__plugin_atlassian_atlassian__getJiraIssueRemoteIssueLinks` | `GET https://<SITE>/rest/api/3/issue/<K>/remotelink` |
+| `search-issues jql:<J>` | `acli jira workitem search --jql "<J>" --json` | `mcp__plugin_atlassian_atlassian__searchJiraIssuesUsingJql` | `POST https://<SITE>/rest/api/3/search/jql` |
+| `list-projects` | `acli jira project list --paginate --json` | `mcp__plugin_atlassian_atlassian__getVisibleJiraProjects` | `GET https://<SITE>/rest/api/3/project/search` |
+| `issue-type-metadata project:<K>` | `acli jira project view --key <K> --include-all --json` | `mcp__plugin_atlassian_atlassian__getJiraProjectIssueTypesMetadata` | `GET https://<SITE>/rest/api/3/issuetype/project?projectId=<id>` |
+| **Confluence ops** | | | |
+| `read-page id:<I>` | `acli confluence page view --id <I> --json` | `mcp__plugin_atlassian_atlassian__getConfluencePage` | `GET https://api.atlassian.com/ex/confluence/<CLOUDID>/wiki/rest/api/content/<I>` |
+| `read-page-descendants id:<I>` | — | `mcp__plugin_atlassian_atlassian__getConfluencePageDescendants` | `GET .../content/<I>/descendant/page` |
+| `read-page-comments id:<I> kind:<footer\|inline>` | — | `mcp__plugin_atlassian_atlassian__getConfluencePageFooterComments` / `getConfluencePageInlineComments` | `GET .../content/<I>/child/comment?location=<kind>` |
+| `read-comment-children id:<C>` | — | `mcp__plugin_atlassian_atlassian__getConfluenceCommentChildren` | `GET .../content/<C>/child/comment` |
+| `write-page payload:<P>` (create) | — | `mcp__plugin_atlassian_atlassian__createConfluencePage` | `POST .../wiki/rest/api/content` body=`<P>` |
+| `write-page payload:<P>` (edit) | — | `mcp__plugin_atlassian_atlassian__updateConfluencePage` | `PUT .../content/<I>` body must include `version.number` bumped |
+| `label-page id:<I> add:<L1,L2> remove:<L3,L4>` | — | (no v2 label-write endpoint on MCP) | (Atlassian gap; not used by lisa — see "Confluence PRD lifecycle" rule) |
+| `comment-page id:<I> kind:<footer\|inline> body:<B>` | — | `mcp__plugin_atlassian_atlassian__createConfluenceFooterComment` / `createConfluenceInlineComment` | `POST .../content` body has `type=comment` |
+| `search-pages cql:<Q>` | — | `mcp__plugin_atlassian_atlassian__searchConfluenceUsingCql` | `GET .../content/search?cql=<Q>` |
+| `list-spaces` | `acli confluence space list --type global --json` | `mcp__plugin_atlassian_atlassian__getConfluenceSpaces` | `GET .../wiki/rest/api/space` |
+| **Common ops** | | | |
+| `list-sites` | `acli auth status --json` | `mcp__plugin_atlassian_atlassian__getAccessibleAtlassianResources` | `GET https://api.atlassian.com/oauth/token/accessible-resources` |
+
+**Confluence v1 vs v2:** every Confluence curl path above uses **v1** (`/wiki/rest/api/...`). v1 is deprecated by Atlassian but as of writing remains functional for API-token Basic auth. The v2 API (`/api/v2/...`) requires *granular* OAuth scopes that aren't issued to Basic-auth API tokens consistently — so v1 is the safer path for now. When Atlassian fully retires v1, this table must move to v2 (the dispatch is the only thing that changes; the substrate-selection logic is unaffected).
+
+**acli flag note:** acli's `--output` flag does not exist; the correct flag is `--json`. List commands require `--paginate` or `--limit` (no implicit fetch-all). Several documented adapters are nominal — verify against `acli <subcmd> --help` before relying on them. When acli's adapter is broken or missing for a specific op, fall through to MCP (if identity-matched) then curl per the tier ordering.
+
+Operations not in this table are unsupported — add an adapter row before using them. Adapters MUST return a structured response (parse `acli`'s `--json`; jq-process curl's raw JSON).
+
+### Payload conventions
+
+- `write-ticket` payload: full JSON spec when creating; partial JSON (only changed fields, with `key` to identify) when editing. Adapters detect create vs edit by presence of `key`.
+- `write-page` payload: supports a label-only mutation form — `{ "id": "<I>", "labels": { "add": [...], "remove": [...] } }` — so callers transitioning PRD lifecycle labels do not need to resend the page body. Full create/update payloads also accepted.
+- `comment-page` `kind: inline` requires `anchor` (the highlighted text the comment attaches to). `kind: footer` ignores `anchor`.
+
+### Step 4 — Return result
+
+Emit either:
+
+- The structured operation result (JSON object), wrapped in a `<result>` block for caller parsing, OR
+- An error message prefixed with `Error:` and a remediation hint. Exit non-zero. Include the HTTP status code (curl) or acli exit code so callers can route on it.
+
+Do not paraphrase substrate output beyond JSON normalization.
+
+## Invariants
+
+- Caller skills never invoke `acli` or `curl` against Atlassian directly. They only invoke this skill.
+- Substrate is decided once per skill invocation and never switches mid-operation.
+- Connection match is mandatory. Operations that bypass it (because "the user obviously meant the configured site") are forbidden.
+- Profile mutations (`acli auth switch`) are allowed when acli is the active substrate. The curl substrate never mutates the token — if `ATLASSIAN_API_TOKEN` doesn't match the configured account, fail loud rather than silently substituting.
+- `.lisa.config.local.json` overrides `.lisa.config.json` per-key — the same precedence rule as every other consumer of project config.
+
+## Headless behavior
+
+In a headless / non-interactive context (no TTY, `CI=true`, or `-p` mode), the MCP tier is unavailable (its OAuth flow needs a browser). The substrate ladder collapses to: acli (if pre-authenticated, e.g., a CI image baked with a service-account token) → curl + `ATLASSIAN_API_TOKEN`. Never block on interactive prompts. If both fail readiness checks, exit non-zero with a deterministic error.