L2 CONFIDENTIAL

Factory L2 Master Spec (2026-03-24)

(更新: 2026/3/24)

Factory L2 Master Spec (2026-03-24)

Clearance: L2 / CONFIDENTIAL Audience: mtdnot (owner), CycleTree core operators Purpose: Factoryの現状仕様・構成・運用・未完了項目を辞書的に参照できる形で一本化

0. 一言定義

Factoryは、Plane起点でAI実装を自律実行し、CI結果で機械判定し、例外時のみ人間介入する開発運用基盤。

設計思想は「AIに判断させる」ではなく、判断をルール化して統治可能性を担保すること。

1. システム境界

1.1 Factoryが担う範囲

  • タスク受理（Issue/Event）
  • 実装生成（LLM）
  • CI監視・判定
  • 失敗時の自動修復ループ
  • 例外時エスカレーション
  • 実行証跡（監査ログ）

1.2 Factoryが直接担わない範囲

  • 最終戦略判断（優先順位の政治的判断）
  • 機密鍵の恒久保管責任（Vault側）
  • 組織構造の最終決裁

2. アーキテクチャ（論理）

2.1 3層構造

  1. Control Layer
  • Plane（タスク管理）
  • Inngest（オーケストレーション）
  • ポリシー/ルール（品質ゲート、エスカレーション条件）
  1. Execution Layer
  • OpenClaw Agent（実装・修正）
  • GitLab API（branch/commit/MR操作）
  • CI Pipeline（検証）
  1. Governance Layer
  • 監査ログ（実行・判定理由）
  • Grafana/Loki（観測・可視化、整備中）
  • エスカレーション通知（Discord等）

2.2 コアループ

  • Define → Execute → Validate → Commit
  • Fail時: Analyze → Auto-fix → Re-validate
  • 修復不能: Escalate to human

3. Cloud / On-Prem 分類（現状）

3.1 Cloud側

  • Plane Cloud（タスク管理）
  • Inngest Cloud（ワークフロー実行）
  • Vercel（factory-inngest APIホスティング）
  • GitLab.com（リポジトリ/Issue/MR/CI）
  • Anthropic API（実装・修正生成）
  • Grafana Cloud（観測先、運用は整備中）
  • Directus Cloud/公開環境（ドキュメント管理）

3.2 On-Prem / Local側

  • OpenClaw各Gateway（anagi/fixus/angisは別Gateway）
  • Qdrant（意味検索基盤）
  • knowledge-search Flask UI（localhost:8080）
  • ローカル運用スクリプト群（workspace）

3.3 ハイブリッド境界

  • Directus文書をQdrantへ同期し、ローカル意味検索で引く
  • Cloud実行結果（GitLab/Inngest）をローカル運用判断に反映

4. 実装済みフロー（検証済み）

4.1 GitLab Webhook → Inngest Event

  • Endpoint: /api/webhook/gitlab
  • Issue Hook で action=open かつ ai-ready ラベル時、factory/issue.ready を送信
  • Pipeline Hook で status=success 時、factory/ci.complete を送信

4.2 ai-development function（Inngest）

主処理:

  1. branch作成
  2. issueラベル更新（in-progress）
  3. 既存コード取得
  4. LLM実装
  5. commit
  6. MR作成
  7. CI待機/判定
  8. 失敗時リトライ（最大回数あり）
  9. 成功時merge、失敗時needs-human化

4.3 E2E実動確認（2026-03-24）

  • Cloud前提で実行
  • GitLab issue作成（ai-ready）
  • 自動で in-progress へ遷移
  • branch issue-21 生成
  • MR !14 自動作成

5. P0で実施した仕様強化（2026-03-24）

5.1 追加/更新ファイル

  • factory-inngest/app/event-schema.ts（new）
  • factory-inngest/config/quality-gates.yaml（new）
  • factory-inngest/scripts/p0-e2e-check.sh（new）
  • factory-inngest/app/functions.ts（updated）
  • factory-inngest/docs/p0-status-2026-03-24.md（new）

5.2 追加した仕様

  • Event schema（zod）で入力の型境界を固定
  • Quality gate最小構成（lint/test/coverage>=80）を明示
  • エスカレーション理由を構造化
    • max_retries_exceeded
    • pipeline_not_found
    • unknown_error（fallback）
  • 失敗時にIssueへ reason/retries を追記

