Ratchet Loop — 実行エンジン
あなたはラチェットバックログを実行しています。契約は前進のみです:アイテムは「完了・検証・コミット済み」であるか、「未完了」であり、台帳がその理由を正確に記載しています。その中間はあなたの実行に残りません。
バックログファイルが唯一の状態源です。あなたはステートレスです。毎回の実行を、前回とは異なるエージェントが行ったものとして扱ってください(多くの場合それが事実です)。重要な情報はすべてファイルに記録し、あなたの内部記憶には残さないでください。
最初に実行ルールを読み込んでください。 この SKILL.md が存在するフォルダ内の executor-rules.md を読み込んでから、どのアイテムにも触れないでください — 現場での実行から抽出された13の拘束力のある、厳密に従うべきルールです。ルールとあなたの直感が矛盾する場合は、ルールに従ってください。
呼び出し
/ratchet-loop [path] [--lane NAME] [--max-items N] [--only ID[,ID...]] [--verify inline|fresh] [--dry-run]
path— バックログファイル。デフォルト:ratchet/BACKLOG.md、存在しない場合はリポジトリルートのBACKLOG.md。どちらもない場合は、その旨を報告し、/ratchet-auditまたは/ratchet-backlog createを提案してください。解決されたパスが以降のバックログファイルであり、そのディレクトリがループの状態ディレクトリ(デフォルトratchet/)です。--lane NAME— v2 バックログのみ(v1 ファイルの場合はエラー):Lane: NAMEを持つアイテムのみを対象とし、状態をlanes/NAME.mdにのみ書き込みます。これは並列セーフモードです — 以下の「v2 バックログ — レーン」を参照。--laneは状態セレクターであり、ルーティングではありません:ハイステークスゲートの--only要件を満たすことはありません。--max-items N— この実行で終端状態に達するアイテムが N 個になったら停止します。--only— 対象を指定された ID に制限します(依存関係は引き続き尊重されます)。また、ハイステークスゲートが必要とする明示的ルーティングシグナルでもあります — 以下を参照。--verify— 検証モード。「検証モード」を参照。デフォルトはinline。--dry-run— フェーズ 0 のみ実行:検証、実行計画と実際の実行で行われる復旧を報告し、何も書き込まずコミットしません。
状態ファイル。 以下では、台帳とジャーナルはすべて状態ファイルに書き込まれます:v1 ではバックログファイル自体。v2 ではレーンファイル lanes/<lane>.md であり、バックログファイルは読み取り専用です。
フェーズ 0 — 事前確認(スキップ禁止、順序変更禁止)
- バックログファイルを完全に読み込み、構造を検証します: 上部近くのバージョンマーカー — 正確に
<!-- ratchet:v1 -->または正確に<!-- ratchet:v2 -->(:laneを含むマーカーは、レーンファイルを指していることを意味します — 拒否して実際のバックログを指してください)。v1 の場合、4 つのセクションすべて(## Items、## Ledger、## Journal、オプションで## Global checks)。v2 の場合、## Lanes+## Items(+ オプションで## Global checks)、バックログに Ledger/Journal はなし、さらに以下の「v2 バックログ — レーン」の v2 構造チェック。ID は[A-Z]+-\d+形式で一意。すべてのアイテムに Spec と 1 つ以上の Acceptance 基準がある。アイテムごとに Ledger 行がある(v2:レーンファイル内のLane:名で指定)ステータスは許可されたセット(todo/in-progress/done/blocked/needs-human/skipped)のいずれか。構造的に壊れている → 停止し、正確な問題を報告し、/ratchet-backlog validateを提案。不正なファイルについては決して推測しないでください。構造を壊さないアイテムレベルの欠陥(古い証拠、ゲートのないアイテムの実行不可能な基準)は、ファイルを拒否するのではなく、そのアイテムを駐車することで後で処理されます。(完全な契約:docs/backlog-format.mdin the ratchet repo;必要なチェックはここにリストされているものです。) - クリーンなワーキングツリーを要求します — ループ状態の例外を除く。
git statusは、追跡ファイルに対するステージング済みまたは未ステージングの変更がないことを示す必要があります。見つけた汚れを分類します:- 自分自身の状態 — v1:バックログファイルと状態ディレクトリ。v2:自分のレーンファイルのみ。Untracked → ユーザーの汚れではありません;ステップ 3 でコミットされます(v1 では、これがキュレーターが新しく書き込んだバックログが履歴に入る方法です)。Dirty だが追跡対象 → 以前の実行(クラッシュ、または未同期の sha バックフィル)によって残された状態;ジャーナルに 1 行記録し、ステップ 3 にコミットさせます。
- v2 のみ — 自分に属さないものは決して自分でクリーンアップしない。
BACKLOG.mdは読み取り専用なので、決して「以前の実行状態」ではありません:dirty tracked → ウィンドウ外の人間による編集またはマージのデブリ → 停止して報告。Untracked(バックログまたはレーンファイル)→ キュレーターの出力がコミットされていません;これは統合ブランチ上でのみ問題なく、ステップ 3 が v1 とまったく同様にratchet: add backlogとしてコミットします。レーンブランチ上で、untracked 状態はバックログがコミットされる前に起動されたことを意味します → 停止(「最初に統合ブランチにバックログをコミットしてください」)。別のレーンのファイルで、dirty またはin-progress行を保持しているもの:2 回目の実行がこのワークツリーを使用している可能性があります → 停止(「並列実行の可能性があります — 各レーンに独自のワークツリーを割り当ててください」)。決してコミットしたり、回復したりしないでください。レーンワークツリー内の dirty または untracked なNEXT.md:そのまま正確に放置し(ステージングもコミットも決して行わない — 統合ブランチ専用です)、レポートに記載します。 in-progressの Ledger アイテムに属する dirty なソースパスはクラッシュデブリであり、ステップ 3 で処理されます — ジャーナルの末尾とアイテムの Evidence/Spec を介して属性を特定します;属性が曖昧な場合は、停止してユーザーに問い合わせてください。- その他の dirty な追跡ファイル → 停止してユーザーに問い合わせます(ユーザーの作業をあなたが隠すことはできません)。この不変条件が、障害回復を安全にします。
- v2 — レーンの存続性を今、書き込みの前に判断します。 レーンの実行マーカーを読み取ります —
--laneが指定するもの、またはシーケンシャルモードで最初に作業するレーン(「v2 バックログ — レーン」を参照)。Closed → これは新しい実行です。Open、現在のブランチを指定 → クラッシュデブリ;既存のマーカーの下で続行します。Open、別のブランチを指定 → レーンが別の場所で稼働中である可能性があります:停止。その後、これがデフォルトレーン実行または--laneなしのシーケンシャル実行の場合、バリア前提条件 — 他のすべてのレーンがクローズかつマージされていること — を検証し、満たされていない場合はここで拒否します。このステップでのすべての拒否は、ステップ 3 が何かを書き込む前に行われるため、開始すべきでない実行はマーカーを残しません。
- 回復し、その後回復を 1 回コミットします。
in-progressでスタックしている Ledger 行は、クラッシュした実行からのデブリです — v2 では、自分のレーンファイル内の行のみ;別のレーンのin-progressは並列実行中である可能性があり、あなたが触れることは決してありません。そのような行ごとに:ステップ 2 で属性が特定されたソースパスを正確に元に戻します(実行ルール 9)(残っている場合);found in-progress from a crashed run — reset to todoとジャーナルに記録;行をtodoに戻します。これが実行エンジンが許可する唯一の後方ステータス変更であり、事前確認時のみです。次に、ステップ 2~3 で触れたすべてをカバーする1 つのコミットを作成します — 初回実行状態(ratchet: add backlog)または回復(ratchet: recover state)。v2 では、同じコミットにレーンの開始ジャーナル行も含まれます。これはステップ 2 で見つかったものに依存します:新しいレーンは- <date> run started (lane <name>, branch <branch>)を取得します;自分のブランチで open と見つかったレーンは- <date> found open run from <date> — presumed crashed, recoveringを取得し、2 つ目のrun startedはありません(既存のものがまだレーンの開始マーカーであり、run endedがそれをバランスします)。コミットするものが他にない場合は、その行だけをratchet(<lane>): run openとしてコミットします。v1 では、ステップ 2~3 で何も見つからなかった場合、コミットするものはありません。 - 台帳とジャーナル全体を読み取ります — v2 では、それはすべてのレーンファイルの台帳とジャーナルを意味し、自分のものだけではありません(あなたは 1 つのレーンに書き込み、すべてを読み取ります)。ジャーナルはあなたの遺産です — 以前の試み、既知のトラップ、失敗した仮説。ジャーナルが失敗したと言っていることを、新しい理由なしに再試行しないでください。
- グリーンベースラインを確立します。
## Global checksの下のすべてのコマンドを決定論的な形式で 1 回実行します — コールド状態、インクリメンタルキャッシュなし、実行中の開発サーバーの生成された型への依存なし(ウォームなtsc --noEmitは、CI が実行するようにコールドで実行された同じチェックが赤である間に、緑を報告する可能性があります)。Global check がキャッシュに敏感に見え、バックログがそれを固定していない場合は、自分でコールドフォームを実行し、不一致を Journal に記録します。赤いベースライン → 停止して報告します(壊れた開始点からラチェットを進めることはできません) — ただし、[BASELINE]タグの付いたアイテムが存在し**、かつそれがあなたの実行対象である場合**(v1:常に;v2:そのLane:が--laneと一致する、または--laneが指定されていない)は除きます。その場合、そのアイテムがファイル順よりも優先される必須の最初の選択肢です。v2 の--lane X実行で、[BASELINE]アイテムが別のレーンに属している場合、停止して報告します:「<ID>がレーン<Y>でベースラインをブロックしています — 先にそのレーンを実行し、マージしてから再起動してください」。待機は停止であり、別のレーンへの書き込みではありません。 git log --oneline -15からリポジトリのコミット規則を検出します(Conventional Commits? 平文の文? スコーププレフィックス?)。それに合わせます。- ブランチを確認します。 リポジトリのデフォルトブランチにおり、リポジトリが PR ベースまたはプッシュトゥデプロイの場合、最初のコミットの前に作業ブランチ(
ratchet/<scope-or-date>)を作成することを提案します —/ratchet-shipは後で PR を開きます。ユーザーの明示的な許可がある場合のみ、デフォルトブランチで続行します。v2 の--lane X実行では、ブランチは選択肢ではありません:ratchet/Xが存在すれば再開し、存在しなければ統合ブランチの先頭から作成し、統合ブランチより遅れている場合はマージします — 「v2 バックログ — レーン」を参照。 NEXT.md(状態ディレクトリ内)が存在すれば読み取ります。 それは/ratchet-recommendからのルーティング計画です:アイテムごとの検証割り当てを尊重します — SUPERVISED または SENIOR にルーティングされたアイテムには--verify freshが必要です。fresh が有効でない場合、この実行で実行されるはずだった SUPERVISED/SENIOR アイテムのみを駐車します(それらは適格であり、--onlyと一致します);この実行の範囲外のアイテムはそのまま残されます — それらのウェーブコマンドは既に適切なフラグを運んでいます。NEXT.md が最後の Ledger 変更(v2:自分のレーンファイルへの最後の変更)より古い場合は、古くなっていると言い、再生成を提案します — v1:通常どおり状態ディレクトリ内;v2:統合ブランチ上、レーンワークツリー内では決してありません。呼び出し元からの明示的なフラグは NEXT.md より優先されます。v2 では読み取り専用:NEXT.md を書き込んだり、ステージングしたり、コミットしたりすることはありません。- 計画を発表します: 適格なアイテムを順番に、駐車されたアイテムとその理由、ブランチ、有効な停止条件。
--dry-runの場合は、ここで停止します — ドライランは何も書き込まないため、ステップ 2~3 で行われたはずのコミットを報告し、それらを作成しません。したがって、ドライランはレーンを開きません:run startedマーカーは書き込まれずコミットされないため、その背後にレーンが開いたままになることはありません。
適格性
アイテムは、すべてが成立する場合に適格です:Ledger ステータス todo · 人間のゲートタグなし([USER-DECISION]、[OPS]、[RISKY]) · すべての Depends: ID が done(v2:クロスレーンの依存関係は、ワークツリーに表示される done 行としてのみカウントされます — 完了しマージされている) · --only が指定されている場合は一致 · --lane が指定されている場合は一致。適格なアイテムをファイル順に取得します。すべての --only ID が存在するが、呼び出されたレーンの Lane: を運んでいない場合、それはエラーです(「SEC-01 はレーン ui にあります — --lane ui を付けて再実行するか、NEXT.md を再生成してください」)、黙って「バックログが空」とはなりません。人間ゲート付きの todo アイテム:その Ledger ステータスを needs-human に設定し、タグをメモとして追加し(1 回)、次に進みます。駐車されたアイテムは、人間が駐車を解除するまで駐車されたままです — ステータスを todo に戻し、ゲートタグを削除し、決定をジャーナルに記録します(フォーマットの「人間による遷移」手順);これを自分で行うことはありません。
ハイステークスゲート(機械的)。 アイテムの Spec または Evidence がトリガーリスト(実行ルール 1 からの正確な文言)のいずれかに触れる場合、そのアイテムはハイステークスです:auth/permissions、テナント境界(companyId / 所有権スコープ)、支払いまたは金銭計算、GL/仕訳転記、データベースマイグレーション、シークレット/env、ファイルまたは行の削除、またはセッション/クッキー処理。ゲートされていないハイステークスアイテムは、両方が成立する場合にのみ実行可能です:(a) --verify fresh が有効である、かつ (b) 呼び出し元がそれを --only に明示的にリストしている — つまり、人間または NEXT.md ルーティングがこの実行のためにそれを選択した。--lane は決して (b) としてカウントされません。そうでない場合は、needs-human として駐車します(メモ:「ハイステークス;/ratchet-recommend 経由でルーティングしてください」)。例外:[BASELINE] アイテムは --only 要件から免除されます — そのタグが人間のルーティングであり、実行はそれなしでは続行できません — ただし、トリガーリストに触れ、fresh が利用可能な場合は、fresh 検証を使用してください。自分がどのモデルであるかについての自己評価は行いません — フラグが決定します。認証や資金に関する誤った「緑」は、Ratchet が防止するために存在する最も高価な障害です。人間の一瞥のコストは常に低くなります。
v2 バックログ — レーン
v2 バックログ(<!-- ratchet:v2 -->)は状態をレーンごとに分割します:バックログは ## Lanes + ## Items(各アイテムは Lane: <name> を持つ)を保持し、各レーンの Ledger + Journal は lanes/<lane>.md に存在します — 単一ライターであるため、並列エージェントが同じファイルに書き込むことはありません。完全な契約:docs/backlog-format.md §5 を ratchet リポジトリで参照;実行エンジンに必要なものはすべて以下にあります。
v2 構造チェック(事前確認ステップ 1 の追加)。 次のいずれかで停止:## Lanes がない;最初のレーンの Scope がリテラル (rest) でない、または別のレーンも (rest) を主張している(デフォルトレーンは正確に 1 つ);名前付きレーンスコープの重複;Lane: がない、または宣言されていないレーンを指定しているアイテム;宣言されたレーンで lanes/<lane>.md が欠落している、またはその <!-- ratchet:v2:lane <name> --> マーカーがファイル名と宣言に一致しない;どこにも Ledger 行がないアイテム、間違ったレーンファイルにある行、またはファイル間で重複した行。レーンファイルを作成することはありません — それはキュレーターの仕事です(/ratchet-backlog)。--lane X 実行での拒否範囲:バックログ、lanes/X.md、または X 自身のアイテムの行居住性の欠陥は停止です;別のレーンファイルに限定された内部損傷は大きな警告です — 報告し、決して触れないでください。
実行マーカー(生存信号)。 レーンは、その Journal をボトムアップでスキャンしたときに、最初に見つかった実行マーカーが run started である場合、open です。実行は、作業しようとしているレーンに - <date> run started (lane <name>, branch <branch>) を追加してコミットすることで、そのレーンを開きます(事前確認ステップ 3、または ratchet(<lane>)...)。
レーンの開始と終了。 実行は、作業しようとしているレーンに - <date> run started (lane <name>, branch <branch>) を追加してコミットすることで、そのレーンを開きます。--dry-run はこれをスキップします — マーカーは書き込まれず、レーンは開いたままになりません。実行が終了したら(成功または停止のいずれか)、- <date> run ended — <outcome> でレーンを閉じます。クローズとマージのバリアは、run ended の後にのみ通過できます。
シーケンシャル実行(--lane なし)。 すべてのレーンを、## Lanes セクションで宣言された順序で処理します。各レーンを独立した実行として扱い、レーン間の遷移時にフェーズ 0 を完全に再実行します。レーン内の各アイテムは、通常の適格性チェックを通過する必要があります。
レーン間の依存関係。 アイテムは、Depends: リストで指定された、別のレーン内のアイテムに依存できます。依存関係は、依存先のアイテムが done 状態(完了し、統合ブランチにマージされている)の場合にのみ満たされたと見なされます。別のレーンのアイテムがブロックされている場合、現在のレーンの依存するアイテムはブロックされたままになります。
検証モード
2 つの検証モードがあります:
inline(デフォルト): Acceptance 基準を、変更の一部として同じコミットで検証します。高速ですが、モデルがパスを偽造するリスクがあります。fresh: Acceptance 基準を、変更がコミットされた後に、新しいコンテキストウィンドウで検証します。モデルが作業を検証する際に、その作業を実行したときと同じ認知バイアスを持たないため、より安全です。--onlyのルーティングと組み合わせると、ハイステークスアイテムに必要です。
実行サイクル
適格な各アイテムについて:
- Spec を読み取り、依存関係を解決します。 依存関係がまだ存在しない場合、現在のレーン内の依存関係を最初に実行します。
- 実装します。 Spec に従ってコードを変更します。グローバルチェックを満たす必要があります。
- Acceptance 基準を検証します。
--verifyモードに応じて。 - 合格した場合: Ledger 行を
doneに更新し、Evidence を記録し、Verified: <criteria>を含めます。コミットを作成します(コミット規則に従って)。 - 失敗した場合: Ledger 行を
blockedに更新し、失敗の理由と試行した内容を Journal に記録します。コミットしません(汚れた状態を残しません)。 --max-itemsに達した場合 またはバックログがなくなった場合に停止します。
緊急停止
次の場合は直ちに停止します:
- グローバルチェックが赤くなる
- 予期しない git の汚れが見つかる
- ハイステークスアイテムがゲートを通過しようとする
- ユーザーが
Ctrl+Cを押す - 内部エラーが発生する
停止したら、理由と Journal の最終エントリを報告します。現在のアイテムは in-progress のままになります。
エイリアス
このスキルは、短いエイリアス /ratchet-loop でも呼び出すことができます(フルパス afrizzal/ratchet の代わりに)。