github-task-protocol 1.0.1__py3-none-any.whl

github_task_protocol-1.0.1.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: github-task-protocol
+Version: 1.0.1
+Summary: Reconstruct AI coding task state from GitHub Issue records
+Requires-Python: >=3.11
+License-Expression: MIT
+License-File: LICENSE
+Project-URL: Repository, https://github.com/shinya0x00/github-task-protocol
+Description-Content-Type: text/markdown
+
+# GitHub Task Protocol
+
+GTPは、AIへ実装を任せても、人間が目的・変更範囲・現在地・根拠・未確認事項を理解し、停止・再開・やり直し・mergeの判断を手放さないための小さなprotocolです。
+
+> 作業はAIに任せる。判断は手放さない。
+
+AIの説明だけを信じるのではなく、GitHub Issue上のRecordと、実際のbranch・PR・commit・Check Runからtask stateを再構成します。GTP自身は変更、完了、mergeの権限を与えません。
+
+## 導入は3手順
+
+1. [`GTP.md`](GTP.md)を導入先repositoryのrootへコピーする。
+2. 下の共通adapter文を、agentが必ず読む文書へ1段落追加する。
+3. taskごとにGitHub Issueを1件作り、agentへそのIssue URLを渡す。
+
+共通adapter文:
+
+> このrepositoryはrootの`GTP.md`をtask protocolの唯一の正本とする。GitHub Issue URLを受け取ったら、Issue commentをServer Orderで読み、4 Record、6 state、7 halt reasonに従って既存branch・PR・次のprotocol actionを再構成する。Recordを推測、編集、独自拡張せず、矛盾時は原因URLを示して止まり、取得不能はhaltと混同しない。GTPの表示やRecordは変更・完了・mergeの権限を与えない。
+
+配置例は次のとおりです。runtimeごとに異なる指示を作る必要はありません。
+
+- Codex: `AGENTS.md`
+- Claude Code: `CLAUDE.md`または`AGENTS.md`
+- Cursor: `AGENTS.md`または`.cursor/rules/gtp.md`
+
+## 4つのRecord
+
+| Record | 平易な意味 |
+|---|---|
+| `contract` | 目的、変更してよい範囲、完了条件を固定する |
+| `start` | Contractと唯一の作業branchを結び付ける |
+| `done` | PRのsource headと、条件ごとのEvidenceを提示する |
+| `stop` | 完了を主張せず中止し、必要なら後継Issueを示す |
+
+RecordはIssue commentへ人向け要約を先に、機械用JSONを折りたたんで記録します。1 Issue = 1 branch = 1 PRです。
+
+## 6つのstate
+
+| state | 平易な意味 |
+|---|---|
+| `unmanaged` | 有効なContractがない |
+| `ready` | ContractはあるがStart前 |
+| `in_progress` | 作業中、またはDone提示後のmerge待ち |
+| `halt` | 特定transitionを矛盾や不適合のため進められない |
+| `done` | Doneのsource headとEvidenceを持つPRがnative mergeされた |
+| `stopped` | Stopにより、このIssueでの作業を終了した |
+
+GitHub情報を完全に取得できない場合はstateを推測しません。これは`halt`ではなくAcquisition Errorです。
+
+## CLIは任意の検証器
+
+人間がGTPを使うためにCLIをinstallする必要はありません。`gtp`はagentや自動検査がRecordと現在stateを確認するための、runtime dependency 0の任意toolです。
+
+CLIはPyPI公開後、固定versionを指定して実行できます。GTPを使うだけならCLIのinstallは不要です。
+
+```console
+uvx --from github-task-protocol==1.0.1 gtp status <issue-url>
+uvx --from github-task-protocol==1.0.1 gtp check <comment.md>
+```
+
+- `status`はGitHubへGETだけを行い、日本語6項目の後にmachine JSONを出します。
+- `check`は投稿前のMarkdown comment全文をoffline検査します。Issue上でもvalidだとは主張しません。
+- exit code、緑色のCheck Run、Evidence URLは、変更やmergeの許可ではありません。
+
+## 仕様と判断記録
+
+protocolの唯一の正本は400行以内の[`GTP.md`](GTP.md)です。Record作成やstate判断に、他の文書は必要ありません。
+
+[`DECISIONS.md`](DECISIONS.md)は、設計変更の理由と履歴です。`GTP.md`と意味が衝突する場合は`GTP.md`を優先します。
+
+実GitHubで観測した引き継ぎ結果は[`acceptance/level0/`](acceptance/level0/)にあります。これは仕様の代わりではありません。
+
+## GTPが証明しないこと
+
+GTPは、actor本人性、credential安全性、コード品質そのもの、Evidence内容の真実性を証明しません。filesystem削除や本番database操作を物理的に防ぐものでもありません。
+
+サンドボックス、最小権限、不可逆操作前の確認、reviewと組み合わせてください。最終的な受理は、人間がPRとEvidenceを読み、GitHubのnative mergeで判断します。
+
+License: [MIT](LICENSE)

