Skip to content

tvproductions/gzkit / .agents/skills/ghi-triage

ghi-triage

Verified

Use to triage the open GHI queue before planning or choosing what to pull; produces a ranked deliverable.

FileKindSize
SKILL.mdskill md11.6 KB
scripts/triage.pyexecutablescript46.4 KB

scripts/triage.py

View on GitHub
#!/usr/bin/env python3
"""ghi-triage: fetch open GHIs, score routing, render deterministic deliverable.

Self-contained to the skill directory. Stdlib + `gh` CLI are the only
hard runtime requirements; `rich` is imported lazily inside the
`--format rich` path so consumers without it can still use the
markdown / json / rank formats. Invoke via:

    uv run python .claude/skills/ghi-triage/scripts/triage.py [args]

Routing thresholds: AGENTS.md § Defect-fix routing.

Output formats:
  - markdown (default, chat-renderable) — the candidate-set table
  - json — structured records for the agent's judgment pass
  - rank — the deterministic rank-ordered deliverable (requires --rank-input)
  - rich — terminal-only Rich table; explicit opt-in for TTY operators
                (this is the only path that requires `rich`)
"""

import argparse
import errno
import json
import os
import re
import shutil
import subprocess
import sys
from dataclasses import dataclass, field
from pathlib import Path

if hasattr(sys.stdout, "reconfigure"):
    sys.stdout.reconfigure(encoding="utf-8")  # ty: ignore[not-callable]
if hasattr(sys.stderr, "reconfigure"):
    sys.stderr.reconfigure(encoding="utf-8")  # ty: ignore[not-callable]
if hasattr(sys.stdin, "reconfigure"):
    sys.stdin.reconfigure(encoding="utf-8")  # ty: ignore[not-callable]

# --- Markdown renderer (default) ---------------------------------------------


def _md_escape(s: str) -> str:
    """Escape pipes and collapse newlines so a cell stays one markdown row."""
    return s.replace("|", "\\|").replace("\n", " ").strip()


def render_markdown(
    issues: list[Issue],
    precedent: int,
    duplicates: dict[int, int],
    *,
    blocker_resolver=None,
) -> str:
    precedent_ok = precedent >= 3
    triaged: list[tuple[Issue, str, str]] = []
    for issue in issues:
        r = route(issue, precedent_ok, duplicates)
        u = urgency(issue, r)
        triaged.append((issue, r, u))
    triaged.sort(key=lambda x: (URGENCY_RANK[x[2]], x[0].number))

    lines: list[str] = []
    lines.append(
        f"**GHI Triage** — {len(issues)} open issues | `fix()` precedent (60d): **{precedent}**\n"
    )
    lines.append("| # | Class | Route | Urgency | Title | Rationale |")
    lines.append("|---:|---|---|---|---|---|")
    for issue, r, u in triaged:
        cells = [
            str(issue.number),
            _md_escape(issue.klass),
            _md_escape(ROUTE_LABEL[r]),
            _md_escape(u),
            _md_escape(issue.title),
            _md_escape(rationale(issue, r, duplicates, blocker_resolver=blocker_resolver)),
        ]
        lines.append("| " + " | ".join(cells) + " |")

    lines.append("")
    lines.append("**Short list (copy/paste):**")
    lines.append("")
    lines.append("```text")
    last_urgency: str | None = None
    for issue, r, u in triaged:
        if last_urgency is not None and u != last_urgency:
            lines.append("")
        last_urgency = u
        lines.append(f"#{issue.number} — {ROUTE_LABEL[r]:<10} — {issue.title}")
    lines.append("```")
    return "\n".join(lines)


# --- Heuristic signals --------------------------------------------------------

_OBPI_SIGNALS = (
    re.compile(r"\bADR amendment\b", re.IGNORECASE),
    re.compile(r"\bcrosses\s+(brief|ADR)\b", re.IGNORECASE),
    re.compile(r"\bscope\s+expansion\b", re.IGNORECASE),
    re.compile(r"\bschema\s+change\b", re.IGNORECASE),
    re.compile(r"\bcontract\s+change\b", re.IGNORECASE),
    re.compile(r"\bnew\s+CLI\s+(verb|subcommand|flag)\b", re.IGNORECASE),
    re.compile(r"\bre[-\s]?open(s|ed)?\s+an?\s+attested\b", re.IGNORECASE),
    re.compile(r"\bpartial\s+Absorb\b", re.IGNORECASE),
    re.compile(r"\bbrief\s+boundary\b", re.IGNORECASE),
    re.compile(r"\bplan[-\s]?mode\s+gate\b", re.IGNORECASE),
)

_NOW_SIGNALS = (
    re.compile(r"\bblocks?\b", re.IGNORECASE),
    re.compile(r"\bdeadlocks?\b", re.IGNORECASE),
    re.compile(r"\bbroken\b", re.IGNORECASE),
    re.compile(r"\bcurrently\s+(fails|failing)\b", re.IGNORECASE),
    re.compile(r"\bfails?\s+for\b", re.IGNORECASE),
    re.compile(r"\bfalse[-\s]?positive\b", re.IGNORECASE),
)

_PATH_RE = re.compile(r"`([\w./\-]+\.(?:py|md|json|yml|yaml|feature|toml))`")
_FENCE_RE = re.compile(r"```.*?```", re.DOTALL)


@dataclass
class Comment:
    body: str
    created_at: str


@dataclass
class Issue:
    number: int
    title: str
    labels: list[str]
    body: str
    created_at: str
    updated_at: str
    comments: list[Comment] = field(default_factory=list)

    @property
    def klass(self) -> str:
        for label in ("defect", "enhancement", "investigation", "chore"):
            if label in self.labels:
                return label
        return "unlabeled"

    @property
    def unique_paths(self) -> set[str]:
        body = _FENCE_RE.sub("", self.body or "")
        return {m.group(1) for m in _PATH_RE.finditer(body)}


