bassemZohdy/todo（コア）

todo（コア） は何をしますか？

このリポジトリは、既に存在するファイルから構築されたクローズドループステートマシンです。状態を保存するものは他にありません。

レイヤー	ファイル	役割	書き込みポリシー
要件	README.md, docs/*.md	真実の基点：契約、仕様、セットアップ、長期計画	読み取り中心。todo-continue の「ドキュメントのずれ」でのみ編集；計画ドキュメント（docs/plans/）は todo-init/todo-plan/todo-add/todo-update が編集；README の Tests: 行は todo-init が「はい」の場合に編集；オプションの RTM（reference/rtm.md）は todo-plan/todo-add/todo-continue が既に存在する場合のみ編集；docs/status.html は todo-report が編集
アクティブキュー	TODO.md	1つのタスクツリー。作業項目のトラッカーであり、設計の場ではない	todo-* スキルのみが編集
検証	ソースコード + テストスイート	「完了」の真実の基点	現在のタスクのためだけに変更
アーカイブ	CHANGELOG.md	永続的、追記専用（Keep a Changelog + Conventional Commits）	ルートのドレインと確認済みの /todo-release によって ## [Unreleased] のみが変更される（リリース時：バージョン名にリネーム、新しい空のセクションを上部に追加、末尾のリンク行を更新）。todo-init がファイルを作成するか、不足している [Unreleased] を追加する
チェック（オプション）	.todo/check.sh, .todo/todo-lint.sh, CIジョブ	Lint + テスト。CI、pre-push フック、/todo-continue によって実行	check.sh は /todo-init --ci が「はい」の場合に作成；todo-lint.sh はユーザーがコピー；ユーザーがコミット
バージョンストア	git	タスクごとにブランチまたはワークツリー。検証されていないものはベースブランチに到達しない	「Git モード」を参照

ファイル編集にはネイティブファイルツール（Read/Edit/Write）を推奨します。ただし、どのように編集する場合でも、意図した行のみを変更し、ファイルの最終改行を維持してください。シェルは git、テストおよび Done when コマンド、オプションのスクリプト、およびスキルが指定するファイルコマンド（cp, chmod, mkdir -p, date, grep, cmp, mv, スキル自身の一時ファイルの rm）にのみ使用してください。

バックログファイル とは、TODO.md、CHANGELOG.md、docs/plans/PROJECT.md、Ref: で指定される docs/plans/<ROOT-ID>-*.md、および todo-* スキルが書き込む README の Tests: 行と Base: 行です。README.md は、git diff README.md がそれらの行のみを追加する場合（オプションで空白行の後）に限り、バックログコミットによってステージングされます。ノードが「ドキュメントのずれ」で行う README 編集はそのノードのファイルであり、そのノードと一緒にコミットされます。その他の README 変更はユーザーのものです：クリーンツリーチェックの対象となり、バックログコミットによってステージングされることはありません。バックログの編集は、スキルが todo/ ブランチで次に行うコミット（通常はツリークレーム）まで未コミットのままであり、そのコミットで明示的なパスによってステージングされます。新しいルート、および未クレームのツリーのノードへの変更は、ベースブランチでのみ行われます。todo/ ブランチでは、スキルはそれらを拒否し、ベースブランチを指定します。クリーンツリーチェック（reference/git-flow.md）はそれらを無視します。

直接使用

/todo 単体は読み取り専用です：コマンド一覧を表示し、TODO.md が存在する場合は不変条件チェックを実行し、報告します。何も変更しません。

コマンド	目的
/todo-init	ファイルをブートストラップ、テストコマンドと git を検出、オプションの事前計画と CI セットアップ、旧形式からの移行
/todo-plan	作業をレーンとツリーに計画；いつでも計画を修正
/todo-add	タスクを追加、またはリクエストをツリーに分解
/todo-continue	次のタスクノードを実行、検証、親にマージ
/todo-update	手動の状態およびフィールドの変更
/todo-status	読み取り専用のツリー、レーン、履歴、検索
/todo-report	インタラクティブな HTML ステータスページを docs/status.html に作成
/todo-release	ユーザーが確認した後、[Unreleased] をバージョンに変換

各スキルは自身のコマンドのみを実行し、プロンプトなしに他のコマンドに連鎖することはありません。

Git モード

すべてのコマンドの開始時に git rev-parse --is-inside-work-tree を実行します。

• Git リポジトリの場合： 各ノードは自身のブランチまたはワークツリー（reference/git-flow.md）で動作します。ベースブランチ は、ユーザーが指定したもの、なければ README の Base: 行、なければ main, master, trunk, develop の最初に存在するもの、いずれもなければ1回尋ねます。ユーザーが指定したベースがそのデフォルトと異なる場合、README に Base: <branch> を追加するよう提案します（「はい」の場合に書き込みます。Tests: 行と同様のバックログファイルです）。ベースにチェックアウトまたはマージする各ステップ（ツリークレーム、クレーム解除、ベースマージ、リリース）は、メインチェックアウト（git worktree list の最初のエントリ）で実行されます。リンクされたワークツリーからは、まずそこに cd します。別のブランチに変更がある場合は停止し、コマンドを表示します。
• Git リポジトリでない場合： コマンドごとに1回警告します：「これは Git リポジトリではありません。todo スキルは引き続き動作しますが、ブランチ、ワークツリー、コミット、マージがないため、分離も履歴もありません。有効にするには git init を実行してください。」その後、no-git モードを使用します：すべての git ステップをスキップし、State:（files: を含む）で進捗を追跡し、マーカーを更新し、CHANGELOG.md にドレインします。検証は変更されません。

タグ付け、強制プッシュ、ハードリセット、clean は決して行わないでください。唯一の強制ブランチ削除は、スキル自身の未公開のクレームコミットのみを保持するブランチの削除です（reference/git-flow.md、ツリークレームのステップ2および5）。スキル自身の git コマンドはネットワークに触れません： fetch、pull、push は行いません。コミットの共有は git とあなたの仕事です。テストコマンドは依存関係をダウンロードする場合があります。ネットワーク不足で失敗した場合は、再試行せずにその理由でブロックします。

TODO.md スキーマ

# Active Backlog

## 🌳 Task Tree

正確にこの見出しと1つのセクションです。In Progress、Ready、Blocked のセクションはありません：各タスクのマーカーがその状態です。空のツリーは2つの見出しのみでタスクはありません。

タスクは 2～4行 です：何をするか、どのように検証するか、オプションのリンクと状態。

- [ ] **FEAT-002** · P1 · mid · XL · 認証サービスにトークンリフレッシュを追加
  - Done when: リフレッシュ後に古いトークンが拒否されること; `npx jest tests/auth`; リグレッション: `npm test`
  - Links: Ref: docs/auth.md#refresh · Depends: TASK-001 · From: FIX-001
  - State: branch todo/FEAT-002-add-token-refresh-auth from main; next: build children
  - [ ] **FEAT-002.1** · mid · リフレッシュエンドポイント
    - Done when: エンドポイントが統合テストでカバーされていること; `npx jest tests/auth/refresh.test.ts`
    - [/] **FEAT-002.1.1** · high · トークンストアインターフェース
      - Done when: ストアがトークンをラウンドトリップすること; `npx jest tests/auth/store.test.ts`
      - State: attempts 1/3; baseline 42 passing; branch todo/FEAT-002.1.1-token-store-interface from todo/FEAT-002.1-refresh-endpoint; next: build

パーツ	ルール
ヘッダー	- [m] **ID** · [P0-P2, ルートのみ ·] 複雑度 [· サイズ] · 何をするか、1文：複雑度は low、mid、high（必須）；サイズは S、M、L、XL（オプション）
Done when:	必須。 基準、続けて ; と少なくとも1つのバッククォートで囲まれた正確なコマンド。オプションで ; regression: \cmd``；リグレッションがない場合のデフォルトはプロジェクト全体のテストスイート
Links:	オプション。Ref: <path#anchor>、Depends: <IDs>、From: <ID>、Lane: <name>（ルートのみ）、· で区切る
State:	オプション。コンテキストリセット後も保持。項目は ; で区切り、各項目は最大1回まで、この順序：attempts n/3、baseline <n> passing（または none、または red: <失敗したテストID、カンマ区切り>）、`tier: <low
Blocked:	[!] タスクでは、State の代わりに同じ位置（最後のフィールド行）に：`<理由> → <バッククォートで囲まれたコマンド> <エラー、最大5行を