@codyswann/lisa 2.189.7 → 2.189.9

package/plugins/lisa/skills/lisa-github-project-v2/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: lisa-github-project-v2
+description: "Shared GitHub ProjectV2 coordination utility. Every GitHub writer or linked pull request flow that needs Project membership MUST delegate through this skill instead of inlining GraphQL. Resolves the configured ProjectV2 id from `github.projects.v2`, validates namespace + access, adds Issue or Pull Request node ids to the Project, optionally updates Project field values, and returns exact failures with best-effort vs required-mode branching."
+allowed-tools: ["Bash", "Read", "Skill"]
+---
+
+# GitHub ProjectV2: $ARGUMENTS
+
+Single chokepoint for GitHub ProjectV2 coordination. Caller skills (`github-write-prd`,
+`github-write-issue`, `git-submit-pr`, later linked-PR flows, later doctor/setup checks) MUST go through
+this skill rather than duplicating `gh api graphql` calls.
+
+The utility never invents policy. It applies the config + validation contract already defined in
+`config-resolution`:
+
+- `github.projects.v2` absent → coordination is disabled; callers keep repository-local writes.
+- `required: false` → Project failures are warning-level, and the underlying issue / PR write
+  remains the durable success.
+- `required: true` → the same Project failures are blocking errors.
+
+## Invocation contract
+
+The caller passes exactly one operation plus its arguments:
+
+```text
+operation: resolve-project
+operation: add-item         content_node_id: <issue-or-pr-node-id>
+operation: ensure-item      content_node_id: <issue-or-pr-node-id>
+operation: update-fields    item_id: <project-item-id> values: [{ field: "Status", option: "In Progress" }]
+operation: add-and-update   content_node_id: <issue-or-pr-node-id> values: [{ field: "Repository", text: "frontend-v2" }]
+```
+
+Argument rules:
+
+- `content_node_id` is the opaque GraphQL node id of a real GitHub Issue or Pull Request.
+- `item_id` is the opaque Project item id returned by `add-item` / `ensure-item`.
+- `values` is optional for `update-fields` / `add-and-update`. Omit it when membership alone is
+  sufficient.
+
+Return shape:
+
+```yaml
+enabled: true | false
+required: true | false
+outcome: disabled | resolved | added | reused | updated | warning | blocked
+project_id: "<opaque-project-id>"
+item_id: "<opaque-project-item-id>"
+warnings:
+  - "<warning text>"
+error:
+  code: "<stable-code>"
+  message: "<exact gh / GraphQL failure>"
+  remediation: "<next step>"
+```
+
+`error.message` MUST preserve the exact GitHub failure text (permission error, missing project,
+field mismatch, duplicate-content response, etc.). Do not collapse failures into generic
+"Project update failed."
+
+## Workflow
+
+### Step 1 — Resolve and validate config
+
+Read config in local-overrides-first order:
+
+```bash
+read_cfg() {
+  local path="$1"
+  local lv gv
+  lv=$(jq -r "$path // empty" .lisa.config.local.json 2>/dev/null)
+  gv=$(jq -r "$path // empty" .lisa.config.json 2>/dev/null)
+  echo "${lv:-$gv}"
+}
+
+ORG=$(read_cfg '.github.org')
+REPO=$(read_cfg '.github.repo')
+OWNER_KIND=$(read_cfg '.github.projects.v2.owner.kind')
+OWNER_SLUG=$(read_cfg '.github.projects.v2.owner.slug')
+PROJECT_NUMBER=$(read_cfg '.github.projects.v2.number')
+REQUIRED=$(read_cfg '.github.projects.v2.required')
+REQUIRED=${REQUIRED:-false}
+```
+
+If the `github.projects.v2` block is absent or incomplete, return:
+
+```yaml
+enabled: false
+required: false
+outcome: disabled
+```
+
+That is a clean no-op for best-effort callers; they continue the repository-local write path.
+
+When the block is present:
+
+1. Require `github.org`, `github.repo`, `owner.kind`, `owner.slug`, and `number`.
+2. Enforce the v1 namespace rule: `owner.slug` MUST equal `github.org`.
+3. Enforce supported owner kinds only: `organization` or `user`.
+4. Confirm `gh auth status` succeeds before any GraphQL call.
+
+Namespace mismatch is never silent. It returns a configuration failure with exact remediation:
+
+```yaml
+enabled: true
+required: <required>
+outcome: warning | blocked
+error:
+  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."
+```
+
+### Step 2 — Resolve the Project id
+
+Resolve the human-facing owner + number to the opaque ProjectV2 id:
+
+```bash
+gh api graphql -f query='
+query($login:String!,$number:Int!){
+  organization(login:$login){ projectV2(number:$number){ id title number url } }
+  user(login:$login){ projectV2(number:$number){ id title number url } }
+}' -F login="$OWNER_SLUG" -F number="$PROJECT_NUMBER"
+```
+
+Pick the branch matching `owner.kind`. If the Project is missing, inaccessible, or the authenticated
+identity cannot read it, preserve the exact GraphQL failure text in `error.message`.
+
+Successful resolution returns:
+
+```yaml
+enabled: true
+required: <required>
+outcome: resolved
+project_id: "<opaque-project-id>"
+```
+
+### Step 3 — Add an Issue or Pull Request to the Project
+
+For `add-item`, `ensure-item`, or `add-and-update`, first resolve the Project id, then add the
+provided Issue / Pull Request node id:
+
+```bash
+gh api graphql -f query='
+mutation($projectId:ID!,$contentId:ID!){
+  addProjectV2ItemById(input:{projectId:$projectId contentId:$contentId}){
+    item { id }
+  }
+}' -F projectId="$PROJECT_ID" -F contentId="$CONTENT_NODE_ID"
+```
+
+Behavior:
+
+- `add-item` expects the membership write to succeed and returns `outcome: added`.
+- `ensure-item` is idempotent. If GitHub reports the content is already in the Project, return
+  `outcome: reused` and surface the existing membership as a success, not a failure.
+- `add-and-update` adds first, then continues into Step 4.
+
+When GitHub returns a duplicate-membership or already-present response, `ensure-item` MUST branch
+idempotently rather than rethrowing.
+
+### Step 4 — Optionally update Project fields
+
+If `values` are provided, apply them in order to the Project item returned from Step 3. Support the
+common field types callers need first:
+
+- single-select option by field name + option name
+- text field by field name + text value
+- iteration field by field name + iteration title
+- date field by field name + ISO date
+
+The utility resolves the Project's fields first, then performs the correct GraphQL mutation for the
+typed value. Missing field names or option names are exact failures; never silently skip them.
+
+Example shape:
+
+```text
+operation: add-and-update
+content_node_id: <node-id>
+values:
+  - { field: "Status", option: "In Progress" }
+  - { field: "Repository", text: "lisa" }
+```
+
+Successful field updates return `outcome: updated` with both `project_id` and `item_id`.
+
+### Step 5 — Required vs best-effort branching
+
+Every failure after config detection branches on `required`:
+
+- **`required: false`** → return `outcome: warning`, preserve the exact error, and let the caller
+  keep the underlying issue / PR write as the durable success.
+- **`required: true`** → return `outcome: blocked` with the same exact error, causing the caller to
+  fail the write before claiming Project coordination succeeded.
+
+This means the exact same GitHub failure can surface in two different severities without changing
+its message:
+
+```yaml
+enabled: true
+required: false
+outcome: warning
+error:
+  code: project_access_denied
+  message: "Resource not accessible by integration"
+  remediation: "Grant the token Project read/write access or disable github.projects.v2."
+```
+
+```yaml
+enabled: true
+required: true
+outcome: blocked
+error:
+  code: project_access_denied
+  message: "Resource not accessible by integration"
+  remediation: "Grant the token Project read/write access or disable github.projects.v2."
+```
+
+## Rules
+
+- Never create draft issues here. This utility coordinates real Issues / Pull Requests only.
+- Never replace repository-local lifecycle truth with Project fields. Project membership is a
+  coordination view layered on top.
+- Never hide the original GitHub failure text.
+- Never treat duplicate membership as an error for `ensure-item`.
+- Never mutate issue / PR labels, comments, or body from this skill. Writers own those surfaces.
+- All GitHub ProjectV2 membership and field writes go through this skill so future GraphQL changes
+  are made in one place.

