task-research contract
対象読者と目的
この文書は、Issue 作成や実装前の調査を行う人と、research packet を下流 workflow で利用する人を対象にする。目的は、read-only 調査の結果、ユーザー判断、未解決事項を、再利用できる packet と handoff に固定することにある。
Loop Engineering の org-l1 daily triage から read-only research を起動する場合も、この packet contract を再利用し、Skill 入口と profile 境界は loop-engineering reference に従う。
通常経路
- target、repo、requested depth、handoff 先を決める。
research=offなら artifact と resume command を作らず、明示 no-op として報告して止める。research-packet=<path>で既存 packet を使う場合は、read-only 調査の入力にする前にreview-orchestrator task-research validateを通す。- read-only 調査を実行し、
research-plan.json、research-packet.json、人間確認用のresearch-brief.mdを作る。 - 既存 packet から新しい packet を作った場合は、
review-orchestrator task-research validate --packet <new-packet> --prior-packet <input-packet>でchosen_by: "user"の decision が残っていることを確認する。 handoff=github-issue-breakdown|fix-github-issue|implement-from-planを指定した場合だけhandoff.jsonと resume command を作る。review-orchestrator task-research validateで packet、plan、handoff、manifest、index など生成した artifact をまとめて検証する。review-orchestrator task-research grill-gateで plan と packet を判定し、success/proceedの時だけ先へ進む。blockedなら/grill-meまたは明示的なgrill=skip、inconclusiveなら不足 artifact の解消へ戻る。- handoff を指定した場合は検証済み resume command で下流 workflow へ渡す。既定の
handoff=noneでは research artifact の報告で止める。
この contract は調査 artifact の shape と downstream handoff 境界だけを定義する。github-issue-validation、issue readiness、plan readiness、PR 前 simplify、multi-review の代替にはしない。
Source of truth
- packet と関連 artifact の shape: この文書の Artifact roles と各 schema section
- artifact validation:
review-orchestrator task-research validate - grill 判定:
review-orchestrator task-research grill-gate - downstream の採用判断:
review-orchestrator task-research discoverのcandidate_stateとcandidates[].candidate_status - Skill の入口と option:
claude/skills/task-research/SKILL.md
Commands
task-research [research=auto|off|light|standard|deep|spike] [research-mode=single|parallel] [research-packet=<path|auto>] [handoff=github-issue-breakdown|fix-github-issue|implement-from-plan|none] [agent=auto|codex|claude|copilot] [target=<Issue番号/URL|自由文>] [repo=<owner/repo>] [out=<dir>] [ask-user]
review-orchestrator task-research validate --packet <path> [--plan <path>] [--workers <path>] [--handoff <path>] [--manifest <path>] [--index <path>]
review-orchestrator task-research validate --packet <path> --prior-packet <path> [--plan <path>] [--workers <path>] [--handoff <path>] [--manifest <path>] [--index <path>]
review-orchestrator task-research grill-gate --plan <path> --packet <path> [--grill-mode skip]
review-orchestrator task-research discover --issue <num|url> --repo <owner/repo> [--state-root <path>] [--legacy-root <path>] [--current-issue-updated-at <time>] [--current-issue-body-digest <digest>]
review-orchestrator task-research discover --target <normalized target> --repo <owner/repo> [--state-root <path>] [--legacy-root <path>]
review-orchestrator issue workflow-family-status --workflow-kind <kind> --workflow-id <id>
out 未指定時の既定 root は workflowstate.DefaultRoot() 配下の repo identity scoped user state root とし、artifact set は repositories/<repo-key>/artifacts/task-research/<id> に保存する。repo-key は repository identity の storage key digest から作る path segment で、Git worktree の cwd や一時 tmp/ の寿命に依存させない。
明示 out=<dir> は後方互換の escape hatch として維持する。out 指定時はその directory に artifact set を作るが、manifest / handoff には machine-local absolute path ではなく repo 相対 path または state-root-relative ref を残す。
既存の tmp/task-research/<id> artifact set は legacy fallback 候補として扱う。自動で移動・削除せず、research-packet=<path> や future discover flow が明示的に候補として読む場合だけ使う。
research=auto は task-research と github-issue-breakdown の Issue 化前 flow の default である。
research-mode=single は実行方式の default であり、既存の単一 context 調査に相当する。
research-mode=parallel は read-only worker を複数起動して観点別に調べる実行方式であり、research=deep などの調査深度とは別に扱う。推奨するのは research=deep の時だけで、light / standard / spike では明示指定または上位 workflow の理由がある場合に限る。
research-packet=<path> は既存 task-research-packet.v1 を read-only discovery の入力として読む指定である。research-packet=auto は既存 packet path ではなく、downstream skill が review-orchestrator task-research discover の candidate_state と candidates[].candidate_status を使う明示 opt-in selector である。未指定 default では packet を暗黙消費しない。grill-me が生成する grill-packet.json も schema_version: "task-research-packet.v1" の互換 packet として扱い、task-research と downstream skill の research-packet= に渡せる。
互換表記として [research-packet=<path>] は既存 packet の直接指定、[research-packet=auto] は discovery selector を意味する。
既存 packet を読む場合は、実行前に review-orchestrator task-research validate --packet <path> を通す。既存 packet から新しい packet を作る場合は、新しい packet を検証する時に --prior-packet <old-packet> も渡す。validator は prior packet の chosen_by: "user" decision を category + decision の exact match で照合し、新しい packet 側でも chosen_by: "user" として残っていない場合は blocked にする。
入力 packet の source_facts[]、candidate_files[]、existing_contracts[]、decisions[]、unresolved_questions[]、validation_commands[] は新しい packet の根拠にできるが、chosen_by: "user" の decision は凍結済みとして上書きしない。
入力 packet に high-impact な chosen_by: "agent" decision または handoff に影響する unresolved_questions[] が残る場合は、question_adequacy_audit.passed=false かつ required_before_handoff[] に入れ、下流実装や起票へ進める前に /grill-me research-packet=<path> で interview に戻せる形にする。
research-mode=parallel の worker 数は固定値にしない。明示指定がなければ resolved_depth から light=1、standard=2、spike=1、deep=必要な観点数に応じて 3 以上 に解決し、research-workers.json に worker_count_source: "auto_by_depth" と理由を残す。deep でも runtime 上限までの起動は強制せず、呼び出し側の AI Agent が調査観点とリスクから必要数を判断する。明示 override では worker_count_source: "explicit" とする。
明示 research-mode=parallel で worker を起動できない、または worker が timeout / unavailable になった場合は成功扱いにしない。timeout は短くせず、既定目安を 30 分程度、machine-readable artifact では timeout_seconds >= 1800 とする。
agent=auto|codex|claude|copilot は downstream validation selector であり、handoff=github-issue-breakdown では github-issue-validation に渡す起票前 validation agent selector、handoff=implement-from-plan では plan validation agent selector として扱う。task-research 自身の調査 Agent や review selector ではない。
fix-github-issue と implement-from-plan は、未指定 default では packet を読まず、research=auto|light|standard|deep|spike、research-packet=<path|auto>、または task-research handoff=... が生成した resume command で明示された場合だけ packet を読む。
research-packet=auto は downstream skill ごとの明示 opt-in discovery である。fix-github-issue は --issue join、github-issue-breakdown と implement-from-plan は --target join を使う。implement-from-plan の join target は Issue 番号ではなく、skill に渡した自由文要求文の normalized target とする。
discover 結果は task-research-discovery.v1 の candidate_state と candidates[].candidate_status を source of truth にし、candidate_state=single かつ唯一の候補が candidate_status=current の時だけ採用する。candidate_state=none は packet なし通常 flow、ambiguous / stale_or_invalid_only は自動採用せず下流 flow を開始する前に停止する。
既存 packet または handoff を読む場合は、実装・起票・plan 作成へ進む前に review-orchestrator task-research validate で artifact shape と handoff safety を確認する。
この validator は artifact の最低限の正しさだけを確認し、github-issue-validation、issue readiness、plan readiness、PR 前 simplify、multi-review の成功証跡としては扱わない。
task-research から managed Issue 作成 family へ進む workflow では、resume や完了判定に review-orchestrator issue workflow-family-status の issue-workflow-family.v1 JSON projection を使う。research packet、handoff、validation、Issue create / post-create / sub-issue link / parent finalization の各 evidence が durable workflow state 上で未解決なら、自然言語 summary や local path の存在だけで success にしない。manual create-effect flow で family state envelope がない場合は、create-effect / post-create / link-sub-issue / finalize-parent-body の stdout JSON と GitHub API 確認を source of truth にする。
Artifact roles
| artifact | schema_version | 役割 |
|---|---|---|
research-plan.json |
task-research-plan.v1 |
調査対象、requested / resolved depth、調査方法、打ち切り条件 |
research-packet.json |
task-research-packet.v1 |
下流 skill が再利用する research result |
research-workers.json |
task-research-workers.v1 |
research-mode=parallel の worker report。下流互換のため packet とは分ける |
research-brief.md |
なし | 人間が確認する要約 |
handoff.json |
task-research-handoff.v1 |
target skill、resume command、packet path、消費済み option |
artifact-manifest.json |
task-research-artifact-manifest.v1 |
artifact set 全体の paths / refs、packet digest、target、created_at、validation status |
artifact-index.json |
task-research-artifact-index.v1 |
repo-scoped user state root 配下にある artifact set の索引 |
research-plan.json
必須 field:
| field | type | 内容 |
|---|---|---|
schema_version |
string | task-research-plan.v1 |
id |
string | artifact set の ID |
repo |
string | owner/repo。repo 不明の場合は空文字ではなく unresolved question に戻す |
target |
object | kind, value, url を持つ調査対象 |
requested_depth |
string | auto|off|light|standard|deep|spike |
resolved_depth |
string | off|light|standard|deep|spike |
reasons |
array[string] | resolved depth の理由 |
research_methods |
array[string] | 実行した read-only 調査 |
required_outputs |
array[string] | depth に応じて必須になった output |
stop_conditions |
array[string] | 調査を止める条件 |
research=off は明示 no-op とし、research-plan.json、research-packet.json、research-workers.json、research-brief.md、handoff.json は作らない。
research-packet.json
必須 field:
| field | type | 内容 |
|---|---|---|
schema_version |
string | task-research-packet.v1 |
id |
string | plan と同じ ID |
repo |
string | owner/repo |
target |
object | kind, value, url を持つ調査対象 |
source_facts |
array[object] | 一次情報。source, fact, evidence を持つ |
candidate_files |
array[string] | repo 相対 path |
existing_contracts |
array[string] | 既存 contract / docs / tests |
recommended_approach |
string | 採用案と理由 |
alternatives |
array[string] | 代替案 |
implementation_sketch |
array[string] | 下流が draft / brief / plan に使える実装イメージ |
decisions |
array[object] | category, decision, chosen_by, evidence, impact |
unresolved_questions |
array[object] | 下流が質問へ戻すべき事項 |
question_adequacy_audit |
object | passed, reasons, required_before_handoff。任意で intent_policy_categories |
risk_flags |
array[string] | requires_spike, requires_split, requires_issue_revision など |
validation_commands |
array[string] | 下流の validation 候補 |
新規 artifact は上記の最小 shape を使う。validator は移行互換として existing_contracts[]、recommended_approach、implementation_sketch の legacy object shape も parse error にはしないが、空値は reject する。
worker dispatch の plan 粒度
実装 runtime tier の初版は実行形態に固定し、モデル名や能力を自動判定しない。
| 実行形態 | tier | 追加の plan 粒度 |
|---|---|---|
fix-github-issue の orchestrator 直接実装 |
high | Issue の契約、受け入れ条件、通常の readiness を使う |
| agent-team の Claude Code Agent worker | high | current research packet の通常 validation を使う |
| agent-team の Codex worker | low | candidate_files 1 件以上、implementation_sketch の fenced code block 1 件以上、validation_commands 1 件以上 |
low tier の必須項目が不足する場合、dispatch は worker request や worktree を作らず、missing_items と refine_plan_or_use_same_tier を返す。既定の代替は、計画を作成した runtime と同じ tier で実装し、機械的な作業だけを low tier worker に渡すことである。判定は field と code fence の有無に限定し、自然文の品質は評価しない。
この gate は current research packet の execution artifact を評価し、Cosense design doc の作成判定とは独立している。design-doc=auto|off で page を省略した Issue でも low tier の必須項目は省略できず、design doc の有無を合否に使わない。粒度不足だけを理由に page を追加せず、packet を具体化できない場合は refine_plan_or_use_same_tier に従う。
object field の最小 shape:
| object | 必須 field |
|---|---|
target |
kind, value, url。val は使わない |
source_facts[] |
source, fact, evidence |
decisions[] |
category, decision, chosen_by, evidence, impact |
question_adequacy_audit |
passed, reasons, required_before_handoff |
candidate_files は repo 相対 path のみ許可する。
decisions[].chosen_by は user|source_text|agent のいずれかにする。
高影響な UX / data format / public API / config format / scope 判断を chosen_by=agent のまま下流実装へ渡す場合、question_adequacy_audit.passed=false にして unresolved_questions[] へ戻す。
question_adequacy_audit.intent_policy_categories[] を使う場合は、各 category を ux_visible_behavior、data_format、public_api、config_format、scope、other のいずれかにし、同じ category の decisions[] か category 名を含む source_facts[].fact で裏付ける。
research-workers.json
research-mode=parallel の時だけ作成する。worker report は packet の required shape に混ぜず、coordinator が cross-check した集約結果だけを task-research-packet.v1 へ投影する。
必須 field:
| field | type | 内容 |
|---|---|---|
schema_version |
string | task-research-workers.v1 |
id |
string | plan / packet と同じ ID |
repo |
string | owner/repo |
research_mode |
string | parallel |
worker_count |
number | 実際に起動した worker 数。worker_reports[] の件数と一致させる |
worker_count_source |
string | auto_by_depth または explicit |
worker_count_reason |
string | worker 数を選んだ理由 |
timeout_seconds |
number | worker 全体または worker ごとの既定 timeout。1800 秒以上を目安にする |
worker_reports |
array[object] | worker ごとの report |
synthesis |
string / array / object | coordinator の cross-check 結果、矛盾、裏取り不足、packet へ投影した要約 |
worker_count_source=auto_by_depth の場合、worker_count は plan の resolved_depth に対応する。light=1、standard=2、spike=1 は固定し、deep は呼び出し側の AI Agent が必要な観点数を判断する。ただし deep の最低数は 3 とし、validator は runtime 上限まで起動したかどうかを要求しない。research-workers.json を検証する時に worker_count_source=auto_by_depth を使う場合は、validator に --plan も渡して resolved_depth と照合できるようにする。
worker_count_source=explicit はユーザーまたは上位 workflow が worker 数を指定した場合だけ使い、理由を worker_count_reason に残す。
worker_reports[] の最小 field:
| field | type | 内容 |
|---|---|---|
name |
string | worker 名または観点名 |
focus |
string | 調査観点 |
status |
string | success|blocked|timeout|unavailable |
findings |
string / array / object | worker の調査結果 |
status が blocked、timeout、unavailable の worker がある場合、明示 research-mode=parallel は成功扱いにしない。silent single fallback は行わず、stop reason として packet / brief / handoff に残す。
artifact-manifest.json
artifact-manifest.json は artifact set の machine-readable index であり、packet や handoff の成功証跡ではなく、保存場所と staleness 判定材料を固定する。
必須 field:
| field | type | 内容 |
|---|---|---|
schema_version |
string | task-research-artifact-manifest.v1 |
id |
string | artifact set ID |
repo |
string | owner/repo |
target |
object | kind, value, url |
artifact_root_ref |
string | state root relative ref。例: repositories/<repo-key>/artifacts/task-research/<id> |
created_at |
string | artifact set 作成時刻 |
packet_digest |
string | research-packet.json の digest |
validation_status |
string | success|blocked|error|unknown |
artifacts |
array[object] | artifact paths / refs / digest / status |
target が既存 Issue の場合は、staleness 判定用に issue_updated_at と issue_body_digest も必須にする。PR URL や自由文 target ではこの 2 field を必須にしない。
artifacts[] の最小 field:
| field | type | 内容 |
|---|---|---|
name |
string | plan, packet, brief, handoff, workers など |
path |
string | artifact set root からの相対 path |
ref |
string | state root relative ref |
digest |
string | artifact content digest |
status |
string | present|missing|generated|validated |
path は artifact set root からの相対 path に限定し、absolute path、空 path、.. を含む path は使わない。ref と artifact_root_ref は state root relative ref に限定し、/Users/...、/tmp/...、repo 外 path は使わない。
artifact-index.json
artifact-index.json は repo-scoped user state root 配下で複数 artifact set を発見するための lightweight index である。review-orchestrator task-research discover は manifest と legacy fallback を read-only に列挙し、packet 本文を stdout JSON に含めない。
必須 field:
| field | type | 内容 |
|---|---|---|
schema_version |
string | task-research-artifact-index.v1 |
repo |
string | owner/repo |
artifact_sets |
array[object] | artifact set entries |
artifact_sets[] の最小 field:
| field | type | 内容 |
|---|---|---|
id |
string | artifact set ID |
target |
object | kind, value, url |
artifact_root_ref |
string | state root relative ref |
manifest_ref |
string | manifest の state root relative ref |
created_at |
string | artifact set 作成時刻 |
packet_digest |
string | research-packet.json digest |
validation_status |
string | success|blocked|error|unknown |
index は artifact の実体を移動しない。legacy tmp/task-research/**/research-packet.json を候補に含める場合も、entry は fallback 候補として明示し、破壊的な移行済みとして扱わない。
discovery result
review-orchestrator task-research discover は stdout に task-research-discovery.v1 の JSON を出力する。repo-scoped user state root の repositories/*/artifacts/task-research/*/artifact-manifest.json と legacy tmp/task-research/*/artifact-manifest.json を read-only に列挙する。
既存 Issue 向けの join key は、repo identity、canonical issue number / URL、packet digest、research 時点の issue updatedAt と body digest で構成する。Issue 起票前の join key は、repo identity と明示された normalized target digest で構成する。title 類似、branch 名、candidate files overlap だけでは exact match にしない。
result は status、next_required_action、repo、target、join_key、candidate_state、candidate_count、searched_roots[]、candidates[] を持つ。candidate_state は none|single|ambiguous|stale_or_invalid_only のいずれかで、0 件、1 件、複数件、stale / invalid だけの状態を機械判定できる。
candidates[] の最小 field:
| field | type | 内容 |
|---|---|---|
id |
string | artifact set ID |
artifact_root_ref |
string | state root relative ref または legacy fallback ref |
manifest_ref |
string | manifest ref |
packet_ref |
string | packet ref。packet 本文は返さない |
packet_digest |
string | packet content digest |
target |
object | kind, value, url |
validation_status |
string | manifest の success|blocked|error|unknown |
candidate_status |
string | current|stale|invalid |
stale_reasons |
array[string] | issue_updated_at_mismatch、issue_body_digest_mismatch など |
invalid_reasons |
array[string] | packet_digest_mismatch、packet_schema_invalid、validation_status_blocked など |
join_key |
object | 候補ごとの join key |
research-packet=auto では candidate_state=single かつ唯一の候補が candidate_status=current の時だけ採用する。candidate_state=none は packet なしの通常 flow に進む。ambiguous、stale_or_invalid_only、または single でも current 以外の候補しかない場合は自動採用せず、ask_user / stop として扱う。採用後も task-research validate と必要な grill gate、fix-github-issue の readiness、github-issue-breakdown の起票前 validation は省略しない。
staleness 判定の一次基準は、現在の issue updatedAt または body digest が research 時点の値と一致しないこと、または packet digest / schema / validation status が manifest と一致しないことである。discover は packet 本文や private context を GitHub に書かない。
validator result
review-orchestrator task-research validate は stdout に task-research-validate.v1 の JSON を出力する。
| exit code | JSON status | 意味 |
|---|---|---|
0 |
success |
指定 artifact は validator を通過した |
2 |
blocked |
schema / path / handoff safety の finding があり、下流へ進めない |
1 |
error |
artifact を読めない、JSON として不正、または command 実行エラー |
result は status、next_required_action、artifacts、findings[] を持つ。
findings[] は code、message、field、severity、artifact を持つ。任意 field として、undefined_enum では allowed_values、invalid_field_type では expected_type を返す。
validator は早期 return せず、検出できた finding を findings[] にまとめて返す。入力 artifact を直す側は、先頭 1 件だけでなく配列全体を見て一括修正する。
validator は artifact の修復や生成を行わず、packet が既存 gate の代替として使われたかの runtime 判定もしない。
--prior-packet が指定された場合、prior packet の user decision が新しい packet へ exact carry-over されていなければ code: "user_decision_missing" を返す。
question_adequacy_audit.intent_policy_categories[] に未裏付けの category があれば code: "intent_policy_category_uncovered" を返す。
high-impact category（ux_visible_behavior / data_format / public_api / config_format / scope）の decisions[].chosen_by が agent のまま question_adequacy_audit.passed=true または passed 未設定なら code: "high_impact_agent_decision" を返す。question_adequacy_audit.passed=false の packet は question_audit_failed または question_audit_without_questions で扱い、この finding を重複して返さない。
--manifest と --index が指定された場合、task-research-artifact-manifest.v1 / task-research-artifact-index.v1 の必須 field、state-root-relative ref、artifact set relative path、validation status enum を検証する。
grill-gate result
review-orchestrator task-research grill-gate は stdout に task-research-grill-gate.v1 の JSON を出力する。
| exit code | JSON status | next_required_action | 意味 |
|---|---|---|---|
0 |
success |
proceed |
下流の readiness / validation へ進める |
2 |
blocked |
run_grill_me_or_set_grill_skip |
deep / spike 相当の research で未確認の high-impact 判断が残るため、/grill-me または明示 grill=skip が必要 |
2 |
inconclusive |
provide_grill_artifacts |
--plan / --packet 欠落、artifact 読み取り不能、schema 不整合などで判定できない |
2 |
inconclusive |
fix_grill_mode |
--grill-mode が skip 以外の非空値 |
1 |
その他 | なし | command 実行または未知 status の error |
--plan は task-research-plan.v1 の research-plan.json を指す。--packet は同じ artifact set の task-research-packet.v1 を指す。
--grill-mode skip が指定された場合は plan / packet を読まず success / proceed を返すが、呼び出し元は grill_mode: "skip" を handoff / checkpoint / resume command に残す。
呼び出し元ごとの --plan は次の通りに扱う。
| 呼び出し元 | --plan に渡す artifact |
|---|---|
github-issue-breakdown |
task-research が作成した research-plan.json |
fix-github-issue |
task-research が作成した research-plan.json。fix-github-issue の implementation brief は渡さない |
implement-from-plan |
task-research が作成した research-plan.json。implement-from-plan が packet から後で作る plan.json は渡さない |
既存 packet や grill-packet.json だけを受け取り、対応する research-plan.json がない場合、grill-gate は inconclusive / provide_grill_artifacts として扱う。この場合は plan を持つ artifact set を指定し直す、task-research を再実行して plan / packet を揃える、またはユーザー明示の grill=skip を使う。
handoff.json
handoff=... が指定された場合だけ作成する。
必須 field:
| field | type | 内容 |
|---|---|---|
schema_version |
string | task-research-handoff.v1 |
target_skill |
string | github-issue-breakdown|fix-github-issue|implement-from-plan |
research_packet_path |
string | repo 相対 path。machine-local absolute path は使わない |
research_packet_ref |
string | 任意。user state root 配下 packet の state root relative ref |
resume_command |
string | ユーザーが実行できる下流 command |
consumed_options |
array[string] | handoff が消費した option |
blocked_options |
array[string] | target skill が消費できず停止した option |
unresolved_questions |
array[object] | resume 前に解消する質問 |
parallel_candidates |
array[object] | 自動起動しない並列候補 |
blocked_options が空でない場合、handoff は成功扱いにしない。
parallel_candidates は通知用であり、下流 skill は自動で複数 worker を起動しない。
handoff=github-issue-breakdown agent=claude のように validation agent が明示された場合、handoff.json は resume_command に agent=claude を残す。agent= は downstream option なので consumed_options[] には入れず、値が auto|codex|claude|copilot のいずれかなら blocked_options[] にも入れない。
handoff=implement-from-plan agent=claude でも同じく、agent= は implement-from-plan の plan validation selector として resume_command に残し、consumed_options[] と blocked_options[] には入れない。
handoff=fix-github-issue では agent= の消費先がないため、blocked_options[] に記録して handoff を停止する。
Downstream consumption
task-research
task-research は research-packet=<path> で既存 task-research-packet.v1 を読む。
grill-me の grill-packet.json は新規 schema ではなく同じ packet として扱い、review-orchestrator task-research validate --packet <path> を通したうえで、追加調査や handoff=... の入力にできる。
入力 packet の source_facts[] と decisions[] は新しい packet の evidence として参照し、入力 packet の path / id を追跡できる source_facts[] を残す。
chosen_by: "user" の decision は凍結済みとして保持し、task-research が上書きしない。high-impact な chosen_by: "agent" decision や handoff に影響する unresolved_questions[] は、question_adequacy_audit.passed=false かつ required_before_handoff[] に戻して、必要なら /grill-me research-packet=<path> で確認する。
新しい packet を出力した後は review-orchestrator task-research validate --packet <new-packet> --prior-packet <input-packet> を実行し、user decision の消失を program 側で検出する。
direct user confirmation
high-impact な未確定事項は /grill-me へ戻すのが既定だが、現在の会話でユーザーが十分に直接回答できる場合は軽量確認として扱える。
その場合は質問と回答の対応、確認日、回答者がユーザーであることを evidence に残し、decisions[] へ chosen_by: "user" として記録する。
この直接確認は grill gate を弱めるものではない。確認後も task-research validate、必要な grill gate、下流 readiness / validation gate を再実行する。
github-issue-breakdown
github-issue-breakdown は research=auto|off|light|standard|deep|spike と research-packet=<path|auto> を受け付ける。
Issue 起票前 flow で research-packet=auto が指定された場合は、明示 target digest を使って review-orchestrator task-research discover --target <normalized target> --repo <owner/repo> を呼ぶ。candidate_state=single かつ唯一の候補が candidate_status=current の時だけ packet を採用し、none は packet なし通常 flow、ambiguous / stale_or_invalid_only は自動採用せず停止する。
Issue draft 作成前に packet の source_facts、candidate_files、existing_contracts、recommended_approach、alternatives、implementation_sketch、unresolved_questions、validation_commands を読み、Issue 本文の判断材料、Mermaid、擬似コード、Rules / Examples / Questions に反映する。
research=auto は Issue 化前 flow の default とし、既存の intent-policy inventory と起票前 validation は維持する。
task-research から渡された agent=auto|codex|claude|copilot は、github-issue-breakdown の起票前 validation agent selector として resume_command から読み、github-issue-validation に渡す。task-research はこの option を自分の調査 depth や reviewer selector として解釈しない。
research artifact を持つ flow では、Issue draft 作成前に review-orchestrator task-research grill-gate --plan <research-plan.json> --packet <research-packet.json> [--grill-mode skip] を実行する。
既存 packet を research-packet=<path> で読む場合、または research-packet=auto で採用した packet を読む場合は、Issue draft 作成前に review-orchestrator task-research validate --packet <path> を通す。
grill-packet.json も task-research-packet.v1 互換 packet であれば同じ入口から読める。
明示 packet を使って Issue を作成した場合は、作成された issue number / URL と packet manifest の binding を repo-scoped local workflow state または artifact に記録する。GitHub Issue body / comment / label には local state key、hidden marker、local absolute path を書かない。
fix-github-issue
fix-github-issue は、明示 research=auto|light|standard|deep|spike または research-packet=<path|auto> の場合だけ packet を読む。research=off は明示 no-op として packet を作らない。
research-packet=auto が指定された場合は、claim gate 後、implementation brief 作成前に review-orchestrator task-research discover --issue <issue> --repo <owner/repo> を呼ぶ。candidate_state=single かつ唯一の候補が candidate_status=current の時だけ packet を採用し、none は packet なし通常 flow、ambiguous / stale_or_invalid_only は実装開始前に停止する。
packet は claim gate 後の read-only discovery で読み、source_facts、candidate_files、existing_contracts、recommended_approach、alternatives、implementation_sketch、decisions、unresolved_questions、validation_commands を implementation brief の evidence / decisions の根拠として使う。
packet の facts は repo identity scoped user state root の artifacts/fix-github-issue/issue-ISSUE_NUMBER/task-ledger-ISSUE_NUMBER.md、または legacy tmp/fix-github-issue/task-ledger-ISSUE_NUMBER.md の changed surfaces、contract sync、non-goals、acceptance、validation commands、E2E status、review scope、rerun scope へ転記できるが、task ledger や packet は readiness / review の代替ではない。
既存 packet を research-packet=<path> で読む場合、または research-packet=auto で採用した packet を読む場合は、readiness brief 作成前に review-orchestrator task-research validate --packet <path> を通す。
research artifact を持つ flow では、readiness gate 前に review-orchestrator task-research grill-gate --plan <research-plan.json> --packet <research-packet.json> [--grill-mode skip] を実行する。ここで渡す --plan は task-research の research-plan.json であり、fix-github-issue の implementation brief ではない。
claim gate、issue readiness、capability preflight、readiness-checkpoint は省略しない。
implement-from-plan
implement-from-plan は、明示 research=auto|light|standard|deep|spike または research-packet=<path|auto> の場合だけ packet を読む。research=off は明示 no-op として packet を作らない。
research-packet=auto が指定された場合は、plan draft 作成前に implement-from-plan に渡した自由文要求文を normalized target として review-orchestrator task-research discover --target <normalized target> --repo <owner/repo> を呼ぶ。candidate_state=single かつ唯一の候補が candidate_status=current の時だけ packet を採用し、none は packet なし通常 flow、ambiguous / stale_or_invalid_only は plan 作成前に停止する。
packet の source_facts、candidate_files、existing_contracts、recommended_approach、alternatives、implementation_sketch、decisions、unresolved_questions、validation_commands から tmp/implement-from-plan/<id>/plan.md と plan.json の draft を作る。
task-research から渡された agent=auto|codex|claude|copilot は、implement-from-plan の plan validation selector として resume_command から読み、plan validation に渡す。task-research はこの option を自分の調査 depth や reviewer selector として解釈しない。
packet の facts は repo identity scoped user state root の artifacts/implement-from-plan/PLAN_ID/task-ledger.md、または legacy tmp/implement-from-plan/PLAN_ID/task-ledger.md の changed surfaces、contract sync、non-goals、acceptance、validation commands、E2E status、review scope、rerun scope へ転記できるが、task ledger や packet は readiness / review の代替ではない。
既存 packet を research-packet=<path> で読む場合、または research-packet=auto で採用した packet を読む場合は、plan draft 作成前に review-orchestrator task-research validate --packet <path> を通す。
research artifact を持つ flow では、plan validation / plan readiness 前に review-orchestrator task-research grill-gate --plan <research-plan.json> --packet <research-packet.json> [--grill-mode skip] を実行する。ここで渡す --plan は task-research の research-plan.json であり、implement-from-plan が packet から後で作る plan.json ではない。
plan validation、plan readiness、plan readiness-checkpoint は省略しない。
Stop conditions
question_adequacy_audit.passed=falseかつ unresolved question が下流の完了条件や high-impact decision に影響する。resolved_depth=spikeで、実装や Issue draft の acceptance を定義できない。- packet の candidate file が repo 外 path、空 path、または
..を含む。 - target skill が消費できない option が
blocked_options[]に残る。 research-mode=parallelの worker が unavailable / timeout / blocked になった。research-mode=parallelのworker_countがworker_reports[]の件数と一致しない。worker_count_source=auto_by_depthなのにworker_countがresolved_depthの規則と一致しない。research-mode=parallelの timeout 目安が 1800 秒未満になっている。- packet が readiness / validation / simplify / review の省略理由として使われている。
この contract は、自然文の調査メモを下流に渡すためではなく、調査の十分性、未解決質問、handoff 境界を artifact として固定するために存在する。
Research / Issue creation family の完了判定では、issue-workflow-family.v1 projection の next_required_action を source of truth にする。skipped、unknown、validation timeout、未 reconcile effect は success に丸めない。