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

github_task_protocol-1.0.2.dist-info/METADATA

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: github-task-protocol
+Version: 1.0.2
+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の権限を与えません。
+
+task固有の未確認事項は、通常のIssue本文やcommentへ人が読める形で残します。開始前から完了判断に必要な不明点はDone Conditionにし、開始後にContract変更が必要になった場合はStopと後継Issueへ移ります。GTP Recordは自由文の意味を自動評価しないため、`status`はDone提示前にIssueを確認するURLを表示します。
+
+## 推奨: 明示的にsetupを依頼
+
+bare GTP repository URLだけではsetup依頼にもrepository変更のauthorizationにもなりません。URLだけを受け取ったagentは、説明または目的確認に留まり、現在のrepositoryを変更しません。
+
+導入先repositoryを操作中のclean agentへ、変更対象とDraft setup PR作成を明示して依頼します。
+
+```text
+このrepositoryへGTPを導入するDraft setup PRを作ってください。
+GTP repository: https://github.com/shinya0x00/github-task-protocol
+```
+
+この明示依頼を受けたagentは、次の順序でsetupします。
+
+agentが手順を理解できることと、実行中ずっと意図の境界内に留まり続けることは別の能力です。この手順はbranch-first順序で境界逸脱のriskを下げます。GTP単独の強制力はこの手順の受入対象にしません。repository ownerは補完策としてGitHub branch protectionまたはrulesetでdefault branchへの直接pushを拒否し、pull request経由の変更を必須にできます。setup agentは保護設定を変更せず、未設定なら人間へ報告します。
+
+1. GitHubのlatest stable Releaseを取得し、`draft: false`かつ`prerelease: false`を確認する。未公開candidateやmoving `main`は選ばない。
+2. Releaseのtagをcommit SHAまでdereferenceし、選択したtagとexact commit SHAを記録する。
+3. target fileを変更する前にrepositoryのdefault branch名とhead SHAを記録し、そのheadから`gtp/setup-<tag>-<short-sha>` branchを作ってswitchする。現在branchがdefault branchではなくsetup branchであることを確認できなければ停止する。
+4. そのcommitの`GTP.md`だけを`https://raw.githubusercontent.com/shinya0x00/github-task-protocol/<commit-sha>/GTP.md`から取得し、導入先rootへvendorする。既存`GTP.md`とSHA-256が同一なら保持する。内容が異なるfile、別のGTP authority、または既存instructionとの衝突があれば、上書きせず停止して人間へ報告する。
+5. root `AGENTS.md`がなければ作成する。存在する場合は本文を変更・削除せず、下のexact adapterがなければ`## GitHub Task Protocol adapter` heading付きで追記する。既に同じadapterがあれば重複追加しない。
+6. commitとpushはsetup branchだけに行い、default branchへ直接pushしない。push後にdefault branch headを再取得し、setup開始前に記録したSHAから予期せず変化していたら停止して報告する。Draft setup PRのbodyにはrelease tag、exact commit SHA、immutable `GTP.md` URL、変更file、保持した既存instruction、次に必要な人間判断を書く。
+7. 人間がsetup PRをmergeするまで導入完了としません。merge後、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`
+
+## 手動導入
+
+自動setupを使わない場合は、次の3手順で導入できます。
+
+1. latest stable Releaseをexact commitへ固定し、file変更前にdefault branchからsetup用branchを作ってswitchする。
+2. setup branch上で`GTP.md`をrootへコピーし、共通adapter文を既存instructionへ非破壊で追加する。
+3. commitとpushをsetup branchだけに行ってDraft PRを作り、人間が内容を確認してmergeする。
+
+## 4つのRecord
+
+| Record | 平易な意味 |
+|---|---|
+| `contract` | 目的、変更してよい範囲、完了条件を固定する |
+| `start` | Contractと唯一の作業branchを結び付ける |
+| `done` | PRのsource headと、条件ごとのEvidenceを提示する |
+| `stop` | 完了を主張せず中止し、必要なら後継Issueを示す |
+
+RecordはIssue commentへ人向け要約を先に、機械用JSONを折りたたんで記録します。1 Issue = 1 branch = 1 PRです。
+Start branchへrepositoryのdefault branchは指定できません。
+Startより前から存在するPRは、そのtaskのcandidateやDoneとして引き継げません。誤ったStartをStopする場合は、古いPRを対象外として安全に閉じます。
+
+## 6つのstate
+
+| state | 平易な意味 |
+|---|---|
+| `unmanaged` | 有効なContractがない |
+| `ready` | ContractはあるがStart前 |
+| `in_progress` | 作業中、またはDone提示後のmerge待ち |
+| `halt` | 特定transitionを矛盾や不適合のため進められない |
+| `done` | Doneのsource headへEvidence resourceが結び付き、そのPRがnative mergeされた。条件内容の十分性は人がEvidenceを読んで判断する |
+| `stopped` | Stopにより、このIssueでの作業を終了した |
+
+GitHub情報を完全に取得できない場合はstateを推測しません。404だけではresource不在と権限不足を区別できないため、これは`halt`ではなくAcquisition Errorです。
+
+## CLIは任意の検証器
+
+人間がGTPを使うためにCLIをinstallする必要はありません。`gtp`はagentや自動検査がRecordと現在stateを確認するための、runtime dependency 0の任意toolです。
+
+CLIはPyPI公開後、固定versionを指定して実行できます。現在のsource candidateは`1.0.2`であり、公開確認前です。公開済み`1.0.1`はこのcandidateと挙動が異なるため、下記commandは`1.0.2`の公開Evidence取得後に使用します。GTPを使うだけならCLIのinstallは不要です。
+
+```console
+uvx --from github-task-protocol==1.0.2 gtp status <issue-url>
+uvx --from github-task-protocol==1.0.2 gtp check <comment.md>
+```
+
+- `status`はGitHubへGETだけを行い、日本語6項目の後にmachine JSONを出します。Evidenceの存在・種類・状態・source headとの結び付きを検査しますが、完了条件の自然言語上の充足までは自動判定しません。
+- `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.2.dist-info/RECORD

