work

/work（別名：/ultracode、/quality-orchestrator） — 完全品質ワークフローオーケストレーター

品質パターンシステム全体を実用的かつ自動的に機能させる中心的なオーケストレーターです。

ワークフロー実行モデル（処理を振り分ける前に形を決める）

JS オーケストレーションエンジンはありません。「ワークフローモード」とは、エージェントが手動で実行する手順です。適切なサブエージェントのロールを割り当て、分離されたワークツリーでバックグラウンド実行するサブエージェントを起動し、すべての処理を待ってから、その結果を収集します。処理を振り分ける前に、必ずハーネスの todo／計画ツールまたは判断記録で形を明示してください。形は次の3つだけです。

• PIPELINE（デフォルト） — 各項目を独立して各ステージに通し、ステージ間のバリアは設けません（項目Bのレビュー中に、項目Aの検証を行います）。経過時間は、最も遅い単一項目の処理チェーンに左右されます。複数ステージにわたる品質作業のほとんどはこの形です。
• PARALLEL / BARRIER — ステージN-1のすべての処理が完了するまで待機します。これが正当化されるのは、項目間に実際の依存関係がある場合に限ります。たとえば、全項目を対象とする重複排除／統合、ゼロ件なら早期終了する処理、または項目間の比較（候補全体の判定ランキング、すべての判定結果を対象とする統合）です。「そのほうがすっきりする」は正当化になりません。迷ったらパイプラインにしてください。
• LOOP（結果が出尽くすまで／予算上限まで） — 件数が不明な作業です。新しい一意の項目がゼロとなるラウンドがK≥2回連続するまで（結果が出尽くすまで）、または次の有用なラウンドのコストを賄えない残予算になるまで（予算上限まで）ラウンドを繰り返します。各ラウンドは、処理の振り分けと、永続化された seen[] に対する重複排除バリアで構成されます。

全体のモデル（仕組み、問題を見抜くチェック、標準的なReviewハーネス）は references/workflow-mode.md にあります。これらの形で防ぐべき失敗パターンは references/anti-error-lessons.md（L1〜L8。以下の各フェーズに要約し、組み込んであります）を参照してください。ここでそれらのドキュメントを繰り返さず、参照してください。

中核となる考え方（組み込み済み）

1. 直接検証を最優先 — 決定論的なオラクル（テスト、コンパイラー、git rev-list --left-right --count、完全一致の grep と手動確認、アプリの実行、型チェックなど）がある場合は、それを使います。エージェントパネルは、適切なオラクルが存在しない領域に限って使用します。
2. 誠実な分割 — 正しさを比較的独立した状態で検証できる単位に作業を分割します。
3. 依頼に応じて規模を調整 — 小さなタスク（「main が同期しているか確認」）には直接コマンドを使います。中〜高難度の実装／レビュー／監査／設計には、フェーズ、パターン、仕組みを網羅したハーネス全体を使います。
4. 上限を黙って設けない／すべて明示 — 予算、同時実行数、観点数などに制限を設ける場合は、対象外にしたものを記録します。

反エラーの教訓 L1〜L8（このオーケストレーターが防ぐ失敗パターン）

これらは理論ではなく、実際の監査から得られたものです（根拠となった事例――/improve のインデックスがジャーナルのドリフト項目を過大評価し、実在する分離バグを誤って否定し、5つの孤立ファイルを見落とした事例――は references/anti-error-lessons.md にあります）。各教訓は上記のフェーズで運用に組み込まれています。対応箇所は次のとおりです。

• L1 — 直接オラクルを最優先 → 中核となる考え方 #1、最終ゲートでは未実行のオラクルがあれば不合格とする。
• L2 — 検証者はソースを独立して読み直す → Reviewフェーズ。契約で reReadSources[] が必須です。
• L3 — 同一の反証者をN人並べるのではなく、視点の異なるレンズを使う → Reviewフェーズ。セキュリティ／認証／マルチテナント／データ整合性／正確性では必須です。
• L4 — 生き残った項目ではなく、SEENと照合して重複を排除する → Research／Discoveryループと、リセットしないジャーナルの seen[]。
• L5 — 網羅性の確認では「SCOPEがカバーしていないのは何か」と問う → 最終ゲートでのグローバルオラクルのスコープ網羅性確認。
• L6 — 重大度を両方向から調整する → 最終ゲートの重大度基準（偽陽性と偽陰性の両方を抑制）。
• L7 — 上限を黙って設けない → 予算／同時実行の仕組みと、項目を明記する droppedDueToCaps[]。
• L8 — 必要な作業を行った場合にのみ判定を有効とする → Reviewフェーズと契約の検証（安易な反証は棄却扱いとなり、指摘は残ります）。

