@codyswann/lisa 4.74.9 → 4.75.1

package/plugins/lisa-devin/skills/lisa-setup-github/SKILL.md

@@ -0,0 +1,319 @@
+---
+name: lisa-setup-github
+description: "Configure GitHub Issues as the destination tracker and/or the PRD source for this project. Verifies the gh CLI is installed and authenticated, resolves `org/repo`, scaffolds the build-queue label namespace (`status:*`) when GitHub is the tracker and/or the PRD-lifecycle label namespace (`prd-*` + sentinel) when GitHub is the PRD source, writes the `github` section into `.lisa.config.json`, and offers to set top-level `tracker: \"github\"` and/or `source: \"github\"`. Idempotent — re-running updates the existing section and reuses existing labels rather than duplicating. No /lisa:setup:atlassian prerequisite (GitHub auth is standalone)."
+allowed-tools: ["Bash", "Read", "Write", "Edit", "Skill", "AskUserQuestion"]
+---
+
+# Setup GitHub: $ARGUMENTS
+
+Make GitHub Issues a tracker, a PRD source, or both for this project. After this skill, `.lisa.config.json` contains `github.org` + `github.repo`, the configured repo carries the lifecycle label namespaces lisa needs, and (optionally) `tracker` / `source` point at GitHub.
+
+Unlike `setup-jira` / `setup-confluence`, this skill has **no `setup-atlassian` dependency** — GitHub auth runs through the `gh` CLI directly.
+
+## Workflow
+
+### Step 0 — Decide what GitHub is for
+
+Ask via `AskUserQuestion` (multiSelect):
+
+> What should lisa use this GitHub repo for?
+>
+> 1. **Destination tracker** — lisa writes Epics / Stories / Sub-tasks here as Issues, and the build queue (`/lisa:intake`, `/lisa:implement`) runs off the `status:*` label namespace. Sets `tracker: "github"`.
+> 2. **PRD source** — humans drop PRDs here as Issues labeled `prd-ready`; `/lisa:intake` scans and ticketes them off the `prd-*` label namespace. Sets `source: "github"`.
+
+The answer drives which label namespaces get scaffolded in Step 3: **tracker → `status:*`**, **source → `prd-*` + sentinel**. Self-host (both) is supported — the two namespaces never overlap (see the `config-resolution` rule's "Self-host edge case").
+
+If the user selects neither, stop — there's nothing to configure.
+
+### Step 1 — Ensure the gh CLI is installed and authenticated
+
+```bash
+if ! command -v gh >/dev/null 2>&1; then
+  if command -v brew >/dev/null 2>&1; then
+    brew install gh
+  else
+    cat >&2 <<'EOF'
+Error: gh (GitHub CLI) not found and Homebrew unavailable. Install it:
+  https://github.com/cli/cli#installation
+Then re-run /lisa:setup:github.
+EOF
+    exit 1
+  fi
+fi
+
+# Auth: prefer an interactive login; CI/headless uses GH_TOKEN.
+if ! gh auth status >/dev/null 2>&1; then
+  if [ -n "$GH_TOKEN" ] || [ -n "$GITHUB_TOKEN" ]; then
+    echo "gh not logged in interactively, but GH_TOKEN/GITHUB_TOKEN is set — gh will use it."
+  else
+    cat >&2 <<'EOF'
+Error: gh is not authenticated. Run:
+  gh auth login           # interactive (developer machines)
+or set GH_TOKEN as a secret (CI / headless), then re-run /lisa:setup:github.
+EOF
+    exit 1
+  fi
+fi
+```
+
+Confirm the authenticated identity can write Issues and labels — `gh auth status` shows the token scopes; `repo` scope (or fine-grained Issues: read-write + metadata: read) is required to create labels and issues. If the scopes look read-only, surface it and instruct `gh auth refresh -s repo`.
+
+### Step 2 — Resolve `org/repo`
+
+Honor any `--repo=org/repo` argument. Otherwise default-detect from the current repo's `origin` remote, then confirm — the tracker/PRD repo is frequently a *different* repo than the code repo (e.g. a dedicated `product-prds` repo):
+
+```bash
+DEFAULT_REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner 2>/dev/null)
+```
+
+Present the detected value via `AskUserQuestion`:
+
+> Use `<DEFAULT_REPO>` as the GitHub repo for lisa's issues/PRDs, or specify a different `org/repo`?
+
+Once resolved, split into `ORG` and `REPO` and confirm reachability + write access:
+
+```bash
+gh repo view "$ORG/$REPO" --json name,viewerPermission \
+  --jq 'if (.viewerPermission | IN("ADMIN","MAINTAIN","WRITE")) then "ok" else error("insufficient permission: \(.viewerPermission)") end'
+```
+
+If permission is `READ` / `TRIAGE`, stop — lisa cannot create labels or issues. Surface and exit.
+
+### Step 2b — Choose the queue repository
+
+When GitHub is selected as the destination tracker, initialize the choice from an existing
+`github.queueRepo`, or `$ORG/$REPO` when absent, then ask whether the build backlog lives there, in
+the identity repo, or in another umbrella/planning repo. If the user gives an umbrella repo, accept a short name by normalizing it to `$ORG/<name>` or accept a full
+`owner/repo`, then verify it is reachable and the authenticated identity can manage the lifecycle
+labels Lisa needs:
+
+```bash
+gh repo view "$QUEUE_ORG/$QUEUE_REPO" --json name,viewerPermission \
+  --jq 'if (.viewerPermission | IN("ADMIN","MAINTAIN","WRITE")) then "ok" else error("insufficient permission: \(.viewerPermission)") end'
+```
+
+Store `github.queueRepo` only when the canonical queue `owner/repo` differs from `$ORG/$REPO`.
+This choice changes queue scans, not repository identity: `github.repo`, `repo:<current>` claim
+scoping, issue destinations, and automation naming remain tied to the identity/tracker repo.
+
+### Step 3 — Scaffold the lifecycle label namespaces
+
+Read role → label mappings with the same default-fallback ladder the intake skills use, so the labels created here exactly match what they look for. Only the namespaces selected in Step 0 are scaffolded.
+
+```bash
+read_role() {  # $1=namespace (build|prd) $2=role $3=default
+  local ns="$1" role="$2" default="$3" local_v global_v
+  local_v=$(jq -r ".github.labels.${ns}.${role} // empty" .lisa.config.local.json 2>/dev/null)
+  global_v=$(jq -r ".github.labels.${ns}.${role} // empty" .lisa.config.json 2>/dev/null)
+  echo "${local_v:-${global_v:-$default}}"
+}
+
+# Idempotent label creator: create if missing, leave untouched if present.
+# LABEL_ORG/LABEL_REPO select the repo for the namespace being scaffolded.
+ensure_label() {  # $1=name $2=hex-color $3=description
+  local name="$1" color="$2" desc="$3"
+  if gh label list --repo "$LABEL_ORG/$LABEL_REPO" --limit 200 --json name --jq '.[].name' | grep -qxF "$name"; then
+    echo "  = $name (exists)"
+  else
+    gh label create "$name" --repo "$LABEL_ORG/$LABEL_REPO" --color "$color" --description "$desc" \
+      && echo "  + $name (created)"
+  fi
+}
+```
+
+#### 3a. Build-queue labels (only if GitHub is the tracker)
+
+Defaults from `config-resolution`. The `done` role is **env-keyed** — create all three by default; a project whose terminal state is env-independent can later collapse `github.labels.build.done` to a single string.
+
+```bash
+LABEL_ORG="$QUEUE_ORG"
+LABEL_REPO="$QUEUE_REPO"
+ensure_label "$(read_role build ready    status:ready)"        FBCA04 "Ready for build (human signal)"
+ensure_label "$(read_role build claimed  status:in-progress)"  0E8A16 "Build in progress (agent owns)"
+ensure_label "$(read_role build blocked  status:blocked)"      D93F0B "Blocked — human attention required"
+ensure_label "$(read_role build done.dev        status:on-dev)" 1D76DB "Deployed to dev"
+ensure_label "$(read_role build done.staging    status:on-stg)" 1D76DB "Deployed to staging"
+ensure_label "$(read_role build done.production status:done)"   0E8A16 "Shipped to production"
+```
+
+#### 3b. PRD-lifecycle labels (only if GitHub is the PRD source)
+
+```bash
+LABEL_ORG="$ORG"
+LABEL_REPO="$REPO"
+ensure_label "$(read_role prd draft     prd-draft)"            C5DEF5 "PRD in progress (product owns)"
+ensure_label "$(read_role prd ready     prd-ready)"            FBCA04 "PRD ready for ticketing"
+ensure_label "$(read_role prd in_review prd-in-review)"        5319E7 "Claude is reviewing this PRD"
+ensure_label "$(read_role prd blocked   prd-blocked)"          D93F0B "PRD blocked — see comments"
+ensure_label "$(read_role prd ticketed  prd-ticketed)"         0E8A16 "Tickets created — see comments"
+ensure_label "$(read_role prd shipped   prd-shipped)"          1D76DB "Work delivered (product owns)"
+ensure_label "$(read_role prd verified  prd-verified)"         0E8A16 "Shipped product empirically verified against the PRD (product owns)"
+ensure_label "$(read_role prd sentinel  prd-intake-feedback)"  EDEDED "Marker for PRD-intake feedback issues"
+```
+
+#### 3c. Handle name collisions / renames
+
+If a project already uses a differently-named label for a role (e.g. `ready-for-dev` instead of `status:ready`), do NOT create a duplicate. Present the repo's existing labels via `AskUserQuestion` and let the user map the role to the existing label — that mapping becomes an override written in Step 4. Renaming-in-place (keeping lisa's defaults) is also fine if the user prefers; just surface the choice.
+
+### Step 4 — Write `.lisa.config.json`
+
+`github.org` / `github.repo` are project-wide → committed. Write **only label keys that differ from the documented defaults** — never echo the full default map into config (keeps it lean; missing keys inherit defaults at runtime).
+
+```bash
+touch .lisa.config.json
+[ -s .lisa.config.json ] || echo '{}' > .lisa.config.json
+
+jq --arg org "$ORG" --arg repo "$REPO" \
+   '.github = ((.github // {}) | .org = $org | .repo = $repo)' \
+   .lisa.config.json > .lisa.config.json.tmp && mv .lisa.config.json.tmp .lisa.config.json
+
+# Queue repo is canonical owner/repo and omitted for the identity/default case.
+# A source-only setup rerun preserves any existing build-queue choice.
+if [ "$GITHUB_TRACKER_SELECTED" = "true" ]; then
+  if [ "$QUEUE_ORG/$QUEUE_REPO" = "$ORG/$REPO" ]; then
+    jq 'del(.github.queueRepo)' .lisa.config.json > .lisa.config.json.tmp \
+      && mv .lisa.config.json.tmp .lisa.config.json
+  else
+    jq --arg queue "$QUEUE_ORG/$QUEUE_REPO" '.github.queueRepo = $queue' \
+      .lisa.config.json > .lisa.config.json.tmp \
+      && mv .lisa.config.json.tmp .lisa.config.json
+  fi
+fi
+
+# Conditionally write label overrides (only roles the user mapped to non-default names).
+# $LABEL_OVERRIDES_JSON is e.g. {"build":{"ready":"ready-for-dev"}} — {} if all defaults.
+if [ -n "$LABEL_OVERRIDES_JSON" ] && [ "$LABEL_OVERRIDES_JSON" != "{}" ]; then
+  jq --argjson o "$LABEL_OVERRIDES_JSON" \
+     '.github.labels = ((.github.labels // {}) * $o)' \
+     .lisa.config.json > .lisa.config.json.tmp && mv .lisa.config.json.tmp .lisa.config.json
+fi
+```
+
+If this project later enables shared GitHub Project coordination, store it under the same `github` block as:
+
+```json
+"github": {
+  "org": "<tracked-repo-owner>",
+  "repo": "<tracked-repo>",
+  "projects": {
+    "v2": {
+      "owner": { "kind": "organization", "slug": "<tracked-repo-owner>" },
+      "number": 7,
+      "required": false
+    }
+  }
+}
+```
+
+That block is optional and coordination-only: real issues and pull requests stay the durable source of truth. In v1, `github.projects.v2.owner.slug` MUST match the tracked repository namespace (`github.org`) — user-owned repos use a user-owned Project, org-owned repos use an org-owned Project, and cross-namespace Project ownership is rejected. `required` defaults to `false`, meaning Project membership is best-effort unless a later setup/doctor flow explicitly opts into strict mode.
+
+When that block is present, later setup/doctor and runtime validation must read the shared Project's owner + access before membership writes depend on it. Best-effort mode (`required: false`) reports warning-level validation failures and continues repository-local writes without Project membership; strict mode (`required: true`) reports the same failures as blocking errors and stops the write.
+
+No secrets go in config — the GitHub token lives in `gh`'s own store (`~/.config/gh/`) or the `GH_TOKEN` env var, never in `.lisa.config.json`.
+
+### Step 5 — Offer to set top-level `tracker` / `source`
+
+For each role selected in Step 0, offer the matching top-level flag (skip if already set to GitHub).
+
+If **tracker** was selected and `.tracker` is unset or not `"github"`, ask via `AskUserQuestion`:
+
+> Repo `<org>/<repo>` configured. Set top-level `tracker: "github"` so all vendor-neutral skills write Issues here?
+
+If yes: `jq '.tracker = "github"' ...`
+
+If **source** was selected and `.source` is unset or not `"github"`, ask:
+
+> Set top-level `source: "github"` so `/lisa:intake` (with no args) scans this repo for `prd-ready` PRDs?
+
+If yes: `jq '.source = "github"' ...`
+
+Both are project-wide switches that change every downstream skill's default — never set either without explicit confirmation.
+
+### Step 6 — Verify
+
+```bash
+jq -e '.github.org and .github.repo' .lisa.config.json >/dev/null
+EFFECTIVE_ORG=$(jq -r '.github.org // empty' .lisa.config.local.json 2>/dev/null)
+EFFECTIVE_ORG=${EFFECTIVE_ORG:-$(jq -r '.github.org' .lisa.config.json)}
+EFFECTIVE_REPO=$(jq -r '.github.repo // empty' .lisa.config.local.json 2>/dev/null)
+EFFECTIVE_REPO=${EFFECTIVE_REPO:-$(jq -r '.github.repo' .lisa.config.json)}
+QUEUE_VALUE=$(jq -r '.github.queueRepo // empty' .lisa.config.local.json 2>/dev/null)
+QUEUE_VALUE=${QUEUE_VALUE:-$(jq -r '.github.queueRepo // empty' .lisa.config.json)}
+if [ -z "$QUEUE_VALUE" ]; then
+  QUEUE_REF="$EFFECTIVE_ORG/$EFFECTIVE_REPO"
+elif [[ "$QUEUE_VALUE" == */* ]]; then
+  QUEUE_REF="$QUEUE_VALUE"
+else
+  QUEUE_REF="$EFFECTIVE_ORG/$QUEUE_VALUE"
+fi
+gh repo view "$QUEUE_REF" --json nameWithOwner --jq .nameWithOwner
+gh label list --repo "$ORG/$REPO" --limit 200 --json name --jq '.[].name' \
+  | grep -E 'prd-' || true
+gh label list --repo "$QUEUE_REF" --limit 200 --json name --jq '.[].name' \
+  | grep -E 'status:' || true
+```
+
+If `github.projects.v2` is configured, setup verification MUST also run the shared Project utility in
+read-only resolution mode before declaring success:
+
+```text
+operation: resolve-project
+```
+
+This is the setup/doctor chokepoint for GitHub Project coordination. Do not inline ad-hoc GraphQL
+here; delegate to `lisa-github-project-v2` so setup, doctor, writers, and linked-PR flows all read
+the same owner/access contract and surface the same exact failure text.
+
+Verification contract when `github.projects.v2` is present:
+
+- First enforce the v1 namespace rule locally: `github.projects.v2.owner.slug` MUST equal
+  `github.org`. If not, report the exact configuration failure and remediation:
+
+  ```yaml
+  code: project_namespace_mismatch
+  message: "github.projects.v2.owner.slug must match github.org in v1"
+  remediation: "Use a Project owned by <github.org> or remove github.projects.v2."
+  ```
+
+- Then resolve the configured Project owner + number through `lisa-github-project-v2`.
+- Preserve the exact GitHub / GraphQL failure text for inaccessible or unsupported Project
+  configurations. Examples: missing Project, `Resource not accessible by integration`, unsupported
+  owner kind, or any other Project read failure.
+- Report the exact remediation path. At minimum, say whether the operator must:
+  1. choose a Project owned by the tracked repo namespace,
+  2. grant the token Project read/write access,
+  3. correct the configured Project number/owner, or
+  4. remove `github.projects.v2` if coordination is not required.
+- Branch severity on `required` exactly the same way the shared utility does:
+  `required: false` => warning-level validation failure, continue repository-local setup success;
+  `required: true` => blocking verification failure, stop setup/doctor before claiming coordination
+  is usable.
+
+The verify output should make the operator's next step obvious. Good examples:
+
+```text
+WARNING github.projects.v2: Resource not accessible by integration
+Remediation: grant the token Project read/write access or remove github.projects.v2.required.
+Repository-local GitHub issue/PR flows remain usable; Project coordination is disabled.
+```
+
+```text
+ERROR github.projects.v2: github.projects.v2.owner.slug must match github.org in v1
+Remediation: use a Project owned by CodySwannGT or remove github.projects.v2.
+```
+
+Report success with the resolved `org/repo`, which label namespaces were scaffolded (and which labels already existed vs. were created), any non-default label overrides written, and whether `tracker` / `source` were set. Direct the user to `/lisa:intake` to test.
+
+## Idempotency
+
+- Re-running merges the `github` section's fields rather than appending — `jq` merge semantics throughout.
+- `ensure_label` is find-or-create: existing labels are left exactly as they are (color/description not overwritten), so a re-run never churns labels a human customized.
+- Re-running does not re-prompt for `tracker` / `source` if they already point at GitHub.
+
+## Rules
+
+- Never write the GitHub token to `.lisa.config.json`. It stays in `gh`'s store or `GH_TOKEN`.
+- Never create a duplicate label for a role that already has a (differently-named) label — map the role to the existing label and record it as a config override instead.
+- Never overload one label across both the PRD and build namespaces — a single issue is either a PRD or a build ticket, never both (see `config-resolution`).
+- Never set `tracker` / `source` without explicit user confirmation — they're project-wide and switch every downstream skill's behavior.
+- Never invent an `org/repo`. Default-detect from the remote and confirm; if detection fails, ask the user to supply it.

package/plugins/lisa-devin/skills/lisa-setup-github-repo/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: lisa-setup-github-repo
+description: "Apply Lisa's GitHub repository governance baseline to the current project's repo: repository settings (merge-only, auto-merge, delete-branch-on-merge, update-branch suggestions, wiki off, secret scanning where available), branch + tag rulesets from Lisa templates (base PR gate with CodeRabbit/GitGuardian/Quality Checks, prevent delete, protect tags, stack overlays), a write-access deploy key + DEPLOY_KEY secret so release workflows can push version bumps through the rulesets' DeployKey bypass, and optional deployment environments with human-approval gates (required reviewers) from the github.environments block in .lisa.config.json. Idempotent — re-running updates settings, rulesets, and environments in place and skips an already-configured deploy key."
+allowed-tools: ["Bash", "Read", "Edit", "AskUserQuestion"]
+---
+
+# Setup GitHub Repository Governance
+
+Apply the fleet-standard GitHub repository configuration to this project's repo. The settings, rulesets, and deploy key that used to be clicked together by hand for every new repo are applied here as one scripted flow.
+
+## What gets applied
+
+1. **Repository settings** (`scripts/lisa-github-repo-settings.sh`)
+   - Merge commits on; squash and rebase merging **off** (merge-only policy)
+   - Merge commit title/message from the PR (`MERGE_MESSAGE` / `PR_TITLE`)
+   - Auto-merge **on** — per-repo opt-out via `.lisa.config.json`:
+     ```json
+     { "github": { "settings": { "allow_auto_merge": false } } }
+     ```
+     (any key under `github.settings` overrides the baseline)
+   - Delete head branches after merge (environment branches survive — the rulesets' `deletion` rule means GitHub refuses to delete them)
+   - "Always suggest updating pull request branches" on
+   - Default branch set to the lowest-tier environment branch that exists (dev → staging → main); override with `github.settings.default_branch`
+   - GitHub wiki tab off (Lisa projects use in-repo `wiki/`)
+   - Secret scanning + push protection enabled where the plan supports it
+2. **Rulesets** (`scripts/lisa-github-rulesets.sh`) — one generated from config, the rest from Lisa's `<type>/github-rulesets/` templates matched by project type:
+   - `base` — **generated from `.lisa.config.json`**, not shipped as a template. Deletion/force-push protection from `policy.protect`, the branch list from `policy.ruleset.include_refs`, bypass actors from `policy.ruleset.bypass_actors`, approvals from `policy.review`, merge methods from `policy.merge`, and required checks from whatever gates the project `await`s. A project that declares nothing gets exactly the ruleset the retired `all/github-rulesets/base.json` described, minus its two vendor checks — those are now `await` declarations a project can choose not to make
+   - `quality checks` — the stack's CI checks (TypeScript emoji names or Rails names)
+   - `prevent delete`, `protect tags` (`v*`), plus stack overlays (`cdk validation`, staging-only `playwright`)
+   - Repos without `.github/workflows/` get only app-based required checks — an Actions check that can never report would block every PR forever
+   - **A template change never reaches an already-configured repo on its own** — re-running this step is the migration. Each context the run newly makes blocking is printed as `+ now required: <context>`, and a ruleset that already satisfies its template reports `nothing to do` and is not sent at all, so a second run is visibly a no-op
+   - **Declaring a ruleset's required list makes it declarative.** By default a live-only required context is preserved, never dropped — including on the generated `base`, which gets no exemption: removing a protection by default, on a script invoked with `--yes`, is not something an operator ever opted into. Name a ruleset in `github.rulesets.requiredChecks` and the live list stops being unioned in, so removing an entry actually stops requiring it — printed as `- no longer required: <context>`. Dropping an `await` without that opt-in leaves the live context in place; `lisa-reconcile-policy.mjs` then reports it as EXTRA, and `--prune` is where the removal is asked for. The retired `addRequiredChecks` is still read and could only ever add
+   - **Bypass actors follow the same contract.** By default a live bypass actor the template does not name (e.g. an admin `RepositoryRole` someone added on purpose) is kept, the template's actors are added beside it, and a live actor's `bypass_mode` is never widened back to the template's. Declaring a ruleset's list — `github.rulesets.bypassActors.<ruleset name>` for a template ruleset, `policy.ruleset.bypass_actors` for the generated `base` — makes it exactly that list, which is the only way to remove one. Every change is printed by name, dry run included: `+ bypass actor added: <type> [<id>] (<mode>)`, a warning `- bypass actor removed: …`, and `~ bypass actor mode changed: <type> [<id>] (<old> -> <new>)`
+3. **Deploy key** (`scripts/setup-deploy-key.sh --yes`) — write-access deploy key + `DEPLOY_KEY` secret, skipped when already configured. The `base` ruleset's `DeployKey: always` bypass is what lets CI version-bump pushes through protected branches.
+4. **Deployment environments** (`scripts/lisa-github-environments.sh`) — entirely optional; only runs when `.lisa.config.json` declares environments:
+   ```json
+   {
+     "github": {
+       "environments": {
+         "production": {
+           "branch": "main",
+           "require_approval": true,
+           "reviewers": ["some-user", "some-org/some-team"],
+           "prevent_self_review": false,
+           "wait_timer": 0
+         },
+         "staging": { "branch": "staging" }
+       }
+     }
+   }
+   ```
+   - Environment names are friendly names (`production`), mapped to branches. Branch resolution order: explicit `branch` → `deploy.branches[<name>]` → the name itself.
+   - `require_approval: true` provisions **required reviewers** (usernames or `org/team-slug`, max 6) — GitHub pauses any workflow job bound to the environment until a listed reviewer approves it in the Actions UI. Reviewers are mandatory when `require_approval` is true; the script refuses a gate nobody can approve.
+   - Every declared environment also gets a **deployment branch policy** pinned to its branch, so only that branch can deploy to it.
+   - Provisioning matters: GitHub silently auto-creates an environment **without** protection rules the first time a workflow references it, so an unprovisioned approval gate gates on nothing.
+   - The stack `deploy.yml` templates read this same config at runtime and pass `require_approval`/`approval_environment` to `release.yml`, whose `release_approval` job is where the run pauses. Requires a public repo or a paid plan for private repos (the script skips gracefully otherwise).
+5. **Policy reconciliation** (`scripts/lisa-reconcile-policy.mjs`, also `npm run policy:reconcile`) — compares the DECLARED gates and `policy` block against what GitHub actually has, and converges it when `policy.on_drift` is `repair`. It runs here rather than only from a skill file, because a declaration nothing applies is not governance.
+   - The installed `scripts/lisa-reconcile-policy.mjs` is preferred; the shipped template is the fallback; finding neither is a hard failure, not a skip.
+   - Exit `2` is `UNPROVEN` — `gh` refused, is missing, or answered something unparseable. A private repository on a plan without rulesets answers `403`. Setup **warns and continues**: failing for a plan limitation punishes a repository that has done nothing wrong. The warning names the state, because a blind gate that says nothing is indistinguishable from a clean one.
+
+## Workflow
+
+### Step 1 — Locate the scripts
+
+In the Lisa repo itself, use `scripts/` directly. In a downstream project, use the installed package:
+
+```bash
+LISA_SCRIPTS=$(ls -d node_modules/@codyswann/lisa/scripts 2>/dev/null || echo scripts)
+```
+
+### Step 2 — Dry-run and show the plan
+
+```bash
+bash "$LISA_SCRIPTS/lisa-github-repo-setup.sh" --dry-run .
+```
+
+Present what would change. If the repo already matches the baseline, say so and stop.
+
+### Step 3 — Apply
+
+```bash
+bash "$LISA_SCRIPTS/lisa-github-repo-setup.sh" .
+```
+
+Requires `gh` authenticated with **admin** permission on the repo. A 403 on rulesets means the plan doesn't support them (private repo on a free personal plan) — settings and deploy key still apply; the script skips rulesets gracefully.
+
+### Step 4 — Wire the approval gate into an existing deploy.yml (guided edit)
+
+Only when `.lisa.config.json` has a `github.environments` entry with `require_approval: true` AND `.github/workflows/deploy.yml` exists but does not reference `approval_environment`:
+
+```bash
+[ -f .github/workflows/deploy.yml ] \
+  && jq -e '[.github.environments // {} | .[] | select(.require_approval == true)] | length > 0' .lisa.config.json > /dev/null 2>&1 \
+  && ! grep -q 'approval_environment' .github/workflows/deploy.yml \
+  && echo "deploy.yml needs approval wiring"
+```
+
+A `grep` hit is only a first pass — before skipping the edit, read the `release` job's `with:` block and confirm it actually passes both `require_approval` and `approval_environment` from the `determine_environment` outputs (a commented-out or unrelated occurrence doesn't count as wired).
+
+`deploy.yml` is create-only — the project owns it, so Lisa never patches it automatically. Show the user the two changes from the current stack template (`<stack>/create-only/.github/workflows/deploy.yml` in the Lisa repo) and offer to apply them via Edit:
+
+1. In `determine_environment`, add a checkout step plus the `🚦 Resolve approval gate from .lisa.config.json` step, and expose the `approval_environment` / `require_approval` outputs.
+2. In the `release` job's `with:` block, replace `require_approval: false` with:
+   ```yaml
+   require_approval: ${{ needs.determine_environment.outputs.require_approval == 'true' }}
+   approval_environment: ${{ needs.determine_environment.outputs.approval_environment }}
+   ```
+
+Skip this step (and say why) if the project's deploy.yml doesn't call Lisa's `release.yml` (rails uses `release-rails.yml` and harper-fabric has no release call — approval gating for those stacks is not wired yet).
+
+### Step 5 — Verify
+
+```bash
+gh api "repos/$(gh repo view --json nameWithOwner -q .nameWithOwner)" \
+  --jq '{allow_squash_merge, allow_auto_merge, delete_branch_on_merge, allow_update_branch}'
+gh api "repos/$(gh repo view --json nameWithOwner -q .nameWithOwner)/rulesets" --jq '[.[].name]'
+```
+
+When environments were configured, also confirm each one carries its protection rules and branch policy:
+
+```bash
+gh api "repos/$(gh repo view --json nameWithOwner -q .nameWithOwner)/environments" \
+  --jq '.environments[] | {name, protection_rules, deployment_branch_policy}'
+```
+
+For every environment declared in `github.environments`, treat a missing `deployment_branch_policy` — or, when `require_approval` is true, an empty `protection_rules` — as a failure: the environment exists but is unprotected, so an approval gate bound to it would block nothing.
+
+Report the applied settings, ruleset names, and environments. If any step failed, surface the error — do not mark the setup complete.

package/plugins/lisa-devin/skills/lisa-setup-jira/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: lisa-setup-jira
+description: "Configure JIRA as the destination tracker for this project. Writes `jira.project` into `.lisa.config.json` and offers to set top-level `tracker: \"jira\"`. Depends on /lisa:setup:atlassian — atlassian.cloudId must already be present, otherwise this skill stops and instructs the user to run setup-atlassian first. Idempotent."
+allowed-tools: ["Bash", "Read", "Write", "Edit", "Skill", "AskUserQuestion"]
+---
+
+# Setup JIRA: $ARGUMENTS
+
+Set the JIRA project key and (optionally) make JIRA this project's destination tracker.
+
+## Workflow
+
+### Step 1 — Verify atlassian prerequisite
+
+```bash
+cloudid=$(jq -r '.atlassian.cloudId // empty' .lisa.config.json 2>/dev/null)
+if [ -z "$cloudid" ]; then
+  echo "Error: atlassian.cloudId not set. Run /lisa:setup:atlassian first." >&2
+  exit 1
+fi
+```
+
+If `atlassian` is missing, invoke `/lisa:setup-atlassian` via the Skill tool first, then resume.
+
+### Step 2 — Resolve the JIRA project key
+
+Honor any `--project=KEY` argument. Otherwise, list projects via the active access substrate:
+
+- CLI: `acli jira project list --output json`
+- MCP: `mcp__plugin_atlassian_atlassian__getVisibleJiraProjects` with `cloudId=$cloudid`
+
+If only one project is returned, pick it. If multiple, present them via `AskUserQuestion` (label = project key, description = project name) so the user picks the one this project should target.
+
+### Step 3 — Probe workflow & resolve role mapping
+
+Lisa's build lifecycle uses three role-keyed statuses (`ready` → `claimed` → `done[env]`). Defaults are `Ready`, `In Progress`, and `{dev: "On Dev", staging: "On Stg", production: "Done"}`. Probe the project's workflow to confirm these exist; prompt for overrides if not.
+
+```bash
+# Fetch a sample ticket's available transitions (or use a project-level workflow scheme query)
+# via lisa-atlassian-access operation: transitions key: <SAMPLE-KEY>
+# Collect the union of status names visible in the project.
+```
+
+For each role:
+
+1. If a status with the **default name** exists in the workflow → use the default; no config entry needed.
+2. If the default name is missing but a status with a similar role exists (e.g. `Resolved` instead of `Done`) → present the project's status list via `AskUserQuestion` and let the user pick which maps to the role.
+3. If nothing plausible exists → stop and tell the user to either add the missing status to their JIRA workflow (admin task) or pick a fallback that's close enough.
+
+Collect overrides as a partial workflow map. ONLY write keys that differ from defaults — don't bloat the config with redundant values.
+
+### Step 4 — Write `jira.project` + overrides
+
+```bash
+# Always write project key.
+jq --arg key "$PROJECT_KEY" \
+   '.jira = ((.jira // {}) | .project = $key)' \
+   .lisa.config.json > .lisa.config.json.tmp \
+   && mv .lisa.config.json.tmp .lisa.config.json
+
+# Conditionally write workflow overrides (only if any role differs from default).
+if [ -n "$WORKFLOW_OVERRIDES_JSON" ]; then
+  jq --argjson wf "$WORKFLOW_OVERRIDES_JSON" \
+     '.jira.workflow = $wf' \
+     .lisa.config.json > .lisa.config.json.tmp \
+     && mv .lisa.config.json.tmp .lisa.config.json
+fi
+```
+
+### Step 5 — Verify transition reachability (A → B → C cascade)
+
+Confirm every resolved role's status name is actually reachable in the JIRA workflow. **acli has no non-destructive workflow inspector** (the `workitem view --json` `transitions` key is always `null` because acli doesn't pass `expand=transitions`), so verification cascades through three modes, each more invasive than the last.
+
+#### Cache check (skip if unchanged)
+
+Hash the workflow-mapping object plus the project key:
+
+```bash
+WORKFLOW_HASH=$(jq -c '{project: .jira.project, workflow: .jira.workflow}' .lisa.config.json | shasum -a 256 | awk '{print $1}')
+CACHED=$(jq -r '.jira.verified_workflow_hash // empty' .lisa.config.local.json 2>/dev/null)
+if [ "$WORKFLOW_HASH" = "$CACHED" ]; then
+  echo "Workflow already verified; skipping probe."
+  # proceed to Step 6
+fi
+```
+
+The verification cache key lives in `.lisa.config.local.json` (per-developer, gitignored) because the workflow on disk might be stale relative to the user's local view of it.
+
+#### Mode A — Changelog inspection (non-destructive, fast)
+
+Aggregate every status name ever observed in the project's ticket histories:
+
+```bash
+acli jira workitem search --jql "project = $PROJECT" --paginate --json \
+  | jq -r '[.[].changelog.histories[]?.items[]? | select(.field == "status") | .fromString, .toString] | unique[]' \
+  | sort -u > /tmp/lisa-observed-statuses.txt
+```
+
+For each role (`ready`, `claimed`, `blocked`, each `done.<env>`), check whether the resolved status name appears in the observed set. Roles that match are **verified**. Roles that don't are **unverified** — but that doesn't yet mean they're missing; freshly-added statuses simply haven't accumulated history.
+
+If every role is verified, cache the hash and proceed to Step 6.
+
+#### Mode B — Create-probe-delete (synthetic ticket)
+
+For any role left unverified by Mode A, fall back to creating a throwaway ticket and walking it through.
+
+Prompt via `AskUserQuestion`:
+
+> Mode A could not verify these roles: `<list>`. Create a synthetic probe ticket to verify (recommended), or designate an existing ticket to use as the probe?
+
+If user picks synthetic:
+
+```bash
+# Create a probe ticket. Title makes its purpose obvious so a teammate doesn't act on it.
+PROBE_KEY=$(acli jira workitem create \
+  --project "$PROJECT" \
+  --type Task \
+  --summary "lisa-setup-probe (DELETE ME)" \
+  --description "Created by /lisa:setup:jira to verify workflow status reachability. Safe to delete." \
+  --json \
+  | jq -r '.key')
+
+trap 'acli jira workitem delete --key "$PROBE_KEY" --yes 2>/dev/null || acli jira workitem archive --key "$PROBE_KEY" --yes 2>/dev/null' EXIT
+
+# Walk through every unverified role's status in order.
+for status in $UNVERIFIED_STATUSES; do
+  if ! acli jira workitem transition --key "$PROBE_KEY" --status "$status" --yes 2>/dev/null; then
+    echo "Error: status '$status' is not reachable in the workflow from the probe ticket's current state." >&2
+    # Mark this role as missing; continue with remaining roles where possible (skip if transition is from a state we couldn't reach).
+    break
+  fi
+done
+
+# trap handles cleanup
+```
+
+If `acli jira workitem create` fails because the project has required fields, surface the field list and instruct the user to either (a) fill them in via `--field`/`--from-json`, (b) temporarily relax the required-fields configuration, or (c) fall through to Mode C.
+
+#### Mode C — Probe an existing ticket (last resort)
+
+If Mode B can't create a probe (mandatory fields, permission, etc.), prompt the user to designate a low-stakes existing ticket:
+
+> Provide a ticket key in `To Do` (or wherever you want to start the probe). I'll walk it through the unverified statuses and revert.
+
+Capture the ticket's starting status; walk through the unverified chain; revert to the starting status at the end. Use `trap` to ensure revert runs even on error.
+
+#### Outcome
+
+Once all roles are verified by some combination of A/B/C, cache the result:
+
+```bash
+jq --arg hash "$WORKFLOW_HASH" \
+   '.jira = ((.jira // {}) | .verified_workflow_hash = $hash)' \
+   .lisa.config.local.json > .lisa.config.local.json.tmp \
+   && mv .lisa.config.local.json.tmp .lisa.config.local.json
+```
+
+If any role is **unreachable** after all three modes, stop and surface a concrete admin-task message (which transition needs to be added, between which two statuses, in which workflow). Do not write a config that points at unreachable transitions.
+
+### Step 6 — Verify mid-build transition chain
+
+Independent of role reachability, confirm the lifecycle's required *transition graph* is intact: `ready → claimed`, `claimed → done.<env>` for each env. Mode A's changelog includes paired `(fromString, toString)` entries — count any pair that matches a required transition as verified. Modes B and C do this implicitly by walking the chain in order. If any required transition is missing (e.g., `claimed → done.staging` requires going through `review` first per the workflow), surface and stop with an admin remediation.
+
+### Step 7 — Offer to set top-level `tracker`
+
+If `.tracker` is unset or differs from `"jira"`, ask via `AskUserQuestion`:
+
+> JIRA project `<KEY>` written. Set top-level `tracker: "jira"` so all vendor-neutral skills target JIRA?
+
+Recommend "Yes" unless the project is using a different destination (e.g., GitHub Issues for build-queue but JIRA for read-only mirror — rare).
+
+If yes:
+
+```bash
+jq '.tracker = "jira"' .lisa.config.json > .lisa.config.json.tmp \
+   && mv .lisa.config.json.tmp .lisa.config.json
+```
+
+### Step 8 — Verify
+
+```bash
+jq -e '.jira.project' .lisa.config.json >/dev/null
+jq -e '.tracker' .lisa.config.json >/dev/null   # if user said yes in step 7
+```
+
+Report success with the resolved project key, the workflow mapping (defaults vs. overrides), and whether `tracker` was set.
+
+## Idempotency
+
+- Re-running replaces `jira.project` cleanly (jq merge, not append).
+- Re-running does not re-prompt for `tracker` if it's already `"jira"`.
+- Re-running with an unchanged workflow mapping skips the verification probe (Mode A/B/C) entirely via the `verified_workflow_hash` cache in `.lisa.config.local.json`. Editing any role name invalidates the cache and re-runs the probe.
+
+## Rules
+
+- Never invent a project key. If discovery fails (no projects visible), surface the error and ask the user to verify their JIRA permissions.
+- Never set `tracker` without explicit user confirmation — `tracker` is project-wide and switching it changes every downstream skill's behavior.
+- Never write env-level config (api tokens, server URLs) into `.lisa.config.json`.