コードの提出と成果確認

Sessionがコードを書き終えても、その変更がGitHubへ届いたとは限らない。aachatはコードを自動でcommit・pushしたり、PRを作成したりしない。PRとpushは自動では記録もされない。成果を確認するときは、変更内容と検証結果に加え、どのrepositoryのどのbranchまたはPRへ、どのHEADが届いたかを確かめる。

Projectの文書・Media・HTML・Workflow・Triggerは、それぞれの保存・同期の仕組みで保存され、Sessionの成果として自動で記録される。このページはGitで管理するコードとAgentの能力の提出を説明する。

2つのrepositoryと提出先

作業を始める前に、Sessionのrepositoryと提出先、対象repoの指示を確認する。Teamのdefault repo、Projectのworking branch、現在checkoutされているSession branchは同じものではない。指示されたPRを省略してmainへpushしない。

aachat/と.aachat/はworkspaceでgit exclude済みである。Projectの同期ファイルや生成された契約をWorkspace repoへcommitしない。文書はShared Documents、環境設定はEnvironmentを参照する。

Agentが提出して記録する

以下はaachatが起動したSession内のAgent向け手順である。外側のターミナルやcoding agentではchatを使わず、通常のGit/GitHub操作を行う。

1. commitする

git statusとgit diffを読み、この仕事に関係するファイルだけをcommitする。repository固有のテストに従う。認証情報・絶対パス・環境固有の値はcommitしない。

git status --short --branch
git diff
git add path/to/changed-file
git commit -m "Describe the completed change"

2. pushし、必要ならPRを作る

Projectのworking branchへ提出する場合は、<working-branch>を確認済みの提出先へ置き換える。non-fast-forwardならgit fetch origin、git rebase origin/<working-branch>の後に再pushする。

git push origin HEAD:<working-branch>

PRで提出する場合は、Session branchをpushしてPRを作る。PRを作る前に、対象repositoryのPull Request templateとrepository guidanceを確認する。templateがあればそれに従い、構造と必須項目を保って本文を書く。mainは対象repositoryのbase branchに合わせる。既存PRを直すときはそのPRのhead branchへpushし、PRを作り直さない。

git push -u origin HEAD
gh pr create --base main --title "Describe the change" --body-file pr-body.md

3. 直後に提出を記録する

Workspace repoでPRの作成やpushに成功したら、Sessionの終了を待たずにその直後に一度だけ記録する。PRはURL、PRのないpushは実際にpushしたremote branchをgit-branch:<owner/repo>:<branch>としてrefに入れる。

chat result report --stdin <<'JSON'
{"results":[{"ref":"https://github.com/owner/repo/pull/123"}]}
JSON

chat result report --stdin <<'JSON'
{"results":[{"ref":"git-branch:owner/repo:feature-branch"}]}
JSON

例の値は実際の提出先へ置き換える。入力の詳細はchat result report --helpで確認できる。

• 1回に1〜50項目。トップレベルはresultsだけで、各項目にref、key、summary、inputs、excluded、projectを入れる
• PRやbranchの項目はrefだけでよい。summaryは任意である。PRを記録すれば、そのhead branchへのpushを別に記録する必要はない
• repositoryは、このSessionのworkspace repoかagent repoに限る。別のrepositoryはdelivery_repository_mismatchで拒否される
• 記録はローカルのGitもGitHubも読まない。送ったrefをそのまま記録し、pushやPR作成も代行しない
• Projectは受付中の現在のtaskから推定される。推定できないとproject_requiredになるので、応答が求めたときだけ--project <team/project>または項目ごとのprojectを付ける
• 以前のdeliveryの項目は廃止されたため、refを使う。現CLIはunknown fieldとしてローカルで拒否し、data.items[]の項目codeをinvalid_inputにする。serverへ旧入力が届いた場合の項目codeはinvalid_report（delivery input was removed: …）。どちらも要求全体のcodeとは限らない。古いCLIならaachat updateする

Agent repoは別のGit worktreeで、detached HEADである。変更を確認してcommitした後、そのディレクトリからmainへpushする。Sessionのcommitを含むHEADがローカルのorigin/mainに含まれることをlauncherが確認すると、turnの終わりに成果として自動で記録される。

cd "$AA_AGENT_DIR"
git status --short --branch
git diff
# 関連ファイルをaddし、commitしてから実行する
git push origin HEAD:main
git remote get-url origin

記録済みのrefを再登録する必要はなく、しても何も変わらない。記録は提出の申告を保存したものであり、GitHubで確認した結果でも、pushやPR作成の代行でもない。

報告の結果を読む

成功するとdata.itemsに項目ごとのstatus（created・updated・unchanged）が返る。1項目でも記録されないと、ok:false・終了コード1・error.codeがresult_report_incompleteになる。記録された項目は保存済みで、data.itemsに残る。

記録されなかった項目はstatusがerrorで、code、message、retryable、input_indexが付き、diagnosticが付くことがある。