@@ -0,0 +1,16 @@
+gtp/__init__.py,sha256=Mgzlh0-l_XUHLRPtouhrFlM1lX4feMnDUULN0WuIsb0,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=__WJN9-EvzYjVFB56bLAvWsH_alcY6WOQRmYwjwZ6qM,8465
+gtp/model.py,sha256=0CnS7k0bMPn3Bw4voZGT-Jgvez65JX6X_hpCeeyyl4Y,2443
+gtp/presentation.py,sha256=9lfmwcuIo9Ip-CEyrqNtr4Mwh0b6S-HwGjZGbsffRB4,18627
+gtp/reducer.py,sha256=YuEq9ylDfkuYGLEa2YEM9PaUOrhxWY3HnU_p5rMK8G0,6997
+gtp/schema.py,sha256=Jjltq80E8HjaUBPWoQJ_YwRM-Lkm85rCaHuv10sB0Sg,7768
+gtp/status.py,sha256=vJ6J7skWqz1CzBgkYnS1M2ECa0OgSj7GQPLhKiI21c8,32702
+gtp/urls.py,sha256=CxheRZ4ND__RMZx-cejSMqk5tCu6aaoin6g3Q_RK2i8,3332
+github_task_protocol-1.0.2.dist-info/METADATA,sha256=ZLYZol7HPEg54qf7ez1xAoikqxZlqLE8KPVNm7ZTpVU,9005
+github_task_protocol-1.0.2.dist-info/WHEEL,sha256=5CJ4bbElW8cq_GDpNSLjMgfb15S72ImTOLq9c70uj1Q,106
+github_task_protocol-1.0.2.dist-info/entry_points.txt,sha256=ULDQmE66x4_NxwQH1Ru9cEVOJMEUBvT27g2a5FcDrAo,37
+github_task_protocol-1.0.2.dist-info/licenses/LICENSE,sha256=yvK8Xx5r58kF13JNYhXfeRf9IAY9rm-jS3THRU0ttJY,1067
+github_task_protocol-1.0.2.dist-info/RECORD,,

gtp/__init__.py

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

gtp/github.py

@@ -164,13 +164,10 @@ class GitHubClient:
             )
         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 branch(self, owner: str, repo: str, branch: str) -> dict[str, Any]:
+        return self._get(
+            f"/repos/{quote(owner)}/{quote(repo)}/branches/{quote(branch, safe='')}"
+        )
 
     def pull_requests(self, owner: str, repo: str, branch: str) -> list[dict[str, Any]]:
         resources = self._pages(

gtp/presentation.py

@@ -19,6 +19,9 @@ HALT_MESSAGES = {
     "terminal_violation": "terminal stateの前後関係に違反するRecordまたはmergeがあります",
 }
 EVIDENCE_LIMITS = [
+    "Check RunがDone Conditionの内容を十分に検査したこと",
+    "Artifactの内容がDone Conditionを満たすこと",
+    "Issue本文・通常commentに未解決事項がないこと",
     "actor本人性",
     "credential安全性",
     "GitHub外情報を参照しなかったこと",
@@ -50,6 +53,7 @@ def _content(record: dict[str, Any] | None) -> dict[str, Any]:
 
 def _task_context(
     *,
+    issue_url: str,
     state: str | None,
     acquisition_complete: bool,
     contract: dict[str, Any] | None,
@@ -94,12 +98,17 @@ def _task_context(
         not_proven.extend(missing)
         if done is None:
             not_proven.append("Done Claim未提示")
-        elif state == "in_progress":
-            not_proven.append("native merge未確認")
-        elif state == "halt" and not missing:
-            not_proven.append("protocol不適合が未解決")
-        elif state == "stopped":
-            not_proven.append("このIssueは完了を証明せず停止済み")
+        else:
+            if state in {"in_progress", "done"} and not missing:
+                not_proven.append(
+                    "Done Conditionの自然言語上の充足は自動判定していない"
+                )
+            if state == "in_progress":
+                not_proven.append("native merge未確認")
+            elif state == "halt" and not missing:
+                not_proven.append("protocol不適合が未解決")
+            elif state == "stopped":
+                not_proven.append("このIssueは完了を証明せず停止済み")
 
     branch_name = branch.get("name") if isinstance(branch, dict) else None
     if not isinstance(branch_name, str):
@@ -109,6 +118,8 @@ def _task_context(
     return {
         "goal": contract_content.get("goal"),
         "scope": scope if isinstance(scope, list) else [],
+        "handoff_url": issue_url,
+        "handoff_semantics": "Issue本文・通常commentの意味は自動判定しない",
         "branch": branch_name,
         "pr": pr,
         "conditions": conditions,
@@ -205,6 +216,7 @@ def status_projection(result: StatusResult) -> dict[str, Any]:
         "diagnostics": diagnostics,
         "acquisition_errors": result.acquisition_errors,
         "task_context": _task_context(
+            issue_url=result.issue_url,
             state=result.state,
             acquisition_complete=not result.acquisition_errors,
             contract=contract,
@@ -223,11 +235,17 @@ def _plain_summary(machine: dict[str, Any], context: dict[str, Any]) -> list[str
         if state is None
         else "このIssueの完了は確認できません。作業を止めて人が確認してください。"
         if state == "halt"
-        else "このIssueの完了を確認しました。"
+        else (
+            "Done ClaimのEvidence bindingとnative mergeを確認しました。"
+            "条件内容の充足はEvidenceを読んで判断してください。"
+        )
         if state == "done"
         else "このIssueは完了を主張せず終了しています。"
         if state == "stopped"
-        else "完了条件の確認資料はそろっていますが、マージはまだです。"
+        else (
+            "Done ClaimのEvidence bindingを確認しましたが、マージはまだです。"
+            "条件内容の充足はEvidenceを読んで判断してください。"
+        )
         if machine["next_action"] == "await_merge"
         else "このIssueはまだ作業途中です。"
     )
@@ -254,6 +272,9 @@ def _plain_summary(machine: dict[str, Any], context: dict[str, Any]) -> list[str
                 f"  変更してよい場所: {scope_text}",
                 f"  作業場所: branch {context.get('branch') or '未確認'}"
                 f" / PR {context.get('pr') or '未確認'}",
+                "  未確認事項の確認先: "
+                f"{context.get('handoff_url') or machine['issue_url']}"
+                "（Issue本文・通常commentの意味は自動判定していません）",
             ]
         )
 
@@ -274,7 +295,7 @@ def _plain_summary(machine: dict[str, Any], context: dict[str, Any]) -> list[str
     evidence_confirmed = state == "done" or machine["next_action"] == "await_merge"
     if presented:
         lines.append(
-            "  確認できた完了条件:"
+            "  Evidence bindingを確認した条件（条件内容の充足は自動判定していません）:"
             if evidence_confirmed
             else "  記録に確認資料へのリンクがある条件（達成済みとはまだ断定しません）:"
         )
@@ -321,7 +342,10 @@ def _status_text(machine: dict[str, Any]) -> list[str]:
         "post_contract": "目的・変更範囲・完了条件をContractとして記録してください",
         "post_start": "Contractと作業branchをStartで束縛してください",
         "continue_work": "束縛されたbranchで作業を続けてください",
-        "post_done": "完了条件を確認し、source headとEvidenceをDoneで提示してください",
+        "post_done": (
+            "Issue本文・通常commentの未確認事項と完了条件を確認し、"
+            "source headとEvidenceをDoneで提示してください"
+        ),
         "await_merge": "Done ClaimとEvidenceを確認し、人間のnative merge判断を待ってください",
         "inspect_halt": "最初のURLを確認し、記録を推測で補わず人間へ戻してください",
         "none_done": "追加のprotocol actionはありません",
@@ -336,7 +360,7 @@ def _status_text(machine: dict[str, Any]) -> list[str]:
         token = machine["halt_reason"]
         reason = f"{token} — {HALT_MESSAGES.get(token, 'protocol上の矛盾または不適合を確認しました')}"
     elif action == "await_merge":
-        reason = "Done Claimは確認済みですが、native mergeはまだ確認できません"
+        reason = "Done ClaimのEvidence bindingは確認済みですが、native mergeはまだ確認できません"
     elif action == "post_done":
         reason = f"Start、作業branch {branch_name or '（名前不明）'}、PR candidateを確認しました"
     elif action == "continue_work":
@@ -345,7 +369,7 @@ def _status_text(machine: dict[str, Any]) -> list[str]:
         reason = {
             "unmanaged": "有効なContractがありません",
             "ready": "有効なContractがあり、Startはまだありません",
-            "done": "Done Claimのsource head、Evidence、native mergeを確認しました",
+            "done": "Done Claimのsource head、Evidence binding、native mergeを確認しました",
             "stopped": "有効なStop Recordを確認しました",
         }[machine["state"]]
     lines = [

gtp/status.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
+from datetime import datetime, timezone
 from typing import Any
 from urllib.parse import unquote
 
@@ -14,7 +15,7 @@ from .model import (
     RecordObservation,
     SuccessorFact,
 )
-from .reducer import fold_comments, historical_state, successor_refs
+from .reducer import fold_comments, historical_state
 from .urls import parse_github_url
 
 
@@ -96,6 +97,72 @@ def _pr_matches(pr: dict[str, Any], repo_id: int, branch: str) -> bool:
     )
 
 
+def _branch_snapshot_key(
+    branch: dict[str, Any] | None,
+    resource: str,
+) -> tuple[str, str] | None:
+    if branch is None:
+        return None
+    name = branch.get("name")
+    sha = branch.get("commit", {}).get("sha")
+    if not isinstance(name, str) or not isinstance(sha, str):
+        raise AcquisitionError(resource, "branch snapshot fields missing")
+    return name, sha
+
+
+def _pr_snapshot_key(pr: dict[str, Any], resource: str) -> tuple[Any, ...]:
+    number = pr.get("number")
+    url = pr.get("html_url")
+    base = pr.get("base", {})
+    base_repo_id = base.get("repo", {}).get("id")
+    base_ref = base.get("ref")
+    base_sha = base.get("sha")
+    head = pr.get("head", {})
+    head_repo_id = head.get("repo", {}).get("id")
+    head_ref = head.get("ref")
+    head_sha = head.get("sha")
+    merged_at = pr.get("merged_at")
+    state = pr.get("state")
+    changed_files = pr.get("changed_files")
+    if (
+        not isinstance(number, int)
+        or not isinstance(url, str)
+        or not isinstance(base_repo_id, int)
+        or not isinstance(base_ref, str)
+        or not isinstance(base_sha, str)
+        or not isinstance(head_repo_id, int)
+        or not isinstance(head_ref, str)
+        or not isinstance(head_sha, str)
+        or not isinstance(state, str)
+        or (merged_at is not None and not isinstance(merged_at, str))
+        or (
+            changed_files is not None
+            and (not isinstance(changed_files, int) or changed_files < 0)
+        )
+    ):
+        raise AcquisitionError(resource, "pull request snapshot fields missing")
+    return (
+        number,
+        url,
+        base_repo_id,
+        base_ref,
+        base_sha,
+        head_repo_id,
+        head_ref,
+        head_sha,
+        state,
+        merged_at,
+        changed_files,
+    )
+
+
+def _pr_collection_snapshot(
+    prs: list[dict[str, Any]],
+    resource: str,
+) -> tuple[tuple[Any, ...], ...]:
+    return tuple(sorted(_pr_snapshot_key(pr, resource) for pr in prs))
+
+
 def _path_in_scope(path: str, scope: list[str]) -> bool:
     for entry in scope:
         if entry == "." or path == entry or (entry.endswith("/") and path.startswith(entry)):
@@ -115,7 +182,22 @@ def _scope_diagnostics(
     pr_url = pr.get("html_url")
     if not isinstance(number, int) or not isinstance(pr_url, str):
         raise AcquisitionError(anchor_url, "pull request identity missing")
+    listed_key = _pr_snapshot_key(pr, pr_url)
+    detail = client.pull_request(owner, repo, number)
+    detail_key = _pr_snapshot_key(detail, pr_url)
+    if listed_key[:-1] != detail_key[:-1] or (
+        listed_key[-1] is not None and listed_key[-1] != detail_key[-1]
+    ):
+        raise AcquisitionError(pr_url, "pull request changed during acquisition")
+    changed_files = detail_key[-1]
+    if not isinstance(changed_files, int) or changed_files < 0:
+        raise AcquisitionError(pr_url, "pull request changed_files missing")
     files = client.pull_request_files(owner, repo, number)
+    detail_after = client.pull_request(owner, repo, number)
+    if _pr_snapshot_key(detail_after, pr_url) != detail_key:
+        raise AcquisitionError(pr_url, "pull request changed during file acquisition")
+    if len(files) != changed_files:
+        raise AcquisitionError(pr_url, "pull request file collection is incomplete")
     observed_paths: list[str] = []
     for item in files:
         if not isinstance(item, dict) or not isinstance(item.get("filename"), str):
@@ -134,26 +216,42 @@ def _scope_diagnostics(
     return []
 
 
-def _missing_is_mismatch(error: AcquisitionError) -> bool:
-    return error.status == 404
+def _github_time(value: object, resource: str, field: str) -> datetime:
+    if not isinstance(value, str):
+        raise AcquisitionError(resource, f"{field} missing")
+    try:
+        observed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError as error:
+        raise AcquisitionError(resource, f"{field} invalid") from error
+    if observed.tzinfo is None:
+        raise AcquisitionError(resource, f"{field} timezone missing")
+    return observed.astimezone(timezone.utc)
+
+
+def _pr_not_after_start(
+    pr: dict[str, Any],
+    start: RecordObservation,
+    resource: str,
+) -> bool:
+    created_time = _github_time(
+        pr.get("created_at"), resource, "pull request created_at"
+    )
+    start_time = _github_time(
+        start.comment.created_at, start.comment.url, "Start created_at"
+    )
+    return created_time <= start_time
 
 
 def _successor_context(
     client: GitHubClient,
-    comments: list[Any],
+    refs: list[str],
 ) -> dict[str, SuccessorFact]:
     facts: dict[str, SuccessorFact] = {}
-    for url in successor_refs(comments):
+    for url in refs:
         parsed = parse_github_url(url, "issue")
         assert parsed is not None
         repository = client.repository(parsed.owner, parsed.repo)
-        try:
-            issue = client.issue(parsed.owner, parsed.repo, parsed.number or 0)
-        except AcquisitionError as error:
-            if _missing_is_mismatch(error):
-                facts[url] = SuccessorFact(url, False, repository_id=repository.get("id"))
-                continue
-            raise
+        issue = client.issue(parsed.owner, parsed.repo, parsed.number or 0)
         facts[url] = SuccessorFact(
             url,
             "pull_request" not in issue,
@@ -189,28 +287,16 @@ def _live_evidence(
             if parsed.sha != head_sha:
                 diagnostics.append(_diagnostic("stale_evidence", done.comment.url, url))
                 continue
-            try:
-                resource = client.artifact(
-                    parsed.owner,
-                    parsed.repo,
-                    unquote(parsed.path or "", encoding="utf-8", errors="strict"),
-                    head_sha,
-                )
-            except AcquisitionError as error:
-                if _missing_is_mismatch(error):
-                    diagnostics.append(_diagnostic("invalid_evidence", done.comment.url, url))
-                    continue
-                raise
+            resource = client.artifact(
+                parsed.owner,
+                parsed.repo,
+                unquote(parsed.path or "", encoding="utf-8", errors="strict"),
+                head_sha,
+            )
             if not isinstance(resource, dict) or resource.get("type") != "file":
                 diagnostics.append(_diagnostic("invalid_evidence", done.comment.url, url))
         else:
-            try:
-                resource = client.check_run(parsed.owner, parsed.repo, parsed.number or 0)
-            except AcquisitionError as error:
-                if _missing_is_mismatch(error):
-                    diagnostics.append(_diagnostic("invalid_evidence", done.comment.url, url))
-                    continue
-                raise
+            resource = client.check_run(parsed.owner, parsed.repo, parsed.number or 0)
             if resource.get("head_sha") != head_sha:
                 diagnostics.append(_diagnostic("stale_evidence", done.comment.url, url))
             elif resource.get("status") != "completed":
@@ -228,6 +314,7 @@ def _evaluate_done(
     client: GitHubClient,
     repo_id: int,
     branch_name: str,
+    start: RecordObservation,
     contract: RecordObservation,
     done: RecordObservation,
 ) -> _DoneLive:
@@ -235,17 +322,13 @@ def _evaluate_done(
     pr_url = parse_github_url(done.record["pr_ref"], "pr")
     assert pr_url is not None
     pr_repo = client.repository(pr_url.owner, pr_url.repo)
-    try:
-        pr = client.pull_request(pr_url.owner, pr_url.repo, pr_url.number or 0)
-    except AcquisitionError as error:
-        if _missing_is_mismatch(error):
-            result.diagnostics.append(
-                _diagnostic("invalid_binding", done.comment.url, done.record["pr_ref"])
-            )
-            return result
-        raise
+    pr = client.pull_request(pr_url.owner, pr_url.repo, pr_url.number or 0)
     result.pr = pr
-    if not _repo_matches(pr_repo, repo_id) or not _pr_matches(pr, repo_id, branch_name):
+    if (
+        not _repo_matches(pr_repo, repo_id)
+        or not _pr_matches(pr, repo_id, branch_name)
+        or _pr_not_after_start(pr, start, done.record["pr_ref"])
+    ):
         result.diagnostics.append(
             _diagnostic("invalid_binding", done.comment.url, done.record["pr_ref"])
         )
@@ -276,7 +359,9 @@ def _evaluate_done(
             client, repo_id, contract, done
         )
     pr_after = client.pull_request(pr_url.owner, pr_url.repo, pr_url.number or 0)
-    if pr_after.get("head", {}).get("sha") != pr.get("head", {}).get("sha"):
+    if _pr_snapshot_key(pr_after, done.record["pr_ref"]) != _pr_snapshot_key(
+        pr, done.record["pr_ref"]
+    ):
         raise AcquisitionError(done.record["pr_ref"], "bound pull request head changed during acquisition")
     result.pr = pr_after
     if scope_diagnostics:
@@ -299,12 +384,20 @@ def _terminal_violations(
     diagnostics: list[Diagnostic],
     recognized_comments: list[Any],
     terminal_at: str,
-    terminal_record: RecordObservation,
+    safe_retry_urls: set[str],
 ) -> list[Diagnostic]:
-    result = list(diagnostics)
-    terminal_aliases = set(terminal_record.alias_urls)
+    violating_urls = {
+        comment.url
+        for comment in recognized_comments
+        if comment.created_at > terminal_at and comment.url not in safe_retry_urls
+    }
+    result = [
+        diagnostic
+        for diagnostic in diagnostics
+        if not any(url in violating_urls for url in diagnostic.urls)
+    ]
     for comment in recognized_comments:
-        if comment.created_at > terminal_at and comment.url not in terminal_aliases:
+        if comment.url in violating_urls:
             item = _diagnostic("terminal_violation", comment.url)
             if item not in result:
                 result.append(item)
@@ -338,16 +431,65 @@ def _stop_diagnostics(
     if start is None:
         return diagnostics
     branch_name = start.record["branch"]
-    candidates = [
-        pr
-        for pr in client.pull_requests(owner, repo, branch_name)
-        if _pr_matches(pr, repo_id, branch_name) and isinstance(pr.get("merged_at"), str)
-    ]
-    for pr in candidates:
-        diagnostics.append(_diagnostic("terminal_violation", stop.comment.url, pr["html_url"]))
+    resource = f"https://api.github.com/repos/{owner}/{repo}/pulls"
+    candidates = client.pull_requests(owner, repo, branch_name)
+    candidates_after = client.pull_requests(owner, repo, branch_name)
+    if _pr_collection_snapshot(candidates, resource) != _pr_collection_snapshot(
+        candidates_after, resource
+    ):
+        raise AcquisitionError(resource, "pull request collection changed during acquisition")
+    for pr in candidates_after:
+        if not _pr_matches(pr, repo_id, branch_name):
+            continue
+        pr_url = pr.get("html_url")
+        if not isinstance(pr_url, str):
+            raise AcquisitionError(stop.comment.url, "pull request ordering fields missing")
+        created_time = _github_time(
+            pr.get("created_at"), pr_url, "pull request created_at"
+        )
+        stop_time = _github_time(
+            stop.comment.created_at, stop.comment.url, "Stop created_at"
+        )
+        if created_time == stop_time:
+            raise AcquisitionError(
+                pr_url, "pull request creation and Stop ordering is ambiguous"
+            )
+        if _pr_not_after_start(pr, start, pr_url):
+            continue
+        if created_time > stop_time:
+            continue
+        merged_at = pr.get("merged_at")
+        if not isinstance(merged_at, str):
+            continue
+        merged_time = _github_time(merged_at, pr_url, "pull request merged_at")
+        if merged_time == stop_time:
+            raise AcquisitionError(pr_url, "merge and Stop ordering is ambiguous")
+        if merged_time > stop_time:
+            diagnostics.append(
+                _diagnostic("terminal_violation", stop.comment.url, pr_url)
+            )
     return diagnostics
 
 
+def _has_terminal_violation(diagnostics: list[Diagnostic]) -> bool:
+    return any(item.token == "terminal_violation" for item in diagnostics)
+
+
+def _done_can_be_evaluated(
+    contract: RecordObservation,
+    done: RecordObservation,
+) -> bool:
+    expected = contract.record["done_conditions"]
+    actual = done.record["evidence"]
+    if set(expected) != set(actual):
+        return False
+    return all(
+        parse_github_url(actual[condition_id], condition["evidence_kind"])
+        is not None
+        for condition_id, condition in expected.items()
+    )
+
+
 def _evaluate_acquired(
     client: GitHubClient,
     issue_url: str,
@@ -380,9 +522,16 @@ def _evaluate_acquired(
             issue_id=issue.get("id"),
             issue_created_at=issue.get("created_at"),
             repository_id=repo_id,
-            successors=_successor_context(client, comments),
         )
         fold = fold_comments(comments, context)
+        if fold.terminal_stop is not None and not _has_terminal_violation(
+            fold.diagnostics
+        ):
+            stop_record = fold.terminal_stop.record
+            if stop_record["reason"] == "superseded":
+                context.successors = _successor_context(
+                    client, [stop_record["successor_ref"]]
+                )
     except IncompleteSnapshotError as error:
         return _acquisition(issue_url, AcquisitionError(issue_url, str(error)))
     except AcquisitionError as error:
@@ -392,6 +541,7 @@ def _evaluate_acquired(
         fold.active["contract"][0] if len(fold.active["contract"]) == 1 else None
     )
     active_done = fold.active["done"][0] if len(fold.active["done"]) == 1 else None
+    terminal_done = fold.active["done"][0] if fold.active["done"] else None
     current: dict[str, Any] = {
         "contract": _record_projection(active_contract),
         "start": _record_projection(fold.bound_start),
@@ -403,6 +553,8 @@ def _evaluate_acquired(
         return StatusResult(issue_url, base_state, list(fold.diagnostics), current)
     if fold.bound_start is None or fold.bound_contract is None:
         if fold.terminal_stop is not None:
+            if _has_terminal_violation(fold.diagnostics):
+                return StatusResult(issue_url, "halt", list(fold.diagnostics), current)
             try:
                 stop_diagnostics = _stop_diagnostics(
                     client,
@@ -425,7 +577,41 @@ def _evaluate_acquired(
     branch_name = fold.bound_start.record["branch"]
     current["branch"] = {"name": branch_name}
     if fold.terminal_stop is not None:
+        if _has_terminal_violation(fold.diagnostics):
+            return StatusResult(issue_url, "halt", list(fold.diagnostics), current)
         try:
+            if terminal_done is not None and _done_can_be_evaluated(
+                fold.bound_contract, terminal_done
+            ):
+                live_done = _evaluate_done(
+                    client,
+                    repo_id,
+                    branch_name,
+                    fold.bound_start,
+                    fold.bound_contract,
+                    terminal_done,
+                )
+                if live_done.terminal_at == fold.terminal_stop.comment.created_at:
+                    raise AcquisitionError(
+                        terminal_done.record["pr_ref"],
+                        "Done terminal and Stop ordering is ambiguous",
+                    )
+                if (
+                    live_done.terminal_at is not None
+                    and live_done.terminal_at < fold.terminal_stop.comment.created_at
+                ):
+                    return StatusResult(
+                        issue_url,
+                        "halt",
+                        [
+                            _diagnostic(
+                                "terminal_violation",
+                                fold.terminal_stop.comment.url,
+                                terminal_done.record["pr_ref"],
+                            )
+                        ],
+                        current,
+                    )
             stop_diagnostics = _stop_diagnostics(
                 client, parsed.owner, parsed.repo, repo_id, fold.terminal_stop, fold.bound_start, context
             )
@@ -435,25 +621,88 @@ def _evaluate_acquired(
             return StatusResult(issue_url, "halt", [*fold.diagnostics, *stop_diagnostics], current)
         return StatusResult(issue_url, "stopped", list(fold.diagnostics), current)
 
-    if fold.diagnostics:
-        return StatusResult(issue_url, "halt", list(fold.diagnostics), current)
+    default_branch = repository.get("default_branch")
+    if not isinstance(default_branch, str):
+        return _acquisition(
+            issue_url,
+            AcquisitionError(issue_url, "repository default_branch missing"),
+        )
+    if branch_name == default_branch:
+        return StatusResult(
+            issue_url,
+            "halt",
+            [_diagnostic("invalid_binding", fold.bound_start.comment.url)],
+            current,
+        )
 
     try:
-        if active_done is not None:
-            live = _evaluate_done(client, repo_id, branch_name, fold.bound_contract, active_done)
+        if terminal_done is not None and _done_can_be_evaluated(
+            fold.bound_contract, terminal_done
+        ):
+            live = _evaluate_done(
+                client,
+                repo_id,
+                branch_name,
+                fold.bound_start,
+                fold.bound_contract,
+                terminal_done,
+            )
             if live.pr is not None:
                 current["bound_pr"] = live.pr.get("html_url")
                 current["bound_pr_head_sha"] = live.pr.get("head", {}).get("sha")
             if live.diagnostics:
-                return StatusResult(issue_url, "halt", live.diagnostics, current)
+                return StatusResult(
+                    issue_url,
+                    "halt",
+                    [*fold.diagnostics, *live.diagnostics],
+                    current,
+                )
             if live.terminal_at is not None:
+                safe_retry_urls = {
+                    url
+                    for observations in fold.ids.values()
+                    for observation in observations
+                    if len(observation.alias_urls) > 1
+                    for url in observation.alias_urls
+                }
                 diagnostics = _terminal_violations(
-                    fold.diagnostics, fold.recognized_comments, live.terminal_at, active_done
+                    fold.diagnostics,
+                    fold.recognized_comments,
+                    live.terminal_at,
+                    safe_retry_urls,
                 )
-                return StatusResult(issue_url, "done", diagnostics, current)
+                return StatusResult(
+                    issue_url,
+                    "halt" if diagnostics else "done",
+                    diagnostics,
+                    current,
+                )
+            if fold.diagnostics:
+                return StatusResult(issue_url, "halt", list(fold.diagnostics), current)
             if live.pr and live.pr.get("merged_at"):
                 return StatusResult(issue_url, "in_progress", [], current)
             branch = client.branch(parsed.owner, parsed.repo, branch_name)
+            branch_after = client.branch(parsed.owner, parsed.repo, branch_name)
+            branch_resource = (
+                f"https://api.github.com/repos/{parsed.owner}/{parsed.repo}/branches/"
+                f"{branch_name}"
+            )
+            if _branch_snapshot_key(branch, branch_resource) != _branch_snapshot_key(
+                branch_after, branch_resource
+            ):
+                raise AcquisitionError(
+                    branch_resource, "bound branch changed during acquisition"
+                )
+            branch_key = _branch_snapshot_key(branch_after, branch_resource)
+            pr_head = live.pr.get("head", {}).get("sha") if live.pr else None
+            if (
+                branch_key is None
+                or branch_key[1] != pr_head
+                or pr_head != terminal_done.record["head_sha"]
+            ):
+                raise AcquisitionError(
+                    branch_resource, "bound branch and pull request head disagree"
+                )
             current["branch"]["exists"] = branch is not None
             if branch is None:
                 return StatusResult(
@@ -464,10 +713,16 @@ def _evaluate_acquired(
                 )
             return StatusResult(issue_url, "in_progress", [], current)
 
+        if fold.diagnostics:
+            return StatusResult(issue_url, "halt", list(fold.diagnostics), current)
+
         branch = client.branch(parsed.owner, parsed.repo, branch_name)
         observed_candidates = client.pull_requests(parsed.owner, parsed.repo, branch_name)
         invalid_candidates = [
-            pr for pr in observed_candidates if not _pr_matches(pr, repo_id, branch_name)
+            pr
+            for pr in observed_candidates
+            if not _pr_matches(pr, repo_id, branch_name)
+            or _pr_not_after_start(pr, fold.bound_start, pr.get("html_url", issue_url))
         ]
         if invalid_candidates:
             urls = [fold.bound_start.comment.url] + [
@@ -503,6 +758,23 @@ def _evaluate_acquired(
             )
             if scope_diagnostics:
                 return StatusResult(issue_url, "halt", scope_diagnostics, current)
+        branch_after = client.branch(parsed.owner, parsed.repo, branch_name)
+        candidates_after = client.pull_requests(parsed.owner, parsed.repo, branch_name)
+        branch_resource = (
+            f"https://api.github.com/repos/{parsed.owner}/{parsed.repo}/branches/"
+            f"{branch_name}"
+        )
+        pulls_resource = (
+            f"https://api.github.com/repos/{parsed.owner}/{parsed.repo}/pulls"
+        )
+        if _branch_snapshot_key(branch, branch_resource) != _branch_snapshot_key(
+            branch_after, branch_resource
+        ) or _pr_collection_snapshot(
+            observed_candidates, pulls_resource
+        ) != _pr_collection_snapshot(candidates_after, pulls_resource):
+            raise AcquisitionError(
+                issue_url, "branch or pull request collection changed during acquisition"
+            )
         if branch is None:
             return StatusResult(
                 issue_url,
@@ -524,6 +796,21 @@ def _issue_snapshot_key(issue: dict[str, Any]) -> tuple[int, str, str]:
     return issue_id, created_at, updated_at
 
 
+def _repository_snapshot_key(
+    repository: dict[str, Any], resource: str
+) -> tuple[int, str, str]:
+    repo_id = repository.get("id")
+    full_name = repository.get("full_name")
+    default_branch = repository.get("default_branch")
+    if (
+        not isinstance(repo_id, int)
+        or not isinstance(full_name, str)
+        or not isinstance(default_branch, str)
+    ):
+        raise AcquisitionError(resource, "repository snapshot fields missing")
+    return repo_id, full_name, default_branch
+
+
 def evaluate_issue(client: GitHubClient, issue_url: str) -> StatusResult:
     parsed = parse_github_url(issue_url, "issue")
     if parsed is None:
@@ -534,6 +821,12 @@ def evaluate_issue(client: GitHubClient, issue_url: str) -> StatusResult:
         )
     try:
         repository = client.repository(parsed.owner, parsed.repo)
+        repository_resource = (
+            f"https://api.github.com/repos/{parsed.owner}/{parsed.repo}"
+        )
+        repository_key = _repository_snapshot_key(
+            repository, repository_resource
+        )
         issue = client.issue(parsed.owner, parsed.repo, parsed.number or 0)
         initial_key = _issue_snapshot_key(issue)
         comments = client.comments(parsed.owner, parsed.repo, parsed.number or 0)
@@ -544,6 +837,13 @@ def evaluate_issue(client: GitHubClient, issue_url: str) -> StatusResult:
     if result.state is None:
         return result
     try:
+        repository_after = client.repository(parsed.owner, parsed.repo)
+        if _repository_snapshot_key(
+            repository_after, repository_resource
+        ) != repository_key:
+            raise AcquisitionError(
+                repository_resource, "repository snapshot changed during acquisition"
+            )
         issue_after = client.issue(parsed.owner, parsed.repo, parsed.number or 0)
         if _issue_snapshot_key(issue_after) != initial_key:
             raise AcquisitionError(issue_url, "issue snapshot changed during acquisition")

github_task_protocol-1.0.1.dist-info/METADATA

@@ -1,88 +0,0 @@
-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

@@ -1,16 +0,0 @@
-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,,