@codyswann/lisa 2.21.1 → 2.23.1

package/plugins/src/base/agents/linear-prd-intake.md

@@ -1,6 +1,6 @@
 ---
 name: linear-prd-intake
-description: PRD intake agent for Linear-hosted PRDs. Runs one intake cycle against a Linear workspace or team — claims `prd-ready` projects (relabels to `prd-in-review`), validates each through the dry-run pipeline, and routes to `prd-blocked` (with clarifying comments on a sentinel feedback issue) or `prd-ticketed` (with JIRA tickets created). Linear counterpart of `notion-prd-intake` and `confluence-prd-intake`. Designed to be invoked manually via /linear-prd-intake or autonomously via a scheduled cron.
+description: PRD intake agent for Linear-hosted PRDs. Runs one intake cycle against a Linear workspace or team — claims projects carrying the configured `ready` PRD label (relabels to the configured `in_review` label), validates each through the dry-run pipeline, and routes to the configured `blocked` label (with clarifying comments on a sentinel feedback issue) or `ticketed` label (with destination tickets created). Linear counterpart of `notion-prd-intake` and `confluence-prd-intake`. Designed to be invoked manually via /linear-prd-intake or autonomously via a scheduled cron.
 skills:
   - linear-prd-intake
   - linear-to-tracker
@@ -17,9 +17,11 @@ You are a PRD intake agent. Your single job is to run one intake cycle against t
 
 This agent is the Linear counterpart of `notion-prd-intake` and `confluence-prd-intake`. The behavior is identical apart from the source-of-truth tool surface and one structural difference (clarifying comments land on a sentinel feedback issue under each project, not on the project page itself, because Linear's MCP doesn't expose project-level comments). If you have a Notion database, use the Notion agent; if you have a Confluence space, use the Confluence agent.
 
+PRD label role names (`ready`, `in_review`, `blocked`, `ticketed`, `shipped`, `sentinel`) are resolved from `.lisa.config.json` `linear.labels.prd.*` by the `linear-prd-intake` skill. The defaults match the legacy hardcoded names (`prd-ready`, `prd-in-review`, `prd-blocked`, `prd-ticketed`, `prd-shipped`, `prd-intake-feedback`).
+
 ## Confirmation policy
 
-Once you have a workspace or team scope, RUN. Do not ask the caller whether to proceed, do not preview projected scope, do not offer "proceed / skip / dry-run" choices. The caller has already authorized the run by invoking you; re-prompting defeats the purpose of a background batch. `prd-blocked` is a valid terminal state of the lifecycle, not a failure mode — large PRDs and PRDs full of open questions are exactly what this skill is for. The `linear-prd-intake` skill defines the only legitimate early-exit conditions (missing scope, unreachable workspace/team, label convention not yet adopted, empty Ready set); ask only when one of those applies.
+Once you have a workspace or team scope, RUN. Do not ask the caller whether to proceed, do not preview projected scope, do not offer "proceed / skip / dry-run" choices. The caller has already authorized the run by invoking you; re-prompting defeats the purpose of a background batch. The `blocked` label is a valid terminal state of the lifecycle, not a failure mode — large PRDs and PRDs full of open questions are exactly what this skill is for. The `linear-prd-intake` skill defines the only legitimate early-exit conditions (missing scope, unreachable workspace/team, label convention not yet adopted, empty ready set); ask only when one of those applies.
 
 ## Workflow
 
@@ -33,30 +35,30 @@ If no scope is provided, stop and ask. Never run intake against a default or gue
 
 Invoke the `linear-prd-intake` skill with the scope as `$ARGUMENTS`. The skill owns the cycle logic — claim, dry-run, branch, write or comment, label transitions, sentinel feedback issue management, summary. Do not duplicate that logic here.
 
-Treat the skill's output as the source of truth. If it reports `prd-ticketed: 3 / prd-blocked: 1 / Errors: 0`, that's what you report.
+Treat the skill's output as the source of truth (e.g. `ticketed: 3 / blocked: 1 / errors: 0`).
 
 ### 3. Surface the summary
 
 Pass the skill's summary block through to the caller verbatim — do not paraphrase or condense. The caller (often a human running `/linear-prd-intake` ad-hoc, or a scheduled cron) needs the structured record:
 
 - Total processed
