architecture-loop

Architecture Loop（調査と改善を収束まで再帰反復するオーケストレーター）

architecture-review(調査)と architecture-fix(改善)を1周として、収束するまで何周も回す上位スキル。 ゴールは 構造品質を「基準(品質ゲート)に到達するまで」自動で引き上げつつ、暴走せず安全に止めること。

本スキルは review/fix の中身を作り直さない。両スキルを部品として呼び出し、周回・状態・停止を司る オーケストレーターである。1周の中身(観点別監査・wave 分割・並列適用・段階検証)はそれぞれのスキルに委ね、 本スキルは「何周するか・次に何を直すか・いつ止めるか・回帰したらどうするか」というループ制御に責任を持つ。

いつ使うか

• 「レビューと修正を繰り返して / 収束するまで直して / 指摘がなくなるまで回して / 自動で改善し続けて」
• 「品質ゲート(critical/high 0 件など)を満たすまでリファクタして」
• 「オーケストレーターで review→fix を回して」「再帰的に調査と改善して」
• 大きめの技術的負債を、1回のレビュー+適用では返しきれず、複数周回で段階的に減らしたいとき。

単発でいいなら本スキルは不要: 1回評価するだけなら architecture-review、出した JSON を1回適用するだけなら architecture-fix。新機能をゼロから作るなら feature-build。繰り返しが要るときだけ本スキルを使う。

中核アイデア

1. 1イテレーション = review → 対象選定 → fix → 検証 → デルタ測定。これを固定の手順で回す。
2. 収束で止める: 品質ゲート達成 / 進捗の頭打ち(デルタ閾値割れ) / 反復予算の消尽 のいずれかで停止。
3. 状態を周回間で引き継ぐ(台帳): 各 finding を applied / failed / deferred / wontfix で台帳管理し、 失敗・wontfix を無限に再挑戦しない(振動の防止)。次周の review はこの台帳を踏まえる。
4. 壊れたら止める: どの周でも検証が赤化(回帰)したら、その wave を切り戻し、ループを停止して報告する。 緑を確認した周だけをコミットとして積む。

進め方（5フェーズ）

Phase 0 — ゴール・収束条件・予算の確定（ループの契約を先に固める）

ループは「いつ止まるか」を先に決めないと暴走する。着手前に停止条件を契約として固定する。 詳細は references/loop-control.md を読む。最低限これを決める:

• スコープ: リポジトリ全体 / 特定パッケージ / 特定の関心事(性能・テスト・依存方向など)。曖昧なら全体。
• 品質ゲート(収束の定義): 例「critical=0 かつ high=0」「対象観点の指摘が N 件以下」。これが第一の停止条件。
• 反復予算: 最大イテレーション数(既定 5)。安全弁としての絶対上限。予算は必ず有限にする。
• 進捗閾値(頭打ち判定): 1周で解消した critical+high が閾値(既定 1)未満なら「これ以上は逓減」として停止。
• 適用ポリシ: 各周で直す対象(既定 now+next の critical/high。later/低優先は最終周以降 or 対象外)。
• 適用前ゲート(壊れた状態でループを始めない):
  • git 作業ツリーがクリーンか確認。未コミット変更は退避/コミットを促す。
  • main 等の保護ブランチ上なら作業ブランチを切る(refactor/arch-loop 等)。
  • ベースラインの検証が通ることを確認(各スキルの references/verify.md)。最初から赤なら先に切り分け。
• イテレーション成果物の置き場: arch-loop/iter-<n>/ に各周の review JSON とサマリを残す(履歴=収束の証跡)。

Phase 1 — 1イテレーションを定義する（review → fix の合成）

1周の中身は 既存2スキルの合成。本スキルは順番と受け渡しだけを定義する。詳細な合成手順・状態の 受け渡し・差分スコープのかけ方は references/orchestration.md を読む。1周の標準フロー:

1. 調査(review): architecture-review を起動し、構造化 JSON を arch-loop/iter-<n>/review.json に出す。
   • 2周目以降は 前周の台帳を入力にし、wontfix/恒久 failed は再掲しない/低信頼に落とすよう指示。
   • 効率化のため、2周目以降は 前周で変更した範囲＋未着手領域に焦点を当ててよい(数周に1回は全体を再スイープ)。
2. 対象選定(select): review JSON の findings から、適用ポリシに従って今周で直す集合を選ぶ (既定 critical/high の now+next)。台帳で failed(原因未解消)/wontfix は除外。
3. 改善(fix): 選んだ findings を architecture-fix に渡し、wave 分割→並列適用→各 wave 検証→ グループコミットまで実行させる(中身は fix スキルに委譲)。
4. 検証(verify): 周末に全体検証(ビルド/型/リンタ/テスト/スモーク)。赤なら 回帰として Phase 2 の停止へ。
5. 記録: 適用済/失敗/スキップを台帳に反映し、arch-loop/iter-<n>/summary.json にメトリクスを残す。

