タスクと状態

プロジェクトとタスクの構造、有効なレーンと稼働状態の組み合わせ、エピック・下書き・アーカイブとの関係を説明します。各項目の詳細は共有ファイルにあります。

プロジェクト

プロジェクトは、名前と不変なProjectId（作成時に生成する32桁の小文字16進文字列）を持つ作業単位です。各プロジェクトはボードを一つだけ持ちます。プロジェクト横断のボードや、プロジェクト間のタスクの移動・コピーはありません。

• 名前は前後の空白を除いて1〜50 Unicodeスカラー値、1行で、大文字・小文字を区別した完全一致で一意です。プロジェクト一覧は名前順です。
• 名前変更とinitではProjectIdは変わりません。削除したProjectIdは再利用しないので、同じ名前で作り直したプロジェクトは別のプロジェクトです。
• タスクID・レーン内のposition・EPIC-IDはプロジェクト内の値です。対象のプロジェクトを、省略・作業フォルダ・Webの選択から推測しません。
• nextTaskIdは1から始まり、削除やinitの後もリセットされず、増え続けます。作成に失敗した場合も、予約済みの番号は再利用しません。
• initはID・名前・nextTaskIdを保ち、タスクとエピックを空にします。プロジェクトの削除はそのフォルダ全体を消し、ほかのプロジェクトには触れません。

変更の検知には三つの値を使います。versionは1プロジェクトの正本ファイルから計算し、順序を持ちません。catalogVersionは、同じ方法でプロジェクト一覧の変更を識別します。cursor（f1:<ProjectId>:<version>）はwaitが使う値で、名前変更後も同じProjectIdを追い、別のプロジェクトへは移りません。

レーンと稼働状態

レーンは作業がどこにあるかを、稼働状態はエージェントがそれに対して何をしているかを表します。有効な組み合わせは限られます。

担当	レーン	有効な稼働状態
ai	todo	idle、pending
ai	doing	idle、running、pending
ai	done	idleのみ
human	すべて	idleのみ

• Runningは自己申告で、生存監視ではありません。自動で戻ることはなく、エージェントもセッションの開始や中断だけを理由に変えません。
• Pendingはエージェントが人の判断を待っている状態です。その間もほかのタスクを進めてかまいません。
• 無効な組み合わせは保存しません。下書きのタスクは、どのレーンでもIdleかPendingです。

操作によって状態は次のように変わります。

• 作成はタスクをTodo・Idleでレーンの末尾に置き、作成を履歴に記録します。本文がなければ空のacceptanceと空の本文を書き、指定した本文はfrontmatterの検証を通します。
• 列移動はactorが必須で、reasonは任意です。タスクは移動先のレーンの末尾に置きます。実際の移動では稼働状態をIdleに戻し、未回答の依頼を取り下げ（取り下げは回答ではありません）、履歴を追加し、taskStatusChangedAtを更新します。同じレーンへの移動は何も変えません。
• 稼働状態の変更はactorが必須で、レーンは変わりません。AI担当のTodoはIdle↔Pending、AI担当のDoingはIdle・Running・Pendingの間の変更を受け付けます。同じ状態の再申告は変更ではありません。
• 編集で変わるのはタイトル・本文・受入条件だけで、担当は変わりません。CLIの--desc・--desc-fileはファイル全体を受け取りますが、保存済みの最新のTASK.mdの履歴を保ちます。epic edit --document-fileはEPIC.mdの全文を置き換えます。Web画面はbodyとacceptanceを送り、ロックの中で最新のファイルに適用します。
• エピックの所属はepicIdを設定または解除します。実際に変わったときだけ履歴を追加します。下書きやアーカイブ済みのタスクでも人は変更できます。
• 削除はタスクのフォルダを消します。Web画面はアーカイブ済みのタスクだけを削除し、CLIは端末での確認を求めます。

通常の更新では、後から保存した内容が優先され、内容の照合や編集ロックはありません。最新のtask.jsonと照らして書き込みロックの中で検証するのは、回答の照合、下書きへのAIの書き込み、アーカイブ済みへの書き込み、一括アーカイブの対象だけです。

エピックと進行順