-- Per-PRD outcomes (`prd-ticketed` → which tickets created; `prd-blocked` → how many gate failures; Errors → reason)
-- JIRA ticket count
+- Per-PRD outcomes (ticketed → which tickets created; blocked → how many gate failures; errors → reason)
+- Destination ticket count
 
 If the cycle errored before processing any PRDs (e.g. workspace unreachable, missing config, label convention not yet adopted), surface the failure cause in plain language and stop.
 
 ### 4. Suggest next actions when warranted
 
-After a successful cycle, if any PRDs ended in `prd-blocked`, mention to the caller that those PRDs need product attention before they can be re-ticketed. Do not auto-notify product — comments on the sentinel feedback issue (and on specific sub-issues for anchored failures) are the channel; the caller decides whether to ping anyone.
+After a successful cycle, if any PRDs ended in the `blocked` label, mention to the caller that those PRDs need product attention before they can be re-ticketed. Do not auto-notify product — comments on the sentinel feedback issue (and on specific sub-issues for anchored failures) are the channel; the caller decides whether to ping anyone.
 
-When reporting `prd-blocked` outcomes, distinguish the cause: **pre-write gate failure** (per-ticket validator caught a problem before any tickets were created) vs **post-write coverage gap** (tickets were created and remain in JIRA, but the PRD has uncovered requirements that the next intake cycle will address). Both result in `prd-blocked`, but the implication for product is different — coverage gaps mean some tickets are already real and product should not re-author the PRD from scratch.
+When reporting `blocked` outcomes, distinguish the cause: **pre-write gate failure** (per-ticket validator caught a problem before any tickets were created) vs **post-write coverage gap** (tickets were created and remain in the destination tracker, but the PRD has uncovered requirements that the next intake cycle will address). Both result in the `blocked` label, but the implication for product is different — coverage gaps mean some tickets are already real and product should not re-author the PRD from scratch.
 
-If all PRDs ended in `prd-ticketed` with coverage `COMPLETE`, mention that the next step is for product to monitor the created tickets and apply the `prd-shipped` label after delivery. If any are `COMPLETE_WITH_SCOPE_CREEP`, point that out so product can review the flagged tickets.
+If all PRDs ended in the `ticketed` label with coverage `COMPLETE`, mention that the next step is for product to monitor the created tickets and apply the configured `shipped` label after delivery. If any are `COMPLETE_WITH_SCOPE_CREEP`, point that out so product can review the flagged tickets.
 
 ## Rules
 
 - **Never run a cycle without an explicit scope.** Side effects are too high to default.
-- **Never modify the lifecycle**: only `prd-ready → prd-in-review → prd-blocked|prd-ticketed`. Never touch `prd-draft` or `prd-shipped`. Never invent new labels.
+- **Never modify the lifecycle**: only `ready → in_review → blocked|ticketed`. Never touch the `draft` or `shipped` labels. Never invent new labels.
 - **Never write destination tickets directly.** All writes go through the skill chain (intake → linear-to-tracker → tracker-write).
 - **Never edit a project's description or any attached Linear document.** Communication with product happens only via comments — on specific sub-issues for anchored failures, on the sentinel feedback issue otherwise.
 - **Never close, archive, or repurpose the sentinel feedback issue.** It is reused across cycles; its longevity is the audit trail.

package/plugins/src/base/agents/notion-prd-intake.md

@@ -1,6 +1,6 @@
 ---
 name: notion-prd-intake
-description: PRD intake agent. Runs one intake cycle against a Notion PRD database — claims Ready PRDs, validates each through the dry-run pipeline, and routes to Blocked (with clarifying comments) or Ticketed (with JIRA tickets created). Designed to be invoked manually via /notion-prd-intake or autonomously via a scheduled cron.
+description: PRD intake agent. Runs one intake cycle against a Notion PRD database — claims PRDs in the configured `ready` status, validates each through the dry-run pipeline, and routes to the `blocked` status (with clarifying comments) or the `ticketed` status (with destination tickets created). Designed to be invoked manually via /notion-prd-intake or autonomously via a scheduled cron.
 skills:
   - notion-prd-intake
   - notion-to-tracker
@@ -15,9 +15,11 @@ skills:
 
 You are a PRD intake agent. Your single job is to run one intake cycle against the Notion PRD database whose URL is given to you, then report what happened.
 
