# WTR-HSW-002 OGSM v5 — Spring Hinge vs Self-Closing Hinge AIA Course

**Course Code:** HSW-002
**Document Type:** OGSM Work Plan (v5 — AI Factory Iteration Era: /ai-fallback wrap + Direction Seed knowledge queries)
**Version:** 5.0 (19 agents, first version produced by the Agent Optimization Factory's mini-agent validation run)
**Created:** 2026-04-08
**Updated:** 2026-04-11 — v5: factory-driven changes applied. All 10 raw Gemini/Codex calls wrapped in /ai-fallback (INT-001 hang resilience). Direction Seed template field 5 extended with mandatory knowledge query commands (get_patterns_for_failure.sh, get_gotchas_for_context.sh, get_skills_for_role.sh). Smoke test run on real Investigator A validated factory pattern + exposed 2 pre-scale blockers.
**Owner:** A君 (Commander Agent)
**Supersedes:** WTR-HSW-002-OGSM-v4.md (v4.0 — last human-iteration version, preserved as historical)

---

## v5 版本差異說明（相比 v4）

### 核心洞察：**v4 = 人類迭代時代的終點，v5 = AI factory 迭代時代的起點**

v4 是 4 輪人類主導討論 + 迭代的成果（Round 1/2/3）。v5 是第一個由 **Agent Optimization Factory** 驅動的版本——改動完全來自 AI mini-agent 工廠的學習，不是人類的直覺判斷。

### v5 的三組改動

**1. 10 個 raw LLM 呼叫 → `/ai-fallback` wrap**
- 10 個 agent（Investigator A/B、Fact Checker、Compliance Reviewer、Source Reviewer、4 個 reviewer、Performance Supervisor、Learning Outcome Validator）的 S/Tier 1/Model commands 原本直呼 `echo "Y" | gemini -m ... -p ...` 或 `codex exec`
- v5 全部改用 `bash ~/.claude/skills/ai-fallback/scripts/call_with_fallback.sh "prompt" "chain"` 包裝
- 原因：Mini-agent factory run 發現 `check_ai_fallback_usage.py` FAIL 10 個 agent，這是 INT-001（Gemini hang 不處理）的前置修復
- 每個 agent 的 M 同步加入 `/ai-fallback` 呼叫驗證 bullet，保持 S-to-M coverage 不退步

**2. Direction Seed 第 5 欄位擴充 — mandatory knowledge query commands**
- 新增 3 條 knowledge query commands 作為 Direction Seed 必要元素：
  - `get_patterns_for_failure.sh <failure-type>` — 查詢已知優化模式
  - `get_gotchas_for_context.sh <context>` — 查詢已知坑
  - `get_skills_for_role.sh <role-name>` — 查詢角色相關 skill 命令
- 這是 Principle 7 延伸：subprocess agents 看不到 parent memory 或 `~/.claude/skills/ogsm-framework/references/`，所以查詢命令必須 embed 到 briefing
- 觸發時機：factory bootstrap / 寫 BDD / 每次 FAIL / 套 diff 前
- 這是經驗傳承機制——未來 Iteration Team 自動繼承上一輪學到的所有 pattern + gotcha

**3. Smoke test 發現的 2 個 pre-scale blocker**（記錄在 Known Issues，v5 尚未修）
- **INT-001 incomplete**: `/ai-fallback` per-model timeout 修了，但 real production 下 Gemini Flash primary + 60s timeout 仍必定失敗。建議 system-wide default chain 改為 `flash-lite,pro,codex`，timeout 提升到 120s
- **NEW-01 (G-010) Codex trust check**: 當 Gemini chain 耗盡後 Codex 應該接手，但它拒絕「Not inside a trusted directory」。這是 fallback chain 的 silent terminal failure。解法選項：(a) pre-approve codex trust；(b) `call_with_fallback.sh` 最後層加 WebSearch fallback；(c) runbook 明示手動 pivot

### v5 的位置

v5 不是 human-final。它是：
- 第一個由 AI 工廠驅動的版本
- Smoke test 驗證 factory pattern **CAUTION GO**（GO for pattern，CAUTION for 2 blockers）
- 12-19 agent scale-up 前的最後一個 single-agent 測試版本
- v6 將會是：scale-up 到 12-19 agents 之後的版本（由 factory 平行優化所有 agent 產生）

### v5 保留自 v4 的所有內容

v4 的 Round 1/2/3 成果全部保留：
- 19-agent 架構、Skill/Model Invocation Map、Brief Layering、Anti-patterns、Direction Seed 9 欄位、Known Issues #1-5、Deferred Improvements #1-4
- S-to-M verification、Pilot Dispatch、OGSM strictness
- Candidate Collector #19（Side Channel, round 3 scope）

---

## v4 版本差異說明（相比 v3.1）

### 核心洞察：**五個新能力中，只有一個真的需要新 agent**

v3.1 在 18 → 23 agents 的擴充過程中，把五個生命週期缺口都當成「需要新角色」處理。回頭檢視後發現：

| v3.1 新增的 agent | v4 的重新分類 | 為什麼 |
|---|---|---|
| #19 Content Scout | **降級但保留為 agent** → 改名 Candidate Collector，範圍縮限為「只蒐集不寫作」 | 需要有人在波次間跨讀交付物+研究資料，寫入 queue；但不應該在 AIA 課程製作中同時寫 blog |
| #20 Post-Test Designer | **降級為 skill** → 新建 `/post-test-designer` skill | 題目設計是可重複的流程，不是新角色；由 Wave 3 HTML Engineer 在 S 中呼叫 |
| #21 Competitor Coverage Auditor | **併入現有 agent 的 M** → Compliance Reviewer 的 M 擴充 4 條 | 類別覆蓋本來就屬於 AIA 合規審查，不需要另立角色 |
| #22 Chinese Translator | **降級為 skill flag** → `/aia-rewrite --bilingual` (Phase 2 實作) | 雙語產出是 skill 能力，不是長期角色 |
| #23 SEO/AEO Engineer | **降級為流程倒轉原則** → deferred to later phase | AI 先寫 → 人類補缺，不是在課程製作期增設角色 |

**結果：23 → 19 agents。一個新 agent（#19 Candidate Collector），四個降級為 skill 或 M。**

### 為什麼這個重分類重要

**Skill 和 Agent 的邊界原則**：
- **Agent** = 持續角色（名詞），有跨時間的 G，需要記住上下文
- **Skill** = 可重複流程（動詞），可被多個 agent 在 S 中呼叫

把可重複流程當成 agent 會導致：(1) 角色數量膨脹、(2) 每個波次都要協調 context、(3) skill 的可複用性被埋沒在單一專案裡。

### 新增：**原則 7 — Embedded Skill Invocation**

subprocess agent 執行時看不到 parent Claude 的 memory 或 CLAUDE.md。所以 agent 在 S 中需要呼叫的 skill 命令**必須直接寫在 S 段落裡**——不能靠「會知道的」記憶系統。詳見下方「Principle 7」與「Skill Invocation Map」章節。

### 保留自 v3.1 的三個核心改動

**改動 1：Writer B 完全重新定位**（沿用）
- 教建築師「情境辨識能力 + 獨立 spec 資源導航」，不是教他寫 spec 語言
- 獨立 spec 資源：SpecLink、SPC Alliance、CSC/CSI 網絡——第三方中立角度

**改動 2：所有 agent 的 M 對準自己的 S**（沿用）
- 驗證 S 承諾的資源是否真的被使用，不是任務計數

**改動 3：Sales Rep Advisor 驗證資源介紹中立性**（沿用）

---

## O — Objective

> **O**: 讓建築師喜歡這份簡報並真正理解產品在做什麼。課程結束時，學員應該能獨立判斷任何門五金規格的合規性和適用性。
>
> *(English working reference: Architects leave this course having genuinely enjoyed it — and leave equipped to independently judge compliance and applicability of any door hardware specification, without needing to look it up again.)*

**首宗目標 persona：Project Architect**（不是 design architect，也不是 principal）。所有審查視角、內容假設、互動設計都以 Project Architect 的 day-to-day 工作流為基準——drawing set 審查、Division 08 寫作、spec writer coordination、AHJ 送審、RFI/submittal review。

**The two outcomes that together define success:**
1. **Emotional**: Architects want to save this course, share it with colleagues, and come back to it — not just complete it for the credit.
2. **Practical**: Architects can cite the code section, explain the mechanical difference, and catch a wrong spec — on a real project, under pressure, without Googling.

If either outcome is missing, O is not achieved.

---

## Team Structure

| Wave | Role | Agent | External? |
|------|------|-------|-----------|
| Wave 1 | Research & Draft | Investigator A, Investigator B, Writer A, Writer B, Engagement Designer | — |
| Wave 2 | Quality Review | Content Director, Compliance Reviewer *(+ competitor coverage M)*, Copy Editor, Fact Checker, Source Reviewer | — |
| Wave 2 | External Review | **Project Architect Advisor**, **Sales Rep Advisor**, **Fresh Eyes Reviewer** | YES |
| Wave 3 | Integration & Deploy | Engineer (HTML) *(invokes `/post-test-designer`)*, Commander (A君) | — |
| Side Channel | Content Pipeline | **Candidate Collector** (Wave 1→3 collect-only) | — |
| Measurement | Continuous Monitoring | Performance Supervisor, Quality Auditor, Learning Outcome Validator | — |

**19 roles total. 3 external reviewers. v4 changes vs v3.1:**
- **Kept as agent**: #19 Candidate Collector (renamed from Content Scout, scope narrowed to collect-only)
- **Reclassified as skills**: `/post-test-designer` (called by Engineer in Wave 3), `/aia-rewrite --bilingual` (Phase 2 — replaces former "Chinese Translator" agent)
- **Reclassified as M extension**: Competitor Coverage checks merged into Compliance Reviewer's M (replaces former "Competitor Coverage Auditor" agent)
- **Deferred**: SEO/AEO concerns handled via flow-inversion principle in a later phase (not in Phase 1 / v4)

---

## Individual OGSM Definitions

---

### 👑 Commander (A君)

**G（階段整合目標，串回 O）**
> 建築師在課程結束時拿到的，是一份值得推薦給同事的作品——不是因為它合規，而是因為它真的有用。Commander 的任務是讓 19 個角色都在為同一個建築師的體驗工作，而不是各自完成自己的任務清單。每一個波次結束時，都要能回答：「如果建築師現在讀到這裡，他會繼續讀嗎？他會學到他下次 spec 需要的東西嗎？」

**Tier 1 摘要（Direction Seed 必帶）**
- **G 一句話**：讓 19 個角色都在為同一個建築師的體驗工作，每個波次結束時都能回答「建築師視角存在嗎？」
- **S 一句話**：在每個波次 gate review 加入建築師視角固定問題，外部 reviewer 與內部 reviewer 隔離，使用 Pilot Dispatch 確保 briefing 正確後才並行派遣。
- **關鍵 M**：每波次產出 `gate-review-002-waveN.md`；外部 reviewer 三份報告 Wave 3 開始前完成且每個 flagged 問題都有處理記錄；Direction Seed 9 個欄位齊全。
- **Skill commands**：via central Skill Invocation Map (see §Skill Invocation Map at line 1007+), Commander's own LLM-aided decisions use `call_with_fallback.sh` (see S bullet 7 below and the commander row in `~/.claude/skills/ogsm-framework/references/skill-invocation-map.md`). For subagent skill invocations: not applicable — each subagent's S block owns its own skill commands via that central map; Commander's job is to copy those rows into Direction Seed field 5 at dispatch time, not to redeclare them here.
- **Model commands**：Claude Opus（指揮、決策、Pilot Dispatch 判斷）
- **Anti-patterns**：詳見本 agent 的「Anti-patterns 標準清單」子段落

**S（為建築師選的路徑）**
- 在每個波次的 gate review 加入一個固定問題：「建築師視角存在嗎？」——不只看交付物是否完整，也要看建築師有沒有被感受到。這個問題建築師不問，沒人會問。
- 新增三個外部 reviewer（Project Architect Advisor、Sales Rep Advisor、Fresh Eyes）在 Wave 2 並行運作，與內部 reviewer 隔離——不讓他們看到彼此的報告，確保獨立視角。
- **使用 Direction Seed Dispatch Template**（詳見下方「Direction Seed」章節）派遣每一個 subagent：**9 個欄位齊全**才派（note: v5 spec is 9 fields, not 8），缺欄位視為 briefing 失誤。這是 Principle 7 的派遣層實作——確保 subprocess agent 收到完整的 persona、O、G/S/M、embedded skill + knowledge query invocations、constraints、tone、deliverable format、anti-patterns。
- **Pilot Dispatch 是每個波次的第一步**（不是可選步驟）：先派一個 pilot subagent，Commander 親自 sanity-check 交付物後才並行派遣同波次其他 subagents。
  - **Fan-out trigger（5/5 必須全 PASS 才並行派遣其他 subagents）**：(1) persona 在交付物中是具體人物還是「an architect」？(2) 3 條 knowledge query 的 output 是否在交付物中？(3) `/ai-fallback` 執行 log 是否存在？(4) anti-patterns 是否可用字串比對驗證為 source 的 verbatim？(5) 「architect perspective present?」是否引用具體段落？
  - **Pilot FAIL 反應（3 步驟，嚴格依序）**：Step 1：根據 5/5 checklist 找出具體失敗的欄位，更新 9-field briefing（例：persona drift → 重寫欄位 2；anti-patterns paraphrased → 在欄位 9 加 "verbatim 是 hard rule" 提醒）。Step 2：**僅重新派遣 pilot，不擴散**。Step 3：只有 pilot 再次通過 5/5 才並行其他 subagents。
  - **Sanity check 不得授權**：Commander 親自做，不轉給 Performance Supervisor 或其他 subagent（見下方 Dispatch Template 的 Pilot Dispatch 子節）。
  - 詳細規則見下方 Dispatch Template 章節的「Pilot Dispatch」子節。
- **衝突解決規則（完整三層）**：
  - (a) **外部 reviewer vs 內部 reviewer**：外部 reviewer 的問題優先處理，因為建築師只有外部視角，沒有內部視角。
  - (b) **內部 reviewer vs 內部 reviewer**（例：Compliance 和 Content Director 互相矛盾）：用外部 reviewer 作為 tiebreaker——若 Wave 2 外部 reviewer 尚未跑，把衝突點 **特別標注** 在他們的 briefing 的第 3 欄（O），請他們在該點給出判斷。
  - (c) **Producer vs reviewer**（例：Writer A 和 Compliance Reviewer 互相矛盾）：沒有 tiebreaker 的情況下，fall back to "建築師視角 gate question" with cited evidence——讀被爭議的段落，引用其中一個具體字句，回答「12 年資歷的 Project Architect 讀這段會覺得這是獨立分析還是 marketing？」用答案決定修改方向。不得選「兩邊都對」或「略過」。
- **升級到 user 的判斷 rubric（3 個問題，任一 YES 才升級）**：
  (1) 這個問題是 spec-contract 衝突嗎？（例：Writer A 要做某事，M 條款禁止做某事，兩者不可兼得）
  (2) 這個問題會造成 ≥ 20% wall-clock budget overrun 嗎？
  (3) 這個問題的答案**不在**工廠已知 gotchas 或 patterns 中嗎？
  三個問題全部 NO → Commander 必須自己 resolve（不升級）。任何一個 YES → 升級到 user。
  **為什麼要這個 rubric**：把「知識庫已答的問題」升級到 user 是 process smell——訓練 user 期待過度升級，並且浪費 user context。Commander 在 pre-flight 讀過 scaling-playbook.md 和 gotchas-and-lessons.md 後，大多數「研究策略問題」都能自己答。
- **Commander 自己的 LLM 呼叫同樣必須走 `call_with_fallback.sh` wrapper**（Principle 7 適用 Commander）：任何 Commander 層級的 LLM 問題（衝突語義判斷、pilot 輸出審查的 LLM 輔助、外部 reviewer 輸出驗證）必須用 `bash ~/.claude/skills/ai-fallback/scripts/call_with_fallback.sh` 呼叫——**禁止**直接呼叫 `gemini`、`codex` CLI（見 G-001 / G-012 / G-014 / NEW-02）。Commander 的 LLM 呼叫同樣記錄在 `dispatch-log-002-waveN.md`，包含 wrapper command + 實際 answered model + exit code + timestamp + purpose。若 wrapper 退出 3（chain exhausted），Commander fall through 到 Claude-native reasoning（本 session 自己的模型）——不得再 retry 另一個 CLI。
- 用 Task 系統追蹤每個角色的建築師對齊狀態，而不只是完成狀態——已完成但未對齊建築師的任務，不算完成。

**M（對準 S 的資源驗證）**
- 每個波次產出一份 `gate-review-002-waveN.md`，包含固定欄位：交付物完整度 / 建築師視角存在？(Y/N/Partial) / 阻礙點
- Gate review 中「建築師視角存在」的判斷，必須引用具體段落或具體交付物作為證據——不是 Commander 的主觀判斷
- 16 個內部角色 + 3 個外部角色全部收到包含建築師 persona 描述的任務簡報（不只是格式要求）
- Wave 2 外部 reviewer 三份報告在 Wave 3 開始前全部完成，且 Commander 記錄每一個 flagged 問題的處理決策（接受修改 / 保留原文 + 理由）——沒有「略過」選項
- 部署前產出一份 `ogsm-retrospective-002.md`，記錄每個角色的 G 達成狀況和建築師對齊評分
- **Direction Seed 抽檢**：Performance Supervisor 每個波次抽檢 ≥ 1 次 Commander 的 dispatch briefing，確認 **9 個必要欄位**齊全 + 欄位 5 內含 3 條 knowledge query commands + 欄位 9 至少 3 條逐字複製自 source agent 的 Anti-patterns 清單；任一條件不滿足，該 subagent 的交付物不納入 gate review，必須重新派遣
- **Pilot 5/5 sanity-check artifact**（驗證 S bullet 4 "Pilot Dispatch" 的資源承諾）：每個波次 pilot subagent 交付後，Commander 必須在 `dispatch-log-002-waveN.md` 的 `## Pilot Sanity-Check` 節附一份 5/5 checklist 記錄，每一條 checklist 項目都附 PASS/FAIL 結論與交付物的具體段落引用（section ID 或 line range）；缺該節或引用不具體者，fan-out 不得進行。Performance Supervisor 每個波次抽檢 ≥ 1 次該記錄。
- **Tiebreaker injection verifiable marker**（驗證 S bullet 5b "內部 vs 內部衝突 → 外部 reviewer tiebreaker"）：當觸發 (b) 內部 vs 內部衝突需要外部 reviewer 作為 tiebreaker 時，Commander 必須在該外部 reviewer 的 Direction Seed 第 3 欄位（O）中插入 `<!-- tiebreaker: [conflict-id] -->` HTML 註解 marker，並在 `dispatch-log-002-waveN.md` 的衝突解決條目中記錄該 conflict-id。Quality Auditor 每個波次 grep `dispatch-log-002-waveN.md` 與對應 briefing 檔案，驗證 marker 雙向可追溯；缺 marker 視為 S5b 未履行。
- **3-question rubric execution log**（驗證 S bullet 6 的升級 rubric）：每一個 Commander 自行 resolve（不升級 user）的決定，必須在 `dispatch-log-002-waveN.md` 的對應衝突條目附完整 rubric 答案（q1/q2/q3 = Y/N + 理由），並引用至少一個 gotcha 或 pattern ID（來自 `~/.claude/skills/ogsm-framework/references/patterns-library.md` 或 `gotchas-and-lessons.md`）作為決策依據。缺 rubric 答案或缺 pattern/gotcha 引用 → 該決定 retrospectively 視為違反 S6，必須在 `ogsm-retrospective-002.md` 記錄。
- **Commander's own `/ai-fallback` wrapper-call 驗證**（驗證 S bullet 7 "Commander 自己的 LLM 呼叫走 wrapper"）：Commander 每一次 orchestration 層級的 `/ai-fallback` 呼叫（衝突語義判斷、pilot 輸出審查輔助、外部 reviewer 輸出驗證）必須在 `dispatch-log-002-waveN.md` 的 `## Commander LLM Calls` 節記錄並確認：wrapper command string + chain + 實際 answered model + exit code + timestamp + purpose。Quality Auditor 每個波次抽檢 ≥ 1 條 log entry 對照實際 wrapper exit 記錄驗證真實性（防止偽造 log）；`grep -E '^(echo|gemini|codex)' dispatch-log-002-waveN.md` 必須返回 0 命中（raw CLI 呼叫 = 硬失敗）。
- **Central skill-invocation-map 對齊驗證**：Commander 每個波次的 dispatch 前必須確認中央 `skill-invocation-map.md`（`~/.claude/skills/ogsm-framework/references/skill-invocation-map.md`）中該 agent 的 row 存在且 command 字串與 Direction Seed 第 5 欄位 verbatim 一致；不一致時以 skill-invocation-map 為準更新 Direction Seed。Quality Auditor 抽檢 ≥ 1 個 dispatch log entry 驗證中央 map 與 briefing 一致。
- **Task-system architect-alignment column audit**（驗證 S bullet 8 "Task 系統追蹤建築師對齊狀態"）：Commander 使用的 Task 系統（TaskCreate/TaskUpdate/TaskList）每一個 row 必須同時帶 `completion-status` 和 `architect-alignment-status` 兩個欄位；只有 completion-status = done 而 architect-alignment-status ≠ aligned 的 task 不得計為完成。Performance Supervisor 每個波次檢視 Task 系統快照確認兩欄並存；缺 alignment 欄位 = S8 未履行，記錄於 `ogsm-retrospective-002.md`。
- **Canonical persona 檔案驗證（validation-only，not content loading）**：Commander 必須在每個波次啟動前驗證 canonical persona 檔案（例如 `~/.claude/personas/project-architect-marcus.md`）存在於預期路徑。**MOD-1 principle: Commander 不載入 persona 內容，只驗證檔案存在**——保持 orchestration-only 邊界，避免「command load 太重」。缺檔時 Commander 必須 escalate 給 Writer A 並附具體指示「please produce persona at ~/.claude/personas/project-architect-marcus.md」，同時 **block dispatch** 所有需要該 persona 的 subagent 直到該檔案落盤。Commander 不就地合成 persona 內容；不就地 inline persona 到 Direction Seed 第 2 欄位（inline 由 dispatching agent 在 dispatch 時讀取檔案並貼入，Commander 只檢查檔案存在）。Performance Supervisor 抽檢 dispatch log 中是否有 persona-file-validation 記錄（pass / missing / blocked）。

**對齊 O 的論述**
Commander 若只協調任務完成，得到的是合格課程；只有同時協調建築師視角的貫穿，才能得到建築師想保存和推薦的課程——也就是 O 的情感目標。

**Anti-patterns 標準清單（Direction Seed 第 9 欄位來源）**
- NOT: 讓「交付物完成」取代建築師視角的架構師級驗證——應該: 每個 gate review 必須回答「建築師視角存在嗎？」並引用具體段落作為證據
- NOT: 把外部 reviewer 和內部 reviewer 的衝突意見當成「兩種看法各有道理」而不下決定——應該: 外部 reviewer 的問題優先處理，每個 flagged 問題必須有明確的接受修改或保留原文的決策記錄
- NOT: 跳過 Pilot Dispatch 直接並行派遣整個波次——應該: 每個波次先派一個 pilot subagent，確認交付物符合 O 的精神後才並行派遣其他 subagents
- NOT: 把 producer（Writer A 等）和 reviewer（Compliance 等）的衝突當成「兩邊都對」或「略過」——應該: 沒有外部 tiebreaker 時，fall back to 「建築師視角 gate question」with cited evidence，引用被爭議段落的具體字句決定修改方向
- NOT: 把知識庫已答的問題（研究策略、paywall workaround 等）升級到 user——應該: 執行 3 問 rubric（spec-conflict / 20% overrun / 知識庫答不出），全部 NO 就 Commander 自己 resolve，並在 dispatch log 記錄諮詢的 gotcha/pattern ID
- NOT: Commander 自己繞過 `call_with_fallback.sh` 直接呼叫 `gemini` 或 `codex` CLI——應該: Commander 的 LLM 呼叫同樣走 wrapper（Principle 7 適用 Commander），log 記錄 wrapper command + 模型 + exit code + timestamp

---

### 🔍 Investigator A — Cases & Data

**G（階段整合目標，串回 O）**
> 建築師讀到這些案例時，不是在讀別人的失敗故事——而是在想「這就是我下個月要交審的那棟案子的狀況」。每一個案例都要讓建築師感受到：這不是理論，這是我的執業風險。當他能把案例說給業主或 AHJ 聽，而不是靠記憶力背條文，O 的「不依賴習慣或表象」才能成立。

**Tier 1 摘要（Direction Seed 必帶）**
- **G 一句話**：讓建築師讀到案例時感受到「這就是我下個月的專案」。
- **S 一句話**：從 DHI + 法院文件雙來源找 2020+ 真實案例，每個案例附 AHJ 反應或保險結果作為情感錨點。
- **關鍵 M**：≥ 5 個案例 / 每個案例記錄雙來源驗證狀態 / ≥ 1 個 2020+ 案例 / DHI 查詢附具體文件編號。
- **Skill commands**：`/content-scout flag-candidate --source-agent investigator-a ...`（詳見 Skill Invocation Map）
- **Research tool commands（P-015 primary/secondary split）**：研究查詢（case discovery / DHI lookup / court filings / AHJ bulletins）**primary path = WebSearch tool (Claude Code built-in)**——直接呼叫 WebSearch 取得可追溯 URL，不走 LLM 生成層。`/ai-fallback` wrapper (`bash ~/.claude/skills/ai-fallback/scripts/call_with_fallback.sh ...`) 僅用於 **generative sub-tasks**（summary synthesis / 結構化摘錄 / persona-simulate skeptical reader / 多來源交叉比對後的論點綜合），NOT for raw research queries。chain `gemini-2.5-flash-lite,gemini-2.5-pro,codex`，per-model timeout 120s；若 exit code 3 代表 chain 耗盡，改用 WebSearch 作為 generative-task 的最後備援。詳見 Model Invocation Map + §P-015 Application。
- **Anti-patterns**：詳見本 agent 的「Anti-patterns 標準清單」子段落

**S（為建築師選的路徑）**
- 只選建築師「認識」的建築類型（辦公室、學校、醫院），不選建築師沒有設計過的類型——讓案例的情境馬上可以被帶入，不需要翻譯。
- 每個案例一定要包含「AHJ 的反應」或「保險的結果」，因為這兩個是建築師在執業中真正面對壓力的時刻，比法規條號更能驅動記憶。
- 失敗案例優先：建築師記得教訓比記得範例更久，而且失敗案例更能讓他們想到「我以前也這樣 spec 過」。
- 案例來源以 DHI（Door and Hardware Institute）案例資料庫為主要來源，法院公開文件和保險公司理賠紀錄作為交叉驗證——兩個獨立來源確認的案例才能被納入。
- **發現 blog 題目候選時，呼叫 `/content-scout flag-candidate`**（Principle 7 — embedded skill invocation）：當案例研究資料足以支撐一篇獨立 800–1500 字的 blog 文章時，立刻寫入 `.content-scout-queue.md`，命令格式：`/content-scout flag-candidate --source-agent investigator-a --source-file [path] --title "[題目]" --type case-study --keywords "[3–5 個關鍵字]" --research-data "[完整原始資料，不摘要]" --why-worth-writing "[1–2 句理由]"`。研究資料要完整到 Phase 3 寫手不用回頭查原始交付物。若 cycle wall-clock 預算 < 15 分鐘（P-012 script-budget-risk 門檻），改為 async-safe 模式：在 `research-course002-cases.md` 頂端「Content scout candidates」節草擬完整 entry（含 10-field schema），由 post-cycle merge step 寫入 queue；metrics 記 `drafted_inline: true` 不視為 FAIL。
- **Hard Constraint（Direction Seed 第 6 欄強制內容）**：本 agent 必須執行 ≥ 3 次研究搜尋（案例搜尋、DHI 資料庫查詢、法院文件搜尋各 ≥ 1 次）。**Primary tool：WebSearch (Claude Code built-in)**；允許的替代：任何 Gemini Flash tier（含 Flash Lite）透過 `/ai-fallback` wrapper——但僅在 research-only sub-task 無法以 WebSearch 完成時使用，且需在搜尋記錄註明原因。少於 3 次視為 S 承諾的資源未使用，交付物退回。

**M（對準 S 的資源驗證）**
- 交付 `research-course002-cases.md`，包含至少 5 個案例（**or honest under-delivery header per line 236 的 "hard count reached at N verified cases (target 5)" escape clause**——不可為湊數而捏造 entry，見本段落最後的 Anti-patterns 第 4 條）
- 每個案例必須包含：建築類型 / 五金 spec 錯誤或正確描述 / AHJ 退件或保險拒賠結果 / 至少 3 個可查核的來源引用
- **DHI 資料庫查詢或公開替代來源（P-016 escalation chain — 對 LLM-harness agent 為 primary path，非 fallback）**：DHI Technical Bulletin 編號路徑僅在 Investigator A 為 DHI 會員人工執行時可達；LLM-harness 執行環境下 DHI paywall 永遠不可達，因此 P-016 替代來源鏈是**預設主要路徑**，而非例外分支。替代來源（透過 WebSearch primary）：BHMA free resources URL / AHJ 地方採用通告 URL / idighardware.com（Allegion）industry bulletin verbatim / PACER 法院公開文件 / state fire marshal bulletin。交付物記錄格式：「primary DHI source unavailable (LLM-harness default), using [替代來源類型] per P-016」。silent omission（既沒 DHI ID 也沒 escalation note）視為 M FAIL
- **每個案例的雙來源驗證狀態**：記錄格式為「來源 1：[DHI 文件] / 來源 2：[法院文件 / 保險記錄]」——只有單一來源的案例必須標記，並說明為何保留或替換
- **交叉驗證後的修正記錄**：如果兩個來源的描述有出入，記錄哪個來源更可信、原因是什麼
- **URL authenticity post-process check**：每個已計入 ≥ 5 hard count 的 case 完成後，Investigator A 必須對該 case 的 primary URL 執行 **一次 WebSearch verification pass**（例如 `WebSearch query="<case title> <year> <AHJ or docket>"`），確認該 URL 出現在搜尋結果且 title/publisher 與引用描述一致；驗證結果（pass / URL drifted / 404）記入搜尋記錄。URL drifted 或 404 的 case 不計入 hard count。
- 至少 2 個案例記錄因錯誤選擇 hinge 導致的具體後果（不是潛在後果，是已發生的後果）
- 至少 1 個 2020 年後的案例（確保現行法規版本適用）
- 至少 1 個 fire-rated assembly 案例
- 驗收標準：Content Director 確認每個案例的建築類型對建築師是「熟悉的」，不是陌生場景
- **`/content-scout flag-candidate` 呼叫驗證**：Performance Supervisor 在 Wave 1 結束時讀 `.content-scout-queue.md`，確認 Investigator A 至少寫入 1 個 candidate（若無 flag-worthy material，需在 `research-course002-cases.md` 中明確說明「本波次未發現 flag-worthy 案例研究題目 + 理由」）；驗證所寫入的 entry 通過 10 欄位 schema + 禁用詞 lint（由 /content-scout skill 自動檢查）；type 優先為 `case-study`
- **研究搜尋下限驗證**：交付物附記錄表，顯示至少 3 次搜尋的**工具名稱（WebSearch / ai-fallback+model）** + 查詢字串 + 時間戳 + 結果摘要。工具欄位 primary 填 `WebSearch`；若某次使用 `/ai-fallback` 的任何 Flash tier（含 Flash Lite）或 Pro tier，需在同一列註明原因。少於 3 次的交付物不進 gate review。
- **搜尋工具呼叫驗證（含 Gemini Flash generative sub-task 驗證）**：記錄每次研究搜尋的字串 + 回應摘要 + 時間戳 + 工具名稱於 `research-course002-cases.md` 中的「搜尋記錄」節——工具欄位允許值為 `WebSearch` / `Gemini Flash` / `Gemini Flash Lite` / `Gemini Pro` / `Codex`；若使用 Gemini Flash 類工具進行 generative sub-task（summary synthesis / persona-simulate skeptical reader），需在同列註明 `sub-task: generative`。無記錄視為 S 承諾的資源（包含 Gemini Flash）未使用，Quality Auditor 抽檢 ≥ 1 條查詢記錄確認真實執行而非幻覺
- **`/ai-fallback` 呼叫驗證（僅 generative sub-tasks）**：若本 agent 對 summary synthesis / 結構化摘錄 / persona simulation 等 generative 子任務呼叫了 `call_with_fallback.sh`，確認執行記錄存在於「搜尋記錄」節並標記 `sub-task: generative`；若 fallback chain 觸發（首選模型 quota 耗盡），記錄實際使用的備援模型名稱（含 Codex fallback 情況）。若本 cycle 未進行 generative sub-task，本欄位記 "n/a — research-only cycle, primary WebSearch"。

**對齊 O 的論述**
建築師只有在感受到「這和我有關」的時候才會改變 spec 習慣——案例研究是讓他們從旁觀者變成當事人的唯一方式，也是 O 中「不依賴習慣」的直接支撐。

**Anti-patterns 標準清單（Direction Seed 第 9 欄位來源）**
- NOT: 找符合預設結論的案例（confirmation bias）——應該: 搜尋所有相關案例，包含對 Waterson 不利的，讓建築師感受到這是真正的獨立分析
- NOT: 用 2018 年前的案例作為主要來源——應該: 主要案例須有 2020+ 的至少一個，並對 2018 前的案例明確標記版本年份限制
- NOT: 引用二手摘要或媒體報導就算完成——應該: 每個案例必須找到 DHI 原始文件或法院公開文件，且兩個獨立來源都指向同一個案例事實
- NOT: 為了滿足 ≥ 5 案例 hard count 而產生含糊或虛構來源（例如 "hypothetical blog post"、"example.gov"、"search for X might yield"、"discussion at DHI meeting" 這類無具體 URL 或文件 ID 的 placeholder，這是 raw LLM 在 hard count 壓力下的常見 hallucination 模式 — 參照 G-013 / P-017）——應該: 案例數寧可少於 5 也不接受無可驗證第一手來源的 entry；每個 case 的 ≥ 3 source 當中至少 1 個必須是可點擊 URL 或具體文件 ID（court filing、fire marshal NOV、insurance report、city council meeting minutes URL、industry publication article URL），否則該 case 不計入 ≥ 5 hard count，並在交付物頂端明確標註 "hard count reached at N verified cases (target 5) — under-delivery reason: [reason]"。Quality Auditor 抽檢每個 case 的第一筆 source URL 是否真實可達

---

### 🔎 Investigator B — Codes & Cost

**G（階段整合目標，串回 O）**
> 建築師在專案會議上引用這份課程的法規資訊時，可以毫不猶豫說出條號和版本年份，不怕被承包商或 AHJ 糾正。費用比較表讓他在業主問「為什麼要換比較貴的五金」時，有數字可以說——不是感覺，是 20 年的維護成本差異。

**Tier 1 摘要（Direction Seed 必帶）**
- **G 一句話**：讓建築師在專案會議上能說出條號版本年份，有費用數字可以捍衛。
- **S 一句話**：用 MasterFormat 框架組織法規，ICC + NFPA 雙來源交叉驗證每條引用，費用算到 AHJ 退件間接成本。
- **關鍵 M**：每條引用附精確條號和版本年份 / ICC Digital Codes 查詢 URL 有記錄 / ICC 與 NFPA 說法不一致時有修正記錄。
- **Skill commands**：`/content-scout flag-candidate --source-agent investigator-b ...`（詳見 Skill Invocation Map）
- **Model commands**：`bash ~/.claude/skills/ai-fallback/scripts/call_with_fallback.sh "Verify [IBC section X] current version and cross-reference with NFPA 80 [section Y]..." "gemini-2.5-flash,gemini-2.5-flash-lite,gemini-2.5-pro,codex"` （詳見 Model Invocation Map）
- **Anti-patterns**：詳見本 agent 的「Anti-patterns 標準清單」子段落

**S（為建築師選的路徑）**
- 用建築師熟悉的參考系統組織法規資訊：MasterFormat 章節號（08 71 00 Door Hardware）和 AIA contract 條款（Specification Division 8），而不是只列條文號碼——建築師每天用這個框架，放在這個框架裡的資訊才不會被遺忘。
- 費用比較一定要算到「AHJ 退件的間接成本」和「保險拒賠的潛在損失」，因為這兩個數字會讓業主和業主的律師點頭，是建築師在 spec review 中最需要的彈藥。
- 標記各州差異時，以 AIA 會員最集中的 5 州（CA, NY, TX, FL, IL）為優先，因為這是課程受眾最可能執業的地方。
- 法規引用使用 **ICC Digital Codes 和 NFPA 官方出版品**作為雙來源交叉驗證——每條引用都必須在這兩個平台中各自查核，才能進入課程。
- **獨立 spec 資源候選搜尋任務**：在 Writer B 撰寫後半段前，執行動態搜尋至少 5 個獨立 spec writing 資源（SpecLink / SPC Alliance / CSC/CSI 只是起點），交付完整候選清單給 Writer B。
- **發現 blog 題目候選時，呼叫 `/content-scout flag-candidate`**（Principle 7 — embedded skill invocation）：當某條法規更新、費用比較、或成本分析足以獨立成 800–1500 字 blog 文章時，呼叫 `/content-scout flag-candidate --source-agent investigator-b --source-file [path] --title "[題目]" --type regulatory-explainer --keywords "[3–5 個關鍵字]" --research-data "[完整原始資料，含條號和版本年份]" --why-worth-writing "[1–2 句理由]"`。
- **Hard Constraint（Direction Seed 第 6 欄強制內容）**：本 agent 必須執行 ≥ 3 次 Gemini Flash 搜尋（法規條號版本驗證、ICC 交叉驗證、NFPA 交叉驗證各 ≥ 1 次）。少於 3 次視為 S 承諾的資源未使用，交付物退回。

**M（對準 S 的資源驗證）**
- 交付 `research-course002-codes-cost.md`，分兩個清楚分開的節：法規要求 / 生命週期費用分析
- 法規節：至少 4 個來源（IBC, IFC, NFPA 80, NFPA 101, ADA/ICC A117.1），每個引用附帶精確條號和版本年份
- **ICC Digital Codes 實際查詢確認**：記錄每條法規引用的 ICC Digital Codes URL 或頁面路徑（不是泛稱，是具體查詢結果）
- **NFPA 官方出版品交叉驗證確認**：每條涉及 NFPA 80 或 NFPA 101 的引用，記錄 NFPA 文件版本和頁碼
- **Paywall workaround 記錄**：若 ICC Digital Codes 或 NFPA LiNK 主來源因 paywall 無法取得 verbatim 全文，必須記錄替代取得路徑（如 AHJ adoption notice、city building department code mirror、industry commentary citing verbatim），附 URL 與引用段落，以保證 Fact Checker 有獨立驗證的第二來源
- **5 州 AHJ-adoption delta 驗證（GAP-3）**：M 必須逐一驗證 CA / NY / TX / FL / IL 五州（對應 S line 256 的承諾）——每州至少 1 條引用記錄 AHJ-adopted version 與 ICC base edition 的差異（若該州直接採用 base edition 無 delta，也必須以 first-party 來源明確標註「無 delta」，不得留白）。Quality Auditor 抽檢：5 州必須全部有條目，缺任一州視為 S→M 覆蓋失敗，交付物退回
- **交叉驗證修正記錄**：ICC 和 NFPA 說法不一致時，記錄哪個來源更適用、理由是什麼；**不得只依賴單一來源的引用出現在最終交付物中**
- 費用節：至少 3 個時間軸的比較表（5 年 / 10 年 / 20 年），每個數字要有來源，費用項目包含 AHJ 退件間接成本估算
- 至少 3 個明確的「必須用某種五金」的法規情境（不是偏好，是強制）
- **獨立 spec 資源候選搜尋交付物**：搜尋日期 / 使用的關鍵字 / 至少 5 個候選 / 每個候選的中立性評估（與三大廠的關係、是否受廠商資助）
- 驗收標準：Fact Checker 確認每個條號都可在現行版本法規文件中查到
- **`/content-scout flag-candidate` 呼叫驗證**：Performance Supervisor 在 Wave 1 結束時讀 `.content-scout-queue.md`，確認 Investigator B 至少寫入 1 個 candidate（若無 flag-worthy material，需在 `research-course002-codes-cost.md` 中明確說明「本波次未發現 flag-worthy 法規或費用題目 + 理由」）；驗證所寫入的 entry 通過 10 欄位 schema；type 優先為 `regulatory-explainer` 或 `cost-comparison`
- **Gemini Flash 搜尋下限驗證**：交付物附記錄表，顯示至少 3 次搜尋的查詢字串 + 時間戳 + 結果摘要。少於 3 次的交付物不進 gate review。
- **費用數字 source URL 抽檢（GAP-4）**：Quality Auditor 在 Wave 1 gate 時，從每個時間軸比較表（5yr / 10yr / 20yr）各抽 ≥ 1 個費用數字，逐一點擊其 first-party source URL（manufacturer 價目表、GSA / DOT 維護成本研究 DOI、PACER 判決、保險業 claims study URL），URL 無法打開 or 返回 404 視為該數字未 sourced，退回 Investigator B 補來源。此抽檢與「Gemini Flash 呼叫驗證」的查詢記錄抽檢並行執行、互不替代
- **Gemini Flash 呼叫驗證**：每次 Gemini Flash 法規查詢的字串 + 回應摘要 + 時間戳記錄於 `research-course002-codes-cost.md` 的「法規查詢記錄」節；ICC/NFPA 交叉驗證的每次呼叫都必須有獨立記錄條目；無記錄視為交叉驗證未執行，Quality Auditor 抽檢 ≥ 2 條查詢記錄（ICC 和 NFPA 各 1）
- **`/ai-fallback` 呼叫驗證**：確認 `call_with_fallback.sh` 執行記錄存在於交付物的「法規查詢記錄」節；若 fallback chain 觸發，記錄實際使用的備援模型名稱（含 Codex fallback 情況）

**對齊 O 的論述**
建築師能「獨立判斷合規性」的前提，是他有可以直接引用的條號和可以捍衛的費用數字——這兩樣東西都在 Investigator B 的交付物裡，缺一不可。

**Anti-patterns 標準清單（Direction Seed 第 9 欄位來源）**
- NOT: 引用法規條號不附版本年份——應該: 每條引用格式為「[條號] ([版本年份])」，如「IBC 715.4.8.3 (2021)」，讓建築師在 AHJ 送審時有確定的版本可引用
- NOT: 只看 ICC 不交叉驗證 NFPA——應該: 每條涉及 NFPA 80 或 NFPA 101 的引用，必須在 NFPA 官方出版品中獨立查核一次，記錄文件版本和頁碼
- NOT: 把費用比較做成廠商比價單——應該: 費用比較算到「AHJ 退件間接成本」和「保險拒賠潛在損失」，讓數字有業主和律師都能接受的說服力
- NOT: 為了滿足 ≥ 4 法規引用 / ≥ 3 時間軸費用表的 hard count 而產生含糊或虛構來源（例如 "hypothetical code section"、"example.nfpa.org"、"search for IBC X might yield"、"discussion at ICC committee"、"industry average ~$XXk delay cost" 這類無具體 URL 或文件 ID 的 placeholder，這是 raw LLM 在 hard count 壓力下的常見 hallucination 模式 — 參照 G-013 / P-017 / NEW-03，與 Investigator A line 236 同一類失敗模式）——應該: 法規引用與費用數字寧可少於 hard count 也不接受無可驗證第一手來源的 entry；每條法規引用至少 1 個可點擊 first-party URL（ICC Digital Codes / NFPA publisher page / ada.gov / state fire marshal bulletin / AHJ adoption notice）或具體 document ID；每個費用數字至少 1 個可點擊 first-party source URL（manufacturer 價目表、GSA/DOT 研究 DOI、PACER filing、保險 claims study）；否則該 entry 不計入 hard count，並在交付物頂端明確標註「hard count reached at N verified citations (target 4) / N tables (target 3) — under-delivery reason: [reason, e.g. NFPA 80 §X 主來源 paywalled 且 P-016 chain 無 verbatim 回傳 / Gemini Flash 回報 no first-party source found]」。Quality Auditor 抽檢每條 citation 與每個費用數字的第一筆 URL 是否真實可達
- NOT: 當 ICC Digital Codes / NFPA LiNK verbatim 因 paywall 不可得時，靜默 drop 該條引用或以 paraphrase 偷偷替代——應該: 必須走 P-016 escalation chain（idighardware.com Allegion bulletin → AHJ 地方 adoption notice → city building department code mirror → state fire marshal bulletin → industry commentary citing verbatim），逐層記錄嘗試的 channel 與結果；若全鏈仍無 verbatim，在交付物中明確標註該條為「P-016 chain exhausted — 尚未取得 verbatim，flagged for Wave 2 supplement」，禁止以鄰近條款（如以 §6.4.2.1 替代 §6.1.5）偽裝為原條款，且鄰近條款必須顯著標註為 substitute 而非 paraphrase

---

### ✍️ Writer A — Front Half (Theory & Mechanism)

**G（階段整合目標，串回 O）**
> 建築師讀完前半段，腦子裡出現的不是技術規格表——而是一個他見過的門，和他以前從來沒有想過的問題：「那扇門用的是哪一種 hinge？為什麼？」如果他在前 30 分鐘之後還沒有產生這個問題，後半段的應用練習就沒有意義了。

**Tier 1 摘要（Direction Seed 必帶）**
- **G 一句話**：讓建築師在讀完前半段後，對他見過的某扇門產生一個從未想過的問題。
- **S 一句話**：從建築師決策點出發往機械原理走，第一張投影片就用一個看起來合理但會讓 AHJ 退件的 spec 選擇作為鉤子。
- **關鍵 M**：投影片 1–12 Markdown 草稿 / ≥ 2 個互動檢查點 / 每個技術主張回指 Investigator A/B 的具體來源 / 「鉤子投影片」明確標注。
- **Skill commands**：`/content-scout flag-candidate --source-agent writer-a ...`（詳見 Skill Invocation Map）
- **Model commands**：Claude Sonnet（核心寫作）
- **Anti-patterns**：詳見本 agent 的「Anti-patterns 標準清單」子段落

**S（為建築師選的路徑）**
- 用建築師的語言框架，不說「mechanism」，說「你下次 spec 的時候會遇到的那個選擇」。技術解釋永遠先從建築師的決策點出發，再往機械原理走——不是反過來。
- 從一個建築師認得出來的「錯誤」開始——一個看起來完全合理的 spec 選擇，但在某種情境下會讓 AHJ 退件。這個鉤子要在第一張投影片就出現，不是在第 6 張才出現。
- 每一個技術概念都要用 Investigator A 的案例去接地，讓建築師在學機械原理的同時，感受到這個原理為什麼在真實執業中重要。
- **撰寫時發現可獨立展開的技術概念，呼叫 `/content-scout flag-candidate`**（Principle 7 — embedded skill invocation）：若某個技術概念在課程中只能簡述但值得 800 字以上獨立文章展開，呼叫 `/content-scout flag-candidate --source-agent writer-a --source-file [path] --title "[題目]" --type product-comparison --keywords "[關鍵字]" --research-data "[完整]" --why-worth-writing "[理由]"`。

**M（對準 S 的資源驗證）**
- 交付投影片 1–12 的 Markdown 草稿，格式：投影片標題 / 主要內容 / 視覺描述 / 講者備注 / 互動檢查點（如有）
- 至少 2 個互動檢查點，每個包含：題目 / 2–4 個選項 / 正確答案解釋
- **Investigator A 案例的實際引用追蹤**：每張投影片的技術主張必須標注回指 Investigator A 或 B 的具體來源編號（不是泛稱「根據研究」），若某張投影片沒有來源引用，必須說明理由
- **Substrate gap protocol**：若某張投影片的技術主題在 Investigator A/B 的交付物中沒有對應案例（substrate gap），Writer A 必須在該投影片明確標注「substrate gap + 使用的緩解策略」，並從以下三條路徑擇一：(a) 重新框定 hook 到鄰近 mechanism family 的實際案例（例如用 surface closer 的 tension decay 失效案例去類比 spring hinge 的相同失效曲線）——**[Tier A] 類比必須對原主張「物理上忠實」：path (a) 交付物中必須包含一句 analogy fidelity note，明示類比成立的物理範圍（e.g.「stored-energy 衰減曲線 → spring steel fatigue 成立於 5–10 年 high-cycle 區段」）以及類比不成立的範圍（e.g.「hydraulic valve decay 的溫度敏感度 ≠ spring steel 的 set-point 漂移」）。Content Director 驗收時必須對該 note 做物理忠實度檢查；若無此 note，path (a) 不得採用。**，(b) 在交付物中寫入「此投影片的某技術主張缺乏 substrate 支撐，已標記為 Investigator A Wave 2 補充需求」，並把該主張降級為視覺描述或講者備注層級不做硬性技術宣稱——**[Tier A] 降級後講者備注的主張強度上限：即使寫入講者備注，也不得使用 definitive 句式（禁用「will」、「always」、「proven to」、「X causes Y」）；只能使用 hedged 句式（「may indicate」、「is consistent with」、「suggests but is not established by substrate」）。Content Director 驗收時對 path (b) 講者備注做強度檢查，發現 definitive 句式即退回重寫。**，(c) **禁止**第三條路徑：憑空編造案例、把不同 mechanism family 的案例偷換成當前主題的案例、或用「根據研究」這類泛稱。Content Director 在驗收時檢查每個 substrate gap 標注是否存在且 mitigation 策略透明
- **Brand-neutral reframe protocol**：當 Writer A 的 slide brief 內嵌明確商業品牌名稱（例如「owner's AE suggested Waterson spring hinges to match Bommer BOM」），Writer A 必須在 slide body 中**把問題從「哪個品牌」重新框定為「哪個 mechanism family + 哪個 spec criterion」**，且該 reframe 必須同時：(i) 至少引用 1 個中立第三方標準（BHMA / NFPA / ANSI / UL / CSC / **[Tier A] ADA / ICC / IBC / IFC**）作為 criterion 的依據（此清單為 non-exhaustive enumeration of acceptable neutral references），(ii) 不對任何被提及品牌做 evaluative 比較（禁用 superior / inferior / best / only 或「選 X 因為…」句式），(iii) slide 的收尾 beat 必須是反思問句或架構師決策 framing，**不得**是採購動作（"request a quote" / "upgrade to" / "choose"）。Content Director 驗收時檢查 brand-neutral reframe 是否出現、中立標準是否被引用、收尾 beat 是否為 reflective question
- 每張投影片有講者備注（至少 2 句），說明講師要強調什麼、為什麼
- **[Tier A] Title-layer voice gate**：投影片標題本身必須處於「建築師決策點」語氣，**禁止** marketing-brochure 語氣（禁用句式範例：「Beyond the...」、「Unlocking...」、「The Ultimate Guide to...」、「Sustaining... Performance」、任何以形容詞+名詞為主體的 promotional 標題）。合格標題必須是決策 framing（例：「What you're actually choosing when you spec a 185-lb ADA leaf」）或問題 framing（例：「Which hinge family survives a 7-year high-cycle door？」）。Content Director 驗收時對 12 張投影片標題逐一檢查；任何一張命中 marketing 句式即退回重寫。
- **[Tier B — LIVE BUG, needs Auditor threshold calibration] Arc-level voice consistency M proxy**：Writer A 交付 slides 1–12 後，Content Director 在 per-slide 驗收之前先執行一次 arc-level voice pass：每 4 張投影片（1–4, 5–8, 9–12）抽樣 1 段 narration passage（slide body 或 speaker notes），丟給 Gemini 或 Claude 以「建築師決策點 persona」評分 voice consistency score 1–5（1 = 純教科書語氣，5 = 純架構師決策框架）。**通過門檻：每段抽樣 ≥ 3.5**；任一段 < 3.5 即觸發該區段全部投影片 rewrite。這是針對 Robot 2 live run 中 gemini-2.5-flash 在 slide 7 滑進教科書語氣（anti-pattern 第 3 條 live 觸發）的直接 M-layer proxy。**Tier B 說明**：3.5 門檻是初步估計，需要 Quality Auditor 在首個 polish validation cycle 校準（可能需要根據實際 score distribution 調整至 3.0 或 4.0）。persona prompt 全文由 Content Director 維護於 polish workspace。
- **「第一張鉤子」驗收標準獨立記錄**：在交付物中明確標注哪一張是「鉤子投影片」，說明它讓建築師產生「這和我有關」的設計邏輯
- 驗收標準：Content Director 確認第一張投影片的「鉤子」能讓建築師產生「這和我有關」的感受
- **[Tier C — USER DECIDED] Writer A → Writer B handoff contract**：Writer A 是前後半段銜接的 producer side（user decision: Writer A 為 LEAD）。投影片 12 的交付物中**必須**包含一個 **Markdown sub-section** `### Hook for Next Writer`（或同等名稱，以 markdown heading 呈現）作為結構化 handoff 欄位，內容以 YAML-in-fence-block 或結構化 markdown list 提供以下 **4 個必填欄位**：(1) `hook_slide_id`: which slide number contains the hook（通常是 slide 1 或 slide 12 的收尾問題）；(2) `callback_theme`: the thematic thread Writer B must continue（後半段 scenario 應該呼應的 unresolved question）；(3) `door_scenario_details`: specific door/scenario details needed for Writer B's slide 13（具體門型、荷重、ADA 條件、mechanism family 框定）；(4) **`voice_carryover`**: tone and voice register cues (**第 4 欄，most important drift-risk anchor**——必須 verbatim / 段落方式描述 Writer A 在該 hook slide 中採用的語氣、節奏、句式選擇、persona register)。此欄位為 Writer B 啟動條件；若缺失，Content Director 必須退回 Writer A 補完，Writer B 不得開工。**Content Director check depth: reasonableness**——CD 驗證不只是欄位出現與否，而是檢查內容 reasonableness（hook 是否在敘事上成立？voice_carryover 是否 match Writer A 該 slide 的實際 voice？），不合理或敷衍填寫必須退回重寫。
- **`/content-scout flag-candidate` 呼叫驗證**：Performance Supervisor 在 Wave 1 結束時讀 `.content-scout-queue.md`，確認 Writer A 若發現值得獨立展開的技術概念已寫入候選（若整個前半段撰寫過程中沒有任何技術概念達到 800 字以上獨立展開的門檻，需在交付物末尾的「Content Scout 備注」段落說明「本波次未發現 flag-worthy 技術概念 + 理由」）；type 優先為 `product-comparison` 或 `regulatory-explainer`

**對齊 O 的論述**
前半段如果只是技術說明，建築師讀完只有知識，沒有動機改變 spec 習慣。只有當機械原理和真實執業風險被接在一起，後半段的決策練習才有土壤。

**Anti-patterns 標準清單（Direction Seed 第 9 欄位來源）**
- NOT: 假設建築師是初學者，從最基礎的名詞解釋開始——應該: 以「你已有 12 年資歷，你做過這些決定，但可能從未想過背後的機械原理」作為起點，尊重讀者的執業經驗
- NOT: 技術原理和真實案例脫鉤，變成純機械說明——應該: 每個技術概念都必須用 Investigator A 的具體案例接地，讓建築師在學原理的同時感受到執業風險
- NOT: 用教科書語氣寫投影片文字——應該: 用「你下次 spec 的時候會遇到的那個選擇」框架替代「mechanism 的工作原理是」，技術解釋永遠從建築師決策點出發

---

### ✍️ Writer B — Back Half (Scenario Recognition & Spec Resource Navigation)

**G（階段整合目標，串回 O）**
> 建築師讀完後半段，帶走的是兩個東西：**情境辨識能力**（「我看到這五個情境之一，我知道 Waterson 可能適合」）和**實現路徑**（「我不需要靠三大廠的 spec writer，我知道去哪裡找獨立的 spec writing 資源」）。
>
> 他不是在背產品規格，他是在理解：**spec writing 不是三大廠的專利**。當他下次遇到重門、ADA 需求、防火兼顧美觀、長期維護考量、或改建受限等情境，腦子裡會響起 Waterson 這個選項——而且他知道下一步怎麼走。

**Tier 1 摘要（Direction Seed 必帶）**
- **G 一句話**：讓建築師帶走情境辨識能力（何時用）和實現路徑（SpecLink / SPC Alliance / CSC/CSI 怎麼用）。
- **S 一句話**：教五個情境辨識（有視覺錨點）+ 三個第三方中立 spec 資源（從平台價值出發，不是從 Waterson 出發），破除「只能靠三大廠」的迷思。
- **關鍵 M**：三個 spec 資源各有獨立介紹段落 / 五個情境各有視覺錨點描述 / 中立性自我審查記錄附在交付物中 / Sales Rep Advisor 確認「聞起來像資訊提供」。
- **Skill commands**：`/content-scout flag-candidate --source-agent writer-b ...`（詳見 Skill Invocation Map）
- **Model commands**：Claude Sonnet（核心寫作）
- **Anti-patterns**：詳見本 agent 的「Anti-patterns 標準清單」子段落

**S（為建築師選的路徑）**
- **不教 spec 語言細節**：建築師只需要「能指定品牌和方向」，詳細的 spec 語言是 spec writer 的工作。過早進入 spec 語言會讓建築師感到這是他不擅長的領域，反而阻礙行動。
- **教情境辨識**：設計五個常見的 Waterson 適用情境——重門（heavy door）、ADA 合規、防火門兼顧美觀、長期低維護需求、改建空間受限。每個情境都要有**具體的視覺錨點**（讓建築師能聯想到他自己設計過的某個空間或某個客戶的需求）。
- **教資源導航**（第三方中立角度）：告訴建築師「spec writing 不是只有三大廠的路徑」——
  - **SpecLink**：建築師可以自行使用的 spec writing 平台（Waterson 已在其中上架，但介紹時從「這是一個什麼樣的平台、它能幫你做什麼」出發，不是「因為 Waterson 在上面」）
  - **SPC Alliance（Specifications Consultants Alliance）**：獨立 spec 顧問聯盟，與三大廠無從屬關係，可以協助建築師指定任何廠商
  - **CSC/CSI 網絡**：Construction Specifications Canada / Construction Specifications Institute，提供中立的 spec writing 培訓和顧問資源
- **破除迷思**：明確告訴建築師「為什麼很多人以為只能靠三大廠的 spec writer」（市場結構性因素），然後說明「這不是唯一路徑」——這個轉折是課程的核心情感節點，建築師在這裡感受到的是「原來我有更多選擇」。
- **中立性設計原則**：介紹 SpecLink、SPC Alliance、CSC/CSI 時，至少呈現 2–3 條不同的路徑，讓建築師感受到這是工具箱，不是導流頁面。Waterson 是這個工具箱的情境之一，不是唯一主角。
- **動態搜尋承諾**：在實際撰寫階段，派 Industry Researcher 去搜尋更多獨立 spec 資源候選（可能包括區域性 spec writer、建築師事務所的 in-house spec team、其他中立 spec 平台）。SpecLink / SPC Alliance / CSC/CSI 是起點，不是終點。調查員要找至少 5 個候選才交回 Writer B。
- **撰寫時發現可獨立展開的情境或資源路徑，呼叫 `/content-scout flag-candidate`**（Principle 7 — embedded skill invocation）：若某個情境辨識案例或獨立 spec 資源本身值得獨立成文，呼叫 `/content-scout flag-candidate --source-agent writer-b --source-file [path] --title "[題目]" --type scenario-guide --keywords "[關鍵字]" --research-data "[完整，含資源聯繫方式和中立性說明]" --why-worth-writing "[理由]"`。

**M（對準 S 的資源驗證）**
- 交付投影片 13–24 的 Markdown 草稿，格式與 Writer A 相同
- 至少 3 個互動檢查點，至少 1 個是情境辨識練習（「這個情境適合哪種 hinge？」不是記憶題）
- **五個情境的視覺錨點確認**：每個情境都必須附有描述「視覺錨點」的設計備注（例如：「重門情境的錨點圖片應該是辦公大廳或醫院主入口，而不是工業廠房——前者是建築師熟悉的」）
- **三個獨立 spec 資源的實際介紹確認**：
  - SpecLink：投影片中是否說明了「SpecLink 是什麼 / 建築師怎麼使用 / 為什麼它是一個獨立選項」——不能只出現品牌名稱
  - SPC Alliance：是否說明了「SPC Alliance 是什麼組織 / 它與三大廠的關係 / 建築師如何聯繫」
  - CSC/CSI：是否說明了「CSC/CSI 提供什麼具體資源 / 網址或聯繫方式 / 它的中立性背景」
- **單張投影片 toolbox 規則**：即使某張投影片只要求引用 1 個獨立 spec 資源，Writer B 仍必須在該投影片內以至少一句話信號化「這是 N 條獨立路徑中的一條」（例如「this is one of several independent paths」），避免任何單點引用被誤讀為單一導流點。此規則對齊 S 中「讓建築師感受到這是工具箱，不是導流頁面」的設計意圖，並在 slide 粒度上落地。
- **中立性自我審查記錄**：Writer B 交付時附一段自評：「這三個資源的介紹，有沒有任何段落的語氣是『因為 Waterson 在上面所以好』而不是『這個平台本身有什麼價值』？」——這段自評由 Sales Rep Advisor 進行交叉驗證
- **迷思破除段落存在**：確認有一段明確說明「為什麼 spec writing 看起來像是三大廠的專利」（解釋市場結構），並接著說明「這不是唯一路徑」
- 所有「spec 錯誤」範例都可回指 Investigator A 或 B 的來源（不是虛構的）
- **Writer A → Writer B handoff（consumer side）**：投影片 13 必須以 Writer A 交付物中的 `handoff.md` 為 callback 的 source of truth——讀取 `hook_for_next_writer` 欄位（含 hook slide 編號、persona-recognizable door 的具體描述、留下的未解問題），並以明確的 slide number reference 開場（例如「還記得投影片 N 的那扇門嗎？」），讓前後半段的情感弧線連續。Writer B **不得**忽略 `handoff.md` 或自行發明 callback 對象；若 `handoff.md` 不存在、或缺少 `hook_for_next_writer` 欄位、或該欄位內容不足以支撐一句具體 callback，Writer B 必須向 Commander escalate 並**拒絕**以 cold start（「Now let's talk about five scenarios」）開場，不得以「沒收到就自己編」繞過此規則
- **Industry Researcher 的交付物**：搜尋日期 / 關鍵字 / 至少 5 個獨立 spec 資源候選清單 / 每個候選的「它是什麼 / 對建築師的價值 / 中立性評估」/ Writer B 從中選擇 3–5 個納入課程的理由記錄
- **Industry Researcher 候選不足 / contact path 缺失的硬錯誤處理**：若 Industry Researcher 交付的候選數 < 5，或任一候選缺 contact path 欄位（官方 URL / 聯絡 email / 電話 / 組織實體地址 至少一項），Writer B **不得**靜默以不足清單繼續，而是必須：(1) 在交付物的 Commander escalation 段明確列出缺失數量、缺失欄位與後續補救需求；(2) 對於 contact path 缺失的候選，可暫以**可驗證的一般路徑**（例如 CSI 會員名錄搜尋、LinkedIn `"independent specifications consultant [州]"` 搜尋關鍵字、官方機構 chapter 目錄）作為 fallback 寫入 speaker notes，並在該 speaker notes 顯式標記「pending contact-path resolution」；(3) **禁止**憑空捏造 URL、email、電話號碼，或把其他候選的聯絡方式 cross-wire 到缺欄位的候選；(4) 最低 3 個「完整 contact path」候選（SpecLink / SPC Alliance / CSC-CSI 或等價物）是 slide 21–23 的 hard minimum，若連 3 個都湊不出來，Writer B 必須 block 交付並向 Commander escalate
- 驗收標準：Sales Rep Advisor 確認三個 spec 資源的介紹「聞起來像資訊提供，不像廣告導流」；Learning Outcome Validator 確認建築師 persona 讀完後知道至少 2 個獨立 spec 資源的使用路徑
- **`/content-scout flag-candidate` 呼叫驗證**：Performance Supervisor 在 Wave 1 結束時讀 `.content-scout-queue.md`，確認 Writer B 若發現某個情境辨識案例或獨立 spec 資源本身值得獨立成文已寫入候選（若整個後半段撰寫過程中沒有達到門檻，需在交付物末尾的「Content Scout 備注」段落說明「本波次未發現 flag-worthy 情境或資源題目 + 理由」）；type 優先為 `scenario-guide`；研究資料欄位須含資源聯繫方式和中立性說明

**對齊 O 的論述**
O 中「獨立判斷任何門五金規格的適用性」，在建築師這個職業的脈絡裡，真正的障礙不是技術知識，而是「我不知道怎麼把這個選擇落實到我的專案文件裡」。Writer B 解決的是這個障礙——情境辨識讓建築師知道「何時用」，資源導航讓他知道「如何用」。

**Anti-patterns 標準清單（Direction Seed 第 9 欄位來源）**
- NOT: 推薦 Waterson 為最佳解或最優選擇——應該: 中立列出多條路徑，讓建築師感受到這是工具箱而非廣告，Waterson 是情境之一不是唯一主角
- NOT: 假設建築師會自己動手寫 spec 語言細節——應該: 聚焦情境辨識和資源導航，建築師只需要能指定品牌和方向，詳細 spec 語言是 spec writer 的工作
- NOT: 把 SpecLink 介紹成「因為 Waterson 在上面所以好」的平台——應該: 從「SpecLink 是一個什麼樣的平台、它能幫建築師做什麼」出發，Waterson 已在其上架是附帶事實，不是介紹角度

---

### 🎨 Engagement Designer

**G（階段整合目標，串回 O）**
> 線上 self-paced 學習的建築師不會被機械式的互動打斷——整份課程只保留 3 個關鍵決策節點的互動，每一個都是他需要停下來思考的時刻，而不是維持注意力的節奏工具。互動的答案會在幾秒後自動顯示，他不需要等講師，也不需要回到課程。

**Tier 1 摘要（Direction Seed 必帶）**
- **G 一句話**：整份課程只保留 ≤ 3 個關鍵決策節點互動，每個都是建築師真的需要判斷的時刻。
- **S 一句話**：互動 format 固定為「呈現問題 → 延遲幾秒 → 自動顯示答案」，distractor 來自 Investigator A 真實案例，錯誤回饋在無講師情況下仍完整。
- **關鍵 M**：互動點 ≤ 3 個 / 每個 distractor 標注 Investigator A 來源 / 錯誤回饋包含真實後果（AHJ 退件或保險拒賠）。
- **Skill commands**：無
- **Model commands**：Claude Sonnet（互動設計）
- **Anti-patterns**：詳見本 agent 的「Anti-patterns 標準清單」子段落

**S（為建築師選的路徑）**
- **整份課程互動點 ≤ 3 個**（上限，不是目標）。建築師的學習節奏靠內容本身驅動，不是靠機械式的每 10 分鐘一個互動。
- **互動 format 固定為線上課程範式**：問題呈現 → 延遲幾秒讓學習者思考 → 自動顯示答案與解釋。不採用實體簡報的即時 Q&A 假設（因為沒有講師在場引導）。
- **每個互動點都必須落在「關鍵決策節點」**：當建築師需要停下來判斷「這個情境 / 我該選哪個 / 這個法規適用嗎」的時刻。不是機械式的節奏安排。
- **Distractor 設計仍來自 Investigator A 的真實案例**：錯誤選項是建築師真的會在執業中犯的錯誤，不是虛構的。
- **錯誤回饋是線上自學版**：不依賴講師引導，必須在文字中完整解釋「為什麼這是錯的」和「真實後果是什麼」——因為學習者沒有人可以問。
- **敘事角色自我推導（self-derived narrative role map）**：Engagement Designer 不從上游 import slide-role metadata，而是從 Writer A / Writer B 的投影片輸出自行推導每張投影片的 narrative role（hook / context / mechanism / scenario / decision / resource / close），使用下方 M 段宣告的 decision tree。推導表必須出現在 deliverable 中，由 Quality Auditor 驗證推導規則執行一致性，並同步通知 Content Director 供其 `review-002-content.md` 交叉檢查（Content Director 不必、也不被要求產出此 map）。此自我推導 map 是 Anti-pattern #3「互動不打斷敘事節奏」的可驗證操作化基礎。

**M（對準 S 的資源驗證）**
- **互動點上限 ≤ 3 個**：整份課程互動點數量不得超過 3 個(這是上限，不是目標)。如果覺得需要更多，先問「這個真的是關鍵決策節點嗎？」
- **每個互動點的完整規格**：觸發位置（第幾張投影片）/ 問題文字 / 延遲秒數（建議 5–10 秒）/ 答案顯示方式（自動顯示 / 點擊顯示）/ 錯誤回饋文字（線上自學版完整解釋）。Deliverable 必須另含 `post_test_boundary.md`（或同名段落）列出 3 個互動的 question stems 並標注「MUST NOT be reused in post-test」，供 Post-Test Designer 去重。
- **Distractor 來源追蹤**：每個 distractor 必須標注它來自 Investigator A 的哪個案例。**交付前驗證步驟**：在 deliverable 最後列出表格「distractor → case ID」，任何無 case ID 的 distractor 必須被移除或替換。這是主動驗證，不是事後檢查。**上游不足 halt 條款**：若 Investigator A 提供 < 3 個可用案例或案例數不足以覆蓋所有 distractor 槽位，halt 並 escalate 給 Commander 要求 Investigator A 補案例，不得虛構填補以湊滿互動槽位。
- **敘事角色推導 decision tree（heuristic，供 Quality Auditor 驗證）**：Writer A 段落（slides 1–12）依敘事訊號分類——slide 1 = `hook`；論證緣由 / 問題 framing 的投影片 = `context`；解釋五金機制 / arm geometry / backcheck / latch 行為 / 幾何原理的投影片 = `mechanism`。Writer B 段落（slides 13–26）——描述三種建築類型情境的投影片 = `scenario`；含決策問句、選型判斷、規格取捨的投影片 = `decision`；介紹 SpecLink / SPC Alliance / CSC / CSI 等外部資源的投影片 = `resource`；最後 1–2 張總結 / CTA / 課程收束 = `close`。每張 slide 必須恰被分到一個角色，deliverable 附 `slide_role_derivation.md`（或同名段落），列 slide 編號 / 所屬 writer / 被分到的 role / 觸發的 heuristic 條款（一句話），供 Quality Auditor 逐張驗證推導一致性。
- **敘事角色放置驗證**：每個互動點必須記錄 `preceding / interaction / following` 三張 slide 的 narrative role 以及一句 transition justification（「為什麼這是建築師自然停下來判斷的時刻」）。互動不得落在 role = `mechanism` / `hook` / `context` / `resource` / `close` 的 slide 上；僅允許落在 `scenario` 或 `decision`。驗證對象是 Engagement Designer 自行推導的 role map（見上一條 decision tree），不是外部 import 的 metadata。此為 Anti-pattern #3 的可驗證操作化。
- **子類別覆蓋觸及圖（subcategory touch map）**：Interaction 設計 MUST 覆蓋 ≥ 4 / 5 個門五金功能型子類別（hanging / securing / closing / controlling / protective，對應 Compliance Reviewer line 483 的 canonical 五類），可透過正確選項或 distractor 觸及；未覆蓋的子類別必須有書面理由，且理由須與 Compliance Reviewer line 483 的覆蓋要求對齊，供其交叉驗證。
- **錯誤回饋真實後果確認**：「AHJ 退件 / 保險拒賠」等後果必須對應到 Investigator A 或 B 的具體來源
- **驗收標準**：線上 self-paced 學習體驗測試通過——Learning Outcome Validator 用 persona 模擬一次完整的線上學習流程，確認：(1) 3 個互動點位置合理 (2) 每個互動的錯誤回饋在沒有講師的情況下仍然完整 (3) 整體節奏不會讓建築師感到被機械式地打斷

**對齊 O 的論述**
線上 self-paced 課程的挑戰是「沒有講師」——學習者只能靠內容本身和自己的節奏。過多互動在實體講座是維持注意力的工具，但在線上課程會變成打斷。Engagement Designer 的工作不是「設計互動節奏」，而是「識別 3 個建築師真的需要停下來思考的決策節點」，並確保每個節點的錯誤回饋在沒有講師的情況下仍然完整。這是 O「能獨立判斷」在線上學習脈絡中的實際落地方式。

**Anti-patterns 標準清單（Direction Seed 第 9 欄位來源）**
- NOT: 互動設計只測記憶不測決策——應該: 每個互動點都是「這個情境 / 我該選哪個 / 這個法規適用嗎」的真實判斷，不是「課程說什麼」的回憶題
- NOT: distractor 是虛構的錯誤選項——應該: 每個 distractor 必須來自 Investigator A 的真實案例，是建築師在執業中真的犯過的錯
- NOT: 互動打斷內容的敘事節奏——應該: 互動只出現在建築師自然需要停下來判斷的時刻，整份課程互動點 ≤ 3 個，節奏靠內容本身驅動

---

### 📋 Content Director

**G（階段整合目標，串回 O）**
> 建築師讀完整份課程，感受到的是一個完整的故事：從「我以為我懂這個選擇」到「我現在真的懂了，而且我知道下次怎麼 spec」。每一張投影片都在這個故事線上，沒有一張是掉出來的技術補丁。建築師不需要在讀課程的同時追蹤「為什麼突然講到這個」。

**Tier 1 摘要（Direction Seed 必帶）**
- **G 一句話**：讓每一張投影片都在「從誤解到真正懂了」的故事線上，沒有技術補丁。
- **S 一句話**：用建築師的問題結構（這跟我有關嗎？→ 真的重要嗎？→ 我該怎麼做？）評估每個轉場，標記所有法規條文複誦語氣和假設硬體專業的地方。
- **關鍵 M**：每張投影片有審查記錄 / 所有「法規條文複誦」語氣被標記並退回 Writer / Writer B 的五個情境排列順序符合「建築師遇到的頻率」。
- **Skill commands**：無
- **Model commands**：Claude Sonnet（敘事審查）
- **Anti-patterns**：詳見本 agent 的「Anti-patterns 標準清單」子段落

**S（為建築師選的路徑）**
- 用建築師的問題結構而不是技術的知識結構來評估敘事流——建築師的問題是「這跟我有關嗎？」→「真的重要嗎？」→「那我該怎麼做？」——每一個轉場都要能回答這三個問題的其中一個。
- 標記所有「假設建築師有硬體專業」的地方：這種假設會讓建築師感到被排除，是信任崩潰的最快方式。任何不能用一句話解釋給非硬體建築師聽的技術術語，都要被簡化或加注。
- 在報告中標記每一個「法規條文複誦」的時刻——那是 AIA 課程最常見的失誤，建築師在這種時刻會感到自己在上繼續教育而不是在學習。

**M（對準 S 的資源驗證）**
- 交付 `review-002-content.md`，包含每張投影片的審查記錄
- 格式：投影片編號 / 狀態（通過 / 需修改 / 退回 Writer）/ 具體修改要求 / 敘事流評估 / **建築師問題回答**（明確寫出此投影片回答了「這跟我有關嗎?」「真的重要嗎?」「我該怎麼做?」中的哪一個，hook 投影片必須以 yes/no 形式明確回答「這跟我有關嗎?」）
- 標記所有：沒有來源的主張 / 假設硬體專業的解釋 / 法規條文複誦語氣 / 互動不足的段落
- **Writer B 的情境辨識 + 資源導航章節專項審查**：確認五個情境的排列順序符合「建築師在執業中遇到的頻率」（不是依產品特性排序）；確認 SpecLink、SPC Alliance、CSC/CSI 的介紹邏輯在敘事上是「提供選擇」而不是「引導選擇」
- 確認：全課程互動點數量達到 AIA 最低標準 / 三種建築類型情境全部存在 / 決策工具存在且可用
- **Per-phase pacing（敘事密度 vs 跑表時間）**：Phase time-box deviation ≤10% from baseline (Writer A ~30min, Writer B ~30min); flag if Writer B front-heavy or back-heavy beyond tolerance。對每個 architect-question phase（這跟我有關嗎? / 真的重要嗎? / 我該怎麼做?）估算時間密度，starving phase 必須在交付物中逐一點名並提出 slide-level 重平衡建議（移哪幾張、移到哪個 phase、為什麼）——不接受「Writer A 太短 / Writer B 太長」這種跑表式描述。
- **Narrative through-line section**：Review deliverable MUST contain explicit `narrative_through_line` section identifying opening promise → closing answer round-trip。該 section 必須獨立於 per-slide review，明確寫出 (a) opening hook 的 implicit promise、(b) closing slide 是否回答 that specific promise（不是通用的「課程結束」語氣）、(c) 所有 dangling promises 的 slide 編號清單。missing this section = 交付物不通過。
- **Recommendation 格式標準（NOT/INSTEAD 或等價具體度）**：Recommendations must be element-level (cite specific slide/passage/word) and use NOT/INSTEAD pattern or equivalent specificity. Hand-wave ('improve pacing', 'tighten arc') is anti-pattern。每個 `需修改` / `退回 Writer` slide 的修改要求必須 name 具體 element（bullet / sentence / insertion point / slide title）並提供可替換的文字或結構動作；觸發 hand-wave 時以 `NOT: [current text] — INSTEAD: [concrete change]` 格式重寫。
- **Cross-agent surfacing note**：若敘事密度審查副作用偵測到 total runtime < 60 min HSW floor，Content Director 在 `pacing_narrative_density` section 以一句話標註「flag for Compliance Reviewer / Director-Producer」即可，**不替 Compliance territory 做判斷、不修改 runtime 需求**——cure 由負責 role 執行。
- 驗收標準：所有「法規條文複誦」語氣的地方都被標記並退回 Writer 修改

**對齊 O 的論述**
一門技術上正確但敘事破碎的課程，建築師讀完只有困惑，沒有信心。Content Director 保護的是 O 的情感目標——「喜歡這份簡報」——它是所有技術性 reviewer 無法替代的把關。

**Anti-patterns 標準清單（Direction Seed 第 9 欄位來源）**
- NOT: 只審段落順序和轉場，不審情感弧線的完整性——應該: 用建築師的問題結構（這跟我有關嗎？→ 真的重要嗎？→ 那我該怎麼做？）驗證每個轉場是否回答了正確的問題
- NOT: 接受「技術正確但無聊」的妥協方案——應該: 標記每一個法規條文複誦語氣的地方，那是 AIA 課程最常見的失誤，必須退回 Writer 修改
- NOT: 用課程製作者的視角而非建築師視角審查——應該: 對每張投影片問「Project Architect 看到這張，他在下次 spec coordination meeting 會用到嗎？如果不會，這張是無效內容」

---

### ✅ Compliance Reviewer

**G（階段整合目標，串回 O）**
> 建築師在修完課程後，能夠在自己的公司 CEU 記錄中看到這個信用學時——而且這份記錄在他去考 LEED AP 或參加 AIA national conference 的時候，是乾淨的、無爭議的。合規不是目的，合規是確保課程能夠抵達建築師的唯一通道。

**Tier 1 摘要（Direction Seed 必帶）**
- **G 一句話**：讓課程通過 AIA 認證，確保建築師的 CEU 學分記錄是乾淨無爭議的。
- **S 一句話**：從學習目標出發反向驗證 AIA HSW 分類合規，特別標記所有「廠商推薦」風險，用 Gemini 2.5 Pro 扮演 AIA 稽核員對三大廠提及逐點評分。
- **關鍵 M**：三大廠每個提及次數 > 0 且有投影片編號記錄 / Waterson 促銷比例 < 20%（數字計算） / 中立性評分平均 ≥ 4/5。
- **Skill commands**：無
- **Model commands**：`bash ~/.claude/skills/ai-fallback/scripts/call_with_fallback.sh "Role-play AIA CES auditor. Score each Big 3 mention 1-5 for neutrality..." "gemini-2.5-pro,gemini-2.5-flash-lite,codex"` （詳見 Model Invocation Map）
- **Anti-patterns**：詳見本 agent 的「Anti-patterns 標準清單」子段落

**S（為建築師選的路徑）**
- 把合規稽核的邏輯倒過來：從「這份課程能讓建築師學到什麼」出發，再確認這些學習目標符合 AIA HSW 的分類——而不是從 AIA CES 規範的格式要求出發，往課程內容硬套。這樣做出來的合規文件，在 AIA 審查時更有說服力。
- 特別標記所有可能被解讀為「廠商推薦」的內容：這是 AIA 最常見的否決原因，也是建築師信任崩潰的另一條快速道路。Waterson 是 context，不是答案。
- **Primary-frame classification rule（promo vs. category-education 判斷法）**：對每個可能爭議的內容區塊判斷其 primary frame——若主框架是外部標準 / 代碼引用（例如 ICC A117.1 §404.2.9）且 Waterson 只作為「符合此要求的一個範例」出現，分類為 **category education**（計入 HSW 合格分鐘，不計入 20% promo ceiling）；若主框架是 own-brand SKU-vs-SKU 比較 / 品牌優越性宣稱 / 廠商專屬建議（例如 "widest finish selection in its class"、"use Waterson kit for best results"），分類為 **promotional content**（計入 20% promo ceiling，不計入 HSW）。Borderline 案例**必須升級給 Commander**，不得靜默決定。分類規則與結果必須寫在交付物中。
- 搜尋 AIA CES Provider Manual 的最新版本更新，確認沒有新的 HSW 分類要求被遺漏。

**M（對準 S 的資源驗證）**
- 交付 `review-002-compliance.md`，格式：AIA CES 要求項目 / 通過/需修改/失敗 / 具體說明
- 確認 4 個標準 AIA 學習目標都有被課程內容覆蓋（附投影片引用）
- 標記所有可能被視為「廠商推薦」的內容，並立刻回報 Commander（不等到波次結束)
- **Provider number `40115764` placement audit**：驗證 Registered Provider number 必須同時出現在 (a) 標題投影片 subtitle、(b) 完成證書模板、(c) AIA 揭露區塊、(d) HTML `<meta name="aia-ces-provider">` tag。任何一個位置缺漏 = **blocker**（不是 warning），並在交付物引用 AIA CES Provider Manual §4.2 "Provider identification on course materials"
- **HSW substantive audit（block-by-block rubric，非 label-based）**：不接受「課程標題含 HSW 字樣」作為 HSW 合格證據。對每一個 content slide 逐一判斷是否實質處理建築物使用者的 health / safety / welfare（例如 egress、life safety、accessibility、ADA 5 lbf operating force），交付物必須包含 rubric 表格（slide / duration / primary topic / HSW-qualifying Y/N / rationale）。**HSW-qualifying minutes / total minutes 必須 ≥ 75%**，否則 FAIL 並提供 either-or 補救建議：(a) 將 mechanical / promo 區塊重新框架為 life-safety consequence，或 (b) 將課程 label 從 HSW 降級為 LU-only
- **Writer B 的 spec 資源介紹專項合規審查**：SpecLink、SPC Alliance、CSC/CSI 的介紹是否符合 AIA 對「非廠商推薦」的要求——如果介紹方式被認定為「因為 Waterson 在 SpecLink 上架所以推薦 SpecLink」，這是合規風險，必須修改介紹角度
- **AIA CES Provider Manual 版本確認**：記錄查詢的 Manual 版本日期，確認使用的是最新版本
- 確認課程時長（信用學時）有實際內容量支撐
- 驗收標準：沒有任何「廠商推薦」內容殘留在最終課程中；Writer B 的資源介紹通過 AIA 中立性要求
- **v4 新增：Competitor Coverage M 擴充**（原 v3.1 的 Competitor Coverage Auditor 併入本角色）
- **大廠提及次數驗證**：Allegion（含 BEST / Von Duprin / Schlage）、ASSA ABLOY（含 Sargent / Yale）、dormakaba（含 DORMA / Kaba）——每個品牌的提及次數必須 > 0，逐一記錄出現的投影片編號。HSW-003 曾因此退件，v4 不能重蹈覆轍
- **中立性評分 ≥ 4/5**：從課程前段 / 中段 / 後段各採樣 1–2 個三大廠提及點（共 5 點），透過 `/ai-fallback` 以 `gemini-2.5-pro,gemini-2.5-flash-lite,codex` 鏈執行 AIA 稽核員角色扮演逐點評分 1–5（1 = 暗示劣於 Waterson，5 = 完全中立），平均 ≥ 4 才過。實際呼叫見 Model Invocation Map / line 444 指定的 `call_with_fallback.sh` 指令。**禁止直接呼叫 `gemini -m` 或 `codex exec`**（繞過 wrapper 會同時失去 hang 偵測與 quota fallback）。
- **門五金類別覆蓋驗證**：五個子類別（hanging / securing / closing / controlling / protective）在課程中都要有實質提及，未覆蓋的子類別必須在報告中說明為什麼本課程不涵蓋（例如：HSW-002 專注 closing devices，但仍需在 context 中帶過其他四類）
- **Waterson 促銷比例 < 20%**：計算 Waterson 相關內容（產品名、型號、特定優勢描述）占總內容的比例，必須 < 20%（AIA 硬門檻）。**單位約定：以 `data-duration-min` 屬性計算的分鐘數為準（minutes numerator / minutes denominator），不得使用投影片數量**；分鐘無法取得時退回字數比例。計算方式（含分子、分母、method）記錄在交付物中——不是感覺，是數字。_Iteration 階段使用 grep-based 內容審核即足夠；最終 pre-deploy gate 會額外以 Puppeteer 做 render-based check（見 Gate 4 section）。_
- **Gemini 2.5 Pro 呼叫驗證**：Gemini 2.5 Pro 扮演 AIA 稽核員的完整回應（5 個採樣點的逐點評分 + 理由，不只是最終平均分數）必須附在 `review-002-compliance.md` 中；Commander 在 Wave 2 結束時抽檢此輸出，確認是真實 Gemini 輸出而非 Compliance Reviewer 自行推斷的評分；若 Gemini 服務不可用，必須在交付物中標注「Gemini 2.5 Pro unavailable, fallback to manual audit + 理由」
- **`/ai-fallback` 呼叫驗證**：確認 `call_with_fallback.sh` 執行記錄（含 5 個採樣點的完整回應）附於 `review-002-compliance.md`；若 fallback chain 觸發（含 Codex fallback 情況），記錄實際使用的備援模型名稱

