@codyswann/lisa 2.21.1 → 2.23.1

package/plugins/src/base/skills/linear-prd-intake/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: linear-prd-intake
-description: "Scans a Linear workspace (or a specific team) for projects labelled `prd-ready` and runs each one through the dry-run validation pipeline. Projects that pass every gate get tickets written and the label flipped to `prd-ticketed`; projects that fail get clarifying-question comments (on a sentinel feedback issue under the project) and the label flipped to `prd-blocked`. Linear counterpart of `lisa:notion-prd-intake` and `lisa:confluence-prd-intake` — the workflow is identical; only the source-of-truth tools differ. Composes existing skills (linear-to-tracker, tracker-validate, tracker-source-artifacts, product-walkthrough)."
+description: "Scans a Linear workspace (or a specific team) for projects carrying the configured `ready` PRD label and runs each one through the dry-run validation pipeline. Projects that pass every gate get tickets written and the label flipped to the configured `ticketed` label; projects that fail get clarifying-question comments (on a sentinel feedback issue under the project) and the label flipped to the configured `blocked` label. Linear counterpart of `lisa:notion-prd-intake` and `lisa:confluence-prd-intake` — the workflow is identical; only the source-of-truth tools differ. Composes existing skills (linear-to-tracker, tracker-validate, tracker-source-artifacts, product-walkthrough)."
 allowed-tools: ["Skill", "Bash", "mcp__linear-server__list_projects", "mcp__linear-server__get_project", "mcp__linear-server__save_project", "mcp__linear-server__list_project_labels", "mcp__linear-server__list_issues", "mcp__linear-server__get_issue", "mcp__linear-server__save_issue", "mcp__linear-server__list_comments", "mcp__linear-server__save_comment", "mcp__linear-server__list_issue_labels", "mcp__linear-server__create_issue_label", "mcp__linear-server__list_documents", "mcp__linear-server__get_document", "mcp__linear-server__list_teams"]
 ---
 
