Skip to content

tvproductions/gzkit / .agents/skills/gz-foundation-triage

gz-foundation-triage

Verified

Use to rank the in-flight foundation backlog by insight signal, GHI count and invariants.

FileKindSize
SKILL.mdskill md6.6 KB
scripts/triage.pyexecutablescript13.5 KB

scripts/triage.py

View on GitHub
#!/usr/bin/env python3
"""gz-foundation-triage: gather in-flight foundation ADRs and render the rank.

Self-contained to the skill directory. Stdlib-only. Invoke via:

    uv run python .gzkit/skills/gz-foundation-triage/scripts/triage.py [args]

Output formats:
  - json (Step 1 input)  — structured records the agent reads for cognition
  - rank (Step 3 output) — deterministic markdown deliverable (requires --rank-input)

The script is read-only over the governance corpus — it parses ADR files,
the insights stream, AGENTS.md, and `.gzkit/rules/*.md` and never writes to
any of them. Rubric scoring is the foundation-triage-rubric OBPI's surface
and is not invoked here; ranking falls back to raw signal totals when no
rubric module is available.
"""

import argparse
import json
import re
import sys
from collections.abc import Iterable
from pathlib import Path

_IN_FLIGHT_STATUSES: frozenset[str] = frozenset({"Draft", "Proposed"})
_ADR_ID_PATTERN = re.compile(r"^ADR-(?:pool\.[a-z0-9-]+|\d+\.\d+\.\d+)", re.IGNORECASE)
_FOUNDATION_ID_PATTERN = re.compile(r"^ADR-\d+\.\d+\.\d+$")
_FOUNDATION_SHORT_ID_PREFIX = re.compile(r"^(ADR-\d+\.\d+\.\d+)")


class RankingsNotListError(SystemExit):
    """The rank-input 'rankings' field is not a list."""

    def __init__(self) -> None:
        super().__init__("rank-input 'rankings' must be a list")


class ReclassifyNotListError(SystemExit):
    """The rank-input 'reclassify_foundation' field is not a list."""

    def __init__(self) -> None:
        super().__init__("rank-input 'reclassify_foundation' must be a list")


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

    def __init__(self, entry: object) -> None:
        super().__init__(f"rankings entry must be a JSON object, got {type(entry).__name__}")


class RankingForbiddenKeysError(SystemExit):
    """A rankings entry carries keys outside the structural schema."""

    def __init__(self, adr_id: object, extra_keys: set[str]) -> None:
        self.adr_id = adr_id
        self.extra_keys = extra_keys
        super().__init__(f"rankings entry {adr_id!r} carries forbidden keys: {sorted(extra_keys)}")


class RankingUnknownIdError(SystemExit):
    """A rankings entry names an ADR absent from the fetched candidate set."""

    def __init__(self, adr_id: object) -> None:
        self.adr_id = adr_id
        super().__init__(f"rankings entry id {adr_id!r} not in fetched candidate set")


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

    def __init__(self, adr_id: str, severity: object, allowed: set[str]) -> None:
        self.adr_id = adr_id
        self.severity = severity
        super().__init__(f"rankings entry {adr_id} severity {severity!r} not in {sorted(allowed)}")


class ReclassifyEntryNotObjectError(SystemExit):
    """A reclassify_foundation entry is not a JSON object."""

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


class ReclassifyForbiddenKeysError(SystemExit):
    """A reclassify_foundation entry carries keys outside the structural schema."""

    def __init__(self, extra_keys: set[str]) -> None:
        self.extra_keys = extra_keys
        super().__init__(
            f"reclassify_foundation entry carries forbidden keys: {sorted(extra_keys)}"
        )


class ReclassifyInvalidIdError(SystemExit):
    """A reclassify_foundation entry's id is not a valid ADR id."""

    def __init__(self, adr_id: object) -> None:
        self.adr_id = adr_id
        super().__init__(f"reclassify_foundation id {adr_id!r} is not a valid ADR id")


class ReclassifyTargetError(SystemExit):
    """A reclassify_foundation entry's reclassify value is not 'foundation'."""

    def __init__(self, adr_id: str) -> None:
        self.adr_id = adr_id
        super().__init__(f"reclassify_foundation entry {adr_id} reclassify must be 'foundation'")


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

    def __init__(self) -> None:
        super().__init__("--format rank requires --rank-input <path>")


class RankInputReadError(SystemExit):
    """The rank-input file could not be read or decoded."""

    def __init__(self, exc: Exception) -> None:
        super().__init__(f"failed to read rank-input: {exc}")


