github-agent 1.2.0__tar.gz → 1.4.1__tar.gz

{github_agent-1.2.0 → github_agent-1.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: github-agent
-Version: 1.2.0
+Version: 1.4.1
 Summary: GitHub Agent for MCP
 Author-email: Audel Rouhi <knucklessg1@gmail.com>
 License: MIT
@@ -48,7 +48,7 @@ Dynamic: license-file
 ![PyPI - Wheel](https://img.shields.io/pypi/wheel/github-agent)
 ![PyPI - Implementation](https://img.shields.io/pypi/implementation/github-agent)
 
-*Version: 1.2.0*
+*Version: 1.4.1*
 
 > **Documentation** — Installation, deployment, and usage across the MCP, API, and
 > CLI interfaces, including the integrated A2A agent server, are maintained in the
@@ -101,6 +101,7 @@ _Auto-generated from the live MCP server — do not edit by hand._
 | `github_dependabot` | `DEPENDABOTTOOL` | Review and manage GitHub Dependabot vulnerability alerts. |
 | `github_discover_graphql_schema` | `GRAPHQLTOOL` | Discover the live GitHub GraphQL schema (types, fields, and attributes) in real-time. |
 | `github_graphql` | `GRAPHQLTOOL` | Execute raw GraphQL queries and mutations natively on GitHub. |
+| `github_ingest_pipelines` | `INGESTTOOL` | Natively ingest GitHub Actions workflow runs into epistemic-graph. |
 | `github_ingest_repos` | `INGESTTOOL` | Natively ingest GitHub repositories into epistemic-graph as typed :Repository nodes. |
 | `github_issues` | `ISSUETOOL` | Manage GitHub issues. |
 | `github_orgs` | `ORGTOOL` | Manage GitHub organizations. |
@@ -195,7 +196,7 @@ _Auto-generated from the live MCP server — do not edit by hand._
 
 </details>
 
-_15 action-routed tool(s) (default) · 76 verbose 1:1 tool(s). Each is enabled unless its `<DOMAIN>TOOL` toggle is set false; `MCP_TOOL_MODE` selects the surface (`condensed` default · `verbose` 1:1 · `both`). Auto-generated — do not edit._
+_16 action-routed tool(s) (default) · 76 verbose 1:1 tool(s). Each is enabled unless its `<DOMAIN>TOOL` toggle is set false; `MCP_TOOL_MODE` selects the surface (`condensed` default · `verbose` 1:1 · `both`). Auto-generated — do not edit._
 <!-- MCP-TOOLS-TABLE:END -->
 
 Detailed tool schemas, parameter shapes, and validation constraints are preserved in [docs/mcp.md](docs/mcp.md).

{github_agent-1.2.0 → github_agent-1.4.1}/README.md

@@ -20,7 +20,7 @@
 ![PyPI - Wheel](https://img.shields.io/pypi/wheel/github-agent)
 ![PyPI - Implementation](https://img.shields.io/pypi/implementation/github-agent)
 
-*Version: 1.2.0*
+*Version: 1.4.1*
 
 > **Documentation** — Installation, deployment, and usage across the MCP, API, and
 > CLI interfaces, including the integrated A2A agent server, are maintained in the
@@ -73,6 +73,7 @@ _Auto-generated from the live MCP server — do not edit by hand._
 | `github_dependabot` | `DEPENDABOTTOOL` | Review and manage GitHub Dependabot vulnerability alerts. |
 | `github_discover_graphql_schema` | `GRAPHQLTOOL` | Discover the live GitHub GraphQL schema (types, fields, and attributes) in real-time. |
 | `github_graphql` | `GRAPHQLTOOL` | Execute raw GraphQL queries and mutations natively on GitHub. |
+| `github_ingest_pipelines` | `INGESTTOOL` | Natively ingest GitHub Actions workflow runs into epistemic-graph. |
 | `github_ingest_repos` | `INGESTTOOL` | Natively ingest GitHub repositories into epistemic-graph as typed :Repository nodes. |
 | `github_issues` | `ISSUETOOL` | Manage GitHub issues. |
 | `github_orgs` | `ORGTOOL` | Manage GitHub organizations. |
@@ -167,7 +168,7 @@ _Auto-generated from the live MCP server — do not edit by hand._
 
 </details>
 
-_15 action-routed tool(s) (default) · 76 verbose 1:1 tool(s). Each is enabled unless its `<DOMAIN>TOOL` toggle is set false; `MCP_TOOL_MODE` selects the surface (`condensed` default · `verbose` 1:1 · `both`). Auto-generated — do not edit._
+_16 action-routed tool(s) (default) · 76 verbose 1:1 tool(s). Each is enabled unless its `<DOMAIN>TOOL` toggle is set false; `MCP_TOOL_MODE` selects the surface (`condensed` default · `verbose` 1:1 · `both`). Auto-generated — do not edit._
 <!-- MCP-TOOLS-TABLE:END -->
 
 Detailed tool schemas, parameter shapes, and validation constraints are preserved in [docs/mcp.md](docs/mcp.md).

{github_agent-1.2.0 → github_agent-1.4.1}/github_agent/agent_server.py

@@ -4,7 +4,7 @@ import os
 import sys
 import warnings
 
-__version__ = "1.2.0"
+__version__ = "1.4.1"
 
 logging.basicConfig(
     level=logging.INFO,

{github_agent-1.2.0 → github_agent-1.4.1}/github_agent/kg_ingest.py

@@ -3,7 +3,8 @@
 CONCEPT:AU-KG.ingest.enterprise-source-extractor. The github-agent connector natively
 pushes its data into the ONE epistemic-graph knowledge graph as **typed OWL nodes**
 (``:Repository``, ``:PullRequest``, ``:Issue``, ``:Release``, ``:Organization``,
-``:Person``) plus links, and release notes as **:Document** nodes for semantic search —
+``:Person``, ``:PipelineRun``, ``:CheckRun``) plus links, and release notes as
+**:Document** nodes for semantic search —
 using the lightweight engine client (``GraphComputeEngine()._client`` + ``txn``), the
 same fast client the blob ``MediaStore`` uses, NOT the heavy in-process ingestion engine.
 
@@ -355,3 +356,123 @@ def ingest_release_notes(
             }
         )
     return ingest_documents(docs, client=client, graph=graph)
+
+
+def _duration_seconds(start: Any, end: Any) -> int | None:
+    """Whole-second wall-clock duration between two ISO-8601 timestamps, or ``None``."""
+    if not start or not end:
+        return None
+    try:
+        import datetime as _dt
+
+        started = _dt.datetime.fromisoformat(str(start).replace("Z", "+00:00"))
+        ended = _dt.datetime.fromisoformat(str(end).replace("Z", "+00:00"))
+        return max(0, int((ended - started).total_seconds()))
+    except (ValueError, TypeError):
+        return None
+
+
+def ingest_pipeline_runs(
+    runs: list[dict[str, Any]],
+    *,
+    repo_full_name: str | None = None,
+    repo_node_id: str | None = None,
+    jobs_by_run: dict[int, list[dict[str, Any]]] | None = None,
+    client: Any | None = None,
+    graph: str | None = None,
+) -> dict[str, int] | None:
+    """Map GitHub Actions workflow runs (+ jobs/check-runs) → ``:PipelineRun``/``:CheckRun``.
+
+    ``runs``: raw ``WorkflowRun`` records (``client.get_workflow_runs`` /
+    ``.get_workflow_run`` ``model_dump()``). ``jobs_by_run``: optional ``{run_id:
+    [job_or_check_run, ...]}`` from ``client.get_workflow_run_jobs`` (or the Checks
+    API) — each becomes a child ``:CheckRun`` linked via ``hasJob``.
+
+    Uses the SAME ``:PipelineRun``/``:CheckRun`` classes and ``ranFor``/``hasJob``
+    edge names as gitlab-api's ingestion so GitHub Actions and GitLab CI/CD unify
+    under one CI node shape in the knowledge graph. ``ranFor`` is emitted once per
+    known target — the repo, the head commit, and (if the run lists it) the PR.
+    Stable ids: ``github:pipelinerun:<repo>:<id>`` / ``github:checkrun:<repo>:<id>``.
+    """
+    entities: list[dict[str, Any]] = []
+    relationships: list[dict[str, Any]] = []
+    jobs_by_run = jobs_by_run or {}
+    for run in runs or []:
+        run_id = run.get("id")
+        if run_id is None:
+            continue
+        repo = repo_full_name or (run.get("repository") or {}).get("full_name")
+        node_id = f"github:pipelinerun:{repo}:{run_id}"
+        run_started = run.get("run_started_at")
+        run_updated = run.get("updated_at")
+        entities.append(
+            {
+                "id": node_id,
+                "type": "PipelineRun",
+                "status": run.get("status"),
+                "conclusion": run.get("conclusion"),
+                "headSha": run.get("head_sha"),
+                "headBranch": run.get("head_branch"),
+                "event": run.get("event"),
+                "htmlUrl": _str(run.get("html_url")),
+                "runStartedAt": run_started,
+                "runUpdatedAt": run_updated,
+                "durationSeconds": _duration_seconds(run_started, run_updated),
+                "externalToolId": str(run_id),
+            }
+        )
+
+        if repo_node_id:
+            relationships.append(
+                {"source": node_id, "target": repo_node_id, "type": "ranFor"}
+            )
+
+        head_sha = run.get("head_sha")
+        if repo and head_sha:
+            commit_id = f"github:commit:{repo}:{head_sha}"
+            entities.append(
+                {
+                    "id": commit_id,
+                    "type": "Commit",
+                    "sha": head_sha,
+                    "externalToolId": head_sha,
+                }
+            )
+            relationships.append(
+                {"source": node_id, "target": commit_id, "type": "ranFor"}
+            )
+
+        for pr in run.get("pull_requests") or []:
+            pr_id = pr.get("id")
+            if pr_id is None:
+                continue
+            relationships.append(
+                {
+                    "source": node_id,
+                    "target": f"github:pullrequest:{pr_id}",
+                    "type": "ranFor",
+                }
+            )
+
+        for job in jobs_by_run.get(run_id) or []:
+            job_id = job.get("id")
+            if job_id is None:
+                continue
+            job_node_id = f"github:checkrun:{repo}:{job_id}"
+            entities.append(
+                {
+                    "id": job_node_id,
+                    "type": "CheckRun",
+                    "name": job.get("name"),
+                    "status": job.get("status"),
+                    "conclusion": job.get("conclusion"),
+                    "startedAt": job.get("started_at"),
+                    "completedAt": job.get("completed_at"),
+                    "htmlUrl": _str(job.get("html_url")),
+                    "externalToolId": str(job_id),
+                }
+            )
+            relationships.append(
+                {"source": node_id, "target": job_node_id, "type": "hasJob"}
+            )
+    return ingest_entities(entities, relationships, client=client, graph=graph)

{github_agent-1.2.0 → github_agent-1.4.1}/github_agent/mcp_server.py

@@ -2317,6 +2317,99 @@ def register_ingest_tools(mcp: FastMCP):
         result = ingest_repositories(records)
         return {"listed": len(records), "ingested": result}
 
+    @mcp.tool(tags={"kg"})
+    async def github_ingest_pipelines(
+        params_json: str = Field(
+            default="{}",
+            description="JSON string with required 'owner'/'repo' and optional "
+            "github_actions 'list_runs' filters (status, branch, per_page, "
+            "max_pages), plus 'include_jobs' (default true — fetch each run's "
+            "jobs as :CheckRun children) and 'repo_node_id' (the :Repository "
+            "node id to link runs to via ranFor).",
+        ),
+        client=Depends(get_client),
+        ctx: Context | None = Field(
+            default=None, description="MCP context for progress reporting"
+        ),
+    ) -> Any:
+        """Natively ingest GitHub Actions workflow runs into epistemic-graph.
+
+        Lists recent workflow runs for a repository (+ each run's jobs, unless
+        ``include_jobs=false``) via the GitHub API and pushes them as typed
+        :PipelineRun nodes (with child :CheckRun jobs linked via hasJob, and
+        ranFor links to the repo/head-commit/PR) into the knowledge graph via
+        the fast engine client. Uses the SAME :PipelineRun/:CheckRun classes as
+        gitlab-api's CI ingestion so GitHub Actions and GitLab CI/CD unify under
+        one node shape. Best-effort: returns ``{"ingested": None}`` when no
+        engine is reachable. CONCEPT:AU-KG.ingest.enterprise-source-extractor.
+        """
+        if ctx:
+            await ctx.info(
+                "Ingesting GitHub Actions pipeline runs into the knowledge graph..."
+            )
+        import json
+
+        from github_agent.kg_ingest import ingest_pipeline_runs
+
+        try:
+            kwargs = json.loads(params_json) if params_json else {}
+        except Exception as e:
+            return {"status": 400, "error": f"Invalid params_json: {e}", "data": None}
+
+        owner = kwargs.get("owner")
+        repo = kwargs.get("repo")
+        if not owner or not repo:
+            return {
+                "status": 400,
+                "error": "Missing required 'owner' or 'repo' parameter",
+                "data": None,
+            }
+
+        include_jobs = kwargs.get("include_jobs", True)
+        repo_node_id = kwargs.get("repo_node_id")
+        list_kwargs = {
+            k: v
+            for k, v in kwargs.items()
+            if k in ("owner", "repo", "status", "branch", "per_page", "max_pages")
+            and v is not None
+        }
+
+        response = await run_blocking(client.get_workflow_runs, **list_kwargs)
+        runs = [
+            run.model_dump() if hasattr(run, "model_dump") else run
+            for run in response.data
+            if run is not None
+        ]
+
+        jobs_by_run: dict[int, Any] = {}
+        if include_jobs:
+            for run in runs:
+                run_id = run.get("id")
+                if run_id is None:
+                    continue
+                try:
+                    jobs_response = await run_blocking(
+                        client.get_workflow_run_jobs,
+                        owner=owner,
+                        repo=repo,
+                        run_id=run_id,
+                    )
+                    jobs_by_run[run_id] = jobs_response.data
+                except Exception as e:
+                    logger.debug(
+                        "github_ingest_pipelines: jobs fetch failed for run %s: %s",
+                        run_id,
+                        e,
+                    )
+
+        result = ingest_pipeline_runs(
+            runs,
+            repo_full_name=f"{owner}/{repo}",
+            repo_node_id=repo_node_id,
+            jobs_by_run=jobs_by_run,
+        )
+        return {"listed": len(runs), "ingested": result}
+
 
 def register_graphql_tools(mcp: FastMCP):
     from github_agent.auth import get_graphql_client

{github_agent-1.2.0 → github_agent-1.4.1}/github_agent/ontology/github.ttl

@@ -49,6 +49,17 @@
     rdfs:label "Workflow Run" ;
     rdfs:comment "A single execution of a GitHub Actions workflow for a ref/commit (github_actions)." .
 
+:PipelineRun a owl:Class ;
+    rdfs:label "Pipeline Run" ;
+    rdfs:comment """A single CI/CD execution for a ref/commit (github_actions workflow run).
+    Shares its class name with the twin gitlab-api producer so GitHub Actions and GitLab
+    CI/CD unify under one node shape in the knowledge graph.""" .
+
+:CheckRun a owl:Class ;
+    rdfs:label "Check Run" ;
+    rdfs:comment """A single job/check within a PipelineRun (github_actions workflow-run job or
+    GitHub Checks-API check run). Shares its class name with the twin gitlab-api producer.""" .
+
 # --- links (owl:ObjectProperty) ---
 
 :belongsToRepository a owl:ObjectProperty ;
@@ -90,6 +101,20 @@
     rdfs:domain :Workflow ;
     rdfs:range :WorkflowRun .
 
+:ranFor a owl:ObjectProperty ;
+    rdfs:label "ran for" ;
+    rdfs:comment """Links a PipelineRun to what it ran for — its Repository, the Commit it
+    built, and/or the PullRequest it validated. Same predicate name as the twin gitlab-api
+    producer (Pipeline ranFor Project/Commit/MergeRequest).""" ;
+    rdfs:domain :PipelineRun .
+
+:hasJob a owl:ObjectProperty ;
+    rdfs:label "has job" ;
+    rdfs:comment """Links a PipelineRun to a CheckRun (job/check) it contains. Same predicate
+    name as the twin gitlab-api producer (Pipeline hasJob Job).""" ;
+    rdfs:domain :PipelineRun ;
+    rdfs:range :CheckRun .
+
 :documentsRelease a owl:ObjectProperty ;
     rdfs:label "documents release" ;
     rdfs:comment "Links a Release to the :Document carrying its release-notes body." ;
@@ -151,6 +176,64 @@
     rdfs:comment "Result/conclusion of a WorkflowRun (success, failure, in_progress, cancelled)." ;
     rdfs:range xsd:string .
 
+:status a owl:DatatypeProperty ;
+    rdfs:label "status" ;
+    rdfs:comment "Lifecycle status of a PipelineRun or CheckRun (queued, in_progress, completed)." ;
+    rdfs:range xsd:string .
+
+:conclusion a owl:DatatypeProperty ;
+    rdfs:label "conclusion" ;
+    rdfs:comment "Terminal result of a PipelineRun or CheckRun (success, failure, cancelled, skipped)." ;
+    rdfs:range xsd:string .
+
+:headSha a owl:DatatypeProperty ;
+    rdfs:label "head sha" ;
+    rdfs:comment "Full git commit SHA a PipelineRun ran against." ;
+    rdfs:domain :PipelineRun ;
+    rdfs:range xsd:string .
+
+:headBranch a owl:DatatypeProperty ;
+    rdfs:label "head branch" ;
+    rdfs:comment "Branch name a PipelineRun ran against." ;
+    rdfs:domain :PipelineRun ;
+    rdfs:range xsd:string .
+
+:event a owl:DatatypeProperty ;
+    rdfs:label "event" ;
+    rdfs:comment "Triggering event of a PipelineRun (push, pull_request, schedule, workflow_dispatch)." ;
+    rdfs:domain :PipelineRun ;
+    rdfs:range xsd:string .
+
+:runStartedAt a owl:DatatypeProperty ;
+    rdfs:label "run started at" ;
+    rdfs:comment "Timestamp a PipelineRun started executing." ;
+    rdfs:domain :PipelineRun ;
+    rdfs:range xsd:dateTime .
+
+:runUpdatedAt a owl:DatatypeProperty ;
+    rdfs:label "run updated at" ;
+    rdfs:comment "Timestamp a PipelineRun was last updated." ;
+    rdfs:domain :PipelineRun ;
+    rdfs:range xsd:dateTime .
+
+:durationSeconds a owl:DatatypeProperty ;
+    rdfs:label "duration seconds" ;
+    rdfs:comment "Wall-clock duration in seconds of a PipelineRun (runUpdatedAt - runStartedAt)." ;
+    rdfs:domain :PipelineRun ;
+    rdfs:range xsd:integer .
+
+:startedAt a owl:DatatypeProperty ;
+    rdfs:label "started at" ;
+    rdfs:comment "Timestamp a CheckRun started executing." ;
+    rdfs:domain :CheckRun ;
+    rdfs:range xsd:dateTime .
+
+:completedAt a owl:DatatypeProperty ;
+    rdfs:label "completed at" ;
+    rdfs:comment "Timestamp a CheckRun finished executing." ;
+    rdfs:domain :CheckRun ;
+    rdfs:range xsd:dateTime .
+
 <http://knuckles.team/kg/github> a owl:Ontology ;
     rdfs:label "GitHub Ontology" ;
     rdfs:comment """GitHub source-control, code-review and CI/CD model — organizations,

github_agent-1.4.1/github_agent/skills/github-backlog-planner/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: github-backlog-planner
+skill_type: skill
+description: >-
+  Sweeps every open issue and pull request across one or more GitHub accounts
+  (a user and/or an organization, all repositories), deeply verifies which items
+  are already addressed, and emits a prioritized Markdown remediation plan. Use
+  when asked to "go through all issues and PRs", triage a whole backlog, plan
+  what to work on next across repos, or audit open work for a user/org. Defaults
+  to read-only analysis; write actions (close, comment, open tracking issue) are
+  opt-in and run only on explicit confirmation. Do NOT use for a single PR's
+  review comments (use github-tools) or interactive one-tracker triage (use
+  issue-triage).
+license: MIT
+tags: [github, issues, pull-requests, backlog, triage, planning, ops]
+metadata:
+  author: Genius
+  version: '1.0.3'
+---
+
+# GitHub Backlog Planner
+
+## Overview
+
+Account-wide backlog sweep. Discovers all open issues and PRs across the target
+accounts (e.g. the `Knucklessg1` user **and** the `Knuckles-Team` org), determines
+which are **already addressed** (deep verification, not just labels), and produces a
+single prioritized Markdown plan grouped by account → repo. Read-only by default;
+any change to GitHub is opt-in.
+
+Drives the **github-agent** MCP server. No `gh` CLI or local `GITHUB_*` token is
+required — the MCP server holds its own auth.
+
+## Tool access (works under delegation AND the multiplexer)
+
+The tools are `github_issues`, `github_pulls`, `github_search`, `github_repos`,
+`github_orgs`, `github_commits`, `github_contents` — each takes `action` + a
+`params_json` **JSON string**.
+
+- **Under direct delegation** to `github-agent` (`execute_agent server=github-agent`,
+  or the `mcp-client` skill) the tools are already bound by their **native** names
+  — call them directly. This is the path this skill is written for.
+- **In the multiplexer / orchestrator** context the same tools carry the `gith__`
+  prefix (`gith__issues`, …); mount them first with
+  `load_tools(servers=["github-agent"])`.
+
+Confirmed action shapes: `github_issues`/`github_pulls` → `list|get|create|update`;
+`github_search` → `repositories|issues|code`; `github_repos` → `list|get`;
+`github_orgs` → `repos|get`.
+
+## Inputs
+
+- **accounts**: list of `{login, type}` where type is `user` or `org`. Default:
+  `[{login: "Knucklessg1", type: "user"}, {login: "Knuckles-Team", type: "org"}]`.
+- **include_prs**: default true. **include_issues**: default true.
+
+## Workflow
+
+### Step 1 — Discover repositories
+- User: `github_repos action=list` (authenticated user) — keep repos owned by the target login.
+- Org: `github_orgs action=repos {"org": "<login>"}`.
+- Record each repo's `default_branch`, `open_issues_count`, and archived flag. Skip archived repos.
+
+### Step 2 — Bulk-discover open items (efficient path)
+Use search, which returns issues AND PRs compactly account-wide:
+- `github_search action=issues {"q": "user:Knucklessg1 is:open is:issue"}`
+- `github_search action=issues {"q": "user:Knucklessg1 is:open is:pr"}`
+- `github_search action=issues {"q": "org:Knuckles-Team is:open is:issue"}`
+- `github_search action=issues {"q": "org:Knuckles-Team is:open is:pr"}`
+
+Paginate (`per_page`, `page`) until exhausted. If search results look incomplete for a
+repo, fall back to per-repo `github_issues action=list {owner, repo, state:"open"}` and
+`github_pulls action=list {owner, repo, state:"open"}`. Remember: the GitHub search/issues
+APIs return PRs in the issues list — distinguish them by the `pull_request` field.
+
+### Step 3 — Heuristic triage (Pass 1)
+Bucket every item using `references/addressed-heuristics.md` (Pass 1 table) into
+`needs-action`, `in-progress`, or *maybe addressed*. This is cheap and uses only the
+data already fetched.
+
+### Step 4 — Deep verification (Pass 2)
+For each *maybe addressed* item, follow Pass 2 in `references/addressed-heuristics.md`:
+`github_issues/pulls action=get` for linked PRs/commits, then `github_commits action=get`
+and/or `github_contents action=get` to **confirm the fix actually landed on the default
+branch** before marking it `addressed`. For items that still need a plan, read the
+relevant source to write a one-line root-cause note and a concrete recommendation.
+
+### Step 5 — Build the plan
+Normalize each item to the JSON schema in `scripts/build_plan.py` (account, repo, kind,
+number, title, url, state, status, evidence, recommendation, priority, labels), then:
+
+```bash
+python scripts/build_plan.py --input items.json --title "GitHub Backlog Plan (<date>)"
+# or: cat items.json | python scripts/build_plan.py
+```
+
+This renders: a summary line, a "verified addressed — safe to close" section, and a
+per-account/per-repo action table sorted by status then priority. Present it to the user.
+
+### Step 6 — Opt-in actions (only on explicit confirmation)
+Never write to GitHub without the user confirming. When asked:
+- Close a verified-addressed issue: `github_issues action=update {owner, repo, number, state:"closed"}`.
+- Post a triage comment: there is **no native comment action or tool** (`github_issues`
+  has no `comment` action, and no dedicated comment tool exists). Hand off to
+  `github-triage-resolver`, which performs gated writes, to leave the
+  `> *This was generated by AI during triage.*` note (mirrors the `issue-triage` convention).
+- Open a tracking issue for orphaned work: `github_issues action=create`.
+
+## Related skills
+- `github-ci-failure-sweep` — cross-link when a PR is blocked by failing CI.
+- `github-tools` — single-PR comments/CI inspection (do not duplicate here).
+- `issue-triage` — interactive, single-tracker state-machine triage.
+- `github-triage-resolver` — performs gated writes (comments, closes) this skill only recommends.

github_agent-1.4.1/github_agent/skills/github-backlog-planner/references/addressed-heuristics.md

@@ -0,0 +1,59 @@
+# "Already addressed?" — triage + deep-verify decision table
+
+Two-pass classification. **Pass 1** is a cheap heuristic that buckets every open item.
+**Pass 2** is a deep, per-item investigation that is run only on the items Pass 1 marks
+as *maybe addressed*, to confirm a fix actually landed before recommending a close.
+
+## Pass 1 — heuristic triage (cheap, from list/search data)
+
+### Issues
+| Signal | Bucket | Status |
+|---|---|---|
+| Has a **linked open PR** (or `linked_pull_requests`, or a PR whose body says `fixes #N`) | in progress | `in-progress` |
+| Has a **merged/closed PR** referencing it, but the issue is still open | maybe addressed → Pass 2 | (`addressed` if confirmed) |
+| Referenced by a recent **commit** on the default branch | maybe addressed → Pass 2 | (`addressed` if confirmed) |
+| Last activity is **stale** and no linked work | needs plan | `needs-action` |
+| Fresh, no linked work | needs plan | `needs-action` |
+
+### Pull requests
+| Signal | Status | Notes |
+|---|---|---|
+| Open, `draft: true` | `in-progress` | Recommend: finish + mark ready. |
+| Open, `mergeable_state: clean`, approved | `needs-action` | Recommend: merge. |
+| Open, failing checks / `mergeable_state: dirty`/`blocked` | `needs-action` | Recommend: fix CI or rebase (cross-link the CI sweep skill). |
+| Open, awaiting review | `needs-action` | Recommend: request/perform review. |
+| Open, conflicts with base | `needs-action` | Recommend: rebase/resolve. |
+
+## Pass 2 — deep verification (only for "maybe addressed")
+
+For each candidate, gather enough evidence to either confirm `addressed` (safe to close)
+or downgrade to `needs-action`:
+
+1. `github_issues action=get {owner, repo, number}` — read body + timeline; collect every
+   referenced PR number and commit SHA (look for `fixes/closes/resolves #N`, cross-refs).
+2. For each referenced PR: `github_pulls action=get {owner, repo, number}` — confirm
+   `merged: true` and which files it touched (`changed_files`, or list the PR's files).
+3. Open the **referencing commit / changed file** to verify the fix is real, not a no-op:
+   - `github_commits action=get {owner, repo, sha}` for the diff, and/or
+   - `github_contents action=get {owner, repo, path, ref}` to read the current source on the
+     default branch and confirm the described change is present.
+4. Verdict:
+   - Fix present on default branch + PR merged → `status: addressed`,
+     `evidence: "merged PR #N landed <change> in <file>"`, `recommendation: "Close #M"`.
+   - Referenced work reverted, or change absent, or PR closed-unmerged → `status: needs-action`,
+     `evidence: "PR #N closed without merging / change not on main"`.
+
+## For items that still need a plan
+
+Read the relevant source (`github_contents`) around the reported problem to write a
+**one-line root-cause note** and a **concrete recommended next step** (the `recommendation`
+field). Keep it actionable: name the file/function and the change, not "investigate".
+
+## Priority assignment
+- `high` (P1): PRs ready to merge, regressions/bugs blocking users, failing CI on default branch.
+- `medium` (P2): normal bugs, enhancements with a clear path.
+- `low` (P3): nice-to-have enhancements, stale/low-signal items.
+
+## Output contract
+Emit one normalized JSON object per item (see `scripts/build_plan.py` docstring for the schema)
+and pipe the list through `build_plan.py` to render the final Markdown plan.