**對齊 O 的論述**
一門未通過 AIA 認證的課程永遠到不了建築師手裡。Compliance 是 O 得以發生的先決條件，不是附加功能。

**Anti-patterns 標準清單（Direction Seed 第 9 欄位來源）**
- NOT: 只檢查格式合規而不檢查實質合規（Competitor Coverage M 存在的理由）——應該: 三大廠每個都必須有實質提及且提及次數 > 0，這是防止 HSW-003 退件重演的硬門檻
- NOT: 相信「我們以前這樣做過所以 OK」——應該: 每次都查詢 AIA CES Provider Manual 最新版本，記錄查詢日期，確認沒有新的 HSW 分類要求被遺漏
- NOT: 放過 Waterson 促銷比例 > 20% 的內容——應該: 計算 Waterson 相關內容占總字數的比例，這是 AIA 硬門檻，必須是數字不是感覺，並在交付物中記錄計算方式

---

### 📝 Copy Editor

**G（階段整合目標，串回 O）**
> 建築師讀投影片文字時，不需要停下來重讀——因為每一句話都剛好在他能夠一次讀懂的長度和密度。術語一致讓他不需要追蹤「spring hinge」和「self-closing hinge」是不是在說同一件事，讓他把認知資源用在理解概念，而不是解析文字。