def _project_root_from_script(script_path: Path) -> Path:
    """Resolve repo root from this script's location.

    Script lives at ``<repo>/.gzkit/skills/<skill>/scripts/triage.py`` —
    four directory levels below the repository root.

    Returns:
        The repository root, taken as the fifth ancestor of the resolved script path.

    """
    return script_path.resolve().parents[4]


def _parse_simple_frontmatter(text: str) -> dict[str, str]:
    """Parse top-of-file YAML frontmatter into a flat str->str mapping.

    Avoids a PyYAML dependency: the script is stdlib-only by contract. The
    frontmatter block is the leading `---` ... `---` fence; each non-empty
    line is parsed as `key: value`. Nested structures are ignored — the
    only fields the triage cares about (id, status, title) are flat.

    Returns:
        Mapping of each flat frontmatter key to its value with surrounding quotes stripped; empty
        when the text has no leading `---` fence or the fence is never closed.

    """
    if not text.startswith("---"):
        return {}
    end = text.find("\n---", 3)
    if end < 0:
        return {}
    body = text[3:end]
    fields: dict[str, str] = {}
    for line in body.splitlines():
        stripped = line.strip()
        if not stripped or stripped.startswith("#"):
            continue
        if ":" not in stripped:
            continue
        key, _, value = stripped.partition(":")
        fields[key.strip()] = value.strip().strip("'\"")
    return fields


def _extract_title(text: str) -> str:
    """Return the first H1 title, stripping any `ADR-X:` prefix."""
    for line in text.splitlines():
        if line.startswith("# "):
            heading = line[2:].strip()
            _, _, after_colon = heading.partition(":")
            return after_colon.strip() or heading
    return ""


def _iter_foundation_adr_files(project_root: Path) -> Iterable[Path]:
    foundation_root = project_root / "docs" / "design" / "adr" / "foundation"
    if not foundation_root.is_dir():
        return []
    return sorted(foundation_root.glob("*/ADR-*.md"))


def _count_insights_signal(project_root: Path, adr_id: str) -> tuple[int, int]:
    """Return (insights_count, ghi_count) mined from the insights stream."""
    insights_path = project_root / ".gzkit" / "insights" / "agent-insights.jsonl"
    if not insights_path.is_file():
        return 0, 0
    insight_count = 0
    ghi_count = 0
    ghi_pattern = re.compile(r"GHI\s*#\d+|GHI-\d+", re.IGNORECASE)
    for raw_line in insights_path.read_text(encoding="utf-8").splitlines():
        if adr_id not in raw_line:
            continue
        insight_count += 1
        ghi_count += len(ghi_pattern.findall(raw_line))
    return insight_count, ghi_count


def _count_invariant_mentions(project_root: Path, adr_id: str) -> int:
    """Count occurrences of an ADR id across AGENTS.md and rules surfaces."""
    surfaces: list[Path] = []
    agents_md = project_root / "AGENTS.md"
    if agents_md.is_file():
        surfaces.append(agents_md)
    rules_root = project_root / ".gzkit" / "rules"
    if rules_root.is_dir():
        surfaces.extend(sorted(rules_root.glob("*.md")))
    total = 0
    for surface in surfaces:
        try:
            total += surface.read_text(encoding="utf-8").count(adr_id)
        except OSError:
            continue
    return total


def gather_records(project_root: Path) -> list[dict[str, object]]:
    """Return one record per in-flight foundation ADR with signal counts."""
    records: list[dict[str, object]] = []
    for adr_path in _iter_foundation_adr_files(project_root):
        text = adr_path.read_text(encoding="utf-8")
        frontmatter = _parse_simple_frontmatter(text)
        status = frontmatter.get("status", "")
        if status not in _IN_FLIGHT_STATUSES:
            continue
        adr_id = frontmatter.get("id", "")
        prefix_match = _FOUNDATION_SHORT_ID_PREFIX.match(adr_id) if adr_id else None
        adr_short = prefix_match.group(1) if prefix_match else ""
        if not _FOUNDATION_ID_PATTERN.match(adr_short):
            continue
        title = _extract_title(text)
        insight_count, ghi_count = _count_insights_signal(project_root, adr_short)
        invariant_mentions = _count_invariant_mentions(project_root, adr_short)
        records.append(
            {
                "id": adr_short,
                "status": status,
                "title": title,
                "path": adr_path.relative_to(project_root).as_posix(),
                "insight_count": insight_count,
                "ghi_count": ghi_count,
                "invariant_mentions": invariant_mentions,
                "signal_total": insight_count + ghi_count + invariant_mentions,
            }
        )
    return records


def _validate_rank_input(payload: dict[str, object], known_ids: set[str]) -> dict[str, list]:
    """Reject any agent-supplied prose fields; enforce structural schema."""
    rankings_raw = payload.get("rankings", [])
    if not isinstance(rankings_raw, list):
        raise RankingsNotListError
    allowed_severity = {"urgent", "next-quarter", "latent"}
    rankings: list[dict[str, str]] = []
    for entry in rankings_raw:
        if not isinstance(entry, dict):
            raise RankingEntryNotObjectError(entry)
        extra_keys = set(entry) - {"id", "severity"}
        if extra_keys:
            raise RankingForbiddenKeysError(entry.get("id"), extra_keys)
        adr_id = entry.get("id")
        severity = entry.get("severity")
        if not isinstance(adr_id, str) or adr_id not in known_ids:
            raise RankingUnknownIdError(adr_id)
        if not isinstance(severity, str) or severity not in allowed_severity:
            raise RankingSeverityError(adr_id, severity, allowed_severity)
        rankings.append({"id": adr_id, "severity": severity})
    reclassify_raw = payload.get("reclassify_foundation", [])
    if not isinstance(reclassify_raw, list):
        raise ReclassifyNotListError
    reclassify: list[dict[str, str]] = []
    for entry in reclassify_raw:
        if not isinstance(entry, dict):
            raise ReclassifyEntryNotObjectError
        extra_keys = set(entry) - {"id", "reclassify"}
        if extra_keys:
            raise ReclassifyForbiddenKeysError(extra_keys)
        adr_id = entry.get("id")
        reclassify_value = entry.get("reclassify")
        if not isinstance(adr_id, str) or not _ADR_ID_PATTERN.match(adr_id):
            raise ReclassifyInvalidIdError(adr_id)
        if reclassify_value != "foundation":
            raise ReclassifyTargetError(adr_id)
        reclassify.append({"id": adr_id, "reclassify": "foundation"})
    return {"rankings": rankings, "reclassify_foundation": reclassify}


def render_rank(records: list[dict[str, object]], rank_input: dict[str, list]) -> str:
    """Render the deterministic markdown deliverable."""
    title_by_id = {str(record["id"]): str(record["title"]) for record in records}
    lines: list[str] = ["# Foundation Triage — Recommended Order", ""]
    rankings = rank_input["rankings"]
    if rankings:
        for index, entry in enumerate(rankings, start=1):
            adr_id = entry["id"]
            severity = entry["severity"]
            title = title_by_id.get(adr_id, "(title unavailable)")
            lines.append(f"{index}. [{severity}] {adr_id}: {title}")
    else:
        lines.append("_No foundations ranked for this pass._")
    reclassify = rank_input["reclassify_foundation"]
    if reclassify:
        lines.extend(["", "## Reclassification candidates", ""])
        for entry in reclassify:
            lines.append(f"- {entry['id']} → foundation")
    lines.append("")
    return "\n".join(lines)


def _parse_args(argv: list[str]) -> argparse.Namespace:
    parser = argparse.ArgumentParser(
        prog="gz-foundation-triage",
        description="Gather in-flight foundation ADRs and render the rank.",
    )
    parser.add_argument(
        "--format",
        choices=("json", "rank"),
        default="json",
        help="json: emit Step-1 records; rank: render Step-3 deliverable from --rank-input.",
    )
    parser.add_argument(
        "--rank-input",
        type=Path,
        default=None,
        help="Path to the agent's rank-input JSON file (required for --format rank).",
    )
    parser.add_argument(
        "--project-root",
        type=Path,
        default=None,
        help="Override the resolved project root (defaults to git toplevel).",
    )
    return parser.parse_args(argv)


def main(argv: list[str] | None = None) -> int:
    args = _parse_args(argv if argv is not None else sys.argv[1:])
    project_root = args.project_root or _project_root_from_script(Path(__file__))
    records = gather_records(project_root)
    if args.format == "json":
        json.dump(records, sys.stdout, indent=2, sort_keys=True)
        sys.stdout.write("\n")
        return 0
    if args.rank_input is None:
        raise RankInputPathRequiredError
    try:
        payload = json.loads(args.rank_input.read_text(encoding="utf-8"))
    except (OSError, json.JSONDecodeError) as exc:
        raise RankInputReadError(exc) from exc
    known_ids = {str(record["id"]) for record in records}
    validated = _validate_rank_input(payload, known_ids)
    sys.stdout.write(render_rank(records, validated))
    return 0


if __name__ == "__main__":
    sys.exit(main())
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall