@codyswann/lisa 2.189.7 → 2.189.8

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

@@ -0,0 +1,316 @@
+---
+name: lisa-setup-notion
+description: "Configure Notion as the PRD source for this project. Walks the user through creating an internal integration in the target workspace, sharing the PRD database with it, stores the resulting `ntn_*` token in OS keychain (multi-workspace-safe — keyed by workspaceId), validates against the Notion API, and writes `notion.workspaceId`, `notion.prdDatabaseId`, and `notion.values` into `.lisa.config.json`. Idempotent — re-runs update the existing section rather than duplicating it. Offers to set top-level `source: \"notion\"`."
+allowed-tools: ["Bash", "Read", "Write", "Edit", "Skill", "AskUserQuestion"]
+---
+
+# Setup Notion: $ARGUMENTS
+
+Provision Notion access for this project. After this skill runs, `.lisa.config.json` contains `notion.workspaceId` and `notion.prdDatabaseId`, and the OS keychain has a `lisa-notion` entry keyed by the workspaceId.
+
+## Workflow
+
+### Step 0 — Pick a setup path
+
+Ask via `AskUserQuestion`:
+
+> How do you want lisa to talk to Notion for this project?
+>
+> 1. **MCP-only (simplest)** — authenticate the Notion MCP once via browser OAuth; lisa uses it for every operation. Best for: single-workspace developers on a personal laptop. New developers onboard with one OAuth flow, no token sharing, no rotation pain when someone leaves. Skip the rest of this setup.
+> 2. **MCP + internal-integration token (recommended for teams)** — MCP for interactive dev, internal-integration token in keychain for headless / CI / multi-workspace. Continue through token-create steps.
+> 3. **Token-only (headless / CI)** — store a workspace-scoped internal-integration token in the OS keychain; lisa uses curl for everything. Best for: CI pipelines, headless containers. Continue through token-create steps.
+
+If the user picks (1) and the MCP is already authenticated to the right workspace (verify by attempting to fetch the configured `prdDatabaseId` via the MCP — success means identity match), write only `notion.workspaceId`, `notion.prdDatabaseId`, and `notion.statusProperty` into `.lisa.config.json` and skip to Step 8 (top-level source offer). If the MCP isn't authed yet, instruct the user to run `mcp__claude_ai_Notion__authenticate` (or the plugin equivalent) and complete the OAuth flow, then re-verify. The PRD database still needs to be shared with the OAuth-granted access — Notion's per-page sharing model applies to OAuth identities the same way it does to internal-integration tokens.
+
+If the user picks (2) or (3), continue through the rest of the steps; the token gets stored in addition to (or instead of) the MCP session.
+
+### Step 1 — Open the Notion integration page
+
+```bash
+case "$(uname -s)" in
+  Darwin) open "https://www.notion.so/profile/integrations" ;;
+  Linux)  xdg-open "https://www.notion.so/profile/integrations" 2>/dev/null ;;
+  MINGW*|MSYS*|CYGWIN*) start "https://www.notion.so/profile/integrations" ;;
+esac
+```
+
+Print instructions for the user:
+
+```
+1. Click "New integration".
+2. Name it: lisa-<project-name>  (e.g., lisa-gemini, lisa-acme — pick something descriptive).
+3. Associated workspace: pick the workspace your PRDs live in.
+4. Type: "Internal integration".
+5. Capabilities: leave defaults (Read content, Update content, Insert content). No comment / user-info capabilities needed.
+6. Click Save.
+7. On the integration's detail page, click "Show" next to "Internal Integration Token".
+8. Copy the token — starts with `ntn_`. Atlassian-style scoped tokens have a `=<CRC>` suffix; Notion's do NOT, but tokens are still 50+ chars. Watch for clipboard-truncation in some terminals.
+```
+
+### Step 2 — Identify the workspace
+
+The user picks a stable identifier for this workspace. Two options:
+
+- **Workspace name** (human-readable, e.g., `Gemini Sports`). Easy to recognize, can be ambiguous if a workspace is renamed in Notion. Recommended.
+- **Workspace UUID** (returned by Notion's API). Stable but opaque.
+
+Default to the workspace name. After the user stores the token (Step 4), Step 5's `/users/me` call surfaces the actual `bot.workspace_name`; if it differs from what the user typed (capitalization, trailing whitespace), prompt to confirm.
+
+```bash
+WORKSPACE=$(jq -r '.notion.workspaceId // empty' .lisa.config.json 2>/dev/null)
+if [ -z "$WORKSPACE" ]; then
+  # Prompt the user — accept any non-empty string. They pick the slug; we just store it.
+  read -p "Workspace identifier (any stable slug, e.g. 'gemini-sports'): " WORKSPACE
+fi
+```
+
+### Step 3 — Share the PRD database with the integration
+
+This is **non-optional**. Notion's permission model is share-based — the integration cannot see any pages or databases until the user explicitly grants access.
+
+Print instructions:
+
+```
+1. In Notion, navigate to your PRD database (or the parent page containing it).
+2. Click the "..." menu in the top right of the database.
+3. Click "Connections".
+4. Find "lisa-<project>" in the list and click "Connect".
+5. Confirm any prompts about granting access.
+
+The connection cascades to all child pages of the database by default. New PRDs added under the database automatically inherit access.
+```
+
+If `--database=<uuid>` was passed in `$ARGUMENTS`, use it; otherwise prompt:
+
+```bash
+DATABASE_ID=$(jq -r '.notion.prdDatabaseId // empty' .lisa.config.json 2>/dev/null)
+if [ -z "$DATABASE_ID" ]; then
+  cat <<EOF
+Paste the PRD database URL or ID:
+  - URL form: https://notion.so/<workspace>/<database-id>?v=...
+  - ID form:  32-char UUID with or without dashes
+EOF
+  read -p "Database: " DB_INPUT
+  # Extract UUID from URL if needed.
+  DATABASE_ID=$(echo "$DB_INPUT" | grep -oE '[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}' | head -1)
+  if [ -z "$DATABASE_ID" ]; then
+    echo "Error: could not extract a UUID from '$DB_INPUT'." >&2
+    exit 1
+  fi
+fi
+```
+
+### Step 4 — Store the token via OS keychain (token never enters chat)
+
+Same security posture as `setup-atlassian`. Print a platform-specific clipboard-pipe command for the user to run **in their own terminal**:
+
+```bash
+case "$(uname -s)" in
+  Darwin)
+    cat <<EOF
+1. Copy the integration token from the Notion page.
+2. Run this single line in your terminal (leading space keeps it out of zsh history):
+
+    security delete-generic-password -s lisa-notion -a "$WORKSPACE" 2>/dev/null;  TOK="\$(pbpaste)"; security add-generic-password -U -s lisa-notion -a "$WORKSPACE" -w "\$TOK"; unset TOK
+
+The token is piped from clipboard straight to keychain — never enters the prompt or chat.
+EOF
+    ;;
+  Linux)
+    if command -v secret-tool >/dev/null 2>&1; then
+      if   command -v wl-paste >/dev/null 2>&1; then CLIP=wl-paste
+      elif command -v xclip    >/dev/null 2>&1; then CLIP="xclip -selection clipboard -o"
+      elif command -v xsel     >/dev/null 2>&1; then CLIP="xsel --clipboard --output"
+      else CLIP="cat"
+      fi
+      cat <<EOF
+1. Copy the integration token.
+2. Run this in your terminal:
+
+   secret-tool clear service lisa-notion account "$WORKSPACE" 2>/dev/null; printf '%s' "\$($CLIP)" | secret-tool store --label="Lisa Notion ($WORKSPACE)" service lisa-notion account "$WORKSPACE"
+
+(If no clipboard tool is installed: the command reads from stdin — paste, Ctrl-D.)
+EOF
+    else
+      cat <<EOF
+libsecret / secret-tool not installed. Options:
+  1. Install: sudo apt install libsecret-tools  (then re-run /lisa:setup:notion).
+  2. Env-var fallback (headless / CI / Docker):
+       export NOTION_API_TOKEN_$(echo "$WORKSPACE" | tr '[:upper:]-' '[:lower:]_')="<paste-token>"
+     Plaintext on disk — only acceptable on ephemeral / CI environments.
+EOF
+    fi
+    ;;
+  MINGW*|MSYS*|CYGWIN*)
+    cat <<EOF
+PowerShell:
+
+  \$tok = Get-Clipboard; cmdkey /generic:"lisa-notion-$WORKSPACE" /user:"$WORKSPACE" /pass:"\$tok"; Remove-Variable tok
+EOF
+    ;;
+esac
+```
+
+**Never accept the token via chat or stdin into this skill.** Wait for the user to confirm storage.
+
+### Step 5 — Verify the token + workspace match
+
+Use the same lookup ladder `notion-access` uses:
+
+```bash
+read_notion_token() {
+  local workspace="$1"
+  [ -n "$NOTION_API_TOKEN" ] && { echo "$NOTION_API_TOKEN"; return; }
+  local slug=$(echo "$workspace" | tr '[:upper:]-' '[:lower:]_')
+  local varname="NOTION_API_TOKEN_${slug}"
+  [ -n "${!varname}" ] && { echo "${!varname}"; return; }
+  case "$(uname -s)" in
+    Darwin)  security find-generic-password -s lisa-notion -a "$workspace" -w 2>/dev/null ;;
+    Linux)   command -v secret-tool >/dev/null && secret-tool lookup service lisa-notion account "$workspace" 2>/dev/null ;;
+    MINGW*|MSYS*|CYGWIN*)
+      # `cmdkey /generic ... /pass:` stores the secret in Windows Credential Manager, but
+      # `cmdkey /list` never prints stored passwords (by design). Read the CredentialBlob
+      # back via the Win32 CredRead API through PowerShell; pass the target name via an env
+      # var to dodge nested quoting, and strip the CRLF powershell.exe appends.
+      LISA_CRED_TARGET="lisa-notion-${workspace}" powershell.exe -NoProfile -NonInteractive -Command '
+Add-Type -TypeDefinition @"
+using System;
+using System.Runtime.InteropServices;
+public static class LisaCred {
+  [StructLayout(LayoutKind.Sequential)]
+  private struct CREDENTIAL {
+    public int Flags; public int Type; public IntPtr TargetName; public IntPtr Comment;
+    public System.Runtime.InteropServices.ComTypes.FILETIME LastWritten;
+    public int CredentialBlobSize; public IntPtr CredentialBlob; public int Persist;
+    public int AttributeCount; public IntPtr Attributes; public IntPtr TargetAlias; public IntPtr UserName;
+  }
+  [DllImport("advapi32.dll", CharSet=CharSet.Unicode, SetLastError=true)]
+  private static extern bool CredRead(string target, int type, int flags, out IntPtr credential);
+  [DllImport("advapi32.dll")] private static extern void CredFree(IntPtr cred);
+  public static string Read(string target) {
+    IntPtr p;
+    if (!CredRead(target, 1, 0, out p)) { return null; }
+    try {
+      CREDENTIAL c = (CREDENTIAL)Marshal.PtrToStructure(p, typeof(CREDENTIAL));
+      if (c.CredentialBlobSize == 0) { return String.Empty; }
+      return Marshal.PtrToStringUni(c.CredentialBlob, c.CredentialBlobSize / 2);
+    } finally { CredFree(p); }
+  }
+}
+"@
+[LisaCred]::Read($env:LISA_CRED_TARGET)' 2>/dev/null | tr -d '\r' ;;
+  esac
+}
+
+TOKEN=$(read_notion_token "$WORKSPACE")
+if [ -z "$TOKEN" ]; then
+  echo "Error: token not retrievable after store. Re-run Step 4." >&2
+  exit 1
+fi
+
+# Notion tokens — sanity length check. Internal-integration tokens are ~50+ chars; if drastically shorter, a paste truncation happened.
+if [ ${#TOKEN} -lt 40 ]; then
+  echo "Warning: token is ${#TOKEN} chars — Notion tokens are typically 50+. Possible truncation." >&2
+fi
+
+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 // empty')
+
+if [ -z "$ME_WORKSPACE" ]; then
+  echo "Error: token failed Notion /users/me probe. Response: $ME" >&2
+  exit 1
+fi
+
+# If the user typed a workspace name that differs from what Notion returns, prompt to align.
+if [ "$ME_WORKSPACE" != "$WORKSPACE" ]; then
+  cat <<EOF
+The token belongs to workspace '$ME_WORKSPACE', but you provided '$WORKSPACE' as the identifier.
+Use the Notion-returned name for consistency? (recommended — connection-match check uses this string)
+EOF
+  # AskUserQuestion: replace WORKSPACE with $ME_WORKSPACE? recommended yes
+fi
+
+# Verify database visibility too (Notion's share model means the token sees only what's been shared).
+DB_PROBE=$(curl -s -o /tmp/setup-notion-db -w "%{http_code}" \
+  -H "Authorization: Bearer $TOKEN" -H "Notion-Version: 2022-06-28" \
+  "https://api.notion.com/v1/databases/$DATABASE_ID")
+if [ "$DB_PROBE" != "200" ]; then
+  cat >&2 <<EOF
+Error: integration cannot see database $DATABASE_ID (HTTP $DB_PROBE).
+The most likely cause is that you skipped Step 3 — sharing the database with the integration.
+Open the database in Notion → "..." → Connections → add 'lisa-<project>' → retry.
+EOF
+  exit 1
+fi
+
+echo "Token validated. Workspace: $ME_WORKSPACE. Database visible."
+```
+
+### Step 6 — Detect lifecycle value names
+
+Read the database schema and find the `Status` property's value list. Compare to lisa defaults and prompt for overrides if names differ.
+
+```bash
+DB_SCHEMA=$(curl -s -H "Authorization: Bearer $TOKEN" -H "Notion-Version: 2022-06-28" \
+  "https://api.notion.com/v1/databases/$DATABASE_ID")
+STATUS_PROP=$(jq -r '.properties | to_entries[] | select(.value.type == "status" or .value.type == "select") | .key' <<<"$DB_SCHEMA" | head -1)
+STATUS_VALUES=$(jq -r --arg p "$STATUS_PROP" '.properties[$p] | (.status.options // .select.options) | .[].name' <<<"$DB_SCHEMA")
+```
+
+For each lisa role (`draft`, `ready`, `in_review`, `blocked`, `ticketed`, `shipped`, `verified`), check if its default name (`Draft`, `Ready`, etc.; `Verified` for `verified`) appears in `$STATUS_VALUES`. If a role's default is missing but a similar-looking value exists, prompt the user to map it via `AskUserQuestion`. If a role has no plausible match, prompt to either create the value in Notion or accept that the lifecycle stage is unrepresented. This find-or-create-or-accept path is idempotent per role: a value already present (default or mapped) is reused untouched, so re-running never duplicates a status option.
+
+`verified` is the terminal lifecycle state after `shipped` (the `verified` role from the `config-resolution` rule, #591): `/lisa:verify-prd` transitions a Notion PRD into it once the shipped product has been empirically verified against the PRD. Notion models the PRD lifecycle as `Status` (or `select`) property options rather than labels, so `verified` is mapped or created through the exact same path as every other role above — and, like them, persisted to `notion.values.verified` when the workspace uses a non-default option name.
+
+Collect overrides as a partial values map. Only write keys that differ from defaults — `verified` included, so a non-default `Verified` option name lands in `notion.values.verified`.
+
+### Step 7 — Write `.lisa.config.json`
+
+```bash
+jq --arg ws "$WORKSPACE" --arg db "$DATABASE_ID" --arg sp "$STATUS_PROP" --argjson values "$VALUES_JSON" '
+  .notion = ((.notion // {})
+    | .workspaceId = $ws
+    | .prdDatabaseId = $db
+    | (if $sp != "" then .statusProperty = $sp else . end)
+    | (if $values != {} then .values = $values else . end))
+' .lisa.config.json > .lisa.config.json.tmp \
+   && mv .lisa.config.json.tmp .lisa.config.json
+```
+
+`VALUES_JSON` is `{}` if all roles use the default names; otherwise contains only the overrides.
+
+### Step 8 — Offer to set top-level `source`
+
+If `.source` is unset or differs from `"notion"`, ask via `AskUserQuestion`:
+
+> Notion is configured. Set top-level `source: "notion"` so `/lisa:intake` (with no args) scans this database for PRDs?
+
+If yes:
+
+```bash
+jq '.source = "notion"' .lisa.config.json > .lisa.config.json.tmp \
+   && mv .lisa.config.json.tmp .lisa.config.json
+```
+
+### Step 9 — Verify
+
+```bash
+jq -e '.notion.workspaceId and .notion.prdDatabaseId' .lisa.config.json >/dev/null
+echo "Token validated (${#TOKEN} chars). Workspace: $ME_WORKSPACE. Database: $DATABASE_ID."
+```
+
+Report success with the resolved workspace, database, status property name, and value overrides (if any), confirming all lifecycle roles — including the terminal `verified` — were detected, mapped, or flagged for creation. Direct the user to `/lisa:intake` to test.
+
+## Idempotency
+
+- Re-running this skill replaces fields in the `notion` section without disturbing others. The keychain entry update in Step 4 is the user's manual action — they re-run the same `security` / `secret-tool` / `cmdkey` command.
+- If `notion.workspaceId` and `notion.prdDatabaseId` already exist in config, skip the prompts in Steps 2–3 and go straight to verification.
+
+## Rules
+
+- Never write the token to `.lisa.config.json`. Tokens stay in keychain or env.
+- Never accept a token via this skill's stdin. Always go through the platform's clipboard-pipe pattern so the value never enters the LLM context.
+- Never auto-create the Notion integration via API — Notion offers no programmatic creation flow, and adding one would require building lisa as a public OAuth app (out of scope here).
+- Never proceed past Step 5 with an unverified token + workspace. Silent cross-workspace operations are exactly the multi-account hazard this design exists to prevent.
+- If the user has multiple Notion accounts, each project's `.lisa.config.local.json` `notion.workspaceId` is the sole disambiguator. There is no "active workspace" concept on the Notion side — the token IS the workspace binding.

package/plugins/lisa/skills/lisa-setup-notion/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Setup Notion"
+short_description: "Configure Notion as the PRD source for this project"
+default_prompt:
+  - "Use $lisa-setup-notion: Configure Notion as the PRD source for this project."

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

@@ -0,0 +1,71 @@
+---
+name: lisa-sonarcloud-access
+description: "Vendor-neutral access layer for SonarCloud/SonarQube Cloud. Sonar triage skills MUST delegate through this skill rather than calling Sonar MCP tools or REST directly. Resolves Sonar MCP first when available, then falls back to SONAR_TOKEN + SonarCloud Web API."
+allowed-tools: ["Bash", "Read", "Skill"]
+---
+
+# SonarCloud Access: $ARGUMENTS
+
+Single chokepoint for SonarCloud operations. Caller skills MUST NOT call
+`mcp__sonarqube__*` tools directly or curl `https://sonarcloud.io/api/`
+themselves.
+
+## Invocation Contract
+
+```text
+operation: gate-status project_key:<KEY> [branch:<BRANCH>] [pull_request:<N>]
+operation: issues project_key:<KEY> [branch:<BRANCH>] [pull_request:<N>] [types:<csv>] [severities:<csv>]
+operation: hotspots project_key:<KEY> [branch:<BRANCH>] [pull_request:<N>]
+operation: rule-detail key:<RULE_KEY>
+operation: source-snippet component:<COMPONENT_KEY> from:<N> to:<N>
+```
+
+Return parsed JSON in a `<result>` block.
+
+## Substrate Selection
+
+Probe in order:
+
+1. Sonar MCP, if available and authenticated.
+2. `SONAR_TOKEN` against the SonarCloud Web API.
+
+SonarCloud documents bearer-token authentication for the Web API. Use:
+
+```bash
+sonar_api() {
+  local path="$1"
+  [ -n "$SONAR_TOKEN" ] || {
+    echo "Error: SONAR_TOKEN is not set." >&2
+    return 1
+  }
+  curl -sS "https://sonarcloud.io/api${path}" \
+    -H "Authorization: Bearer $SONAR_TOKEN"
+}
+```
+
+If a host still requires the legacy token-as-basic-auth form, make that an
+explicit adapter branch in this skill; consumers do not choose auth style.
+
+If neither tier works, fail with:
+
+```text
+Error: no SonarCloud access substrate available. Authenticate the Sonar MCP or set SONAR_TOKEN.
+```
+
+## REST Dispatch
+
+| Operation | REST path |
+|---|---|
+| `gate-status` | `/qualitygates/project_status?projectKey=<KEY>[&branch=<BRANCH>][&pullRequest=<N>]` |
+| `issues` | `/issues/search?componentKeys=<KEY>[&branch=<BRANCH>][&pullRequest=<N>]...` |
+| `hotspots` | `/hotspots/search?projectKey=<KEY>[&branch=<BRANCH>][&pullRequest=<N>]` |
+| `rule-detail` | `/rules/show?key=<RULE_KEY>` |
+| `source-snippet` | `/sources/lines?key=<COMPONENT_KEY>&from=<N>&to=<N>` |
+
+## Invariants
+
+- Fallback is gated on `SONAR_TOKEN`.
+- SonarCloud host access requires `sonarcloud.io` in any custom remote network
+  allowlist.
+- Consumers ask for analysis data by operation name; this skill owns the Web API
+  path shape.

package/plugins/lisa/skills/lisa-sonarcloud-access/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "SonarCloud Access"
+short_description: "Vendor-neutral access layer for SonarCloud/SonarQube Cloud"
+default_prompt:
+  - "Use $lisa-sonarcloud-access: Vendor-neutral access layer for SonarCloud/SonarQube Cloud."

package/plugins/lisa/skills/lisa-spec-conformance/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: lisa-spec-conformance
+description: "Verifies that shipped work matches its spec section-by-section — acceptance criteria, Out of Scope, Technical Approach, Validation Journey assertions, and any explicit deliverables. Builds a coverage matrix mapping each requirement to evidence, flags scope creep separately from misses, and produces a verdict (CONFORMS / PARTIAL / DIVERGES). Runs during the verification phase alongside empirical system verification."
+allowed-tools: ["Read", "Glob", "Grep", "Bash", "Skill", "mcp__atlassian__getJiraIssue", "mcp__atlassian__searchJiraIssuesUsingJql", "mcp__atlassian__getAccessibleAtlassianResources"]
+---
+
+# Spec Conformance: $ARGUMENTS
+
+Compare shipped work against its spec section-by-section. This is the "accountant lens" — did the work ship exactly what was written, nothing more, nothing less? It is NOT UX review (that's `product-specialist`) and it is NOT empirical system verification (that's `verification-specialist`). Run it alongside those, not instead of them.
+
+## Phase 1 — Resolve Spec Source
+
+Determine the source of truth for this work. Check in this order:
+
+1. **Explicit spec argument** — plan file path (e.g. `.claude/plans/<name>.md`), JIRA key (e.g. `PROJ-123`), Linear key, GitHub issue URL, or PRD path passed as `$ARGUMENTS`.
+2. **Linked JIRA ticket** — if the current branch or PR body references a JIRA key, use it.
+3. **PR body** — if the PR description contains a "Spec" or "Ticket" link, follow it.
+4. **Plan file on disk** — check `.claude/plans/` for an active plan matching the branch name.
+
+If none of the above resolves, stop. Do not guess what the spec was. Report: "No spec source found — pass a plan file, ticket key, or PR URL."
+
+Based on the source, load the full spec:
+
+| Source | How to Load |
+|--------|-------------|
+| Plan file (`.md`) | `Read` the file |
+| JIRA key, GitHub issue ref, or Linear identifier | Invoke `/tracker-read <ref>` (vendor-neutral; dispatches to `/jira-read-ticket`, `/github-read-issue`, or `/linear-read-issue` per `.lisa.config.json` `tracker`) to get the full context bundle (primary item + epic / project / parent + linked items) |
+| PRD | `Read` the file or fetch via Notion / Confluence MCP, or `gh issue view` for a GitHub PRD |
+
+## Phase 2 — Extract Requirements
+
+Parse the spec into a structured requirement list. Do NOT skip sections — every requirement becomes a row in the coverage matrix.
+
+Sections to extract:
+
+| Section | What to Extract | Classification |
+|---------|-----------------|----------------|
+| Acceptance Criteria | Each Gherkin scenario or bullet | `acceptance` |
+| Out of Scope | Each excluded item | `excluded` (flags scope creep) |
+| Technical Approach | Each concrete implementation commitment (not narrative) | `technical` |
+| Validation Journey Assertions | Each `Assertion:` bullet | `assertion` |
+| Deliverables | Each explicit deliverable (migration, doc, endpoint, script) | `deliverable` |
+| Plan file tasks | Each task marked complete in the plan | `task` |
+| Linked blocker resolutions | Each `is blocked by` that required work in this ticket | `blocker` |
+
+If an acceptance criterion is not in Gherkin, still extract it as a requirement — but flag it as `LOW_SPECIFICITY` so the verdict downgrades.
+Downgrade rule: if any `LOW_SPECIFICITY` requirement exists, the maximum possible verdict is `PARTIAL` unless the spec is tightened and re-evaluated.
+
+Skip narrative prose (Context / Business Value) — it isn't directly verifiable. Reference it only when explaining a miss.
+
+## Phase 3 — Inspect Shipped Work
+
+Gather evidence of what was actually shipped:
+
+1. **Diff scope** — the commits on the current branch vs. the default branch:
+   ```bash
+   BASE_BRANCH="$(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@')"
+   git log "${BASE_BRANCH}"..HEAD --oneline
+   git diff "${BASE_BRANCH}"...HEAD --stat
+   ```
+2. **File-level changes** — per-file diff for each changed file:
+   ```bash
+   git diff "${BASE_BRANCH}"...HEAD -- <file>
+   ```
+3. **Test coverage** — which tests were added/changed for the requirements:
+   ```bash
+   git diff "${BASE_BRANCH}"...HEAD -- '**/*.test.*' '**/*.spec.*'
+   ```
+4. **Empirical evidence** — output of `verification-specialist` if available (proof artifacts, API captures, UI screenshots, DB queries). If that report isn't in context, ask the caller for it before proceeding — do not substitute reading code for running the system.
+5. **PR description** — `gh pr view --json title,body,files` if a PR exists.
+6. **Deployed state** — if the verification phase already hit a deployed environment, use those captures.
+
+Do NOT run the system yourself — that's the verification-specialist's job. Your job is to map their evidence to the spec.
+
+## Phase 4 — Build Coverage Matrix
+
+For every requirement extracted in Phase 2, produce one row:
+
+| Column | Value |
+|--------|-------|
+| Requirement ID | Stable identifier (e.g. `AC-1`, `OOS-2`, `ASSERT-3`) |
+| Classification | `acceptance` / `excluded` / `technical` / `assertion` / `deliverable` / `task` / `blocker` |
+| Requirement Text | Verbatim from spec |
+| Evidence | Specific pointer — file:line, test name, verification report section, PR file, screenshot name |
+| Status | `MATCH` / `PARTIAL` / `MISSING` / `SCOPE_CREEP_VIOLATION` |
+| Notes | One line — why partial, what's missing, or where evidence is thin |
+
+### Status definitions
+
+- **`MATCH`** — requirement is implemented AND there is empirical evidence it works (test + verification report).
+- **`PARTIAL`** — implementation exists but evidence is incomplete (e.g. code present, no test; or test present, no run-time verification).
+- **`MISSING`** — requirement has no corresponding implementation OR no evidence at all.
+- **`SCOPE_CREEP_VIOLATION`** — used for `excluded` classification only. An Out-of-Scope item appears to have been shipped anyway. This is a different failure than a miss — it means the agent exceeded the spec.
+
+### Scope creep detection
+
+Separately from the matrix, scan the diff for work NOT traceable to any requirement. For each such change:
+
+- Identify the file/module
+- Summarize the change in one line
+- Classify as `UNTRACEABLE_CHANGE` (not necessarily wrong — refactors often land here — but MUST be surfaced)
+
+Untraceable changes are not automatic failures. They become findings the human reviews.
+
+## Phase 5 — Verdict
+
+Produce exactly one verdict:
+
+- **`CONFORMS`** — every requirement is `MATCH`. No `SCOPE_CREEP_VIOLATION`. Untraceable changes, if any, are clearly refactors or test support.
+- **`PARTIAL`** — some requirements are `PARTIAL` but none are `MISSING` or `SCOPE_CREEP_VIOLATION`. Work is mostly there but evidence is thin.
+- **`DIVERGES`** — at least one requirement is `MISSING`, OR at least one `SCOPE_CREEP_VIOLATION` exists, OR there are substantive untraceable changes that materially alter behavior.
+
+A verdict of `PARTIAL` or `DIVERGES` blocks task completion. The caller must resolve the gaps (implement the miss, remove the creep, add the missing evidence) before re-running.
+
+## Phase 6 — Output
+
+Structure the report so it can be pasted into a PR comment or JIRA ticket:
+
+```text
+## Spec Conformance Report
+
+**Spec source:** <plan file / JIRA key / Linear / GitHub issue / PRD>
+**Shipped scope:** <N commits, M files, K tests on branch <branch> vs <default-branch>>
+
+### Coverage Matrix
+
+| ID | Class | Requirement | Evidence | Status | Notes |
+|----|-------|-------------|----------|--------|-------|
+| AC-1 | acceptance | [text] | [pointer] | MATCH | |
+| AC-2 | acceptance | [text] | — | MISSING | No corresponding code or test |
+| OOS-1 | excluded | [text] | src/foo.ts:42 | SCOPE_CREEP_VIOLATION | Added anyway |
+| ASSERT-1 | assertion | [text] | verification-report §2 | PARTIAL | Asserted in code, not run in verification |
+
+### Untraceable Changes
+- src/utils/helpers.ts — extracted shared regex constant (refactor, no behavior change)
+- src/auth/session.ts — added retry logic (NOT IN SPEC — verify intentional)
+
+### Verdict: CONFORMS | PARTIAL | DIVERGES
+
+**Matches:** N/Total
+**Partial:** N
+**Missing:** N
+**Scope creep violations:** N
+**Untraceable changes flagged for review:** N
+
+### Required Actions (if PARTIAL or DIVERGES)
+1. [specific action — implement X, remove Y, add test for Z, capture evidence for W]
+2. ...
+```
+
+## Rules
+
+- Never substitute "I read the code and it looks right" for empirical evidence. If verification-specialist hasn't run yet, request its report before producing a verdict.
+- Never mark a requirement `MATCH` based on the presence of code alone — evidence means test + runtime observation.
+- Always surface scope creep separately from misses. They are distinct failures.
+- Always surface untraceable changes — even benign refactors — so the human can confirm intent.
+- The Out of Scope section is load-bearing. If the spec has one, every item must appear in the matrix as `excluded`.
+- If the spec has no acceptance criteria, flag the spec itself as inadequate before running the matrix. The verdict is `DIVERGES` for spec inadequacy until criteria are added.
+- Do not invent requirements the spec didn't state. If the shipped work does something reasonable but unspecified, it becomes an untraceable change, not a match.

package/plugins/lisa/skills/lisa-spec-conformance/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Spec Conformance"
+short_description: "Verifies that shipped work matches its spec section-by-section — acceptance criteria, Out of Scope, Technical Approach, Validation Journey…"
+default_prompt:
+  - "Use $lisa-spec-conformance: Verifies that shipped work matches its spec section-by-section — acceptance criteria, Out of Scope, Technical Approach, Validation Journey…."