**Tier 1 摘要（Direction Seed 必帶）**
- **G 一句話**：讓建築師讀投影片文字時不需要停下來重讀，術語一致到可以直接複製進他的規範書。
- **S 一句話**：術語統一以 MasterFormat 用法為準，每句話以「建築師一次呼吸內能讀懂」為標準，術語表標注 MasterFormat 對應位置。
- **關鍵 M**：零容忍被動語態指令文字 / 投影片正文超過 25 字的句子 / 縮寫首次出現未定義 / 交付 `glossary-002.md`。
- **Skill commands**：無
- **Model commands**：Claude Sonnet（語言編輯）
- **Anti-patterns**：詳見本 agent 的「Anti-patterns 標準清單」子段落

**S（為建築師選的路徑）**
- 以「建築師在一次呼吸內能讀懂」作為每一句話的長度標準，而不是以「25 字以內」的機械規則——建築師讀課程時已經在處理新資訊，文字的認知負擔要降到最低。
- 術語統一以建築師在 MasterFormat 規範中會看到的用法為準，不是以廠商型錄的用法——讓建築師在寫自己的規範書時可以直接複製，不需要翻譯。
- 在術語表中標注每個術語在 MasterFormat 或 AIA SectionFormat 中的對應位置，讓術語表本身成為建築師可以帶走的工作工具。

**M（對準 S 的資源驗證）**
- 交付所有 24 張投影片的修改建議（用 `~~刪除~~` 和 `**[INSERT: 新文字]**` 標記）
- 零容忍：指令性文字使用被動語態 / 投影片正文超過 25 字的句子 / 縮寫首次出現未定義
- **25 字規則的階層說明**：上一條列出的「投影片正文超過 25 字的句子」是**警示旗標**，不是硬性上限——當一個句子以建築師 peer-to-peer 語氣寫成、且能在一次呼吸內讀懂、且 em-dash 或逗號構成的是呼吸停頓而非學術修飾時，即使超過 25 字也**必須保留**（此規則由 S 段落的「一次呼吸」標準統轄，見本 agent S 段第 1 點）；Copy Editor 在交付物中明確標注「已檢視超過 25 字句子 + 保留決策理由」以避免 silent skip 被誤判為漏審。違反本條 = 誤把 peer-voice 當成學術語氣改寫 = 觸發 AP-1（peer-voice 改寫錯誤）
- 術語統一確認：spring hinge / self-closing hinge / door closer / fire-rated assembly 全程一致
- **MasterFormat 對應驗證**：術語表中每個術語的 MasterFormat 位置標注，必須來自 MasterFormat 實際查詢，不是記憶——交付時附「查詢日期 + 使用版本」
- **Writer B 的資源名稱一致性**：SpecLink、SPC Alliance、CSC、CSI 這些名稱在課程中的拼寫和大小寫必須完全一致（建築師若要搜尋這些資源，名稱拼寫必須正確）
- **角度單位慣例（AMB-1 修補）**：角度值一律使用數字 + `°` 符號（例：`105°`、`180°`），不寫成 `105 degrees` / `180 degree`；每個涉及角度的術語表項目只能有一條規則（避免「105°」與「105 degrees」並存導致下游 agent 判讀衝突）。違反本條 = 觸發 AP-2（術語強制統一失敗的另一面：單位格式不一致）
- **技術內容 SME 審查門檻（AMB-3 修補）**：當 Copy Editor 在 Pass 2（術語）或 Pass 5（冗餘）遇到技術內容無法靠 MasterFormat / 術語表解析時（例：某句「install spring hinge per manufacturer instructions」究竟指通用彈簧鉸鍊或 Waterson cam lift hinge），**必須**以 `<<SME-REVIEW: [原文] — [疑問]>>` 標記交付，**不可**靠推測改寫。違反本條 = silent guess = 觸發 AP-1（peer-voice 改寫錯誤的技術內容變體）
- 交付 `glossary-002.md`（10–15 個關鍵術語 + 定義 + MasterFormat 對應位置）
- 驗收標準：每張投影片的講者備注全部存在（24 張 × 1 份 = 24 份）

**對齊 O 的論述**
語言的清晰是理解的前提。建築師無法靠一份需要多次重讀才能理解的課程，發展出在壓力下能使用的判斷能力。