github_task_protocol-1.0.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+gtp/__init__.py,sha256=p2yfQm17fjTB7nHssAmxA-IfIMg5gIUIfUsc6HA5gwc,58
+gtp/__main__.py,sha256=D31U8_ux95qF64EQ8ReT25nabzxh7ped5avpobXz_bM,49
+gtp/carrier.py,sha256=K4Wi1BGlFZ87VuRYa6CYC-oOuGnEPsFw5-2EkDWAbno,4039
+gtp/cli.py,sha256=OSmVwjr9GiBqBUY64i2VpFV9putlCKGCrfeL_40laUU,1721
+gtp/github.py,sha256=zK4HZ-yATvhoN03j91RYnVZLWaHJT4VyhUVCK3I-75w,8591
+gtp/model.py,sha256=0CnS7k0bMPn3Bw4voZGT-Jgvez65JX6X_hpCeeyyl4Y,2443
+gtp/presentation.py,sha256=F50zagAcedp4xyRIuAS-CKu2s6JXrarhAglnPiT_uzM,17347
+gtp/reducer.py,sha256=YuEq9ylDfkuYGLEa2YEM9PaUOrhxWY3HnU_p5rMK8G0,6997
+gtp/schema.py,sha256=Jjltq80E8HjaUBPWoQJ_YwRM-Lkm85rCaHuv10sB0Sg,7768
+gtp/status.py,sha256=PlubWkx6WB1uVuf5cgSklVjVXlrqoViSHoks7m6v8LA,21434
+gtp/urls.py,sha256=CxheRZ4ND__RMZx-cejSMqk5tCu6aaoin6g3Q_RK2i8,3332
+github_task_protocol-1.0.1.dist-info/METADATA,sha256=yxHr1cvH9lYHwvHr4F6RsxzpdCE7KvzgF27N4bUW0fQ,4687
+github_task_protocol-1.0.1.dist-info/WHEEL,sha256=5CJ4bbElW8cq_GDpNSLjMgfb15S72ImTOLq9c70uj1Q,106
+github_task_protocol-1.0.1.dist-info/entry_points.txt,sha256=ULDQmE66x4_NxwQH1Ru9cEVOJMEUBvT27g2a5FcDrAo,37
+github_task_protocol-1.0.1.dist-info/licenses/LICENSE,sha256=yvK8Xx5r58kF13JNYhXfeRf9IAY9rm-jS3THRU0ttJY,1067
+github_task_protocol-1.0.1.dist-info/RECORD,,

github_task_protocol-1.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: github-task-protocol.build_backend
+Root-Is-Purelib: true
+Tag: py3-none-any
+

github_task_protocol-1.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gtp = gtp.cli:main

github_task_protocol-1.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shinya0x00
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gtp/__init__.py

@@ -0,0 +1,3 @@
+"""GitHub Task Protocol reader."""
+
+__version__ = "1.0.1"

gtp/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+
+raise SystemExit(main())

gtp/carrier.py