+Status role names (`draft`, `ready`, `in_review`, `blocked`, `ticketed`, `shipped`) are resolved from `.lisa.config.json` `notion.values.*` by the `notion-prd-intake` skill. The defaults match the legacy hardcoded names (`Draft`, `Ready`, `In Review`, `Blocked`, `Ticketed`, `Shipped`).
+
 ## Confirmation policy
 
-Once you have a database URL, RUN. Do not ask the caller whether to proceed, do not preview projected scope, do not offer "proceed / skip / dry-run" choices. The caller has already authorized the run by invoking you; re-prompting defeats the purpose of a background batch. `Blocked` is a valid terminal state of the lifecycle, not a failure mode — large PRDs and PRDs full of open questions are exactly what this skill is for. The `notion-prd-intake` skill defines the only legitimate early-exit conditions (missing URL, misconfigured database, empty Ready set); ask only when one of those applies.
+Once you have a database URL, RUN. Do not ask the caller whether to proceed, do not preview projected scope, do not offer "proceed / skip / dry-run" choices. The caller has already authorized the run by invoking you; re-prompting defeats the purpose of a background batch. The `blocked` status is a valid terminal state of the lifecycle, not a failure mode — large PRDs and PRDs full of open questions are exactly what this skill is for. The `notion-prd-intake` skill defines the only legitimate early-exit conditions (missing URL, misconfigured database, empty ready set); ask only when one of those applies.
 
 ## Workflow
 
@@ -31,30 +33,30 @@ If no URL is provided, stop and ask. Never run intake against a default or guess
 
 Invoke the `notion-prd-intake` skill with the database URL as `$ARGUMENTS`. The skill owns the cycle logic — claim, dry-run, branch, write or comment, status transition, summary. Do not duplicate that logic here.
 
-Treat the skill's output as the source of truth. If it reports `Ticketed: 3 / Blocked: 1 / Errors: 0`, that's what you report.
+Treat the skill's output as the source of truth (e.g. `ticketed: 3 / blocked: 1 / errors: 0`).
 
 ### 3. Surface the summary
 
 Pass the skill's summary block through to the caller verbatim — do not paraphrase or condense. The caller (often a human running `/notion-prd-intake` ad-hoc, or a future schedule wrapper) needs the structured record:
 
 - Total processed
-- Per-PRD outcomes (Ticketed → which tickets created; Blocked → how many gate failures; Errors → reason)
-- JIRA ticket count
+- Per-PRD outcomes (ticketed → which tickets created; blocked → how many gate failures; errors → reason)
+- Destination ticket count
 
 If the cycle errored before processing any PRDs (e.g. database misconfigured, missing config), surface the failure cause in plain language and stop.
 
 ### 4. Suggest next actions when warranted
 
-After a successful cycle, if any PRDs ended in `Blocked`, mention to the caller that those PRDs need product attention before they can be re-ticketed. Do not auto-notify product — Notion comments on the PRDs are the channel; the caller decides whether to ping anyone.
+After a successful cycle, if any PRDs ended in the `blocked` status, mention to the caller that those PRDs need product attention before they can be re-ticketed. Do not auto-notify product — Notion comments on the PRDs are the channel; the caller decides whether to ping anyone.
 
-When reporting Blocked outcomes, distinguish the cause: **pre-write gate failure** (per-ticket validator caught a problem before any tickets were created) vs **post-write coverage gap** (tickets were created and remain in JIRA, but the PRD has uncovered requirements that the next intake cycle will address). Both result in `Status = Blocked`, but the implication for product is different — coverage gaps mean some tickets are already real and product should not re-author the PRD from scratch.
+When reporting `blocked` outcomes, distinguish the cause: **pre-write gate failure** (per-ticket validator caught a problem before any tickets were created) vs **post-write coverage gap** (tickets were created and remain in the destination tracker, but the PRD has uncovered requirements that the next intake cycle will address). Both result in the `blocked` status, but the implication for product is different — coverage gaps mean some tickets are already real and product should not re-author the PRD from scratch.
 
-If all PRDs ended in `Ticketed` with coverage `COMPLETE`, mention that the next step is for product to monitor the created tickets and flip the PRDs to `Shipped` after delivery. If any are `COMPLETE_WITH_SCOPE_CREEP`, point that out so product can review the flagged tickets.
+If all PRDs ended in the `ticketed` status with coverage `COMPLETE`, mention that the next step is for product to monitor the created tickets and flip the PRDs to the configured `shipped` status after delivery. If any are `COMPLETE_WITH_SCOPE_CREEP`, point that out so product can review the flagged tickets.
 
 ## Rules
 
 - **Never run a cycle without an explicit database URL.** Side effects are too high to default.
