@codyswann/lisa 2.119.0 → 2.121.0

package/plugins/lisa-cursor/rules/reference/config-resolution.md

@@ -0,0 +1,691 @@
+# Config Resolution
+
+Lisa is vendor-agnostic. PRDs can be sourced from Notion, Confluence, Linear, GitHub Issues, or JIRA. Tickets can be written to JIRA, GitHub Issues, or Linear. Per-project configuration lives in `.lisa.config.json` at the repo root, with optional `.lisa.config.local.json` overriding on a per-key basis.
+
+This rule is the single source of truth for the `.lisa.config.json` schema, the resolution algorithm, and the dispatch tables every vendor-neutral skill follows.
+
+## File location and precedence
+
+Read configuration from the repo root in this order:
+
+1. `.lisa.config.local.json` — gitignored, per-developer overrides (e.g., a developer running with a different destination tracker for one branch).
+2. `.lisa.config.json` — committed, project-wide settings.
+
+Local overrides global on a **per-key basis**: missing keys in `.lisa.config.local.json` fall through to `.lisa.config.json`. Use `jq` from Bash for all reads — never hand-parse JSON.
+
+A typical Bash read:
+
+```bash
+local_value=$(jq -r '.tracker // empty' .lisa.config.local.json 2>/dev/null)
+global_value=$(jq -r '.tracker // empty' .lisa.config.json 2>/dev/null)
+tracker="${local_value:-${global_value}}"
+if [ -z "$tracker" ]; then
+  echo "Error: 'tracker' not set in .lisa.config.json. Run /lisa:setup:jira (or :github, :linear) to configure." >&2
+  exit 1
+fi
+```
+
+`tracker` is **required** — there is no implicit default. Projects must declare their destination explicitly via one of the `/lisa:setup:*` skills.
+
+## Schema
+
+```json
+{
+  "tracker": "jira",
+  "source":  "notion",
+
+  "atlassian":  { "cloudId": "<uuid>", "site": "<host>" },
+  "jira": {
+    "project": "<KEY>",
+    "workflow": {
+      "ready":   "Ready",
+      "claimed": "In Progress",
+      "review":  "Code Review",
+      "blocked": "Blocked",
+      "done":    { "dev": "On Dev", "staging": "On Stg", "production": "Done" }
+    }
+  },
+  "confluence": {
+    "spaceKey": "<KEY>",
+    "parentPageId": "<id>",
+    "parents": {
+      "draft":     "<page-id>",
+      "ready":     "<page-id>",
+      "in_review": "<page-id>",
+      "blocked":   "<page-id>",
+      "ticketed":  "<page-id>",
+      "shipped":   "<page-id>",
+      "verified":  "<page-id>"
+    },
+    "dashboardPageId": "<page-id>",
+    "feedbackPageId":  "<page-id>"
+  },
+  "github": {
+    "org": "<org-or-user>",
+    "repo": "<repo>",
+    "projects": {
+      "v2": {
+        "owner": {
+          "kind": "organization",
+          "slug": "<org-or-user>"
+        },
+        "number": 7,
+        "required": false
+      }
+    },
+    "labels": {
+      "build": {
+        "ready":   "status:ready",
+        "claimed": "status:in-progress",
+        "blocked": "status:blocked",
+        "done":    { "dev": "status:on-dev", "staging": "status:on-stg", "production": "status:done" }
+      },
+      "prd": {
+        "draft": "prd-draft",
+        "ready": "prd-ready", "in_review": "prd-in-review",
+        "blocked": "prd-blocked", "ticketed": "prd-ticketed",
+        "shipped": "prd-shipped", "verified": "prd-verified",
+        "sentinel": "prd-intake-feedback"
+      }
+    }
+  },
+  "notion": {
+    "workspaceId":    "<workspace-uuid-or-human-slug>",
+    "prdDatabaseId":  "<uuid>",
+    "statusProperty": "Status",
+    "values": {
+      "draft": "Draft", "ready": "Ready", "in_review": "In Review",
+      "blocked": "Blocked", "ticketed": "Ticketed", "shipped": "Shipped",
+      "verified": "Verified"
+    }
+  },
+  "linear": {
+    "workspace": "<workspace-slug>",
+    "teamKey": "<TEAM>",
+    "labels": {
+      "build": {
+        "ready":   "status:ready",
+        "claimed": "status:in-progress",
+        "review":  "status:code-review",
+        "blocked": "status:blocked",
+        "done":    { "dev": "status:on-dev", "staging": "status:on-stg", "production": "status:done" }
+      },
+      "prd": {
+        "draft": "prd-draft",
+        "ready": "prd-ready", "in_review": "prd-in-review",
+        "blocked": "prd-blocked", "ticketed": "prd-ticketed",
+        "shipped": "prd-shipped", "verified": "prd-verified",
+        "sentinel": "prd-intake-feedback"
+      }
+    }
+  },
+
+  "deploy": {
+    "branches": {
+      "dev":        "dev",
+      "staging":    "staging",
+      "production": "main"
+    }
+  },
+
+  "usage": {
+    "pricing": {
+      "currency": "USD",
+      "source": "openai-api-pricing",
+      "snapshot": "2026-05-25",
+      "models": {
+        "openai/gpt-5": {
+          "inputPer1M": 1.25,
+          "cachedInputPer1M": 0.125,
+          "outputPer1M": 10.0,
+          "reasoningPer1M": 10.0
+        }
+      }
+    }
+  },
+
+  "intake": {
+    "assignee": "<vendor-user-id-or-login>",
+    "repair": {
+      "staleAfterHours": 2,
+      "maxCandidates": 100
+    }
+  }
+}
+```
+
+### Top-level fields
+
+| Field | Required | Default | Notes |
+|-------|----------|---------|-------|
+| `tracker` | **yes** | — | Destination for ticket writes. One of `"jira"`, `"github"`, `"linear"`. Missing → fail with instruction to run the matching `/lisa:setup:*` skill. |
+| `source` | no | — | Default PRD source for batch skills (`/lisa:intake`) and arg-less single-PRD skills. One of `"notion"`, `"confluence"`, `"linear"`, `"github"`, `"jira"`. Explicit URLs/keys passed to a skill always win over `source`; this is a default, not a lock. |
+| `usage` | no | — | Optional token/cost pricing metadata consumed by the `usage-accounting` rule. Missing pricing never blocks a lifecycle flow; Lisa records token counts with `estimated_cost: null` when no trustworthy price source is configured. |
+
+### Vendor sections
+
+Each vendor section is **conditionally required**: required only when that vendor is referenced as `tracker`, as `source`, or by an explicit invocation. Skills validate their own required keys at entry and stop with a clear error if missing — never invent values.
+
+#### `atlassian`
+
+| Field | Required when | Where it lives | Notes |
+|-------|---------------|----------------|-------|
+| `atlassian.cloudId` | `tracker = "jira"`, `source = "jira"`, `source = "confluence"`, or any `confluence-*` / `jira-*` skill is invoked | **committed** (`.lisa.config.json`) | Atlassian Cloud site UUID. Same for every developer on the project. Resolve once via `curl https://<site>/_edge/tenant_info` or `getAccessibleAtlassianResources`. Shared between JIRA and Confluence (same Atlassian site). |
+| `atlassian.site` | same as above | **committed** | Human-readable site URL (e.g. `propswap.atlassian.net`). Same for every developer. |
+| `atlassian.email` | when the developer's machine has multiple Atlassian accounts that can access the configured site | **local** (`.lisa.config.local.json`) | Per-developer. `--site` alone cannot disambiguate which acli profile to switch to when two accounts both have access to the same site (e.g., a personal account and a work account both invited to a customer's site). The setup skill writes this to the local override file, NEVER the committed file. |
+
+#### `jira`
+
+| Field | Required when | Notes |
+|-------|---------------|-------|
+| `jira.project` | `tracker = "jira"` or any `jira-*` skill is invoked | JIRA project key (e.g. `SE`, `ENG`). |
+
+#### `confluence`
+
+| Field | Required when | Notes |
+|-------|---------------|-------|
+| `confluence.spaceKey` | `source = "confluence"` and `parentPageId` is not set | Confluence space key (e.g. `ENG`). |
+| `confluence.parentPageId` | `source = "confluence"` and `spaceKey` is not set | Confluence parent page ID. Either `spaceKey` or `parentPageId` must be set; both is allowed (parent page ID narrows the scope). |
+
+#### `github`
+
+| Field | Required when | Notes |
+|-------|---------------|-------|
+| `github.org` | `tracker = "github"` or `source = "github"` or any `github-*` skill is invoked | GitHub organization or user name. |
+| `github.repo` | same as above | GitHub repository name. |
+| `github.projects.v2.owner.kind` | GitHub Project coordination is enabled | Owner type for the shared ProjectV2. Supported values are `organization` and `user`. |
+| `github.projects.v2.owner.slug` | GitHub Project coordination is enabled | Owner login for the shared ProjectV2. In v1 it MUST match the tracked repository namespace (`github.org`); cross-namespace coordination is rejected. |
+| `github.projects.v2.number` | GitHub Project coordination is enabled | Human-facing ProjectV2 number from the GitHub UI / URL. Later utilities resolve the opaque node id from this owner + number pair. |
+| `github.projects.v2.required` | no | Coordination strictness flag. Default `false` keeps Project membership best-effort; `true` makes Project membership failures block the write. Setup/doctor/runtime validation reads Project ownership + access and branches on this flag: best-effort failures warn, required-mode failures stop the write. |
+
+When `tracker = "github"` AND `source = "github"` (self-host), both reads and writes hit the same GitHub repo. Label namespaces are kept separate so the two flows don't collide — see "Self-host edge case" below.
+
+`github.projects.v2` is optional. When absent, GitHub issue / PR writes remain repository-local exactly as they work today. When present, the shared Project is a coordination view layered on top of real issues and pull requests; it does not replace lifecycle labels, comments, dependencies, or native issue / PR state as Lisa's durable source of truth.
+
+When `github.projects.v2` is present, later setup/doctor and writer preflight validation MUST read the referenced Project's owner + access level before any membership write depends on it. The validation contract is:
+
+- Resolve the Project from `owner.kind`, `owner.slug`, and `number`.
+- Confirm the owner namespace still matches `github.org`; cross-namespace Project ownership is a configuration error.
+- Confirm the authenticated identity can read the Project and has sufficient access for membership coordination.
+- If `required = false`, surface Project-validation failures as warnings and continue repository-local issue / PR writes without Project membership.
+- If `required = true`, surface the same failures as blocking errors and stop the write before mutating issue / PR membership.
+
+#### `notion`
+
+| Field | Required when | Where it lives | Notes |
+|-------|---------------|----------------|-------|
+| `notion.workspaceId` | `source = "notion"` | **committed** | Workspace identifier (Notion workspace UUID, or a stable human slug the user picks at setup). Same for every developer on the project. Used as the keychain `account` value when looking up the Notion API token, so each project's `notion-access` finds the right per-workspace token. |
+| `notion.prdDatabaseId` | `source = "notion"` | **committed** | Notion database ID (UUID, dashes optional). The database is the PRD queue. Same for every developer on the project. |
+| `notion.statusProperty` | `source = "notion"` | **committed** | Name of the database property that drives the lifecycle. Defaults to `"Status"` if absent. |
+| `notion.values` | optional | **committed** | Map of role → Notion status-value name (`draft`, `ready`, `in_review`, `blocked`, `ticketed`, `shipped`, `verified`). Defaults match the role names in title case. Override here if your Notion DB uses different value names. |
+
+#### `linear`
+
+| Field | Required when | Notes |
+|-------|---------------|-------|
+| `linear.workspace` | `tracker = "linear"`, `source = "linear"`, or any `linear-*` skill is invoked | Linear workspace slug (e.g. `acme`). |
+| `linear.teamKey` | `tracker = "linear"` | Linear team key (e.g. `ENG`). The team owns the destination Issues. For source mode, projects are workspace-scoped or team-scoped per the URL passed. |
+
+#### `usage`
+
+`usage` is optional. It carries non-secret pricing metadata Lisa may use when runtime token counts are trustworthy but runtime monetary cost is absent.
+
+| Field | Required when | Where it lives | Notes |
+|-------|---------------|----------------|-------|
+| `usage.pricing.currency` | estimating cost from config | **committed** | ISO currency code paired with the configured rates (for example `USD`). |
+| `usage.pricing.source` | estimating cost from config | **committed** | Human-readable source label for the configured pricing schedule (for example `openai-api-pricing`). This is metadata, not a URL requirement. |
+| `usage.pricing.snapshot` | no | **committed** | Version/date/hash describing when the pricing schedule was captured. Use it to make estimated-cost provenance durable across later vendor price changes. |
+| `usage.pricing.models` | estimating cost from config | **committed** | Map of `<provider>/<model>` to per-million-token rates. Lisa has **no built-in provider rates**; every estimated-cost model must be declared here explicitly. |
+
+Each `usage.pricing.models["<provider>/<model>"]` value supports these numeric keys:
+
+| Key | Required | Notes |
+|-----|----------|-------|
+| `inputPer1M` | yes | Price per 1M non-cached input tokens. |
+| `cachedInputPer1M` | no | Price per 1M cached input tokens when the runtime exposes them separately. If absent, cached tokens cannot be priced and the entry falls back to `pricing_status=missing` unless the runtime already supplied cost. |
+| `outputPer1M` | yes | Price per 1M output/completion tokens. |
+| `reasoningPer1M` | no | Price per 1M reasoning/internal tokens when the provider bills them separately. If absent, treat reasoning tokens as unpriceable rather than folding them into another bucket. |
+
+Resolution rules for estimated pricing:
+
+- Resolve `usage.pricing.*` with the same per-key local-overrides-global precedence as every other config section.
+- Estimates are allowed only when trustworthy token counts exist and a matching `usage.pricing.models["<provider>/<model>"]` entry supplies every rate needed for the exposed token buckets.
+- Missing model entries or missing required bucket rates do **not** trigger built-in defaults. Preserve the token counts, leave `cost = null`, and emit `pricing_status = missing`.
+- When an estimate is produced from config, write `pricing_source` as `config:<source>@<snapshot>` when both fields exist, `config:<source>` when only `source` exists, or `config` when neither metadata field is available.
+- Runtime-observed monetary cost always wins over config estimates; config pricing is fallback-only.
+
+## Workflow & vocabulary roles
+
+Every lifecycle skill operates on a fixed set of **roles** (`ready`, `claimed`, `done`, etc.), not concrete status/label strings. The role → string mapping lives in the per-vendor section above, with defaults that match the legacy hardcoded names. A project that uses different names overrides the relevant key; everything else inherits.
+
+### Roles
+
+**Build lifecycle** (work items):
+
+| Role | What it means | JIRA default | GitHub/Linear default |
+|---|---|---|---|
+| `ready` | Human signal "this is buildable; agent may claim" | `Ready` (status) | `status:ready` (label) |
+| `claimed` | Agent has picked the item up | `In Progress` (status) | `status:in-progress` (label) |
+| `review` | Optional post-build review hold, when a tracker/project still uses one | `Code Review` (status) | Linear default: `status:code-review`; GitHub has no default review label |
+| `blocked` | Agent stopped on triage ambiguities or external blocker | `Blocked` (status) | `status:blocked` (label) |
+| `done` | Terminal state for this work, **env-keyed** | map of env → status | map of env → label |
+
+`review` is optional. GitHub build intake skips it by default and moves successful builds directly from `claimed` to the configured `done` label. Linear and JIRA projects that still use a post-build review hold can configure `review`; projects that keep the ticket in `claimed` until terminal can omit it and lifecycle skills will skip the intermediate transition.
+
+`blocked` is what every vendor agent flips to when triage finds unresolved ambiguities or the build path is blocked by something the agent can't resolve. Different from `claimed` because it explicitly signals "human attention required."
+
+**PRD lifecycle** (specifications):
+
+| Role | What it means | Notion default | Confluence/GitHub/Linear default |
+|---|---|---|---|
+| `draft` | Author drafting; agent ignores until promoted to `ready` | `Draft` (status) | `prd-draft` (GitHub/Linear label); parent-page lookup (Confluence) |
+| `ready` | "Ready for ticketing"; agent claims | `Ready` (status) | `prd-ready` (label) |
+| `in_review` | Agent has claimed and is validating | `In Review` (status) | `prd-in-review` (label) |
+| `blocked` | Validation failed; clarifying-comments posted | `Blocked` (status) | `prd-blocked` (label) |
+| `ticketed` | Validated and tickets created | `Ticketed` (status) | `prd-ticketed` (label) |
+| `shipped` | All child tickets shipped | `Shipped` (status) | `prd-shipped` (label) |
+| `verified` | Shipped product empirically checked against the PRD | `Verified` (status) | `prd-verified` (label); parent-page lookup (Confluence) |
+| `sentinel` | (PRD-intake feedback issue marker, GitHub/Linear self-host only) | — | `prd-intake-feedback` |
+
+### PRD rollup behavior
+
+PRD lifecycle completion is **derived** from the PRD's generated top-level work, not set independently — see the `prd-lifecycle-rollup` rule for the full contract (generated-top-level-work definition, per-vendor terminal-state predicate, the `shipped` transition, verified native closure, and the child-ref idempotency key). When all required generated top-level children are terminal, rollup transitions the PRD to its `shipped` role and leaves it open/active for `/lisa:verify-prd`. There is no project-configurable close-on-shipped flag: provider-native closure/archive/completion happens only after `/lisa:verify-prd` passes and moves the PRD to `verified`.
+
+### Repair intake config (`intake.repair`)
+
+`lisa:repair-intake` (the recovery counterpart to `lisa:intake`) reads two optional tuning keys
+from the top-level `intake.repair` block. Both are **optional** — a missing block inherits the
+documented defaults, so existing projects need no config change.
+
+| Key | Required | Default | Notes |
+|-----|----------|---------|-------|
+| `intake.repair.staleAfterHours` | no | `2` | How long an in-progress item (build `claimed`, PRD `in_review`) may show no observable activity before repair-intake treats it as stalled and resumes it. `blocked` items are judged on blocker/answer state, not this threshold. Overridable per-run via `stale_after=<dur>` in `$ARGUMENTS` (which always wins). The same value is the default backoff window for loop-prevention notes. |
+| `intake.repair.maxCandidates` | no | `100` | Upper bound on how many stuck items repair-intake enumerates while searching for the first actionable one. Bounds scan cost. Overridable per-run via `max_candidates=<n>`. |
+
+### Intake assignee filter (`intake.assignee`)
+
+The optional intake assignee filter narrows **ready-item selection only**. It never assigns or
+reassigns tickets; it simply tells build-intake to consider only ready items that are already
+assigned to the resolved person for this local run.
+
+Resolution order:
+
+1. `$ARGUMENTS` `assignee=<vendor-user-id-or-login>`
+2. `.lisa.config.local.json` `intake.assignee`
+3. empty default (no filtering)
+
+The setting is intentionally **local-only**: personal or machine-specific intake lanes belong in
+`.lisa.config.local.json`, not the committed project config. An empty resolved value disables the
+filter and preserves the shared ready-queue behavior.
+
+| Field | Required | Default | Notes |
+|-------|----------|---------|-------|
+| `intake.assignee` | no | empty | Local ready-queue filter for build intake. When non-empty, vendor build-intake skills query only ready items already assigned to that vendor-specific user id or login. When empty, no assignee filter is applied. Runtime `$ARGUMENTS` `assignee=<...>` always wins over config for that invocation. |
+
+Resolution order matches every other key: `$ARGUMENTS` override → `.lisa.config.local.json` →
+`.lisa.config.json` → built-in default. The role SEMANTICS repair-intake operates on (which
+roles count as "stuck", what each repair does) are fixed like every other lifecycle transition;
+only these thresholds are tunable.
+
+### Env-keyed `done`
+
+The `done` role is special: the terminal status/label depends on which environment a PR was merged into. A hotfix to staging ends at `On Stg`; a production hotfix ends at `Done`. So `done` is a **map** keyed by env name (`dev`, `staging`, `production`).
+
+Skills that transition to `done` MUST resolve the env first:
+
+1. **Explicit caller arg** (`target_env=staging`) — always wins.
+2. **Branch inference** — derive from the PR's base branch via `deploy.branches`. Reverse-lookup: if base branch is `staging`, env is `staging`.
+3. **Failure** — if neither resolves and `done` is a map, fail loudly. Never pick arbitrarily.
+
+If a project's terminal state is the same regardless of env, set `done` to a string instead of a map (lifecycle skills accept either shape).
+
+### Env → base branch (forward: the build base and PR base)
+
+`deploy.branches` is also read in the **forward** direction by the build flow (`lisa:implement`): the environment a work item targets determines the branch the work is built on and the branch the PR opens against.
+
+1. **Resolve the work item's target environment** — its `## Target Backend Environment` field. If the item names no environment, use the **remote default branch** (`gh repo view --json defaultBranchRef`, or `origin/HEAD`).
+2. **Map env → base branch** via `deploy.branches` (e.g. `staging → staging`, `production → main`). Absent env or missing branch → stop and report; never guess.
+3. **Before any code is written**, `lisa:implement` fetches and **rebases the working branch onto `origin/<base>`, resolving conflicts**, so implementation builds on the latest target-environment code. **The PR then opens against that same base branch** (`target_branch=<base>` to `lisa:git-submit-pr`).
+
+This is the exact inverse of the env-keyed `done` "Branch inference" above: `done` derives the env *from* the PR base branch (reverse); the build flow derives the base branch *from* the env (forward). Both use the one `deploy.branches` map, so the branch a PR targets and the `done` status it earns always agree.
+
+The true terminal `done` value is also the only value that triggers provider-native closure / resolution per `leaf-only-lifecycle`:
+
+- If `done` is a string, that value is terminal.
+- If `done` is an env-keyed map, the production / final environment's value is terminal. The conventional key is `production`; project-specific final env names must be explicit in deploy config or the lifecycle skill must fail rather than guessing.
+- Intermediate env values (`dev`, `staging`, or configured equivalents) are deployment waypoints. Applying them must not close / resolve / complete the native tracker item.
+
+### What's configurable, what's not
+
+- **Status / label NAMES** are configurable per project — that's the point of the vocabulary maps.
+- **Role SEMANTICS and TRANSITIONS** are not. The build lifecycle is always `ready → claimed → done` (with optional `review` for label-driven systems). The PRD lifecycle is always `ready → in_review → (blocked | ticketed) → shipped`, then verification may move `shipped → verified` on a pass or `shipped → ticketed` on a failed verification. `verified` is terminal and product-owned like `draft` and `shipped`; Lisa does not add `prd-verifying` or `prd-verification-failed` states. Skills hardcode these transitions because they encode the design intent of the framework, not the project's preferences.
+- **Extra statuses/labels** the project uses outside these roles are fine — lisa never touches them.
+
+### Defaults vs. requirements
+
+Vocabulary maps are **optional** in `.lisa.config.json`. Missing keys inherit the defaults shown in the schema above. The setup skills probe the project's actual workflow / labels at setup time and either:
+
+- Confirm the default name exists → proceed silently.
+- Confirm a different name exists (e.g., `Resolved` instead of `Done`) → prompt the user to either rename in the tracker or override the key in config.
+- Find nothing matching → stop and ask the user to (a) create the missing status/label in the tracker, or (b) provide the actual name to write into config.
+
+## Resolution algorithm
+
+Every `tracker-*` shim and every vendor-neutral caller follows this:
+
+1. Read `.lisa.config.local.json` first (if present), then `.lisa.config.json`. Local overrides global on a per-key basis. Use `jq` — never hand-parse JSON.
+2. Extract the `tracker` field. If missing or null, stop and report: `"'tracker' is not set in .lisa.config.json. Run /lisa:setup:jira (or :github, :linear) to configure."`
+3. Dispatch:
+   - `tracker = "jira"` → delegate to the matching `jira-*` skill. Validate `atlassian.cloudId` and `jira.project` are present.
+   - `tracker = "github"` → delegate to the matching `github-*` skill. Validate `github.org` and `github.repo` are present.
+   - `tracker = "linear"` → delegate to the matching `linear-*` skill. Validate `linear.workspace` and `linear.teamKey` are present.
+4. Any other value: stop and report `"Unknown tracker '<value>' in .lisa.config.json. Expected 'jira', 'github', or 'linear'."`
+
+For batch skills that consume `source`:
+
+1. If `$ARGUMENTS` contains an explicit URL or key, parse the source vendor from it (always wins).
+2. If `$ARGUMENTS` is the bare token `notion` / `confluence` / `linear` / `github` / `jira`, the source is that vendor; resolve location from the corresponding config section.
+3. If `$ARGUMENTS` is empty, fall back to `source` from config; if that's also empty, stop and report `"No source specified and no 'source' field in .lisa.config.json."`
+
+### Doctor config readiness
+
+`/lisa:doctor` reads the same config, but it audits readiness instead of dispatching a write.
+Doctor must validate config in three layers:
+
+1. **Parse and merge**
+   - Parse both config files as JSON. Missing or invalid `.lisa.config.json` is a blocking error.
+     `.lisa.config.local.json` is optional, but if present and invalid it is also a blocking error.
+   - Merge per key with the standard local-overrides-global rule. Doctor reports against the merged
+     effective config; it does not treat the local file as a full replacement for the committed
+     file.
+2. **Required-key correctness**
+   - Missing `tracker` after merge is a blocking error. Unknown merged `tracker` / `source` values
+     are also blocking errors.
+   - If the configured tracker/source vendor is missing its required keys after merge, doctor must
+     report a blocking readiness failure using the vendor tables above. Examples: `tracker=github`
+     requires `github.org` + `github.repo`; `tracker=jira` requires `atlassian.cloudId` +
+     `jira.project`; `source=notion` requires `notion.workspaceId` + `notion.prdDatabaseId`.
+3. **Field locality correctness**
+   - `atlassian.email`, `intake.assignee`, and `jira.verified_workflow_hash` are local-only. If
+     they appear in committed config, doctor warns that developer-specific state was checked into
+     the project file.
+   - Project-wide fields that exist only in `.lisa.config.local.json` should warn, not pass
+     silently. Current machine works, repository not durably configured for teammates and
+     automations. Common examples include `tracker`, `source`, `github.org`, `github.repo`,
+     `atlassian.cloudId`, `atlassian.site`, `jira.project`, `linear.workspace`, `linear.teamKey`,
+     and `deploy.branches`.
+
+Doctor's severity rule is simple: unusable merged config is `FAIL`; locality drift with a still
+usable merged config is `WARN`.
+
+### Doctor vendor preflight
+
+Once doctor can resolve the merged `tracker` and optional `source`, it must run a read-only vendor
+preflight for those configured vendors only.
+
+1. **Audit only the configured vendors**
+   - Always audit the merged `tracker`.
+   - Audit `source` when present and when it is not already covered by the tracker check.
+   - Every other vendor is a doctor `SKIP`, not an implicit pass.
+2. **Read-capable substrate requirement**
+   - `github` requires `gh` CLI, a passing `gh auth status`, and read access to the configured
+     repo (`github.org` + `github.repo`).
+   - `jira` / `confluence` must reuse the `atlassian-access` substrate ladder. Doctor passes when
+     at least one supported read-capable substrate (`acli`, Atlassian MCP, or validated curl/API
+     token) can prove visibility to the configured `atlassian.cloudId` and target scope.
+   - `linear` passes when either the Linear MCP or a validated API-key probe can read the
+     configured workspace; tracker mode also requires visibility to `linear.teamKey`.
+   - `notion` passes when either the Notion MCP identity matches `notion.workspaceId` or a valid
+     internal-integration token does, and the configured `notion.prdDatabaseId` is readable.
+3. **Observed-fact discipline**
+   - Missing executable / MCP availability and failed auth/scope probes must be reported
+     separately.
+   - Preserve the exact probe failure text or status code when a read attempt fails; doctor should
+     not collapse repo-not-found, wrong-workspace, and unauthenticated cases into one generic
+     readiness error.
+4. **Severity**
+   - No read-capable substrate for the configured vendor, or a configured target that remains
+     unreadable after all supported probes, is a doctor `FAIL`.
+   - A reachable vendor with only auxiliary-substrate degradation is a doctor `WARN`.
+
+### Doctor automation readiness
+
+Doctor's automation-readiness group is also read-only. It answers "could this repo safely support
+Lisa's recurring automations from the current runtime?" without creating, editing, deleting, or
+reconciling any automation state.
+
+1. **Resolve the automation queues from merged config**
+   - Resolve the PRD automation queue from merged `source`.
+   - Resolve the build automation queue from merged `tracker`.
+   - Resolve repair-intake from the same queue-detection contract `lisa:intake` /
+     `lisa:repair-intake` already use; doctor should not invent a second queue schema.
+   - If an automation's queue cannot be resolved because `source`, `tracker`, or the selected
+     vendor's required keys are still missing after merge, that automation is a doctor `FAIL`.
+     Unattended runs would be ambiguous before the scheduler is even involved.
+2. **Check native scheduler availability by runtime, read-only**
+   - Codex automation support means the runtime exposes the native automations surface
+     (`automation_update`) that `setup-automations` depends on.
+   - Claude automation support means `/schedule` is available.
+   - Other runtimes should be reported explicitly as having no known native Lisa scheduler unless a
+     supported surface is observable.
+   - Doctor must not create a throwaway automation just to prove the scheduler exists.
+3. **Match exploratory automation support to the repo's shipped stack**
+   - `exploratory-bugs` exists only for stacks that ship `exploratory-qa` (`expo`, `rails`,
+     `harper-fabric`). If the repo lacks that command surface, doctor reports the automation as
+     `SKIP`, not `FAIL`.
+   - `exploratory-prds` follows the normal queue-resolution rules; if its prerequisites are
+     unresolved, preserve the exact blocking config fact.
+4. **Severity**
+   - Queue resolution failure is a doctor `FAIL`.
+   - Missing native scheduler support in an otherwise manually-usable repo is a doctor `WARN`.
+   - Intentional absence of an optional exploratory automation surface is a doctor `SKIP`.
+
+## Skill mapping
+
+The shim → vendor mapping is fixed:
+
+| Shim | jira tracker | github tracker | linear tracker |
+|------|--------------|----------------|----------------|
+| `lisa:tracker-write` | `lisa:jira-write-ticket` | `lisa:github-write-issue` | `lisa:linear-write-issue` |
+| `lisa:tracker-validate` | `lisa:jira-validate-ticket` | `lisa:github-validate-issue` | `lisa:linear-validate-issue` |
+| `lisa:tracker-verify` | `lisa:jira-verify` | `lisa:github-verify` | `lisa:linear-verify` |
+| `lisa:tracker-read` | `lisa:jira-read-ticket` | `lisa:github-read-issue` | `lisa:linear-read-issue` |
+| `lisa:tracker-evidence` | `lisa:jira-evidence` | `lisa:github-evidence` | `lisa:linear-evidence` |
+| `lisa:tracker-sync` | `lisa:jira-sync` | `lisa:github-sync` | `lisa:linear-sync` |
+| `lisa:tracker-add-journey` | `lisa:jira-add-journey` | `lisa:github-add-journey` | `lisa:linear-add-journey` |
+| `lisa:tracker-journey` | `lisa:jira-journey` | `lisa:github-journey` | `lisa:linear-journey` |
+| `lisa:tracker-create` | `lisa:jira-create` | `lisa:github-create` | `lisa:linear-create` |
+| `lisa:tracker-build-intake` | `lisa:jira-build-intake` | `lisa:github-build-intake` | `lisa:linear-build-intake` |
+
+The `tracker-source-artifacts` skill (formerly `tracker-source-artifacts`) is read-only and vendor-neutral — it has no shim and is invoked directly by every `*-to-tracker` skill and every destination write skill (`jira-write-ticket`, `github-write-issue`, `linear-write-issue`).
+
+## Caller responsibilities
+
+- **PRD-source skills** (`notion-to-tracker`, `confluence-to-tracker`, `linear-to-tracker`, `github-to-tracker`) MUST invoke `tracker-write` and `tracker-validate` — never `jira-write-ticket` / `github-write-issue` / `linear-write-issue` directly. This is what makes a project's destination switchable via config.
+- **Lifecycle skills** (`implement`, `verify`, `monitor`) MUST invoke `tracker-read`, `tracker-evidence`, `tracker-sync` for ticket interaction — never the vendor-specific equivalents.
+- **Per-vendor PRD intake skills** (`notion-prd-intake`, `confluence-prd-intake`, `linear-prd-intake`, `github-prd-intake`) compose the PRD-source skills (which in turn invoke the shims) — they do not need to read `tracker` themselves.
+- **Vendor-specific destination skills** (`jira-*`, `github-*`, `linear-*`) read their own vendor config section directly. They do NOT consult `tracker` — they are the targets of dispatch, not the dispatchers.
+
+## Linear destination semantics (best practices)
+
+Linear's data model differs from JIRA / GitHub. The destination mapping follows Linear's recommended patterns:
+
+| Concept (JIRA / GitHub) | Linear equivalent | Linear MCP write |
+|---|---|---|
+| Epic | **Project** (with milestones, target dates, lead, state) | `save_project` |
+| Story | **Issue** with `projectId` set, no `parentId` | `save_issue` |
+| Sub-task | **Sub-issue** with `parentId` = Story issue ID | `save_issue` |
+| Fix version | Linear **ProjectMilestone** (native, dated) | `save_project` (milestones array) |
+| Priority | Native `priority` field (0=No, 1=Urgent, 2=High, 3=Medium, 4=Low) | issue field |
+| Estimate / story points | Native `estimate` field | issue field |
+| Status workflow | **Labels** (`status:ready`, `status:in-progress`, `status:on-dev`, `status:done`) — portable across teams | issue labels |
+| Component | Label prefix `component:` | issue labels |
+| Issue links (blocks / relates / duplicates) | Native Linear relations | `save_issue_relation` |
+
+`linear-write-issue` is **polymorphic**: dispatches internally on `issue_type` (Epic → `save_project`, Story / Sub-task → `save_issue`). Parity with `jira-write-ticket` / `github-write-issue` is preserved at the shim level.
+
+Initiatives (Linear's cross-Project rollup) are NOT used — they're intended for cross-quarter, cross-team groupings rarely appropriate for an Epic. If a project ever needs Initiative-level grouping, that's a future extension to this rule.
+
+## Self-host edge case (GitHub PRDs → GitHub destination)
+
+When `github-to-tracker` is invoked AND `tracker = "github"`, both reads and writes hit the same GitHub repo. Label namespaces are kept separate so the two flows don't collide:
+
+- PRD-source labels: `prd-draft`, `prd-ready`, `prd-in-review`, `prd-blocked`, `prd-ticketed`, `prd-shipped`, `prd-verified` — owned by `github-prd-intake`, `verify-prd`, and the human PM.
+- Build-queue labels: `status:ready`, `status:in-progress`, `status:on-dev`, `status:done` — owned by `github-build-intake` and `github-agent`.
+- Sentinel issue label: `prd-intake-feedback` — owned by `github-prd-intake`.
+
+Never overload one label across both lifecycles.
+
+The same separation applies for Linear self-host (`source = "linear"` AND `tracker = "linear"`): project-level labels (`prd-*`) drive the PRD lifecycle; issue-level labels (`status:*`) drive the build lifecycle; the sentinel feedback issue carries the issue-level `prd-intake-feedback` label.
+
+## Notion access (substrate ladder)
+
+`notion-access` selects a substrate per operation in this order:
+
+1. **Notion MCP** — used when authenticated and its identity covers `notion.workspaceId`. Identity-match is verified by attempting to fetch `notion.prdDatabaseId` through the MCP; success means the MCP is authed to the correct workspace. If the MCP is authed elsewhere or unauthenticated, this tier is skipped.
+2. **curl + API token** — used when MCP isn't viable. Token is read via the standard lookup ladder (env → workspace-suffixed env → keychain → `tokenSource`).
+3. Fail with a clear diagnostic.
+
+(No CLI tier — Notion has no first-party CLI; community wrappers aren't taken as a dependency.)
+
+**Identity-match is mandatory.** A Notion MCP authed to the wrong workspace must be skipped, not used. `notion-access` verifies the configured `prdDatabaseId` is fetchable through the MCP before any operation; failure routes to the next tier.
+
+**Token type**: Notion **internal-integration tokens** (`ntn_*` prefix). Created at notion.so/profile/integrations or workspace settings → Connections → New integration. Each token is **bound to one workspace** by construction. There is no v1/v2 scope mess like Atlassian — the token's access is uniform across whichever pages have been explicitly shared with the integration.
+
+**Multi-account / multi-workspace**: same approach as Atlassian. The keychain entry is keyed by the workspace identifier (workspace id or human slug) declared in `.lisa.config.json` `notion.workspaceId`. Different projects targeting different Notion workspaces resolve to different keychain entries, no collision.
+
+**Per-page access**: Notion's integration model requires each PRD page (or the parent database) to be explicitly **shared** with the integration before the API can see it. `setup-notion` prompts the user to share the PRD database with the freshly-created integration; downstream lifecycle skills assume the share has happened and fail loudly if a page isn't visible.
+
+**Token storage and lookup ladder** (mirrors `atlassian-access`):
+
+```bash
+read_notion_token() {
+  local workspace="$1"
+  [ -n "$NOTION_API_TOKEN" ] && { echo "$NOTION_API_TOKEN"; return; }
+  local slug=$(echo "$workspace" | tr '[:upper:]-' '[:lower:]_')
+  local varname="NOTION_API_TOKEN_${slug}"
+  [ -n "${!varname}" ] && { echo "${!varname}"; return; }
+  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 && \
+             secret-tool lookup service lisa-notion account "$workspace" 2>/dev/null ;;
+    MINGW*|MSYS*|CYGWIN*)
+      # `cmdkey /generic ... /pass:` stores the secret in Windows Credential Manager, but
+      # `cmdkey /list` never prints stored passwords (by design). Read the CredentialBlob
+      # back via the Win32 CredRead API through PowerShell; pass the target name via an env
+      # var to dodge nested quoting, and strip the CRLF powershell.exe appends.
+      LISA_CRED_TARGET="lisa-notion-${workspace}" powershell.exe -NoProfile -NonInteractive -Command '
+Add-Type -TypeDefinition @"
+using System;
+using System.Runtime.InteropServices;
+public static class LisaCred {
+  [StructLayout(LayoutKind.Sequential)]
+  private struct CREDENTIAL {
+    public int Flags; public int Type; public IntPtr TargetName; public IntPtr Comment;
+    public System.Runtime.InteropServices.ComTypes.FILETIME LastWritten;
+    public int CredentialBlobSize; public IntPtr CredentialBlob; public int Persist;
+    public int AttributeCount; public IntPtr Attributes; public IntPtr TargetAlias; public IntPtr UserName;
+  }
+  [DllImport("advapi32.dll", CharSet=CharSet.Unicode, SetLastError=true)]
+  private static extern bool CredRead(string target, int type, int flags, out IntPtr credential);
+  [DllImport("advapi32.dll")] private static extern void CredFree(IntPtr cred);
+  public static string Read(string target) {
+    IntPtr p;
+    if (!CredRead(target, 1, 0, out p)) { return null; }
+    try {
+      CREDENTIAL c = (CREDENTIAL)Marshal.PtrToStructure(p, typeof(CREDENTIAL));
+      if (c.CredentialBlobSize == 0) { return String.Empty; }
+      return Marshal.PtrToStringUni(c.CredentialBlob, c.CredentialBlobSize / 2);
+    } finally { CredFree(p); }
+  }
+}
+"@
+[LisaCred]::Read($env:LISA_CRED_TARGET)' 2>/dev/null | tr -d '\r' ;;
+  esac
+}
+```
+
+**Schema additions** to `notion` section:
+
+```json
+"notion": {
+  "workspaceId":     "<uuid-or-human-slug>",
+  "prdDatabaseId":   "<uuid>",
+  "statusProperty":  "Status",
+  "values":          { "draft": "Draft", "ready": "Ready", ... }
+}
+```
+
+`workspaceId` is the connection-match key. The notion-access skill calls `GET /v1/users/me` with the token and verifies the returned `bot.workspace_name` (or workspace id when Notion exposes it) matches the configured value before allowing operations to proceed.
+
+## Confluence PRD lifecycle uses parent pages, not labels
+
+GitHub and Linear PRD lifecycles use labels (`prd-ready` / `prd-in-review` / etc.). **Confluence does not** — it uses parent pages instead. Each lifecycle role maps to a parent page; a PRD's current state is determined by which parent it's a child of; transitions are `PUT /wiki/api/v2/pages/{id}` with a new `parentId`.
+
+**Why this asymmetry exists**: scoped API tokens (the only secure form Atlassian offers) cannot write labels on Confluence pages. The v1 label endpoint `POST /wiki/rest/api/content/{id}/label` rejects scoped-token granular scopes with 401 "scope does not match"; the v2 Label API group has no POST endpoint at all (see open bug `CONFCLOUD-76866`). Until Atlassian ships v2 label writes, labels are read-only via scoped tokens. Parent-id transitions, by contrast, are first-class in v2 and work with `write:page:confluence` scope.
+
+**`confluence.parents` map**: each role's parent page id is stored in `.lisa.config.json` after `setup-confluence` creates the lifecycle scaffolding. Skills that need to discover the current state of a PRD read its `parentId` and reverse-lookup in `confluence.parents`. Skills that need to transition update the page's `parentId` to the new role's value.
+
+**Native UX benefit**: parent-page state shows up automatically in Confluence's left-sidebar page tree — users see PRDs grouped by state without ever opening the Dashboard page. The Dashboard is still produced, but as a `Children Display`-macro aggregation rather than `Content by Label`.
+
+## Atlassian access (substrate ladder)
+
+`atlassian-access` selects a substrate per operation in this order:
+
+1. **acli** — preferred when installed and authenticated, and when its active profile's site matches `atlassian.site` from config. `atlassian-access` calls `acli auth status` and compares the returned site/email to config before routing.
+2. **Atlassian MCP** — used when acli is unavailable for an op (e.g., Confluence page writes — acli has no `confluence page` write surface), or when acli isn't installed at all. Before routing, `atlassian-access` calls `getAccessibleAtlassianResources` and verifies `atlassian.cloudId` is in the returned list. If the configured cloudId isn't visible to the MCP's authed identity, the MCP tier is skipped.
+3. **curl + API token** — used when neither acli nor MCP is viable (headless, multi-account where MCP is authed elsewhere, scoped-token-only deployments). Token is read via the standard lookup ladder (env → email-suffixed env → keychain → `tokenSource`).
+4. Fail with a clear diagnostic listing what was attempted.
+
+**Identity-match is mandatory at every tier.** A substrate that's authenticated as the *wrong* Atlassian account is more dangerous than no substrate — it silently performs operations against the wrong workspace. `atlassian-access` verifies identity before every operation and skips substrates that don't match.
+
+**Why curl is still needed**: acli's Confluence surface only covers `space` and `page view`. v1 page-write endpoints accept scoped tokens but return 410 Gone (deprecated); v2 endpoints require granular OAuth scopes acli doesn't request. API tokens via Basic auth bypass this with full user scope, so curl is the headless-friendly path for ops neither acli nor MCP can do.
+
+## Repo scoping (multi-repo trackers)
+
+A ticketing system can oversee **multiple repos** — e.g. one JIRA project (or Linear team) for `frontend`, `backend`, and `infrastructure`. When build-intake runs inside one repo, it must claim only the tickets that belong to **that** repo and skip the rest. Two pieces make this work; the claim-time enforcement lives in the `repo-scope-split` rule.
+
+### The `repo:<name>` label (the repo marker)
+
+A work item's target repo is recorded as a **label** `repo:<name>`, where `<name>` is the repo's short name (e.g. `repo:frontend`). The convention is uniform across trackers (JIRA / GitHub / Linear), consistent with the other namespaced labels (`status:`, `type:`, `component:`). On JIRA a **component** equal to the repo name is accepted as an alias (matches the legacy `component = "frontend"` JQL pattern). A leaf work unit carries **exactly one** `repo:<name>` (leaves are single-repo per `repo-scope-split`); a container (Epic/Story/Spike) may carry several or none.
+
+The label is not required to exist up front: build-intake **determines** the target repo from the ticket's content + code surfaces when the label is absent and **stamps** `repo:<name>` so later cycles filter cheaply (see `repo-scope-split` "claim-time repo scoping").
+
+### Current-repo resolution (which repo am I?)
+
+Resolve the name of the repo intake is running in, highest priority first:
+
+1. `.lisa.config.local.json` then `.lisa.config.json` `repo` (an explicit override, e.g. `"repo": "frontend"`).
+2. `.lisa.config.json` `github.repo` when set (the repo's own identity).
+3. The git remote basename: `basename -s .git "$(git remote get-url origin)"` (e.g. `git@github.com:acme/frontend.git` → `frontend`).
+
+```bash
+read_g() { local lv gv; lv=$(jq -r "$1 // empty" .lisa.config.local.json 2>/dev/null); gv=$(jq -r "$1 // empty" .lisa.config.json 2>/dev/null); echo "${lv:-${gv}}"; }
+CURRENT_REPO=$(read_g '.repo')
+[ -z "$CURRENT_REPO" ] && CURRENT_REPO=$(read_g '.github.repo')
+[ -z "$CURRENT_REPO" ] && CURRENT_REPO=$(basename -s .git "$(git remote get-url origin 2>/dev/null)" 2>/dev/null)
+```
+
+If the current repo cannot be resolved by any tier, build-intake stops with a clear error rather than claiming tickets it cannot scope. The match is by repo short name (`repo:<CURRENT_REPO>`), case-insensitive.
+
+## Invariants
+
+- Project tracker selection is **persistent** within a project — always read from config, never infer from the shape of `$ARGUMENTS`. If a developer wants a different destination for one run, they edit `.lisa.config.local.json`.
+- **Developer-specific fields (e.g., `atlassian.email`) live in `.lisa.config.local.json`, never in the committed file.** The committed file describes the project (which site, which tracker, which space); the local file describes the developer's identity (which account, which profile, which override). Setup skills MUST write developer-specific fields to the local override and shared fields to the committed file.
+- A vendor-neutral skill never embeds vendor-specific terminology in its prompts (no "JIRA ticket key", "epic parent" — use "tracker key", "parent issue"). The vendor skill is responsible for translating its inputs.
+- The shim layer is intentionally thin — its only job is dispatch. Gate logic, validation rules, and field schemas all live in the vendor skills.
+- Secrets stay in env (`ATLASSIAN_API_TOKEN`, `NOTION_API_TOKEN`, `LINEAR_API_KEY`, `GH_TOKEN`). Configuration in `.lisa.config.json` is non-secret only — IDs, keys, slugs, project codes.
+- **`ATLASSIAN_API_TOKEN`** is required when the project uses JIRA or Confluence and any operation that acli doesn't cover (Confluence page writes, label edits, etc. — see `atlassian-access` skill's dispatch table). It's per-developer and per-project (different projects under different Atlassian accounts get different tokens). Setup-atlassian guides token generation and persists it to a gitignored `.envrc` (direnv) or `.env.lisa` (manual source); CI sets it directly as a pipeline secret. The token MUST belong to the account whose email is declared in `.lisa.config.local.json` `atlassian.email` — `atlassian-access` validates the pairing on first use of the curl substrate.
+- E2E test config (`E2E_BASE_URL`, `E2E_TEST_PHONE`, `E2E_TEST_OTP`, `E2E_TEST_ORG`, `E2E_GRAPHQL_URL`) stays in env for now — not tracker-related and frequently per-environment.
+
+## Migration from the previous schema
+
+The pre-expansion `.lisa.config.json` had only `tracker` and `github.{org,repo}`, and a missing `tracker` defaulted to `"jira"`. That default has been removed — `tracker` is now required.
+
+To migrate a project to the new requirements:
+
+1. Run `/lisa:setup:atlassian` (or `/lisa:setup:github`, `/lisa:setup:linear`) — installs the vendor MCP if needed, authenticates, and writes the vendor section.
+2. Run `/lisa:setup:jira` (or matching) — writes `jira.project` and prompts to set top-level `tracker`.
+3. Optionally run `/lisa:setup:confluence` / `/lisa:setup:notion` / etc. for source vendors — writes their sections and prompts to set top-level `source`.
+
+Projects that previously relied on the `"jira"` default will now fail loudly at the next vendor-neutral skill invocation; the error message points the user at the right setup skill.