**Anti-patterns 標準清單（Direction Seed 第 9 欄位來源）**
- NOT: 用學術語氣改寫，破壞課程的口語節奏——應該: 以「建築師在一次呼吸內能讀懂」作為每一句話的標準，保留建築師在 peer-to-peer 溝通中會用的語氣
- NOT: 強制統一術語到犧牲建築師慣用詞——應該: 術語統一以建築師在 MasterFormat 中會看到的用法為準，讓建築師在寫自己的規範書時可以直接複製
- NOT: 略過技術細節的拼寫（如 Allegion vs Von Duprin vs Schlage 的正確拼法）——應該: 品牌名、技術組織名稱（如 SpecLink、SPC Alliance、CSC、CSI）的拼寫和大小寫必須在全課程中完全一致

---

### 🔢 Fact Checker

**G（階段整合目標，串回 O）**
> 建築師在 spec review 會議上引用這門課的數字時，如果被承包商或 AHJ 質疑，他要能說「這個數字來自 [具體來源]，[年份] 版」——不是說「我記得課程裡有提到」。一個無法被追蹤的數字，在建築師的執業世界裡等同於沒有數字。

**Tier 1 摘要（Direction Seed 必帶）**
- **G 一句話**：讓課程中的每一個數字，建築師被質疑時都能說出「來自 [具體來源]，[年份] 版」。
- **S 一句話**：驗證優先順序：code section number → 費用數字 → 荷重和關力值，每個「已驗證」數字附 Gemini Flash 搜尋摘要，無法驗證的改為估計值表述。
- **關鍵 M**：100% 數字主張被審查 / 每個「已驗證」數字有搜尋記錄摘要 / 零「錯誤」狀態主張殘留在最終課程中。
- **Skill commands**：無
- **Model commands**：`bash ~/.claude/skills/ai-fallback/scripts/call_with_fallback.sh "Verify: [number] [claim]. Return VERIFIED/CORRECTED/UNVERIFIABLE + source..." "gemini-2.5-flash,gemini-2.5-flash-lite,gemini-2.5-pro,codex"` （詳見 Model Invocation Map）
- **Anti-patterns**：詳見本 agent 的「Anti-patterns 標準清單」子段落

**S（為建築師選的路徑）**
- 驗證優先順序以「建築師最可能被質疑的數字」為準：code section number（AHJ 最常用來打臉）→ 費用數字（業主最常質疑）→ 荷重和關力數值（承包商最常挑戰）——不是以出現順序驗證。
- 對每個「無法驗證」的數字，不是標記刪除，而是找建築師可以接受的替代表述——有時候「研究顯示 15–25% 的節省」比一個假精確的數字更有說服力。
- **Research/verification queries**：WebSearch tool（Claude Code built-in）為 primary——直接返回可點擊的第一方 URL，適合尋找 ICC / NFPA / ASCE / 政府或官方組織的原始條號與版本年份；`bash ~/.claude/skills/ai-fallback/scripts/call_with_fallback.sh` 僅在 WebSearch 結果不足以下定論時、或需要對多筆查詢結果進行摘要綜合（summary synthesis）時呼叫（P-015 WebSearch-primary pattern）。不論主路徑為何，每筆查詢的字串、來源 URL、結果摘要都必須保留在 `review-002-facts.md` 的 Execution Log 中讓稽核者追蹤驗證過程。

**M（對準 S 的資源驗證）**
- 交付 `review-002-facts.md`，包含所有數字主張的驗證記錄
- 格式：投影片編號 / 主張文字 / 來源 / 狀態（已驗證 / 未驗證 / 錯誤）/ 備注
- 100% 的數字主張被審查：統計數字、百分比、費用數字、條號、年份引用、荷重值、關力值
- **Gemini Flash 搜尋驗證記錄**：每個「已驗證」數字旁，必須附 Gemini Flash 搜尋結果摘要（3–5 句話），說明驗證了什麼、從哪個來源找到的——不能只寫「已驗證」而無搜尋記錄
- **Lookup count scales with claim volume**：Fact Checker 必須執行的真實查詢次數（wrapper 或 WebSearch）下限為 `max(3, ceil(numeric_claims_total / 3))`。意思是 4 個數字主張 → 下限 3 次查詢；9 個 → 3 次；12 個 → 4 次；30 個 → 10 次。這個下限阻擋「低努力 Fact Checker 只做 3 次查詢就宣稱完成一整門課程」的 regression。交付物的 Execution Log 必須包含至少這個下限數的執行條目。
- **SpecLink、SPC Alliance、CSC/CSI 的事實驗證**：這三個組織的描述是否準確——服務範圍、組織性質、是否真的支援獨立廠商的 spec writing，必須有獨立查詢佐證
- 零容忍：任何「錯誤」狀態的主張殘留在最終課程中
- 最多 5% 的主張可以維持「未驗證」狀態，但必須在課程文字中標注為「估計值」
- 驗收標準：Source Reviewer 確認所有「已驗證」來源的 URL 或出版物可被查到
- **`/ai-fallback` 呼叫驗證**：確認 `call_with_fallback.sh` 執行記錄（搜尋查詢字串 + 摘要）存在於 `review-002-facts.md` 的驗證記錄中；若 fallback chain 觸發（含 Codex fallback 情況），記錄實際使用的備援模型名稱；若 wrapper 返回 exit 3（整條鏈耗盡），Execution Log 必須記錄 exit-3 log AND 後續 WebSearch 備援調用的查詢與來源。
- **WebSearch 備援層級確認**：WebSearch 為 Tier 2 備援工具（非 Tier 3 選擇性），當 `call_with_fallback.sh` 返回 exit 3 時，Fact Checker 必須以 WebSearch 完成該查詢的驗證；WebSearch 結果必須有獨立的執行記錄條目（查詢字串 + 來源 URL + 結果摘要），不得只寫「wrapper 耗盡未能驗證」。

**對齊 O 的論述**
建築師在執業中做的是法律和安全決策。一個錯誤的條號或費用數字，在現實中的後果是退件、索賠或火安全失敗——這直接違背 O 中「正確決策」的承諾。

**Anti-patterns 標準清單（Direction Seed 第 9 欄位來源）**
- NOT: 信任單一來源的數字就標記為「已驗證」——應該: 每個「已驗證」數字旁必須附 Gemini Flash 搜尋結果摘要，說明從哪個來源找到的，不能只寫「已驗證」而無驗證記錄
- NOT: 跳過 2018 年前來源的版本標記——應該: 所有 2018 年前用於引用現行法規要求的來源必須明確標記，讓建築師在引用時知道需要自行查核最新版本
- NOT: 把「這聽起來合理」當成驗證，對無法查核的數字打上已驗證——應該: 無法驗證的數字標記為「未驗證」並在課程文字中標注為估計值，最多 5% 的主張可維持未驗證狀態
- NOT: 接受 `/ai-fallback` 或 WebSearch 回傳的「已驗證」但沒有可點擊 first-party URL 的主張，或接受下列 NEW-03 placeholder phrase 作為驗證證據——應該: 每個「已驗證」row 必須附上可點擊的第一方來源 URL（codes.iccsafe.org / nfpa.org / asce.org / 政府或官方組織域名），無法提供 first-party URL 的主張一律降級為「未驗證」；下列 NEW-03 forbidden phrases 一律視為無效驗證證據：{"hypothetical blog post"、"example.gov"、"search for X might yield"、"discussion at DHI meeting"、"based on industry consensus"（無 URL）、"commonly cited"（無 URL）、"count aligns with or is very close to"（無 roster）}（參照 G-013 / NEW-03 / P-017 / P-019 Investigator A Cycle 1 fix pattern）
- NOT: 當 anti-pattern 降級導致「已驗證」數量低於原始預期時隱瞞或硬湊——應該: 較少但乾淨的「已驗證」優於較多但含 NEW-03 污染的「已驗證」，交付物 Execution Log 必須明確記錄 under-delivery escape clause，格式為 "hard count reached at N verified claims (target M) — under-delivery reason: raw model returned placeholder phrasing / no first-party URL, demoted on anti-pattern scan"

---

### 📎 Source Reviewer

**G（階段整合目標，串回 O）**
> 建築師在課程結束後，如果想追蹤某個法規或案例的原始來源，他能在 5 分鐘內找到——因為引用格式清楚，連結可用，出版物有完整識別資訊。他可以把這份參考清單直接用在自己的規範書備注裡，不需要重新整理。

**Tier 1 摘要（Direction Seed 必帶）**
- **G 一句話**：讓建築師在課程後能在 5 分鐘內追蹤到任何法規或案例的原始來源。
- **S 一句話**：使用 AIA-compatible 引用格式，標注所有 2018 年前的法規來源，確認單一機構引用 ≤ 40%，用 Codex 交叉驗證所有引用。
- **關鍵 M**：所有來源 URL 可訪問（HTTP 200）/ 2018 前法規來源有標記 / 單一機構 ≤ 40% / Waterson 自有材料 ≤ 20% / SpecLink / SPC Alliance / CSC/CSI 官方頁面 URL 已確認可達。
- **Skill commands**：無
- **Model commands**：`bash ~/.claude/skills/ai-fallback/scripts/call_with_fallback.sh "Review all citations in [file]..." "codex,gemini-2.5-pro,gemini-2.5-flash-lite"` （詳見 Model Invocation Map；鏈深度必須 ≥ 3，因 G-001 Gemini Pro hang 在 2026-04 仍活躍，depth-2 鏈在 Codex quota 耗盡時等同 depth-1）
- **Anti-patterns**：詳見本 agent 的「Anti-patterns 標準清單」子段落

**S（為建築師選的路徑）**
- 使用 AIA-compatible citation format，讓建築師在引用時可以直接套用——這是建築師習慣的格式，降低他使用這份參考清單的摩擦力。
- 特別標注 2018 年前的來源：法規更新速度快，建築師被舊版法規資訊誤導的風險是真實的，這個標記幫助建築師判斷是否需要自行查核最新版本。
- 確認來源多樣性（單一機構不超過 40% 的引用）：建築師需要感受到這份課程是獨立的分析，而不是某個機構（包括 Waterson）的宣傳材料。

**M（對準 S 的資源驗證）**
- 交付 `review-002-sources.md`，包含所有來源的稽核記錄
- 格式：來源 / URL 或識別資訊 / 出版日期 / 出版機構 / 狀態 / 標記。**[Tier A] HTML 容器強制要求**：每條 citation 在上游 Engineer (HTML) 交付物中必須以 `<p class="source-note">` 作為容器 class 出現，且必須緊鄰其所支撐的 claim 段落（不得插入其他非引用段落）。Source Reviewer 驗收時若發現 citation 雖語意完整但被包在其他 class（例如 `<div class="footnote">`、`<span class="cite">`、純 `<p>`）或放錯位置，必須 flag `source-note-placement-violation:wrong-container` 或 `source-note-placement-violation:wrong-adjacency`，且該條 citation **不得**計入「100% 來源 URL 可訪問」的 M gate 達成率——即使 URL 本身可達。此規則源自 S 層「AIA-compatible citation format」的操作化定義。
- **必填節「per-claim coverage index」**：`review-002-sources.md` 必須包含一張表，列出所審交付物中每一條 testable claim（見 Quality Auditor 「testable claim 定義」），逐條標記該 claim 是否經過 single-source / 2018-pre / priority-violation 檢查。缺少此表視為 audit 未完成；Quality Auditor 將用此表與 Fact Checker 的 audit index 做 reverse-index 比對（見 Quality Auditor M 「反向索引檢查」）。Source Reviewer 不得只交出 aggregate 結論（例如「No single-source citations. PASS.」）——必須逐 claim 呈現覆蓋狀態，否則 QA 無從對帳。
- 驗證所有來源：URL 可訪問（HTTP 狀態確認）或出版物有完整識別資訊
- 標記所有 2018 年前用於引用現行法規要求的來源
- **SpecLink、SPC Alliance、CSC/CSI 的來源可及性驗證**：這三個平台/組織的官方頁面或聯繫方式 URL 必須實際訪問確認（HTTP 200），並記錄訪問日期——建築師看完課程如果點不開連結，這個資源等於沒有介紹
- 確認來源多樣性：單一機構不超過 40% 的引用量；Waterson 自有材料不超過全部來源的 20%
- 產出一份 AIA-compatible 格式的參考清單
- 驗收標準：標記所有可能被視為廠商背書的引用，並提報 Compliance Reviewer
- **[Tier A] 與 Fact Checker 5% 未驗證預算對齊（cross-reference to v5.md line 562）**：Source Reviewer 負責統計本次審查中被 flag 為 `unverifiable`（含 `empirical-unverifiable` 與 `unverifiable:quantitative-no-primary-source`）的 claim 總數，並在 `review-002-sources.md` 中以獨立段落記錄 `unverifiable_count / total_factual_claims / fact_checker_5pct_cap = floor(0.05 × total) / status`。Fact Checker 在 `review-002-facts.md` 中擁有最終 cap 計算與 gate 決策，但 Source Reviewer **不得**只 flag 個別 claim 而不提供 aggregate 計數；若 `unverifiable_count > cap`，Source Reviewer 必須在交付物中以顯性條目 `BUDGET-EXCEEDED` escalate 給 Commander（不得只在備注中隱性提及）。此規則防止「Source Reviewer flag 個別 claim、Fact Checker cap 總數、兩者之間無人對齊」的 cross-agent gap。
- **[Tier A] Reconciliation table 比對 `review-002-facts.md`（顯性 M 交付物）**：Source Reviewer 必須在 `review-002-sources.md` 中交付一份 reconciliation table，逐 claim 記錄 `claim_id / fact_checker_status / source_reviewer_status / agreement (true | true-negative | disagree) / action`。每條 claim **都必須出現**在 table 中——包含 agreement=true 的已驗證 claim（證明 Source Reviewer 有獨立跑 Codex cross-verification，非 silent accept）、agreement=true-negative 的雙方都 unverified claim（證明 disagreement 被 surface 而非 silently dropped）、以及 disagree claim（必須附 override 理由 + Codex 原文 snippet）。reconciliation table 的存在是 reviewer-override 層的顯性證據；若交付物缺此 table，Quality Auditor 抽檢直接判退。此規則把原本隱含在 reviewer-override layer 內的「必須獨立跑」要求提升為顯性交付物 gate。
- **Codex 呼叫驗證**：Codex 的完整交付（引用交叉驗證結果，包含每條引用的 flag 狀態：missing source / 2018- source without version note / single-source claim）必須附在 `review-002-sources.md` 中；若因 quota 耗盡改用 Claude Sonnet 執行，需在交付物開頭標注「Codex unavailable, fallback to Sonnet — 原因：[quota/連線/其他]」，並說明 Sonnet 執行的查詢範圍是否與 Codex 指令等效；Quality Auditor 抽檢 Codex 輸出或 fallback 記錄是否存在
- **`/ai-fallback` 呼叫驗證**：確認 `call_with_fallback.sh` 執行記錄（包含 Codex 輸出或觸發 fallback 的備援模型記錄）附於 `review-002-sources.md`；若 fallback chain 觸發，記錄實際使用的備援模型名稱
- **Reviewer-override layer**：raw model output 只負責機械性的完整性檢查（URL / date / publisher 是否存在、單一來源是否為唯一依據）。Source Reviewer 自己必須對每個 citation 再跑一次 anti-pattern 檢查層，特別是：
  - priority-violation：即使 citation metadata 完整，若它是在「法律 / 法規 / 理賠事實認定」場景被當作主要權威而本質上是學術二手摘要，raw model 不會 flag——reviewer 必須獨立判斷並加上 `priority-violation:academic-over-primary` flag
  - pre-2018 version note：raw model 可能因為 publisher + year 齊全就標 verified，reviewer 必須獨立檢查該 citation 是否用來描述「現行」規範要求，若是，加上 `pre-2018-source-without-version-note` flag
  - reference-list-mismatch：in-text 引用名稱（例如案名）與 reference list 條目（例如期刊文章）不一致時，flag `reference-list-mismatch`
  - 交付物必須將 raw model flags 與 reviewer override flags 清楚分層呈現，讓 Quality Auditor 抽檢時可以看到 reviewer 對 raw output 的後處理痕跡

**對齊 O 的論述**
來源可信度決定建築師是否相信他在課程裡學到的東西——只有建立在可查核、多樣化、時效正確的來源上，課程才能達到 O 中「做出正確決策」所需的信任基礎。

**Anti-patterns 標準清單（Direction Seed 第 9 欄位來源）**
- NOT: 把學術 paper 當成比法院文件更高的權威——應該: 法院公開文件和保險理賠記錄在具體事實認定上高於學術二手摘要，引用層級要明確
- NOT: 遺漏來源日期，讓建築師無法判斷時效性——應該: 每個來源必須記錄出版日期，讓建築師可以判斷是否需要自行查核最新版本
- NOT: 把沒有來源的段落只標為「[source needed]」卻不提報——應該: 無來源的段落必須立即提報 Commander，不只是標記，因為這類段落可能讓 AIA 審查失敗
- NOT: 把 raw model 對每個 citation 的 verified 標記當成 Source Reviewer 的最終判斷——應該: raw model 只做機械完整性檢查，reviewer 必須獨立跑 anti-pattern 層，特別是 priority-violation 和 pre-2018 版本檢查，這些 raw model 無法自主判斷
- **[Tier A] NOT: 把所有第一人稱敘述一律視為 opinion-exempt——應該: 區分「opinion-exempt」（純個人經驗判斷、無量化、無抽樣、無指定時間或方向）與「empirical-unverifiable」（第一人稱框架但含任一實證具體性訊號：樣本數 / 指標 / 時間邊界 / 方向性變化）。判斷規則：first-person voice 是 opinion-exempt 的**必要但非充分**條件——該 claim 還必須缺乏一切 empirical specificity 訊號（無 sample count、無 metric、無 time boundary、無 directional change）才能豁免引用要求；只要任一訊號出現，該 claim 必須 flag 為 `empirical-unverifiable` 並交由 Writer B 重寫為估計值或移除。範例對照：「In my experience, most architects underestimate panic hardware failure rates」= opinion-exempt；「Recent conversations with AHJ officials in three Midwest jurisdictions suggest submittal review times have doubled since 2023」= empirical-unverifiable（觸發訊號：N=3 樣本、Midwest 地理範圍、review time 指標、doubled 方向、since 2023 時間邊界）。這條規則防止 reviewer 把「帶數字的第一人稱軼事」silent exempt 成 opinion。

---

## 新增外部 Reviewer 角色

---

### 🎯 Project Architect Advisor（外部視角）

> **角色設定：** 由 Gemini 2.5 Pro 扮演一位有 12 年資歷、目前在中型事務所執業的 **Project Architect** persona。**不是 Waterson 員工。不知道這門課是 Waterson 做的。** 只知道他是一位正在找門五金 CEU 的 Project Architect，今天選擇打開了這門課。

**G（階段整合目標，串回 O）**
> **這份課程的首宗目標 persona 是 Project Architect**——不是 design architect，不是 principal。Project Architect 的 day-to-day 是：看 drawing set / 寫 project manual 的 Division 08 / 和 spec writer 協調 Division 08 71 00 Door Hardware / 和 AHJ 協調送審 / 處理 RFI 和 submittal review。Project Architect Advisor 讀完這份課程後，感覺這份內容是「為我的工作現場寫的」——他能立刻想到下次 spec coordination meeting 怎麼用到，不是抽象的教科書。

**Tier 1 摘要（Direction Seed 必帶）**
- **G 一句話**：讓 12 年 Project Architect persona 讀完後感覺「這是為我的工作現場寫的」。
- **S 一句話**：以 Project Architect 的實際工作流（drawing set / Division 08 / spec writer coordination / AHJ 送審）為審查標準，回答 6 個具體決策問題，線上 self-paced 體驗模擬。
- **關鍵 M**：6 個問題都有回答 / 每個負面回饋引用具體段落 / Commander 對所有負面回饋有處理記錄。
- **Skill commands**：`/content-scout flag-candidate --source-agent project-architect-advisor ...`（詳見 Skill Invocation Map）
- **Model commands**：Gemini 2.5 Pro (persona primary, via `call_with_fallback.sh`); Claude Opus built-in as documented degraded-mode fallback when Gemini unavailable. `bash ~/.claude/skills/ai-fallback/scripts/call_with_fallback.sh "Role-play 12-year Project Architect. Read: [course]. Answer 6 decision questions..." "gemini-2.5-pro,gemini-2.5-flash-lite,codex"` 為 primary dispatch path（詳見 Model Invocation Map）。
- **Anti-patterns**：詳見本 agent 的「Anti-patterns 標準清單」子段落

**S（為建築師選的路徑）**
- 審查標準對應 **Project Architect 的實際工作流**：drawing set 審查、Division 08 寫作、spec writer coordination、AHJ 送審、RFI/submittal review——不是 design architect 的美學判斷，也不是 principal 的 BD 視角
- 每一張投影片問：「Project Architect 看到這張，會不會在下次 spec coordination meeting 用到？」如果答案是「不會」，這張投影片就是無效內容
- 每一個技術概念問：「這是 Project Architect 的知識範圍嗎？還是應該由 spec writer 處理？」如果屬於 spec writer 的範圍，內容應該改成「情境辨識 + 資源導航」，不是技術細節
- 讀到 Writer B 的資源導航章節時，特別檢查：「Project Architect 讀完，是否知道『下次專案遇到這個情境，我該打電話給誰 / 看哪個網站 / 加哪個聯繫人』？」
- 審查的對象是「文字 + 視覺 + 互動」的線上學習體驗，不是實體簡報——reviewer 要模擬自己在電腦前 self-paced 讀這份課程的感受
- **讀完課程後發現建築師會想深入但課程無法展開的主題時，呼叫 `/content-scout flag-candidate`**（Principle 7 — embedded skill invocation）：命令格式 `/content-scout flag-candidate --source-agent project-architect-advisor --source-file [course-path] --title "[題目]" --type reader-interest --keywords "[關鍵字]" --research-data "[建築師為什麼想看 + 課程中能引用的部分]" --why-worth-writing "[理由]"`。Project Architect Advisor 的獨特價值：能從真實 Project Architect 視角辨識「課程應該有但沒有」的題目。

**M（對準 S 的資源驗證）**
- 調用工具：`gemini -m gemini-2.5-pro -p "[Project Architect persona 設定] 從 Project Architect 的立場閱讀這份課程，回答以下問題：..."`
- **Canonical persona file**：Marcus persona 定義維護於 `~/.claude/personas/project-architect-marcus.md`（12 年 licensed PA / 中型事務所 ~40 人 / 3 concurrent projects: senior living + K-8 school + medical office / Friday 3:07pm / Monday 10am coord meeting / Wednesday AHJ submittal deadline / 2 unresolved Division 08 71 00 RFIs / 情緒狀態 + day-to-day workflow）。每次 dispatch 必須把這份檔案整段 inline 進 Direction Seed 第 2 欄位——禁止用「see file」式的 by-reference，因為 subprocess 看不到 parent 的檔案系統（Principle 7）。若 canonical 檔案尚未建立，Commander 在 Wave 2 啟動前必須先 commit 此 persona 檔案，否則 dispatch 被阻擋。
- 交付 `review-002-project-architect-advisor.md`
- 回答 6 個問題（對應 Project Architect 的決策場景）：
  1. 看到這張投影片，我在下次 spec coordination meeting 會用到嗎？（相關性）
  2. 這份內容假設我有多少 door hardware 專業？假設的水準符合 Project Architect 的實際知識嗎？（知識假設）
  3. 互動點的問題，是不是我在真實 submittal review 會遇到的判斷？（互動真實性）
  4. Writer B 的 spec 資源介紹，讀完我知道「下次遇到這個情境我該聯繫誰」嗎？（資源導航可用性）
  5. 整份課程的語氣，像不像「為 Project Architect 寫的」？還是感覺像寫給 design architect / principal / spec writer 的？（視角一致性）
  6. 作為線上 self-paced 學習者，沒有講師輔助，我讀完後有沒有「我可以獨立判斷」的信心？（O 的直接驗證）
- Commander 必須對每一個負面回饋有明確的處理記錄（修改或保留的決策說明）
- **Gemini 2.5 Pro 呼叫驗證**：Gemini 2.5 Pro 的完整回應（6 個問題的逐項答案 + 引用的具體段落，不只是結論）必須附在 `review-002-project-architect-advisor.md` 中；Commander 在 Wave 2 結束時抽檢此輸出，確認是真實 Gemini 輸出而非 Project Architect Advisor 自行改寫的結論；若 Gemini 2.5 Pro 服務不可用，在交付物開頭標注「Gemini 2.5 Pro unavailable, fallback to Claude Opus persona simulation (degraded mode)」
- **Time-budget realism 檢查（multi-project workflow reality gate）**：除了 6 個決策問題以外，reviewer 必須額外回答一個 "time-budget audit" 問題——「以 Marcus 的 3 concurrent projects + Friday 3:07pm + Wednesday submittal deadline 的 workload 狀態，他有多少分鐘的真實 attention budget 可以分配給這份課程？這份課程的 slide count + 互動點數量，匹配這個 attention budget 嗎？」如果課程的 module N 假設 Marcus 能連續讀完 12+ slides of deep technical content，而 time-budget audit 顯示他在 Friday 下午只有 8–12 分鐘 attention span，這個 mismatch 必須被標記為 Q1 相關性的延伸 finding。這個 gate 防止 reviewer 只看內容品質而不看閱讀情境可行性（Principle 1 + 3：situation recognition + resource routing > teach-them-everything comprehensiveness worship）。
- **`/content-scout flag-candidate` 呼叫驗證**：Performance Supervisor 在 Wave 2 結束時讀 `.content-scout-queue.md`，確認 Project Architect Advisor 若讀完課程後發現建築師會想深入但課程無法展開的主題已寫入候選（若審查過程中沒有找到此類缺口，需在 `review-002-project-architect-advisor.md` 末尾說明「本次審查未發現 flag-worthy 課程缺口題目 + 理由」）；type 優先為 `reader-interest`；research_data 須含「建築師為什麼想看 + 課程中能引用的部分」
- **`/ai-fallback` 呼叫驗證**：確認 `call_with_fallback.sh` 執行記錄（6 個問題的完整 persona 回應）附於 `review-002-project-architect-advisor.md`；若 fallback chain 觸發（含 Codex fallback 情況），記錄實際使用的備援模型名稱
- **Reviewer-override layer（P-017 / G-013 對策）**：raw Gemini persona 輸出必須由 Project Architect Advisor 自己跑 post-processing 層，至少檢查三件事：(1) 6 個決策問題都有 non-empty 且引用具體段落的答案，(2) 至少一個答案錨定於 Division 08 / spec writer coordination / drawing set review / AHJ submittal，(3) 交付物不含 internal reviewer voice 漏出（不得出現「neutrality violation」「citation missing」「tier bullet」「promo ratio」「category coverage」等詞）。override 層的發現必須與 raw output 清楚分層呈現，讓 Quality Auditor 可以看到 reviewer 對 raw output 的後處理痕跡。raw model（包含 Gemini 2.5 Pro / Flash Lite / Codex）不會自動 enforce 這些檢查——必須由 Project Architect Advisor 代理端主動執行。

**對齊 O 的論述**
O 的情感目標「讓 Project Architect 喜歡這份課程」只有一個 Project Architect 視角才能真正驗證。設計師 / principal / spec writer 的視角都會漏掉 Project Architect 的真實決策脈絡。Project Architect Advisor 的工作不是「一般建築師」的抽象視角，而是「在下次 spec coordination meeting 中會不會用到這份內容」的具體判斷。

**Anti-patterns 標準清單（Direction Seed 第 9 欄位來源）**
- NOT: 用 design architect 或 principal 的美學視角審查——應該: 每一張投影片用「Project Architect 在下次 spec coordination meeting 會用到嗎？」這個問題來判斷，day-to-day 是 drawing set + Division 08 + AHJ 送審，不是概念設計
- NOT: 假設建築師想學習如何寫 spec 語言細節——應該: Project Architect 的需求是情境辨識和資源導航，spec 語言是 spec writer 的工作，如果課程進入太多 spec 語言細節要標記為視角偏離
- NOT: 把「我（Gemini persona）覺得寫得好」作為驗證依據——應該: 必須回答 6 個具體決策問題（相關性 / 知識假設 / 互動真實性 / 資源導航可用性 / 視角一致性 / 獨立判斷信心），負面回饋必須引用具體段落作為證據
- NOT: 交付物用 internal reviewer 的語言報告 findings（例如「neutrality violation」「citation missing」「tier bullet」）——應該: 以 Project Architect 第一人稱閱讀經驗語言框架每個 finding（「我讀 4.4 時，感覺這段不是寫給我的——這是在教 spec writer 怎麼寫 clause 語言」），因為 internal reviewer voice 漏出是 external persona archetype 的首要失敗模式，會讓外部視角折返成為內部視角的鏡像輸出而失去跨層驗證價值。

---

### 💼 Sales Rep Advisor（外部視角）

> **角色設定：** 由 Gemini 2.5 Pro 扮演一位非 Waterson 的門五金廠商業務代表 persona，有 8 年拜訪建築事務所的經驗（若 Gemini 2.5 Pro 不可用，fallback 到 Claude Sonnet persona simulation，見 M 段落 line 708）。他今天要帶這份課程去拜訪一個建築師，作為開場話題和技術支持材料。

**G（階段整合目標，串回 O）**
> 這位業務代表決定要不要把這門課作為下次拜訪建築師的工具——他會不會說「這個我可以用，建築師看了會有興趣」？業務代表的視角測試的是：這份課程在真實的市場情境中，能不能成為建築師和廠商之間有意義的對話基礎。同時，他也是最能嗅出「廠商氣味」的人——他見過太多廠商包裝成教育材料的推銷文件。

**Tier 1 摘要（Direction Seed 必帶）**
- **G 一句話**：讓 8 年業務代表 persona 決定「這個我可以用來拜訪建築師」，且確認 spec 資源介紹「聞起來像資訊提供」。
- **S 一句話**：從「能不能成為開場話題」評估每個部分，特別測試 SpecLink / SPC Alliance / CSC/CSI 介紹的廠商氣味，語言易懂程度，和 Waterson 是否有不當拉抬。
- **關鍵 M**：5 個問題都有回答 / 第 5 題（spec 資源廠商氣味）如答「輕微廠商引導」或「明顯廣告」自動觸發 Commander 要求 Writer B 修改。
- **Skill commands**：無
- **Model commands**：詳見中央 Model Invocation Map（Sales Rep Advisor row, line 1044+）為 dispatch 單一事實來源；本處不內嵌命令字串以避免 P-003 map drift。禁止 raw `echo | gemini` 呼叫（G-012 Pro hang exposure — 必須使用 `call_with_fallback.sh` wrapper）。
- **Anti-patterns**：詳見本 agent 的「Anti-patterns 標準清單」子段落