package/plugins/lisa/skills/lisa-github-project-v2/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Github Project V2"
+short_description: "Shared GitHub ProjectV2 coordination utility"
+default_prompt:
+  - "Use $lisa-github-project-v2: Shared GitHub ProjectV2 coordination utility."

package/plugins/lisa/skills/lisa-github-read-issue/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: lisa-github-read-issue
+description: "Fetches the full scope of a GitHub Issue — metadata, body sections, all comments, native sub-issue parent and children, linked PRs, related issues parsed from `Blocks/Blocked by/Relates to/Duplicates/Cloned from` lines, and any cross-repo references. Produces a consolidated context bundle that downstream agents consume so they never act on an issue in isolation. The GitHub counterpart of lisa-jira-read-ticket."
+allowed-tools: ["Bash", "Skill"]
+---
+
+# Read GitHub Issue: $ARGUMENTS
+
+Fetch the full scope of the issue AND its related graph. Downstream agents must never act on an issue in isolation — always call this skill first so they see blockers, sibling sub-issues, linked PRs, and historical comments.
+
+This skill is the GitHub counterpart of `lisa-jira-read-ticket`. The output bundle structure mirrors the JIRA bundle so vendor-neutral consumers can parse either with minimal branching.
+
+Repository name for scoped comments and logs: `basename $(git rev-parse --show-toplevel)`.
+
+## Phase 1 — Resolve Context
+
+1. Confirm `gh auth status` succeeds.
+2. Parse `$ARGUMENTS`. Accept either:
+   - `<org>/<repo>#<number>` token, OR
+   - `https://github.com/<org>/<repo>/issues/<number>` URL.
+
+   If `$ARGUMENTS` is just `#<number>` or `<number>`, resolve `<org>/<repo>` from `.lisa.config.json` (`github.org` / `github.repo`).
+3. If the input doesn't parse cleanly, stop and report. Do NOT guess.
+
+## Phase 2 — Fetch Primary Issue
+
+```bash
+gh issue view <number> --repo <org>/<repo> --json number,title,body,state,stateReason,author,assignees,labels,milestone,createdAt,updatedAt,closedAt,url,comments,reactionGroups,projectItems
+```
+
+Extract and preserve:
+
+### Metadata
+
+- `number`, `title`, `state` (open/closed), `stateReason` (completed/not_planned/reopened/null)
+- `author` (immutable original reporter), `assignees`
+- All labels — partition by namespace: `type:<...>` (issue type), `status:<...>` (workflow status), `priority:<...>`, `component:<...>`, `points:<...>`, `fix-version:<...>`, `claude-triaged-<repo>`, plus any free-form labels
+- `milestone` (name + url)
+- `createdAt`, `updatedAt`, `closedAt`
+- `url` (canonical issue URL)
+
+### Body — parse markdown sections
+
+Walk the markdown body and capture each top-level `## ` section by name. Standard sections (per `lisa-github-write-issue` Phase 3):
+
+- `Context / Business Value`
+- `Technical Approach`
+- `Acceptance Criteria` (preserve the Gherkin code-fence verbatim)
+- `Out of Scope`
+- `Target Backend Environment`
+- `Sign-in Required`
+- `Repository`
+- `Source Artifacts`
+- `Source Precedence`
+- `Links`
+- `Relationship Search`
+- `Validation Journey` (preserve verbatim — pass through to verifier agents)
+- `Open Questions`
+- `Current Product`
+
+Any other `##` section: capture under `extra_sections` so callers can see PRDs that adopt non-standard sections.
+
+### Comments
+
+Fetch ALL comments. Do not truncate. The `comments` field from `gh issue view --json comments` includes author, body, createdAt for each. Flag comments that contain:
+- Credentials, reproduction steps
+- Status updates from stakeholders
+- Decisions
+- Triage headers like `[<repo>]`
+
+If pagination matters (issues with hundreds of comments), use `gh api repos/<org>/<repo>/issues/<number>/comments --paginate` to get the full set.
+
+## Phase 3 — Fetch Sub-issue Graph (Parent + Children)
+
+GitHub native sub-issues are exposed via GraphQL:
+
+```graphql
+query($org:String!,$repo:String!,$number:Int!){
+  repository(owner:$org,name:$repo){
+    issue(number:$number){
+      id
+      parent { number title state url repository { nameWithOwner } }
+      subIssues(first: 100) {
+        nodes {
+          number title state url
+          repository { nameWithOwner }
+          labels(first: 50) { nodes { name } }
+          assignees(first: 5) { nodes { login } }
+        }
+      }
+    }
+  }
+}
+```
+
+```bash
+gh api graphql -f query='<above>' -F org=<org> -F repo=<repo> -F number=<number>
+```
+
+Capture:
+- **Parent sub-issue**: number, title, state, url, repo.
+- **Child sub-issues**: list with number, title, state, url, repo, labels (especially `type:` and `status:`), assignees.
+
+If the GraphQL `parent` / `subIssues` fields aren't available (older GHES), fall back to parsing `Parent: #<n>` text in the body and recording sub-issue text references — note "GraphQL sub-issues unavailable" in the bundle so callers know parent-link is text-based.
+
+## Phase 4 — Parse Issue Links from Body
+
+The body's `## Links` section encodes typed relationships. Parse:
+
+| Pattern (case-insensitive) | Link type |
+|----------------------------|-----------|
+| `Blocks #<n>` or `Blocks <org>/<repo>#<n>` | `blocks` |
+| `Blocked by #<n>` or `Blocked by <org>/<repo>#<n>` | `is blocked by` |
+| `Relates to #<n>` or `Relates to <org>/<repo>#<n>` | `relates to` |
+| `Duplicates #<n>` or `Duplicates <org>/<repo>#<n>` | `duplicates` |
+| `Cloned from #<n>` or `Cloned from <org>/<repo>#<n>` | `clones` |
+| `Resolves #<n>` or `Closes #<n>` or `Fixes #<n>` (PR refs) | remote-link to PR |
+
+For each parsed reference, fetch the linked issue/PR:
+
+```bash
+gh issue view <link-number> --repo <link-org>/<link-repo> --json number,title,state,labels,assignees,url
+gh pr view <link-number> --repo <link-org>/<link-repo> --json number,title,state,reviewDecision,merged,mergedAt,url,reviewRequests,reviews,comments
+```
+
+For each linked **issue**, capture: number, title, state, type (from labels), status (from labels), assignees, url.
+
+For each linked **PR**, capture: number, title, state, mergedAt, reviewDecision, unresolved review comments, url.
+
+**Special handling for `is blocked by`:** include the linked issue's PR refs (parse `Resolves` lines in its body) and fetch each PR's state, so the agent knows whether the blocker is actually shipped.
+
+## Phase 5 — Fetch Sibling Sub-issues (Epic Context)
+
+If the primary issue has a parent sub-issue (i.e., is a Story / Task / Sub-task / Improvement under an Epic):
+
+1. Fetch the parent Epic in full via Phase 2 logic — full body, all comments, Validation Journey if present.
+2. Fetch the parent Epic's other sub-issues (siblings) via the same GraphQL `subIssues` query against the parent. Filter out the primary issue itself.
+3. For each sibling, capture: number, title, type label, status label, assignee, url. Read the first paragraph of each sibling's body for context. If a sibling has `status:in-progress` with an assignee different from the primary issue's assignee, **flag prominently** so the caller can avoid duplicate work.
+
+If the primary issue IS an Epic, capture all children via Phase 3's `subIssues` traversal (already done).
+
+## Phase 6 — Fetch Linked PRs (Native `Resolves` / Cross-references)
+
+GitHub's native `closingIssuesReferences` and timeline give the canonical PR↔Issue relationship:
+
+```bash
+gh api graphql -f query='query($org:String!,$repo:String!,$number:Int!){repository(owner:$org,name:$repo){issue(number:$number){closedByPullRequestsReferences(first:50){nodes{number title state merged mergedAt url repository{nameWithOwner}}}timelineItems(first:100,itemTypes:[CROSS_REFERENCED_EVENT]){nodes{...on CrossReferencedEvent{source{...on PullRequest{number title state url repository{nameWithOwner}}}}}}}}}' -F org=<org> -F repo=<repo> -F number=<number>
+```
+
+Capture: PR number, title, state, mergedAt, repo, url. Dedupe with PRs found in Phase 4.
+
+For each PR, fetch unresolved review comments via `gh pr view <num> --repo <org>/<repo> --json reviews,reviewThreads`.
+
+## Phase 7 — Assemble Context Bundle
+
+Produce a single structured output that the caller can pass verbatim to downstream agents. Use this format:
+
+```text
+# Issue Context: <org>/<repo>#<number>
+
+## Primary Issue
+- Ref: <org>/<repo>#<number>
+- URL: <url>
+- Type: <type from `type:` label>
+- Status: <status from `status:` label>
+- State: <open|closed> (<stateReason>)
+- Priority: <priority from `priority:` label>
+- Author: <login>
+- Assignees: <list>
+- Parent: <parent-ref> — <parent-title>  (or "None")
+- Milestone: <name>  (or "None")
+- Labels: <comma-separated raw labels>
+- Components: <list from `component:` labels>
+- Story points: <n from `points:` label>  (or "None")
+- Fix version: <from `fix-version:` label or milestone>
+- Created: <ISO> | Updated: <ISO> | Closed: <ISO or "—">
+
+### Body sections
+#### Context / Business Value
+<verbatim>
+
+#### Technical Approach
+<verbatim>
+
+#### Acceptance Criteria
+<verbatim, including the gherkin fence>
+
+#### Validation Journey
+<verbatim or "None">
+
+#### Out of Scope
+<verbatim>
+
+#### Source Artifacts / Source Precedence / Links / Relationship Search / Repository / Sign-in Required / Target Backend Environment / Open Questions / Current Product
+<each verbatim, omit those not present>
+
+### Comments (<count>)
+<chronological comments with author + ISO timestamp + body. Flagged items called out.>
+
+## Sub-issue graph
+### Parent
+<parent block: ref, title, state, url, type label> (or "None — this is an Epic / unparented")
+
+### Sub-issues (children, <count>)
+- <ref> — <type> — <status> — <state> — <title>
+  - <one-paragraph body summary>
+  - <FLAG: in progress by other assignee> if applicable
+
+## Linked Issues (parsed from body `## Links`)
+### Blocks (<count>)
+<per-issue block>
+
+### Is Blocked By (<count>)
+<per-issue block; include shipped/not-shipped state of any linked PRs>
+
+### Relates To (<count>)
+<per-issue block>
+
+### Duplicates / Clones
+<per-issue block>
+
+## Linked Pull Requests
+### Native (closedByPullRequestsReferences + cross-references)
+- <pr-ref> — <state> — <title> — <reviewDecision>
+  <body summary + unresolved review comments>
+
+### Body-referenced (`Resolves #<n>`)
+<per-PR block>
+
+## Sibling Sub-issues (other children of the same parent, <count>)
+- <ref> — <type> — <status> — <assignee> — <title>  **[FLAG: in progress by other assignee]**
+
+## Summary for Downstream
+- Full graph fetched: <issue-count>
+- Blockers still open: <list>
+- Related in-flight work: <list>
+- Relevant PRs: <list with state>
+```
+
+## Rules
+
+- Never summarize or truncate the primary issue's body or Validation Journey section.
+- Never skip a link type, even if it seems unrelated — the agent downstream decides relevance.
+- If a linked issue / PR returns an access error (private repo, deleted, etc.), capture the error and continue. Do not abort the read.
+- Flag in-flight sibling work prominently so the caller can avoid duplicate implementation.
+- If the issue has no parent sub-issue, state this explicitly — do not silently skip Phase 5.
+- Output is pure context. This skill never modifies the issue.
+- The body parser must be tolerant of small format variations (different `##` casings, missing optional sections) but strict enough that downstream skills can rely on the named sections being present when they exist.