エピックは、タスクをまとめて進行と作業順を管理する単位です。エピックの詳細（EPIC.md）には、目的・範囲・判断などをMarkdownで書きます。タスクは最大で一つのエピックに所属でき、所属の正本はタスクのepicIdだけです。エピック側はタスクの一覧を保存しません。

項目	規則
id	EPIC-ID。[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*に合う1〜64文字。小文字の入力は大文字にする。変更不可。
name	前後の空白を除いて1〜100文字、1行。
color	#RRGGBB（大文字）。省略時は作成時に乱数で決める。
isDraft	準備中のエピックの印。所属タスクには影響しない。
document・body	frontmatterを含むEPIC.mdの全文（0〜100,000文字）と、frontmatterを除いた本文。
priority・priorityError	所属タスクIDの作業順と、その読み込みに失敗したかどうか。

• タスクはepicIdだけを保存し、ラベルの色と名前は取得時に解決します。
• アーカイブ済みを含め、いずれかのタスクが参照しているエピックは削除できません（epic_in_use）。Web画面ではエピックの編集画面からDELETE .../epics/{epicId}で削除します。CLIではepic rmを使います。
• 新しいプロジェクトには、既定のエピックBUGとENHANCEMENTが最初からあります。どちらも通常のエピックなので、編集も削除もできます。プロジェクトにこれらを用意し終えるとproject.jsonのdefaultEpicsSeededが設定されるので、削除した既定のエピックが作り直されることはありません。serveは、このフラグがまだないプロジェクトに一度だけ用意します。
• エピックには管理対象の受入条件はありません。参考条件は本文の通常のMarkdownで、APIはエピックへのacceptanceの入力を拒否します。
• priorityはEPIC.mdのfrontmatterにあるタスクIDのリストで、例えばpriority: [24, 26, 25]です。重複や型の誤りは保存時のエラーです。所属しなくなったIDは表示から除き、次の保存で取り除きます。記載のない所属タスクは作成順で後に続きます。進行順の変更はDoneのタスクの編集に当たりません。レーン内のpositionは、エピックの作業順序には影響しません。

下書き

下書きは、人がまだ書いているタスクです。

• 人がWeb画面でisDraftを切り替えます。下書きにできるのはIdleかPendingのタスクだけで、Runningは拒否します。実際に変わると履歴を追加しますが、updatedAtは変えません。
• CLIのedit・mv・state・history addは、書き込みロックの中でisDraftを確かめ、task_is_draftで失敗します。読み取り・add・人によるWebの操作は影響を受けません。時間の経過によって下書きが自動で確定されることはありません。
• Webの編集は下書きのタスクだけを受け付けます。finalizeを指定すると、本文・タイトル・isDraft=false・履歴を一組で確定します。
• 下書きのTASK.mdの直接編集は製品では止められず、READMEとエージェントのスキルで編集しないよう伝えます。

アーカイブ

• アーカイブでは、レーン・isDraft・epicId・positionを保ち、稼働状態をIdleに戻し、依頼を取り下げ、updatedAtを更新します。レーンとtaskStatusChangedAtは変わりません。Web画面のアーカイブと復元は、固定の理由Archived by user.とRestored by user.を記録します。
• 復元したタスクは元のレーンの末尾に置きます。
• 通常のスナップショット・ls・Hookは未アーカイブのタスクだけを返し、show IDはアーカイブ済みも表示します。アーカイブ済みへの書き込みはtask_archivedで失敗しますが、画像は読めます。アーカイブ一覧はarchivedAtの新しい順です。

並び順と日時

• PCのボードとCLIでは、TodoとDoingはpositionの昇順、Doneはpositionの降順です。モバイルのDone一覧はtaskStatusChangedAtの新しい順です。完了順を履歴から推測しません。APIのtasksはID順で、画面が表示用に並べ替えます。エピックはEPIC-ID順です。
• 保存とJSONの日時は、厳密にYYYY-MM-DDTHH:MM:SSZの形のUTC文字列です。時差表記（+00:00も）と小数秒は拒否します。表示はMM/DD HH:mmで、CLIは実行環境、画面はブラウザのローカル時刻を使います。