これらはGitHubへのpushが失敗した証拠ではない。記録のためにpushやPR作成を繰り返さない。要求全体がsession_not_runningになった場合は、実行を受け付けたturnの外から報告した（トラブルシューティング）。

報告だけを再送する

送信後に記録されなかった項目がある場合は、送信前に保存された固定payloadのpathがdata.retry_fileに返る（AA_WS_DIR配下の.aachat/session-results/pending/にある、権限0600のファイル）。そのファイルを編集せずに再送する。

chat result report --retry-stdin < <data.retry_file のpath>

再送ではProject・version・nonceが固定される。元のJSONで--stdinを再実行すると再送ではなく新しい更新になる。送信前に拒否された項目（invalid_refやdocument_not_syncedなど）はretry_fileに含まれないので、その項目だけを直して--stdinで報告し直す。pushやPR作成は再実行しない。残った失敗は最終回答で短く明示する。報告の失敗だけでSessionの終了は止まらない。

成果を整理する・過去の提出を読む

成果を伴う最終回答の直前に、自分のSessionの成果を整理する（Sessions）。既存の成果にはsummaryを追加・変更でき、summaryなしでinputsだけを更新することもできる。試作や重複など不要な成果は"excluded":trueで通常の一覧から隠し、falseで戻す（nullは不可）。除外は一覧の整理であり、本体・参考関係・receipt・未提出の警告は消えない。

記録済みのPR・pushはchat result listのgithub_pr・git_branchの成果で確認する。repositoriesのローカル状態は観測時点の記録である。提出記録がない、または取得できない場合は未確認として扱う。

人間が確認すること

ProjectのWork PanelからSessionを開き、headerの成果バッジを確認する。

• Pull requestsのバッジは記録されたPRの一覧を開き、GitHubのPRへ移動できる
• Branchesのバッジは、PRなしで記録されたbranchへのpushの一覧を開く
• Code deliveryのバッジは、repositoryのローカル観測を開く。注意が必要なrepositoryがあると注意色になり、3 uncommitted changes、Local inspection failed、2 repos need attentionなどを添える。Sessionの一覧の行には、この注意だけが表示される

Code deliveryパネルにはrepositoryごとに、Needs attention、Next:（次の操作）、Technical details（未commitの変更数、Session commit数、Current branch、失敗のReason）が並ぶ。提出の記録がなければNo recorded submissionsと出る。

1. PRまたはbranchが、依頼したrepositoryと提出先に一致するか確認する
2. 提出されたHEADと、今回の変更・検証の対象を照合する。提出後に追加の変更があれば、その変更も届いたか確認する
3. PR本文とチェック結果を読み、未確認事項や残る作業を確認する
4. merge、release、公開後の動作確認が必要な仕事では、それぞれの結果まで確認する

提出記録はCI成功、レビュー承認、merge、本番反映を証明しない。Sessionの停止や「完了しました」という文章も、その代わりにはならない。

ローカル観測とattention

turn終了時のローカル観測は、未commitの変更とSessionのcommit数をread-onlyで確認する。remoteをfetchしたりGitHubへ問い合わせたりしないため、ローカル観測だけで提出済みとは判断しない。表示がない、または取得できない場合も、変更なしと決めつけない。

ローカル観測は提出の有無を判定しない。Session commitが残っていても注意にはならないので、PR・pushの記録と合わせて、依頼した変更が提出先に届いたかを確認する。

Local inspection failedの主なReasonは次のとおり。

古い提出の後に新しいcommitを作った場合、過去のPR記録があっても最新の変更まで提出されたとは限らない。remoteの状態も含めて確認する。

Sessionを終える前に

作業workspaceは永続的な保存場所ではない。commitし、指示されたbranchまたはPRへpushした成果だけが残る。成果がpush済み、未push、repository変更なしのどれかを明示し、PR URLまたはbranch、確認したテスト、残る差を引き継ぐ。未pushなら、残る変更と必要な次の操作を説明する。

chat session finishの後、現在のturnの後に最後の整理のturn（Asset Wrap-Up）が一度だけ走る。ここでは未記録のPR・pushだけをchat result report --stdinで記録すればよく、記録済みのものは送り直さない。

Asset Wrap-Upの入力時、workspace repoがあるSessionではローカルHEADの追跡ファイルも検査する。aachat/README.md以外のaachat/配下（aachat自体を含む）がcommitされていれば、agent向けのrepository状態に禁止パスと「このcommitから次のSessionを起動できない」旨を表示する。実ファイルを残して追跡を解除し、既存の提出権限内で削除をcommit・pushするための診断であり、自動修正や終了の拒否は行わない。stage済みの削除だけではHEADに残るため警告は消えない。検査できない場合は未確認と表示する。警告がないことは、push先や別branch、最終turn中に作ったcommitの状態、次の起動全体の成功を保証しない。

workspaceの保持・回収とSessionの再開はSessions、Projectの成果の受け入れはProjects、構文一覧はCLIを参照する。