-- **Never modify the lifecycle**: only `Ready → In Review → Blocked|Ticketed`. Never touch `Draft` or `Shipped`. Never invent new status values.
+- **Never modify the lifecycle**: only `ready → in_review → blocked|ticketed`. Never touch `draft` or `shipped`. Never invent new status values.
 - **Never write destination tickets directly.** All writes go through the skill chain (intake → notion-to-tracker → tracker-write). Bypassing this skips quality gates.
 - **Never edit a PRD's body.** Communication with product happens only via Notion comments on the PRD.
 - **Never start a second cycle while one is in flight against the same database.** This agent assumes serial execution; the scheduling layer is responsible for not double-firing.

package/plugins/src/base/agents/pr-mining-specialist.md

@@ -80,6 +80,6 @@ If there are no findings under a checklist row, write `(none)`.
 - **Never judge.** Surface every match. The synthesizer reconciles signal vs. noise.
 - **Quote verbatim.** Don't paraphrase review comments; the exact wording often carries the learning.
 - **Link, don't summarize.** Every finding has at least one evidence link (PR comment anchor, commit URL, file blob URL).
-- **Run within the team.** Do not call `TeamCreate`. The Debrief skill created the team; you are a teammate.
+- **Run within the team.** Do not create a second team. The Debrief skill created the team; you are a teammate.
 - **Read-only.** No `gh pr merge`, no `gh pr review`, no commits. You observe; you do not mutate.
 - **Parallel-safe.** You run alongside `tracker-mining-specialist`; do not coordinate with them. The synthesizer reconciles.

package/plugins/src/base/agents/tracker-mining-specialist.md

@@ -80,6 +80,6 @@ If there are no findings under a checklist row, write `(none)` — silence is it
 - **Never judge.** "Probably not interesting" is not a category. Every signal that matches a checklist row goes in.
 - **Quote verbatim.** Paraphrasing comments loses author voice and the specifics that make a finding actionable.
 - **Link, don't summarize.** Every finding has at least one evidence link to the source artifact (comment URL, ticket URL fragment, PR URL).
-- **Run within the team.** Do not call `TeamCreate`. The Debrief skill created the team; you are a teammate.
+- **Run within the team.** Do not create a second team. The Debrief skill created the team; you are a teammate.
 - **Read-only.** Never call write MCP tools. You report; you do not mutate.
 - **Parallel-safe.** You run alongside `pr-mining-specialist`; do not coordinate with them. The synthesizer reconciles.

package/plugins/src/base/commands/setup/atlassian.md

@@ -0,0 +1,7 @@
+---
+description: "Set up Atlassian (cloudId + acli profile) for this project. Writes the `atlassian` section of `.lisa.config.json` and enables the Atlassian MCP and/or installs acli as needed. Prerequisite for /lisa:setup:jira and /lisa:setup:confluence."
+allowed-tools: ["Skill"]
+argument-hint: "[--site=<site>] [--email=<email>]"
+---
+
+Use the /lisa:setup-atlassian skill to configure Atlassian access for this project. $ARGUMENTS

package/plugins/src/base/commands/setup/confluence.md

@@ -0,0 +1,7 @@
+---
+description: "Set up Confluence as the PRD source for this project. Writes the `confluence` section of `.lisa.config.json` (spaceKey and/or parentPageId) and offers to set top-level `source: \"confluence\"`. Depends on /lisa:setup:atlassian."
+allowed-tools: ["Skill"]
+argument-hint: "[--space=<KEY>] [--parent=<pageId>]"
+---
+
+Use the /lisa:setup-confluence skill to configure Confluence as the PRD source. $ARGUMENTS

package/plugins/src/base/commands/setup/jira.md

@@ -0,0 +1,7 @@
+---
+description: "Set up JIRA as the tracker for this project. Writes `jira.project` and offers to set top-level `tracker: \"jira\"` in `.lisa.config.json`. Depends on /lisa:setup:atlassian (needs cloudId)."
+allowed-tools: ["Skill"]
+argument-hint: "[--project=<KEY>]"
+---
+
+Use the /lisa:setup-jira skill to configure JIRA as the project tracker. $ARGUMENTS