# --- Blocker freshness -------------------------------------------------------
#
# `ghi-close/SKILL.md` § Phase 1 step 1a: a blocker comment is "a claim about
# the tree as it stood on the day it was written" and must be re-derived before
# it is honored. The obligation was prose-only, so the decay went uncaught until
# someone checked by hand. These functions supply the instrument.

_BLOCKER_MARKERS = (
    re.compile(r"\bblocker\b", re.IGNORECASE),
    re.compile(r"\bblocked\s+on\b", re.IGNORECASE),
    re.compile(r"\bsequence\s+(?:this\s+)?after\b", re.IGNORECASE),
    re.compile(r"\bwaiting\s+on\b", re.IGNORECASE),
)

# OBPI before ADR: an OBPI id embeds its parent's semver, so matching ADR first
# would strand the suffix and invent a second, bogus reference.
_REFERENCE_PATTERNS = (
    ("OBPI", re.compile(r"\bOBPI-\d+\.\d+\.\d+-\d+")),
    ("ADR", re.compile(r"\bADR-(?:pool\.[a-z0-9-]+|\d+\.\d+\.\d+)")),
    ("GHI", re.compile(r"(?:\bGHI\s*)?#(\d+)\b")),
)

# `#N` is also how gzkit prose numbers a rule, a list item, or a section of some
# *other* document -- "`skill-surface-sync.md` #6", "Behavior Rules item #13".
# Those resolve against the issue tracker by coincidence, and a low number
# almost always hits a long-closed issue, so an unguarded match manufactures a
# confident false gate. Observed on the first live run against GHI #691.
_ORDINAL_CONTEXT = re.compile(
    r"(?:rules?|items?|steps?|sections?|invariants?|criteri(?:on|a)|questions?|rows?"
    r"|points?|lines?|phases?|notes?|tables?|clauses?|defects?|\.md`?|§)\s*$",
    re.IGNORECASE,
)


@dataclass
class BlockerRef:
    kind: str
    identifier: str
    state: str = "unknown"


@dataclass
class Blocker:
    created_at: str
    references: list[BlockerRef]

    @property
    def cites_settled(self) -> bool:
        """True when a cited precondition has already closed.

        Only `settled` counts. `unknown` does not: an unresolvable reference is
        missing evidence, not evidence of a closed precondition. Collapsing the
        two would let the flag manufacture a verdict it never earned.
        """
        return any(ref.state == "settled" for ref in self.references)


def is_blocker_comment(body: str) -> bool:
    """True when a comment records a precondition on the tree.

    Deliberately narrow. Every comment cross-links issues, so mining all of them
    would turn ordinary discussion into false gates -- the noise that gets a
    freshness signal ignored, which is indistinguishable from not having one.

    Returns:
        True when any blocker marker matches the body (an empty or None body never matches),
        otherwise False.

    """
    return any(p.search(body or "") for p in _BLOCKER_MARKERS)


def extract_references(text: str) -> list[BlockerRef]:
    """Return every governance identifier a precondition cites.

    Pure -- no network, no `gh`. Deduplicated on (kind, identifier) with
    first-seen order preserved, so a blocker naming the same GHI twice yields
    one reference to adjudicate rather than two.

    Returns:
        One reference per distinct (kind, identifier) pair, grouped by kind in pattern order and
        first-seen within each kind; empty when the text cites nothing.

    """
    seen: set[tuple[str, str]] = set()
    found: list[BlockerRef] = []
    remaining = text or ""
    for kind, pattern in _REFERENCE_PATTERNS:
        for match in pattern.finditer(remaining):
            identifier = match.group(1) if kind == "GHI" else match.group(0)
            if kind == "GHI" and _ORDINAL_CONTEXT.search(remaining[: match.start()]):
                continue
            if (kind, identifier) in seen:
                continue
            seen.add((kind, identifier))
            found.append(BlockerRef(kind=kind, identifier=identifier))
        # Consume what this kind claimed so a looser later pattern cannot
        # re-read the same span (`ADR-0.0.65` inside `OBPI-0.0.65-02`).
        remaining = pattern.sub(" ", remaining)
    return found


def blockers(issue: Issue, resolver=None) -> list[Blocker]:
    """Pair each of an issue's preconditions with the live state of what it cites.

    `resolver` is a parameter, never a named technology (hexagonal § Operative
    rule 4): it maps a GHI number to `live` / `settled` / `unknown`. With none
    injected every reference stays `unknown`, so the core is exercisable without
    `gh` and an unreachable live state never renders as verified.

    ADR and OBPI references always resolve `unknown` -- their only repo-local
    index is a Layer-3 derived view, which `state-doctrine.md` forbids as a
    source of truth. Reporting them as unverified is the honest outcome.

    Returns:
        One blocker per precondition comment, carrying its creation time and the references it
        cites, with GHI references resolved when a resolver is given; empty when no comment records
        a precondition.

    """
    found: list[Blocker] = []
    for comment in issue.comments:
        if not is_blocker_comment(comment.body):
            continue
        refs = extract_references(comment.body)
        if resolver is not None:
            for ref in refs:
                if ref.kind == "GHI":
                    ref.state = resolver(int(ref.identifier))
        found.append(Blocker(created_at=comment.created_at, references=refs))
    return found


def _stale_blocker_note(issue: Issue, resolver) -> str | None:
    """Render the settled citations of an issue's preconditions, if any."""
    settled = [
        f"#{ref.identifier}"
        for blocker in blockers(issue, resolver)
        for ref in blocker.references
        if ref.state == "settled"
    ]
    if not settled:
        return None
    return f"stale blocker: cites settled {', '.join(dict.fromkeys(settled))}"