@@ -0,0 +1,107 @@
+"""Exact GTP Carrier classifier shared by check and status."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import unicodedata
+from typing import Any
+
+from .schema import strict_json_loads, validate_record
+
+
+MARKER = "<!-- gtp-record:v1 -->"
+DETAILS_OPEN = "<details><summary>記録(JSON)</summary>"
+DETAILS_CLOSE = "</details>"
+JSON_OPEN = "```json"
+JSON_CLOSE = "```"
+
+
+@dataclass(frozen=True)
+class CarrierResult:
+    recognized: bool
+    schema_valid: bool | None
+    record: dict[str, Any] | None
+    errors: list[dict[str, str]]
+
+    def projection(self) -> dict[str, Any]:
+        result: dict[str, Any] = {
+            "recognized": self.recognized,
+            "schema_valid": self.schema_valid,
+            "contextual_checks": "not_run",
+        }
+        if self.errors:
+            result["errors"] = self.errors
+        return result
+
+
+def _blank(line: str) -> bool:
+    return not line.strip()
+
+
+def classify_carrier(body: str) -> CarrierResult:
+    lines = body.split("\n")
+    recognized = any(line == MARKER for line in lines)
+    if not recognized:
+        return CarrierResult(False, None, None, [])
+
+    nonblank = [index for index, line in enumerate(lines) if not _blank(line)]
+    format_errors: list[dict[str, str]] = []
+    if len(nonblank) < 7:
+        format_errors.append({"code": "invalid_carrier", "path": "$"})
+        return CarrierResult(True, False, None, format_errors)
+
+    marker_index, summary_index = nonblank[0], nonblank[1]
+    summary = lines[summary_index]
+    if (
+        not summary
+        or summary != summary.strip()
+        or any(unicodedata.category(char) == "Cc" for char in summary)
+    ):
+        format_errors.append({"code": "invalid_summary", "path": "$.summary"})
+    if lines[marker_index] != MARKER:
+        format_errors.append({"code": "invalid_marker_position", "path": "$.marker"})
+
+    details_open_candidates = [index for index in nonblank if lines[index] == DETAILS_OPEN]
+    details_close_candidates = [index for index in nonblank if lines[index] == DETAILS_CLOSE]
+    if len(details_open_candidates) != 1 or len(details_close_candidates) != 1:
+        format_errors.append({"code": "invalid_details_wrapper", "path": "$.details"})
+        return CarrierResult(True, False, None, format_errors)
+
+    opening_candidates = [index for index in nonblank if lines[index] == JSON_OPEN]
+    closing_candidates = [index for index in nonblank if lines[index] == JSON_CLOSE]
+    if len(opening_candidates) != 1 or len(closing_candidates) != 1:
+        format_errors.append({"code": "invalid_json_fence", "path": "$.fence"})
+        return CarrierResult(True, False, None, format_errors)
+
+    details_open = details_open_candidates[0]
+    details_close = details_close_candidates[0]
+    opening = opening_candidates[0]
+    closing = closing_candidates[0]
+    expected_prefix = [marker_index, summary_index, details_open, opening]
+    expected_suffix = [closing, details_close]
+    if (
+        nonblank[:4] != expected_prefix
+        or nonblank[-2:] != expected_suffix
+        or not (marker_index < summary_index < details_open < opening < closing < details_close)
+    ):
+        format_errors.append({"code": "invalid_carrier_layout", "path": "$"})
+        return CarrierResult(True, False, None, format_errors)
+
+    required_spacing = (
+        summary_index == marker_index + 1
+        and details_open == summary_index + 2
+        and opening == details_open + 2
+        and details_close == closing + 2
+    )
+    if not required_spacing:
+        format_errors.append({"code": "invalid_carrier_spacing", "path": "$"})
+    if format_errors:
+        return CarrierResult(True, False, None, format_errors)
+
+    value, parse_errors = strict_json_loads("\n".join(lines[opening + 1 : closing]))
+    if parse_errors:
+        return CarrierResult(True, False, None, parse_errors)
+    schema_errors = validate_record(value)
+    if schema_errors:
+        return CarrierResult(True, False, None, schema_errors)
+    return CarrierResult(True, True, value, [])

gtp/cli.py

@@ -0,0 +1,52 @@
+"""GTP command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+from . import __version__
+from .carrier import classify_carrier
+from .github import GitHubClient
+from .presentation import present_check, present_input_error, present_status
+from .status import evaluate_issue
+
+
+def _emit(lines: list[str], value: object) -> None:
+    for line in lines:
+        sys.stdout.write(f"{line}\n")
+    json.dump(value, sys.stdout, ensure_ascii=False, sort_keys=True, indent=2)
+    sys.stdout.write("\n")
+
+
+def _check(path: str) -> int:
+    try:
+        body = Path(path).read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as error:
+        _emit(*present_input_error(str(error)))
+        return 2
+    result = classify_carrier(body)
+    _emit(*present_check(result))
+    return 0 if result.recognized and result.schema_valid else 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="gtp")
+    parser.add_argument("--version", action="version", version=__version__)
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    check = subparsers.add_parser("check", help="validate one complete Markdown comment")
+    check.add_argument("comment")
+    status = subparsers.add_parser("status", help="reconstruct one GitHub Issue state")
+    status.add_argument("issue_url")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.command == "check":
+        return _check(args.comment)
+    result = evaluate_issue(GitHubClient(), args.issue_url)
+    _emit(*present_status(result))
+    return 0 if result.state is not None else 2