package/plugins/src/base/commands/setup/notion.md

@@ -0,0 +1,7 @@
+---
+description: "Set up Notion as the PRD source for this project. Walks the user through creating a workspace-scoped internal-integration token, sharing the PRD database with it, and stores the token in OS keychain. Writes `notion.workspaceId`, `notion.prdDatabaseId`, and `notion.values` into `.lisa.config.json`. Offers to set top-level `source: \"notion\"`."
+allowed-tools: ["Skill"]
+argument-hint: "[--database=<uuid>] [--workspace=<slug>]"
+---
+
+Use the /lisa:setup-notion skill to configure Notion as the PRD source. $ARGUMENTS

package/plugins/src/base/hooks/enforce-team-first.sh

@@ -1,18 +1,22 @@
 #!/usr/bin/env bash
-# Enforces team-first orchestration for lifecycle skills.
+# Enforces Claude's TeamCreate-first orchestration for lifecycle skills.
+#
+# This hook is intentionally Claude-specific. Other harnesses may use different
+# team tooling or an explicit no-team fallback; those paths are described in the
+# shared rules/skills but are not enforced by this Claude hook.
 #
 # Triggered on four hook events:
 #   - UserPromptSubmit  : detects /lisa:research|plan|implement|intake|debrief in the
 #                         raw prompt and arms enforcement for the session
 #   - PreToolUse        : detects the same skills via a `Skill` tool call,
 #                         arms enforcement, and blocks bypass tool calls
-#                         until ToolSearch+TeamCreate have fired
-#   - PostToolUse       : on a successful TeamCreate, marks the session as
+#                         until ToolSearch+TeamCreate have fired in Claude
+#   - PostToolUse       : on a successful Claude TeamCreate, marks the session as
 #                         team-created (lifts enforcement)
 #   - SubagentStart     : marks the new subagent session as a teammate so
 #                         it is exempt — teammates inherit the lead's team
-#                         and must never call TeamCreate (double-create
-#                         is rejected by the harness)
+#                         and must never create a second team (double-create
+#                         is rejected by the Claude harness)
 #
 # Per-session state lives under "$STATE_DIR" as flag files keyed by
 # session_id. Stale state (>24h) is cleaned on each invocation.
@@ -159,7 +163,7 @@ fi
 ACTIVE_SKILL=$(cat "$SKILL_FLAG" 2>/dev/null || echo "lisa:???")
 cat >&2 <<EOF
 Blocked: this session invoked /${ACTIVE_SKILL}, which is an agent-team flow.
-Before any other tool call, you must:
+In Claude, before any other tool call, you must:
 
   1. ToolSearch with query: "select:TeamCreate"  (load the deferred schema)
   2. TeamCreate                                   (actually create the team)
@@ -169,6 +173,10 @@ the ticket, exploring the code, fetching context — those are tasks for the
 team you are about to create, not for the lead session before the team
 exists.
 
+If you are running Lisa in a non-Claude harness, this Claude enforcement hook
+should not be installed; follow the runtime-aware orchestration preamble in the
+skill instead.
+
 Re-read the orchestration preamble in /${ACTIVE_SKILL} and start with
 ToolSearch.
 EOF

package/plugins/src/base/rules/base-rules.md

@@ -8,7 +8,7 @@ After echoing the chosen flow and BEFORE doing any work, state the orchestration
 
 Default to an agent team for Research, Plan, Implement (Build/Fix/Improve/Investigate-Only), and any flow that invokes the Review sub-flow. Use a single agent only for Verify (standalone) and Monitor (standalone). See the `intent-routing` rule's Orchestration section for the full decision matrix.
 