package/plugins/lisa/skills/lisa-github-read-issue/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Github Read Issue"
+short_description: "Fetches the full scope of a GitHub Issue — metadata, body sections, all comments, native sub-issue parent and children, linked PRs, related…"
+default_prompt:
+  - "Use $lisa-github-read-issue: Fetches the full scope of a GitHub Issue — metadata, body sections, all comments, native sub-issue parent and children, linked PRs, related…."

package/plugins/lisa/skills/lisa-github-sync/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: lisa-github-sync
+description: "Syncs plan progress to a linked GitHub Issue. Posts plan contents, progress updates, branch links, and PR links at key milestones. Use this skill throughout the plan lifecycle to keep issues in sync. The GitHub counterpart of lisa-jira-sync."
+allowed-tools: ["Bash", "Read", "Glob", "Grep"]
+---
+
+# GitHub Issue Sync
+
+Sync current plan progress to a GitHub Issue: `$ARGUMENTS`
+
+If no argument is provided, search for an issue ref (`org/repo#<number>` or `https://github.com/<org>/<repo>/issues/<n>` URL) in the active plan file (most recently modified `.md` in `plans/`).
+
+Optional arguments include `pr_url=<url>` for the live pull request and `merge_sha=<sha>` once merged.
+
+## Workflow
+
+### Step 1: Identify Issue and Context
+
+1. **Parse issue ref** from `$ARGUMENTS` or extract from the active plan file.
+2. **Fetch current issue state**:
+
+   ```bash
+   gh issue view <number> --repo <org>/<repo> --json number,title,state,labels,milestone,assignees,comments,url
+   ```
+
+3. **Determine current milestone** by checking:
+   - Does a plan file exist? → Plan created
+   - Is there a working branch? → Implementation started
+   - Are tasks in progress? → Active implementation
+   - Is there an open PR? → PR ready for review
+   - Is the PR merged? → Complete
+
+### Step 2: Gather Update Content
+
+| Milestone | Content to post |
+|-----------|-----------------|
+| **Plan created** | Plan summary, branch name, link to PR (if draft exists) |
+| **Implementation in progress** | Task completion summary (X of Y tasks done), any blockers |
+| **PR ready** | PR link, summary of changes, test results |
+| **PR merged** | Final summary, suggest moving issue to `status:done` |
+
+### Step 3: Post Update
+
+1. **Idempotency check** — read the issue's recent comments. If the most recent comment with the prefix `[claude-sync] <milestone>` matches the current milestone AND the body content is unchanged, skip the post (no duplicate).
+2. **Add the comment**:
+
+   ```bash
+   gh issue comment <number> --repo <org>/<repo> --body-file /tmp/sync-comment.md
+   ```
+
+   The body must start with `[claude-sync] <milestone>` so the next sync run can dedupe.
+
+3. **Report** to the user what was synced.
+
+### Step 3b: Ensure PR Backlink
+
+When `$ARGUMENTS` includes `pr_url=<url>` for `PR ready` or `PR merged`, ensure the GitHub Issue has a durable ticket -> PR link:
+
+1. Prefer GitHub's native development link by making sure the PR body contains `Refs #<n>` / `Closes #<n>` (or the fully qualified cross-repo form) and verify with `gh issue view <number> --json timelineItems` or an equivalent GitHub read that exposes the linked PR.
+2. If native linkage cannot be verified, post or update a single managed issue comment starting with `[lisa-pr-link]`. Include the PR URL, milestone (`pr-ready` or `pr-merged`), and merge SHA when available.
+3. Keep the fallback idempotent: search existing comments for `[lisa-pr-link]` and the PR URL; update/replace that managed comment where the provider allows updates, otherwise skip when the current body already matches. Do not append duplicate backlink comments on reruns.
+
+This fallback is required even though GitHub usually links PRs natively from PR body keywords; the issue must show the PR from at least one ticket-side surface.
+
+### Step 4: Suggest Status Transition
+
+Based on the milestone, suggest (but do NOT automatically perform) a label transition:
+
+| Milestone | Suggested label |
+|-----------|-----------------|
+| Plan created | `status:in-progress` |
+| PR ready | configured `done` label (`status:done` in this repo) |
+| PR merged | no additional build-label transition |
+
+The actual `status:in-progress` flip is owned by `lisa-github-build-intake` (claim) and `lisa-github-agent`. The configured `done` flip is owned by the build-intake owner after a successful build and evidence post. This skill never relabels.
+
+### Step 5: Parent Status Rollup (`--rollup`)
+
+When invoked with `--rollup`, this skill **derives a parent/container issue's `status:*` label from the roll-up of its child sub-issues** instead of posting a milestone update on a leaf. This implements the GitHub sub-issue-completion arm of the **Parent status rollup (the state machine)** section of the `leaf-only-lifecycle` rule — cite that rule, do not restate the policy. It is the sync-side complement to the write-time labeling (`lisa-github-write-issue`), the validate-time S15 gate (`lisa-github-validate-issue`), and the claim-time gate (`lisa-github-build-intake`); all four cite the same rule so the classification never drifts.
+
+**Resolve the child set the same way `lisa-github-read-issue` does** — native sub-issues via GraphQL, each with its `status:*` label and open/closed state:
+
+```bash
+gh api graphql -f query='
+  query($owner:String!,$repo:String!,$number:Int!){
+    repository(owner:$owner,name:$repo){
+      issue(number:$number){
+        number title state
+        subIssues(first:100){ nodes { number state labels(first:20){ nodes { name } } } }
+      }
+    }
+  }' -F owner=<org> -F repo=<repo> -F number=<parent-number>
+```
+
+If the `subIssues` field is unavailable (older GHES), fall back to body parentage exactly as `lisa-github-read-issue` does. If the issue has **no** children it is a leaf, not a parent — rollup is N/A; behave as a normal milestone sync.
+
+**Evaluate the required children over the env ladder `in-progress < dev < staging < production` (the ordered keys of the GitHub env-keyed `done` map, e.g. `status:on-dev < status:on-stg < status:done`) and take the first match** (canonical roles from `config-resolution`; the GitHub label map is `status:blocked`, `status:in-progress`, env-keyed `done`):
+
+| If among the required child leaves… | Derived parent role | GitHub label |
+|---|---|---|
+| any child carries `status:blocked` (or is otherwise blocked) | `blocked` | `status:blocked` |
+| else **every** required child has shipped to some env (each at a `done`-map label, e.g. `status:on-dev`/`status:on-stg`/`status:done`) | `done[min-env]` | the **least-advanced** env label among them (all `status:on-stg` → `status:on-stg`; mixed dev+staging → `status:on-dev`; all production → `status:done`) |
+| else any child has **started** (`status:in-progress`, or shipped to an env while a sibling has not) | `claimed` | `status:in-progress` |
+| else (children exist, none started) | — | unchanged — parent keeps its non-ready container label |
+
+- **Blocked dominates** — a single blocked child surfaces `status:blocked` on the parent even while siblings progress, so a human sees the parent needs attention.
+- **Least-advanced env wins** — the parent reaches an env only when every required child has reached at least that env; it never sits ahead of its laggard child. Native closure (`gh issue close --reason completed`) fires only when the resolved env is the production `status:done`, never at `status:on-dev`/`status:on-stg`.
+- **"Required" children only** — a child labelled won't-do / optional does not hold the parent open; only leaves that must ship count toward the env-rollup check.
+- **Recursive** — a parent reaches an env only when its children have all reached at least that env; an Epic reaches it only when its Stories have themselves rolled up to it. Evaluate bottom-up.
+- **Never set the parent to `status:ready`** — `ready` is leaf-only (the human "claim this" signal). Rollup only moves the parent between non-ready container labels.
+
+**Single-environment collapse (this repo).** `.lisa.config.json` `deploy.branches` declares only `production: main`, so the env-keyed `done` resolves to the single label `status:done` — there is no `status:on-dev` / `status:on-stg` and **no dev → staging → prod promotion chain**. Resolve the env rungs via the env-keyed `done` logic in `config-resolution`, but in the single-environment case the only rung is production and it collapses to the one `status:done` value; the rollup never attempts to resolve a dev or staging `done`. Projects that DO have multiple environments keep the env-keyed map and roll the parent up to whichever `done` (including intermediate `status:on-dev`/`status:on-stg`) its leaves have collectively reached.
+
+**Apply the derived label** (only when it differs from the parent's current `status:*`): remove the parent's existing `status:*` label and add the derived one, keeping exactly one `status:*` label so the build-queue invariant holds. Post an idempotent `[claude-sync] rollup` comment naming the derived state and the child tally (e.g. `3/4 leaves terminal, 1 blocked → status:blocked`); skip the comment if an identical one is already the most recent rollup comment.
+
+```bash
+gh issue edit <parent-number> --repo <org>/<repo> \
+  --remove-label "<current status:*>" --add-label "<derived status:*>"
+```
+
+**Safe default.** If rollup cannot be applied automatically (e.g. ambiguous required-set, GraphQL hierarchy unavailable, or a derived terminal that the env logic cannot resolve), this skill does **not** guess — it posts the derived suggestion as a comment and leaves the parent's label untouched. No unsafe transition is ever made.
+
+## Important Notes
+
+- **Never auto-transition labels** — always suggest and let the user / pipeline confirm. The one exception is the explicit `--rollup` parent derivation (Step 5), which moves a *parent's* `status:*` label as the `leaf-only-lifecycle` rule mandates — never a leaf's, and never to `status:ready`.
+- **Idempotent updates** — the `[claude-sync] <milestone>` prefix on the most-recent comment is the dedupe key; the rollup path uses `[claude-sync] rollup`.
+- **Comment format** — use GitHub-flavored markdown (`##` headings, fenced code blocks). The same template is used for the JIRA path (rendered as wiki markup there); keep the markdown source canonical.
+- **Rollup cites the rule by slug** — parent state derivation follows the `leaf-only-lifecycle` rule's state machine; this skill does not restate the policy.
+
+## Execution
+
+Sync the issue now.

package/plugins/lisa/skills/lisa-github-sync/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Github Sync"
+short_description: "Syncs plan progress to a linked GitHub Issue"
+default_prompt:
+  - "Use $lisa-github-sync: Syncs plan progress to a linked GitHub Issue."