mas クローン + webapp_client cross-clone 同期 runbook (ADR-0159 Phase b §C-2)

ADR-0159 の 5 クローン体制 (main / doc / mas / ocr / drp) で GAS ドメインエンジン (mas/400_domain/) を SPA (webapp_client) に取り込む経路 は同一 origin / 同一 commit の共有で機能する。本 runbook は mas クローンと main クローンを跨ぐ作業順序を明示し、commit 取り違いによるドリフトを防ぐ。

対象

mas クローン (~/projects/bizlp/mas/): mas/400_domain/{442,443,444,445,447,449,451,454}_*.js を編集
main クローン (~/projects/bizlp/main/): webapp_client/scripts/sync-engines.mjs を実行して上記ファイルを webapp_client/src/engines/ へコピーし、UI ビルドへ取り込む

正本: mas/400_domain/*.js (mas クローンが editor)。webapp_client/src/engines/*.js は 生成物 (.gitignore 済) で main クローン側で再生成する。

既存 drift 検査の範囲

scripts/pre-push-check.sh L36-41 は mas/templates/{sidebar_spa_shell,financial_cockpit,multiyear_cockpit}.html の drift を検知するが、mas/400_domain/*.js と webapp_client/src/engines/*.js の不整合は検知しない (engines は gitignored で対象外)。よって本 runbook の手順遵守が同期保証の唯一の経路。

推奨手順

A. mas クローンで GAS ドメインエンジンを編集する場合

cd ~/projects/bizlp/mas
最新 main を取込: git checkout main && git pull && git checkout -b feat/<branch>
mas/400_domain/{442,443,444,445,447,449,451,454}_*.js を編集
GAS 実機で動作確認 (cd mas && pnpm run push:dev → Spreadsheet UI 動作確認・mas/CLAUDE.md feedback_deploy_sequence 準拠)
commit + push + PR

→ この時点で webapp_client は未同期。SPA UI ビルドは古い engines を使う。

B. main クローンで SPA UI に反映する場合 (A の commit 後・別 PR 推奨)

cd ~/projects/bizlp/main
必ず git fetch origin && git pull origin main で mas クローンの commit を取り込む (この一手を忘れると古い commit で sync-engines.mjs が走り、本番 HTML テンプレートと engines が乖離する)
cd webapp_client && pnpm run prebuild (= node scripts/sync-engines.mjs)
git status で webapp_client/src/engines/*.js が untracked (gitignored) のままで OK・生成物は commit しない
pnpm run build:spa + Playwright 等で UI 検証
SPA 側に手当てが必要な場合のみ webapp_client/src/** を編集 → commit + push + PR

C. atomic に同一 PR で出す場合 (UI 連動が複雑な変更)

mas 側 GAS 改修 + webapp_client 側 UI 改修が同時に必要なケース。

cd ~/projects/bizlp/mas で feat branch 作成
mas/400_domain/*.js 編集 + commit
push (origin に上がる)
cd ~/projects/bizlp/main で 同 feat branch を checkout (git fetch && git checkout feat/<branch>)
cd webapp_client && pnpm run prebuild → SPA 側 UI 修正 → commit
push → 1 つの PR で GAS 改修 + SPA 改修を同時 merge

この場合 PR title に [cross-workspace] を付与 (workspace_rules.md §例外運用準拠)。

既知の落とし穴

落とし穴	症状	予防
mas commit 後 main で git pull 忘れ	main クローンの mas/400_domain/ が古いまま sync-engines.mjs 実行 → 本番 HTML が古い engines を使う	上記 B-2 「必ず `git fetch + pull`」を順序固定。`pre-push-check.sh` の drift 検知に依存しない (engines は範囲外)
webapp_client/src/engines/ を commit してしまう	gitignored だが explicit add で git に入る → SSoT が 2 箇所になる	`.gitignore` 確認 + `git add -i` を使わず `git add` で specific path 指定
mas/400_domain/ に新規ファイル追加時	sync-engines.mjs の `ENGINES` 配列に未登録 → SPA 側に取り込まれない	`webapp_client/scripts/sync-engines.mjs` の `ENGINES` 配列に追記 + `exposes` (window 露出変数名) を IIFE と対称に揃える (`docs/spec/sidebar_api.d.ts` も並行更新)
mas クローンから webapp_client/ を編集	workspace_rules.md ファイル担当マトリクスで `webapp_client/src/**` は main 担当 → 越境	mas クローンは編集しない (例外時のみ `[cross-workspace]` PR title)。`scripts/hooks/pre_bash_guard.sh` の cwd 判定 (Phase c) で構造ガード化予定

ファイル配置 (参考)

~/projects/bizlp/main/   (main clone)
  webapp_client/
    scripts/sync-engines.mjs       ← main clone でのみ実行
    src/engines/                   ← 生成物 (gitignored)
      442_social_insurance_tier_engine.js
      ...

~/projects/bizlp/mas/    (mas clone)
  mas/400_domain/                  ← SSoT (mas clone が editor)
    442_social_insurance_tier_engine.js
    443_corporate_housing_optimizer.js
    444_per_diem_policy_engine.js
    445_required_revenue_solver.js
    447_capital_allocation_engine.js
    449_dividend_mix_optimizer.js
    451_multiyear_planner.js
    454_compensation_strategy_engine.js

対象