-When the mode is `agent team` **and you are not already operating inside an agent team**, your FIRST tool calls after the classification echo MUST be `ToolSearch` with `query: "select:TeamCreate"` (to load the deferred tool's schema), then `TeamCreate`. Do not reach for `TaskCreate`, `Agent`, `Skill`, MCP tools, `Read`, `Bash`, or any other content-gathering call before the team exists — those are bypass paths that skip durable task state and parallel review. Reading the ticket, exploring the code, querying the API are all tasks for the team, not for the lead session before the team exists.
+When the mode is `agent team` **and you are not already operating inside an agent team**, your FIRST tool calls after the classification echo MUST establish team orchestration before any content-gathering work. Use `TeamCreate` if available. In Claude, if `TeamCreate` has not been loaded yet, first use `ToolSearch` with `query: "select:TeamCreate"` to load its schema. If `TeamCreate` is not available, use the current runtime's tool-discovery mechanism (for Codex, `tool_search`) to discover available multi-agent/team tools, then call the appropriate team creation tool. If no team creation tool is available, explicitly state that team orchestration is unavailable in this runtime, continue as the lead agent, and preserve the workflow's review, verification, and task-tracking obligations locally. Do not reach for `TaskCreate`, `Agent`, `Skill`, MCP tools, `Read`, `Bash`, or any other content-gathering call before the team exists or the no-team fallback has been declared — those are bypass paths that skip durable task state and parallel review. Reading the ticket, exploring the code, querying the API are all tasks for the team, not for the lead session before orchestration exists.
 
 Requirement Verification:
 
@@ -70,7 +70,7 @@ JIRA Discipline:
 - When reading a JIRA issue, always read ALL comments on the ticket — not just the description. Comments contain critical context: stakeholder decisions, scope changes, blockers, triage findings from other repos, and implementation notes. Use the Atlassian MCP or `jira issue view <TICKET_ID> --comments 100` to fetch them.
 - When requesting clarification on a JIRA issue, post the question as a comment using ADF (Atlassian Document Format) and @mention the Reporter so they receive a notification.
 - When creating JIRA tickets, establish issue link relationships (e.g. "is blocked by", "blocks", "relates to", "is duplicated by") between tickets that have dependencies or logical connections. Do not leave related tickets unlinked. Relationship discovery is mandatory on every create and update — search BOTH the local git history (`git log --all --grep=<keyword>`, `git log -- <path>`) AND Jira (JQL by component, keyword, label, epic siblings) before declaring "no related work." Record the searches you ran and their outcomes in the description (or a comment) so a reviewer can see the search was real.
-- Ticket scope by type: Bug, Task, and Sub-task tickets MUST be single-repo (one work unit, one repo). Epic, Spike, and Story tickets MAY span multiple repos. If a Bug/Task/Sub-task crosses repos, split it.
+- Ticket scope by type: Bug, Task, and Sub-task tickets MUST be single-repo (one work unit, one repo). Epic, Spike, and Story tickets MAY span multiple repos. If a Bug/Task/Sub-task crosses repos, split it per the `repo-scope-split` rule — at PRD-decomposition time via `task-decomposition` step 1.5 (parent Story + per-repo children); at work-time (an existing ticket an agent is about to implement) via the work-time split procedure (narrow the original to one repo, spin off a sibling per additional repo cloning its metadata, link the producer→consumer dependency, then proceed). A cross-repo work unit is a decomposition error the agent fixes by splitting, not a reason to bounce the ticket to the reporter.
 - Ticket descriptions MUST contain everything an implementer needs to start work without asking the reporter. In particular:
   - **Target backend environment** (`dev` / `staging` / `prod`) when the ticket has runtime behavior. QA/product report against a deployed env; the implementer verifies locally first against that backend before CI/CD. Skip only for doc-only, config-only, type-only, or Epic tickets.
   - **Sign-in account / credentials** when the work requires being signed in. Name the account (or the source — 1Password item, env var, seeded fixture) and the role. Omit entirely when sign-in is not required.
@@ -130,4 +130,4 @@ When you detect any of the above:
 1. Do NOT guess or make assumptions about what the external code does
 2. Identify which repository contains the missing code
 3. Add that repository to your current session before proceeding
-4. If you cannot determine which repository contains the code, ask — do not proceed without it
+4. If you cannot determine which repository contains the code, ask — do not proceed without it

package/plugins/src/base/rules/config-resolution.md

@@ -18,9 +18,15 @@ 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:-jira}}"
+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
@@ -28,12 +34,88 @@ tracker="${local_value:-${global_value:-jira}}"
   "tracker": "jira",
   "source":  "notion",
 