# --- Family and staleness pass -----------------------------------------------
#
# Row 4 of `docs/rnd/ghi-landscape-reorganization.md`. Two signals of
# deliberately unequal strength; the difference is the point, so it is stated
# here and in the skill rather than left for a reader to infer.
#
# `stale_annotations` is EXACT. A body that writes `#889 (open)` transcribes a
# Layer-2 fact GitHub already renders live, so whether the transcription still
# holds is a lookup. The pattern binds the annotation to the reference it
# follows: a window-based match lends `(open)` to the neighbours of a correct
# `(closed)` list, which is how the `ghi-cross-reference-staleness` chore's
# first detector reached a 44% false-positive rate. Mirrored from that chore's
# `ANNOTATION_RE` rather than imported -- the chore is `projectLocal` and this
# script is mirrored to every vendor surface by `gz agent sync`.
#
# `family_signal` is NOT a classifier and its hits must never be counted as a
# family. Measured 2026-09-20 against the 38 members
# `docs/governance/f1-family-share-2026-09-20-evidence/measure.py` names among
# 57 open issues, these patterns disagree with that reader on 15: 9 they
# excluded, and 6 members no phrase catches (#950, #968, #997, #1011, #1012,
# #1013). Root-cause class is not a surface-word property -- which is exactly
# why the family slips past `ghi-author` Step 0's title skim. The signal names
# candidates for the agent's body read in Step 2; the agent rules.

_ANNOTATION_RE = re.compile(r"#(\d+)\*{0,2}\s*\((open|still open)\)", re.IGNORECASE)

_FAMILY_SIGNALS = (
    re.compile(
        r"\bno\s+(?:\w+\s+){0,2}(?:mechanism|witness|enforcement|validator|check|gate"
        r"|counter|caller|detection|coverage|owner|scope|path)\b",
        re.IGNORECASE,
    ),
    re.compile(
        r"\bnever\s+(?:\w+\s+){0,2}(?:invoked|called|enforced|checked|run|read"
        r"|validated|measured|passed|formed|fires?)\b",
        re.IGNORECASE,
    ),
    re.compile(r"\bunwitnessed\b|\bunmeasured\b|\buncorpused\b|\bunenforced\b", re.IGNORECASE),
    re.compile(
        r"\bnothing\s+(?:\w+\s+){0,2}(?:enforces|checks|validates|observes|refuses"
        r"|reads|asserts|detects)\b",
        re.IGNORECASE,
    ),
    re.compile(r"\bonly\s+in\s+prose\b|\bprose\s+only\b|\badvisory\s+only\b", re.IGNORECASE),
    re.compile(
        r"\bdeclares?\b[^.\n]{0,80}\bno\b|\bdeclared\b[^.\n]{0,40}\bwithout\b", re.IGNORECASE
    ),
    re.compile(
        r"\bnot\s+(?:enforced|witnessed|validated|checked|detected|measured)\b", re.IGNORECASE
    ),
    re.compile(r"\bexits?\s+0\s+(?:while|despite)\b|\breports?\s+success\s+over\b", re.IGNORECASE),
)


def family_signal(issue: Issue) -> list[str]:
    """Return the distinct doctrine-declared-without-mechanism phrases a body uses.

    Candidate evidence for the Step 2 body read, never a verdict and never a
    count -- see the calibration above. An empty list means no phrase matched,
    which is not evidence the issue is outside the family.

    Returns:
        The distinct matched phrases, lowercased and sorted; empty when no phrase matches.

    """
    haystack = f"{issue.title}\n{issue.body or ''}"
    return sorted({m.group(0).lower() for p in _FAMILY_SIGNALS for m in p.finditer(haystack)})


def stale_annotations(issue: Issue, resolver=None) -> list[dict]:
    """Return the issue's transcribed sibling-state annotations that have decayed.

    `resolver` is a parameter, never a named technology (hexagonal § Operative
    rule 4), matching `blockers` above: it maps a GHI number to `live` /
    `settled` / `unknown`. With none injected nothing resolves, so the core is
    exercisable without `gh` and an unreachable live state never renders as
    decayed.

    A decayed annotation is DECORATION, not a precondition. The
    `ghi-cross-reference-staleness` chore never rewrites a body, because
    `#889 (open)` is a dated record of what its author observed; this function
    reports the decay so the reader discounts the annotation, and the remedy is
    to stop writing them (`ghi-author` § Step 4).

    Returns:
        One `{"identifier", "annotated"}` dict per distinct cited issue the resolver reports
        settled, the last annotation winning; empty when no resolver is given or none has decayed.

    """
    if resolver is None:
        return []
    found: list[dict] = []
    for match in _ANNOTATION_RE.finditer(issue.body or ""):
        number = int(match.group(1))
        if resolver(number) == "settled":
            found.append({"identifier": f"#{number}", "annotated": match.group(2).lower()})
    return list({entry["identifier"]: entry for entry in found}.values())


# --- Data acquisition --------------------------------------------------------

ISSUE_JSON_FIELDS = "number,title,labels,createdAt,updatedAt,body,comments"


# Carried verbatim from gzkit.executables (tests/test_executables.py fences the copy):
# the current directory is never searched, so a planted gh.exe is never spawned.
def find_executable(name: str) -> str | None:
    """Return the absolute path of ``name`` from the absolute ``PATH`` entries.

    The ``shutil.which`` replacement for a presence probe: same answer on POSIX,
    and on Windows never the current directory.

    Returns:
        The executable's absolute path, or None when no absolute entry holds it.

    """
    for entry in os.environ.get("PATH", "").split(os.pathsep):
        directory = Path(entry)
        if not entry or not directory.is_absolute():
            continue
        found = shutil.which(str(directory / name))
        if found is not None:
            return found
    return None