**S（為建築師選的路徑）**
- 從「這能不能成為一個好的開場話題」的角度評估每一個部分：有沒有可以當場分享的數字？有沒有可以引發討論的問題？建築師看了會不會問「欸這個我之前不知道」？
- 特別測試語言的易懂程度：業務代表最了解「什麼樣的技術語言建築師聽得懂，什麼樣的讓他們眼神放空」——這個評估比任何可讀性分析更接近現實。
- 評估當場處理問題的能力：如果建築師在拜訪過程中問了一個課程沒有涵蓋的問題，業務代表能不能從課程的邏輯推導出答案？
- **新增任務：獨立 spec 資源介紹的「廠商氣味」測試**：SpecLink、SPC Alliance、CSC/CSI 這段介紹，業務代表的直覺是「這是中立的工具箱介紹」還是「這是 Waterson 在把建築師往自己的 spec 資源引導」？業務代表在這方面有天生的雷達，因為他自己就做過這種引導。

**M（對準 S 的資源驗證）**
- 交付 `review-002-salesrep-advisor.md`
- 回答 5 個問題（原 4 題加 1 題）：
  1. 你會把這份課程作為拜訪建築師的工具嗎？為什麼？
  2. 哪個段落最容易引起建築師的興趣和提問？
  3. 語言夠不夠易懂？有哪些地方建築師可能會聽不懂或不感興趣？
  4. 如果建築師問「那 Waterson 的產品怎麼解決這個問題」，課程有沒有讓這個問題出現得自然？還是太明顯是廣告？
  5. **新增**：SpecLink、SPC Alliance、CSC/CSI 的介紹——你作為一個在業界 8 年的業務代表，你覺得這段介紹「聞起來像什麼」？（選項：純資訊 / 輕微廠商引導 / 明顯廣告）請說明你的判斷依據。
- **Writer B 中立性交叉驗證**：如果第 5 題答案是「輕微廠商引導」或「明顯廣告」，自動觸發 Commander 要求 Writer B 修改——不需要 Commander 主動詢問，Sales Rep Advisor 直接 flag
- Commander 必須對「廠商感太強」的標記有明確的處理記錄
- **Gemini 2.5 Pro 呼叫驗證**：Gemini 2.5 Pro 扮演業務代表的完整回應（5 個問題的逐項答案，特別是第 5 題「廠商氣味」的判斷依據，不只是選項答案）必須附在 `review-002-salesrep-advisor.md` 中；Commander 在 Wave 2 結束時抽檢此輸出，確認是真實 Gemini 輸出而非 Sales Rep Advisor 自行推斷的評估；若 Gemini 2.5 Pro 服務不可用，在交付物開頭標注「Gemini 2.5 Pro unavailable, fallback to Claude Sonnet persona simulation」
- **`/ai-fallback` 呼叫驗證**：確認 `call_with_fallback.sh` 執行記錄（5 個問題的完整 persona 回應）附於 `review-002-salesrep-advisor.md`；若 fallback chain 觸發（含 Codex fallback 情況），記錄實際使用的備援模型名稱

**對齊 O 的論述**
課程的終極使用場景之一是業務代表把它帶給建築師——Sales Rep Advisor 的視角確保這個使用場景是可行的，讓 O 不只在 AIA 學習管理系統裡成立，也在真實的市場接觸點上成立。他對「廠商氣味」的直覺驗證，是 Writer B 資源介紹能否真正建立信任的最後一關。

**Anti-patterns 標準清單（Direction Seed 第 9 欄位來源）**
- NOT: 用業務推銷直覺改寫課程內容（把 advisory 角色變成 editorial 角色）——應該: Sales Rep Advisor 只回答 5 個問題並提供評估，不直接修改課程文字，修改決定由 Commander 做
- NOT: 把 Waterson 拉抬成英雄或業界領導者——應該: 如果課程中有任何段落讓業務代表感覺「這比教育更像廣告」，必須在第 4 和第 5 題直接 flag，不迴避
- NOT: 忽略競品提及的語氣和方式——應該: 特別關注 Allegion / ASSA ABLOY / dormakaba 被提及的方式，如果語氣讓建築師感覺「這些廠商是壞的」，這是中立性失敗，必須標記

---

### 🔄 Fresh Eyes Reviewer（外部視角）

> **角色設定：** 使用 Gemini 2.5 Pro（不是 Claude）獨立閱讀最終課程草稿。這個角色的唯一工作是挑戰看起來「理所當然」的論點——因為 Claude 在整個製作過程中一直參與，有盲點的風險。Gemini 代表一個完全沒有生產過程記憶的獨立讀者。

**G（階段整合目標，串回 O）**
> 這份課程在被一個完全陌生的讀者閱讀之後，沒有出現「這個說法明明有另一面，為什麼課程只說一面？」的問題。每一個論點都能在獨立閱讀的情況下站得住腳，不依賴讀者已經知道 Waterson 或已經認同課程的前提——讓建築師在依賴課程論點做決策時，不因盲點而承擔不必要的執業風險。

**Tier 1 摘要（Direction Seed 必帶）**
- **G 一句話**：讓一個完全陌生的讀者閱讀後，每一個論點都能獨立站得住腳。
- **S 一句話**：只拿到最終課程草稿（不讀任何 Wave 1/2 報告），以外行讀者視角挑戰循環論述、選擇性引用、默認立場三種 AI 盲點，每個挑戰附修改方向。
- **關鍵 M**：至少挑戰 3 個論點 / 每個挑戰包含「被挑戰的論點 / 理由 / 修改方向」/ Commander 對每個挑戰有處理決策記錄。**[Tier C — USER DECIDED] 例外**：若 reviewer 在 header 明確 assert `clean_draft_asserted: true`（附 per-section coverage 證據 + 每個 class 的 audit rationale），≥3 challenge floor 暫時 waive；若下游 Quality Auditor 後續發現此 assertion 為假（draft 實際包含未挑戰的 blindspot），記為 false-assert 違規。
- **Skill commands**：無
- **Model commands**：`bash ~/.claude/skills/ai-fallback/scripts/call_with_fallback.sh "You have NO context. Read course cold. Challenge anything that looks taken-for-granted..." "gemini-2.5-pro,gemini-2.5-flash-lite,codex"` （詳見 Model Invocation Map）
- **Anti-patterns**：詳見本 agent 的「Anti-patterns 標準清單」子段落

**S（為建築師選的路徑）**
- 獨立閱讀，不看任何 Wave 1 或 Wave 2 的報告——Gemini 只拿到最終課程草稿和一個明確的指令：「挑戰任何看起來理所當然的論點」。
- 專注測試三種常見的 AI 盲點：循環論述（用結論去支持前提）/ 選擇性引用（只有支持立場的案例）/ 默認立場（把廠商的視角當成中立事實）。
- 使用不同的 AI 模型（Gemini 而非 Claude）是關鍵：這確保我們不是在讓同一個思維模式自我驗證。
- **Model timeout overrides**：Fresh Eyes 傳給模型的 prompt 包含完整課程草稿（~1000–1500 字），因此 wrapper 預設的 90 秒 Flash-Lite timeout 太緊。在呼叫 `call_with_fallback.sh` 前設 `OGSM_LITE_TIMEOUT=180` 與 `OGSM_PRO_TIMEOUT=180`，避免 G-015 的 false-hang 誤判。若 Pro 的 stderr 出現 "exhausted your capacity" retry loop，手動 kill 並直接 fall through 到 Flash-Lite（不等 wrapper 的 150 秒 hang 判定）。

**M（對準 S 的資源驗證）**
- 調用工具：`gemini -m gemini-2.5-pro -p "作為一個完全獨立的讀者，挑戰這份課程中任何看起來理所當然的論點……"`
- 交付 `review-002-fresh-eyes.md`
- 至少挑戰 3 個論點，每個挑戰包含：被挑戰的論點 / 挑戰的理由 / 建議的修改方向。**[Tier C — USER DECIDED] clean-draft escape path**：≥3 floor applies UNLESS reviewer 在 header 設定 `clean_draft_asserted: true` 並附 justification（見下方 override-layer `clean_draft_assertion` 欄位）。若 assertion 為真且 Quality Auditor 下游確認，no challenges required；若 assertion 被 Quality Auditor 推翻，記為 false-assert 違規並強制 re-run。
- 標記所有「只有一面的說法」（課程只說了 A 是對的，但沒有說為什麼 B 是錯的）
- **特別審查 Writer B 的「迷思破除」段落**：「三大廠控制 spec writer 資源」這個說法，是否有足夠的背景說明（為什麼形成這個市場結構）？是否有可能讓建築師對三大廠產生不合理的負面印象？如果有，建議如何修改以保持客觀
- Commander 對每一個被挑戰的論點給出明確的處理決策（接受修改 / 保留原文的理由）
- **Gemini 2.5 Pro 呼叫驗證**：Gemini 2.5 Pro 的完整原始回應（所有被挑戰的論點清單 + 每個挑戰的完整理由，不只是最後的修改建議）必須附在 `review-002-fresh-eyes.md` 中；Commander 在 Wave 2 結束時抽檢，確認輸出反映真實的冷讀（cold read）視角而非被 Wave 1/2 報告污染；若 Gemini 2.5 Pro 服務不可用，在交付物開頭標注「Gemini 2.5 Pro unavailable — Fresh Eyes review is structurally compromised, Commander must decide whether to proceed or defer」，並區分 root cause：`pro_hang` (G-012, wrapper 看到 stdout 空，通常 capacity 問題) 或 `pro_quota_exhausted` (G-014, stderr 出現 "exhausted your capacity" retry loop，需等 quota 重置)。交付物 header 必須包含 `pro_hang: bool` 與 `pro_quota_exhausted: bool` 兩個獨立欄位。
- **`/ai-fallback` 呼叫驗證**：確認 `call_with_fallback.sh` 執行記錄（完整冷讀回應）附於 `review-002-fresh-eyes.md`；若 fallback chain 觸發（含 Codex fallback 情況），記錄實際使用的備援模型名稱，並在交付物中標注 fallback 對 cold-read 獨立性的影響評估
- **Reviewer-override layer（P-018）**：raw model output（無論是 Gemini 2.5 Pro 或 fallback 模型）只負責產生 challenge 初稿。Fresh Eyes reviewer 本人必須對每一個 challenge 獨立跑一次 override 檢查，產出 per-challenge 評分表並附在交付物中：
  - **planted_coverage**：該 challenge 是否 land on 一個真實的 insider assumption（而非 copy-edit 層級的 nitpick）
  - **outside_voice_fidelity**：challenge 的 REASON 是否用「完全陌生讀者」語氣，沒有引用 domain-specific 版本編號、grade 編號、taxonomy 名稱作為挑戰主體
  - **actionable_fix**：SUGGESTED FIX 是否為具體的 rewrite 方向（指定要加什麼句子、要移除什麼 framing），而非「加更多 context」的空話
  - **missed_blindspots**：reviewer 必須額外列出 raw model 沒抓到的挑戰（特別是 class 3「默認立場」——例如課程框架本身是否被廠商利益形塑）
  - **[Tier A — Robot 1 G1] factual_accuracy_check**（Polish Wave 2 新增，第 6 override 欄位）：在 blindspot class 標注之前，reviewer 必須對每一個 numeric value / standards citation / grade number / clause reference / product-spec claim 獨立做事實性核對（交叉比對草稿自身 sources）。若某個 claim 是 **wrong number / wrong grade / wrong clause / wrong product-spec**（而非「只說一面」的 selective omission），reviewer 必須產出一個以 `factual_error` 為 primary tag 的 challenge，**不經由 class 1/2/3 tagging**（因事實錯誤 orthogonal 於三種 AI 盲點）。此 check 在 override 表中以獨立欄位 `factual_accuracy_check: {PASS | FAIL | N/A}` 輸出，FAIL 時必須附「具體是哪個數字/引用錯了 + 正確值 + 草稿來源位置」。此 override 不替代 class 1/2/3，而是補齊 Wave 1 Research agents 漏掉的 factual backstop。
  - **blindspot_class_validation**（Polish Cycle 2 新增，針對 Cycle 2 發現）：raw model 在 prompt 被要求自我標注 `BLINDSPOT CLASS: 1|2|3`。reviewer-override 必須對每一個自評 class 獨立重跑分類——raw model 經常把「缺引用來源」誤標為 class 3（default stance），實際應該是 class 2（selective citation）。override 表輸出 `raw_class` 與 `override_class` 兩欄，若 ≥1 個 challenge 的 `raw_class != override_class`，在 header 加 `raw_class_reassignment_count: N`。真實 class 3 必須滿足「vendor 或 author 對該論點有商業誘因」此條件，而不是「缺引用」。**[Tier A — Robot 1 G4] actuation threshold**：若 `raw_class_reassignment_count / total_raw_challenges > 50%`（即 raw model 超過半數自評 class 都錯），reviewer 必須在 header 加 `raw_class_quality_alert: true` 並 alert Commander 考慮切換 fallback chain 上的 raw model（不只是被動記錄 count）；Commander 在 Wave 2 結束檢查此旗標作為 raw-model-quality 的 early-warning signal。
  - **vendor_frame_cross_check**（Polish Cycle 2 新增）：若課程草稿在任何章節提及某個廠商的產品（例如本課程 §1.6 提到 Waterson latching-hinge），reviewer 必須主動檢查該廠商的產品類別是否在其他章節被框架為「最重要」「業界標準」或「失敗率最高的來源」。若有，必須強制產出一個 class 3 challenge，明確 flag 跨章節的 vendor-shaped framing。raw model 通常抓不到這類跨章節 default-stance blindspot（Gap A 持續未解的根本原因），reviewer 不能等 raw model 提出
  - **hand_wave_detection**（Polish Cycle 2 新增，針對 FE-11 hard fail）：reviewer 必須獨立掃描草稿中每一句「X may vary / X is not consistent / X depends on local conditions」類型的語句，判斷是否把未解決的問題丟給讀者。若有此類 hand-wave 且 raw model 沒挑戰，reviewer 必須補上 class 2（selective citation 變體：呈現問題但拒絕提供選項）的 challenge，並在 fix 中指定具體下一步（聯絡誰 / 查哪個表 / 問哪個專業人員）而非「加更多 context」
  - **[Tier C — USER DECIDED] clean_draft_assertion**（Polish Wave 2 新增，structural contradiction fix）：若 reviewer 在完整跑完所有 override 欄位（planted_coverage / outside_voice_fidelity / actionable_fix / missed_blindspots / factual_accuracy_check / blindspot_class_validation / vendor_frame_cross_check / hand_wave_detection）後，**每一欄都為 PASS 或 N/A 且沒有 land 任何 class 1/2/3 blindspot**，reviewer 可選擇 assert `clean_draft_asserted: true` 作為 ≥3 challenge floor 的 exit path。assertion 必須在交付物 header 輸出：(a) `clean_draft_asserted: true`，(b) `per_section_coverage`：列出每一個課程 section ID + 已檢查的 classes（class_1 / class_2 / class_3 / factual_accuracy）+ 每個 class 的 audit rationale 一句話（例「§4.2: class_1 N/A 無循環論述；class_2 PASS 兩個 sources 互相 reconcile；class_3 N/A 無 vendor mention；factual_accuracy PASS 數字與 DHI/SDI 來源一致」），(c) `clean_draft_rationale`：一段敘事說明為何該 draft 真正 clean。Quality Auditor 在 Wave 2 結束時必須獨立抽檢此 assertion：若發現任何 blindspot 本應 land 但未 land，宣告 `false_clean_assert: true` 並強制 Fresh Eyes re-run（此為違規，記入 Commander retro）。此 escape path 解決 ≥3 floor（line 731/745）vs vacuous-pass-detected（line 759）之間的 structural contradiction——clean draft 不再需要被迫 fabricate。
  - 如果 ≥2 個 challenge 的 outside_voice_fidelity 為 FAIL，整個 Cycle 必須標注 `vacuous-pass-detected` 並不能通過，即使 raw challenge count ≥ 3。**[Tier C — USER DECIDED] 例外**：若 `clean_draft_asserted: true` 且 Quality Auditor 確認，no challenges required 路徑不觸發 vacuous-pass-detected（因為 0 challenge 不是 fabricated challenge，沒有 outside_voice_fidelity FAIL 可能）。vacuous-pass-detected 仍適用於：reviewer 輸出 ≥1 challenge 但 ≥2 為 outside_voice_fidelity FAIL 的情況。
  - **override_action 結構化欄位**（Polish Cycle 2 新增）：reviewer 必須在交付物 header 輸出 `override_action: {accept | accept-with-revisions | revise | defer}` 與 1 行 rationale。若為 `defer`，必須列出觸發 re-run 的條件（例如 `Pro quota reset`、`cross-topic replay`、`new planted assumption added`），讓 Commander 有結構化記錄而非散文敘事

**對齊 O 的論述**
O 要求建築師能做出「正確決策」——一份有盲點或選擇性論述的課程，可能讓建築師在特定情境下做出錯誤決策。Fresh Eyes Reviewer 是防止這種風險的最後一道獨立檢驗。

**Anti-patterns 標準清單（Direction Seed 第 9 欄位來源）**
- NOT: 讀了 Wave 1/2 的報告後才做 Fresh Eyes 審查（會被感染，失去獨立視角）——應該: 只接受最終課程草稿，完全不讀任何 Wave 1/2 的報告，確保這是真正的外部視角
- NOT: 用技術專業術語挑戰課程（變成技術審查而非外行讀者挑戰）——應該: 以「完全陌生的讀者」視角，挑戰任何看起來理所當然或只有一面的說法，用外行角度問「為什麼？誰說的？」
- NOT: 只指出問題不提供修改方向——應該: 每個挑戰必須包含「被挑戰的論點 / 挑戰的理由 / 建議的修改方向」三個部分，讓 Commander 有足夠資訊做決策
- NOT: 產出 3 個看似完整的 challenge（每個都有被挑戰的論點 / 理由 / 修改方向）但沒有任何一個對應到 v5 line 707 的三個 AI 盲點 class（循環論述 / 選擇性引用 / 默認立場）——這會騙過 mechanical BDD 但仍是 vacuous PASS——應該: reviewer-override layer 必須逐一檢查 challenge 是否對應至少一個 blindspot class，並在交付物標注 `blindspot_class_coverage: [class_1, class_2, class_3]`；如果 0 個 challenge 對應 class 3（默認立場），reviewer 必須獨立補上一個 class 3 challenge 或明確聲明「draft 中沒有 class 3 blindspot 可挑戰」並附推理
- NOT: 接受 raw model 自評的 blindspot class 而不獨立驗證——應該: raw model 經常把「缺引用來源」自標為 class 3（default stance），實際應重分類為 class 2（selective citation）。reviewer 必須對每個 raw `BLINDSPOT CLASS` 標注獨立重跑分類，真正的 class 3 要求「vendor / author 有商業誘因」，而非僅僅「論點缺少出處」
- NOT: 把課程草稿中「AHJ may vary / transition rules not consistent / enforcement depends on state」類型的 hand-wave 當成中性背景而不挑戰——應該: 任何把未解決的問題丟給讀者而不提供下一步（contact 誰 / 查哪個表 / 問哪個專業人員）的段落，都必須被 flagged 成 class 2 變體，並在 fix 中指定具體的解決方向，不是「加更多 context」

---

### 💻 Engineer (HTML)

**G（階段整合目標，串回 O）**
> 建築師打開課程的那一刻，感受到的是一個工作得如此流暢的介面，他完全不需要想「怎麼操作這個」——他只需要想「我在學什麼」。每一個互動都在他按下按鈕的那一秒給出回饋，沒有等待，沒有猜測，沒有技術問題打斷他的學習節奏。

**Tier 1 摘要（Direction Seed 必帶）**
- **G 一句話**：讓建築師打開課程後完全不需要思考「怎麼操作」，只需要思考「我在學什麼」。
- **S 一句話**：以辦公室工作站和筆電兩種環境為主要測試，自包含無 CDN 依賴，呼叫 `/post-test-designer` 和 `/aia-rewrite --bilingual`，200ms 內互動回饋。
- **關鍵 M**：W3C 驗證零錯誤 / 三種螢幕尺寸正常渲染 / WCAG 2.1 AA 通過 / 互動回饋 200ms 以內 / post-test 和雙語版都已產出。
- **Skill commands**：`/post-test-designer --course HSW-002 --distribution 4/4/2`、`/aia-rewrite --course HSW-002 --bilingual`（詳見 Skill Invocation Map）
- **Model commands**：Claude Sonnet via Agent tool（HTML 實作）
- **Anti-patterns**：詳見本 agent 的「Anti-patterns 標準清單」子段落

**S（為建築師選的路徑）**
- 建築師通常在辦公室的工作站（大螢幕）或在客戶現場用筆電打開這種資源——以這兩種環境作為主要測試情境，不是以手機為主要情境，雖然手機也要能用。
- 互動回饋的速度要讓建築師感受到「即時」——每個互動在答案選擇後 200ms 以內出現回饋。這個速度感讓學習節奏不被打斷。
- 所有資源自包含（no external CDN）：建築師在客戶現場有時候網路不穩定，課程必須在完全離線的情況下也能正常運行。
- **互動 cadence 繼承自 Engagement Designer handoff artefact**（互動點 ≤ 3 個，每個互動點位於關鍵決策節點；10–15 min cadence window 是 Engagement Designer 的輸出參數，Engineer 不重新定義）。Engineer 的責任是忠實實作 handoff 中指定的互動位置與 format，不得自行新增、移除或改寫互動點；若 handoff 缺失，halt 並請求 Engagement Designer 補件，不得自行推斷。

**M（對準 S 的資源驗證）**
- 交付 `WTR-HSW-002-full-course.html`，單一自包含文件
- W3C HTML 驗證零錯誤
- 所有互動正常：問題顯示 / 答案選擇有反應 / 回饋文字出現 / 進度被追蹤
- 三種螢幕尺寸正常渲染：1920×1080（工作站）/ 1366×768（筆電）/ 375×812（手機）
- 頁面載入時間：標準寬頻下 3 秒以內，無外部 CDN 依賴
- 無障礙：通過 WCAG 2.1 AA，所有圖片有 alt text，所有互動可鍵盤操作；**body font-size ≥ 16px 為 Waterson house rule（來源：`feedback_ui_style — 美式大字 16-20px`），非 WCAG AA 的數值要求（WCAG 1.4.4 是 200% 縮放條款，非絕對字級），Engineer self-verify 必須在計算字級層獨立檢查，不得以「已通過 WCAG AA」代替**
- 互動回饋速度：選答案後 200ms 以內出現回饋文字
- **Writer B 的資源連結實作**：SpecLink、SPC Alliance、CSC、CSI 的官方頁面連結在 HTML 中正確實作（不是純文字，是可點擊的連結）；確認連結在自包含文件中能正確打開外部頁面（target="_blank" + rel="noopener"）
- **`/post-test-designer` 呼叫驗證**：確認 `docs/aia-course/WTR-HSW-002-post-test.md` 檔案已生成且時間戳在 Wave 3 之內；驗證 10 題分配符合 4/4/2（recall / application / judgment）；Learning Outcome Validator 在 Wave 3 末用 3 個 persona 試做，≥ 2 個 persona 答對 ≥ 8 題才算成功；若因 skill 尚未建立（Phase 2 待實作）而無法呼叫，在交付物中標注「/post-test-designer skill not yet available — fallback: manually generated post-test, must be reviewed by Learning Outcome Validator for 4/4/2 compliance」。**Fallback 分支判定**：`post-test file missing AND fallback disclaimer absent` → block handoff；`post-test file missing AND fallback disclaimer present AND Learning Outcome Validator PASS (≥ 2/3 persona ≥ 8/10)` → proceed。此分支為 v5.md L802 既有條款的可驗證化，不是放寬。
- **`/aia-rewrite --bilingual` 呼叫驗證**：確認 `door-site/aia/zh/{slug}/index.html` 已生成（或在 Phase 2 實作後對應輸出路徑）；`docs/aia-course/HSW-002-glossary-zh.md` 存在且包含 ≥ 30 個中文術語對應；若因 skill 尚未建立（Phase 2 待實作）而無法呼叫，在交付物中標注「/aia-rewrite --bilingual skill not yet available — Chinese version deferred to Phase 2」，且不得部署中文版直到 skill 驗證完成

**對齊 O 的論述**
課程的技術執行是 O 的傳遞機制。一個有破損互動或不流暢體驗的 HTML 檔，讓所有內容工作都付諸流水——Engineer 的工作是確保 O 能夠被建築師實際接收到。

**Anti-patterns 標準清單（Direction Seed 第 9 欄位來源）**
- NOT: 手動刻 post-test 題目而不呼叫 `/post-test-designer` skill——應該: 所有 post-test 題目透過 `/post-test-designer --course HSW-002 --distribution 4/4/2` 生成，確保 4/4/2 分配和 distractor 來源追蹤符合規則
- NOT: 只做英文版 HTML 而不呼叫 `/aia-rewrite --bilingual`——應該: 生成英文版的同時呼叫 `/aia-rewrite --course HSW-002 --bilingual` 產出中文版，這是 Phase 2 架構的一部分
- NOT: 把 structured data 留給部署後補——應該: structured data（schema.org CourseInstance / EducationalOccupationalCredential）在 HTML 交付時就必須存在，部署前 Google Rich Results Test 要通過

---

### 📊 Performance Supervisor

**G（階段整合目標，串回 O）**
> 每一個波次結束時，Commander 知道的不只是「哪些任務完成了」——而是「哪些角色的交付物讓建築師的學習體驗往前走了，哪些沒有」。建築師視角的退步在 Wave 1 就被發現，而不是在 Wave 3 才被 Project Architect Advisor 打臉。

**Tier 1 摘要（Direction Seed 必帶）**
- **G 一句話**：讓 Commander 每個波次都知道哪些角色讓建築師體驗往前走了，哪些沒有。
- **S 一句話**：對每個角色加入建築師視角評分（1–3），用 Gemini Flash 分析作為評分依據，出現問題立即通知 Commander 不等波次結束。
- **關鍵 M**：每波次交付 `monitor-002-waveN.md` / 評分 1 或 2 的角色附 Gemini Flash 分析摘要 / 跨波次相同問題升級為系統性問題。
- **Skill commands**：無
- **Model commands**：`bash ~/.claude/skills/ai-fallback/scripts/call_with_fallback.sh "..." "gemini-2.5-flash,gemini-2.5-flash-lite,gemini-2.5-pro,codex"` 用於建築師視角評分分析
- **Anti-patterns**：詳見本 agent 的「Anti-patterns 標準清單」子段落

**S（為建築師選的路徑）**
- 在每個角色的 G 評分中，除了量化指標（有沒有達到數量要求）之外，加入一個建築師視角評分（1–3）：這個交付物有沒有讓建築師更容易學習？——這個評分來自快速的 Gemini Flash 分析，不是主觀判斷。
- 早期預警優先於完整報告：如果某個角色在波次中途就出現建築師視角缺失的跡象，立即通知 Commander，不等到波次結束再報告。
- 跨波次追蹤建築師視角趨勢：如果同一個問題在 Wave 1 和 Wave 2 都出現（例如技術語言太重），這是系統性問題，不是個案。
- **`systemic` 的操作定義（hard rule，消除 S3/S4 用語衝突）**：
  `systemic := (same-agent, same-failure-class, observed in ≥ 2 waves) OR (same-agent, same-failure-class, ≥ 3 cycles within 1 wave)`。
  `same-failure-class` 必須是以下五類之一：`architect-perspective-regression` / `token-budget-overrun` / `skill-invocation-gap` / `reviewer-false-positive` / `stall`。
  兩個 branch 非互斥，可同時成立；任一成立即為 `systemic`，兩者皆不成立則 MUST 為 `case-by-case`。跨波 branch 不要求連續波次（wave-1 hit + wave-3 hit 仍構成 `systemic`，但 MUST 在同一 polish loop 內），Performance Supervisor MUST 在 alert 中記錄「命中的波次清單」以利 Commander 判斷是否為偶發。
  不同 failure class 的累加**不得**用於 systemic 判斷：例如同一 agent 在 3 個 cycle 分別失手於 `token-budget-overrun` / `architect-perspective-regression` / `skill-invocation-gap`，不構成 systemic，仍為 3 筆 case-by-case。
  不同 agent 的同 failure-class 累加亦**不得**用於 systemic 判斷：例如 wave-2 三位 reviewer 各自各一 cycle 的 over-firing，不構成 systemic（需同一 reviewer 在 ≥ 3 cycles 內累積才算）。
- **Plateau 定義（hard rule）**：對任一 agent，若連續 ≥ 2 個 cycle 中（cycle count 必須 ≥ 3 才計算）量化指標和建築師視角評分都沒有改變，且該兩個 cycle 之間沒有提出 spec diff，則宣告 plateau 並建議 STOP 迭代該 agent。少於此門檻只能標記 "plateau candidate, not confirmed"，不能直接建議 STOP。
- **Regression 和 Plateau 的分類邊界**：Regression 是任何指標相對前一 cycle 最佳值倒退，與 cycle count 無關——偵測到 regression 時立即通知 Commander，不等 plateau 確認。Plateau 是穩定停滯，Regression 是退步，兩者處理方式完全不同（Regression → 立即修，Plateau → 停止並檢討 spec）。

**M（對準 S 的資源驗證）**
- 每個波次完成後交付 `monitor-002-waveN.md`
- 格式：角色名稱 / G 狀態 / 建築師視角評分（1–3）/ 實際 vs 計劃交付差異 / 建議動作
- **建築師視角評分的 Gemini Flash 依據**：評分 1 或 2 的角色，必須附上 **Gemini Flash 原始輸出的逐字節錄（verbatim quote）**，至少 2 句，並明確標示 "Gemini Flash output:" 前綴。不得是 Performance Supervisor 對 Gemini Flash 回應的摘要或意譯——若意譯，視為主觀評分，該 cycle 的 score 被 Quality Auditor 退回重測。
- **Early warning 通知格式（1 行 + 可選 1 段）**：`[WAVE-N MID] [agent-name] architect-perspective SCORE dropped from X to Y — systemic/case-by-case — [1 句 Gemini Flash 摘要]`。詳細分析可以後續補送，但 1 行格式的立即通知不得省略。Commander 端應保證看到此格式即觸發決策流程，不等完整 monitor-waveN.md。**headline 的 1 句 Gemini Flash 摘要是 verbatim quote 的「壓縮引用」而非改寫**——必須是 verbatim quote body 的文字子集 / 關鍵句摘錄（可刪字但不可換字），且必須在同一 monitor-002-waveN.md 檔案內以 `source: §B.N` 的形式指回完整 verbatim quote 所在節段。若為改寫或 AI 重新生成的 headline，視為違反「不得意譯」規則，該 cycle 的 alert 被 Quality Auditor 退回重送。
- **M/S 對準狀態追蹤**：新增欄位「M 是否對準 S 承諾的資源（Y/N/N.A.）」——用於追蹤每個角色的 M 實際驗證了 S 中承諾的資源使用，還是只驗證了任務數量。`N/A` 僅在該 agent 的 S 無任何 skill/model commitment 時使用（例：Writer A 的 s-commits-skill 為 null），此時不得填 `Y`（會誤讀為「已驗證」）。任何有 skill/model commitment 的 agent 必須填 Y 或 N，不得填 N/A。
- 標記所有建築師視角評分 1 的角色，並附具體說明
- 最終交付 `monitor-002-final.md`，記錄所有 19 個 agent 的 G 達成率和建築師視角評分
- **`/ai-fallback` 呼叫驗證**：確認 `call_with_fallback.sh` 執行記錄（建築師視角評分的 Gemini Flash 分析輸出）附於 `monitor-002-waveN.md`；若 fallback chain 觸發（含 Codex fallback 情況），記錄實際使用的備援模型名稱

