github-task-protocol 1.0.1__tar.gz → 1.0.2__tar.gz

{github-task-protocol-1.0.1 → github-task-protocol-1.0.2}/DECISIONS.md

@@ -1530,3 +1530,192 @@ protocol coreは次の4領域へ限定する。
 - 取得不能時にstateを推測せず、`state: null`と`acquisition: incomplete`を返せる。
 - GitHubへのwrite path、GraphQL、webhook、cache、database、fork、GHESを追加せず、Issue #10のlive binding規則を検証できる。
 - live HTTP matrixとprune reportをimmutable Done Evidenceとして利用できる。
+
+## ADR-030: CLIを任意validatorとしてPyPIへ公開する
+
+- Status: Accepted
+- Date: 2026-07-20
+- Supersedes: Issue #5完了時のCLI非公開方針
+
+### 観測事実
+
+- [Issue #5の完了コメント](https://github.com/shinya0x00/github-task-protocol/issues/5#issuecomment-5016145451)は、`v1.0.1` tag、GitHub Release、PyPI packageを作成せず、CLI配布方式を未決定とする境界で親Issueを閉じた。
+- 利用者の新しい判断を受け、Issue #49で1.0.1公開candidateを準備し、Issue #52でsdistの`PKG-INFO`を修復した。
+- Issue #54では固定candidateからannotated tag、GitHub Release、PyPI公開、public PyPIからのclean install、live `done`／`stopped`再読を行った。
+- `README.md`は、GTP利用にCLI installは不要であり、使う場合だけ固定versionを指定できると説明している。
+- 最終公開結果とEvidenceの限界は`acceptance/public-release-v1.0.1.json`が所有する。一方、`acceptance/release.json`は公開前計画の`prepared_not_published`とplaceholderを保持していた。
+
+### 推論
+
+- CLIをPyPIから取得可能にすると、任意validatorを試す利用者の導入負担を下げられるが、GTPの参加条件へCLIを追加する必要はない。
+- packageの公開factは、Level 0のtoolなし引き継ぎ、人間のnative merge判断、GTPが権限を与えない境界を変更しない。
+- 公開前計画と最終Evidenceが異なる役割を持つことを明示しなければ、clean readerは`prepared_not_published`を現在状態と誤読できる。
+- `acceptance/release.json`をrenameすると過去のIssueとPRからのpath参照を壊すため、同じpathでsupersessionを明示する方が履歴を追いやすい。
+
+### 決定
+
+- CLIはGTP利用の必須条件ではないが、任意の参照validatorとしてPyPIへ公開する。
+- 公開によってRecord、state、halt reason、Level 0の価値、人間の受理権限、GTPが証明する範囲を変更しない。
+- `acceptance/release.json`は1.0.1公開前計画のhistorical artifactとして残し、statusを`superseded_by_public_release_evidence`とする。
+- 同fileの`superseded_by`から`acceptance/public-release-v1.0.1.json`へ解決可能な関係を持たせる。最終公開factはsuccessor Evidenceが所有し、公開前placeholderを遡及的な実績値へ書き換えない。
+- npm公開、自動publish workflow、CLI必須化はこのDecisionへ含めない。
+
+### 不採用案
+
+- CLI非公開方針の維持は、新しい利用者判断と実際の1.0.1公開factに一致しないため採用しない。
+- `acceptance/release.json`の削除またはrenameは、公開前判断の履歴と既存path参照を弱めるため採用しない。
+- 公開後の値でplaceholderを全面更新する案は、計画時点の観測と実行後Evidenceのownerを混同するため採用しない。
+
+### 結果
+
+- clean readerは、公開前計画から最終public Evidenceへ一意に移動できる。
+- 配布方針の理由をIssueとPRの全履歴から再構成せず、Decisionとして読める。
+- 今後のversion準備、tag、GitHub Release、registry upload、公開後検証は、それぞれのrelease IssueとEvidenceで扱う。
+- PyPI公開、CI成功、CLI出力は、actor本人性、credential安全性、package品質全体、変更・完了・merge authorityを証明しない。
+
+## ADR-031: 目的説明とEvidence binding表示を分離する
+
+- Status: Accepted
+- Date: 2026-07-20
+
+### 観測事実
+
+- `GTP.md`はCheck Runのtest十分性とArtifact内容の真実性を証明しないと定義している。
+- 変更前のCLIは`done`を「このIssueの完了を確認しました」、条件一覧を「確認できた完了条件」と表示し、resource bindingの確認を条件内容の意味評価と読める余地があった。
+- core schemaはtask固有のunknown fieldを持たず、通常commentは履歴へ影響しない。
+- reducerは同一ID・同一JSONのsafe retryをLogical Recordへ畳むが、live terminal検査はDone aliasだけを除外していたため、terminal後のContractまたはStart retryを新Recordとして扱っていた。
+- Level 1のIssue #12はbranch削除後の完了再構成を示す一方、Issue #65はPython 3.11、3.12、3.13の各Done Conditionを個別のexact-head Check Runへ束縛している。
+
+### 推論
+
+- protocol stateの`done`と、人間による条件内容の受理を同じ文面にすると、GTPが証明しないsemantic fulfillmentを過剰claimする。
+- task固有のunknownをclosed Record schemaへ追加すると、stateへ影響する意味規則が必要になり、最小protocolの境界を越える。通常のIssue本文・commentで人へ引き継ぎ、Done可否に関係するunknownが残るならDoneを提示しない方が一意である。
+- safe retry aliasは新Logical Recordではないため、Record typeにかかわらずterminal後の違反検査から除外しなければ仕様と実装が一致しない。
+- current acceptanceは、Done ConditionとEvidenceを一対一に追えるIssue #65を参照した方がclean readerの再検証可能性が高い。
+
+### 決定
+
+- CLIはDone Claim、Evidence binding、native mergeを観測factとして表示し、Done Conditionの自然言語上の充足を自動判定しないことを同じ出力で明示する。
+- `task_context.not_proven`と`evidence_limits`へsemantic fulfillmentの限界を投影する。task固有のunknown field、state、Record typeは追加しない。
+- terminal後の同一ID・同一JSON retryはContract、Start、Done、Stopの別なくsafe aliasとして扱う。fresh Recordは従来どおり`terminal_violation`とする。
+- Level 1のIssue #12を歴史的な完了再構成Evidenceとして保持し、現行のexact-head CI受入はIssue #65を参照する。
+
+### 不採用案
+
+- `done`をsemantic fulfillmentの自動証明として扱う案は、Evidence resourceから内容の十分性を一般に判定できないため採用しない。
+- unknownをGTP Recordへ追加する案は、closed schemaと4 Recordの最小境界を変えるため採用しない。
+- terminal検査でDone aliasだけを特別扱いする案は、Logical Recordのidentity規則がRecord typeに依存しないため採用しない。
+- Issue #12の記録を削除または現在値へ書き換える案は、過去の受入履歴を失うため採用しない。
+
+### 結果
+
+- 人はCLI出力だけで、機械確認できたbindingと、人がEvidenceを読んで判断すべき条件内容を区別できる。
+- ContractとStartの遅延retryがterminal resultを壊さず、fresh Recordだけが違反になる。
+- task固有の未確認事項はGitHub上の通常proseへ残り、protocol coreのstate判断へ暗黙に混入しない。
+- clean readerは歴史的な完了再構成と現行のexact-head CI受入を区別して辿れる。
+
+## ADR-032: terminal identityと取得完全性をfail-closedにする
+
+- Status: Accepted
+- Date: 2026-07-20
+
+### 観測事実
+
+- Stop後のfresh Recordを`terminal_violation`として検出しても、live statusは`stopped`と`none_stopped`を表示していた。
+- Stop再読時に同名branchの全PR履歴を対象としていたため、Stop後に別taskが同名branchを再利用してmergeすると、過去Issueが`stopped`から`halt`へ変化した。
+- GitHub RESTの404はresource不在と権限不足を一意に区別できないが、branch、PR、Check Run、artifact、successor Issueの404をprotocol不適合へ変換していた。
+- Issueだけを再読していたため、取得中のbranch、PR candidate、merge factの変化を検出しない経路があった。
+- List Pull Request Filesには取得上限があるが、返却fileを完全なPR差分としてscope判定していた。
+- Startはrepository default branchも受理し、`continue_work`を提示できた。
+- sourceは公開1.0.1後にruntime挙動を変更したが、package versionとREADME commandは1.0.1のままだった。
+
+### 決定
+
+- Stop後のfresh Recordはpublic stateを`halt`、reasonを`terminal_violation`とし、最初のfresh comment URLを原因とする。pre-terminal diagnosticを持つvalid Stopの非常口は維持する。
+- Stop後mergeの対象は、Start以後かつStop以前に作成されたsame-repository・same-branch PRへ限定する。Stop後に作成された同名branch PRは過去Issueへ影響させない。
+- 汎用404からresource不在を推測せず、十分な取得を証明できない場合はAcquisition Errorとする。
+- branch、PR candidate collection、Bound PRを再読し、stateを左右するsnapshotが変化した場合はAcquisition Errorとする。
+- PR detailの`changed_files`と取得したfile数を照合し、完全な差分を取得できない場合はscope適合をClaimしない。
+- Start branchがrepository default branchと一致する場合は`halt / invalid_binding`とする。valid Stopはこのpre-terminal不適合を安全に閉じられる。
+- task固有の自由文はIssue本文・通常commentがcanonical ownerであり、CLIはその意味を自動判定しない。開始前から完了判断に必要な不明点はDone Conditionとし、開始後にContract変更が必要ならStopと後継Issueへ移る。CLIはDone提示前の確認先としてIssue URLを表示する。
+- Record grammarは変更しない。runtime修復candidateのpackage versionを1.0.2とし、公開完了前はpublic packageとして案内しない。
+
+### 不採用案
+
+- unknown専用Recordまたは自由文parserの追加は、4 Recordと決定的reducerの境界を広げるため採用しない。
+- 404を常にresource不在とする案は、権限不足をprotocol不適合へ変換するため採用しない。
+- branch名をrepository全体で永久に再利用禁止とする案は、Stop comment時刻でtask対象PRを限定できるため採用しない。
+- 既に公開済みの1.0.1 tagまたはartifactを移動・置換する案は、immutableなrelease identityを壊すため採用しない。
+
+### 結果
+
+- terminal resultはfresh Recordと将来の無関係なbranch再利用を区別できる。
+- 取得不能、取得中変化、file一覧打ち切りをprotocol haltと混同しない。
+- default branchへの作業継続をGTP statusが案内しない。
+- clean readerはIssue URLからtask固有の未確認事項を確認する必要と、CLIが意味評価しない限界を同時に確認できる。
+- source candidateと次のpublic package identityを1.0.1から分離できる。
+
+## ADR-033: PR snapshotとtask lifecycleのidentity境界を一致させる
+
+- Status: Accepted; Stopのpre-Start PR判断はADR-034でsupersede
+- Date: 2026-07-20
+
+### 観測事実
+
+- PR snapshot比較はhead SHAとmerge時刻を含む一方、base ref・base SHA・`changed_files`を含まず、file一覧取得中のbase更新を検出できなかった。
+- 通常のcandidateとDoneはStart前から存在するsame-branch PRを受理したが、Stop後merge検査はStart以後に作成されたPRだけを対象とし、同じPRのtask identityがlifecycle途中で変わった。
+- repositoryの`default_branch`はStart拒否を決めるが、最初の取得後に再確認していなかった。
+- native merge前のDoneはPR headとDone SHAを照合したが、同時に観測したbranch SHAとの一致を要求していなかった。
+- Issue #64 / PR #67とIssue #73 / PR #74が、異なるruntime内容で同じ未公開version 1.0.2をcandidateとして保持していた。
+
+### 決定
+
+- PR snapshotはbase repository・ref・SHA、head repository・ref・SHA、state、merge時刻、取得可能な`changed_files`を含む。scope判定ではdetail PRをfile一覧の前後に取得し、全snapshotが一致した場合だけfile一覧を使用する。
+- Startと同時刻以前に作成されたPRはcandidate、Done、Stopの全経路で`invalid_binding`とする。Stop後に作成された同名branch PRは従来どおり元taskの対象外とする。
+- issue repositoryをstate評価後に再取得し、identityまたは`default_branch`が変化した場合はAcquisition Errorとする。
+- native merge前のDoneでは、安定したbranch SHA、Bound PR head SHA、Done head SHAの三者一致を要求する。merge後にbranchが削除されても、Issue、Done、PR、merge factから再構成できる既存境界は維持する。
+- Issue #64とIssue #73をIssue #75へsupersedeし、PR #67とPR #74を未mergeで閉じる。未公開1.0.2のopen delivery laneはIssue #75 / PR #76へ一本化する。
+
+### 不採用案
+
+- PR作成時刻をStop時だけ使う案は、作業中と停止後でtask identityが変わるため採用しない。
+- base branch名だけを比較する案は、同じbranch名の先端更新を検出できないため採用しない。
+- merge後もbranch取得を必須にする案は、正常なbranch削除後にhistorical Doneを再構成できなくなるため採用しない。
+- RecordへPR番号またはbase SHA fieldを追加する案は、GitHub live resourceから取得でき、Record grammarを広げる必要がないため採用しない。
+
+### 結果
+
+- scope判定が使用したfile一覧を、同じbase/head/`changed_files`のdetail PRへ束縛できる。
+- PRがtaskへ属するかの規則がcandidate、Done、Stopで一致する。
+- default branch変更とnative merge前のbranch/PR反映差からstateを推測しない。
+- clean readerはpredecessorから一つのopen 1.0.2 candidate laneへ移動できる。
+
+## ADR-034: Stopではpre-Start PRを対象外とし、同一instantを推測しない
+
+- Status: Accepted
+- Date: 2026-07-20
+
+### 観測事実
+
+- ADR-033はStartと同時刻以前のPRをcandidate、Done、Stopの全経路で`invalid_binding`とした。
+- この規則では、古いsame-branch PRが原因でhaltしたIssueへvalid Stopを投稿しても`stopped`へ着地できず、pre-terminalな不適合を安全に放棄するStopの役割と衝突した。
+- GitHubのPR作成時刻とStop comment時刻が同一instantでも、実装はPRをStop以前の対象として扱い、後日のmergeを`terminal_violation`と断定できた。
+
+### 決定
+
+- candidate探索とDone bindingでは、Startと同時刻以前のPRを従来どおり`invalid_binding`とする。
+- Stopでは、Startと同時刻以前のPRを現在taskの対象外として除外し、diagnosticへ加えない。
+- PR作成時刻とStop時刻が同一instantなら、merge有無より先にAcquisition Errorとする。merge時刻とStop時刻の同一instantもAcquisition Errorを維持する。
+- timestampはtimezone付きdatetimeとしてUTCへ正規化して比較する。Record、state、halt reasonは追加しない。
+
+### 不採用案
+
+- Stopでもpre-Start PRを`invalid_binding`にする案は、valid Stopを非常口として使えなくするため採用しない。
+- PR作成とStopの同一instantをStop以前とみなす案は、Stop後に作成された別taskのPRを元Issueへ結び付ける可能性があるため採用しない。
+- branch名を永久に再利用禁止とする案は、Stopの時間窓と後継Issueの新branchでtask identityを分離できるため採用しない。
+
+### 結果
+
+- 作業中に古いPRを誤継承せず、壊れたStartはvalid Stopで`stopped`へ閉じられる。
+- Stopと同一instantのPR作成から`stopped`または`terminal_violation`を推測しない。
+- candidate、Done、Stopは同じPR集合を同じ目的で扱うのではなく、作業bindingと安全な放棄という役割に応じた境界を持つ。

{github-task-protocol-1.0.1 → github-task-protocol-1.0.2}/GTP.md

@@ -108,6 +108,8 @@ taskの目標、変更範囲、完了条件を確定する。fieldは次だけ
 
 `done_conditions`のkeyはcondition IDである。各valueは`text`と`evidence_kind`だけを持つ。`evidence_kind`は`check`または`artifact`である。
 
+開始前から完了判断に必要な不明点はDone Conditionとして固定する。task固有の自由文はIssue本文または通常commentが所有し、readerは意味を自動判定しない。開始後にContract変更が必要な不明点が判明した場合は、Stopと後継Issueで新しいContractへ移る。
+
 ### 5.2 `start`
 
 有効なContractと唯一の作業branchを束縛する。fieldは次だけである。
@@ -120,6 +122,8 @@ taskの目標、変更範囲、完了条件を確定する。fieldは次だけ
 | `contract_ref` | string | 同じIssue内の先行Contract comment URL |
 | `branch` | string | Issue repository内のbranch short name |
 
+live bindingではrepositoryのdefault branchを拒否する。Start、branch、CLI表示は作業権限を与えない。
+
 ### 5.3 `done`
 
 特定source headについて、完了条件ごとのEvidenceを持つDone Claimを示す。Task Completionそのものではない。fieldは次だけである。
@@ -255,7 +259,7 @@ Issue commentはGitHub comment IDの昇順で読む。record内の自己申告
 
 同じ`id`かつ構造的に同じJSONの再投稿だけをsafe retry aliasとして1 Logical Recordへ畳む。object key順、JSON whitespace、人向け要約は同一性へ含めない。配列順と値は含める。同じ`id`で異なるJSONは`halt / invalid_record`である。
 
-通常commentは履歴へ影響しない。Carrierを削除または編集して履歴を修復してはならない。複雑な訂正、Recordのjoin、Recordの置換は定義しない。
+通常commentはprotocol履歴へ影響しないが、task固有の自由文を引き継ぐGitHub記録である。Done提示前にIssue本文と通常commentを読む。Carrierを削除または編集して履歴を修復してはならない。複雑な訂正、Recordのjoin、Recordの置換は定義しない。
 
 ## 8. lifecycleとstate
 
@@ -287,10 +291,13 @@ valid Doneが指す`head_sha`を、Bound PRがnative mergeし、その後にterm
 
 - ContractはStartより前に1件だけ置く。複数Contractは`conflicting_records`である。
 - Startは先行する唯一のContractを指す。Start後はContractとbranchを凍結する。
+- Start branchはrepositoryのdefault branchではならない。
 - StartなしのDone、Start後のContract、Record順序違反は`invalid_transition`である。
 - Start、Done、Stopを複数の異なるLogical Recordとして置かない。
 - 1 Issue = 1 branch = 1 PRとする。分割、統合、別branchへの移動はStopと新Issueで行う。
-- Doneの`head_sha`はBound PRのsource headと一致し、全Evidenceも同じrepositoryとSHAへ束縛される。
+- Startと同時刻以前の`created_at`を持つPRは、そのStartのcandidateまたはDone対象として受理せず`invalid_binding`とする。valid Stopではpre-terminalな不適合を閉じるため、現在taskの対象PRから除外する。
+- PR file一覧を完全取得し、`filename`とrename時の`previous_filename`がすべてContract scope内にあることを確認する。
+- Doneの`head_sha`はBound PRのsource headと一致し、全Evidenceも同じrepositoryとSHAへ束縛される。native merge前はbranch SHAも同じ値でなければならない。
 - Stop後の新Recordまたは対象PR merge、証明済みDone後のStopや新Recordは`halt / terminal_violation`である。先に成立したterminal resultを別のterminal resultへ書き換えない。
 - safe retry aliasは新Recordではないため、同一内容ならterminal後でも畳める。
 
@@ -314,6 +321,8 @@ valid Doneが指す`head_sha`を、Bound PRがnative mergeし、その後にterm
 
 `reason: "superseded"`では`successor_ref`へ後継Issueを示す。`reason: "abandoned"`では`successor_ref: null`とする。Stop後は元Issueへ新Recordを投稿しない。
 
+Stop後mergeの対象は、Startより後かつStopより前に作成されたsame-repository・same-branch PRだけである。Startと同時刻以前のPRとStop後に作成されたPRは元Issueへ影響しない。PR作成またはmergeとStopが同一instantで先後を一意に取得できない場合はAcquisition Errorである。
+
 証明済みDoneは後のStopで`stopped`へ上書きできない。Stop後に対象PRがmergeされた場合も`done`へ変えない。どちらもpublic stateは`halt`、理由は`terminal_violation`とし、先に成立していたterminal resultを`details`へ残す。
 
 ## 12. Evidenceとnative merge
@@ -325,13 +334,17 @@ Evidence kindは`check`と`artifact`だけである。
 
 Check Runが証明するのはGitHubが指定SHAへsuccessを返したことまでであり、test内容の十分性までは証明しない。Artifactが証明するのは指定commitにfileが存在することまでであり、内容の真実性までは証明しない。
 
+readerが機械的に判定するのはEvidence resourceとDone Claimのbindingであり、Done Conditionの自然言語上の充足ではない。条件内容の受理は人間がEvidenceを読んで判断する。
+
 人間の最終受理はGitHub native PR mergeへ一本化する。Done ClaimとEvidenceだけではTask Completionにならない。
 
 ## 13. Acquisition Error
 
 state決定に必要なIssue comments、branch、PR、Check Run、artifact、merge factを完全に取得できない場合、stateを出してはならない。これは`halt`ではなくAcquisition Errorである。
 
-network、authentication、rate limit、pagination途中失敗をprotocol不適合と推測しない。取得できたresourceの不一致と、resourceを取得できないことを分離する。
+network、authentication、rate limit、pagination途中失敗をprotocol不適合と推測しない。404だけではresource不在を確定しない。PRの`changed_files`と取得file数が一致しない場合もstateを出さない。取得できたresourceの不一致と、resourceを取得できないことを分離する。
+
+stateを左右するrepository、Issue、branch、PR候補、Bound PRは取得前後を比較し、変化したsnapshotからstateを出さない。repositoryはidentityと`default_branch`を比較する。PRは少なくともbase repository・ref・SHA、head repository・ref・SHA、state、merge時刻、取得可能な`changed_files`を比較し、file一覧取得の前後ではdetail PRの全項目を固定する。
 
 ## 14. Level 0とLevel 1
 

github-task-protocol-1.0.2/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,107 @@
+# 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/acceptance/explicit-setup-install/delivery.json

@@ -0,0 +1,70 @@
+{
+  "schema": "github-task-protocol-explicit-setup-delivery/v1",
+  "status": "delivery_candidate_pending_merge",
+  "source_issue": "https://github.com/shinya0x00/github-task-protocol/issues/85",
+  "supersession": [
+    {
+      "issue": "https://github.com/shinya0x00/github-task-protocol/issues/81",
+      "pull_request": "https://github.com/shinya0x00/github-task-protocol/pull/82",
+      "reason": "bare repository URL is not mutation authorization"
+    },
+    {
+      "issue": "https://github.com/shinya0x00/github-task-protocol/issues/83",
+      "pull_request": "https://github.com/shinya0x00/github-task-protocol/pull/84",
+      "reason": "unmerged instructions cannot be externally accepted from the default branch"
+    }
+  ],
+  "input_boundary": {
+    "bare_repository_url": "explain_or_request_purpose_without_repository_mutation",
+    "setup_request": "explicit_target_setup_request_plus_gtp_repository_url",
+    "setup_effect_limit": "draft_pull_request_pending_human_merge",
+    "task_after_setup": "target_issue_url_only"
+  },
+  "delivery_boundary": {
+    "done_evidence": [
+      "README and static release-surface tests",
+      "source head bound Python 3.11, 3.12, and 3.13 PR Check Runs",
+      "this delivery artifact"
+    ],
+    "external_acceptance_required_for_delivery_done": false,
+    "external_acceptance_activation": "after native merge in a separate Issue and pull request"
+  },
+  "observed_probes": [
+    {
+      "input": "bare GTP repository URL only",
+      "result": "description_only_no_repository_mutation",
+      "interpretation": "expected_safe_behavior"
+    },
+    {
+      "input": "explicit setup request plus GTP repository URL",
+      "result": "draft_setup_pull_request_created_with_moving_main_spec",
+      "interpretation": "activation succeeded but stable Release selection failed because candidate instructions were not on the default branch"
+    }
+  ],
+  "external_acceptance": {
+    "status": "pending_after_delivery_merge",
+    "executor": "user_with_separate_provider_and_repository",
+    "dedicated_acceptance_repository": false,
+    "required_evidence": [
+      "explicit setup input and target repository context",
+      "stable tag, dereferenced commit SHA, and vendored GTP.md SHA-256",
+      "Draft setup PR URL, non-destructive diff, and human merge SHA",
+      "separate clean agent receiving only the target Issue URL",
+      "reconstructed state, first action, referenced Contract, Start, and PR",
+      "existing branch and PR reuse without duplicates",
+      "Evidence disclosure boundary and remaining verification limits"
+    ]
+  },
+  "claim_boundary": {
+    "external_setup_success": false,
+    "version_1_0_2_published": false,
+    "merge_authority": false
+  },
+  "evidence_limits": [
+    "delivery tests do not prove behavior of an external clean agent",
+    "the prior explicit-setup probe used a private target and cannot be independently reproduced from public URLs",
+    "native merge and default-branch discoverability are not established by this artifact",
+    "this artifact does not authorize merge or publication"
+  ],
+  "next_action": "human reviews and natively merges the delivery pull request, then a successor acceptance lane reruns the explicit setup probe"
+}