@codyswann/lisa 2.189.7 → 2.189.9

package/plugins/lisa-agy/skills/lisa-github-add-journey/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: lisa-github-add-journey
+description: "Add a Validation Journey section to an existing GitHub Issue by analyzing the change type and generating appropriate verification steps with evidence markers. The GitHub counterpart of lisa-jira-add-journey."
+allowed-tools: ["Bash", "Skill"]
+---
+
+# Add Validation Journey to Existing GitHub Issue
+
+Read an existing GitHub Issue, analyze the change type, and append a `## Validation Journey` markdown section with appropriate verification steps based on the project's verification patterns.
+
+## Arguments
+
+`$ARGUMENTS`: `<ISSUE_REF>`
+
+- `ISSUE_REF` (required): GitHub issue ref — `org/repo#<number>` or full GitHub issue URL.
+
+## Prerequisites
+
+- `gh` CLI authenticated (`gh auth status`).
+
+## Workflow
+
+### Step 1: Read the Issue
+
+```bash
+gh issue view <number> --repo <org>/<repo> --json number,title,body,labels,assignees,milestone,url
+```
+
+Extract: title, body, type (from `type:` label), components (from `component:` labels), assignees, linked PRs.
+
+### Step 2: Check for Existing Journey
+
+Parse the body for an existing `## Validation Journey` heading. If present and the section contains at least one `[EVIDENCE: <name>]` marker, the issue already has a journey — report this to the user and stop.
+
+### Step 3: Analyze the Change Type
+
+Examine the body, acceptance criteria, and codebase to determine the change type:
+
+1. **API/GraphQL changes** — New or modified endpoints, request/response schemas
+2. **Database migration** — Schema changes, new tables/columns, indexes
+3. **Background job/queue** — New job processors, queue consumers, event handlers
+4. **Library/utility** — Exported functions, shared modules, npm package changes
+5. **Security fix** — Auth, authorization, input validation, OWASP vulnerabilities
+6. **Authentication/authorization** — Role-based access, session management, tokens
+
+Use Explore agents or read the codebase directly to understand which files are affected.
+
+### Step 4: Map Change Type to Verification Pattern
+
+| Change Type | Verification Approach |
+|---|---|
+| API/GraphQL | curl commands verifying endpoints, status codes, response schemas |
+| Database migration | Migration execution + schema verification + rollback check |
+| Background job/queue | Enqueue + process + state change verification |
+| Library/utility | Test execution + build verification + export check |
+| Security fix | Exploit reproduction pre-fix + exploit failure post-fix |
+| Auth/authz | Multi-role verification with explicit status codes |
+
+### Step 5: Draft the Validation Journey
+
+Compose the journey with `[EVIDENCE: name]` markers at key verification points:
+
+```markdown
+## Validation Journey
+
+### Prerequisites
+- List required services, database, env vars
+
+### Steps
+1. Verify current state before changes
+2. Apply the change
+3. Verify expected new state [EVIDENCE: state-name]
+4. Test error/edge cases [EVIDENCE: error-case]
+5. Verify rollback if applicable [EVIDENCE: rollback]
+
+### Assertions
+- Describe what must be true after verification
+```
+
+### Guidelines for Drafting
+
+1. **2–5 evidence markers** — Focus on proving the change works and handles errors.
+2. **Concrete, runnable steps** — `Run \`curl -s localhost:3000/health | jq .status\`` not "Check the endpoint".
+3. **Include environment setup** — Database connection, running services, env vars.
+4. **Evidence names in kebab-case** — `api-response`, `schema-check`, `rate-limit-hit`.
+5. **Assertions are measurable** — `Returns 200 with {status: ok}` not "API works correctly".
+6. **Cover happy path AND error path** — At minimum, one success and one failure marker.
+7. **On a leaf work unit, the markers are binding** — For a Bug / Task / Sub-task / Improvement, every `[EVIDENCE: name]` here is the issue's evidence manifest: validation gate S14 requires at least one, and the issue cannot be closed until each named artifact is captured and attached (see the "Per-Work-Unit Evidence Contract" in the `verification` rule). Name only evidence you intend to capture — and name all of it.
+
+### Step 6: Present to User for Approval
+
+Display the drafted Validation Journey and ask for confirmation before appending it to the issue body. (If invoked from a parent skill running unattended — e.g., `lisa-github-write-issue` Phase 6 step 5 — proceed without the prompt.)
+
+### Step 7: Append to Issue Body
+
+After approval:
+
+```bash
+current_body=$(gh issue view <number> --repo <org>/<repo> --json body --jq '.body')
+# Compose new body: existing + "\n\n## Validation Journey\n..." (or replace if present)
+gh issue edit <number> --repo <org>/<repo> --body-file /tmp/updated-body.md
+```
+
+Preserve every other section verbatim — never re-render the body from parsed fields, since the issue may carry `extra_sections` we don't recognize.
+
+### Step 8: Verify
+
+Re-read the issue and confirm the `## Validation Journey` section is present and includes at least one `[EVIDENCE: <name>]` marker.
+
+## When to Use This Skill
+
+- Issue was created before the Validation Journey convention was established.
+- Issue was created manually without following `lisa-github-create` guidelines.
+- Issue needs a journey added or updated based on implementation progress.
+- Before starting work on an issue, to ensure verification steps are documented.