def resolve_executable(name: str) -> str:
    """Return the absolute path of ``name``, as :func:`find_executable` finds it.

    Returns:
        The executable's absolute path.

    Raises:
        FileNotFoundError: no absolute ``PATH`` entry holds ``name``; the same
            exception ``subprocess`` raises for a missing executable, so a
            caller's existing handling still applies.

    """
    found = find_executable(name)
    if found is None:
        raise FileNotFoundError(
            errno.ENOENT,
            f"{name} is not on an absolute PATH entry; install it or add its directory to PATH",
            name,
        )
    return found


def _require(binary: str) -> None:
    if find_executable(binary) is None:
        sys.stderr.write(f"ghi-triage: required binary not found on PATH: {binary}\n")
        sys.exit(2)


def fetch(limit: int, label: str | None) -> list[Issue]:
    _require("gh")
    cmd = [
        "gh",
        "issue",
        "list",
        "--state",
        "open",
        "--limit",
        str(limit),
        "--json",
        ISSUE_JSON_FIELDS,
    ]
    if label:
        cmd += ["--label", label]
    raw = subprocess.run(  # noqa: S603 — gh issue list, a fixed argv; executable resolved
        [resolve_executable(cmd[0]), *cmd[1:]],
        capture_output=True,
        text=True,
        check=True,
        encoding="utf-8",
        errors="replace",
    )
    data = json.loads(raw.stdout)
    return [
        Issue(
            number=i["number"],
            title=i["title"],
            labels=[lbl["name"] for lbl in i["labels"]],
            body=i.get("body") or "",
            created_at=i["createdAt"],
            updated_at=i["updatedAt"],
            comments=[
                Comment(body=c.get("body") or "", created_at=c.get("createdAt") or "")
                for c in (i.get("comments") or [])
            ],
        )
        for i in data
    ]


def gh_reference_resolver(open_numbers: set[int]):
    """Adapter: resolve a GHI number against GitHub, closing over the open set.

    The open set is already in hand from `fetch()`, so a reference to an open
    issue costs nothing. Anything else needs one `gh` call to distinguish
    *closed* from *never existed* -- a distinction that matters, because a
    blocker citing a typo'd number is not a discharged precondition.

    Returns:
        A resolver mapping a GHI number to "live" (open, or not closed), "settled" (closed) or
        "unknown" (the `gh` lookup failed), caching each answer.

    """
    cache: dict[int, str] = {}

    def resolve(number: int) -> str:
        if number in open_numbers:
            return "live"
        if number in cache:
            return cache[number]
        try:
            raw = subprocess.run(  # noqa: S603 — gh issue view of a cited number; executable resolved
                [resolve_executable("gh"), "issue", "view", str(number), "--json", "state"],
                capture_output=True,
                text=True,
                check=True,
                encoding="utf-8",
                errors="replace",
            )
            state = json.loads(raw.stdout).get("state", "")
            cache[number] = "settled" if state == "CLOSED" else "live"
        except OSError, ValueError, subprocess.SubprocessError:
            # Unreachable state is `unknown`, never `settled`: a network failure
            # must not be readable as "the precondition cleared".
            cache[number] = "unknown"
        return cache[number]

    return resolve


# --- Precedent count cache ---------------------------------------------------


def _precedent_cache_path() -> Path:
    return Path.home() / ".cache" / "gzkit" / "triage-precedent.json"


def _git_head_sha() -> str | None:
    try:
        out = subprocess.run(  # noqa: S603 — git with a fixed subcommand; executable resolved
            [resolve_executable("git"), "rev-parse", "HEAD"],
            capture_output=True,
            text=True,
            check=True,
            encoding="utf-8",
        )
        return out.stdout.strip() or None
    except subprocess.CalledProcessError, FileNotFoundError:
        return None


def _load_precedent_cache(head: str) -> int | None:
    path = _precedent_cache_path()
    try:
        payload = json.loads(path.read_text(encoding="utf-8"))
    except FileNotFoundError, json.JSONDecodeError, OSError:
        return None
    entry = payload.get(head)
    if isinstance(entry, int):
        return entry
    return None


def _store_precedent_cache(head: str, count: int) -> None:
    path = _precedent_cache_path()
    try:
        path.parent.mkdir(parents=True, exist_ok=True)
        try:
            payload = json.loads(path.read_text(encoding="utf-8"))
            if not isinstance(payload, dict):
                payload = {}
        except FileNotFoundError, json.JSONDecodeError, OSError:
            payload = {}
        payload[head] = count
        path.write_text(json.dumps(payload, indent=2, sort_keys=True), encoding="utf-8")
    except OSError:
        pass


def fix_precedent_count() -> int:
    _require("git")
    head = _git_head_sha()
    if head is not None:
        cached = _load_precedent_cache(head)
        if cached is not None:
            return cached
    out = subprocess.run(  # noqa: S603 — git with a fixed subcommand; executable resolved
        [resolve_executable("git"), "log", "--since=60 days ago", "--oneline", "--grep=^fix("],
        capture_output=True,
        text=True,
        check=True,
        encoding="utf-8",
    )
    count = sum(1 for line in out.stdout.splitlines() if line.strip())
    if head is not None:
        _store_precedent_cache(head, count)
    return count


def detect_duplicates(issues: list[Issue]) -> dict[int, int]:
    by_title: dict[str, list[Issue]] = {}
    for i in issues:
        by_title.setdefault(i.title.strip().lower(), []).append(i)
    duplicates: dict[int, int] = {}
    for group in by_title.values():
        if len(group) > 1:
            canonical = min(group, key=lambda x: x.number)
            for dup in group:
                if dup.number != canonical.number:
                    duplicates[dup.number] = canonical.number
    return duplicates


# --- Routing logic -----------------------------------------------------------


