feat(docs): Path Map wiki pipeline — flowchart + generator + drift-guard (#276 Phase 2)

docs/wiki/Path-Map.md

@@ -0,0 +1,149 @@
+# IDD Path Map
+
+> **36 條 sanctioned path 的選擇導航圖** — maintainer 日常查詢用（#276）。
+> Single source：[docs/workflows.md](https://github.com/PsychQuant/issue-driven-development/blob/main/docs/workflows.md)（§ Path Flowchart + § Path Catalog）；
+> 本頁由 `scripts/generate-path-map.py` 生成，**請勿直接編輯** — 改 workflows.md 後重跑 generator。
+
+```mermaid
+flowchart TD
+    START(["你正要做什麼？"]) --> Q1{"single issue<br/>還是 multi？"}
+
+    Q1 -->|single| QM{"type=meeting？"}
+    QM -->|yes| A5["P-meeting<br/>（複雜度評估前分流）"]
+    QM -->|no| Q2{"Complexity？<br/>（硬閘：≥5 檔互依概念或<br/>shared abstraction → MUST Plan）"}
+    Q2 -->|Simple| Q3{"attended？<br/>（你在 keyboard）"}
+    Q3 -->|yes| A1["P-atomic（5 touchpoints）"]
+    Q3 -->|no| QD{"已有 diagnosis？"}
+    QD -->|yes| B1["P-auto-from-diagnosed"]
+    QD -->|no| B2["P-auto-full-swallow"]
+    Q2 -->|Plan| A2["P-plan-gated<br/>（EnterPlanMode 審批）"]
+    Q2 -->|Spectra| Q4{"方向已明確？<br/>（零 open questions）"}
+    Q4 -->|yes（罕用）| A4["P-spectra-opt-out"]
+    Q4 -->|no（預設）| A3["P-spectra-discuss-first"]
+
+    Q1 -->|multi| Q5{"issues 之間的關係？"}
+    Q5 -->|同根 cluster| B4["P-batch-diagnose → P-cluster-pr"]
+    Q5 -->|ripple：1 root + auto-emerge| B5["P-chain-from-root"]
+    Q5 -->|forest：N roots 獨立| B6["P-chain-multi-root<br/>（或 N × P-atomic）"]
+    Q5 -->|unrelated backlog drain| B3["P-batch-drain<br/>（conflict-class ordered）"]
+    Q5 -->|source-driven（一份來源 ≥2 findings）| D1["P-multi-finding<br/>（強制單線 → P-no-multi-finding）"]
+
+    subgraph C["C. Batch（N issues 各自 atomic，無共用 PR）"]
+        C2["P-batch-comment"]
+        C3["P-batch-update"]
+        C4["P-batch-edit"]
+        C5["P-batch-close"]
+    end
+
+    subgraph E["E. Verify-only / PR review"]
+        E1["P-pr-verify"]
+        E2["P-verify-file-profile（非 code deliverable）"]
+        E3["P-pr-verify-then-merge"]
+    end
+
+    subgraph F["F. Resume / 中斷恢復"]
+        F1["P-spectra-resume"]
+        F2["P-implement-retry"]
+    end
+
+    subgraph G["G. Non-lifecycle / ancillary"]
+        G1["P-list-triage"]
+        G2["P-route-recommend"]
+        G3["P-comment-only"]
+        G4["P-edit-only"]
+        G5["P-discussions-intake"]
+        G6["P-clarify-audit"]
+        G7["P-find-lookup"]
+        G8["P-ask-history"]
+        G9["P-report-rollup"]
+        G10["P-config-maintain"]
+    end
+
+    subgraph H["H. Autopilot（no human-in-loop）"]
+        H1["P-loop-autopilot"]
+        H2["P-cron-autopilot"]
+        H3["P-cron-list-triage"]
+    end
+```
+
+## Path 一覽（依類別）
+
+### A. Single-issue lifecycle paths(typical bug / feature flow)
+
+| Path | 說明 |
+|------|------|
+| `P-atomic` | Simple complexity baseline |
+| `P-plan-gated` | Plan tier with EnterPlanMode approval |
+| `P-spectra-discuss-first` | Spectra tier with alignment |
+| `P-spectra-opt-out` | Spectra with direction pre-confirmed(罕用 |
+| `P-meeting` | meeting-type deliberation（#57，v2.93+ |
+
+### B. Convenience-orchestrator paths(快速 lifecycle 完成)
+
+| Path | 說明 |
+|------|------|
+| `P-auto-from-diagnosed` | diagnose 已過,跑自動化 |
+| `P-auto-full-swallow` | legacy `idd-all` 一次跑完 |
+| `P-batch-drain` | multi-issue conflict-class-ordered sequential（v2.83+，#182 |
+| `P-cluster-pr` | N issues 共 1 PR |
+| `P-chain-from-root` | 1 root + auto-emergent spawn |
+| `P-chain-multi-root` | 多 root forest chain |
+
+### C. Batch paths(N issues 各自 atomic)
+
+| Path | 說明 |
+|------|------|
+| `P-batch-diagnose` | - **Use case**:同 doc 來源 N issues,各自 diagnose 各 user-reviewable |
+| `P-batch-comment` | - **Use case**:批次加同一段 note(e.g.「blocked by upstream」)到多 issue |
+| `P-batch-update` | - **Use case**:批次同步 Current Status phase |
+| `P-batch-edit` | - **Use case**:批次套同一段 edit 到多 issue 既存 comment |
+| `P-batch-close` | - **Use case**:cluster PR merge 後批次 close,**每個 issue 仍各自獨立 closing summary** |
+
+### D. Multi-finding dispatch paths(source-driven mixed routing)
+
+| Path | 說明 |
+|------|------|
+| `P-multi-finding` | auto-triggered |
+| `P-no-multi-finding` | force single-issue |
+
+### E. Verify-only / PR-review paths(external agent integration)
+
+| Path | 說明 |
+|------|------|
+| `P-pr-verify` | - **Use case**:外部 agent(Codex / Copilot)開的 PR,IDD 6-AI ensemble verify |
+| `P-verify-file-profile` | 非 code deliverable 驗證（#258，v2.97+ |
+| `P-pr-verify-then-merge` | - **Use case**:verify-gated PASS 後 user 主動 merge,**per IDD MANIFESTO**「auto-merge 須走 #3… |
+
+### F. Resume / continuation paths(mid-work recovery)
+
+| Path | 說明 |
+|------|------|
+| `P-spectra-resume` | - **Use case**:Spectra change 中途 requirements 變更,重新對齊 spec 後繼續 |
+| `P-implement-retry` | - **Use case**:Chain mode 某 issue verify FAIL,retry on cluster branch(避免另開新 branch) |
+
+### G. Non-lifecycle / ancillary paths(maintenance + observation)
+
+| Path | 說明 |
+|------|------|
+| `P-list-triage` | - **Use case**:開工前 triage,看哪些 open issue,各自 phase 為何 |
+| `P-route-recommend` | - **Use case**:選 agent(Codex / Claude / etc.) |
+| `P-comment-only` | 非 lifecycle 推進 |
+| `P-edit-only` | - **Use case**:編輯既存 comment(append / replace / prepend-note) |
+| `P-discussions-intake` | Discussions 盲點橋接（#221，v2.95+ |
+| `P-clarify-audit` | terminology / semantic surfacing（#135，v2.72+ |
+| `P-find-lookup` | 語意查找（#139，v2.97+ |
+| `P-ask-history` | issue 知識庫問答（#72，v2.99+ |
+| `P-report-rollup` | 跨 issue 人類 triage 視圖（#134，v2.97+ |
+| `P-config-maintain` | config 生命週期（v2.31+ |
+
+### H. Unsupervised / autopilot paths(no human-in-loop)
+
+| Path | 說明 |
+|------|------|
+| `P-loop-autopilot` | - **Use case**:autonomous 持續執行;適合 well-bounded simple issues |
+| `P-cron-autopilot` | - **Use case**:cron-scheduled ETL / housekeeping |
+| `P-cron-list-triage` | - **Use case**:每週一 9am 印出 open issue triage report |
+
+---
+
+細節（touchpoints、mode、assumptions、risk）與 § Anti-patterns 見 [docs/workflows.md](https://github.com/PsychQuant/issue-driven-development/blob/main/docs/workflows.md)。

docs/workflows.md

@@ -427,6 +427,74 @@ idd-edit comment:NNN --append --body "..."
 
 ---
 
+## Path Flowchart（wiki source，#276 Phase 2）
+
+> 本節的 mermaid 是 **wiki [Path Map](https://github.com/PsychQuant/issue-driven-development/wiki/Path-Map) 頁的 single source** — `scripts/generate-path-map.py` 把它與上方 catalog 一起渲染成 `docs/wiki/Path-Map.md`，wiki 同步逐字複製該檔。改這裡，跑 generator，別直接改 wiki。drift-guard：`path-map-sync`（freshness + 36 條 path 全覆蓋 + README 連結）。主幹忠實鏡像 § Path Selection Decision Tree；不在主幹上的 family 以 legend 群組列出。
+
+```mermaid
+flowchart TD
+    START(["你正要做什麼？"]) --> Q1{"single issue<br/>還是 multi？"}
+
+    Q1 -->|single| QM{"type=meeting？"}
+    QM -->|yes| A5["P-meeting<br/>（複雜度評估前分流）"]
+    QM -->|no| Q2{"Complexity？<br/>（硬閘：≥5 檔互依概念或<br/>shared abstraction → MUST Plan）"}
+    Q2 -->|Simple| Q3{"attended？<br/>（你在 keyboard）"}
+    Q3 -->|yes| A1["P-atomic（5 touchpoints）"]
+    Q3 -->|no| QD{"已有 diagnosis？"}
+    QD -->|yes| B1["P-auto-from-diagnosed"]
+    QD -->|no| B2["P-auto-full-swallow"]
+    Q2 -->|Plan| A2["P-plan-gated<br/>（EnterPlanMode 審批）"]
+    Q2 -->|Spectra| Q4{"方向已明確？<br/>（零 open questions）"}
+    Q4 -->|yes（罕用）| A4["P-spectra-opt-out"]
+    Q4 -->|no（預設）| A3["P-spectra-discuss-first"]
+
+    Q1 -->|multi| Q5{"issues 之間的關係？"}
+    Q5 -->|同根 cluster| B4["P-batch-diagnose → P-cluster-pr"]
+    Q5 -->|ripple：1 root + auto-emerge| B5["P-chain-from-root"]
+    Q5 -->|forest：N roots 獨立| B6["P-chain-multi-root<br/>（或 N × P-atomic）"]
+    Q5 -->|unrelated backlog drain| B3["P-batch-drain<br/>（conflict-class ordered）"]
+    Q5 -->|source-driven（一份來源 ≥2 findings）| D1["P-multi-finding<br/>（強制單線 → P-no-multi-finding）"]
+
+    subgraph C["C. Batch（N issues 各自 atomic，無共用 PR）"]
+        C2["P-batch-comment"]
+        C3["P-batch-update"]
+        C4["P-batch-edit"]
+        C5["P-batch-close"]
+    end
+
+    subgraph E["E. Verify-only / PR review"]
+        E1["P-pr-verify"]
+        E2["P-verify-file-profile（非 code deliverable）"]
+        E3["P-pr-verify-then-merge"]
+    end
+
+    subgraph F["F. Resume / 中斷恢復"]
+        F1["P-spectra-resume"]
+        F2["P-implement-retry"]
+    end
+
+    subgraph G["G. Non-lifecycle / ancillary"]
+        G1["P-list-triage"]
+        G2["P-route-recommend"]
+        G3["P-comment-only"]
+        G4["P-edit-only"]
+        G5["P-discussions-intake"]
+        G6["P-clarify-audit"]
+        G7["P-find-lookup"]
+        G8["P-ask-history"]
+        G9["P-report-rollup"]
+        G10["P-config-maintain"]
+    end
+
+    subgraph H["H. Autopilot（no human-in-loop）"]
+        H1["P-loop-autopilot"]
+        H2["P-cron-autopilot"]
+        H3["P-cron-list-triage"]
+    end
+```
+
+---
+
 ## Path × Skill Matrix
 
 | Skill | A:atomic | A:plan | A:spectra | B:auto | B:cluster | B:chain | C:batch | D:multi-finding | E:pr-verify | F:resume | G:non-lifecycle | H:autopilot |

plugins/issue-driven-dev/README.md

@@ -53,6 +53,8 @@ idd-issue → idd-diagnose → idd-implement → idd-verify → idd-close
     ①            ②              ③              ④            ⑤
 ```
 
+> 上圖是最常見的 P-atomic 主幹。完整 **36 條 sanctioned path** 的選擇導航（何時走 Plan / Spectra / cluster / chain / batch…）見 wiki **[Path Map](https://github.com/PsychQuant/issue-driven-development/wiki/Path-Map)**（流程圖 + 分類表；source = `docs/workflows.md`，generator 防 drift，#276）。
+
 | Skill | Purpose |
 |-------|---------|
 | `idd-issue` | Create well-documented GitHub Issue with original quotes and images |

plugins/issue-driven-dev/scripts/tests/path-map-sync/test.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# test.sh — drift-guard for the Path Map wiki pipeline (#276 Phase 2).
+#
+# CONTRACT: docs/workflows.md is the single source (its `## Path Flowchart`
+# mermaid block + the `#### P-` catalog); scripts/generate-path-map.py renders
+# the committed wiki-source page docs/wiki/Path-Map.md deterministically; the
+# wiki sync copies that file verbatim. Three invariants keep the navigation
+# map from silently rotting (the #122/#267 drift class, third instance):
+#   1. FRESHNESS — regenerating must reproduce the committed page byte-for-byte
+#   2. COVERAGE  — every P- name in the catalog appears in the mermaid block
+#                  AND in the generated page (a new path that skips the map
+#                  goes red here, not unnoticed)
+#   3. DISCOVERY — README points at the wiki page
+#
+# Usage: bash test.sh   (exit 0 = all pass, 1 = any fail)
+
+set -u
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$HERE/../../.."
+REPO_ROOT="$PLUGIN_ROOT/../.."
+WORKFLOWS="$REPO_ROOT/docs/workflows.md"
+GEN="$REPO_ROOT/scripts/generate-path-map.py"
+PAGE="$REPO_ROOT/docs/wiki/Path-Map.md"
+README="$PLUGIN_ROOT/README.md"
+
+HELPERS="$HERE/../../lib/assert-helpers.sh"
+[ -f "$HELPERS" ] || { echo "✗ missing $HELPERS — cannot run suite" >&2; exit 1; }
+. "$HELPERS"
+
+assert_file_exists "docs/workflows.md exists" "$WORKFLOWS"
+assert_file_exists "generator exists" "$GEN"
+assert_file_exists "committed wiki-source page exists" "$PAGE"
+
+# ── source section present ──
+assert_output_grep "workflows.md has the Path Flowchart section" "## Path Flowchart" "$WORKFLOWS"
+assert_output_grep "flowchart section carries a mermaid fence"   '```mermaid'         "$WORKFLOWS"
+
+# ── invariant 1: freshness (generator --check diffs against committed page) ──
+OUT=$(python3 "$GEN" --check 2>&1); RC=$?
+if [ "$RC" -eq 0 ]; then
+  pass "Path-Map.md is fresh (generator --check clean)"
+else
+  fail "Path-Map.md is fresh (generator --check clean)" "$OUT"
+fi
+
+# ── invariant 2: coverage — every catalog P- name in mermaid block AND page ──
+MERMAID=$(awk '/^## Path Flowchart/{f=1} f && /^```mermaid/{m=1; next} m && /^```/{exit} m' "$WORKFLOWS")
+MISS_M=""; MISS_P=""
+while IFS= read -r NAME; do
+  case "$MERMAID" in *"$NAME"*) : ;; *) MISS_M="$MISS_M $NAME" ;; esac
+  grep -qF -- "$NAME" "$PAGE" || MISS_P="$MISS_P $NAME"
+done < <(grep -oE '^#### (P-[a-z0-9-]+)' "$WORKFLOWS" | sed 's/^#### //' | sort -u)
+if [ -z "$MISS_M" ]; then
+  pass "every catalog path appears in the mermaid flowchart"
+else
+  fail "every catalog path appears in the mermaid flowchart" "missing:$MISS_M"
+fi
+if [ -z "$MISS_P" ]; then
+  pass "every catalog path appears in Path-Map.md"
+else
+  fail "every catalog path appears in Path-Map.md" "missing:$MISS_P"
+fi
+
+# ── invariant 3: discovery ──
+assert_output_grep "README links to the wiki Path Map" "wiki/Path-Map" "$README"
+
+print_summary "path-map-sync"