6. クリアランス/ドキュメント運用仕様

6.1 Clearanceレベル

  • 0 PUBLIC
  • 1 INTERNAL
  • 2 CONFIDENTIAL
  • 3 SECRET
  • 4 TOP SECRET
  • 5 CLASSIFIED

6.2 公開経路

  • clearance 0: /article/[slug]
  • clearance 1+: /docs/[slug]

6.3 DocOps運用（skill化）

  • skills/factory-docops/ 配下にマニュアル化済み
  • 目的: blog/clearance/directusルールを運用手順として固定

7. 情報基盤（Knowledge/COP）

7.1 現状

  • Directus文書群（documents/scraps）
  • Qdrant embedding（意味検索）
  • knowledge-search API/UIで検索可能

7.2 意味検索API（ローカル）

  • POST http://localhost:8080/api/search
  • queryをembedding化し、Qdrant directus_documents / scraps を検索

7.3 未整備

  • 失敗イベントの自動集約ビュー
  • KPI連動のリアルタイムCOP（共通状況認識）

8. 運用モデル（複数Gateway前提）

8.1 組織前提

  • anagi / fixus / angis は別Gateway

8.2 現在ルール

  • 指示系統はanagi一本化
  • mtdnotとanagiの対話を常時維持
  • 実行は下位へ委譲（ただし認証集中で一部anagi依存）

8.3 ボトルネック

  • 認証情報がanagiに集中
  • これが委譲スループットを下げる

8.4 対応方針

  • Keycloak + Vaultで最小権限分離
  • サービスアカウント化
  • 監査可能な認可境界を作る

9. 現在の未完了タスク（優先）

9.1 近接優先

  • Discord命令テンプレからIssue自動起票ブリッジ
  • 定時進捗サマリ通知
  • 例外時即時アラート

9.2 基盤優先

  • OpenClaw連携の運用安定化
  • Plane連携の完全自動化
  • 自動修復Runbook拡充

9.3 統治優先

  • Grafana/Loki dashboard実運用
  • 認証基盤（Keycloak/Vault）本番導入

10. 4/1報告に出せる状態（定義）

必須:

  1. E2E実行証跡（Issue→MRの実例）
  2. 現在アーキテクチャ図（Cloud/On-Prem境界付き）
  3. P0実装差分一覧
  4. 次30日の実行計画（期限入り）

望ましい:

  • KPIダッシュボードの初版スクリーン
  • 自動修復成功ケース1件

11. 辞書（キーワード）

  • 機械的判断: ルール/閾値/exit code/logで判定
  • 自律実行: 通常系を人手なしで回す
  • エスカレーション: 例外時のみ人間介入
  • 統治可能性: 監査・責任追跡・再現性がある状態
  • COP: 共通状況認識（同じ現実を全員が見る）

12. 取り扱い注意

本資料はL2（CONFIDENTIAL）。

  • 外部公開不可
  • 鍵/トークン等の生値は記載しない
  • 公開資料への転記時はclearance再判定を必須とする

13. 2026-03-24 追記（実行経路の確定）

13.1 本番デプロイ実体

  • 本番 factory-inngest は Vercel project: factory-inngest
  • 最新本番コミット: 23e7f16884b33415f8e958b9a447b4f452d1cb4a
  • コミット要旨: feat: Use OpenClaw webhook instead of direct Anthropic API

13.2 実行経路（確定）

  1. GitLab Issue (ai-ready)
  2. GitLab Webhook -> https://factory-inngest.vercel.app/api/webhook/gitlab
  3. Inngest event factory/issue.ready
  4. ai-development function が https://factory.mtdnot.dev/api/implement を呼び出し
  5. OpenClaw経由で実装コード生成
  6. factory-inngest が GitLab commit / MR 作成

13.3 補足

  • workspace 配下の factory-inngest コピーは本番基準ではない場合がある。
  • 本番確認時は /home/mtdnot/factory-inngest と Vercel deployment metadata を優先する。

13.4 運用ルール

  • 仕様確認は「本番デプロイ実体 -> 実行ログ -> ローカルコピー」の順で行う。
  • 構成変更時は本書に追記して差分を残す。

(Updated: 2026-03-24T13:25:12.385610+00:00)