def route(issue: Issue, precedent_ok: bool, duplicates: dict[int, int]) -> str:
    """Triage routing for an open GHI.

    GHIs are repair vessels for defects; the receipts left on the GHI itself
    are the audit trail. Triage never routes to OBPI — OBPI ceremony is
    reserved for new feature-shape work under an active ADR (operator-
    directed via gz plan / gz-design), not produced from the issue queue.
    Feature-shape signals on a GHI are surfaced through `rationale()` as
    escalation hints for operator judgment, not as a routing flip.

    Returns:
        "close-dup" when the issue is a known duplicate, "ambiguous" when the fix() precedent is too
        thin, otherwise "direct-fix".

    """
    if issue.number in duplicates:
        return "close-dup"
    if not precedent_ok:
        return "ambiguous"
    return "direct-fix"


def urgency(issue: Issue, route_label: str) -> str:
    if route_label == "close-dup":
        return "later"
    body = issue.body or ""
    if any(p.search(body) for p in _NOW_SIGNALS):
        return "now"
    if issue.klass == "chore":
        return "later"
    return "soon"


def rationale(
    issue: Issue,
    route_label: str,
    duplicates: dict[int, int],
    *,
    blocker_resolver=None,
) -> str:
    if route_label == "close-dup":
        return f"Duplicate of #{duplicates[issue.number]}"
    paths = issue.unique_paths
    body = issue.body or ""
    parts: list[str] = []
    stale = _stale_blocker_note(issue, blocker_resolver)
    if stale:
        # First, not appended: a precondition that no longer holds changes
        # whether the rest of the rationale is worth reading at all.
        parts.append(stale)
    if paths:
        parts.append(f"{len(paths)} file{'s' if len(paths) != 1 else ''}")
    for p in _OBPI_SIGNALS:
        m = p.search(body) or p.search(issue.title)
        if m:
            parts.append(f"signal: {m.group(0)!r}")
            break
    for p in _NOW_SIGNALS:
        m = p.search(body)
        if m:
            parts.append(f"blocking: {m.group(0)!r}")
            break
    if not parts:
        parts.append("thin body — manual review")
    return "; ".join(parts)


URGENCY_RANK = {"now": 0, "soon": 1, "later": 2}
ROUTE_LABEL = {
    "direct-fix": "direct-fix",
    "ambiguous": "ambiguous",
    "close-dup": "close",
}

# Color map for at-a-glance scanning.
URGENCY_STYLE = {"now": "bold red", "soon": "yellow", "later": "dim"}
ROUTE_STYLE = {
    "direct-fix": "green",
    "ambiguous": "yellow",
    "close": "dim",
}
CLASS_STYLE = {
    "defect": "red",
    "enhancement": "cyan",
    "investigation": "blue",
    "chore": "dim",
    "unlabeled": "dim italic",
}


# --- Rank deliverable (the agent-fed deterministic output) -------------------


SEVERITY_VALUES = ("blocking", "degrading", "latent")
SEVERITY_RANK = {sev: idx for idx, sev in enumerate(SEVERITY_VALUES)}
# What ends the issue: an agent now, an operator ruling, another landing, or an
# open question. Structural, like severity — never prose (GHI #424). Tuple order
# is render order: the landing queue first, then the ruling docket.
READINESS_VALUES = ("ready", "ruling", "sequence", "design")
READINESS_HEADERS = {
    "ready": "## Landing queue — ready (single writer, ghi-close one issue at a time)",
    "ruling": "## Ruling docket — awaiting an operator ruling",
    "sequence": "## Waiting on sequence",
    "design": "## Open design questions",
}
_ALLOWED_RANKING_KEYS = frozenset({"number", "severity", "readiness"})


@dataclass(frozen=True)
class RankItem:
    number: int
    severity: str
    readiness: str | None = None


class RankInputError(ValueError):
    """Raised when --rank-input fails the rendering-edge contract."""


class RankInputNotObjectError(RankInputError):
    """The --rank-input payload is not a JSON object."""

    def __init__(self) -> None:
        super().__init__("--rank-input must be a JSON object")


class RankingsMissingError(RankInputError):
    """The --rank-input payload lacks a non-empty 'rankings' list."""

    def __init__(self) -> None:
        super().__init__("--rank-input requires non-empty 'rankings' list")


class RankingEntryNotObjectError(RankInputError):
    """A rankings entry is not a JSON object."""

    def __init__(self, idx: int) -> None:
        self.idx = idx
        super().__init__(f"rankings[{idx}] must be an object")


class RankingForbiddenFieldsError(RankInputError):
    """A rankings entry carries fields outside the structural schema."""

    def __init__(self, idx: int, extra: list[str]) -> None:
        self.idx = idx
        self.extra = extra
        super().__init__(
            f"rankings[{idx}] has forbidden field(s) {extra!r}; "
            "schema accepts only 'number', 'severity' and 'readiness' (GHI #424)"
        )


class RankingNumberTypeError(RankInputError):
    """A rankings entry's number is not an int."""

    def __init__(self, idx: int) -> None:
        self.idx = idx
        super().__init__(f"rankings[{idx}].number must be int")


class RankingDuplicateNumberError(RankInputError):
    """A rankings entry repeats a number an earlier entry carried."""

    def __init__(self, idx: int, number: int) -> None:
        self.idx = idx
        self.number = number
        super().__init__(f"rankings[{idx}].number={number} duplicates earlier entry")


class RankingUnknownNumberError(RankInputError):
    """A rankings entry names an issue absent from the fetched set."""

    def __init__(self, idx: int, number: int) -> None:
        self.idx = idx
        self.number = number
        super().__init__(f"rankings[{idx}].number={number} not present in fetched issue set")


class RankingSeverityError(RankInputError):
    """A rankings entry's severity is outside the allowed values."""

    def __init__(self, idx: int, allowed: tuple[str, ...]) -> None:
        self.idx = idx
        super().__init__(f"rankings[{idx}].severity must be one of {allowed}")