オーケストレーターを使用すべき場合

• 中程度または高い複雑さを伴う、実装、大規模なリファクタリング、レビュー、セキュリティ／パフォーマンス／正確性の分析、アーキテクチャ上の決定、または移行。
• プロジェクトの AGENTS.md と品質フックが、このしきい値を超えたときに通知し（可視化を強制しようとし）ます。

複雑さの低い機械的な変更では、省略するか、ごく軽量な手順を使用できます。

オーケストレーターが従う大まかな流れ

1. タスクの受付と複雑さの評価

   • ユーザーの目標を理解します。
   • シグナルを収集します（現在の git diff --stat、直近のターンで変更されたファイル、依頼文の性質（「実装」「監査」「修正」「方法の設計」など）、変動要素の数）。
   • 低／中／高に分類します。
   • 低の場合 → 直接対応し、最小限の検証を行います。判断を記録します。
   • 中／高の場合 → 完全なワークフローに進みます。

2. フェーズの選択（一般的で有用なフェーズ。オーケストレーターはこれらを連結したり、一部のみ実行したりできます）。各フェーズでは、その形式と、運用に反映する教訓を示します。

   • 理解 — PARALLEL/BARRIER：並行して調査する担当者／関連サブシステムに対する work-sweep → 領域の構造化されたマップ（判断の前にマップを完成させるためのバリア）。
   • 設計（アプローチを選ぶ場合）— PARALLEL/BARRIER：work-judge がすべての候補を順位付けします（項目横断の比較 ⇒ バリア）。
   • 調査／発見 — LOOP：work-sweep + work-exhaust を実行し、各ラウンドで seen[] と照合して重複を除去します（L4：生き残った候補ではなく SEEN と照合して重複を除去します。そうしないと、judge に却下された項目が再び現れ、ループが収束しません）。
   • 実装 — 並行エージェントがコードを変更する場合は、通常のエージェント作業を worktree 分離（分離された worktree）で行い、オラクルで頻繁に直接確認します（L1）。「N 通り試す」場合は、work-tournament を呼び出します。
   • レビュー — PIPELINE：検出（work-sweep）→ これまでに確認したすべてのものと照合して重複を除去（バリア。単純な集合演算のみ。エージェントは使用しません）→ CODE の差分では、まず work-check（オラクル優先の PASS/FAIL。保守性に関する詳細な視点は work-review に委任されます）→ 指摘が届いたらすぐに、各指摘を work-refute で検証（多様な視点）→ work-gaps。コード変更では、work-check を work-refute より先に実行します。work-review は work-check 経由で実行され、名前を指定した場合のみ呼び出されます（disable-model-invocation: true）。/work-review を直接呼び出してください。自動的には起動しません。教訓を反映します。
     • L2 — すべての検証担当者は各 file:line を再度開き、現在のソースから確認します。調査担当者が引用した証拠をそのまま受け入れてはいけません。reReadSources[] を記録します。
     • L3 — セキュリティ／認証／マルチテナンシー／データ整合性／正確性に関する主張では、異なる視点（偽造／なりすまし、設定またはレルムの混同、別のコードパス、下流への影響、リグレッション）を割り当てます。これは必須であり、任意ではありません。同一の反証担当者を N 人用意しても、多様性ではなく冗長性にすぎません。
     • L8 — refuted の判定（指摘を無効にする判定）は、workDone: true かつ reReadSources が空でない場合に限り有効です。安易な却下は棄権として扱い、フィルタリングして記録します。指摘は次のラウンドに持ち越されます。needs_oracle の判定はフェイルクローズです。判断の前に L1 オラクルを実行します。投票は証拠の重み付けに基づきます（十分な証拠のある反証 1 件は、「疑いなし」という根拠のない票 2 件より重くなります）。
   • 移行／変換 — PIPELINE：対象箇所を特定 → 分離された worktree で変換 → それぞれを検証。
   • 最終ゲート（work-gaps、PARALLEL/BARRIER）：以下の「最終ゲート」を参照してください。未実行のオラクルがあればフェイルクローズとし、重要度とスコープ網羅性の両面を確認します。