gtp/github.py

@@ -0,0 +1,214 @@
+"""Read-only GitHub REST adapter for GTP status."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.parse import quote, urlencode, urlsplit
+from urllib.request import HTTPRedirectHandler, Request, build_opener
+
+from .model import Comment
+
+
+class AcquisitionError(RuntimeError):
+    def __init__(self, resource: str, message: str, status: int | None = None):
+        super().__init__(message)
+        self.resource = resource
+        self.status = status
+
+
+def _origin(url: str) -> tuple[str, str, int | None]:
+    parsed = urlsplit(url)
+    return parsed.scheme, parsed.hostname or "", parsed.port
+
+
+def _validate_api_url(url: str) -> None:
+    try:
+        parsed = urlsplit(url)
+    except ValueError as error:
+        raise AcquisitionError(url, "invalid GitHub API URL") from error
+    if (
+        parsed.scheme != "https"
+        or parsed.hostname != "api.github.com"
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.port is not None
+        or parsed.fragment
+    ):
+        raise AcquisitionError(url, "GitHub API host is not allowed")
+
+
+class _SafeRedirectHandler(HTTPRedirectHandler):
+    def redirect_request(self, request, fp, code, msg, headers, newurl):
+        redirected = super().redirect_request(request, fp, code, msg, headers, newurl)
+        if redirected is not None and _origin(request.full_url) != _origin(newurl):
+            redirected.remove_header("Authorization")
+            redirected.unredirected_hdrs.pop("Authorization", None)
+        return redirected
+
+
+_OPENER = build_opener(_SafeRedirectHandler())
+
+
+def _open(request: Request, timeout: int):
+    return _OPENER.open(request, timeout=timeout)
+
+
+class GitHubClient:
+    api_root = "https://api.github.com"
+
+    def __init__(self, token: str | None = None) -> None:
+        self.token = token if token is not None else os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+
+    def _request(self, url: str) -> tuple[Any, dict[str, str]]:
+        _validate_api_url(url)
+        headers = {
+            "Accept": "application/vnd.github+json",
+            "Cache-Control": "no-cache",
+            "User-Agent": "github-task-protocol/1.0",
+            "X-GitHub-Api-Version": "2022-11-28",
+        }
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        request = Request(url, headers=headers, method="GET")
+        try:
+            with _open(request, timeout=30) as response:
+                final_url = response.geturl()
+                if isinstance(final_url, str):
+                    _validate_api_url(final_url)
+                data = json.loads(response.read().decode("utf-8"))
+                return data, {key.lower(): value for key, value in response.headers.items()}
+        except HTTPError as error:
+            raise AcquisitionError(url, f"GitHub API returned HTTP {error.code}", error.code) from error
+        except (URLError, TimeoutError, UnicodeError, json.JSONDecodeError) as error:
+            raise AcquisitionError(url, str(error)) from error
+
+    def _get(self, path: str, query: dict[str, str] | None = None) -> Any:
+        url = f"{self.api_root}{path}"
+        if query:
+            url = f"{url}?{urlencode(query)}"
+        return self._request(url)[0]
+
+    def _pages(self, path: str, query: dict[str, str] | None = None) -> list[Any]:
+        url = f"{self.api_root}{path}"
+        params = dict(query or {})
+        params.setdefault("per_page", "100")
+        url = f"{url}?{urlencode(params)}"
+        values: list[Any] = []
+        while url:
+            data, headers = self._request(url)
+            if not isinstance(data, list):
+                raise AcquisitionError(url, "expected a JSON array")
+            values.extend(data)
+            url = _next_link(headers.get("link", ""))
+        return values
+
+    def repository(self, owner: str, repo: str) -> dict[str, Any]:
+        resource = self._get(f"/repos/{quote(owner)}/{quote(repo)}")
+        if not isinstance(resource, dict) or not isinstance(resource.get("id"), int):
+            raise AcquisitionError(
+                f"{self.api_root}/repos/{quote(owner)}/{quote(repo)}",
+                "repository identity missing",
+            )
+        return resource
+
+    def issue(self, owner: str, repo: str, number: int) -> dict[str, Any]:
+        resource = self._get(f"/repos/{quote(owner)}/{quote(repo)}/issues/{number}")
+        if (
+            not isinstance(resource, dict)
+            or not isinstance(resource.get("id"), int)
+            or not isinstance(resource.get("created_at"), str)
+            or not isinstance(resource.get("updated_at"), str)
+        ):
+            raise AcquisitionError(
+                f"{self.api_root}/repos/{quote(owner)}/{quote(repo)}/issues/{number}",
+                "issue snapshot fields missing",
+            )
+        return resource
+
+    def comments(self, owner: str, repo: str, number: int) -> list[Comment]:
+        data = self._pages(
+            f"/repos/{quote(owner)}/{quote(repo)}/issues/{number}/comments",
+            {"sort": "created", "direction": "asc"},
+        )
+        comments: list[Comment] = []
+        for item in data:
+            if (
+                not isinstance(item, dict)
+                or not isinstance(item.get("id"), int)
+                or not isinstance(item.get("html_url"), str)
+                or not isinstance(item.get("created_at"), str)
+                or not isinstance(item.get("updated_at"), str)
+                or not isinstance(item.get("user"), dict)
+                or not isinstance(item["user"].get("login"), str)
+            ):
+                raise AcquisitionError(
+                    f"{self.api_root}/repos/{quote(owner)}/{quote(repo)}/issues/{number}/comments",
+                    "comment snapshot entry is incomplete",
+                )
+            body = item.get("body")
+            if body is not None and not isinstance(body, str):
+                raise AcquisitionError(item["html_url"], "comment body is not text")
+            comments.append(
+                Comment(
+                    id=item["id"],
+                    url=item["html_url"],
+                    body=body or "",
+                    created_at=item["created_at"],
+                    updated_at=item["updated_at"],
+                    github_login=item["user"]["login"],
+                )
+            )
+        return comments
+
+    def branch(self, owner: str, repo: str, branch: str) -> dict[str, Any] | None:
+        try:
+            return self._get(f"/repos/{quote(owner)}/{quote(repo)}/branches/{quote(branch, safe='')}")
+        except AcquisitionError as error:
+            if error.status == 404:
+                return None
+            raise
+
+    def pull_requests(self, owner: str, repo: str, branch: str) -> list[dict[str, Any]]:
+        resources = self._pages(
+            f"/repos/{quote(owner)}/{quote(repo)}/pulls",
+            {"state": "all", "head": f"{owner}:{branch}"},
+        )
+        if not all(isinstance(item, dict) for item in resources):
+            raise AcquisitionError(
+                f"{self.api_root}/repos/{quote(owner)}/{quote(repo)}/pulls",
+                "pull request collection entry is incomplete",
+            )
+        return resources
+
+    def pull_request(self, owner: str, repo: str, number: int) -> dict[str, Any]:
+        resource = self._get(f"/repos/{quote(owner)}/{quote(repo)}/pulls/{number}")
+        if not isinstance(resource, dict):
+            raise AcquisitionError(
+                f"{self.api_root}/repos/{quote(owner)}/{quote(repo)}/pulls/{number}",
+                "pull request snapshot is incomplete",
+            )
+        return resource
+
+    def pull_request_files(self, owner: str, repo: str, number: int) -> list[dict[str, Any]]:
+        return self._pages(f"/repos/{quote(owner)}/{quote(repo)}/pulls/{number}/files")
+
+    def check_run(self, owner: str, repo: str, number: int) -> dict[str, Any]:
+        return self._get(f"/repos/{quote(owner)}/{quote(repo)}/check-runs/{number}")
+
+    def artifact(self, owner: str, repo: str, path: str, sha: str) -> dict[str, Any]:
+        return self._get(
+            f"/repos/{quote(owner)}/{quote(repo)}/contents/{quote(path, safe='/')}",
+            {"ref": sha},
+        )
+
+
+def _next_link(header: str) -> str:
+    for value in header.split(","):
+        match = re.match(r'\s*<([^>]+)>;\s*rel="([^"]+)"', value)
+        if match and match.group(2) == "next":
+            return match.group(1)
+    return ""

gtp/model.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Comment:
+    id: int
+    url: str
+    body: str
+    created_at: str
+    updated_at: str
+    github_login: str
+
+
+@dataclass
+class RecordObservation:
+    record: dict[str, Any]
+    comment: Comment
+    aliases: list[Comment] = field(default_factory=list)
+
+    @property
+    def type(self) -> str:
+        return self.record["type"]
+
+    @property
+    def id(self) -> str:
+        return self.record["id"]
+
+    @property
+    def alias_urls(self) -> tuple[str, ...]:
+        return tuple([self.comment.url, *(item.url for item in self.aliases)])
+
+    def add_alias(self, comment: Comment) -> None:
+        self.aliases.append(comment)
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    token: str
+    urls: tuple[str, ...]
+    detail: dict[str, Any] = field(default_factory=dict)
+
+    def projection(self) -> dict[str, Any]:
+        result: dict[str, Any] = {"token": self.token, "urls": list(self.urls)}
+        if self.detail:
+            result["detail"] = self.detail
+        return result
+
+
+@dataclass(frozen=True)
+class SuccessorFact:
+    url: str
+    exists: bool
+    repository_id: int | None = None
+    issue_id: int | None = None
+    created_at: str | None = None
+
+
+@dataclass
+class FoldContext:
+    issue_url: str | None = None
+    issue_id: int | None = None
+    issue_created_at: str | None = None
+    repository_id: int | None = None
+    successors: dict[str, SuccessorFact] = field(default_factory=dict)
+
+
+@dataclass
+class FoldResult:
+    recognized_count: int = 0
+    recognized_comments: list[Comment] = field(default_factory=list)
+    active: dict[str, list[RecordObservation]] = field(
+        default_factory=lambda: {kind: [] for kind in ("contract", "start", "done", "stop")}
+    )
+    observations_by_url: dict[str, RecordObservation] = field(default_factory=dict)
+    ids: dict[str, list[RecordObservation]] = field(default_factory=dict)
+    diagnostics: list[Diagnostic] = field(default_factory=list)
+    started_once: bool = False
+    bound_contract: RecordObservation | None = None
+    bound_start: RecordObservation | None = None
+    terminal_stop: RecordObservation | None = None
+
+
+class IncompleteSnapshotError(ValueError):
+    pass
+
+
+class ContextAcquisitionRequired(ValueError):
+    def __init__(self, resource: str):
+        super().__init__(resource)
+        self.resource = resource