class RankingReadinessError(RankInputError):
    """A rankings entry's readiness is outside the allowed values."""

    def __init__(self, idx: int, allowed: tuple[str, ...]) -> None:
        self.idx = idx
        super().__init__(f"rankings[{idx}].readiness must be one of {allowed}")


class RankingReadinessPartialError(RankInputError):
    """Readiness is carried by some rankings entries but not all."""

    def __init__(self, carrying: int, total: int) -> None:
        self.carrying = carrying
        self.total = total
        super().__init__(
            f"readiness is on {carrying} of {total} entries; every entry carries it or none does"
        )


class RankInputPathRequiredError(RankInputError):
    """--format rank was invoked without a --rank-input path."""

    def __init__(self) -> None:
        super().__init__(
            "--format rank requires --rank-input <path>; stdin is not accepted (GHI #424)"
        )


class RankInputStdinError(RankInputError):
    """--rank-input named stdin, which the contract refuses."""

    def __init__(self) -> None:
        super().__init__(
            "--rank-input does not accept stdin ('-'); "
            "Write the JSON to .gzkit/cache/triage/<name>.json and pass the path "
            "(GHI #424)"
        )


class RankInputOutsideCacheError(RankInputError):
    """--rank-input names a path outside the triage cache directory."""

    def __init__(self, cache_dir: str, path: str) -> None:
        self.cache_dir = cache_dir
        self.path = path
        super().__init__(
            f"--rank-input path must live under {cache_dir}/ "
            f"(got {path!r}); the cache-path requirement structurally prevents "
            "inline-pipe duplicate-render shapes (GHI #424)"
        )


class RankInputEmptyError(RankInputError):
    """The --rank-input file is empty."""

    def __init__(self) -> None:
        super().__init__("--rank-input is empty")


def parse_rank_input(payload: object, known_numbers: set[int]) -> list[RankItem]:
    """Validate agent-supplied rank input.

    Schema is structural-only: number + severity per entry, plus an optional
    readiness enum that every entry carries or none does. No prose fields
    (no `action`, no `why`) — those duplicated the renderer's title output
    and produced the recurring chat-surface duplication GHI #424 closed
    structurally. Cognitive freedom lives in selection + ordering + severity;
    the renderer owns all prose.

    Returns:
        The validated rank items in input order.

    Raises:
        RankInputNotObjectError: The payload is not a JSON object.
        RankingsMissingError: The payload lacks a non-empty 'rankings' list.
        RankingEntryNotObjectError: A rankings entry is not an object.
        RankingForbiddenFieldsError: An entry carries a field outside the schema.
        RankingNumberTypeError: An entry's number is not an int.
        RankingDuplicateNumberError: An entry repeats an earlier number.
        RankingUnknownNumberError: An entry names an issue outside the fetched set.
        RankingSeverityError: An entry's severity is not an allowed value.
        RankingReadinessError: An entry's readiness is not an allowed value.
        RankingReadinessPartialError: Readiness is on some entries but not all.

    """
    if not isinstance(payload, dict):
        raise RankInputNotObjectError
    rankings = payload.get("rankings")
    if not isinstance(rankings, list) or not rankings:
        raise RankingsMissingError
    items: list[RankItem] = []
    seen: set[int] = set()
    for idx, entry in enumerate(rankings):
        if not isinstance(entry, dict):
            raise RankingEntryNotObjectError(idx)
        extra = sorted(set(entry.keys()) - _ALLOWED_RANKING_KEYS)
        if extra:
            raise RankingForbiddenFieldsError(idx, extra)
        number = entry.get("number")
        if not isinstance(number, int) or isinstance(number, bool):
            raise RankingNumberTypeError(idx)
        if number in seen:
            raise RankingDuplicateNumberError(idx, number)
        if number not in known_numbers:
            raise RankingUnknownNumberError(idx, number)
        seen.add(number)
        severity = entry.get("severity")
        if not isinstance(severity, str) or severity not in SEVERITY_VALUES:
            raise RankingSeverityError(idx, SEVERITY_VALUES)
        readiness = entry.get("readiness")
        if readiness is not None and readiness not in READINESS_VALUES:
            raise RankingReadinessError(idx, READINESS_VALUES)
        items.append(RankItem(number=number, severity=severity, readiness=readiness))
    carrying = sum(item.readiness is not None for item in items)
    if carrying not in (0, len(items)):
        raise RankingReadinessPartialError(carrying, len(items))
    return items


def render_rank(
    items: list[RankItem],
    issue_index: dict[int, Issue],
    routes: dict[int, str],
    precedent: int,
    total: int,
) -> str:
    """Render the rank-ordered deliverable.

    Deterministic by construction: items render in caller-provided order
    (the agent owns the ranking), every field is validated upstream by
    parse_rank_input, and no formatting branches on environment. The line
    shape is a strict superset of the agent's input — the agent contributes
    {number, severity, ordering}; the renderer adds {route, title} from the
    fetched issue set. No prose field appears in both surfaces. When the input
    carries readiness, items render in fixed-order readiness groups, caller
    order kept within each.

    Returns:
        The Markdown deliverable: a header line, then the rank lines either grouped under readiness
        headers or in caller order.

    """
    lines = [
        f"# GHI Triage Ranking — {len(items)} ranked of {total} open "
        f"| fix() precedent (60d): {precedent}",
        "",
    ]
    if items and items[0].readiness is not None:
        for readiness in READINESS_VALUES:
            group = [item for item in items if item.readiness == readiness]
            if group:
                lines.extend([READINESS_HEADERS[readiness], ""])
                lines.extend(_rank_lines(group, issue_index, routes))
                lines.append("")
    else:
        lines.extend(_rank_lines(items, issue_index, routes))
        lines.append("")
    return "\n".join(lines)