3. パターンの構成

   • オーケストレーターが各フェーズで使用する具体的なパターンを決定します。
   • 標準的なレビューのハーネス（PIPELINE。完全版は references/workflow-mode.md §2 を参照）：work-sweep → これまでに確認したすべての項目と重複排除（バリア、単純なセットロジック）→ CODE の差分の場合：work-check を最初に実行（オラクル優先の PASS/FAIL。保守性の詳細な評価は work-review に委任します）→ work-refute（生成的な場合は work-judge）→ work-gaps。コード変更では、work-check を work-refute より前に実行します。work-review は work-check を通じて呼び出され、名前を指定してのみ呼び出し可能です（disable-model-invocation: true — /work-review を直接呼び出してください）。組み合わせ可能なスキルの全一覧：work-refute、work-judge、work-exhaust、work-sweep、work-gaps、work-tournament、work-check、work-review。
   • ワークフローをネストして、別のワークフロー実行や、焦点を絞ったパターンスキルをサブステップとして呼び出すこともできます。「この変更は主張どおりの動作をするか？」といった簡単なチェックは、work-check に委任できます。

4. 実行メカニズムの適用（これらによってパターンの信頼性が高まります。表全体は references/workflow-mode.md §3 を参照してください）

   • 構造化出力＋再試行：すべてのサブエージェントは、文章ではなく、スキーマ検証済みの ```json オブジェクト（以下の契約を参照）を返します。呼び出し側は形式を検証し、出力に不備があれば一度だけ再要求します。それでも不備がある場合は、破棄して記録し、黙って受け入れることはありません。
   • ワークツリーによる分離：並行してファイルを作成または変更するサブエージェントは、それぞれ独立したワークツリーで実行します。読み取り専用のファンアウトには必要ありません。
   • null の処理（具体例）：応答しない／エラー／空の結果／棄権（L8）を返すサブエージェントは除外します（.filter(Boolean)）。投票数には含めません。除外後、残った投票者を基準に判定しきい値を再計算し、除外を記録します（判定記録と、使用しているハーネスの todo/plan ツール）。応答しない反証者 1 人を「反証」や「生き残り」として扱ってはなりません。例：3 人の検証者パネルで過半数の反証が必要な場合に 1 人が応答しなかったとき、しきい値を「残る 2 人のうち 2 人が反証」に再計算し、droppedVoters: ["v2:errored"] を記録します。
   • 同時実行数の上限：min(16, cores−2) 程度（または設定された上限）の制御されたウェーブに分けて起動します。超過分はキューに入れます。上限自体も記録します（非表示なら、それは暗黙の上限です）。
   • 予算 → 暗黙の上限を設けない（具体的な制限）：概算のトークン消費量を追跡します。予算が少なくなったら、N を減らすか、明示的に早期終了します。上限を黙って縮小してはなりません。削減内容は、判定記録に名前付きの行（droppedDueToCaps[]）として記載し、使用しているハーネスの todo/plan ツールでも提示します（例："budget: capped verify panel 5→3, dropped lenses [regression, downstream]"）。読者が「問題なし」と「途中で打ち切られた」を判別できるようにします。
   • ジャーナリング／再開：長時間の実行では、quality-journals/<task-id>.json（エージェントのデータディレクトリ配下。スキーマは以下を参照）に書き込みます。再開時には、seen[] を読み込み、決してリセットしません（L4）。これにより、却下済みの指摘が再び持ち込まれたり、調査済みの観点が再実行されたりするのを防ぎます。
   • モデル／エージェントの役割の上書き：各ステップに適したサブエージェントの役割（網羅的な調査には幅広い探索役、検証には汎用または専門のレビュアー役、設計には計画役）と、有用なペルソナを選びます。
   • log() / phase()：使用しているハーネスの todo/plan ツールを使って各フェーズと主要な判断を通知し、進行中の計画、現在のフェーズ、指摘を可視化して、人がいつでも介入できるようにします。
   • 暗黙の上限を設けない（L7）：上位 N 件への絞り込み、サンプリング、未実施の観点、スキップしたラウンド、予算による指摘の破棄、表示されなかった細かな指摘はすべて、名前付きの行（判定記録と使用しているハーネスの todo/plan ツール）に記載し、何を、なぜ破棄したのかを示します。

5. 可視性と人によるチェックポイント

   • 使用しているハーネスの todo/plan ツールを積極的に使い、進行中の計画、現在のフェーズ、主要な指摘を可視化します。
   • オーケストレーターは各フェーズの後に、担当者が確認して続行、調整、停止を判断できる明確な成果物を作成します。
   • ジャーナリングにより、「以前に開始した品質レビューを続けて」といった形で、作業の途中から再開できます。

6. 完了前の最終ゲート（PARALLEL/BARRIER — 残存項目の全体が必要です）

   • 未実行のオラクルはフェイルクローズ（L1）：残存するすべての指摘について、利用可能だが未実行のオラクル（テスト、型チェック、正確な grep と手動確認、git、アプリの実行）がないか確認します。該当するものがあれば、ゲートは done をブロックします。先にオラクルを実行し、その後に再評価します。利用可能な未実行のオラクルがある指摘は、完了とはみなされません。
   • スコープ網羅性（L5）：ファンアウトリストの対象外にある項目（孤立ファイル／未確認モダリティの分類）を洗い出すため、少なくとも1つのグローバルオラクル（リポジトリ全体でのコアエンティティの grep、スコープ網羅性の差分）を実行します。seen[] と網羅済み項目を記録します。
   • 両面からの重大度評価（L6）：残存する各指摘の重大度を、実際に確認された現実の影響に照らして再評価し、両方の誤りを防ぎます。推測にすぎない問題を high にせず、悪用可能な問題を low にしません。基準：high ＝具体的に到達可能 ＋ 有害 ＋ 現在未対策（到達可能性の根拠を示す）、medium ＝もっともらしいが未検証／オラクルなし、low ＝表面的／すでに軽減済み。
   • work-gaps は「LIST / SCOPE で網羅されていないものは何か？」と問いかけます。残る優先度の高いギャップは、未完了の todo または意思決定記録に明記するリスクとして残します。

構造化された I/O 契約（フェンス付き JSON — 必須フィールド ＋ 列挙値）

各サブエージェントは、呼び出し元が検証するフェンス付きの ```json ブロックを出力します。自由形式の文字列では評価の一貫性を保てません。severity と verdict は列挙値です。証拠は file:line と、呼び出し元が再確認できる短い引用を添えて提示します。スキルごとのスキーマは各パターンスキルに記載されています。以下は、オーケストレーターで共有する指摘の形式と、維持する記録です。

