@galda/cli 0.10.17 → 0.10.20

package/CLAUDE.md

@@ -5,7 +5,20 @@
 ## テスト（Masa指示 2026-07-03・必須）
 
 - `毎回、実装したものにはテストを書いて、実行する`。
-  - engine/ の変更 → `node --test 'engine/test/*.test.mjs'` が緑になるまで完了と言わない。
+  - engine/ の変更 → `node --test --test-concurrency=1 'engine/test/*.test.mjs'` が緑になるまで完了と言わない。
+  - 🔴 **`--test-concurrency=1` は必須**（Masa報告のカオス調査で発見・2026-07-16）。既定（CPUコア数）だと
+    58ファイルが同時に実サーバと Chrome を立てて**マシンを飽和させ、同じコードで赤が毎回入れ替わる**。
+    **「テスト緑」がコードの状態でなく運を報告している状態を放置しない**＝規律の土台。
+    - **原因の半分は 2026-07-17 に構造で潰した**（PR: test-port-allocation）。各テストが
+      `4600 + (pid % 40)` 式で**ポートを手書きし隣接バンドで衝突**していた分は、`MANAGER_PORT=0`＋
+      `engine/test/helpers/start-server.mjs` に一本化して**原理的に消えた**（OSは同じポートを2つに渡さない）。
+      `multi-user-server` の「18msで全滅」はこれ。**テストで新しくポートを書かない**＝ヘルパを使う。
+    - **残る半分は資源の飽和**（実サーバ＋Chrome の総量）。実測 2026-07-17: 並列だと1回目3件赤→2回目2件赤で
+      **まだ揺れる上に遅い**（並列152秒 vs 直列135秒）。**並列に戻す根拠は無い**＝直列のまま。
+      直列は2回連続で **584 pass / 既知の赤1件** と完全一致。
+      次に上限を上げたければ、テストが実サーバを立てる設計自体（in-process 化等）を変えること。
+  - 既知の赤1件＝`persist-failure`(full-disk resilience)。**素の `origin/main` でも落ちる**（`fix/persist-log-disk-full` が未マージ）。
+    自分の変更のせいかは、素の main と比べて判定する。
   - 新しいロジックは可能な限り純関数として `engine/lib.mjs` 等に切り出し、`engine/test/` にテストを追加する。
   - テストが書けない変更（純UI等）は、その理由と手動確認手順を報告に書く。
 
@@ -21,6 +34,28 @@
 - `コミットしない`（git 操作は Manager 側の仕事。workerは編集のみ）。
 - 報告は日本語で短く：何を変えたか・どのファイルか・人間が確認すべき点。
 
+## 並行開発（Masa指示 2026-07-16・必須）
+
+- **`engine/lib.mjs` `engine/server.mjs` `app/index.html` を触る作業は、`lane start` でレーンを取ってから始める**。
+  ```
+  cd ~/agent-manager && node tools/lane.mjs start fix/<topic> --hot engine|app|none
+  ```
+  取れなければ**その場で落ちる**＝他のエージェントがそのレーンにいる。待つか `--hot none`（cold作業）へ振る。
+- **並行の上限は `hot 2 + cold N` 本**（`engine`=lib+serverで1レーン・`app`=index.html・cold=それ以外）。
+  上限が2なのはプロダクトが3つの巨大ファイルに入っているから。上げる道はファイル分割だけ（CTOの仕事）。
+- **PRの前に必ずローカルで動かす**（Masa指示 2026-07-16・スキップ不可）:
+  ```
+  node tools/lane.mjs verify --run "<実際に走らせるコマンド>" --observed "<before → after を具体的に>" [--evidence <path>]
+  ```
+  **自己申告ではなく `lane` がコマンドを実行して transcript を残す**（ワーカーの申告を信じない＝プロダクトの原則）。
+  「動いた」「works」は機械が弾く。**ユーザーに見える差分は `--evidence`（人が開けるファイル）が必須**。
+  **テスト緑はゲートではない**。動かして見たかどうかがゲート。
+- 終わりは **`lane finish`**（テスト＋**検証記録**＋PR確認＋ロック解放）。**検証もPRも無いと成功しない**
+  ＝「見込みで完了と言う」を止める。
+- 全文＝`docs/RELEASE-WORKFLOW.md` の「並行開発の運用」。
+  > 7/16 に open PR 9本中8本がコンフリクトした。原因はエージェントの数でなく、旧ルール
+  > 「面/ファイルを散らす」が**構造上守れなかった**こと。守れないルールは他のルールまで無効化する。
+
 ## トークン規律（Masa指示 2026-07-12・全レーン必読）
 
 - MUST要件＝`トークンを過度に使わない`（初の課金条件シグナル）。対話セッションは次を守る。詳細＝`docs/token-discipline.md`。
@@ -38,6 +73,13 @@
 - **`a2c-tech.workers.dev` を絶対に使わない・コードやdocsに書かない**。これはクライアント企業 **A2C** の名を冠した Cloudflare workers.dev サブドメインで、Galda の製品・URL・設定に一切登場させてはいけない（見つけたら全て除去）。
 - Worker/API へは**必ず所有ドメイン `https://galda.app`（custom domain）経由**で参照する。`*.workers.dev` サブドメインを製品コードに焼き込まない（`MANAGER_BILLING_API_URL` 等の既定値は `https://galda.app`）。
 - **Cloudflare/wrangler にデプロイする前に `wrangler whoami` でデプロイ先アカウントを確認**し、Galda/Kodo 所有であること・workers.dev サブドメイン名に客先名や別プロジェクト名が出ていないことを確かめる。怪しければ止めて Masa に確認（本番デプロイは Masa 明示許可制）。
+- **リリースは4面**（① npm ② Fly ③ Worker ④ Masaの常駐インスタンス `~/manager-for-ai`:4400）。①だけ出して④を忘れると「直したのに直ってない」＋relay相互kickループ再発の実例あり（2026-07-16/17）。全文＝`docs/RELEASE-WORKFLOW.md`の「本番は1つじゃない」表。
+
+## relay接続（`app.galda.app`）を伴う作業の掟（Masa明言 2026-07-17・全レーン必読）
+
+- **relayは1アカウント=同時1接続のみ**。同じ`MANAGER_HOME`（既定`~/.manager-for-ai`）を指す2つ目のプロセスを起動すると、実本番アカウントの接続を奪い合い、"無限ループ"（app.galda.appのリロード連打）を引き起こす。**5回繰り返した実績のあるインシデントクラス**（`docs/RUNBOOK-relay-mutual-kick.md`参照）。
+- `engine/relay-client.mjs`は2026-07-17からPIDロックで2つ目の起動を自動拒否するが、**手動検証で`node engine/relay-client.mjs`や`npx @galda/cli`を叩く時は、必ず隔離した`MANAGER_HOME`を使う**（本番の`~/.manager-for-ai`を素で使わない）。
+- 「無限ループが起きてる」と報告されたら、コードを読みに行く前に**必ず**`docs/RUNBOOK-relay-mutual-kick.md`の診断手順（`ps aux | grep relay-client`から）に従う。
 
 ## 構成