def _rank_lines(
    items: list[RankItem], issue_index: dict[int, Issue], routes: dict[int, str]
) -> list[str]:
    return [
        f"{rank}. #{item.number} [{item.severity}] {routes.get(item.number, '—')} — "
        f"{issue_index[item.number].title}"
        for rank, item in enumerate(items, start=1)
    ]


# --- Rendering ---------------------------------------------------------------


def _detect_width() -> int:
    """Pick a render width by interrogating the runtime context.

    Resolution order:
      1. GHI_TRIAGE_WIDTH env var (explicit operator override)
      2. COLUMNS env var (parent shell or harness propagation)
      3. shutil.get_terminal_size() when stdout is a real TTY (no cap)
      4. 100 cols (agent-harness display column; no TTY detected)

    Returns:
        The render width in columns from the first source in the resolution order that applies.

    """
    env_explicit = os.environ.get("GHI_TRIAGE_WIDTH")
    if env_explicit and env_explicit.isdigit():
        return int(env_explicit)

    env_cols = os.environ.get("COLUMNS")
    if env_cols and env_cols.isdigit():
        return int(env_cols)

    if sys.stdout.isatty():
        return shutil.get_terminal_size((100, 20)).columns

    return 100


def _make_console(width: int | None):
    """Force Rich to render a real table even under non-TTY capture.

    Rich downgrades box drawing, color, and column ratios when stdout isn't a
    TTY. We always want the full Rich table, so `force_terminal=True` keeps
    the glyphs and the explicit width defeats the 80-col fallback.

    Rich is imported lazily here so consumers that ship the skill without
    `rich` installed can still use the markdown / json / rank paths
    (`--format rich` is the only consumer of this helper).

    Returns:
        A Rich console forced to terminal mode with truecolor, at the given width or the detected
        one when width is None.

    """
    from rich.console import Console  # noqa: PLC0415 — lazy: see docstring

    if width is None:
        width = _detect_width()
    return Console(force_terminal=True, color_system="truecolor", width=width)


def render(
    issues: list[Issue],
    precedent: int,
    duplicates: dict[int, int],
    width: int | None = None,
    *,
    blocker_resolver=None,
) -> None:
    # Lazy imports: rich is only needed for the --format rich path; keeping
    # the skill script importable on consumers that don't ship rich.
    from rich import box  # noqa: PLC0415
    from rich.table import Table  # noqa: PLC0415
    from rich.text import Text  # noqa: PLC0415

    console = _make_console(width)
    precedent_ok = precedent >= 3

    triaged: list[tuple[Issue, str, str]] = []
    for issue in issues:
        r = route(issue, precedent_ok, duplicates)
        u = urgency(issue, r)
        triaged.append((issue, r, u))
    triaged.sort(key=lambda x: (URGENCY_RANK[x[2]], x[0].number))

    console.print(
        f"\n[bold]GHI Triage[/bold] — {len(issues)} open issues | "
        f"fix() precedent (60d): [bold]{precedent}[/bold]\n"
    )

    table = Table(
        box=box.ROUNDED,
        show_lines=True,
        header_style="bold",
        expand=True,
        pad_edge=False,
    )
    table.add_column("#", justify="right", style="bold", no_wrap=True)
    table.add_column("Class", no_wrap=True)
    table.add_column("Route", no_wrap=True)
    table.add_column("Urgency", no_wrap=True)
    table.add_column("Title", overflow="fold", ratio=3)
    table.add_column("Rationale", overflow="fold", ratio=2)

    for issue, r, u in triaged:
        route_label = ROUTE_LABEL[r]
        table.add_row(
            str(issue.number),
            Text(issue.klass, style=CLASS_STYLE.get(issue.klass, "")),
            Text(route_label, style=ROUTE_STYLE.get(route_label, "")),
            Text(u, style=URGENCY_STYLE.get(u, "")),
            issue.title,
            rationale(issue, r, duplicates, blocker_resolver=blocker_resolver),
        )
    console.print(table)

    console.print("\n[bold]Short list (copy/paste):[/bold]\n")
    last_urgency: str | None = None
    for issue, r, u in triaged:
        if last_urgency is not None and u != last_urgency:
            console.print("")
        last_urgency = u
        console.print(
            f"#{issue.number} — {ROUTE_LABEL[r]:<10} — {issue.title}",
            highlight=False,
            markup=False,
        )
    console.print("")


def render_json(
    issues: list[Issue],
    precedent: int,
    duplicates: dict[int, int],
    *,
    blocker_resolver=None,
) -> str:
    """Emit triage records for agent consumption.

    The agent uses this to drive per-GHI judgment: full body included so the
    agent does not re-shell `gh issue view` once per issue. `blockers` carries
    each recorded precondition with the live state of what it cites, so the
    judgment pass re-derives them (`ghi-close` § Phase 1 step 1a) instead of
    inheriting them as standing fact.

    `family_signal` and `stale_annotations` are the row-4 pass. They are not
    peers: `stale_annotations` is an exact lookup, `family_signal` is candidate
    evidence with a measured disagreement rate that the agent adjudicates.
    Neither feeds the rank-input schema, which stays structural-only (GHI #424).

    Returns:
        Indented JSON object carrying the 60-day precedent count, the issue count and the per-issue
        records sorted by urgency and then issue number.

    """
    precedent_ok = precedent >= 3
    records: list[dict] = []
    for issue in issues:
        r = route(issue, precedent_ok, duplicates)
        u = urgency(issue, r)
        records.append(
            {
                "number": issue.number,
                "title": issue.title,
                "labels": issue.labels,
                "klass": issue.klass,
                "body": issue.body,
                "files_mentioned": sorted(issue.unique_paths),
                "dup_of": duplicates.get(issue.number),
                "route": ROUTE_LABEL[r],
                "urgency": u,
                "rationale": rationale(issue, r, duplicates, blocker_resolver=blocker_resolver),
                "blockers": [
                    {
                        "created_at": b.created_at,
                        "cites_settled": b.cites_settled,
                        "references": [
                            {"kind": ref.kind, "identifier": ref.identifier, "state": ref.state}
                            for ref in b.references
                        ],
                    }
                    for b in blockers(issue, blocker_resolver)
                ],
                "family_signal": family_signal(issue),
                "stale_annotations": stale_annotations(issue, blocker_resolver),
                "created_at": issue.created_at,
                "updated_at": issue.updated_at,
            }
        )
    records.sort(key=lambda x: (URGENCY_RANK[x["urgency"]], x["number"]))
    return json.dumps(
        {"precedent_60d": precedent, "count": len(issues), "issues": records},
        indent=2,
    )