指摘ごとの契約（検証者が返す内容）

{
  "id": "host-derived-tenant",
  "claim": "string — the asserted finding",
  "verdict": "confirmed_bug | refuted | survives | needs_oracle",
  "severity": "critical | high | medium | low",
  "evidence": ["upload-handler.ts:171 — storage tenant from ?hostname, post-auth, no session binding"],
  "reReadSources": ["src/http/routes/upload-handler.ts:171"],
  "lensesUsed": ["spoofing", "alternative-code-path", "downstream-effect"],
  "workDone": true,
  "oracleAvailable": "string | null — e.g. 'read the migration runner' / null if none",
  "oracleRun": true,
  "reasoning": "string",
  "scenario": "concrete repro / why-not-exploitable"
}

呼び出し元が適用する検証ルール：refuted の verdict（指摘を棄却する verdict）は、workDone: true かつ reReadSources が空でない場合に限り有効です（L8）。そうでない場合は棄権として扱い、フィルタリングしてログに記録し、指摘は残存します。needs_oracle の verdict はフェイルクローズとなります。判断前に L1 のオラクルを実行してください（オラクル実行前に、棄却または残存として扱わないでください）。oracleAvailable != null && !oracleRun の場合、done はブロックされます（L1、フェイルクローズ）。形式不正の場合は1回だけ再要求し、その後、破棄してログに記録します。

意思決定記録（「高い確信に至った経緯」を示す唯一の情報源）

{
  "complexity": "low | medium | high",
  "complexityJustification": "string",
  "phasesDone": ["understand", "review", "final-gate"],
  "shapePerPhase": { "understand": "barrier", "review": "pipeline" },
  "patternsApplied": [
    { "phase": "review", "skill": "work-refute", "params": { "N": 3, "lenses": ["spoofing","realm-confusion","alt-path"], "K": 2 } }
  ],
  "seen": ["host-derived-tenant", "journal-drift"],
  "anglesUsed": ["storage-path", "token-issuer", "design-doc-intent"],
  "oraclesAttempted": [{ "oracle": "read the migration runner", "result": "apply path is fs scan, never reads journal" }],
  "survivors": [{ "id": "host-derived-tenant", "severity": "high" }],
  "droppedDueToCaps": [
    { "what": "lenses [regression, downstream]", "why": "budget", "where": "todo/plan tool + record" }
  ],
  "remainingGaps": ["string"]
}

ジャーナル（再開用の、エージェントのデータディレクトリ内にある quality-journals/<task-id>.json）