package/plugins/lisa-agy/skills/lisa-github-build-intake/SKILL.md

@@ -0,0 +1,446 @@
+---
+name: lisa-github-build-intake
+description: "GitHub counterpart to lisa-jira-build-intake. Scans a GitHub repository for issues carrying the configured `ready` build label, processes the first eligible issue, runs leaf work via lisa-github-agent, relabels to the configured `done` label on completion, then exits. Enforces the claim-time arm of the `leaf-only-lifecycle` rule: a parent/container with open child work (or a childless Epic) that still carries a stale build-ready label is moved out of the ready pickup queue into the configured `claimed` label with a lifecycle-repair comment, never dispatched to lisa-github-agent. The `ready` label is the human-flipped signal that an issue is truly ready for direct development pickup — mirroring how Notion PRDs work product Draft → Ready → (us) In Review → Blocked|Ticketed."
+allowed-tools: ["Skill", "Bash"]
+---
+
+# GitHub Build Intake: $ARGUMENTS
+
+`$ARGUMENTS` is one of:
+
+1. A GitHub `org/repo` token (e.g., `acme/frontend-v2`).
+2. A full GitHub repo URL (e.g., `https://github.com/acme/frontend-v2`).
+3. The literal token `github` — falls back to `.lisa.config.json` (`github.org` / `github.repo`).
+
+Run one build-intake cycle. The first eligible issue in the configured `ready` build label is claimed, built via the `lisa-github-agent` flow, relabeled to the configured `done` label (env-aware — see Workflow resolution), then the cycle exits. Remaining ready issues stay queued for later scheduler invocations.
+
+This skill also accepts an optional `assignee=<github-login>` queue filter. Resolve it in this
+order:
+
+1. `$ARGUMENTS` `assignee=<login>`
+2. `.lisa.config.local.json` `intake.assignee`
+3. empty default
+
+When the resolved assignee is empty, scan the shared ready queue exactly as before. When it is
+non-empty, filter the ready-item query to issues already assigned to that login. This filter is
+selection-only: never assign or reassign issues as part of build intake.
+
+## Workflow resolution
+
+Build-queue label names are read from `.lisa.config.json` `github.labels.build.*`, 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 ".github.labels.build.${role} // empty" .lisa.config.local.json 2>/dev/null)
+  global_v=$(jq -r ".github.labels.build.${role} // empty" .lisa.config.json 2>/dev/null)
+  echo "${local_v:-${global_v:-$default}}"
+}
+
+READY=$(read_role ready "status:ready")
+CLAIMED=$(read_role claimed "status:in-progress")
+
+read_intake_assignee() {
+  local cli_value local_v
+  cli_value=$(printf '%s\n' "$ARGUMENTS" | sed -n 's/.*assignee=\([^[:space:]]*\).*/\1/p' | head -1)
+  local_v=$(jq -r '.intake.assignee // empty' .lisa.config.local.json 2>/dev/null)
+  echo "${cli_value:-${local_v:-}}"
+}
+
+ASSIGNEE=$(read_intake_assignee)
+```
+
+For env-keyed `done`, resolve the env first, then look up `done[<env>]`:
+
+1. Explicit caller arg (`target_env=staging`) wins.
+2. Otherwise, infer the env from the PR's base branch via `deploy.branches` (reverse lookup).
+3. If `done` is a **string** in config, use it directly regardless of env.
+4. If `done` is a **map** and env cannot be resolved, **fail loudly** — do not pick arbitrarily.
+
+```bash
+TARGET_ENV="${target_env:-}"
+if [ -z "$TARGET_ENV" ] && [ -n "$PR_BASE_BRANCH" ]; then
+  TARGET_ENV=$(jq -r --arg b "$PR_BASE_BRANCH" \
+    '.deploy.branches // {} | to_entries[] | select(.value == $b) | .key' \
+    .lisa.config.json 2>/dev/null | head -1)
+fi
+
+DONE_TYPE=$(jq -r '.github.labels.build.done | type' .lisa.config.json 2>/dev/null)
+if [ "$DONE_TYPE" = "string" ]; then
+  DONE=$(jq -r '.github.labels.build.done' .lisa.config.json)
+  DONE_LABELS_JSON=$(jq -c '[.github.labels.build.done]' .lisa.config.json)
+elif [ "$DONE_TYPE" = "object" ]; then
+  [ -z "$TARGET_ENV" ] && { echo "ERROR: github.labels.build.done is env-keyed but env not resolvable"; exit 1; }
+  DONE=$(jq -r --arg e "$TARGET_ENV" '.github.labels.build.done[$e] // empty' .lisa.config.json)
+  [ -z "$DONE" ] && { echo "ERROR: github.labels.build.done has no entry for env '$TARGET_ENV'"; exit 1; }
+  DONE_LABELS_JSON=$(jq -c '[.github.labels.build.done[]]' .lisa.config.json)
+else
+  case "$TARGET_ENV" in
+    dev) DONE="status:on-dev" ;;
+    staging) DONE="status:on-stg" ;;
+    production) DONE="status:done" ;;
+    *) echo "ERROR: cannot resolve done label without env"; exit 1 ;;
+  esac
+  DONE_LABELS_JSON=$(jq -cn --arg d "$DONE" '[$d]')
+fi
+```
+
+In prose below, the role names refer to the resolved labels: e.g. "the `ready` label" means whatever `github.labels.build.ready` resolves to (default: `status:ready`).
+
+## Confirmation policy
+
+Do NOT ask the caller whether to proceed. Once invoked with a repo, run the cycle to completion — claim and dispatch the first eligible issue through `lisa-github-agent`, relabel a successful build to `$DONE`, write the summary, and exit. The caller (a human or a cron) has already authorized the run by invoking the skill; re-prompting defeats the purpose of a background queue.
+
+Specifically forbidden:
+
+- Previewing projected scope (issue count, projected PR count, build duration) and asking whether to continue.
+- Offering A/B/C-style choices like "proceed / skip a few / dry-run only".
+- Pausing because the queue is large, issues look complex, or issues are likely to be `Blocked` by `lisa-github-agent`'s pre-flight gate. Pre-flight `Blocked` is a valid terminal state of the per-issue lifecycle, not a failure mode.
+- Pausing because the build flow looks expensive.
+
+The only legitimate reasons to stop early:
+
+- Missing repo or required configuration. Surface the missing value and exit.
+- Label namespace not adopted (no issue carries any of `$READY` / `$CLAIMED` / `$DONE`). Surface a label-convention error and exit (this is setup, not a normal idle cycle — see "Adoption" at the bottom).
+- Empty ready set. Exit cleanly with `"No GitHub issues labeled $READY in <org>/<repo>. Nothing to do."`
+
+## Lifecycle assumed
+
+The GitHub Issues build lifecycle uses **labels** (we deliberately do NOT key off open/closed alone — closed issues aren't always the right post-build state):
+
+```text
+ready → claimed → done(env-keyed)
+(human)  (us claim)  (us done; PR ready)
+```
+
+(Defaults: `status:ready` / `status:in-progress` / `status:on-dev`/`status:on-stg`/`status:done`.)
+
+This skill ONLY transitions:
+
+- `$READY` → `$CLAIMED` (claim)
+- `$CLAIMED` → `$DONE` (build complete, PR ready)
+
+A "transition" means: remove the old role label and add the new one, in two `gh issue edit` calls (`--remove-label` + `--add-label`) or one combined call. The skill MUST verify exactly one build-lifecycle label (from the resolved `$READY`/`$CLAIMED`/`$DONE` set) is present after the update — having two simultaneously breaks idempotency.
+
+**Pre-flight check**: at the start of each cycle, confirm at least one of the resolved role labels (`$READY`, `$CLAIMED`, or any `$DONE` value) exists on the repo via `gh label list --repo <org>/<repo> --json name`. If none exist, the convention has not been adopted — surface the label-convention error and exit.
+
+## Phases
+
+### Phase 1 — Resolve the repo
+
+1. Parse `$ARGUMENTS`:
+   - `org/repo` token → use as-is.
+   - GitHub URL → extract `org` and `repo`.
+   - Literal `github` → resolve from `.lisa.config.json` (`github.org`, `github.repo`); error if not set.
+2. Confirm `gh auth status` succeeds.
+3. Confirm the repo is reachable: `gh repo view <org>/<repo> --json name --jq '.name'`.
+
+### Phase 2 — Find ready issues
+
+```bash
+if [ -n "$ASSIGNEE" ]; then
+  gh issue list --repo <org>/<repo> --label "$READY" --assignee "$ASSIGNEE" --state open \
+    --json number,title,labels,assignees,milestone,createdAt --limit 100
+else
+  gh issue list --repo <org>/<repo> --label "$READY" --state open \
+    --json number,title,labels,assignees,milestone,createdAt --limit 100
+fi
+```
+
+If empty, run a secondary check to distinguish a genuinely empty queue from an unconfigured repo:
+
+```bash
+gh label list --repo <org>/<repo> --json name \
+  | jq -r --arg r "$READY" --arg c "$CLAIMED" --argjson d "$DONE_LABELS_JSON" \
+      '[.[] | .name | select(. == $r or . == $c or (. as $n | $d | index($n)))] | length'
+```
+
+If none of the configured role labels exist on the repo → label convention not adopted, surface a setup error and exit. If the role labels exist but none are `$READY` on any open issue matching the resolved assignee filter (or any open issue when the filter is empty) → genuinely empty queue, exit cleanly with `"No GitHub issues labeled $READY. Nothing to do."`
+
+### Phase 3 — Process the first eligible ready issue
+
+#### 3a.0 Repo-scope gate (claim only current-repo issues)
+
+GitHub Issues live in one repo by definition, so the scanned repo's issues are usually inherently current-repo. But a planning/umbrella repo's issues can target sibling repos, so this skill still claims only issues for the repo it is running in. Run this gate **before** the leaf-only gate (3a) and the claim (3b), per the `repo-scope-split` rule's "Claim-time repo scoping" section (cite it by slug; do not restate its decision table).
+
+1. **Resolve the current repo** per `config-resolution` "Repo scoping" (`.repo` → `.github.repo` → `git remote get-url origin` basename). If unresolvable, stop and report.
+2. **Cheap path first.** Prefer candidates already carrying the `repo:<current>` label. Keep the Phase 2 scan broad so unlabeled issues are still seen, determined, and stamped.
+3. **Per candidate, apply the repo-scope decision (`repo-scope-split`):**
+   - Carries `repo:<other>` → **skip** (leave it `ready` for that repo's own intake); next candidate.
+   - **Unlabeled** → determine the target repo(s) from the issue + code surfaces, then **stamp** `repo:<name>` via `gh issue edit <n> --add-label "repo:<name>"` (create the label lazily) so later cycles filter cheaply; re-apply with the now-known repo. (An issue whose work is entirely in the scanned repo is simply labeled `repo:<current>`.)
+   - **Container visibility is allowed.** A multi-repo Epic / Story / Spike may legitimately carry multiple `repo:<name>` labels for operator visibility. Do not split or claim it here; leave the repo markers intact and fall through to the leaf-only gate, which repairs the stale build-ready label instead of dispatching the container.
+   - **Multi-repo leaf → split, never claim.** Run the `repo-scope-split` work-time procedure into single-repo siblings, each created **build-ready** (`build_ready: true`) and stamped with its own `repo:<name>`; the current repo's sibling becomes a normal candidate.
+   - **Single-repo leaf for the current repo** → fall through to 3a (leaf-only gate) and 3b (claim).
+4. Continue until a claimable current-repo leaf is found (claim it; one per cycle) or the ready set is exhausted — exit cleanly with `"No ready issues for repo <current>. Nothing to do."`.
+
+#### 3a. Leaf-only claim gate (repair containers)
+
+Build intake dispatches **only independently implementable leaf work units** to the build agent. This enforces the claim-time arm of the vendor-neutral `leaf-only-lifecycle` rule: a parent/container that still carries a stale build-ready role (e.g. `status:ready` applied before this rule existed, or hand-applied to an Epic/Story) is **never dispatched** — intake moves it out of the pickup queue by replacing `$READY` with `$CLAIMED`, then posts a clear lifecycle-repair message. It is the claim-time complement to the write-time labeling in `lisa-github-write-issue` and the validate-time S15 gate in `lisa-github-validate-issue`; all three cite the same rule so the classification never drifts. **Never silently implement a container.**
+
+Run this gate **before** the leaf claim relabel, starting with the oldest/highest-priority ready candidate. Do NOT comment "Claimed" or invoke `lisa-github-agent` for an issue that fails the gate. A container repair still changes labels: remove `$READY`, add `$CLAIMED`, explain that parent/container `$CLAIMED` means rollup/build-lane progress through child/leaf work rather than direct implementation, record it, and end the cycle.
+
+**Resolve container vs. leaf — structural first, then nominal.** Per `leaf-only-lifecycle` the classification is structural: an issue is a **container** if it has **open** child work, whatever its declared type; otherwise the **type label** decides. Resolve child work using the same hierarchy `lisa-github-read-issue` uses — native sub-issues first, then body parentage (task-list checkboxes referencing other issues, `Parent: #<n>` references). Dependency links such as `Blocked by:` are not parentage; they are handled by the active dependency hold gate below.
+
+```bash
+# Native sub-issues via GraphQL (same query lisa-github-read-issue uses).
+SUBS=$(gh api graphql -f query='
+query($org:String!,$repo:String!,$number:Int!){
+  repository(owner:$org,name:$repo){
+    issue(number:$number){
+      subIssues(first: 100) {
+        nodes { number state }
+      }
+    }
+  }
+}' -F org=<org> -F repo=<repo> -F number=<number> 2>/dev/null)
+
+# Count children still OPEN — a parent whose children are all closed is no longer
+# holding open work and rolls up via lisa-github-read-issue's rollup, not here.
+OPEN_CHILDREN=$(echo "$SUBS" | jq -r '[.data.repository.issue.subIssues.nodes[]? | select(.state == "OPEN")] | length' 2>/dev/null)
+OPEN_CHILDREN=${OPEN_CHILDREN:-0}
+```
+
+If the GraphQL `subIssues` field is unavailable (older GHES), fall back to parsing the body for child references exactly as `lisa-github-read-issue` does, and treat the issue as a container if any referenced child issue is open. Note "GraphQL sub-issues unavailable" so the operator knows parentage was text-derived.
+
+Classify and act (first match wins). `type:` is read from the issue's labels (`type:Epic`, `type:Story`, `type:Spike`, `type:Bug`, `type:Task`, `type:Sub-task`, `type:Improvement`):
+
+| Condition | Class | Action |
+|---|---|---|
+| `OPEN_CHILDREN > 0` (open child work, any type) | **Container** | **Move to `$CLAIMED` as lifecycle repair — do NOT dispatch** |
+| no open children AND `type = Epic` | **Childless Epic (pure rollup container)** | **Move to `$CLAIMED` as lifecycle repair — do NOT dispatch** |
+| no open children AND `type ≠ Epic` (Bug, Task, Sub-task, Improvement, Story, Spike, or no `type:` label) | **Leaf work unit** | **Proceed to 3b claim** |
+
+The childless-parent exception promotes every childless type **except Epic** to a dispatchable leaf: a childless Story is a directly shippable increment and a childless Spike *is* the investigation unit, so neither is stranded. Only a childless **Epic** is held back — an Epic is a pure rollup container by design, and a childless one is an incomplete decomposition or a mis-applied role, moved out of the ready pickup queue for repair/rollup and never dispatched.
+
+**Lifecycle repair (default action for a flagged container).** Move the issue out of the pickup queue by removing `$READY` and adding `$CLAIMED`, post a single lifecycle-repair comment, and record the issue under "Repaired (container)" in the summary. Do NOT invoke `lisa-github-agent`. Keep the comment idempotent — skip posting if an identical `[claude-build-intake]` lifecycle-repair comment already exists on the issue, so a re-entrant cycle doesn't spam it.
+
+```bash
+gh issue edit <number> --repo <org>/<repo> --remove-label "$READY" --add-label "$CLAIMED"
+gh issue comment <number> --repo <org>/<repo> --body "[claude-build-intake] Lifecycle repair: this issue carried the build-ready role ($READY) but is a parent/container with open child work (or a childless Epic). I moved it to $CLAIMED without invoking the build agent. For parent/container issues, $CLAIMED means rollup/build-lane progress through child/leaf work; direct implementation must happen on leaf issues. Build-ready is leaf-only per leaf-only-lifecycle — move $READY onto its leaf children, or decompose/reclassify a childless Epic."
+```
+
+This gate never blocks a legitimate flat Task/Bug: those have no open children and a leaf `type:`, so they fall straight through to the claim in 3b.
+
+**Active dependency hold gate.** After the leaf-only gate passes, but still before the claim relabel, parse explicit blocker relationships from the issue body and durable Lisa relationship sections. Support these forms at minimum:
+
+- `Blocked by: #123`
+- `Blocked by: #123, #456`
+- `Blocked by: owner/repo#123`
+- `Blocked by: https://github.com/owner/repo/issues/123`
+
+Resolve local `#123` references against the candidate issue's repo. Resolve qualified refs and GitHub issue URLs against their named repo. For each blocker, read the blocker issue's status labels with `gh issue view <number> --repo <owner>/<repo> --json labels,state`.
+
+Default cleared blocker labels for GitHub build intake are:
+
+- `status:code-review`
+- `status:on-dev`
+- `status:on-stg`
+- `status:done`
+
+A blocker is active if it is open and has no cleared status label. Treat `status:ready`, `status:in-progress`, missing status labels, and inaccessible blockers as active. Closed blockers are cleared. If any blocker is active, skip the candidate without changing lifecycle labels, without posting "Claimed", and without invoking `lisa-github-agent`. Record it under "Skipped (active blockers)" in the summary and include the active blocker refs. Keep any dependency-hold comment idempotent with a `[claude-build-intake]` prefix.
+
+#### 3b. Claim
+
+```bash
+gh issue edit <number> --repo <org>/<repo> --remove-label "$READY" --add-label "$CLAIMED"
+# Assign to the authenticated user ONLY when the issue is currently unassigned (attributable claim;
+# do not pile a second assignee onto an issue that already has an owner):
+gh issue view <number> --repo <org>/<repo> --json assignees -q '.assignees | length' # → if 0:
+gh issue edit <number> --repo <org>/<repo> --add-assignee "@me"
+gh issue comment <number> --repo <org>/<repo> --body "[claude-build-intake] Claimed by Claude. Starting build."
+```
+
+This is the idempotency lock — a re-entrant cycle's `--label $READY` filter will not see this issue again.
+
+If the relabel fails (permission, race), log under "Errors" in the cycle summary and skip this issue. **Do not invoke the build flow on an issue you didn't successfully claim.**
+
+#### 3c. Return or run the build delegation
+
+After the claim succeeds, the per-issue build must run under `lisa-github-agent` (the per-issue lifecycle agent), but a teammate running this skill must not spawn that named peer itself. Claude teams are flat: only the lead can add a named teammate. Therefore:
+
+- If you are the team lead/root agent, spawn or invoke `lisa-github-agent` with the issue ref and wait for its structured result.
+- If you are a teammate, stop this skill's direct work and return a structured `delegation-request` to the lead instead of calling `Agent` with `name` or otherwise spawning `github-agent` as a named peer.
+- A private anonymous helper is allowed only when the helper is not a roster peer and the `Agent` call omits `name`; it must not replace this `github-agent` delegation.
+
+Return this payload shape to the lead:
+
+```json
+{
+  "type": "delegation-request",
+  "agent": "github-agent",
+  "workItem": "<org>/<repo>#<number>",
+  "context": {
+    "claimedLabel": "$CLAIMED",
+    "doneResolution": "Resolve $DONE from the PR base branch per this skill's Workflow resolution section"
+  },
+  "onSuccess": "Confirm the returned PR is merged, then apply Phase 3d and Phase 3d.1",
+  "onBlockedOrError": "Leave the issue where github-agent left it and record the surfaced outcome"
+}
+```
+
+`lisa-github-agent` owns:
+- Reading the full issue graph (`lisa-github-read-issue`)
+- Running its own pre-flight quality gate (`lisa-github-verify`)
+- Running issue triage (`lisa-ticket-triage`)
+- Routing to the appropriate flow (Build / Fix / Investigate / Improve based on `type:` label)
+- Posting progress comments via `lisa-github-sync`
+- Posting evidence via `lisa-github-evidence`
+
+The lead waits for `lisa-github-agent` to return, then resumes this scanner with the returned outcome:
+
+- **Success** — the build flow completed and a PR exists; evidence posted. The PR may already be **merged** or still **open** (auto-merge enabled, awaiting checks/merge). "Success" means the build work is sound — it does **not** assert the change reached an environment. The env transition in 3d gates on the PR actually being merged; an open PR does not advance the issue to a `done` env status.
+- **Blocked by github-verify pre-flight gate** — `lisa-github-agent` itself relabels the issue to `status:blocked` (or removes `$CLAIMED` and reassigns to the original author). This is correct and expected — let it stand. Record and move on.
+- **Duplicate already fixed** — `lisa-github-agent` / `lisa-ticket-triage` returned `DUPLICATE_ALREADY_FIXED` with a canonical issue reference and empirical base-branch evidence. Post the triage finding, ensure the native `duplicates <canonical>` relationship exists when GitHub exposes it (otherwise leave an explicit cross-reference comment/body link), remove `$CLAIMED`, add the terminal `$DONE` label, close the issue with `gh issue close --reason "not planned"`, and do not open a PR. If the canonical fix is merged but not yet on the production branch, the close comment must say the production error can recur until the canonical issue promotes and that recurrence is tracked by the canonical issue; do not reopen this duplicate for that recurrence.
+- **Blocked by ticket-triage ambiguities** — `lisa-github-agent` posts findings and stops. The issue stays in `$CLAIMED`. Surface to human; do not auto-relabel. Record under "Errors".
+- **Errored** — exception, missing config, etc. Leave the issue in `$CLAIMED` for human investigation. Record under "Errors".
+
+#### 3c.1 Close duplicate already fixed
+
+Run this only when the returned triage verdict is exactly `DUPLICATE_ALREADY_FIXED`.
+
+1. Verify the structured result includes a canonical issue reference, the canonical PR/commit, and empirical evidence that the canonical fix is present on the base branch. If any piece is missing, treat the outcome as Held instead of closing.
+2. Post or preserve the triage-finding comment that explains why this issue is a duplicate and names the canonical issue.
+3. Ensure a native `duplicates <canonical>` link exists when GitHub exposes issue relationships; if this installation cannot create that relationship, leave an explicit issue cross-reference comment/body link and record the limitation in the summary.
+4. Resolve terminal `$DONE` exactly as in Phase 3d. For a single-env repo, `$DONE` is terminal; for env-keyed config, only the production/final value is terminal.
+5. Replace `$CLAIMED` with `$DONE`, then close the issue as duplicate/not-planned:
+
+```bash
+gh issue edit <number> --repo <org>/<repo> --remove-label "$CLAIMED" --add-label "$DONE"
+gh issue comment <number> --repo <org>/<repo> --body "[claude-build-intake] Closed as duplicate of <canonical>. Canonical fix: <PR-or-commit>. Evidence: <base-branch-proof>."
+gh issue close <number> --repo <org>/<repo> --reason "not planned"
+```
+
+If the canonical fix is merged but not yet present on the production branch, append the production-promotion caveat to the close comment: the production error can recur until the canonical issue promotes, and recurrence is tracked by the canonical issue rather than by reopening this duplicate.
+
+This path is distinct from `BLOCKED`: ambiguity, open blockers, and duplicate-of-open findings remain held for human action and must not be auto-closed.
+
+#### 3d. Transition to $DONE (only after the PR is merged)
+
+A `done` env state (`status:on-dev`, `status:on-stg`, or the terminal value) asserts that the code has actually reached that environment. Never set it for a PR that is merely open: auto-merge can be blocked indefinitely (a required rebase / `BEHIND` branch, failing checks, an unaddressed review), and the change may never land. Relabeling an issue `status:on-stg` on an open PR makes it *claim* a deploy that never happened. Transition only after confirming the PR merged.
+
+If `lisa-github-agent` returned Success:
+
+1. **Confirm the PR merged.** Read the live state of the issue's PR — `gh pr view <pr> --json state,mergedAt,mergeStateStatus,url`:
+   - **Merged** (`state == MERGED`) → proceed to resolve and apply `$DONE` below. Where the env deploy is observable (a deploy workflow run / deployment status keyed to the merged-into branch via `deploy.branches`), confirm it did not fail before relabeling; a still-running deploy is treated like an open PR (leave in `$CLAIMED`), a failed deploy is recorded as an Error.
+   - **Open / not yet merged** → do **not** transition. The build is sound but the change has reached no environment yet. Record the issue under **"PR open — awaiting merge"** in the summary (with the PR URL and its `mergeStateStatus`), leave it in `$CLAIMED`, and stop. A later `lisa-repair-intake` cycle drives the open PR to merge — re-syncing a `BEHIND` branch so the already-enabled auto-merge can land, or surfacing a real blocker — and, once merged, applies this same env transition. Do **not** comment "Build complete" or close anything.
+   - **Closed without merging** → record an Error (the PR was abandoned unmerged); leave the issue in `$CLAIMED`.
+2. Resolve `$DONE` for this issue's PR base branch using the Workflow resolution algorithm above. If env can't be resolved and `done` is env-keyed, record an Error and skip this transition — never guess.
+3. Determine whether `$DONE` is the true terminal done value per the `leaf-only-lifecycle` rule's Terminal native closure section:
+   - If `github.labels.build.done` is a string, that string is terminal.
+   - If `github.labels.build.done` is an object, only the production/final environment value is terminal (default: `status:done`). Intermediate env values such as `status:on-dev` and `status:on-stg` are not terminal and must stay open.
+   - If the project uses a different final environment name, resolve it from the configured deployment topology; if ambiguous, record an Error and do not close.
+
+```bash
+gh issue edit <number> --repo <org>/<repo> --remove-label "$CLAIMED" --add-label "$DONE"
+gh issue comment <number> --repo <org>/<repo> --body "[claude-build-intake] Build complete. PR <URL> merged. Transitioned to $DONE."
+```
+
+If `$DONE` is terminal, immediately close the native GitHub issue:
+
+```bash
+gh issue close <number> --repo <org>/<repo> --reason completed
+```
+
+This close is idempotent: if the issue is already closed, record that native closure was already satisfied and continue. If `$DONE` is an intermediate env state, leave the issue open by design.
+
+For any non-Success outcome, do NOT transition. The issue sits in `$CLAIMED` (or wherever `lisa-github-agent` left it) — humans take it from there.
+
+#### 3d.1 Roll up the parent chain (forward rollup)
+
+Run this **only after a successful `$DONE` transition in 3d** (the leaf actually reached an env — intermediate or terminal). This is the **forward** arm of the `leaf-only-lifecycle` rule's *"rollup is evaluated whenever a child transitions"* requirement: a leaf reaching `$DONE` is exactly such a transition, so its parent's derived state may now have changed — the last open child of a Story just shipped, so the Story rolls up to `$DONE` and closes, which may in turn complete its Epic. Without this step a fully-built parent stays open until the recovery `lisa-repair-intake` cron happens to run.
+
+1. Resolve the leaf's parent using the same hierarchy `lisa-github-read-issue` uses — native sub-issue parent first (GraphQL `parent`), then body parentage (`Parent: #<n>` / `Parent Epic: #<n>`). If the leaf has no parent, skip — nothing to roll up.
+2. Walk **up the ancestor chain bottom-up**: for the immediate parent, then its parent, and so on, invoke `lisa-github-sync <org>/<repo>#<ancestor> --rollup`. That skill derives the ancestor's `status:*` from its children per `leaf-only-lifecycle`, applies it only when it differs (never `status:ready`), and performs terminal native closure (`gh issue close --reason completed`) when the derived env is the production/terminal `$DONE`. It is idempotent and safe-defaults (suggests, does not guess) when the rolled state is ambiguous.
+3. Stop walking up when an ancestor has no parent, or when `--rollup` reports no change (a higher ancestor cannot advance past an unchanged child). Record each rolled-up ancestor and its derived state in the summary.
+
+This does not re-implement the state machine — it delegates to `lisa-github-sync --rollup`, the single rollup implementation `lisa-repair-intake` also uses, so the forward and recovery paths can never drift. Children closed **outside** this flow (e.g. by external automation) are not observed here; `lisa-repair-intake` remains the recovery net for those.
+
+#### 3e. Stop
+
+Stop immediately after the first claimed, skipped, blocked, held, or errored issue. Later scheduler invocations process the remaining ready issues.
+
+### Phase 4 — Summary report
+
+```text
+## github-build-intake summary
+
+Repo: <org>/<repo>
+Cycle started: <ISO timestamp>
+Cycle completed: <ISO timestamp>
+
+Issues processed: <n>
+- $DONE (build complete, PR merged): <n>
+  - <org>/<repo>#<number> <title> → PR <URL>
+- PR open — awaiting merge (left in $CLAIMED for repair-intake): <n>
+  - <org>/<repo>#<number> <title> → PR <URL> (mergeStateStatus: <state>)
+- Repaired (container — leaf-only-lifecycle): <n>
+  - <org>/<repo>#<number> <title> — build-ready on a parent/container; moved $READY → $CLAIMED without invoking lisa-github-agent; lifecycle-repair comment posted
+- Skipped (active blockers): <n>
+  - <org>/<repo>#<number> <title> — waiting on <blocker refs>
+- Duplicate already fixed (closed as duplicate): <n>
+  - <org>/<repo>#<number> <title> — duplicate of <canonical>; no PR opened
+- Blocked (pre-flight verify failed): <n>
+  - <org>/<repo>#<number> <title> — see issue comments
+- Held (triage found ambiguities): <n>
+  - <org>/<repo>#<number> <title> — see issue comments
+- Errors: <n>
+  - <org>/<repo>#<number> <title> — <reason>
+
+Total PRs opened: <n>
+```
+
+## Idempotency & safety
+
+- **Leaf-only claim gate runs first**: Phase 3a classifies each candidate before any leaf claim; a container with open child work (or a childless Epic) is moved `$READY` → `$CLAIMED` as lifecycle repair and never dispatched. The lifecycle-repair comment is idempotent — a re-entrant cycle does not re-post it.
+- **Dependency hold runs before leaf claim**: explicit `Blocked by:` relationships are resolved after container repair is ruled out but before `$READY → $CLAIMED`; active blockers leave the leaf candidate in `$READY` and are reported as skipped, not blocked.
+- **Claim-first ordering**: `$CLAIMED` set BEFORE `lisa-github-agent` invocation for leaves; containers are also moved to `$CLAIMED` to leave the ready pickup queue, but are not dispatched.
+- **No writes outside the lifecycle**: this skill only relabels `$READY → $CLAIMED` and `$CLAIMED → $DONE`. For containers, `$READY → $CLAIMED` is a lifecycle repair, not a direct build claim. Every other label change is owned by `lisa-github-agent`.
+- **Duplicate terminal exception**: `DUPLICATE_ALREADY_FIXED` is the only triage outcome that may close a claimed item without a PR from this cycle. It must include a canonical issue reference and empirical base-branch evidence, and it closes as duplicate/not-planned rather than as completed build work.
+- **Terminal native closure**: after `$CLAIMED → $DONE`, close the GitHub issue only when `$DONE` is the true terminal done value per `leaf-only-lifecycle`; intermediate env labels stay open.
+- **One item per cycle**: per-issue exceptions are caught and recorded, then the cycle exits. The scheduler owns retrying or moving on to the next ready item.
+- **Single cycle per repo**: do not run two `lisa-github-build-intake` cycles in parallel against the same repo — concurrent claims could race. The scheduling layer is responsible for serialization.
+- **Single-label invariant**: after every transition, verify exactly one `status:*` label is present on the issue. If two are present (rare race), surface as an Error and skip — do NOT auto-resolve.
+- **Never pick an arbitrary env for `$DONE`**. If `done` is a map and env is ambiguous, fail loudly.
+
+## Configuration
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `.lisa.config.json` `github.org` | (from `$ARGUMENTS`) | GitHub org for the default queue |
+| `.lisa.config.json` `github.repo` | (from `$ARGUMENTS`) | GitHub repo for the default queue |
+| `.lisa.config.json` `github.labels.build.ready` | `status:ready` | The label that signals "human says this is buildable" |
+| `.lisa.config.json` `github.labels.build.claimed` | `status:in-progress` | The label set on pickup |
+| `.lisa.config.json` `github.labels.build.done` | env-keyed map or string | The label set after a successful build; env-aware |
+| `.lisa.config.json` `deploy.branches` | — | Reverse-lookup map for env inference from PR base branch |
+
+If the repo has not adopted the `status:*` label namespace, this skill cannot run. The remediation is to create the labels — `gh label create status:ready --color FBCA04 --description "Ready for build"` and similar — typically a one-time setup. See "Adoption" below for the full command set using the defaults; if your project overrides the role names, substitute accordingly.
+
+## Rules
+
+- **Dispatch leaves only.** Per the `leaf-only-lifecycle` rule, never dispatch a container — an issue with open child work, or a childless Epic — even if it carries the build-ready role. Move it `$READY → $CLAIMED` as lifecycle repair (Phase 3a); never silently implement a container.
+- Never relabel an issue outside the cycle's allowed transitions. The `$CLAIMED` label is the signature of cycle ownership for leaves, and the parent/container progress state for lifecycle repairs.
+- Never bypass `lisa-github-agent` to do build work directly. `lisa-github-agent` owns the per-issue lifecycle.
+- Never auto-transition past `$DONE`. Downstream labels (terminal `status:done`, etc.) are owned by QA / PM / merge automation.
+- Never close a GitHub issue at intermediate env states (`status:on-dev`, `status:on-stg`, or configured equivalents). Native close happens only at the terminal `done` value.
+- Never auto-close a `BLOCKED`, ambiguous, or duplicate-of-open issue. Auto-close is allowed only for `DUPLICATE_ALREADY_FIXED`.
+- If the issue has no Validation Journey or no sign-in credentials, `lisa-github-agent`'s pre-flight verify will catch it — **don't try to fix the issue from here**.
+- On any unexpected response from `lisa-github-agent` (status it doesn't claim, missing PR URL on success), record as Error and surface — never assume.
+- Never pick an arbitrary env for `$DONE` resolution. If `done` is a map and env is ambiguous, fail loudly.
+
+## Adoption (one-time per repo)
+
+Before this skill can run, the repo must adopt the `status:*` label namespace. Using the defaults:
+
+1. Create the labels:
+   ```bash
+   gh label create status:ready --color FBCA04 --description "Ready for build" --repo <org>/<repo>
+   gh label create status:in-progress --color 0E8A16 --description "Build in progress" --repo <org>/<repo>
+   gh label create status:on-dev --color 1D76DB --description "Built, deployed to dev" --repo <org>/<repo>
+   gh label create status:done --color 0E8A16 --description "Shipped" --repo <org>/<repo>
+   ```
+   If your project overrides any `github.labels.build.*` role name in config, substitute the actual label names you configured.
+2. Apply the `$READY` label to issues that are ready for development.
+3. Reserve `$CLAIMED`, `$DONE` for this skill — humans should not set them manually except to recover from an error.
+4. PRD-source labels (defaults: `prd-ready`, `prd-in-review`, etc.) are a SEPARATE namespace owned by `lisa-github-prd-intake`. Don't conflate.