@@ -8,52 +8,78 @@ allowed-tools: ["Skill", "Bash", "mcp__linear-server__list_projects", "mcp__line
 
 `$ARGUMENTS` is one of:
 
-- A Linear **workspace** URL — scans every project in the workspace whose labels include `prd-ready`. Example: `https://linear.app/acme`.
-- A Linear **team** URL or team key — scans every project on the team whose labels include `prd-ready`. Example: `https://linear.app/acme/team/ENG/projects` or bare `ENG`.
+- A Linear **workspace** URL — scans every project in the workspace whose labels include the configured `ready` label. Example: `https://linear.app/acme`.
+- A Linear **team** URL or team key — scans every project on the team whose labels include the configured `ready` label. Example: `https://linear.app/acme/team/ENG/projects` or bare `ENG`.
 - The literal token `linear` — equivalent to "the default Linear workspace"; only valid if `linear.workspace` is configured in `.lisa.config.json`.
 
-Run one intake cycle against that scope. Each project with the `prd-ready` label is claimed, validated, and routed to either `prd-blocked` (with clarifying comments on a sentinel feedback issue) or `prd-ticketed` (with JIRA tickets created).
+Run one intake cycle against that scope. Each project with the `ready` label is claimed, validated, and routed to either the `blocked` label (with clarifying comments on a sentinel feedback issue) or the `ticketed` label (with destination tickets created).
 
-This skill is the Linear counterpart of `lisa:notion-prd-intake` and `lisa:confluence-prd-intake`. The phases, gates, comment templates, and rules are identical — the only differences are (1) the lifecycle is encoded as **project labels** instead of a Status property, (2) the fetch / update tools are Linear MCP, and (3) clarifying-question comments land on a sentinel feedback Issue under the project (because Linear's MCP does not expose project-level comments). Keep all three skills behaviorally aligned: when changing intake logic, change them together.
+## Workflow resolution
+
+PRD label names are read from `.lisa.config.json` `linear.labels.prd.*`, falling back to defaults documented in the `config-resolution` rule. Bash pattern:
+
+```bash
+# Read role with default fallback. Local overrides global per-key.
+read_role() {
+  local role="$1" default="$2"
+  local local_v global_v
+  local_v=$(jq -r ".linear.labels.prd.${role} // empty" .lisa.config.local.json 2>/dev/null)
+  global_v=$(jq -r ".linear.labels.prd.${role} // empty" .lisa.config.json 2>/dev/null)
+  echo "${local_v:-${global_v:-$default}}"
+}
+
+READY=$(read_role ready "prd-ready")
+IN_REVIEW=$(read_role in_review "prd-in-review")
+BLOCKED=$(read_role blocked "prd-blocked")
+TICKETED=$(read_role ticketed "prd-ticketed")
+SHIPPED=$(read_role shipped "prd-shipped")
+SENTINEL=$(read_role sentinel "prd-intake-feedback")
+```
+
+In prose below, the role names refer to the resolved labels: e.g. "the `ready` label" means whatever `linear.labels.prd.ready` resolves to (default: `prd-ready`).
+
+This skill is the Linear counterpart of `lisa:notion-prd-intake` and `lisa:confluence-prd-intake`. The phases, gates, comment templates, and rules are identical — the only differences are (1) the lifecycle is encoded as **project labels** instead of a status property, (2) the fetch / update tools are Linear MCP, and (3) clarifying-question comments land on a sentinel feedback Issue under the project (because Linear's MCP does not expose project-level comments). Keep all three skills behaviorally aligned: when changing intake logic, change them together.
 
 ## Confirmation policy
 
-Do NOT ask the caller whether to proceed. Once invoked with a workspace/team scope, run the cycle to completion — claim, validate, branch to `prd-blocked` or `prd-ticketed`, write the summary. The caller (a human or a cron) has already authorized the run by invoking the skill; re-prompting defeats the purpose of a background batch.
+Do NOT ask the caller whether to proceed. Once invoked with a workspace/team scope, run the cycle to completion — claim, validate, branch to `$BLOCKED` or `$TICKETED`, write the summary. The caller (a human or a cron) has already authorized the run by invoking the skill; re-prompting defeats the purpose of a background batch.
 
 Specifically forbidden:
 
 - Previewing projected scope (epic count, story count, write count) and asking whether to continue.
 - Offering A/B/C-style choices like "proceed / skip / dry-run only" — the documented behavior IS the default.
-- Pausing because a PRD looks large, has many open questions, or is likely to end in `prd-blocked`. `prd-blocked` is a valid terminal state of this lifecycle, not a failure mode — routing a PRD to `prd-blocked` with gate-failure comments is exactly how this skill communicates "the PRD needs more work before it can be ticketed." That outcome is success.
+- Pausing because a PRD looks large, has many open questions, or is likely to end in `$BLOCKED`. The `blocked` label is a valid terminal state of this lifecycle, not a failure mode — routing a PRD there with gate-failure comments is exactly how this skill communicates "the PRD needs more work before it can be ticketed." That outcome is success.
 - Pausing because the dry-run validation looks expensive. The cost of one cycle is bounded; the cost of stalling a scheduled cron waiting on a human is unbounded.
 
 The only legitimate reasons to stop early:
 
 - Missing scope argument or required configuration (`linear.workspace` in `.lisa.config.json`, `E2E_BASE_URL`, etc.). Surface the missing key(s) and exit this cycle — never invent values.
-- Workspace/team unreachable, or the labelling convention not yet adopted (no projects carry any of `prd-ready` / `prd-in-review` / `prd-blocked` / `prd-ticketed`). Surface and exit.
-- Empty `prd-ready` set. Exit cleanly with `"No Linear projects labelled prd-ready. Nothing to do."`
+- Workspace/team unreachable, or the labelling convention not yet adopted (no projects carry any of `$READY` / `$IN_REVIEW` / `$BLOCKED` / `$TICKETED`). Surface and exit.
+- Empty ready set. Exit cleanly with `"No Linear projects labelled $READY. Nothing to do."`
 
 ## Lifecycle assumed
 
 The Linear PRD lifecycle is encoded as **project labels** (we deliberately do NOT key off Linear's native project state, since project state is product's day-to-day signal and we don't want to fight it). Exactly one of these labels is expected on a project at any time:
 
 ```text
-prd-draft → prd-ready → prd-in-review → prd-blocked | prd-ticketed → prd-shipped
-            (product)    (us)            (us)                          (product)
+draft → ready → in_review → blocked | ticketed → shipped
+        (product)  (us)      (us)                  (product)
 ```
 
+(Defaults: `prd-draft` / `prd-ready` / `prd-in-review` / `prd-blocked` / `prd-ticketed` / `prd-shipped`.)
+
 This skill ONLY transitions:
 
-- `prd-ready` → `prd-in-review` (claim)
-- `prd-in-review` → `prd-blocked` (gate failures or coverage gaps)
-- `prd-in-review` → `prd-ticketed` (success)
-- `prd-ticketed` → `prd-blocked` (post-write coverage gaps from Phase 3e)
+- `$READY` → `$IN_REVIEW` (claim)
+- `$IN_REVIEW` → `$BLOCKED` (gate failures or coverage gaps)
+- `$IN_REVIEW` → `$TICKETED` (success)
+- `$TICKETED` → `$BLOCKED` (post-write coverage gaps from Phase 3e)
 
-It never adds, removes, or touches `prd-draft` or `prd-shipped`. Those labels are owned by product.
+It never adds, removes, or touches the `draft` or `shipped` labels. Those labels are owned by product.
 
 A "transition" means: remove the old lifecycle label and add the new one in a single `save_project` call (passing the full new label set in the `labels` array). The skill MUST verify that exactly one lifecycle label exists on the project after the update — having two simultaneously breaks idempotency.
 
-If the project does not yet use `prd-*` labels, this skill cannot run. Adopting the convention is a one-time setup the project owner does (see "Adoption" at the bottom of this file).
+If the project does not yet use these labels, this skill cannot run. Adopting the convention is a one-time setup the project owner does (see "Adoption" at the bottom of this file).
 
 ## Phases
 
@@ -67,32 +93,32 @@ If the project does not yet use `prd-*` labels, this skill cannot run. Adopting
 2. Verify the scope is reachable:
    - For a workspace: call `mcp__linear-server__list_teams` and confirm at least one team is returned (non-empty workspaces are readable; empty results indicate auth or workspace-mismatch).
    - For a team: call `mcp__linear-server__list_teams({query: <KEY>})` and confirm the team resolves.
-3. Resolve the project-label IDs for `prd-ready`, `prd-in-review`, `prd-blocked`, `prd-ticketed` via `mcp__linear-server__list_project_labels`. Cache them — every transition uses these IDs. If any of the four are missing, surface a label-convention error and exit (see "Adoption").
+3. Resolve the project-label IDs for `$READY`, `$IN_REVIEW`, `$BLOCKED`, `$TICKETED` via `mcp__linear-server__list_project_labels`. Cache them — every transition uses these IDs. If any of the four are missing, surface a label-convention error and exit (see "Adoption").
 
-### Phase 2 — Find Ready PRDs
+### Phase 2 — Find ready PRDs
 
-Call `mcp__linear-server__list_projects({label: "prd-ready", ...scope-filter})`:
+Call `mcp__linear-server__list_projects({label: "$READY", ...scope-filter})`:
 
-- For a workspace scope: pass `label: "prd-ready"` only.
-- For a team scope: pass `label: "prd-ready"` AND `team: "<KEY>"`.
+- For a workspace scope: pass `label: "$READY"` only.
+- For a team scope: pass `label: "$READY"` AND `team: "<KEY>"`.
 
-The query returns the list of candidate projects with IDs, names, and label sets. For each candidate, confirm that exactly one lifecycle label is present (the API filter is `prd-ready`, but a project could have ended up with two labels by hand — that's a misconfiguration, not a normal queue entry).
+The query returns the list of candidate projects with IDs, names, and label sets. For each candidate, confirm that exactly one lifecycle label is present (the API filter is `$READY`, but a project could have ended up with two labels by hand — that's a misconfiguration, not a normal queue entry).
 
 If the result set is empty, run a secondary query to distinguish between a genuinely empty queue and a workspace/team that has not yet adopted the label convention:
 
-- Secondary query: `list_projects({...scope-filter})` with no label filter, then in-process check whether any returned project carries any of `prd-ready` / `prd-in-review` / `prd-blocked` / `prd-ticketed`.
+- Secondary query: `list_projects({...scope-filter})` with no label filter, then in-process check whether any returned project carries any of `$READY` / `$IN_REVIEW` / `$BLOCKED` / `$TICKETED`.
 
-If the secondary query shows zero projects carrying any `prd-*` label → the convention has not been adopted. Surface a misconfiguration message: `"No Linear projects in this scope carry prd-* labels. If this is a new project, apply the prd-ready label to projects that are ready for ticketing (see Adoption section)."` Exit with an error — this is a setup issue, not a normal idle cycle.
+If the secondary query shows zero projects carrying any PRD lifecycle label → the convention has not been adopted. Surface a misconfiguration message: `"No Linear projects in this scope carry PRD lifecycle labels. If this is a new project, apply the $READY label to projects that are ready for ticketing (see Adoption section)."` Exit with an error — this is a setup issue, not a normal idle cycle.
 
-If the secondary query shows projects with other `prd-*` labels but none with `prd-ready` → the queue is genuinely empty (all PRDs are already in-review, blocked, ticketed, or shipped). Exit cleanly with `"No Linear projects labelled prd-ready. Nothing to do."`
+If the secondary query shows projects with other PRD lifecycle labels but none with `$READY` → the queue is genuinely empty (all PRDs are already in `in_review`, `blocked`, `ticketed`, or `shipped`). Exit cleanly with `"No Linear projects labelled $READY. Nothing to do."`
 
-### Phase 3 — Process each Ready PRD
+### Phase 3 — Process each ready PRD
 
 For each project (process serially to keep label transitions auditable):
 
 #### 3a. Claim
 
-Transition labels via `mcp__linear-server__save_project({id, labels})`: pass the full new label set with `prd-ready` removed and `prd-in-review` added. This is the idempotency lock — a re-entrant cycle running concurrently won't see this project because its query filters on `label: "prd-ready"`.
+Transition labels via `mcp__linear-server__save_project({id, labels})`: pass the full new label set with `$READY` removed and `$IN_REVIEW` added. This is the idempotency lock — a re-entrant cycle running concurrently won't see this project because its query filters on `label: "$READY"`.
 
 If the update fails (permission error, race condition), log it and skip this project. Do not proceed to validation on a project you didn't successfully claim.
 
@@ -114,8 +140,8 @@ This call also indirectly invokes `lisa:tracker-source-artifacts` (artifact extr
 
 1. Re-invoke `lisa:linear-to-tracker` with `dry_run: false` to actually write the tickets. This re-runs Phases 1-5 and runs the preservation gate (Phase 5.5).
 2. Capture the created ticket keys from the skill's output.
-3. Ensure the project has a sentinel feedback issue (see "Sentinel feedback issue" below for the helper). Post a comment on it via `mcp__linear-server__save_comment` listing the created tickets (epic, stories, sub-tasks) with their JIRA URLs. Lead with: `"Ticketed by Claude. Created N JIRA issues — see below. Add the prd-shipped label to the Linear project after the work is delivered."`
-4. Transition labels: remove `prd-in-review`, add `prd-ticketed` via `save_project`.
+3. Ensure the project has a sentinel feedback issue (see "Sentinel feedback issue" below for the helper). Post a comment on it via `mcp__linear-server__save_comment` listing the created tickets (epic, stories, sub-tasks) with their JIRA URLs. Lead with: `"Ticketed by Claude. Created N JIRA issues — see below. Add the $SHIPPED label to the Linear project after the work is delivered."`
+4. Transition labels: remove `$IN_REVIEW`, add `$TICKETED` via `save_project`.
 5. **Run Phase 3e (coverage audit)** before considering this PRD done.
 
 **If `FAIL`** (one or more planned tickets failed one or more gates):
@@ -144,7 +170,7 @@ Each comment body MUST contain these four parts, in this order, no exceptions:
 
 **Recommendation:** <validator's `recommendation` field, verbatim — must contain 1–3 concrete options, never a generic "please clarify">
 
-**Action:** Update this section in the PRD, then replace the `prd-blocked` label with `prd-ready` on the Linear project and Claude will re-run intake.
+**Action:** Update this section in the PRD, then replace the `$BLOCKED` label with `$READY` on the Linear project and Claude will re-run intake.
 ```
 
 If multiple failures share an anchor, render each as its own `**What's unclear:** ... **Recommendation:** ...` block within the same comment, separated by horizontal lines (`---`). Keep the single `[Category badge]` heading at the top using the most-severe / most-blocking category from the group.
@@ -175,13 +201,13 @@ Use these exact badge labels — they are the validator's category values transl
 
 ##### 3c.6 Label transition
 
-After all comments are posted (anchored groups + the optional sentinel-issue summary), transition labels: remove `prd-in-review`, add `prd-blocked` via `save_project`. Do NOT write any JIRA tickets.
+After all comments are posted (anchored groups + the optional sentinel-issue summary), transition labels: remove `$IN_REVIEW`, add `$BLOCKED` via `save_project`. Do NOT write any destination tickets.
 
 #### 3d. Continue
 
-Move to the next Ready PRD. One PRD failing does not affect others.
+Move to the next ready PRD. One PRD failing does not affect others.
 
-#### 3e. Coverage audit (mandatory after prd-ticketed)
+#### 3e. Coverage audit (mandatory after $TICKETED)
 
 Per-ticket gates prove each ticket is well-formed; they do NOT prove the *set* of created tickets covers the *whole* PRD. Silent drops happen — invoke the `lisa:prd-ticket-coverage` skill to catch them.
 
@@ -190,16 +216,16 @@ Per-ticket gates prove each ticket is well-formed; they do NOT prove the *set* o
 
    | Verdict | Action |
    |---------|--------|
-   | `COMPLETE` | Done. Leave label as `prd-ticketed`. Move to next PRD. |
-   | `COMPLETE_WITH_SCOPE_CREEP` | Post an advisory comment on the sentinel feedback issue naming the scope-creep tickets (so product can decide whether to close them as out-of-scope). Leave label as `prd-ticketed`. |
-   | `GAPS_FOUND` | The created ticket set is incomplete. (a) For each gap, post a comment using the same product-facing template as Phase 3c.3 — anchored on the relevant sub-issue when `prd_anchor` is non-null, on the sentinel feedback issue otherwise; category badge from the gap's `category` field; `What's unclear` and `Recommendation` from the audit report's `what` and `recommendation` fields. Apply the same forbidden-language rules from Phase 3c.5. (b) Post one summary comment on the sentinel feedback issue listing the tickets that *were* successfully created (so product knows what to keep vs. what to extend). (c) Transition labels from `prd-ticketed` back to `prd-blocked` via `save_project`. |
-   | `NO_TICKETS_FOUND` | Should not happen if step 2 succeeded. If it does, log it as an Error in the cycle summary and leave label as `prd-ticketed` with a comment flagging the audit failure for human review. |
+   | `COMPLETE` | Done. Leave label as `$TICKETED`. Move to next PRD. |
+   | `COMPLETE_WITH_SCOPE_CREEP` | Post an advisory comment on the sentinel feedback issue naming the scope-creep tickets (so product can decide whether to close them as out-of-scope). Leave label as `$TICKETED`. |
+   | `GAPS_FOUND` | The created ticket set is incomplete. (a) For each gap, post a comment using the same product-facing template as Phase 3c.3 — anchored on the relevant sub-issue when `prd_anchor` is non-null, on the sentinel feedback issue otherwise; category badge from the gap's `category` field; `What's unclear` and `Recommendation` from the audit report's `what` and `recommendation` fields. Apply the same forbidden-language rules from Phase 3c.5. (b) Post one summary comment on the sentinel feedback issue listing the tickets that *were* successfully created (so product knows what to keep vs. what to extend). (c) Transition labels from `$TICKETED` back to `$BLOCKED` via `save_project`. |
+   | `NO_TICKETS_FOUND` | Should not happen if step 2 succeeded. If it does, log it as an Error in the cycle summary and leave label as `$TICKETED` with a comment flagging the audit failure for human review. |
 
 3. The created tickets remain in the destination tracker regardless of the verdict — they are valid in their own right. The audit only tells us whether *more* are needed.
 
 ### Phase 4 — Summary report
 
-After processing every Ready PRD, emit a summary:
+After processing every ready PRD, emit a summary:
 
 ```text
 ## linear-prd-intake summary
@@ -209,18 +235,18 @@ Cycle started: <ISO timestamp>
 Cycle completed: <ISO timestamp>
 
 PRDs processed: <n>
-- prd-ticketed: <n>
+- $TICKETED: <n>
   - <project name> → <epic-key> + <story-count> stories + <subtask-count> sub-tasks (coverage: COMPLETE | COMPLETE_WITH_SCOPE_CREEP)
-- prd-blocked: <n>
+- $BLOCKED: <n>
   - <project name> → <gate-failure-count> gate failures (pre-write) OR <gap-count> coverage gaps (post-write)
 - Errors (claim failed, etc): <n>
   - <project name> — <reason>
 
-Total JIRA tickets created: <n>
+Total destination tickets created: <n>
 Coverage audit summary: <n> COMPLETE / <n> COMPLETE_WITH_SCOPE_CREEP / <n> GAPS_FOUND
 ```
 
-Print to the agent's output. Do not write this summary to Linear or JIRA — it's an operational record for the human.
+Print to the agent's output. Do not write this summary to Linear or the destination tracker — it's an operational record for the human.
 
 ## Sentinel feedback issue
 
@@ -229,52 +255,61 @@ Linear's MCP does not expose project-level comments. To preserve the comment-bas
 The sentinel issue is identified by:
 
 - A stable title: `"PRD intake: clarifying questions"`
-- A stable label: `prd-intake-feedback` (issue-level label, distinct from the project-level `prd-*` labels)
+- A stable label: `$SENTINEL` (issue-level label, distinct from the project-level PRD lifecycle labels)
 - Membership in the project being processed
 
 Helper behavior — call this **before** posting any clarifying-question comment in Phase 3c or 3e:
 
-1. Search for an existing feedback issue: `list_issues({project: <id>, label: "prd-intake-feedback"})`. If multiple match (shouldn't happen, but defensive), use the oldest by `createdAt`.
-2. If none exists: ensure the `prd-intake-feedback` label exists on the project's team via `list_issue_labels` then `create_issue_label` if needed; then create the sentinel via `save_issue({team: <team-id>, project: <id>, title: "PRD intake: clarifying questions", description: "Auto-created by lisa:linear-prd-intake. This issue collects clarifying-question comments that don't anchor to a specific sub-issue. Do not close manually — it is reused across intake cycles.", labels: ["prd-intake-feedback"]})`. Capture the new issue identifier.
+1. Search for an existing feedback issue: `list_issues({project: <id>, label: "$SENTINEL"})`. If multiple match (shouldn't happen, but defensive), use the oldest by `createdAt`.
+2. If none exists: ensure the `$SENTINEL` label exists on the project's team via `list_issue_labels` then `create_issue_label` if needed; then create the sentinel via `save_issue({team: <team-id>, project: <id>, title: "PRD intake: clarifying questions", description: "Auto-created by lisa:linear-prd-intake. This issue collects clarifying-question comments that don't anchor to a specific sub-issue. Do not close manually — it is reused across intake cycles.", labels: ["$SENTINEL"]})`. Capture the new issue identifier.
 3. Return the issue identifier to the caller for use in `save_comment({issueId: <id>, body: ...})`.
 
 Idempotency: the helper finds-or-creates. Re-runs of the cycle reuse the same sentinel issue. Comments accumulate; product reads top-down to see the latest cycle's findings. Do not delete or repurpose old comments — history is the audit trail.
 
 ## Idempotency & safety
 
-- **Single-cycle scope**: this skill processes the `prd-ready` set as it exists at the start of Phase 2. New `prd-ready` projects added mid-cycle are picked up next run.
-- **No writes outside the lifecycle**: this skill only ever writes to the destination tracker via `lisa:linear-to-tracker` (which delegates to `lisa:tracker-write`), only ever changes Linear project labels among `prd-in-review`, `prd-blocked`, `prd-ticketed`, only ever creates/comments on the sentinel feedback issue (never any other Linear issue). It never edits project descriptions, never edits Linear documents, never touches `prd-draft` or `prd-shipped`, never archives or deletes projects.
-- **Claim-first ordering**: the label flip to `prd-in-review` happens BEFORE validation runs, so a re-entrant call won't double-process.
-- **Failure isolation**: an exception processing one project must not stop the cycle. Catch, record under "Errors" in the summary, continue to the next project. The project that errored is left labelled `prd-in-review` — the human investigates from there.
+- **Single-cycle scope**: this skill processes the ready set as it exists at the start of Phase 2. New `$READY` projects added mid-cycle are picked up next run.
+- **No writes outside the lifecycle**: this skill only ever writes to the destination tracker via `lisa:linear-to-tracker` (which delegates to `lisa:tracker-write`), only ever changes Linear project labels among `$IN_REVIEW`, `$BLOCKED`, `$TICKETED`, only ever creates/comments on the sentinel feedback issue (never any other Linear issue). It never edits project descriptions, never edits Linear documents, never touches the `draft` or `shipped` labels, never archives or deletes projects.
+- **Claim-first ordering**: the label flip to `$IN_REVIEW` happens BEFORE validation runs, so a re-entrant call won't double-process.
+- **Failure isolation**: an exception processing one project must not stop the cycle. Catch, record under "Errors" in the summary, continue to the next project. The project that errored is left labelled `$IN_REVIEW` — the human investigates from there.
 - **Single-label invariant**: after every transition, verify exactly one lifecycle label is present on the project. If two are present (rare race), surface as an Error and skip — do NOT auto-resolve, the human decides.
 
 ## Configuration
 
 Same configuration as `lisa:linear-to-tracker`. See that skill for the full table. Key items:
 
-- **From `.lisa.config.json`**: `linear.workspace` (required for Linear MCP). When the destination tracker is `linear`, also `linear.teamKey`.
+- **From `.lisa.config.json`**: `linear.workspace` (required for Linear MCP). When the destination tracker is `linear`, also `linear.teamKey`. Lifecycle label vocabulary lives under `linear.labels.prd.*` (all optional; defaults documented above).
 - **From environment variables**: `E2E_BASE_URL`, `E2E_TEST_PHONE`, `E2E_TEST_OTP`, `E2E_TEST_ORG`, `E2E_GRAPHQL_URL` (operational E2E test config).
 
 Destination tracker config (jira / github / linear) is consumed by `lisa:tracker-write` internally — this skill does NOT read it. If any required value is missing, surface the missing key(s) and exit this cycle — never invent values.
 
+| Field | Default | Purpose |
+|-------|---------|---------|
+| `.lisa.config.json` `linear.labels.prd.ready` | `prd-ready` | Project label signalling "PRD ready for ticketing" |
+| `.lisa.config.json` `linear.labels.prd.in_review` | `prd-in-review` | Project label set on claim |
+| `.lisa.config.json` `linear.labels.prd.blocked` | `prd-blocked` | Project label set on validation failure |
+| `.lisa.config.json` `linear.labels.prd.ticketed` | `prd-ticketed` | Project label set on success |
+| `.lisa.config.json` `linear.labels.prd.shipped` | `prd-shipped` | Project label product sets after delivery |
+| `.lisa.config.json` `linear.labels.prd.sentinel` | `prd-intake-feedback` | Issue-level label marking the sentinel feedback issue |
+
 ## Rules
 
 - Never write to the destination tracker outside of `lisa:linear-to-tracker` → `lisa:tracker-write`. The validator's verdict gates progress; bypassing it produces broken tickets.
-- Never add or remove a label this skill doesn't own (`prd-in-review`, `prd-blocked`, `prd-ticketed`). Product owns `prd-draft`, `prd-ready`, `prd-shipped`. The issue-level `prd-intake-feedback` label is owned by this skill but is not a lifecycle label.
+- Never add or remove a label this skill doesn't own (`$IN_REVIEW`, `$BLOCKED`, `$TICKETED`). Product owns the `draft`, `ready`, and `shipped` labels. The issue-level `$SENTINEL` label is owned by this skill but is not a lifecycle label.
 - Never edit a project's description or any attached Linear document. Communication with product happens only through comments on sub-issues or on the sentinel feedback issue.
 - Never post a single dump of all gate failures on one comment. One comment per `prd_anchor` group on the relevant sub-issue (or one comment on the sentinel feedback issue for unanchored failures only). Comments must be sub-issue-anchored where possible, categorized, plain-language, and contain a concrete recommendation.
 - Never include a gate ID, internal skill name, or engineering shorthand in a comment body.
 - Never run more than one intake cycle concurrently against the same scope. This skill assumes serial execution.
 - Never close, archive, or otherwise modify the sentinel feedback issue except to post comments on it. Its longevity is the audit trail.
-- If `lisa:linear-to-tracker` returns errors, treat them as gate failures: comment + `prd-blocked`. Don't silently fail.
+- If `lisa:linear-to-tracker` returns errors, treat them as gate failures: comment + `$BLOCKED`. Don't silently fail.
 
 ## Adoption (one-time per project)
 
-Before this skill can run against a Linear workspace or team, the team must adopt the `prd-*` project-label convention:
+Before this skill can run against a Linear workspace or team, the team must adopt the PRD lifecycle project-label convention (defaults shown; override via `linear.labels.prd.*` if you want different names):
 
-1. Apply `prd-ready` to projects that are ready for ticketing (replaces the Notion `Status = Ready` flip and the Confluence `prd-ready` page label).
-2. Reserve `prd-in-review`, `prd-blocked`, `prd-ticketed` for this skill — humans should not set them manually except to recover from an error.
-3. (Optional but recommended) Add `prd-draft` for in-progress PRDs and `prd-shipped` for delivered work, so the full lifecycle is visible at a glance.
+1. Apply the `ready` label (default: `prd-ready`) to projects that are ready for ticketing (replaces the Notion `Status = Ready` flip and the Confluence `prd-ready` page label).
+2. Reserve `in_review`, `blocked`, `ticketed` (defaults: `prd-in-review`, `prd-blocked`, `prd-ticketed`) for this skill — humans should not set them manually except to recover from an error.
+3. (Optional but recommended) Add the `draft` and `shipped` labels (defaults: `prd-draft`, `prd-shipped`) for in-progress PRDs and delivered work respectively, so the full lifecycle is visible at a glance.
 4. The labels must exist as **project labels** in Linear (`list_project_labels` should return them). Issue-level labels with the same names won't work; Linear keeps the two label kinds separate.
 
 If the workspace hasn't adopted these labels, the first run exits with a label-convention error (not the idle empty-set message) — this distinguishes a setup issue from a genuinely empty queue so operators know to apply the convention rather than assuming the queue is drained. See Phase 2 for how the skill detects this case.

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

@@ -86,6 +86,7 @@ Each gate is tagged with a fixed `category` and a `product_relevant` boolean. Ca
 | S11 Validation Journey | `acceptance-criteria` | true |
 | S12 Source Precedence | `design-ux` | true |
 | S13 Relationship Search | `dependency` | true |
+| S14 Evidence manifest binding (leaf work units) | `acceptance-criteria` | true |
 | F1 Issue type valid in team | `structural` | false |
 | F2 Project parent exists and is in same team | `structural` | false |
 | F3 Linked items exist | `structural` | false |
@@ -191,6 +192,14 @@ The item must EITHER have at least one entry in `relations`, OR the description
 
 An item with zero relations and no documented search: FAIL.
 
+#### S14 — Evidence manifest binding (leaf work units)
+
+When `issue_type ∈ {Bug, Task, Sub-task, Improvement}` AND `runtime_behavior_change = true`, the `## Validation Journey` must declare at least one `[EVIDENCE: name]` marker. Each marker name must be kebab-case and unique within the item. These markers are the work unit's **evidence manifest** — the exact, enumerated set of artifacts that must be captured and attached before the item may be closed (see the "Per-Work-Unit Evidence Contract" section of the `verification` rule, the Definition of Done in `verification-lifecycle`, and the evidence-manifest gate in `tracker-evidence`).
+
+FAIL when the Validation Journey is present but declares zero `[EVIDENCE: name]` markers, or when any marker name is empty, duplicated, or not kebab-case. A behavior-changing work unit SHOULD declare both a success marker and an error/edge marker; a journey with only one marker passes but the remediation should recommend adding the error/edge case.
+
+This gate depends on S11. It is `N/A` for Project / Story / Spike (coordination containers, not work units) and for leaf units with `runtime_behavior_change = false` (doc-only / config-only / type-only). If S11 fails because the Validation Journey is absent, S14 also FAILs (there is no manifest to bind) with remediation pointing back to `lisa:linear-add-journey`.
+
 ### Feasibility Gates (require Linear lookups; skip in dry-run if requested)
 
 #### F1 — Issue type valid in team
@@ -242,6 +251,7 @@ Output is a single fenced text block. Callers parse it; do not add free-form pro
 - [PASS|FAIL|N/A] S11 Validation Journey — <one-line reason>
 - [PASS|FAIL|N/A] S12 Source Precedence — <one-line reason>
 - [PASS|FAIL|N/A] S13 Relationship Search — <one-line reason>
+- [PASS|FAIL|N/A] S14 Evidence manifest binding — <one-line reason>
 
 ### Feasibility Gates  (omit when --spec-only)
 - [PASS|FAIL|N/A] F1 Issue type valid in team — <one-line reason>

package/plugins/src/base/skills/monitor/SKILL.md

@@ -10,14 +10,13 @@ Spot-check application health in the named environment (`dev` / `staging` / `pro
 
 ## Orchestration: agent team
 
-If you are NOT already operating inside an agent team (no prior `TeamCreate` in this session, not spawned via `Agent` with `team_name`), the very first thing you do is create the team. Two tool calls only, in this exact order:
+If you are NOT already operating inside an agent team (no prior successful team-creation tool call in this session, not spawned into a team context), the very first thing you do is establish team orchestration.
 
-1. `ToolSearch` with `query: "select:TeamCreate"` — `TeamCreate` is a deferred tool whose schema must be loaded before it can be invoked. A cold call returns `InputValidationError` and tempts a fallback to direct `Agent` calls, which bypasses the team.
-2. `TeamCreate` — actually create the team.
+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.
 
-Until `TeamCreate` returns successfully, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion / Sentry), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Hitting health endpoints, pulling logs, querying Sentry — all of those are tasks for the team you are about to create, not for the lead session before the team exists.
+Until the team is established or the no-team fallback has been declared, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion / Sentry), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Hitting health endpoints, pulling logs, querying Sentry — all of those are tasks for the team you are about to create, not for the lead session before orchestration exists.
 
-If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT call `TeamCreate` — the harness rejects double-creates. Continue within the existing team. The team lead created the team; teammates inherit it.
+If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT create a second team — many harnesses reject double-creates. Continue within the existing team. The team lead created the team; teammates inherit it.
 
 ## Flow
 

package/plugins/src/base/skills/notion-access/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: notion-access
+description: "Vendor-neutral access layer for Notion. Every notion-* skill MUST delegate through this skill rather than invoking the Notion REST API or any Notion MCP directly. Resolves a substrate per operation in this order: (1) Notion MCP if authenticated and the configured prdDatabaseId is fetchable through it (identity-match), (2) curl + Bearer auth + internal-integration token. Verifies the active connection matches `.lisa.config.json` before every operation — substrates authenticated as a different Notion workspace are skipped, not used."
+allowed-tools: ["Bash", "Read", "Skill"]
+---
+
+# Notion Access: $ARGUMENTS
+
+Single chokepoint for all Notion operations. Routes each op to a substrate, enforces connection match, returns structured result. Caller skills (`notion-*`) MUST go through this — they MUST NOT call the Notion REST API or any `mcp__*notion*` tools directly.
+
+## Invocation contract
+
+```text
+operation: read-page         id: <uuid>
+operation: write-page        payload: {...}        # update page properties
+operation: archive-page      id: <uuid>
+operation: query-database    id: <uuid> filter: {...} sort: {...}
+operation: read-database     id: <uuid>
+operation: append-blocks     page_id: <uuid> children: [...]
+operation: search            query: "..." [filter: { object: "page" }]
+operation: list-users
+operation: get-self
+```
+
+The skill returns either the structured operation result (JSON) or an error message prefixed with `Error:` and a remediation hint.
+
+## Workflow
+
+### Step 1 — Substrate selection (per operation)
+
+Read config:
+
+```bash
+WORKSPACE=$(jq -r '.notion.workspaceId // empty' .lisa.config.json)
+DB_ID=$(jq -r '.notion.prdDatabaseId // empty' .lisa.config.json)
+[ -z "$WORKSPACE" ] && { echo "Error: notion.workspaceId not set. Run /lisa:setup:notion." >&2; exit 1; }
+[ -z "$DB_ID" ]     && { echo "Error: notion.prdDatabaseId not set. Run /lisa:setup:notion." >&2; exit 1; }
+```
+
+Probe each tier in order; the first that's ready AND identity-matches is the substrate for this operation. Identity-match is verified before any operation; substrates authenticated as a different workspace are skipped, not used.
+
+```bash
+substrate=""
+
+# Tier 1: Notion MCP (identity-matched by fetching the configured PRD database)
+# Pseudo-code; actual call is the MCP tool invocation.
+# Try to fetch DB_ID through the MCP. Success → MCP is authed to the right workspace.
+# 404 / object_not_found → MCP is authed elsewhere (or unauthenticated). Skip.
+if mcp_notion_can_fetch_database "$DB_ID"; then
+  substrate="mcp"
+fi
+
+# Tier 2: curl + API token
+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
+}
+TOKEN=$(read_notion_token "$WORKSPACE")
+if [ -n "$TOKEN" ]; then
+  # Verify token belongs to the configured workspace.
+  me=$(curl -s -H "Authorization: Bearer $TOKEN" -H "Notion-Version: 2022-06-28" \
+              "https://api.notion.com/v1/users/me")
+  me_workspace=$(echo "$me" | jq -r '.bot.workspace_name // .bot.workspace_id // empty')
+  if [ -n "$me_workspace" ] && [ "$me_workspace" = "$WORKSPACE" ]; then
+    : ${substrate:=curl}
+  elif [ -n "$me_workspace" ]; then
+    echo "Warning: Notion token belongs to workspace '$me_workspace' but config declares '$WORKSPACE'. Skipping curl tier." >&2
+  fi
+fi
+
+# Fail loudly with actionable remediation if nothing works.
+if [ -z "$substrate" ]; then
+  # Detect plugin enablement state for the suggestion.
+  plugin_enabled_global=$(jq -r '.enabledPlugins["notion@claude-plugins-official"] // false' ~/.claude/settings.json 2>/dev/null || echo "false")
+  plugin_enabled_project=$(jq -r '.enabledPlugins["notion@claude-plugins-official"] // false' .claude/settings.json 2>/dev/null || echo "false")
+  plugin_enabled_local=$(jq -r '.enabledPlugins["notion@claude-plugins-official"] // false' .claude/settings.local.json 2>/dev/null || echo "false")
+
+  cat >&2 <<EOF
+Error: no Notion access substrate available for workspace '$WORKSPACE'.
+
+Attempted:
+  MCP    — $([ "$plugin_enabled_global" = "true" ] || [ "$plugin_enabled_project" = "true" ] || [ "$plugin_enabled_local" = "true" ] && echo "plugin enabled but not authenticated or cannot fetch configured prdDatabaseId" || echo "plugin not enabled in any settings.json scope")
+  curl   — no NOTION_API_TOKEN found for $WORKSPACE (env, slug-suffixed env, or keychain) OR token belongs to a different workspace
+
+Remediation paths (pick one):
+
+1. Install the Notion MCP plugin (local scope — per-developer, gitignored).
+   This is the simplest path for single-workspace developers.
+
+   Run in your terminal:
+
+     jq '.enabledPlugins["notion@claude-plugins-official"] = true' \\
+       .claude/settings.local.json 2>/dev/null > /tmp/s && \\
+       mv /tmp/s .claude/settings.local.json || \\
+       echo '{"enabledPlugins":{"notion@claude-plugins-official":true}}' > .claude/settings.local.json
+
+   Then restart Claude Code (or run /restart-mcp) to load the plugin, and
+   invoke 'mcp__plugin_notion_notion__authenticate' to complete OAuth.
+   Also share the configured prdDatabaseId with the integration via
+   the page's '•••' menu → Connections.
+
+2. Provision an internal-integration API token (headless / CI / multi-workspace).
+
+     Run /lisa:setup:notion — guided flow with clipboard-piped keychain store.
+
+EOF
+  exit 1
+fi
+```
+
+### Step 2 — Connection-match assertion
+
+The substrate selection in Step 1 already verifies identity. This step is the explicit re-assertion before any operation runs — defensive in case substrate state changed since selection. For the curl tier, re-validate token-to-workspace pairing if more than a few minutes elapsed.
+
+The workspace identifier stored in config is whatever stable string the user picked at setup time — typically `bot.workspace_name` (human-readable) for simplicity. If the workspace has been renamed in Notion, `setup-notion` re-detects and re-stores; the access skill surfaces the mismatch instead of silently authing as the wrong workspace.
+
+### Step 3 — Operation dispatch
+
+When `$substrate=mcp`, route through Notion MCP tools. When `$substrate=curl`, hit the Notion REST API directly. All curl calls use `https://api.notion.com/v1/<path>`, `Notion-Version: 2022-06-28`, `Authorization: Bearer $TOKEN`.
+
+Substrate columns: try the column matching `$substrate` first. If that column is `—` for the requested operation (no adapter), fall through to the other substrate if it's also available. If neither has an adapter, the operation is unsupported.
+
+| Operation | MCP adapter | curl adapter |
+|---|---|---|
+| **Pages** | | |
+| `read-page id:<I>` | `mcp__claude_ai_Notion__notion-fetch` | `GET /v1/pages/<I>` |
+| `write-page payload:<P>` | `mcp__claude_ai_Notion__notion-update-page` | `PATCH /v1/pages/<I>` body `{ "properties": {...}, "archived": true/false }` |
+| `archive-page id:<I>` | `mcp__claude_ai_Notion__notion-update-page` (with `archived: true`) | `PATCH /v1/pages/<I>` body `{ "archived": true }` |
+| `append-blocks page_id:<P> children:<arr>` | (no direct equivalent) | `PATCH /v1/blocks/<P>/children` body `{ "children": <arr> }` |
+| **Databases** | | |
+| `read-database id:<I>` | `mcp__claude_ai_Notion__notion-fetch` | `GET /v1/databases/<I>` |
+| `query-database id:<I> filter:<F> sort:<S>` | `mcp__claude_ai_Notion__notion-search` (with collection scope) | `POST /v1/databases/<I>/query` body `{ "filter": <F>, "sorts": <S>, "page_size": <N> }` |
+| **Comments** | | |
+| `list-comments block_id:<I>` | (MCP lacks a generic list-comments tool) | `GET /v1/comments?block_id=<I>` |
+| `create-comment page_id:<I> rich_text:<arr>` | `mcp__claude_ai_Notion__notion-create-comment` (page-level) | `POST /v1/comments` body `{ "parent": { "page_id": "<I>" }, "rich_text": <arr> }` |
+| `create-comment-on-block block_id:<I> rich_text:<arr>` | `mcp__claude_ai_Notion__notion-create-comment` (with block anchor) | `POST /v1/comments` body `{ "parent": { "block_id": "<I>" }, "rich_text": <arr> }` |
+| **Search & users** | | |
+| `search query:<Q> [filter:<F>]` | `mcp__claude_ai_Notion__notion-search` | `POST /v1/search` body `{ "query": "<Q>", "filter": <F or null> }` |
+| `list-users` | — | `GET /v1/users` |
+| `get-self` | — | `GET /v1/users/me` |
+
+Operations not in this table are unsupported — add an adapter row before invoking. Adapters MUST return parsed JSON; never raw HTTP responses.
+
+### Step 4 — Return result
+
+Wrap the JSON response in a `<result>` block for caller parsing. On HTTP non-2xx, prefix the error message with `Error:` and surface the HTTP status code plus Notion's response body verbatim.
+
+```bash
+exec_op() {
+  local method="$1" path="$2" body="${3:-}"
+  local args=( -s -X "$method"
+    -H "Authorization: Bearer $TOKEN"
+    -H "Notion-Version: 2022-06-28" )
+  [ -n "$body" ] && args+=( -H "Content-Type: application/json" --data-binary "$body" )
+  local code=$(curl "${args[@]}" -o /tmp/notion-resp -w "%{http_code}" \
+    "https://api.notion.com/v1${path}")
+  if [ "${code:0:1}" != "2" ]; then
+    echo "Error: Notion API $method $path returned HTTP $code" >&2
+    cat /tmp/notion-resp >&2
+    return 1
+  fi
+  cat /tmp/notion-resp
+}
+```
+
+## Invariants
+
+- Caller skills never call `curl https://api.notion.com/...` or any `mcp__*notion*` tool directly. They invoke this skill via the Skill tool with an operation name and arguments.
+- Substrate is selected per skill invocation following the tier ladder. The first tier that's available AND identity-matches `notion.workspaceId` wins.
+- The connection-match check is mandatory at every tier. Skipping it (because "the user obviously meant this workspace") is forbidden — silent cross-workspace operations are exactly the multi-account hazard this design exists to prevent.
+- API tokens never mutate. If the configured workspace's token is wrong or missing, fail loudly and tell the user to run `/lisa:setup:notion`.
+- `Notion-Version` is pinned to `2022-06-28` — the version every existing notion-* skill targets. Bumping it is a coordinated change across the access skill and all callers.
+
+## Headless behavior
+
+In a headless / non-interactive context (no TTY, `CI=true`, or `-p` mode), the MCP tier is unavailable (its OAuth flow needs a browser). The ladder collapses to curl + `NOTION_API_TOKEN`. Same skill code runs identically; only the substrate changes.
+
+## Per-page sharing prerequisite
+
+Notion integrations only see pages that have been **explicitly shared** with them. If `read-page` or `query-database` returns a 404 or `object_not_found` error and the configured workspace is correct, the cause is almost always that the page/database wasn't shared with the integration. Surface this in the error message:
+
+> Page <id> not visible to the integration. Open the page in Notion → "..." menu → Connections → add the lisa integration.
+
+Do not paper over with a retry. Sharing is a one-time human action per database (or per page if the user prefers page-level sharing); failures here mean the user needs to act.