{
  "taskId": "audit-2026-06-14-isolation",
  "phasesDone": ["understand", "find", "verify"],
  "seen": ["host-derived-tenant", "journal-drift", "orphan-refs"],
  "anglesUsed": ["storage-path", "token-issuer", "design-doc-intent"],
  "survivors": [{ "id": "host-derived-tenant", "severity": "high" }],
  "droppedDueToCaps": [{ "what": "round 4", "why": "until-dry K=2 met", "where": "record" }]
}

再開時は、seen[] を読み込み、決してリセットしません（L4）。却下した指摘は対象外のまま維持し、調査済みの観点は再実行しません。

実例 — マルチテナント分離の監査（パイプライン＋バリア＋ループ）

/work "audit the upload + storage paths of a multi-tenant app for tenant isolation" → 複雑度は高（データ境界、判断、未知のスコープ）。

1. 把握（BARRIER）：3 人の調査担当が、認証ミドルウェア、アップロードハンドラー（ストレージ）、テナント分離の設計ドキュメントを調査します。バリアにより、判断する前に全体像を作成します。出力：サブシステムのマップ、anglesUsed += [storage-path, token-issuer, design-doc-intent]。
2. 発見（work-sweep）→ seen[] に対する重複排除バリア（単純なセット処理）。調査結果：host-derived-tenant（?hostname によるストレージの上書きと、共有 ID プロバイダーのトークン混同）、および journal-drift。
3. 検証（PIPELINE、L2/L3/L8）：各調査結果のレビューが完了するたびに検証します。
   • journal-drift：オラクルが利用可能 → マイグレーションランナーを読み込みます。適用パスはファイルシステムをスキャンしますが、ジャーナルを読み取りません ⇒ { "verdict": "refuted", "severity": "low", "oracleRun": true, "workDone": true }（誤検知を防止するL1/L6）。
   • host-derived-tenant：レンズ [spoofing, realm-confusion, alternative-code-path]。「発行者チェックで防げる」という安易な判定が、空の reReadSources とともに届きます → 棄権（L8）。フィルタリングされてログに記録され、調査結果は残ります。多角的なレンズでストレージハンドラーと設計ドキュメントを再読します ⇒ { "verdict": "confirmed_bug", "severity": "high", "reReadSources": ["upload-handler.ts:171"], "workDone": true }（見逃しを防止）。
4. 網羅性（枯れるまでループ、K=2）：テナントエンティティをグローバル検索すると、ファンアウトリストに一度も載っていない5 つの孤立参照ファイルが見つかります（L5）。それらを seen[] に追加し、ラウンド 4 で新規項目が 0 件になったため停止します。ジャーナルには droppedDueToCaps += [{ "what": "round 4", "why": "until-dry K=2 met" }] と記録します。
5. 最終ゲート：残ったすべての項目で oracleAvailable が実行済みです（L1 のフェイルクローズを通過）。重大度を再確認します（L6）。判断記録：survivors: [host-derived-tenant:high]、seen = 3 件の調査結果＋5 件の孤立項目、droppedDueToCaps は記録済み。

フックおよび AGENTS.md との統合

• プロジェクトの品質フックは、複雑な作業で重要な編集が行われた場合、または作業が完了した場合にそれを検出し、オーケストレーターの呼び出しを強く促す注釈を表示します。
• AGENTS.md には必須ポリシーが記載されています。中〜高複雑度の実装／レビュー／修正／設計／監査では、作業完了を宣言する前に、オーケストレーターを使用する（または同等の厳密さでパターンを明示的に組み合わせる）必要があります。
• オーケストレーター自体も「依頼に応じてエスカレーションする」ルールに従います。些細なタスクに大掛かりな処理を実行することは拒否し、その理由を説明します。

高レベルの呼び出し例

• 長時間の実装後：/work "review the changes I just made to the draft-generation flow for correctness, robustness, and state issues"
• 設計上の判断：/work "help me choose the right architecture for real-time updates in a kanban board"
• 全面的な監査：/work "perform an end-to-end audit of the upload-handling and SLA-calculation paths"

オーケストレーターは作業を分解し、適切なサブパターン（サブスキルとして work-refute、work-judge、work-exhaust などを呼び出す場合があります）を実行して、仕組みを適用し、根拠の追跡経路とともに信頼度の高い結果を提示します。

これは、完全な ultracode スタイルの品質システムを実用化したもので、さまざまなハーネスに移植できます。ご活用ください。