Phase 2 — 収束判定（続けるか・止めるか）

各周末に必ず判定して次の周に入るか決める。判定ロジックと指標は references/loop-control.md を読む。 停止条件(いずれか1つでも満たせば停止):

• 収束(成功): 品質ゲート達成(例 critical=0 かつ high=0)。→ これがゴール。
• 頭打ち(逓減): 今周の「解消した critical+high」が進捗閾値未満。これ以上回しても費用対効果が低い。
• 予算消尽: 反復予算(最大イテレーション数)に到達。
• 回帰(失敗): 周末の全体検証が赤、かつ当該 wave の切り戻し後も赤のまま → 即停止して切り分け報告。
• 振動(失敗): 同一 finding が解消されず周をまたいで出戻る/同じファイルを行き来して純増がない → ループでは解けないと判断して停止(台帳で検出、references/loop-control.md)。

続行する場合のみ n = n+1 で Phase 1 に戻る。判定なしで次周に入らない(暴走の防止)。

Phase 3 — ループのオーケストレーション（Workflow）

Phase 1〜2 の周回を Workflow ツールで決定論的に回す。雛形は references/workflow-template.md を読んで埋める。 構造(イテレーション = barrier。次周は前周の検証 PASS とコミット後に開始):

• ループ本体は for (n of 1..budget) で、各周 review → select → fix → verify → 収束判定 を実行。
• 各 step は 既存スキルの実行に委譲する(review は review スキル、適用は fix スキルの wave 実行)。
  • 本体は周ごとに review JSON とメトリクスを受け取り、台帳と進捗デルタを更新する。
  • 周内の fix は fix スキルの Workflow(wave barrier)で並列適用される。本スキルは周境界の barrier を担う。
• 緑を確認した周だけコミットを積む(コミットは周/wave 単位、refactor(arch): iter<n> <要約> 形式)。
• 収束判定で停止条件を満たしたら break。判定をスキップして回し続けない。

Phase 4 — 統合レポート（収束の軌跡を示す）

ループ終了時に周をまたいだ推移をまとめる(単発レポートではなく、収束の証跡を見せるのが本スキルの価値):

• 停止理由: 収束 / 頭打ち / 予算消尽 / 回帰 / 振動 のどれで止まったか。
• 収束カーブ: 各周の severity 別件数(critical/high/medium/low)と principle coverage の推移(減っているか)。
• 周ごとの実績: 適用済/失敗/スキップの finding.id、コミットハッシュ、検証結果。
• 残課題: 未解消の finding(deferred/failed/wontfix)とその理由。ループで解けないものは手動対応として明示。
• 次の一手: まだ予算や価値が残るなら次に回すべき対象、止めたなら人手で判断すべき項目。

原則（なぜそうするか）

• ループは契約を先に固める(最重要): 品質ゲート・反復予算・進捗閾値を着手前に決める。停止条件のない 自動ループは暴走する。有限予算＋ゲート＋頭打ち判定の三重で必ず止まるようにする。
• 再実装しない(合成する): 1周の中身は review/fix に委譲し、本スキルは周回・状態・停止だけを司る。 各スキルの改善が自動でループにも効く(単一責務・DRY)。
• 状態を持って賢く繰り返す: 台帳で applied/failed/deferred/wontfix を追跡し、失敗・wontfix を再挑戦しない。 次周の review はこれを踏まえる。素朴な再実行は同じ指摘を無限に出し続ける(振動)。
• 進捗で止める: 解消デルタが閾値を割ったら逓減と見なし止める。0 件を狙って無限に磨き続けない(YAGNI)。
• 壊れたら止めて切り分け: 各周/各 wave で検証し、緑の周だけコミット。赤化(回帰)したら切り戻して停止。 壊れた状態で次周に進まない。
• 証跡を残す: 各周の review JSON・メトリクス・コミットを残し、収束の推移を後から検証可能にする。

参考ファイル

• references/loop-control.md — 収束条件・反復予算・進捗(デルタ)指標・頭打ち/回帰/振動の検知・台帳の持ち方。Phase 0/2 で読む。
• references/orchestration.md — review→fix の合成手順、周回間の状態受け渡し、差分スコープ・対象選定、failed/wontfix の扱い。Phase 1 で読む。
• references/workflow-template.md — ループの Workflow 雛形(イテレーション barrier・周内の review/fix 委譲・収束判定・コミット)。Phase 3 で読む。
• (委譲先) architecture-review / architecture-fix の各 SKILL と references — 1周の中身(監査・wave 適用・検証)はこれらに従う。