-  "atlassian":  { "cloudId": "<uuid>" },
-  "jira":       { "project": "<KEY>" },
-  "confluence": { "spaceKey": "<KEY>", "parentPageId": "<id>" },
-  "github":     { "org": "<org-or-user>", "repo": "<repo>" },
-  "notion":     { "prdDatabaseId": "<uuid>", "statusProperty": "Status", "readyValue": "Ready" },
-  "linear":     { "workspace": "<workspace-slug>", "teamKey": "<TEAM>" }
+  "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>"
+    },
+    "dashboardPageId": "<page-id>",
+    "feedbackPageId":  "<page-id>"
+  },
+  "github": {
+    "org": "<org-or-user>",
+    "repo": "<repo>",
+    "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",
+        "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"
+    }
+  },
+  "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",
+        "sentinel": "prd-intake-feedback"
+      }
+    }
+  },
+
+  "deploy": {
+    "branches": {
+      "dev":        "dev",
+      "staging":    "staging",
+      "production": "main"
+    }
+  }
 }
 ```
 
@@ -41,7 +123,7 @@ tracker="${local_value:-${global_value:-jira}}"
 
 | Field | Required | Default | Notes |
 |-------|----------|---------|-------|
-| `tracker` | no | `"jira"` | Destination for ticket writes. One of `"jira"`, `"github"`, `"linear"`. Missing key resolves to `"jira"` for back-compat. |
+| `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. |
 
 ### Vendor sections
@@ -50,9 +132,11 @@ Each vendor section is **conditionally required**: required only when that vendo
 
 #### `atlassian`
 
-| Field | Required when | Notes |
-|-------|---------------|-------|
-| `atlassian.cloudId` | `tracker = "jira"`, `source = "jira"`, `source = "confluence"`, or any `confluence-*` / `jira-*` skill is invoked | Atlassian Cloud site UUID. Resolve once via the Atlassian MCP `getAccessibleAtlassianResources` and paste in. Shared between JIRA and Confluence (same Atlassian site). If a project ever needs separate sites for JIRA vs Confluence, override via `jira.cloudId` / `confluence.cloudId` (not currently implemented — file an issue). |
+| 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`
 
@@ -78,11 +162,12 @@ When `tracker = "github"` AND `source = "github"` (self-host), both reads and wr
 
 #### `notion`
 
-| Field | Required when | Notes |
-|-------|---------------|-------|
-| `notion.prdDatabaseId` | `source = "notion"` | Notion database ID (UUID, dashes optional). The database is the PRD queue. |
-| `notion.statusProperty` | `source = "notion"` | Name of the database property that drives the lifecycle. Defaults to `"Status"` if absent. |
-| `notion.readyValue` | `source = "notion"` | Status value that means "ready for ticketing". Defaults to `"Ready"` if absent. The full lifecycle (Ready → In Review → Blocked / Ticketed → Shipped) is hardcoded; only the entry-point value name is configurable for now. |
+| 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`). Defaults match the role names in title case. Override here if your Notion DB uses different value names. |
 
 #### `linear`
 
@@ -91,12 +176,70 @@ When `tracker = "github"` AND `source = "github"` (self-host), both reads and wr
 | `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. |
 
+## 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` | Build complete, in code review | `Code Review` (status) | `status:code-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 required for label-driven systems (GitHub, Linear) because that's how the agent signals "PR opened, awaiting human review." For JIRA, `review` is optional — 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) |
+| `sentinel` | (PRD-intake feedback issue marker, GitHub/Linear self-host only) | — | `prd-intake-feedback` |
+
+### 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).
+
+### 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`. Lisa 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, default to `"jira"`.
+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.
@@ -167,21 +310,96 @@ 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 /list:"lisa-notion-${workspace}" 2>/dev/null | grep Password | awk '{print $NF}' ;;
+  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.
+
 ## 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 (`JIRA_API_TOKEN`, `LINEAR_API_KEY`, `GH_TOKEN`, `NOTION_API_KEY`, `ATLASSIAN_API_TOKEN`). Configuration in `.lisa.config.json` is non-secret only — IDs, keys, slugs, project codes.
+- 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}`. Existing projects continue to work — the new fields are all conditionally required, and `tracker = "jira"` (the default) only requires `atlassian.cloudId` and `jira.project`, which were previously read from env (`JIRA_SERVER`, `JIRA_PROJECT`).
+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:
 
-To migrate a project off env vars:
+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`.
 
-1. Add `atlassian.cloudId` (resolve via `getAccessibleAtlassianResources` once).
-2. Add `jira.project` (was `JIRA_PROJECT`).
-3. Drop `JIRA_SERVER` from env (replaced by `atlassian.cloudId`).
-4. Optionally add `source` to set the default PRD source for batch skills.
+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.