RANK_INPUT_CACHE_DIR = Path(".gzkit/cache/triage")


def _ensure_rank_input_cache_dir() -> Path:
    """Create `.gzkit/cache/triage/` on demand and return its resolved path.

    Auto-creation keeps the skill portable to fresh checkouts: the agent's
    `Write .gzkit/cache/triage/<name>.json` step would otherwise fail with
    a parent-directory error on first use. The directory is the supported
    Write target, so the script owns its lifecycle.

    Returns:
        The cache directory's resolved absolute path.

    """
    RANK_INPUT_CACHE_DIR.mkdir(parents=True, exist_ok=True)
    return RANK_INPUT_CACHE_DIR.resolve()


def _read_rank_input(path: str | None) -> object:
    """Load rank input from a path under .gzkit/cache/triage/.

    Stdin (`-`) is rejected and inline-pipe shapes (`echo '<json>' | …`) are
    structurally impossible: the agent must Write the JSON to a file under
    the cache directory and pass the path. The path constraint kills the
    duplicate-render shape on the bash command-line surface (GHI #424
    round 4) — a `Write` tool call surfaces only the file path in chat,
    while `echo '<json>' | …` surfaces the whole rank payload as the
    command line itself.

    Returns:
        The JSON value decoded from the file.

    Raises:
        RankInputPathRequiredError: No --rank-input path was given.
        RankInputStdinError: The path is stdin (`-`).
        RankInputOutsideCacheError: The path lies outside the triage cache.
        RankInputEmptyError: The file is empty.

    """
    if path is None:
        raise RankInputPathRequiredError
    if path == "-":
        raise RankInputStdinError
    cache_root = _ensure_rank_input_cache_dir()
    resolved = Path(path).resolve()
    try:
        resolved.relative_to(cache_root)
    except ValueError as exc:
        raise RankInputOutsideCacheError(RANK_INPUT_CACHE_DIR.as_posix(), path) from exc
    raw = resolved.read_text(encoding="utf-8")
    if not raw.strip():
        raise RankInputEmptyError
    return json.loads(raw)


def main() -> int:
    p = argparse.ArgumentParser(description="Triage open GHIs")
    p.add_argument("--limit", type=int, default=100)
    p.add_argument("--label", default=None, help="Filter by single label")
    p.add_argument(
        "--format",
        choices=("markdown", "json", "rank", "rich"),
        default="markdown",
        help="Output format. 'markdown' (default) — chat-renderable table for "
        "operator skim. 'json' — structured records the agent reads to compose "
        "rank input. 'rank' — the deterministic rank-ordered deliverable; "
        "requires --rank-input. 'rich' — terminal-only Rich table with ANSI "
        "color, opt-in for TTY operators.",
    )
    p.add_argument(
        "--rank-input",
        default=None,
        help="Path to a JSON file containing the agent's rank input "
        "({'rankings': [{number, severity[, readiness]}, ...]}). Path MUST live under "
        f"{RANK_INPUT_CACHE_DIR.as_posix()}/ (stdin rejected — Write the "
        "JSON to a cache file and pass the path). Required with --format "
        f"rank. Schema is structural-only: severity is one of "
        f"{SEVERITY_VALUES}; readiness, on every entry or none, is one of "
        f"{READINESS_VALUES}. No prose fields are accepted (extras are "
        "rejected, GHI #424).",
    )
    p.add_argument(
        "--width",
        type=int,
        default=None,
        help="Rich render width override (only with --format rich)",
    )
    args = p.parse_args()

    issues = fetch(args.limit, args.label)
    if not issues:
        if args.format == "json":
            print(json.dumps({"precedent_60d": 0, "count": 0, "issues": []}))
        elif args.format == "rank":
            sys.stderr.write("ghi-triage: no open issues — nothing to rank.\n")
            return 1
        else:
            print("No open issues.")
        return 0
    precedent = fix_precedent_count()
    duplicates = detect_duplicates(issues)

    if args.format == "rank":
        try:
            payload = _read_rank_input(args.rank_input)
            known = {issue.number for issue in issues}
            items = parse_rank_input(payload, known)
        except (RankInputError, json.JSONDecodeError, FileNotFoundError, OSError) as exc:
            sys.stderr.write(f"ghi-triage: --rank-input invalid: {exc}\n")
            return 1
        precedent_ok = precedent >= 3
        issue_index = {issue.number: issue for issue in issues}
        routes = {
            issue.number: ROUTE_LABEL[route(issue, precedent_ok, duplicates)] for issue in issues
        }
        sys.stdout.write(render_rank(items, issue_index, routes, precedent, len(issues)))
        return 0
    resolver = gh_reference_resolver({issue.number for issue in issues})
    if args.format == "rich":
        render(issues, precedent, duplicates, width=args.width, blocker_resolver=resolver)
    elif args.format == "markdown":
        print(render_markdown(issues, precedent, duplicates, blocker_resolver=resolver))
    else:
        print(render_json(issues, precedent, duplicates, blocker_resolver=resolver))
    return 0


if __name__ == "__main__":
    sys.exit(main())
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall