ucp-gen 0.1.0__tar.gz

ucp_gen-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+package-lock.json
+.venv/
+__pycache__/
+.pytest_cache/
+.DS_Store

ucp_gen-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: ucp-gen
+Version: 0.1.0
+Summary: Generate Universal Context Packages (UCP) from real systems. First source: GitHub issues.
+Project-URL: Specification, https://github.com/ucpcore/ucp
+Project-URL: Homepage, https://ucpcore.org
+Author: UCP contributors
+License-Expression: Apache-2.0
+Keywords: context,github,llm,mcp,ucp
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyucp>=0.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ucp-gen
+
+Generate [Universal Context Packages](https://github.com/ucpcore/ucp) from
+real systems — no LLM in the loop. The first supported source is GitHub
+issues: one command turns an issue, its comments, timeline and linked pull
+requests into a validated, provenance-backed `.ucp.json`.
+
+```bash
+pip install ucp-gen
+export GITHUB_TOKEN=...   # optional, raises the API rate limit
+
+# JSON package to a file
+ucp-gen github vercel/next.js#12345 -o task.ucp.json
+
+# canonical LLM rendering, capped at 1500 tokens
+ucp-gen github owner/repo#42 --markdown --token-budget 1500
+
+# include a "what changed since" diff (adds the ucp-temporal profile)
+ucp-gen github owner/repo#42 --since 2026-06-01T00:00:00Z
+```
+
+## What the mapping does
+
+| GitHub | UCP |
+|---|---|
+| issue title / state / assignee | `entity` |
+| first meaningful paragraph of the body | `summary` |
+| state, assignees, milestone, labels, PR states, comment gists | `must_know` claims with salience |
+| merged linked PRs | `decisions` (accepted) |
+| comments with decision markers ("we decided", "let's go with") | `decisions` (proposed) |
+| issue timeline | `history`, and `context_diff` when `--since` is given |
+| linked PRs | `related_objects` |
+| every issue / comment / PR | `sources` entry with URL + content hash |
+
+Every claim cites its sources; every source carries a `sha256` content hash.
+The output always validates against the UCP schema before it is written —
+the generator will fail rather than emit an invalid package.
+
+Feed the result to any UCP consumer, e.g. the reference MCP server:
+
+```bash
+pip install ucp-mcp
+ucp-gen github owner/repo#42 -o ./contexts/task.ucp.json
+ucp-mcp --dir ./contexts   # Cursor / Claude Code now sees the context
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Part of the UCP reference toolchain (Apache 2.0).

ucp_gen-0.1.0/README.md

@@ -0,0 +1,54 @@
+# ucp-gen
+
+Generate [Universal Context Packages](https://github.com/ucpcore/ucp) from
+real systems — no LLM in the loop. The first supported source is GitHub
+issues: one command turns an issue, its comments, timeline and linked pull
+requests into a validated, provenance-backed `.ucp.json`.
+
+```bash
+pip install ucp-gen
+export GITHUB_TOKEN=...   # optional, raises the API rate limit
+
+# JSON package to a file
+ucp-gen github vercel/next.js#12345 -o task.ucp.json
+
+# canonical LLM rendering, capped at 1500 tokens
+ucp-gen github owner/repo#42 --markdown --token-budget 1500
+
+# include a "what changed since" diff (adds the ucp-temporal profile)
+ucp-gen github owner/repo#42 --since 2026-06-01T00:00:00Z
+```
+
+## What the mapping does
+
+| GitHub | UCP |
+|---|---|
+| issue title / state / assignee | `entity` |
+| first meaningful paragraph of the body | `summary` |
+| state, assignees, milestone, labels, PR states, comment gists | `must_know` claims with salience |
+| merged linked PRs | `decisions` (accepted) |
+| comments with decision markers ("we decided", "let's go with") | `decisions` (proposed) |
+| issue timeline | `history`, and `context_diff` when `--since` is given |
+| linked PRs | `related_objects` |
+| every issue / comment / PR | `sources` entry with URL + content hash |
+
+Every claim cites its sources; every source carries a `sha256` content hash.
+The output always validates against the UCP schema before it is written —
+the generator will fail rather than emit an invalid package.
+
+Feed the result to any UCP consumer, e.g. the reference MCP server:
+
+```bash
+pip install ucp-mcp
+ucp-gen github owner/repo#42 -o ./contexts/task.ucp.json
+ucp-mcp --dir ./contexts   # Cursor / Claude Code now sees the context
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Part of the UCP reference toolchain (Apache 2.0).

ucp_gen-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ucp-gen"
+version = "0.1.0"
+description = "Generate Universal Context Packages (UCP) from real systems. First source: GitHub issues."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [{ name = "UCP contributors" }]
+keywords = ["ucp", "llm", "context", "github", "mcp"]
+dependencies = [
+  "pyucp>=0.1.0",
+  "httpx>=0.27",
+]
+
+[project.urls]
+Specification = "https://github.com/ucpcore/ucp"
+Homepage = "https://ucpcore.org"
+
+[project.scripts]
+ucp-gen = "ucp_gen.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ucp_gen"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

ucp_gen-0.1.0/src/ucp_gen/__init__.py

@@ -0,0 +1,6 @@
+"""ucp-gen — generate Universal Context Packages from real systems."""
+from .build import build_package
+
+__version__ = "0.1.0"
+
+__all__ = ["build_package", "__version__"]

ucp_gen-0.1.0/src/ucp_gen/build.py

@@ -0,0 +1,288 @@
+"""Map a GitHub issue bundle to a valid Universal Context Package.
+
+Pure functions only: no network, no clock reads (``now`` is injectable),
+so the whole mapping is testable on fixtures. No LLM in the loop — the
+structure itself carries the meaning; summarization can be layered on top.
+"""
+from __future__ import annotations
+
+import hashlib
+import re
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+SPEC_VERSION = "0.1.0"
+GENERATOR = {"name": "ucp-gen", "version": "0.1.0", "url": "https://github.com/ucpcore/ucp"}
+
+# Comments matching these are surfaced as proposed decisions (cheap heuristic;
+# merged PRs are the reliable "accepted" signal).
+_DECISION_RE = re.compile(
+    r"\b(we (?:decided|agreed|will go with)|decision:|let's go with|going with)\b", re.IGNORECASE
+)
+
+_MAX_HISTORY = 20
+_MAX_COMMENT_CLAIMS = 10
+_EXCERPT_LEN = 280
+
+
+def _hash(text: str) -> str:
+    return "sha256:" + hashlib.sha256((text or "").encode("utf-8")).hexdigest()
+
+
+def _actor(user: Optional[dict]) -> Optional[dict]:
+    if not user:
+        return None
+    return {"id": f"github:{user['login']}", "display_name": user["login"]}
+
+
+def _excerpt(text: Optional[str]) -> Optional[str]:
+    if not text:
+        return None
+    flat = " ".join(text.split())
+    return flat[:_EXCERPT_LEN] + ("…" if len(flat) > _EXCERPT_LEN else "")
+
+
+def _first_paragraph(text: Optional[str], fallback: str) -> str:
+    if not text:
+        return fallback
+    for block in re.split(r"\n\s*\n", text.strip()):
+        cleaned = " ".join(block.split())
+        # Skip pure-markup blocks (images, HTML comments, headers-only).
+        if cleaned and not cleaned.startswith(("<!--", "![", "|")):
+            return cleaned[:600]
+    return fallback
+
+
+def _iso(value: Optional[str]) -> Optional[str]:
+    return value or None
+
+
+def build_package(
+    bundle: dict[str, Any],
+    since: Optional[str] = None,
+    now: Optional[datetime] = None,
+) -> dict[str, Any]:
+    """Build a UCP dict (spec 0.1.0, profile ucp-core) from a GitHub bundle."""
+    owner, repo = bundle["owner"], bundle["repo"]
+    issue = bundle["issue"]
+    comments = bundle.get("comments", [])
+    timeline = bundle.get("timeline", [])
+    pulls = bundle.get("linked_pulls", [])
+    number = issue["number"]
+    full = f"{owner}/{repo}"
+    generated_at = (now or datetime.now(timezone.utc)).isoformat().replace("+00:00", "Z")
+
+    sources: dict[str, dict] = {}
+    sources["issue"] = {
+        "system": "github",
+        "type": "ticket",
+        "title": f"{full}#{number}: {issue['title']}",
+        "url": issue["html_url"],
+        "author": _actor(issue.get("user")),
+        "created_at": _iso(issue.get("created_at")),
+        "updated_at": _iso(issue.get("updated_at")),
+        "content_hash": _hash(issue.get("body") or ""),
+        "retrieved_at": generated_at,
+        "excerpt": _excerpt(issue.get("body")),
+    }
+    for comment in comments:
+        sources[f"comment-{comment['id']}"] = {
+            "system": "github",
+            "type": "comment",
+            "title": f"Comment by {comment['user']['login']}",
+            "url": comment["html_url"],
+            "author": _actor(comment.get("user")),
+            "created_at": _iso(comment.get("created_at")),
+            "content_hash": _hash(comment.get("body") or ""),
+            "retrieved_at": generated_at,
+            "excerpt": _excerpt(comment.get("body")),
+        }
+    for pull in pulls:
+        sources[f"pr-{pull['number']}"] = {
+            "system": "github",
+            "type": "pull_request",
+            "title": f"PR #{pull['number']}: {pull['title']}",
+            "url": pull["html_url"],
+            "author": _actor(pull.get("user")),
+            "created_at": _iso(pull.get("created_at")),
+            "updated_at": _iso(pull.get("updated_at")),
+            "content_hash": _hash(pull.get("body") or ""),
+            "retrieved_at": generated_at,
+            "excerpt": _excerpt(pull.get("body")),
+        }
+
+    # --- must_know: state of the world, highest salience first ---------------
+    must_know: list[dict] = []
+
+    def claim(cid: str, text: str, salience: float, srcs: list[str], **extra: Any) -> None:
+        must_know.append({"id": cid, "text": text, "salience": salience, "sources": srcs, **extra})
+
+    state = issue.get("state", "open")
+    state_text = f"Issue is {state}"
+    if state == "closed" and issue.get("state_reason"):
+        state_text += f" ({issue['state_reason']})"
+    claim("state", state_text, 0.95, ["issue"], kind="status",
+          asserted_at=_iso(issue.get("updated_at")))
+
+    assignees = [a["login"] for a in issue.get("assignees") or []]
+    if assignees:
+        claim("assignees", "Assigned to " + ", ".join(assignees), 0.85, ["issue"], kind="fact")
+    else:
+        claim("assignees", "Nobody is assigned", 0.6, ["issue"], kind="fact")
+
+    if issue.get("milestone"):
+        milestone = issue["milestone"]
+        text = f"Milestone: {milestone['title']}"
+        if milestone.get("due_on"):
+            text += f" (due {milestone['due_on'][:10]})"
+        claim("milestone", text, 0.8, ["issue"], kind="constraint")
+
+    labels = [label["name"] for label in issue.get("labels") or []]
+    if labels:
+        claim("labels", "Labels: " + ", ".join(labels), 0.65, ["issue"], kind="fact")
+
+    for pull in pulls:
+        merged = bool(pull.get("merged_at"))
+        pr_state = "merged" if merged else pull.get("state", "open")
+        claim(
+            f"pr-{pull['number']}-state",
+            f"PR #{pull['number']} \u201c{pull['title']}\u201d is {pr_state}",
+            0.9 if merged else 0.8,
+            [f"pr-{pull['number']}"],
+            kind="status",
+            asserted_at=_iso(pull.get("merged_at") or pull.get("updated_at")),
+        )
+
+    # Recent comments become low-salience claims: newer ⇒ more relevant.
+    recent = sorted(comments, key=lambda c: c.get("created_at") or "", reverse=True)
+    for rank, comment in enumerate(recent[:_MAX_COMMENT_CLAIMS]):
+        body = _excerpt(comment.get("body"))
+        if not body:
+            continue
+        claim(
+            f"comment-{comment['id']}-gist",
+            f"{comment['user']['login']}: {body}",
+            max(0.2, 0.55 - 0.05 * rank),
+            [f"comment-{comment['id']}"],
+            kind="fact",
+            asserted_at=_iso(comment.get("created_at")),
+        )
+
+    # --- decisions ------------------------------------------------------------
+    decisions: list[dict] = []
+    for pull in pulls:
+        if pull.get("merged_at"):
+            decisions.append({
+                "id": f"decision-pr-{pull['number']}",
+                "decision": f"Implemented via PR #{pull['number']}: {pull['title']}",
+                "status": "accepted",
+                "sources": [f"pr-{pull['number']}"],
+                "decided_by": _actor(pull.get("merged_by") or pull.get("user")),
+                "decided_at": _iso(pull.get("merged_at")),
+            })
+    for comment in comments:
+        body = comment.get("body") or ""
+        if _DECISION_RE.search(body):
+            decisions.append({
+                "id": f"decision-comment-{comment['id']}",
+                "decision": _excerpt(body) or "",
+                "status": "proposed",
+                "sources": [f"comment-{comment['id']}"],
+                "decided_by": _actor(comment.get("user")),
+                "decided_at": _iso(comment.get("created_at")),
+            })
+
+    # --- history + context_diff from the timeline ------------------------------
+    history: list[dict] = [{
+        "occurred_at": issue["created_at"],
+        "summary": f"Issue opened by {issue['user']['login']}",
+        "actor": _actor(issue.get("user")),
+        "sources": ["issue"],
+    }]
+    diff_changes: list[dict] = []
+
+    def timeline_summary(event: dict) -> Optional[tuple[str, str]]:
+        kind = event.get("event")
+        actor_login = (event.get("actor") or {}).get("login", "someone")
+        if kind == "labeled":
+            return f"{actor_login} added label \u201c{event['label']['name']}\u201d", "updated"
+        if kind == "unlabeled":
+            return f"{actor_login} removed label \u201c{event['label']['name']}\u201d", "updated"
+        if kind == "assigned":
+            return f"{actor_login} assigned {(event.get('assignee') or {}).get('login', '?')}", "updated"
+        if kind == "closed":
+            return f"{actor_login} closed the issue", "status_changed"
+        if kind == "reopened":
+            return f"{actor_login} reopened the issue", "status_changed"
+        if kind == "milestoned":
+            return f"{actor_login} set milestone \u201c{(event.get('milestone') or {}).get('title', '?')}\u201d", "updated"
+        if kind == "cross-referenced":
+            source_issue = (event.get("source") or {}).get("issue") or {}
+            ref_kind = "PR" if source_issue.get("pull_request") else "issue"
+            return f"Referenced by {ref_kind} #{source_issue.get('number', '?')}", "added"
+        if kind == "commented":
+            return f"{actor_login} commented", "added"
+        return None
+
+    for event in timeline:
+        occurred = event.get("created_at") or event.get("submitted_at")
+        described = timeline_summary(event)
+        if not occurred or not described:
+            continue
+        summary_text, change_type = described
+        history.append({
+            "occurred_at": occurred,
+            "summary": summary_text,
+            "actor": _actor(event.get("actor")),
+            "sources": ["issue"],
+        })
+        if since and occurred > since:
+            diff_changes.append({
+                "type": change_type,
+                "summary": summary_text,
+                "occurred_at": occurred,
+                "actor": _actor(event.get("actor")),
+                "sources": ["issue"],
+            })
+
+    history.sort(key=lambda e: e["occurred_at"])
+    history = history[-_MAX_HISTORY:]
+
+    # --- related objects --------------------------------------------------------
+    related = [{
+        "ref": {"system": "github", "type": "pull_request",
+                "id": f"{full}#{pull['number']}", "url": pull["html_url"]},
+        "title": pull["title"],
+        "relation": "implements" if pull.get("merged_at") else "references",
+        "salience": 0.9 if pull.get("merged_at") else 0.7,
+    } for pull in pulls]
+
+    profiles = ["ucp-core"]
+    package: dict[str, Any] = {
+        "ucp_version": SPEC_VERSION,
+        "id": f"urn:uuid:{uuid.uuid4()}",
+        "generated_at": generated_at,
+        "generator": GENERATOR,
+        "profiles": profiles,
+        "entity": {
+            "ref": {"system": "github", "type": "issue",
+                    "id": f"{full}#{number}", "url": issue["html_url"]},
+            "title": issue["title"],
+            "status": state,
+            **({"assignee": _actor(issue["assignee"])} if issue.get("assignee") else {}),
+        },
+        "summary": {
+            "text": _first_paragraph(issue.get("body"), issue["title"]),
+            "sources": ["issue"],
+        },
+        "must_know": must_know,
+        "decisions": decisions,
+        "history": history,
+        "related_objects": related,
+        "sources": sources,
+    }
+    if since:
+        profiles.append("ucp-temporal")
+        package["context_diff"] = {"since": since, "changes": diff_changes}
+    return package

ucp_gen-0.1.0/src/ucp_gen/cli.py

@@ -0,0 +1,76 @@
+"""CLI: turn a GitHub issue into a validated UCP package.
+
+    ucp-gen github vercel/next.js#12345 -o task.ucp.json
+    ucp-gen github owner/repo#42 --since 2026-06-01T00:00:00Z --markdown
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+
+import ucp
+
+from .build import build_package
+from .github import GitHubError, fetch_issue_bundle
+
+_REF_RE = re.compile(r"^(?P<owner>[\w.-]+)/(?P<repo>[\w.-]+)#(?P<number>\d+)$")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="ucp-gen", description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    gh = sub.add_parser("github", help="generate a UCP from a GitHub issue")
+    gh.add_argument("ref", help="issue reference, e.g. owner/repo#123")
+    gh.add_argument("-o", "--output", help="write the package to this file (default: stdout)")
+    gh.add_argument("--since", help="ISO timestamp: include a context_diff since this moment")
+    gh.add_argument("--token", help="GitHub token (default: $GITHUB_TOKEN / $GH_TOKEN)")
+    gh.add_argument("--markdown", action="store_true",
+                    help="print the canonical LLM rendering instead of JSON")
+    gh.add_argument("--token-budget", type=int, default=None,
+                    help="token budget for --markdown rendering")
+
+    args = parser.parse_args(argv)
+
+    match = _REF_RE.match(args.ref)
+    if not match:
+        parser.error(f"expected owner/repo#number, got: {args.ref}")
+
+    try:
+        bundle = fetch_issue_bundle(
+            match["owner"], match["repo"], int(match["number"]), token=args.token
+        )
+    except GitHubError as exc:
+        print(f"ucp-gen: {exc}", file=sys.stderr)
+        return 1
+
+    data = build_package(bundle, since=args.since)
+
+    # The generator must never emit an invalid package.
+    ucp.validate(data)
+    pkg = ucp.Package.model_validate(data)
+    dangling = pkg.verify_references()
+    if dangling:
+        print(f"ucp-gen: internal error, dangling sources: {dangling}", file=sys.stderr)
+        return 2
+
+    if args.markdown:
+        out = pkg.render(token_budget=args.token_budget)
+    else:
+        out = json.dumps(data, indent=2, ensure_ascii=False)
+
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as fh:
+            fh.write(out + "\n")
+        est = ucp.estimate_tokens(pkg.render())
+        print(f"ucp-gen: wrote {args.output} "
+              f"({len(data['sources'])} sources, ~{est} tokens rendered)", file=sys.stderr)
+    else:
+        print(out)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ucp_gen-0.1.0/src/ucp_gen/github.py

@@ -0,0 +1,96 @@
+"""GitHub REST client: fetches everything needed to build a UCP for an issue.
+
+Network access is confined to this module; ``build.py`` is pure and works
+on the plain-dict bundle returned by :func:`fetch_issue_bundle`.
+"""
+from __future__ import annotations
+
+import os
+from typing import Any, Optional
+
+import httpx
+
+API = "https://api.github.com"
+
+
+class GitHubError(RuntimeError):
+    pass
+
+
+def _client(token: Optional[str] = None) -> httpx.Client:
+    token = token or os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+    headers = {
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+        "User-Agent": "ucp-gen",
+    }
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    return httpx.Client(base_url=API, headers=headers, timeout=30.0, follow_redirects=True)
+
+
+def _get_json(client: httpx.Client, url: str, **params: Any) -> Any:
+    resp = client.get(url, params=params or None)
+    if resp.status_code == 404:
+        raise GitHubError(f"not found: {url}")
+    if resp.status_code == 403 and resp.headers.get("x-ratelimit-remaining") == "0":
+        raise GitHubError("GitHub rate limit exceeded; set GITHUB_TOKEN to raise the limit")
+    resp.raise_for_status()
+    return resp.json()
+
+
+def _paginate(client: httpx.Client, url: str, limit: int = 200) -> list[dict]:
+    items: list[dict] = []
+    page = 1
+    while len(items) < limit:
+        batch = _get_json(client, url, per_page=100, page=page)
+        if not batch:
+            break
+        items.extend(batch)
+        if len(batch) < 100:
+            break
+        page += 1
+    return items[:limit]
+
+
+def fetch_issue_bundle(
+    owner: str, repo: str, number: int, token: Optional[str] = None
+) -> dict[str, Any]:
+    """Fetch an issue with comments, timeline, and linked pull requests.
+
+    Returns a JSON-serializable bundle:
+    ``{"owner", "repo", "issue", "comments", "timeline", "linked_pulls"}``.
+    """
+    with _client(token) as client:
+        base = f"/repos/{owner}/{repo}/issues/{number}"
+        issue = _get_json(client, base)
+        comments = _paginate(client, f"{base}/comments")
+        timeline = _paginate(client, f"{base}/timeline")
+
+        # Cross-referenced PRs show up in the timeline; fetch their real state
+        # (merged / open / closed) because the timeline entry alone lacks it.
+        pull_numbers: list[int] = []
+        for event in timeline:
+            source_issue = (event.get("source") or {}).get("issue") or {}
+            if event.get("event") == "cross-referenced" and source_issue.get("pull_request"):
+                same_repo = (source_issue.get("repository") or {}).get("full_name")
+                if same_repo == f"{owner}/{repo}":
+                    pull_numbers.append(source_issue["number"])
+
+        linked_pulls = []
+        for pull_number in dict.fromkeys(pull_numbers):
+            try:
+                linked_pulls.append(
+                    _get_json(client, f"/repos/{owner}/{repo}/pulls/{pull_number}")
+                )
+            except GitHubError:
+                continue
+
+    return {
+        "owner": owner,
+        "repo": repo,
+        "issue": issue,
+        "comments": comments,
+        "timeline": timeline,
+        "linked_pulls": linked_pulls,
+    }

ucp_gen-0.1.0/tests/fixtures.py

@@ -0,0 +1,72 @@
+"""A realistic GitHub issue bundle (trimmed to the fields ucp-gen reads)."""
+
+
+def user(login: str) -> dict:
+    return {"login": login}
+
+
+BUNDLE = {
+    "owner": "acme",
+    "repo": "rocket",
+    "issue": {
+        "number": 42,
+        "title": "Payment webhook drops events under load",
+        "state": "closed",
+        "state_reason": "completed",
+        "html_url": "https://github.com/acme/rocket/issues/42",
+        "user": user("alice"),
+        "created_at": "2026-06-01T09:00:00Z",
+        "updated_at": "2026-06-20T18:00:00Z",
+        "body": (
+            "When more than ~50 webhook events arrive per second, some are\n"
+            "silently dropped.\n\n"
+            "Steps to reproduce:\n1. Fire 100 events\n2. Count processed"
+        ),
+        "assignee": user("bob"),
+        "assignees": [user("bob")],
+        "labels": [{"name": "bug"}, {"name": "priority:high"}],
+        "milestone": {"title": "v2.1", "due_on": "2026-07-01T00:00:00Z"},
+    },
+    "comments": [
+        {
+            "id": 100,
+            "user": user("bob"),
+            "created_at": "2026-06-02T10:00:00Z",
+            "html_url": "https://github.com/acme/rocket/issues/42#issuecomment-100",
+            "body": "Reproduced. The consumer ack's before processing finishes.",
+        },
+        {
+            "id": 101,
+            "user": user("carol"),
+            "created_at": "2026-06-05T12:00:00Z",
+            "html_url": "https://github.com/acme/rocket/issues/42#issuecomment-101",
+            "body": "We decided to switch to at-least-once delivery with an idempotency key.",
+        },
+    ],
+    "timeline": [
+        {"event": "labeled", "created_at": "2026-06-01T09:05:00Z",
+         "actor": user("alice"), "label": {"name": "bug"}},
+        {"event": "assigned", "created_at": "2026-06-01T09:10:00Z",
+         "actor": user("alice"), "assignee": user("bob")},
+        {"event": "commented", "created_at": "2026-06-02T10:00:00Z", "actor": user("bob")},
+        {"event": "cross-referenced", "created_at": "2026-06-10T08:00:00Z",
+         "actor": user("bob"),
+         "source": {"issue": {"number": 55, "pull_request": {},
+                              "repository": {"full_name": "acme/rocket"}}}},
+        {"event": "closed", "created_at": "2026-06-20T18:00:00Z", "actor": user("bob")},
+    ],
+    "linked_pulls": [
+        {
+            "number": 55,
+            "title": "Make webhook consumer idempotent",
+            "state": "closed",
+            "merged_at": "2026-06-20T17:55:00Z",
+            "merged_by": user("carol"),
+            "html_url": "https://github.com/acme/rocket/pull/55",
+            "user": user("bob"),
+            "created_at": "2026-06-10T08:00:00Z",
+            "updated_at": "2026-06-20T17:55:00Z",
+            "body": "Adds idempotency keys so redelivered events are no-ops.",
+        }
+    ],
+}

ucp_gen-0.1.0/tests/test_build.py

@@ -0,0 +1,93 @@
+import copy
+from datetime import datetime, timezone
+
+import ucp
+
+from ucp_gen import build_package
+
+from .fixtures import BUNDLE
+
+NOW = datetime(2026, 7, 5, 12, 0, 0, tzinfo=timezone.utc)
+
+
+def build(**kwargs):
+    return build_package(copy.deepcopy(BUNDLE), now=NOW, **kwargs)
+
+
+def test_output_is_schema_valid_and_reference_clean():
+    data = build()
+    ucp.validate(data)  # raises on violation
+    pkg = ucp.Package.model_validate(data)
+    assert pkg.verify_references() == []
+
+
+def test_entity_reflects_the_issue():
+    pkg = ucp.Package.model_validate(build())
+    assert pkg.entity.ref.id == "acme/rocket#42"
+    assert pkg.entity.status == "closed"
+    assert pkg.entity.assignee.id == "github:bob"
+
+
+def test_summary_takes_first_meaningful_paragraph():
+    pkg = ucp.Package.model_validate(build())
+    assert pkg.summary.text.startswith("When more than ~50 webhook events")
+    assert pkg.summary.sources == ["issue"]
+
+
+def test_state_claim_has_top_salience():
+    pkg = ucp.Package.model_validate(build())
+    top = max(pkg.must_know, key=lambda c: c.salience or 0)
+    assert top.id == "state"
+    assert "closed" in top.text and "completed" in top.text
+
+
+def test_merged_pr_becomes_accepted_decision():
+    pkg = ucp.Package.model_validate(build())
+    accepted = [d for d in pkg.decisions if d.status == "accepted"]
+    assert len(accepted) == 1
+    assert "PR #55" in accepted[0].decision
+    assert accepted[0].decided_by.id == "github:carol"
+
+
+def test_decision_marker_in_comment_becomes_proposed_decision():
+    pkg = ucp.Package.model_validate(build())
+    proposed = [d for d in pkg.decisions if d.status == "proposed"]
+    assert len(proposed) == 1
+    assert "at-least-once delivery" in proposed[0].decision
+    assert proposed[0].sources == ["comment-101"]
+
+
+def test_every_source_carries_content_hash():
+    data = build()
+    assert len(data["sources"]) == 4  # issue + 2 comments + 1 PR
+    for source in data["sources"].values():
+        assert source["content_hash"].startswith("sha256:")
+
+
+def test_history_is_chronological():
+    pkg = ucp.Package.model_validate(build())
+    stamps = [event.occurred_at for event in pkg.history]
+    assert stamps == sorted(stamps)
+    assert "Issue opened by alice" in pkg.history[0].summary
+
+
+def test_since_produces_context_diff_and_temporal_profile():
+    data = build(since="2026-06-15T00:00:00Z")
+    ucp.validate(data)
+    pkg = ucp.Package.model_validate(data)
+    assert "ucp-temporal" in pkg.profiles
+    summaries = [change.summary for change in pkg.context_diff.changes]
+    assert summaries == ["bob closed the issue"]  # the only event after `since`
+
+
+def test_no_since_means_no_diff():
+    data = build()
+    assert "context_diff" not in data
+    assert data["profiles"] == ["ucp-core"]
+
+
+def test_rendering_fits_budget_and_keeps_core():
+    pkg = ucp.Package.model_validate(build())
+    tight = pkg.render(token_budget=500)
+    assert ucp.estimate_tokens(tight) <= 500
+    assert "Payment webhook drops events" in tight

ucp_gen-0.1.0/tests/test_cli.py

@@ -0,0 +1,38 @@
+import copy
+import json
+
+import pytest
+
+import ucp_gen.cli as cli
+
+from .fixtures import BUNDLE
+
+
+@pytest.fixture(autouse=True)
+def offline_github(monkeypatch):
+    def fake_fetch(owner, repo, number, token=None):
+        assert (owner, repo, number) == ("acme", "rocket", 42)
+        return copy.deepcopy(BUNDLE)
+
+    monkeypatch.setattr(cli, "fetch_issue_bundle", fake_fetch)
+
+
+def test_cli_writes_valid_json(tmp_path, capsys):
+    out = tmp_path / "task.ucp.json"
+    assert cli.main(["github", "acme/rocket#42", "-o", str(out)]) == 0
+    data = json.loads(out.read_text())
+    assert data["ucp_version"] == "0.1.0"
+    assert "sources" in data
+    assert "wrote" in capsys.readouterr().err
+
+
+def test_cli_markdown_mode(capsys):
+    assert cli.main(["github", "acme/rocket#42", "--markdown", "--token-budget", "600"]) == 0
+    output = capsys.readouterr().out
+    assert "Payment webhook drops events" in output
+    assert "{" not in output.splitlines()[0]
+
+
+def test_cli_rejects_bad_ref():
+    with pytest.raises(SystemExit):
+        cli.main(["github", "not-a-ref"])