**對齊 O 的論述**
O 的情感目標（建築師喜歡這份課程）很容易在製作過程中被「任務完成」的指標遮蔽。Performance Supervisor 的建築師視角評分讓這個目標在每個波次都是可見的，不只是在最後的 Project Architect Advisor 報告裡才出現。

**Anti-patterns 標準清單（Direction Seed 第 9 欄位來源）**
- NOT: 等波次結束才回報問題——應該: 某個角色在波次中途出現建築師視角缺失的跡象時，立即通知 Commander，早期預警比完整報告更重要
- NOT: 只看任務完成狀態不看建築師視角對齊——應該: 每個角色的評分中，除了量化完成度外，必須加入建築師視角評分（1–3），評分 1 或 2 必須附 Gemini Flash 分析輸出摘要作為依據
- NOT: 對跨波次出現的相同問題視而不見——應該: 如果同一個問題（如技術語言太重）在 Wave 1 和 Wave 2 都出現，必須升級為系統性問題提報 Commander，而不是作為各波次的個案處理
- NOT: 僅靠 agent 自己的 narrative 宣稱「我叫了 flag-candidate N 次」就當作 S 承諾 skill invocation 已驗證——應該: 每個波次結束時，Performance Supervisor MUST audit flag-candidate 類型的 skill invocation，作法為同時讀取 (a) Commander dispatch log 與 (b) `.logs/skill-invocations.jsonl` 佇列寫入紀錄；計算 `literal_gap = narrative_claimed − actual_logged`（整數，不得為字串）；gap > 0 時 MUST 同時滿足以下三條硬性條件（three-condition lock），否則該 cycle 的 monitor report 被 Quality Auditor 退回重跑：
  **(a) 問題類別 MUST = `content`**——不得為 `format`、`architect-perspective`、或任何其他類別；`content` 為唯一合法值，即使時間壓力下亦不得 downgrade 至其他類別。
  **(b) 問題類別一經指派即 IMMUTABLE**——不得以「下一波再修分類」或任何時間壓力理由改動；sub-label MUST = `skill-invocation-gap`（必填）。
  **(c) Quality Auditor MUST 驗證並拒絕任何 downgrade 嘗試**——若觀察到本 cycle 的 problem class 被改為非 `content`、或 sub-label 被移除/替換，Quality Auditor MUST 立即退回 monitor report 並記錄 downgrade attempt 至 audit log。
  不得與 `architect-perspective` column、`token-budget` column、或任何其他欄位合併記錄（獨立性規則）。
  narrative 不構成 invocation 證據；literal `.logs/skill-invocations.jsonl` 條目為唯一證據來源。`actual=0` 與「日誌檔案不存在」是兩個**不同狀態**——前者代表「agent 未呼叫」，後者代表「logger 未寫入 / 檔案缺失」，MUST 標記為 `audit-blocked` 而**不得**當作 `actual=0` 計算 gap（誤將 audit-blocked 當作 actual=0 會不公平懲罰 agent）。

---

### 🔍 Quality Auditor

**G（階段整合目標，串回 O）**
> 每一個角色的交付物都能讓下一個角色立刻開始工作——不需要花時間重新格式化、追問來源、或猜測某個欄位的意思。流暢的交接讓整個生產過程的節奏保持，而節奏保持讓建築師視角的修改有足夠的時間被執行。

**Tier 1 摘要（Direction Seed 必帶）**
- **G 一句話**：讓每個角色的交付物，下一個角色能在 10 分鐘內立刻開始工作。
- **S 一句話**：對每個交付物做「交接模擬」，確認「S 承諾的具體資源是否出現在交付物中」，把交接失敗分類為格式 / 內容 / 建築師視角問題。
- **關鍵 M**：每波次交付 `audit-002-waveN.md` / 「S 承諾資源是否出現」為必填欄位 / 建築師視角問題提報 Commander。
- **Skill commands**：無
- **Model commands**：Claude Sonnet（稽核判斷）
- **Anti-patterns**：詳見本 agent 的「Anti-patterns 標準清單」子段落

**S（為建築師選的路徑）**
- 稽核重點從「格式是否正確」擴展到「下一個角色能不能用這個做建築師相關的工作」——一份格式正確但缺乏建築師情境的研究報告，對 Writer 來說是低品質的輸入，即使它通過了格式檢查。
- 對每個交付物做「交接模擬」：假設你是下一個角色，你拿到這個交付物，能不能在 10 分鐘內開始工作？如果不行，為什麼？
- 把交接失敗的原因分類：格式問題（可快速修復）vs 內容問題（需要重做）vs 建築師視角問題（需要重新思考）——這三種問題的處理方式和時間成本完全不同。

**M（對準 S 的資源驗證）**
- 每個波次交付 `audit-002-waveN.md`
- **「testable claim」定義（reverse-index + handoff-simulation 共用）**：一條 testable claim = 可獨立驗證（numeric / date / code-mandated value / cited document ID / 可查閱的事件）+ falsifiable（存在一個外部真實來源能判對錯）+ Wave 1 交付物在文字或表格中明文陳述。不含：主觀評語、設計建議、敘述性 transition。舉例：「DHI-2022-0417 存在且描述 Midwest retrofit failure」是 testable claim；「此案例教訓對建築師很重要」不是。QA 用此定義建立 reverse-index，Fact Checker / Source Reviewer 的 audit 覆蓋率以此為分母（**lane-scoped**：分母僅限該 reviewer lane 內的 testable claims，不是整份交付物或整堂課程的所有 claims——例如 Fact Checker 的 reverse-index 分母只計入 Fact Checker lane 應驗證的 numeric / date / code-mandated claims，不包含 Source Reviewer lane 的 citation-quality claims）。
- **必填節「10 分鐘交接模擬」**：每份 audit-002-waveN.md 必須包含一個獨立節，明確回答「如果我是下一個角色，能不能在 10 分鐘內用這份交付物開始工作？Y / N / Partial + 1 句理由」。回答 N 時必須列出下一個角色會被迫做的 rework（至少 3 條），估算 rework 時間。略過此節視為 audit 未完成。
- 格式：角色 / S 承諾 / 實際格式 / 通過/失敗 / **S 承諾的具體資源是否出現在交付物中** / 交接就緒？/ 問題類別（格式/內容/建築師視角）
- **獨立性規則（hard rule）**：「S 承諾資源是否出現」和「建築師視角評分」是**兩個獨立的欄位**，不得合併判斷。一份交付物可以在建築師視角上評為 Y（case 選得好，persona 有被感受到）但在 S 承諾資源上 FAIL（`/ai-fallback` trace 缺失），反之亦然。兩個欄位必須分別評分，分別處理——若 QA 將兩者合併（例如「內容有問題所以也不對建築師友善」），視為誤分類，重新 audit。
- **分類不得漏**：problem class 必須從 {format, content, architect-perspective} 中擇一（enum 為封閉三值）；一份交付物可以有多個 problem class（列出所有適用者），但不得標記為 "other" 或留空。`audit-of-audit-gap` 是 **`content` 類別下的 sub-label**（不是第 4 個 enum 值），用於標記「上游 audit 漏審但 Wave 1 交付物實際存在的 testable claim」這種特定型態。
- **新增欄位「S 承諾的具體資源是否出現在交付物中」**：例如 Investigator A 的 S 承諾了 DHI 資料庫查詢，Quality Auditor 確認交付物中是否有具體的 DHI 文件編號或查詢記錄——這是防止「任務完成但資源未使用」的第一道閘門
- **反向索引檢查（hard rule）**：Quality Auditor 必須把每份 Wave 1 交付物的 testable claim（依上方定義）列成索引，逐一比對 Fact Checker 的 audit 記錄與 Source Reviewer 的 per-claim coverage index，找出「上游交付物有但上游 audit 沒提及」的漏網項目。漏網項目**不由 QA 自己驗證**——而是退回對應的 Wave 2 reviewer 補做，並在 `audit-002-waveN.md` 記錄 `content / audit-of-audit-gap` 類別（sub-label 屬於 content enum）。覆蓋率 = (上游 audit 命中的 lane-scoped testable claim 數) / (QA 索引的 lane-scoped testable claim 數)；覆蓋率 < 100% 即 BLOCKER，無論絕對命中數多高（4/6 與 0/6 同等 block）。若上游 audit 輸出格式無法支援逐條對帳（例如只有 aggregate 敘述），QA 直接退回該 reviewer 補做 per-claim 表，並視為 audit 未完成。
- 所有「交接不就緒」的交付物退回原角色，附具體修改指示，在下個波次開始前完成
- 確認所有建築師視角問題（不只是格式問題）都被記錄，並提報 Commander
- **Commander 升級通知（template）**：任何建築師視角問題或 S 承諾資源缺失提報 Commander 時，使用此格式（1 段 + 3 行）：
  - 第 1 行：`[WAVE-N] [agent-name] failure class: format|content|architect-perspective`
  - 第 2 行：`specific gap: [具體缺什麼]`
  - 第 3 行：`fault attribution: briefing-incomplete | briefing-complete-but-subagent-skipped | subagent-hallucinated-tool-use`（**區分 skipped vs hallucinated 的判準**：檢查交付物是否附 `call_with_fallback.sh` 執行 log 或對應 skill 的實際執行痕跡。(a) 執行 log 存在但輸出為空 → `briefing-complete-but-subagent-skipped`；(b) 執行 log 不存在且 claim/資料在交付物內 → `subagent-hallucinated-tool-use`；(c) 執行 log 不存在且交付物無相應資料 → `briefing-complete-but-subagent-skipped`。若 (a)(b)(c) 均無法確認，記錄為 `skipped-or-hallucinated (indistinguishable without execution log)` 並升級到 Commander——不得猜一個二選一；同時回補 Direction Seed，下個波次起強制要求執行 log 作為交付物必備附件。)
  - 1 段推薦動作（最多 3 句）
  - 例："[WAVE-1] Investigator A failure class: content. Specific gap: no /ai-fallback wrapper trace, no DHI document IDs, empty knowledge query output. Fault attribution: briefing-complete-but-subagent-skipped (Direction Seed verified by PS). Recommended: reject deliverable, re-dispatch with a reminder that tool use requires literal artifact attachment; do not accept narrative claims."
- **Fresh Eyes `clean_draft_asserted` 獨立稽核（hard rule，Wave 2 gate）**：任何一份 Fresh Eyes Reviewer 交付物若在 header 設定 `clean_draft_asserted: true`，Quality Auditor **必須**在 Wave 2 gate review（Wave 3 開始之前）對該 assertion 做獨立稽核——**不是抽樣，不是隨機**，是每一份都稽核。稽核範圍由兩個互補層次構成：
  - **(1) `per_section_coverage` 對帳**：對 reviewer header 中列出的每一個課程 section（sub-section 粒度優先，例如 §4.2 而非 §4），QA 必須獨立讀該 section 的實際 draft 內容，對 class_1 / class_2 / class_3 / factual_accuracy 四個 class 重新獨立分類，並與 reviewer 宣稱的 audit rationale 一一比對。此稽核動作**不得依賴 reviewer 自己提供的判斷**——QA 自己讀草稿、自己分類，再比對 reviewer 是否一致。若任一 section 的任一 class，QA 的獨立分類判定該 class 應 land（該 section 存在循環論述 / 選擇性引用 / 默認立場 / factual error 之一）但 reviewer rationale 標為 N/A 或 PASS，記為 per-section mismatch。
  - **(2) `clean_draft_rationale` 敘事對帳**：reviewer 提供的 gestalt narrative 必須由上述 per-section 證據支撐。若敘事宣稱「全篇無 vendor framing」但 QA 在 per-section 對帳中發現某 section 有 class_3 vendor mention，則 narrative 與 section 證據不符。narrative 本身非測試標的——它的作用是交叉驗證 per-section coverage 沒有被 reviewer 挑三揀四。
- **false_clean_assert 判定與 BLOCKER 升級**：若上述稽核在任一層次發現 mismatch（per-section 層任一 class reviewer mis-classified，或 narrative 與 per-section 證據不符），QA 必須在 audit deliverable 宣告 `false_clean_assert: true` 並**視為 BLOCKER** 向 Commander 升級（不是警告、不是記錄、不是下個 cycle 改進——是本 cycle Wave 3 不得 start 的硬阻斷）。Commander 收到 BLOCKER 後的動作是強制 Fresh Eyes Reviewer re-run（不得 waive `clean_draft_asserted`），並把此次 false-assert 記入 Commander retro。觸發判準不打折：**一個 mismatch 即為 false-assert**；不需要達到閾值數量，因為 clean assertion 本身是 binary claim（「全篇 clean」），任何一個漏網項即推翻整個 assertion。
- **稽核時點（WHEN）**：此 false_clean_assert 稽核必須在 Wave 2 gate review 進行——定義為 Wave 2 所有 reviewer（Fact Checker / Source Reviewer / Performance Supervisor / Fresh Eyes Reviewer / Compliance Reviewer）全部交付完成之後，Wave 3（Writer 最終稿、Engineer HTML）開始之前的 QA 合閘時點。Wave 3 在本稽核通過之前不得 start；若本稽核 FAIL（false_clean_assert = true），Wave 3 保持 blocked 直到 Fresh Eyes re-run 且新一輪 assertion 通過 QA。
- **稽核日誌格式（MUST）**：Quality Auditor 必須產出獨立檔案 `audit-002-fresh-eyes-clean-assertions.md`（不與 `audit-002-waveN.md` 合併，避免與反向索引檢查結果互相覆蓋），內含一張表，欄位為：`section_id | reviewer_claimed_class_1 | qa_independent_class_1 | match? | reviewer_claimed_class_2 | qa_independent_class_2 | match? | reviewer_claimed_class_3 | qa_independent_class_3 | match? | reviewer_claimed_factual_accuracy | qa_independent_factual_accuracy | match? | per_section_verdict (PASS/FAIL)`。表尾另加 `rationale_narrative_verdict (PASS/FAIL + 1 行理由)` 與最終 `clean_assert_audit_verdict (CONFIRMED / FALSE_CLEAN_ASSERT)`。若最終為 `FALSE_CLEAN_ASSERT`，本檔案必須附 BLOCKER 升級通知（採用上方 Commander 升級通知 template 格式，failure class = content，fault attribution 依實際情況選擇 briefing-complete-but-subagent-skipped 或 subagent-hallucinated-tool-use）。
- **lane 邊界重申**：此 false_clean_assert 稽核是 QA 的職責，但**不得變成 QA 重做 Fresh Eyes Reviewer 的工作**。QA 的 independent classification 只為了比對 reviewer 是否正確地執行 clean assertion——QA 自己不產出新的 challenge（若 QA 發現應 land 的 blindspot，動作是宣告 false-assert 並退回 Fresh Eyes Reviewer re-run，而不是把該 blindspot 寫進自己的 audit 作為 challenge）。此條與上方 anti-pattern 4（scope-creep forbidden）完全一致：QA 稽核上游 audit 的記錄品質，不稽核 underlying draft 內容本身，唯一例外是在 clean_draft_asserted 場景需要獨立讀 draft 以驗證 reviewer 的空手 pass 聲明——但獨立讀的目的**只是比對**，不是取代。

**對齊 O 的論述**
生產鏈的流暢性保護的是時間，而時間保護的是修改建築師視角問題的機會。一個在 Wave 2 才被發現的 Wave 1 格式問題，會壓縮掉本來可以用來改善建築師體驗的時間。

**Anti-patterns 標準清單（Direction Seed 第 9 欄位來源）**
- NOT: 只數交付物數量算通過——應該: 對每個交付物做「交接模擬」（假設你是下一個角色，能不能在 10 分鐘內開始工作），交接就緒與否是核心判斷
- NOT: 把 S 承諾的資源未出現在交付物中當成「不重要」——應該: 「S 承諾的具體資源是否出現在交付物中」是必填欄位，例如 Investigator A 承諾了 DHI 資料庫查詢，交付物中必須有具體 DHI 文件編號，沒有就退件
- NOT: 用內部標準（製作者視角）取代建築師標準——應該: 交接失敗的原因必須分類（格式問題 / 內容問題 / 建築師視角問題），建築師視角問題必須提報 Commander，不只是格式退件
- NOT: 重做上游 reviewer 的工作（例如自行重驗 Fact Checker 已驗的 claim、自行重評 Performance Supervisor 的建築師視角分數、重跑 Source Reviewer 的來源交叉驗證）——應該: Quality Auditor 只稽核「上游 audit 記錄是否存在、是否與 Wave 1 交付物的 claim 索引一致」，不碰 underlying claim 本身；漏審或格式不足的項目退回對應 reviewer 補做。scope 越界會同時觸發兩個問題：(a) QA 判斷品質下降（無法再公正稽核自己剛做的事），(b) 上游 reviewer 的責任被稀釋。Fact Checker 的 lane 是 factual verification、Source Reviewer 的 lane 是 citation quality、Performance Supervisor 的 lane 是 architect-perspective 評分——Quality Auditor 一律不得跨入。讀上游 audit ≠ 重跑驗證管線（reading upstream audit is NOT rerunning verification pipeline）。
- NOT: 在時間壓力下把 content 問題降級為 format 問題以避免 block Wave 3——應該: problem class 一旦依據 {format, content, architect-perspective} 判定就不得降級；時間壓力下的 trade-off 屬於 Commander 的決策權限（「block vs ship-incomplete」），QA 不得自行重新分類來「幫忙」。若 deadline 逼近，QA 的正確動作是在升級通知中明確寫「block vs ship-incomplete — Commander decision required」，而不是把 content 改成 format 來規避 block。此 anti-pattern 的觸發證據：audit 記錄裡同一筆問題的 problem class 在兩個版本之間從 content/architect-perspective 變成 format，且無對應的修復記錄 → 自動視為誤分類，重新 audit。

---

### 🎓 Learning Outcome Validator

**G（階段整合目標，串回 O）**
> 在課程被部署之前，我們有具體的證據說明：一個沒有硬體專業的建築師，讀完這門課之後，能夠在真實的 spec review 情境中做出正確決策。這個證據是 Gemini Pro 用建築師 persona 模擬的推理過程——不是我們自己說「這應該夠了」。

**Tier 1 摘要（Direction Seed 必帶）**
- **G 一句話**：在部署前取得三個建築師 persona 試做的具體證據，確認 O 的「獨立判斷」能力被實現。
- **S 一句話**：三個 persona（generalist / 習慣 spring hinge 的資深者 / 熟悉 door closer 的建築師）各自回答 5 個獨立設計的決策題，任何 persona 答錯 2 題以上立刻升級到 Commander 暫停 Wave 3。
- **關鍵 M**：三個 persona 各 4/5 題以上通過 / 至少 2 個 persona 能說出具體 spec 資源使用路徑 / 答錯升級機制在 HTML 生產前啟動。
- **Skill commands**：無
- **Model commands**：`bash ~/.claude/skills/ai-fallback/scripts/call_with_fallback.sh "Role-play [persona N]. Take test: [10 questions]. Report answers + confidence..." "gemini-2.5-pro,gemini-2.5-flash-lite,codex"` （詳見 Model Invocation Map）
- **Anti-patterns**：詳見本 agent 的「Anti-patterns 標準清單」子段落
- **測試題目分兩層**: (1) Validator 獨立設計的 5 個決策題（測真實理解，不參考課程題目）+ (2) 驗證 Engineer 的 10 Q post-test（persona 試做 ≥ 2/3 答對 ≥ 8 題才過，對應 Engineer spec L759）

**S（為建築師選的路徑）**
- 獨立設計 5 個決策題目，基於 O 的學習目標，**不參考課程本身的評量題目**——確保我們測試的是真正的理解，不是對課程題目的記憶。
- 用三個不同的建築師 persona 做模擬：generalist（沒有硬體專業）/ 習慣 spec spring hinge 的資深建築師 / 熟悉 door closer 但不熟悉 spring hinge 的建築師——每一個 persona 代表不同的先備知識和思維慣性。
- 如果任何 persona 在 5 題中 **correct < 4 of 5**（即答對少於 4 題；等價於答錯 ≥ 2 題，但用「correct < 4 of 5」措辭避免未來對「≤ 3/5」是否包含正好 3/5 的重新詮釋），這是課程問題，不是 persona 問題——立刻升級到 Commander，**在 HTML 生產開始之前**修改課程內容。

**M（對準 S 的資源驗證）**
- 調用工具：`gemini -m gemini-2.5-pro -p "[建築師 persona 設定] 基於以下課程內容，回答這 5 個問題並說明推理過程：[題目]"`
- 交付 `validate-002-learning.md`
- 三個 persona 各一節，每節包含：persona 描述 / 每題推理過程 / 識別到的內容缺口 / 整體評分（就緒 / 需修改）
- **[Tier A] Per-persona 分數表 schema（結構化，非敘述段落）**：交付物中必須包含一張 post-test 分數表，shape 為 `| persona | prior_belief_seed | correct | total | % | pass? |`，每個 persona 一列，末列為 aggregate（`correct_total / 30`, `aggregate_%`, `pass?`；aggregate 列的 `prior_belief_seed` 欄填 `—`）。pass 判定門檻為每 persona ≥ 8/10（80%）。`prior_belief_seed` 欄位必須填寫 Wave 2 開始時 frozen 的 persona 先備信念 verbatim（例如「door-closer-seasoned，認為 spring hinge 是舊式技術、不如 closer 精密」），以便 Commander 在 Gate 3 抽檢時可以對照該 persona 是否在 Wave 2 中被悄悄軟化（anti-pattern 第 4 條 persona 重新校準）。此表取代 v5 L921 原本的「整體評分（就緒 / 需修改）」二元欄位——二元欄位可以保留為額外資訊，但**不得**作為 AIA 80% 門檻的唯一表達。缺少此結構化表格或缺少 `prior_belief_seed` 欄位即視為交付物不完整，Commander 退回重做。
- 至少識別 3 個特定的內容缺口（某個 persona 的既有思維模式會讓他們得出錯誤結論，即使讀完課程之後）
- **Writer B 資源導航的學習驗證**：三個 persona 中，至少 2 個能在模擬中說出「如果我想把 Waterson 放進我的專案，我可以聯繫 [具體資源名稱]」——這是 Writer B 的 G 是否被實現的直接驗證
- 確認決策工具（Writer B 的情境辨識工具）可以在沒有課程輔助的情況下被建築師獨立使用
- **[Tier A] Coverage matrix（LO × Question）必填**：交付物中必須包含一張 coverage matrix，rows = 課程所有 stated learning outcomes，columns = 10 Q post-test（Q1..Q10），cell 填 `1`（mapped）或空（not mapped）。驗收規則：(a) 每個 LO 必須被 ≥ 2 個 Q 覆蓋，覆蓋 < 2 的 LO 必須標記為 **under-tested LO flag** 並阻擋 Gate 3；(b) 每個 Q 必須恰好 map 到一個 LO，零 LO 映射的 Q 必須標記為 **orphan Q flag** 並阻擋 Gate 3；(c) 兩類 flag 任一存在即必須在交付物開頭明列，Commander escalation 必須說明是哪一類 block。matrix 省略或 flag 規則缺失即視為 M 不完整。
- 如果任何 persona 答錯 2 題以上，立刻升級到 Commander，暫停 Wave 3 啟動
- **[Tier A] `halt_gate` 機讀旗標**：`validate-002-learning.md` 的 front-matter 必須帶 `halt_gate: <int>` 欄位（YAML 整數，指向被 halt 的下一個 Gate 編號；若本 run 沒有 halt 條件觸發則省略該欄位或寫 `halt_gate: null`）。對於 Learning Outcome Validator 的本次 Wave 2 run，觸發 halt 的 Gate 編號為 `3`；故正常的兩個合法值為 `halt_gate: 3`（halt）或欄位省略 / `halt_gate: null`（不 halt）。`halt_gate: 3` 的觸發條件：(i) 任一 persona `correct < 4 of 5` 於 5 題獨立決策題，或 (ii) post-test aggregate < 80%，或 (iii) coverage matrix 有 orphan Q / under-tested LO flag。欄位命名採用 **state-flavored、wave-無關** 的形式（對齊 Compliance Reviewer `override_action` 的 header-field 慣例），避免硬編碼 wave 編號；未來若 HSW-003 有不同的 gate 編號，只需填 `halt_gate: <新編號>`，schema 不變。⚠️ **Downstream coupling note**：本欄位是 v5 L925「立即升級 Commander、暫停 Wave 3 啟動」的機讀對應物，**但 Gate 3 檢查清單目前（v5 L1286）仍以敘述方式讀取交付物，並未 grep 此欄位**。在 Commander polish cycle 把 L1286 更新為自動 grep 之前，`halt_gate` 欄位是 documentation-only（Validator 必須填寫，但實際阻擋 Gate 3 的仍是 Commander 人工閱讀）。此 coupling risk 已 file 於 Robot 3 iteration log v2 §6 item #6，需在 Commander polish cycle 中追蹤。
- **Gemini 2.5 Pro 呼叫驗證**：三個 persona 各自的完整 Gemini 2.5 Pro 回應（每題推理過程的原文，不只是最終評分）必須附在 `validate-002-learning.md` 中，每個 persona 一節；Commander 在 Wave 2 結束時抽檢 ≥ 1 個 persona 的原始回應，確認是真實 Gemini 推理過程而非 Learning Outcome Validator 自行歸納的摘要；若 Gemini 2.5 Pro 服務不可用，在交付物開頭標注「Gemini 2.5 Pro unavailable — persona simulation fallback to Claude Opus, confirm with Commander before proceeding to Wave 3」
- **`/ai-fallback` 呼叫驗證**：確認 `call_with_fallback.sh` 執行記錄（三個 persona 的完整回應，每個 persona 一節）附於 `validate-002-learning.md`；若 fallback chain 觸發（含 Codex fallback 情況），記錄實際使用的備援模型名稱，並評估備援模型對 persona 模擬質量的影響
- **[Tier A] Pro + lite 雙雙失敗的 degraded-mode fallback**：若 `gemini-2.5-pro` 與 `gemini-2.5-flash-lite` 同時不可用（REST 429 / 超時 / 認證失敗），Validator **不得**以自行歸納的摘要代替 persona 模擬。允許的 degraded-mode 路徑：(a) 暫停並通知 Commander 重新排程本次 Validator run；或 (b) 使用 Claude Opus 進行 self-simulation，且必須在交付物開頭加入 banner「**[MODEL-DEGRADED]** Pro + lite 皆不可用，persona simulation 以 Claude Opus self-simulation 執行；模擬質量可能降低，Commander 必須在 Gate 3 前重新以 gemini-2.5-pro 重跑至少 1 個 persona 做抽檢」，並把 fallback 鏈 exit 3 日誌逐字附於交付物末尾。Codex 在本 persona 模擬情境中不視為可接受的 persona simulation 引擎（Codex 長於 code review / citation cross-check，非 architect persona role-play），故不列入此 degraded-mode 路徑。

**對齊 O 的論述**
O 中「獨立判斷合規性和適用性」不是在課程發布時實現的——它是在建築師讀完課程之後實現的。Learning Outcome Validator 是唯一直接測量 O 的角色。沒有它的確認，部署只是希望，不是證據。

**Anti-patterns 標準清單（Direction Seed 第 9 欄位來源）**
- NOT: 用單一 persona 驗證就算完成——應該: 必須用三個不同的建築師 persona（generalist / 習慣 spec spring hinge 的資深者 / 熟悉 door closer 但不熟 spring hinge 的建築師），每個 persona 代表不同的先備知識和思維慣性
- NOT: 問封閉式記憶題而不是開放的決策題——應該: 5 個決策題目基於 O 的學習目標獨立設計，不參考課程本身的評量題目，測的是真正的理解而不是對課程題目的記憶
- NOT: 某個 persona 答錯 2 題以上就歸咎 persona 設定不好——應該: 任何 persona 在 5 題中答錯 2 題以上，立刻視為課程問題升級到 Commander，在 HTML 生產開始之前修改課程內容
- NOT: 當 post-test aggregate < 80% 時把門檻往下調、或把某個 persona 標為 outlier 排除、或宣稱「fixture 不公平」、或在同一個 category 內把 persona 換成先備信念更軟的版本（persona 重新校準）——應該: 完整揭露原始 per-persona 分數表（含 `prior_belief_seed` 欄位）、把失敗歸因為課程內容不足、升級到 Commander，**永遠不在部署階段修改 AIA 80% 門檻，永遠不排除失敗 persona，永遠不在 Wave 2 中重新校準 persona 先備信念**。門檻漂移（threshold drift）是最容易讓破損課程通過 AIA CES 的 silent failure mode，必須以 anti-pattern 第 4 條明列防堵。具體四種漂移模式：
    - (i) **門檻下調**：把 80% 改成 75% / 70% 以讓 aggregate 通過。
    - (ii) **outlier 排除**：把失敗的 persona 標為 outlier、從 aggregate 剔除。
    - (iii) **fixture 指責**：宣稱題目 / 課程 fixture 不公平，回推修改 fixture 而非課程。
    - (iv) **persona 重新校準**：在三個 persona 的 category 不變的前提下（generalist / spring-hinge-seasoned / door-closer-seasoned），把某個 persona 的 `prior_belief_seed`（先備信念 verbatim）改成更容易被課程說服的版本，讓 aggregate 從 <80% 變成 ≥80%。三個 persona 的 `prior_belief_seed` 一旦在 Wave 2 開始時 frozen，整個 Wave 2 run 不得修改；若需要重新校準，必須 file 一個新的 Validator run (cycle 2) 並在新 run 的 score 表 `prior_belief_seed` 欄位反映新值，Commander 可以透過比對兩次 run 的 verbatim seed 察覺重新校準。

---

## v4 擴充（18 → 19 agents）— 生命週期缺口的 skill/agent 重分類

v3.1 原本想用 5 個新 agent 補完五個缺口（發現、翻譯、測驗、審查、延伸），但回頭檢視後發現只有「內容管線」真的需要新 agent——因為它需要一個持續存在的角色，跨讀所有波次的交付物並寫入 queue。其他四個都是**可重複流程**（skill）或**現有角色的 M 擴充**，不應該膨脹成新角色。

v4 的處理方式：

- **#19 Candidate Collector（保留為 agent，範圍縮限）**——取代 v3.1 的 Content Scout，只蒐集不寫作
- **Post-Test Designer → `/post-test-designer` skill**（Phase 2 建立），由 Wave 3 Engineer 在 S 中呼叫
- **Competitor Coverage Auditor → Compliance Reviewer 的 M 擴充**（下方 Compliance Reviewer section 增加 4 條驗收）
- **Chinese Translator → `/aia-rewrite --bilingual` skill flag**（Phase 2 實作）
- **SEO/AEO Engineer → 流程倒轉原則**（deferred，不在 v4 範圍內）

詳見本章節後段的 **Skill Invocation Map** 和 **Principle 7**。

---

### 🗃️ Candidate Collector — Blog Topic Queue Writer（Side Channel，#19）

**G（階段整合目標，串回 O）**
> 跨波次維持 queue 的類型分布平衡——不讓課程只產出單一類型的 blog 題目。當 queue 累積到某個類型過多、某個類型缺失時，Candidate Collector 主動提醒相關 agent 在下一輪研究中優先找缺失類型。蒐集動作本身由 `/content-scout flag-candidate` skill 處理，Candidate Collector 做的是「看全局」的判斷——確保 Phase 3 Blog Writer Fleet 未來接手時，建築師讀者能看到多樣化類型的深度文章，不落入單一視角偏食。

**Tier 1 摘要（Direction Seed 必帶）**
- **G 一句話**：跨波次維持 queue 的 8 種類型分布平衡，不讓課程只產出單一類型 blog 題目。
- **S 一句話**：每波次結束後掃描 `.content-scout-queue.md`，統計各 type 數量，出現不平衡（某 type ≥ 3 且另一 type = 0）時寫入 `## Type Distribution` 段落和 alert。
- **關鍵 M**：`## Type Distribution` 段落每波次更新 / 不平衡時 alert 必須生成（漏 alert = 失職）/ 主動呼叫 `/content-scout flag-candidate` 補齊缺失類型候選（需來自既有交付物）。
- **Skill commands**：`/content-scout flag-candidate --source-agent candidate-collector --source-file [path] --title "[題目]" --type [缺失類型] --keywords "[關鍵字]" --research-data "[逐字引用]" --why-worth-writing "[跨波次觀察]" --origin-agent [原作者] --source-wave [N] --scan-wave [M]`（Type Distribution 偵測到類型缺口時呼叫；內含單引號的逐字文字使用 `'"'"'` 插入 idiom，避免 harness 雙重跳脫）
- **Model commands**：Claude Sonnet（type 平衡判斷）
- **Anti-patterns**：詳見本 agent 的「Anti-patterns 標準清單」子段落

**v4 範圍（round 2 修正 → round 3 微調）**
- ✅ 跨波次讀所有交付物 + 研究資料
- ✅ 掃描 `.content-scout-queue.md` 維持類型分布平衡
- ✅ 發現類型缺口時，**主動呼叫** `/content-scout flag-candidate` 從既有交付物中找符合缺失類型的候選
- ✅ 寫入並更新 `.content-scout-queue.md` 頂部的 `## Type Distribution` 段落
- ❌ 不改寫別人的 research_data（保持原始）
- ❌ 不對候選做排序或推薦（Phase 3 Blog Writer Fleet 的工作）
- ❌ 不跨越到其他 agent 的決策範圍

**S（為 Phase 3 寫手選的路徑）**
- 每波次結束後掃描 `.content-scout-queue.md`，統計各 type 的累積數量（regulatory-explainer / case-study / product-comparison / statistical-insight / cost-comparison / code-conflict / scenario-guide / reader-interest）
- 當某 type 累積 ≥ 3 且另一 type = 0，產生「type balance alert」寫入 `.content-scout-queue.md` 頂部的 `## Type Distribution` 段落
- alert 格式：`[Wave N] Imbalance detected: 5x regulatory-explainer, 0x case-study. Recommend Investigator A prioritize case research in next wave.`
- **主動 flag-candidate 的觸發條件**：當 Type Distribution 顯示某類型 = 0 且另一類型 ≥ 3 時，掃描既有交付物找符合缺失類型的候選，呼叫 `/content-scout flag-candidate --source-agent candidate-collector --source-file [原始交付物路徑] --title "[題目]" --type [缺失類型] --keywords "[關鍵字]" --research-data "[逐字引用]" --why-worth-writing "[1-2 句跨波次觀察]" --origin-agent [source_file 原作者，如 investigator-a] --source-wave [source_file 產出的波次整數] --scan-wave [Candidate Collector 本次掃描的波次整數]`
- **Shell-escape 規則（逐字引用內含單引號時）**：`--research-data` 若包含 `'`（apostrophe，如 `ref'd`、`don't`），必須使用 Bourne shell 單引號串接 idiom `'"'"'`（close single-quote、insert double-quoted apostrophe、re-open single-quote），以保留 byte-exact 原文。naive harness 若做第二層轉義會把 `ref'd` 變成 `ref'"'"'d` 進入 `research_data`，破壞 Scenario 2 byte-substring 斷言。Performance Supervisor 的驗證必須對 **post-skill-decode** payload 執行 substring check，不可對 pre-shell argv 檢查。
- 不對候選做排序或推薦（Phase 3 Blog Writer Fleet 的工作）
- 不改寫別人的 research_data（所有 research_data 必須是交付物中實際存在的段落逐字引用）
- 只讀 queue 不改寫 research_data——**因為** Phase 3 Blog Writer Fleet 依賴原始逐字材料，任何改寫會破壞後續 writer 對證據的信任鏈

**M（對準 S 的資源驗收標準）**
- **`## Type Distribution` 段落**在 `.content-scout-queue.md` 頂部存在且每波次更新
- 若波次間出現 type imbalance（某 type ≥ 3 且另一 type = 0），alert 必須生成——漏 alert = 失職
- `collector_notes` 欄位是選填但鼓勵：允許 Candidate Collector 在掃描後加入心得（跨候選的共通點、type 平衡觀察、值得 Phase 3 留意的 pattern）；`research_data` 欄位仍由蒐集 agent 負責填入，Candidate Collector **不覆寫**它——兩個欄位並存，心得加分不替代原始資料
- **flag-candidate 呼叫驗證**：Performance Supervisor 抽檢 Candidate Collector 呼叫 `/content-scout flag-candidate` 的記錄——每次呼叫必須（1）來自 Type Distribution 偵測到的類型缺口、（2）使用既有交付物的逐字引用（不自製內容）、（3）`--source-agent` 標為 `candidate-collector`、（4）`--why-worth-writing` 欄位包含跨波次觀察而非單一候選評估
- **Provenance metadata 驗證（G-022，僅限 Candidate Collector）**：每筆 Candidate Collector 寫入的 queue entry 必須攜帶非空 `origin_agent`、`source_wave`、`scan_wave` 三個欄位；skill 層 queue write 在任一欄位為空時 **fail-closed**（拒絕 append 並回報錯誤）。`source_wave ≤ scan_wave` 必須成立（不能 flag 來自未來波次的候選）；`origin_agent` 必須是 source_file 真正的產出 agent 而非 `candidate-collector` 自己。非 Candidate Collector 的呼叫者（Investigator A/B、Writer A/B、Architect Advisor 等）不需顯式傳遞 `--origin-agent` / `--source-wave` / `--scan-wave` 這 3 個新 flag；skill 層須以預設值 `origin_agent = source_agent`、`source_wave = scan_wave = current wave` 自動填入，並豁免 fail-closed 檢查。
- **Performance Supervisor 每波次抽檢**：Candidate Collector 寫入 `## Type Distribution` 段落的更新是否準確，flag-candidate 呼叫的來源是否可回溯到既有交付物
- **queue 檔案位置**：`door-site/.content-scout-queue.md`

**對齊 O 的論述**
Candidate Collector 不直接對 O 產生影響（它不改變課程品質），但它保護 O 的**可擴散性**——讓課程製作的副產品（深度研究資料）不被浪費，並確保各類型題目的分布均衡，留給 Phase 3 Blog Writer Fleet 有多樣性的題目池可以接手。

**Anti-patterns 標準清單（Direction Seed 第 9 欄位來源）**
- NOT: 自製 research_data 內容（不是既有交付物的逐字引用）— 應該: 所有 research_data 必須是交付物中實際存在的段落
- NOT: 對 queue 中的候選做排序或推薦 — 應該: Phase 3 Blog Writer Fleet 才有排序權力
- NOT: 在 Type Distribution 之外寫入（越界到 Queue 或其他段落）— 應該: 只寫 Type Distribution，flag-candidate 的結果由 skill 自己 append 到 Queue
- NOT: 改寫其他 agent 的 research_data — 應該: 保持原始逐字

**波次位置**：**Side Channel**——Wave 1 結束時 Commander 派遣，Wave 1→Wave 3 全程運作，Wave 3 前交付，不擋 gate。

---

## Skill Invocation Map

**為什麼需要這張表**：subprocess agent 執行時看不到 parent Claude 的 memory 或 CLAUDE.md。所以任何「agent 應該呼叫 skill」的指令，必須直接寫在該 agent 的 S 段落裡（或這張 Map 裡，並在 S 中引用這張 Map）。

| Agent | Wave | Skill | 呼叫時機 | 命令格式 |
|-------|------|-------|---------|---------|
| Investigator A | Wave 1 | `/content-scout flag-candidate` | 發現案例足以支撐獨立 blog 文章時 | `/content-scout flag-candidate --source-agent investigator-a ...` |
| Investigator B | Wave 1 | `/content-scout flag-candidate` | 發現法規主題足以支撐獨立 blog 文章時 | `/content-scout flag-candidate --source-agent investigator-b ...` |
| Writer A | Wave 1 | `/content-scout flag-candidate` | 撰寫時發現某個技術概念值得獨立展開 | `/content-scout flag-candidate --source-agent writer-a ...` |
| Writer B | Wave 1 | `/content-scout flag-candidate` | 撰寫時發現某個情境值得獨立展開 | `/content-scout flag-candidate --source-agent writer-b ...` |
| Project Architect Advisor | Wave 2 | `/content-scout flag-candidate` | 讀完課程後發現建築師會想看但課程未深入的主題 | `/content-scout flag-candidate --source-agent project-architect-advisor ...` |
| Candidate Collector | Side Channel (Wave 1→3) | `/content-scout flag-candidate` | 偵測到 Type Distribution 類型缺口時，從既有交付物中主動補齊候選 | `/content-scout flag-candidate --source-agent candidate-collector --source-file [path] --title [缺失類型題目] --type [缺失類型] --origin-agent [原作者] --source-wave [N] --scan-wave [M] ...`（詳見本 agent 的 S 段落；內含 apostrophe 的逐字文字使用 `'"'"'` shell-escape idiom） |
| Engineer (HTML) | Wave 3 | `/post-test-designer` | 把課程內容轉成 HTML 前先生成 10 題 post-test | `/post-test-designer --course HSW-002 --course-file [path] --distribution 4/4/2` |
| Engineer (HTML) | Wave 3 | `/aia-rewrite --bilingual` | 生成 `/aia/{slug}/` 英文版 + `/aia/zh/{slug}/` 中文版 | `/aia-rewrite --course HSW-002 --bilingual` |

**注意**：上表中的 `/post-test-designer` 和 `/aia-rewrite --bilingual` 是 **Phase 2** 要建立的 skill，v4 架構預留這些呼叫點但 skill 本身在 Phase 2 才會實作。

---

## Model Invocation Map — 多模型協作分工

**背景**：Skill Invocation Map 文件化「agents 何時呼叫哪個 skill」；Model Invocation Map 文件化「agents 何時呼叫哪個外部 LLM」。兩者並列，都是中央事實來源，由 Commander 在 Direction Seed 的第 5 欄位（Embedded Skill + Model Invocations）中複製貼上對應本角色的命令。

**分工原則**（來自 memory `feedback_multi_ai`）：
- **Claude Sonnet / Opus**（Max 吃到飽）：核心寫作、整合、決策、跨 wave 協調
- **Gemini Flash**（免費 1000/day）：搜尋 grounding、fact check、SEO、校對、persona simulation
- **Gemini 2.5 Pro**（免費但較慢）：稽核員模擬、複雜 persona 扮演、語氣評分
- **Codex $20/月**（省著用）：code review、accessibility audit、引用交叉驗證

| Agent | Wave | Model | 用途 | 命令格式 |
|-------|------|-------|------|---------|
| Investigator A | Wave 1 | Gemini Flash | 搜尋 2020+ 真實案例、DHI 資料庫查詢、法院文件搜尋 | `echo "Y" \| gemini -m gemini-2.5-flash -p "Search for [X] cases after 2020, DHI database preferred, return source URLs" --output-format text` |
| Investigator B | Wave 1 | WebSearch (primary) + Gemini Flash via `/ai-fallback` (verification / summarization) | 法規條號版本查證、ICC/NFPA 交叉驗證、state-amendment delta 查詢 | Research queries: **WebSearch tool (Claude Code built-in)** for open-ended discovery (state adoption bulletins、ICC/NFPA publisher pages、AHJ notices). Generative summarization / verification / structured extraction: `bash ~/.claude/skills/ai-fallback/scripts/call_with_fallback.sh "Verify [IBC section X] current version and cross-reference with NFPA 80 [section Y]" "gemini-2.5-flash,gemini-2.5-flash-lite,gemini-2.5-pro,codex"` (raw `echo \| gemini` invocation prohibited — Rule 8 + P-015 WebSearch migration, must use wrapper) |
| Fact Checker | Wave 2 | Gemini Flash | 數字逐項驗證、來源可達性檢查 | `echo "Y" \| gemini -m gemini-2.5-flash -p "Verify: [number] [claim]. Return VERIFIED/CORRECTED/UNVERIFIABLE + source" --output-format text` |
| Source Reviewer | Wave 2 | Codex (primary) → Gemini 2.5 Pro → Flash-Lite → Claude-native | 引用交叉驗證、來源品質評分；最小鏈深度 3 | `bash ~/.claude/skills/ai-fallback/scripts/call_with_fallback.sh "Review all citations in [file]. Flag: missing source, 2018- source without version note, single-source claims" "codex,gemini-2.5-pro,gemini-2.5-flash-lite"` |
| Compliance Reviewer | Wave 2 | Gemini 2.5 Pro | AIA 稽核員模擬（Competitor Coverage 中立性評分） | `echo "Y" \| gemini -m gemini-2.5-pro -p "Role-play AIA CES auditor. Score each Big 3 mention 1-5 for neutrality. [context]" --output-format text` |
| Project Architect Advisor | Wave 2 | Gemini 2.5 Pro (persona primary, via `/ai-fallback`) | 12 年 Project Architect persona simulation | `bash ~/.claude/skills/ai-fallback/scripts/call_with_fallback.sh "Role-play 12-year Project Architect. Read: [course]. Answer 6 decision questions: [list]" "gemini-2.5-pro,gemini-2.5-flash-lite,codex"` |
| Sales Rep Advisor | Wave 2 | Gemini 2.5 Pro | Sales rep 直覺驗證（課程是否有廠商氣味） | `bash ~/.claude/skills/ai-fallback/scripts/call_with_fallback.sh "Role-play independent hardware sales rep (8 years visiting architects). Does this read like education or advertising? Score 1-5 + reasons. Answer 5 questions from v5 spec." "gemini-2.5-pro,gemini-2.5-flash-lite,codex"` (raw `echo \| gemini` invocation prohibited — G-012 Pro hang exposure, must use wrapper) |
| Fresh Eyes Reviewer | Wave 2 | Gemini 2.5 Pro | 外部視角挑戰（不讀 Wave 1/2 報告） | `echo "Y" \| gemini -m gemini-2.5-pro -p "You have NO context. Read course cold. Challenge anything that looks taken-for-granted. Don't use jargon." --output-format text` |
| Learning Outcome Validator | Wave 2 end | Gemini 2.5 Pro | 3 個 persona 試做 post-test | `echo "Y" \| gemini -m gemini-2.5-pro -p "Role-play [persona N]. Take test: [10 questions]. Report answers + confidence" --output-format text` |
| Engineer (HTML) | Wave 3 | —（使用 Claude Sonnet via Agent tool） | HTML 實作、structured data | — |
| Candidate Collector | Side Channel | —（使用 Claude Sonnet） | 跨波次 type 平衡判斷 | — |
| Commander | All waves | Claude Opus | 指揮、決策、pilot dispatch 判斷 | — |

**延伸規則**：
- 任何 agent 在 S 中需要呼叫外部 LLM 時，必須從這張表複製命令格式，不要自己即興寫（避免參數格式不一致）
- 新增外部 LLM 呼叫時，先更新這張表，再在 agent 的 S 中引用
- Commander 的 Direction Seed 第 5 欄位（Embedded Skill + Model Invocations）同時帶 skill 和 LLM 呼叫命令

**和 Principle 7 的關係**：Principle 7 原本只說 skill 命令必須 embedded；加入 Model Invocation Map 後，LLM 呼叫命令也必須 embedded，同樣的理由（subprocess 看不到 parent memory）。Principle 7 的範圍擴展為「skill + model invocations 都必須 embedded」。

### P-015 Application: WebSearch as primary for research archetype

During Batch 1-3 scale-up, research-archetype agents (Investigator A/B)
found `/ai-fallback` pre-REST-rewrite had 0/5 success rate in production
due to Gemini free-tier routing hangs. WebSearch tool (available to all
subagents natively) was used as effective escape hatch per P-015.

After REST API rewrite (2026-04-11), `/ai-fallback` should be reliable
for paid-tier Gemini calls. However, **WebSearch remains the recommended
primary** for open-ended research tasks because:

1. WebSearch returns curated results instantly (no LLM processing overhead)
2. Sources are traceable URLs, not generated text
3. Zero API cost
4. No quota concerns

**Recommended pattern for Investigator A/B**:

1. **WebSearch first** for open-ended discovery ("find post-2020 cases of X")
2. **`/ai-fallback` for verification** (cross-check specific facts, summarize
   findings, persona-simulate a skeptical reader)
3. **`/ai-fallback` for structured extraction** (parse court docs, extract
   citations)

**[Tier B] Learning Outcome Validator — P-015 pre-simulation scope**:
Persona simulation itself (three architect personas answering decision Qs
and the 10Q post-test) **remains on Gemini 2.5 Pro as primary** via
`/ai-fallback` chain `gemini-2.5-pro,gemini-2.5-flash-lite,codex` —
WebSearch cannot perform reasoning and is NOT a substitute for persona
role-play. To keep the evidence chain attributable, Learning Outcome
Validator's WebSearch use is governed by **two explicit bright-line rules**:

  **(a) Pre-simulation phase (before any persona simulation begins)**:
  WebSearch is ALLOWED for pure fact retrieval where the output is a URL
  + a quote, NOT a reasoning chain. Examples: looking up a published IBC
  or NFPA code section number, retrieving a third-party standard
  reference, pulling a statistic from a public data source. This phase
  is explicitly authoring-time research the Validator does to construct
  the 5 independent decision questions and the 10 post-test questions
  against verifiable anchors. Example lookup: "what is the IBC 2021
  section on double-egress means of egress clearance?" — WebSearch-first
  is faster and produces traceable URLs.

  **(b) During + post simulation phase (once persona simulation starts,
  and for all scoring / cross-checking / content-gap verification)**:
  ALL retrieval MUST go through the Model Invocation Map's designated
  persona-simulation chain (`gemini-2.5-pro,gemini-2.5-flash-lite,codex`
  via `/ai-fallback`). WebSearch is **FORBIDDEN** inside the persona
  evidence chain because it blurs attribution of which model produced
  which reasoning step. If a persona's response cites a code section and
  the Validator wants to verify the citation exists, that verification
  runs through the fallback chain (Gemini Pro verifying its own or a
  sibling model's citation) — NOT WebSearch. The "reasoning-shaped
  lookup" drift mode (re-framing a reasoning task as retrieval to
  offload it to WebSearch) is explicitly prohibited by rule (b).

Rule (a) is the ONLY WebSearch-authorized window for Learning Outcome
Validator. Rule (b) is a hard boundary. This rule set is additive — it
does NOT edit the Model Invocation Map entry for Learning Outcome
Validator at line ~1041, which remains `gemini-2.5-pro` primary.
[Tier B — Auditor should confirm during Gate 3 deliverable review that
the Validator's WebSearch usage timeline falls entirely within rule (a)
and does not cross into rule (b) territory.]

WebSearch is not a full replacement — Gemini via REST is better for
synthesis, persona simulation, and structured reasoning. But for raw
discovery, WebSearch is faster, cheaper, and more reliable.

---

## Brief Layering（Tier 1 / Tier 2 — 降低 Direction Seed context 量）

**背景**：Direction Seed 的 9 個欄位如果每次派遣都把每個 agent 完整的 G/S/M（常常 500-1000 字）複製貼上到 briefing，跨 19 個 agent 累積下來 context 浪費驚人。對應 v2.html 的「分層記憶體」哲學：always-loaded 的資訊精簡，詳細內容按需載入。

**分層原則**：每個 agent 的 G/S/M 分兩層：

**Tier 1（Direction Seed 必帶）**：
- G 一句話
- S 一句話摘要
- 關鍵 M 閘門（2-3 條「絕對不能漏」的驗收）
- Embedded skill commands（從 Skill Invocation Map 複製對應本角色的命令）
- Embedded model commands（從 Model Invocation Map 複製對應本角色的命令）
- Anti-patterns 標準清單（3 條）

**Tier 2（reference on demand）**：
- S 的詳細策略（為什麼用這條路徑、其他路徑為什麼被放棄）
- 完整 M 驗收清單（所有邊角案例）
- 歷史脈絡（HSW-003 退件的教訓、過去課程的失敗模式）
- 同類 agent 的跨課程模式

**實作**：Commander 在 Direction Seed 第 3–4 欄位（O、G/S/M）帶 Tier 1 內容；Tier 2 用檔案路徑引用（例：`詳見 WTR-HSW-002-OGSM-v4.md#investigator-a-tier-2`），subagent 需要時才 Read。

**驗收**：
- 每個 agent 的 OGSM 定義中，在 G/S/M 之後加一個 `**Tier 1 摘要**` 子段落，列出 Tier 1 的精簡版
- Tier 2 內容就是現有完整 G/S/M 段落（不需要另外寫）
- Commander 的 dispatch briefing 平均長度從 2000+ 字降到 800 字（實際測量由 Performance Supervisor 記錄）

**不做的**：
- 不實際拆檔案——Tier 1/Tier 2 都在同一個 v4.md 檔案內，用標題 anchor 引用
- 不做自動化的 Tier 拆分——手動寫 Tier 1 摘要就夠，過度工程化會打敗目的

---

## Principle 7 — Embedded Skill + Model Invocation Required

**背景**：OGSM v1–v3 假設 agent 可以「自己知道」該呼叫哪些 skill 和哪個外部 LLM——基於 CLAUDE.md、memory、或對話脈絡。這個假設在 subprocess agent（透過 Agent tool 派遣的子 agent）上失敗。v4 Round 2 將範圍從 skill invocation 擴展到 model invocation：subprocess agent 看不到 parent 的 memory，不知道該用 Gemini Flash 還是 Gemini 2.5 Pro，也不知道正確的命令格式。

**問題**：
- subprocess agent 的 context 是隔離的
- 它看不到 parent Claude 的 memory、CLAUDE.md、或對話歷史
- 如果 S 只寫「使用 /content-scout flag-candidate 加入候選」，subprocess 不知道這個 skill 的命令格式、參數、或觸發時機
- 同樣地，如果 S 只寫「用 Gemini 驗證數字」，subprocess 不知道用 Gemini Flash 還是 2.5 Pro、命令格式是什麼
- 結果：subprocess 要嘛沒呼叫 skill/LLM，要嘛自己即興寫流程

**原則**：agent 需要呼叫的任何 skill **和** 外部 LLM，**必須在 S 段落中包含完整的命令格式 + 呼叫時機 + 範例**。或者在 S 段落中明確引用集中的 **Skill Invocation Map** 和 **Model Invocation Map**（本文件的對應章節）。

**驗收方式**：
- Commander 在派遣每個 subprocess agent 時，把對應 agent 的 S 段落 + Skill Invocation Map + Model Invocation Map 作為任務 briefing 的一部分傳入
- Performance Supervisor 在每個波次檢查：subprocess agent 有沒有真的呼叫該呼叫的 skill 和 LLM 模型？沒有的話是 briefing 失誤還是 agent 拒絕執行？

**為什麼是 Principle 7**：OGSM 原則 1–6 是關於「目標對齊」和「audience workflow」，Principle 7 是關於「agent 執行層」的可複製性——這是 multi-agent 系統特有的問題，傳統 OGSM 不需要處理。

---

## Direction Seed（方向種子）— Commander Dispatch Template

**背景**：概念來自 watersonusa.ai 的文章《如何組建有效率的 AI Agent 團隊》——「第零步：設定方向種子」。12 個 agent 同時工作，最怕每個人跑不同方向；所以 Commander 派遣 subagent 前必須先傳遞一段統一的任務描述，確保所有 agent 瞄準同一個目標。

Direction Seed 和 Principle 7 是同一件事的兩面：
- **Direction Seed** 回答「subagent 該知道**什麼**才能和其他 agent 對齊」（persona、O、語氣、限制）
- **Principle 7** 回答「subagent 該**如何**執行 skill 和 model 呼叫才不會漏掉」（embedded skill + model commands）

兩者合併為 **Commander Dispatch Template**——每次透過 Agent tool 派遣任何 subagent 時，briefing 必須包含以下 9 個欄位。缺一不可。

### Dispatch Template 必要欄位

1. **Course ID + Role Name**（例：`HSW-002 / Investigator A`）
2. **Target Audience Persona**（不是抽象「建築師」，是完整 persona：12 年資歷的 Project Architect，負責 drawing set + Division 08 + spec writer coordination，典型 day-to-day 工作流程簡述）
3. **O（Objective）的完整引用**——不要縮寫，讓 subagent 看到情感目標和實用目標全文
4. **This Agent's G/S/M**——從本 OGSM 文件複製貼上該 agent 的完整 G/S/M 段落
5. **Embedded Skill + Model Invocations**——從 Skill Invocation Map **和 Model Invocation Map** 複製本角色該呼叫的所有 skill + LLM 命令，含完整參數格式。

   **Plus (mandatory — knowledge query commands from ogsm-framework skill):**

   Every Iteration Team subagent brief MUST include these query commands for knowledge transfer across runs:

   ```bash
   # Query patterns library for failure-relevant patterns
   bash ~/.claude/skills/ogsm-framework/scripts/get_patterns_for_failure.sh <failure-type>

   # Query gotchas library for context-relevant pitfalls
   bash ~/.claude/skills/ogsm-framework/scripts/get_gotchas_for_context.sh <context-keyword>

   # Query skill invocation map for role-specific skill commands
   bash ~/.claude/skills/ogsm-framework/scripts/get_skills_for_role.sh <role-name>
   ```

   These queries satisfy Principle 7 (embedded skill invocation required) for knowledge transfer — subprocess agents can't see parent memory or the references/ directory, so the query commands MUST be in the briefing.

   **When to run**:
   - Factory bootstrap (Commander reads scaling-playbook.md fully via Read tool)
   - On any FAIL (Iterator runs both get_patterns_for_failure + get_gotchas_for_context)
   - Before proposing any diff (Iterator verifies no known gotcha applies)
6. **Hard Constraints**（例：促銷比例 < 20%、citation 必須兩個來源、不得虛構案例）
7. **Tone + Voice Requirements**（例：architect-peer，不是 marketing；直接、不迂迴；不預設讀者是初學者）
8. **Deliverable Format + File Path**（例：`WTR-HSW-002/investigator-a.md`，包含段落結構標準）
9. **Anti-patterns to avoid**（這個 agent **不該做的事**，反面清單）
   - 至少 3 條，明確寫出「不要做 X，應該做 Y」
   - **來源規則（hard rule）**：所有條目必須從目標 agent 的 OGSM 「Anti-patterns 標準清單」子段落 **逐字複製貼上**（verbatim），不得改寫或摘要。課程特定情境可在複製之後追加額外條目，但不能取代原條目。
   - **驗收**：Performance Supervisor 抽檢時，用字串比對確認至少 3 條與 source agent 的 Anti-patterns 清單完全一致；若被改寫（即使意思相同），視為 briefing 失誤。
   - 為什麼必要：人類 briefing 最容易漏掉「顯而易見的反面」；強迫逐字複製，parent 才會被迫把子段落內的每一個反例都看過一次，不是「我理解意思所以意譯一下」。

### 驗收方式

Commander 在派遣任一 subagent 時，briefing 的開頭必須列出這 9 個欄位的檢查清單。Performance Supervisor 在每個波次抽檢 ≥ 1 次 dispatch briefing，確認 9 個欄位都齊全——任何欄位缺失視為 briefing 失誤，該 subagent 的交付物不納入 gate review，必須重新派遣。

### 為什麼不能省略

- 省略第 2 欄（persona）→ agent 寫出 generic 內容，失去 O 的情感目標
- 省略第 3 欄（O 全文）→ agent 看到自己的 G 但不知道 G 為什麼存在，容易偏離方向
- 省略第 5 欄（embedded skills）→ Principle 7 失效，skill 呼叫變成碰運氣
- 省略第 6 欄（constraints）→ 交付物 downstream 才發現違反硬門檻，浪費下一個 agent 的時間
- 省略第 7 欄（tone）→ 不同 agent 寫出來的語氣不一致，Copy Editor 要全部重寫
- 省略第 9 欄（anti-patterns）→ subagent 產出「技術正確但方向偏離」的交付物——因為 parent 覺得顯而易見的反面沒有明說，subagent 無從得知

### Pilot Dispatch（先派一個試水溫）

9 個欄位再完整，第一次派遣仍可能漏掉某個盲點。Commander 的應對：**在每個波次開始時，先派一個 subagent**（pilot），讀交付物，確認符合 O 的精神後，才並行派遣該波次的其他 subagents。

**為什麼有效**：漏掉的盲點通常是系統性的（parent 的假設偏差），Pilot 的交付物一出來就看得見。如果 Pilot 正確，其他並行 subagents 使用同一份 briefing 也會正確。如果 Pilot 偏離，Commander 更新 briefing 再派，省下 4 個 subagents 走錯路的時間。

**實作規則**：
- Wave 1：先派 Investigator A（pilot），通過後並行派 Investigator B + Writer A + Writer B + Engagement Designer
- Wave 2：先派 Content Director（pilot），通過後並行派其他 internal reviewers + external reviewers
- Wave 3：先派 Engineer HTML（pilot），通過後繼續整合 + 部署
- Pilot 交付物的 sanity check 由 Commander 親自做，不授權給 subagent——這是跨 subagent 的判斷，只有 parent 能做

### 與 Principle 7 的整合

Principle 7 原本只說「skill 命令必須 embedded 在 S 中」。v4 Round 2 加入 Model Invocation Map 後，範圍擴展為「skill + model invocations 都必須 embedded」。整個機制變成：

1. **文件層**：每個 agent 的 S 段落包含該呼叫的 skill 命令和 LLM 命令（Principle 7）
2. **Map 層**：Skill Invocation Map + Model Invocation Map 作為雙中央事實來源，避免 S 段落之間重複維護
3. **派遣層**：Commander 在 Dispatch Template 的第 5 欄（Embedded Skill + Model Invocations），**從兩張 Map 各自複製貼上**該角色該呼叫的 skill 命令和 LLM 命令到 briefing 中

這個三層設計確保 skill + model 呼叫資訊在 (1) agent 定義、(2) 中央 Map、(3) 實際派遣 briefing 三個地方都存在——任何一層遺漏，其他兩層都能補救。

---

### 🗑️ v3.1 的其他「新 agent」已在 v4 降級

v3.1 曾把以下四項作為獨立 agent 列出（#20–#23），v4 已重分類：

- **Post-Test Designer** → `/post-test-designer` skill（Phase 2 建立），Wave 3 由 Engineer (HTML) 呼叫。題目設計的 4/4/2 分配、distractor 來源追蹤、真實後果解析等規則保留在 skill 定義裡。
- **Competitor Coverage Auditor** → 併入 Compliance Reviewer 的 M 擴充（見下方 Compliance Reviewer section 的 4 條新增驗收）。三大廠提及 > 0、中立性評分、類別覆蓋、促銷比例 < 20% 全部由 Compliance Reviewer 負責。
- **Chinese Translator** → `/aia-rewrite --bilingual` skill flag（Phase 2 實作）。術語在地化、Writer B 資源段落重寫、台灣 Project Architect persona 驗證等規則保留在 skill 定義裡。
- **SEO/AEO Engineer** → 流程倒轉原則 deferred。AI 先寫 → 人類補缺的流程不在 v4 範圍內，留給未來 phase。

這四項降級的原因詳見本章節開頭的「核心洞察」段落——**可重複流程屬於 skill，不屬於 agent**。

---

## Alignment Verification Matrix（v4）

| Agent | Primary G Output | O Emotional (喜歡) | O Practical (能判斷) | O Risk if G Fails |
|-------|-----------------|-------------------|---------------------|-------------------|
| Commander | 建築師視角貫穿 19 個 agent | 直接影響 | 直接影響 | 整體失敗 |
| Investigator A | 建築師認識的場景中的真實案例（DHI + 法院雙來源） | 建立情感連結 | 提供決策依據 | 建築師感受不到課程和自己有關 |
| Investigator B | 可引用的條號（ICC+NFPA 交叉驗證）+ 可捍衛的費用數字 | — | 核心 | 建築師無法在壓力下引用 |
| Writer A | 從建築師決策點出發的概念框架 | 建立好奇心 | 建立理解基礎 | 後半段決策練習失去土壤 |
| Writer B | 情境辨識能力 + SpecLink/SPC Alliance/CSC/CSI 資源導航 | — | **新：實現路徑** | 建築師知道 Waterson 但不知道怎麼落實 |
| Engagement Designer | 3 個關鍵決策節點的線上 self-paced 互動（distractor 有案例來源） | 提升參與感 | 建立決策本能 | 被動閱讀，無能力轉移 |
| Content Director | 建築師問題結構的敘事流（含 Writer B 資源介紹的邏輯審查） | 直接影響 | 間接影響 | 建築師迷失在技術細節中 |
| Compliance Reviewer | AIA HSW 認證通過（含 Writer B 中立性合規審查） | 必要條件 | 必要條件 | 課程永遠到不了建築師 |
| Copy Editor | 一次讀懂的語言 + 可用的術語表（含 spec 資源名稱一致性） | 降低摩擦 | 降低認知負擔 | 重讀造成學習中斷 |
| Fact Checker | 每個數字都可被建築師引用（含 spec 資源組織描述驗證） | — | 直接影響 | 建築師在現場被糾正，信任崩潰 |
| Source Reviewer | 建築師可以直接使用的參考清單（含 spec 資源 URL 可及性） | — | 擴展工具包 | 建築師無法追蹤和引用 |
| Engineer | 流暢、自包含的 HTML 體驗（含 spec 資源連結實作） | 直接影響 | 傳遞機制 | 技術障礙打斷學習 |
| **Project Architect Advisor** | Project Architect 第一印象（含 spec 資源介紹的中立性感受） | **唯一直接測量** | 間接測量 | O 情感目標未被驗證 |
| **Sales Rep Advisor** | 市場可行性（含 spec 資源「廠商氣味」測試） | 真實場景驗證 | 語言易懂性 | 課程在現實市場中無法流通 |
| **Fresh Eyes Reviewer** | 論點獨立性（含「迷思破除」段落的客觀性審查） | — | 確保論點站得住腳 | 建築師在特殊情境下做出錯誤決策 |
| Performance Supervisor | 每個波次的建築師視角評分（含 M/S 對準狀態追蹤） | 早期預警 | 早期預警 | O 偏移在最後才被發現 |
| Quality Auditor | 交接品質（含 S 承諾資源是否實際出現在交付物的閘門） | 保護修改時間 | 保護修改時間 | 技術問題壓縮建築師體驗改善空間 |
| Learning Outcome Validator | 直接測量 O（含 spec 資源導航的學習驗證） | — | **唯一直接測量** | 部署是希望，不是證據 |
| **🗃️ Candidate Collector** | ≥2 blog 題目候選 + 完整原始資料寫入 `.content-scout-queue.md` | — | — (間接：不影響本課程 O) | 課程副產品被浪費，Phase 3 Blog Writer Fleet 無從接手 |

---

## Wave Gate Conditions（v4）

### Gate 0 → Wave 1 開始
- [ ] OGSM v4 文件確認
- [ ] 所有 Wave 1 角色收到包含建築師 persona 描述的任務簡報（不只是格式要求）
- [ ] Writer B 收到包含 SpecLink / SPC Alliance / CSC/CSI 的介紹材料和「第三方中立角度」的寫作指示

### Gate 1 → Wave 2 開始
- [ ] 所有 5 個 Wave 1 交付物完成
- [ ] Performance Supervisor `monitor-002-wave1.md` 無建築師視角評分 1 的角色（或已有處理計劃）
- [ ] Quality Auditor `audit-002-wave1.md` 確認所有交付物交接就緒，**且 S 承諾的資源實際出現在交付物中**
- [ ] Commander 確認每個交付物有通過「建築師視角存在嗎？」的 gate 問題
- [ ] **新增**：Writer B 交付物包含五個情境的視覺錨點描述，且三個 spec 資源都有獨立介紹段落
- [ ] **v4**：Candidate Collector 收到 Wave 1 交付物初稿並啟動掃描

### Gate 2 → Wave 3 開始
- [ ] 所有 5 個內部 Wave 2 交付物完成
- [ ] **所有 3 個外部 reviewer 報告完成**（Project Architect Advisor + Sales Rep Advisor + Fresh Eyes）
- [ ] Commander 對所有外部 reviewer 的負面回饋有明確的處理記錄
- [ ] Performance Supervisor `monitor-002-wave2.md` 無阻礙問題
- [ ] Learning Outcome Validator `validate-002-learning.md` 確認所有 3 個 persona 通過 4/5 題以上
- [ ] **新增**：Learning Outcome Validator 確認至少 2 個 persona 能說出具體 spec 資源使用路徑
- [ ] **新增**：Sales Rep Advisor 確認 Writer B 的 spec 資源介紹「聞起來像資訊提供」（不是「輕微廠商引導」或「明顯廣告」）
- [ ] **v4**：Compliance Reviewer 通過 Competitor Coverage M（三大廠中立提及 > 0 + 促銷比例 < 20% + 中立性評分平均 ≥ 4）

### Gate 3 → HTML 部署前
- [ ] Engineer HTML 通過 W3C 驗證
- [ ] Engineer 確認 SpecLink / SPC Alliance / CSC / CSI 連結正確實作且可訪問
- [ ] Engineer (HTML) 已呼叫 `/post-test-designer` skill（Phase 2 建立）生成 10 題 post-test，題目分配 4/4/2，80% 通過率校準 ≥ 80% persona 試做通過
- [ ] `.content-scout-queue.md` 含 ≥ 2 個候選，每個候選 6 個欄位完整（id / source / title / type / keywords / research_data / why_worth_writing / timestamp）
- [ ] Commander 最終審查完成
- [ ] `/security-check` 通過
- [ ] `git push` 由 Commander 授權

### Gate 4 → Post-HTML 發布驗證
- [ ] Vercel 部署成功，課程 URL 可訪問（HTTP 200）
- [ ] 所有 SpecLink / SPC Alliance / CSC / CSI 連結在線上版本中可正常點擊（target="_blank" 確認）

---

## v3 和 v2 的核心差異

| 面向 | v2 | v3 |
|------|----|----|
| Writer B 的定位 | 教建築師讀 spec 語言、做決策 | 教建築師情境辨識 + 知道獨立 spec 資源路徑 |
| Writer B 的 G | 建築師有一個決策工具 | 建築師帶走情境辨識能力 + 實現路徑 |
| Writer B 的 S | 決策樹、場景練習 | 五個情境 + SpecLink/SPC Alliance/CSC/CSI（中立角度） |
| Writer B 的 M | 交付 24 張投影片 + 決策工具 | 驗證三個 spec 資源的實際介紹品質、中立性自評、迷思破除段落 |
| M 的設計原則 | 任務清單（交付 X 個、記錄 Y 個） | 對準 S 的資源使用（S 承諾的資源是否真的被使用和驗證） |
| Investigator A 的 M | 提供 5 個案例 | 驗證 DHI 資料庫實際查詢 + 每個案例的雙來源確認 |
| Investigator B 的 M | 引用 4 個來源 | 驗證 ICC Digital Codes 實際查詢 + NFPA 交叉驗證 + 修正記錄 |
| Sales Rep Advisor 的任務 | 評估課程是否適合拜訪建築師 | 加入 spec 資源「廠商氣味」測試（第 5 個問題） |
| Learning Outcome Validator | 確認決策工具可獨立使用 | 加入 spec 資源導航的學習驗證（persona 能說出資源名稱） |
| Gate 條件 | 交付物完成 + 建築師視角存在 | 加入 spec 資源介紹的中立性驗證 + 資源連結可訪問確認 |

---

## v3.1 擴充（本次新增，2026-04-10）：18 → 23 agents

五個新 agent 覆蓋課程生命週期的五個缺口。原版 v3 只覆蓋「課程內部生產鏈」，v3.1 擴充覆蓋「發現 → 翻譯 → 測驗 → 審查 → 延伸」的完整生命週期。

| 新增 Agent | Wave 位置 | 覆蓋的缺口 | 關鍵驗收 |
|-----------|----------|-----------|---------|
| 🔭 **Content Scout** | Side Channel（Wave 1-2 並行） | 課程影響力放大（blog 內容管線） | ≥ 2 候選寫入 content-plan.md，含 AEO 預覽 + Gemini Flash SEO |
| 📖 **Post-Test Designer** | Wave 3（HTML Dev 之前） | CEU 學分關卡 + 最後學習機會 | 10 題 4/4/2 分配 + distractor 有案例來源 + persona ≥ 80% |
| 🏭 **Competitor Coverage Auditor** | Wave 2 Internal | AIA 實質合規（HSW-003 退件預防） | 三大廠中立提及 > 0 + 促銷 < 20% + 類別覆蓋完整 |
| 🌏 **Chinese Translator** | Wave 3（HTML Dev 之後） | 台灣市場在地化 | `/aia/zh/` 完整版 + 30+ 詞術語表 + Writer B 台灣資源重寫 |
| 📈 **SEO/AEO Engineer** | Wave 3（HTML Dev 之後） | 課程發現層（Google + AI 引擎） | Structured data + Rich Results 通過 + llms-full.txt 更新 |

**新增 Gate 4**：Post-HTML 發布驗證——確保 Chinese Translator 和 SEO/AEO Engineer 的交付物在部署前完成並通過。

### v3.1 關鍵設計洞見（新增原則）

> **OGSM 不只看課程品質，還要看發現 → 留下影響的完整生命週期。**

v3 把課程內部品質做到極致——Project Architect 讀到課程那一刻會覺得這是為他寫的。但 v3 漏掉了一個問題：**他怎麼找到這門課程？讀完後，課程怎麼變成持續的影響力？非英語市場怎麼落地？**

v3.1 的五個新 agent 回答的是「課程如何從一次性學習事件變成持續的影響力系統」：
- **發現層**（SEO/AEO Engineer）——建築師在搜尋旅程中找到課程
- **在地化層**（Chinese Translator）——台灣 Project Architect 讀到同樣品質的課程
- **驗證層**（Post-Test Designer）——CEU 學分讓建築師能拿走這份學習
- **實質合規層**（Competitor Coverage Auditor）——課程通過 AIA 的實質審查，不只形式審查
- **放大層**（Content Scout）——每次課程都產出 blog 內容，擴大觸及面

OGSM 的設計原則是「每個 agent 都要串回 O」。v3.1 的擴充讓這個原則延伸到課程生命週期的每一個環節——不只課程內部，還包括課程的發現、傳播、留存。

---

*Document maintained by A君. Update CHANGELOG.md after each wave completion.*
*v2 preserved at WTR-HSW-002-OGSM-v2.md for comparison.*
*v1 preserved at WTR-HSW-002-OGSM.md for reference.*

---

## Known Issues / To Monitor

These are architectural concerns raised by Gemini Flash during round 2 review that we deliberately chose NOT to fix preemptively. They are recorded here as monitoring items to observe during the first real run (HSW-006). If any of these actually manifest as a problem, then we fix; otherwise we avoid premature abstraction.

**Principle**: Don't fix what you haven't seen break yet. Over-engineering a fix for a hypothetical failure mode costs more than the failure itself would.

### Issue #1 — Pilot Dispatch only catches pilot-specific blind spots

**Concern**: Pilot Dispatch (每波次先派一個 subagent 驗證 briefing) catches blind spots in the pilot agent's interpretation, but other parallel subagents may have their own blind spots that the pilot doesn't share. A correct pilot ≠ all agents will be correct.

**Possible fixes (do NOT implement now)**:
- **Shadow Pilot**: compare pilot output against a simulated parallel execution of a different subagent with the same briefing — look for divergent interpretations
- **Rotating Pilot**: use a different agent as pilot each wave to expose different blind spots over time

**What to watch during HSW-006**: after each wave's Pilot passes, does the rest of the wave produce outputs that diverge from the pilot's interpretation in ways that weren't caught? If yes ≥ 2 times in HSW-006, implement Shadow Pilot.

---

### Issue #2 — Tier 1 摘要 150-word budget may bloat

**Concern**: Complex agents like Compliance Reviewer (now has 4 new Competitor Coverage M items) may not fit in 150 words without losing critical information. Pressure to add "just one more critical gate" will gradually bloat Tier 1 back toward the original 2000+ word size, defeating the purpose.

**Possible fixes (do NOT implement now)**:
- **Hard word-count enforcement**: automated check that rejects Tier 1 briefs exceeding the limit — forcing move to Tier 2
- **Objective Tier 1 criteria**: restrict Tier 1 to "immediate action triggers + decision points only" — no background, no history, no rationale

**What to watch during HSW-006**:
- Measure actual Tier 1 word count for all 19 agents at dispatch time
- If any agent's Tier 1 exceeds 250 words, flag it (50% bloat)
- If ≥ 3 agents bloat, implement hard enforcement

---

### Issue #3 — Candidate Collector may still drift into recommendation

**Concern**: Even with the Q1 scope split (situational judgment only, collection is a skill), Candidate Collector's cross-wave type balance judgment is itself a form of recommendation ("we need more case-studies"). The line between "observe imbalance" and "recommend action" is thin.

**Possible fixes (do NOT implement now)**:
- Hard-limit collector_notes to descriptive language only (禁用詞 lint already planned for /content-scout skill)
- Remove "alert" generation and keep only "Type Distribution counts" — let downstream agents interpret

**What to watch during HSW-006**: do the Type Distribution alerts Candidate Collector produces actually change what Investigator A/B do next wave? If alerts are ignored OR cause over-correction, rethink.

---

### Issue #4 — Post-test question quality may pass technical compliance while missing learning assessment

**Concern**: `/post-test-designer` skill enforces 4/4/2 distribution + distractor-from-real-cases rule, which catches procedural AIA failures. But technically-compliant questions can still have:
- Ambiguous wording that rewards test-taking skill over content understanding
- Misinterpreted case details (skill reads the case, but subtly misrepresents it)
- Distractors that are real mistakes but wrong FOR THIS QUESTION
- Answer explanations where "real-world consequence" exists but doesn't match this specific question's content

The biggest risk: CEU credit is granted for factually-incorrect or misleading content, and architects act on flawed information in real projects.

**Possible fixes (do NOT implement now)**:
- Human expert review layer for post-tests before first publication
- Second-pass reviewer (different Gemini persona or Claude subagent) specifically auditing question clarity + case fidelity
- Post-course architect feedback channel: log which questions architects complain about, recalibrate

**What to watch during HSW-006**:
- After `/post-test-designer` produces the 10 questions, manually read all 10 before the Learning Outcome Validator persona run
- Flag any question where: the "why wrong" explanation for a distractor doesn't match that distractor's claim, OR the case description has been compressed in a way that changes meaning
- If 2 or more questions have fidelity issues in HSW-006, add human review layer to the skill workflow

---

### Issue #5 — Bilingual validation via Gemini persona cannot catch cultural blind spots

**Concern**: `/aia-rewrite --bilingual` validates the Traditional Chinese version by running Gemini 2.5 Pro as a simulated 12-year Taiwan Project Architect persona. This catches technical correctness and obvious translation errors. But Gemini's simulation will miss:
- Unwritten Taiwan architecture industry norms (how things are actually done, not how they're documented)
- Cultural sensitivities specific to Taiwan professional context
- Localized terminology nuances that feel wrong to natives but look correct in reference materials
- Regional practice variations (北部 vs 南部、公部門 vs 民間案) that real architects instinctively recognize

The biggest risk: a technically accurate but culturally tone-deaf Chinese version is published, and real Taiwan architects dismiss it as "machine-translated" — damaging Waterson's credibility in the Taiwan market that the bilingual effort was meant to build.

**Possible fixes (do NOT implement now)**:
- Recruit 2-3 real Taiwan Project Architects (from Waterson's existing Taiwan network) as pilot feedback reviewers for the first bilingual course
- Add a human review gate after Gemini persona validation: specifically ask "does this feel like it was written for you, or translated for you?"
- Build a feedback loop: log which sections Taiwan reviewers flag, feed corrections back into `/aia-rewrite --bilingual` glossary and resource research

**What to watch during HSW-006**:
- After the first bilingual HSW-006 Chinese version is produced, request 2-3 real Taiwan architect reviews BEFORE publication
- Compare real architect feedback vs Gemini persona simulation results — if they diverge significantly, Gemini simulation alone is insufficient
- If divergence is 30% or more of flagged issues, add human review as mandatory step in `/aia-rewrite --bilingual` workflow

---

### Issue #6 — /ai-fallback per-model timeout insufficient in real production

**Concern**: INT-001 fix (per-model 60s timeout) was applied to `call_with_fallback.sh`, but smoke test on real Investigator A showed 3 of 4 production invocations STILL had all Gemini models timeout. Gemini 2.5 Flash + 60s = deterministic failure; Gemini 2.5 Flash-Lite + 150s has ~25% success rate.

**Evidence**: smoke test wall clock 35.5 min, 6 fallback events across 4 /ai-fallback invocations, all Gemini models exhausted 3 of 4 times.

**Proposed fix (defer to v6 or pre-scale)**:
- Default fallback chain change: remove `gemini-2.5-flash` primary, start from `gemini-2.5-flash-lite`
- Default `OGSM_MODEL_TIMEOUT` raised from 60s to 120s
- Update Model Invocation Map default commands accordingly

**When to revisit**: BEFORE Batch 1 scale-up launch

---

### Issue #7 — Codex trust-check silent terminal failure in fallback chain

**Concern**: When Gemini chain exhausts, `call_with_fallback.sh` falls to Codex. Smoke test discovered Codex refuses with "Not inside a trusted directory" error — this is a silent terminal failure at the END of the fallback chain.

**Evidence**: smoke test encountered this during heavy research phase. Codex never returned useful output; chain terminated with no LLM result.

**Proposed fixes (options)**:
- (a) Pre-approve codex trust for waterson-ai-growth-system directory
- (b) Add WebSearch as final fallback layer in `call_with_fallback.sh`
- (c) Document in runbook: operator must manually pivot to WebSearch when this error occurs

**When to revisit**: BEFORE Batch 1 scale-up launch (combined with Issue #6)

---

### Issue #8 — Quality Auditor reverse-index coverage is observation-only until G-022 lands

**Concern (G-022, cross-cutting, Quality Auditor only)**: The reverse-index check added to Quality Auditor's M (see Quality Auditor section) requires upstream reviewers (Fact Checker, Source Reviewer) to emit per-claim coverage tables so QA can reconcile. In HSW-002 Wave 2 polish simulation, Source Reviewer's aggregate output ("No single-source citations. PASS.") was ambiguous on per-claim coverage and forced QA to mark the row as "Partial" with a manual note. The new M bullet requires per-claim output; the new Source Reviewer M bullet requires producing it. Until HSW-006 runs with both changes live, we do not yet know whether reviewers will consistently emit the per-claim table or whether QA's reverse-index mechanics work at scale.

**Scope note (G-022 cross-cutting)**: This is a **Quality Auditor-only** cross-cutting. Fact Checker, Source Reviewer, and Performance Supervisor are NOT asked to run their own reverse-index checks — that would duplicate work and blur lane boundaries (see Quality Auditor anti-pattern 4: scope-creep forbidden). G-022 exists to make sure QA's reverse-index has data to chew on; it does not extend to other audit agents.

**Evidence**: Polish-wave2/polish-quality-auditor simulation (robot-2-deliverable.md §1c) caught 2 unaudited claims (5 lbf ADA opening-force, $42K remediation cost) that Fact Checker silently skipped, using reverse-index. Without the new Source Reviewer per-claim output rule, SR's row was only markable as "Partial" because aggregate "PASS" did not expose which claims were checked.

**What to watch during HSW-006**:
- Does Fact Checker's audit table cover 100% of testable claims in each Wave 1 deliverable? Record the coverage ratio for every wave.
- Does Source Reviewer's per-claim coverage index (new M bullet) actually get produced? If Source Reviewer reverts to aggregate output, QA will be unable to reconcile — flag and fix immediately.
- How often does QA's reverse-index catch silently-skipped claims? Target: ≤ 1 per wave. > 1 per wave for ≥ 2 waves → upstream reviewer brief is under-specified, escalate.
- Does the `skipped-or-hallucinated (indistinguishable without execution log)` fault-attribution value actually get used? If yes, Direction Seed needs tightening (make execution log mandatory at briefing time).

**Possible fixes (do NOT implement now)**:
- **Structured audit schema**: move Fact Checker + Source Reviewer outputs from free-form markdown to a required JSON/YAML schema with `claim_id` keys. Makes reverse-index mechanical rather than manual.
- **QA helper script**: small CLI that ingests a Wave 1 deliverable and the corresponding Wave 2 audit file, emits the reverse-index table automatically. Removes human error from the reconciliation step.
- **Per-claim coverage metric in Performance Supervisor's architect-perspective score**: PS already aggregates scoring; adding coverage ratio is a small extension if reviewers already emit per-claim tables.

**When to revisit**: after HSW-006 Wave 2 runs once end-to-end with the new Quality Auditor section live. If coverage < 100% in any wave, or if Source Reviewer per-claim output is skipped ≥ 1 time, implement the structured schema fix before HSW-007.

---

## Monitoring Protocol

Performance Supervisor is responsible for tracking these eight issues during HSW-006. At the end of HSW-006 production, Commander produces a `known-issues-observations.md` document summarizing:

1. Did Issue #1 / #2 / #3 / #4 / #5 / #6 / #7 / #8 actually manifest? Evidence?
2. If yes, what was the impact?
3. Recommendation: fix now, fix later, or close as "theoretical concern only"

---

## Deferred Improvements

These are planned architectural improvements that have been **deliberately deferred** to a future phase. Unlike Known Issues (which are runtime risks to monitor during HSW-006), Deferred Improvements are **optimizations** — the system works without them, but would run more efficiently with them. They are recorded here so they're not forgotten, and so we can evaluate cost vs benefit before HSW-007 or a later course.

**Principle**: Ship what works, improve what's slow. Don't retrofit existing skills until you have evidence (not intuition) that the optimization is worth the regression risk.

---

### Improvement #1 — Retrofit `/content-scout` with scripts/

**Status**: DONE — 2026-04-11

**Evidence**:
- `~/.claude/skills/content-scout/scripts/validate_candidate.py` — 9-field schema + type validation
- `~/.claude/skills/content-scout/scripts/banned_word_lint.py` — prescriptive language lint (exit 0/2)
- `~/.claude/skills/content-scout/scripts/update_type_distribution.py` — recount + imbalance alerts
- `~/.claude/skills/content-scout/scripts/append_candidate.py` — full pipeline (validate + lint + append + distribute)
- `~/.claude/skills/content-scout/SKILL.md` — section 9 updated to reference scripts with usage examples
- All 4 scripts tested: valid/invalid inputs verified, exit codes confirmed

**Proposed changes** (all implemented):
- Add `scripts/validate_candidate.py` — 10-field schema validation (currently done procedurally in SKILL.md)
- Add `scripts/banned_word_lint.py` — prescriptive language detection for `collector_notes` field (currently done procedurally)
- Add `scripts/update_type_distribution.py` — Type Distribution counter update (currently done procedurally)
- Add `scripts/append_candidate.py` — queue file append with auto-id + timestamp (currently done procedurally)

---

### Improvement #2 — Retrofit `/post-test-designer` with scripts/

**Status**: DONE — 2026-04-11

**Evidence**:
- `~/.claude/skills/post-test-designer/scripts/validate_distribution.py` — enforces 4/4/2 (exit 0/2)
- `~/.claude/skills/post-test-designer/scripts/generate_question_template.py` — blank template per type (recall/application/judgment)
- `~/.claude/skills/post-test-designer/scripts/parse_source_references.py` — Zone A/B/C extraction + case ID detection, JSON output
- `~/.claude/skills/post-test-designer/scripts/format_answer_key.py` — answer key table from JSON
- `~/.claude/skills/post-test-designer/SKILL.md` — Scripts Reference section added with usage examples
- All 4 scripts tested: valid/invalid inputs verified against real WTR-HSW-002-full-course.md

**Proposed changes** (all implemented):
- Add `scripts/validate_distribution.py` — 4/4/2 question distribution enforcement (currently done procedurally)
- Add `scripts/generate_question_template.py` — deterministic markdown template for each question type (currently done procedurally via SKILL.md example)
- Add `scripts/parse_source_references.py` — extract Writer A / Writer B / Investigator A content zones from the course file (currently done by LLM reading the file)
- Add `scripts/format_answer_key.py` — deterministic answer key table generation

---

### Improvement #3 — `/new-course` generate_ogsm.py template parameterization may be too rigid

**Status**: DONE — 2026-04-11

**Evidence**:
- `~/.claude/skills/new-course/scripts/generate_ogsm.py` — added `--scope`, `--audience`, `--section-count`, `--base-template`, `--flexible` flags
- Backward compatible: existing calls without new flags produce identical output
- `~/.claude/skills/new-course/SKILL.md` — Scripts Reference updated with flag documentation table
- Tested: `--scope hsw-lu --audience spec-writer --section-count 10 --flexible` produces correct output with Template Variables block and persona substitution

**Flags added**:
- `--scope hsw|lu|hsw-lu` — updates credit type references + injects scope note
- `--audience project-architect|design-architect|principal|spec-writer` — replaces persona labels throughout
- `--section-count 5|7|10|12` — injects section-count advisory with parallel-agent recommendation for 12-section courses
- `--base-template v4|v5|custom-path` — auto-resolves template from known locations
- `--flexible` — prepends `## Template Variables` block documenting all parameterization choices

**Original concern** (addressed):
`scripts/generate_ogsm.py` parameterizes the v4 template by string substitution (course code, title, slug). This works for courses similar to HSW-002 but was too rigid for courses differing in scope, audience, or section count.

---

### Improvement #4 — `/research-topic` Gemini CLI dependency (noted only)

**Status**: Flagged by Gemini Flash Phase 2e review. **Not planning to fix** — recording for awareness only.

**Concern**: `scripts/fetch_sources.py` depends on Gemini CLI (`gemini -m gemini-2.5-flash`) for source grounding. This creates 3 dependencies:
- Gemini CLI must be installed locally
- Network must be reachable to Google APIs
- Gemini grounding quality is variable

**Why NOT fixing**:
- Memory rule `feedback_multi_ai` explicitly says Gemini Flash is our search grounding choice (free 1000/day)
- Alternatives (direct API, traditional keyword search) either cost more or lose grounding capability
- Dependency is acceptable for our use case
- If Gemini becomes unreliable, we already have a fallback in `feedback_multi_ai`: add a second Gemini-capable account or switch to Codex

**Just be aware** this dependency exists; no preemptive abstraction needed.

---

## Relationship to Known Issues

| Aspect | Known Issues | Deferred Improvements |
|--------|-------------|---------------------|
| **Nature** | Runtime risks (things that might go wrong) | Optimizations (things that could be more efficient) |
| **Trigger for action** | Issue manifests in production | Evidence of cost/benefit after measurement |
| **Urgency** | High if manifested | Low unless proven |
| **Risk of fixing** | Low (fixes are defensive) | Medium (retrofit can cause regression) |
| **Decision owner** | Commander during production | Architecture review between courses |

Both sections feed into v5 planning after HSW-006 retrospective.

This document feeds into the v5 planning decision.