@adamchanadam/cer-workflow 0.3.17

package/skills/cer-workflow/references/parallel-producers.md

@@ -0,0 +1,159 @@
+# 平行候選生產者
+
+<!-- cer-parallel-producers-owner -->
+
+本檔是 CER 平行候選生產者的唯一完整規則 owner。它規定 C 如何按需使用
+inline、非正式能力，同時保持正式角色、唯一 writer、fresh Reviewer、來源裁決
+及停止邊界不變。
+
+## 目錄
+
+- [定位與角色邊界](#定位與角色邊界)
+- [使用者操作保持簡單](#使用者操作保持簡單)
+- [啟動資格](#啟動資格)
+- [Lane 凍結契約](#lane-凍結契約)
+- [模式與寫入邊界](#模式與寫入邊界)
+- [Scratch root 機械邊界](#scratch-root-機械邊界)
+- [候選回傳](#候選回傳)
+- [C 的讀回、裁決與合流](#c-的讀回裁決與合流)
+- [失敗、漂移與生命週期](#失敗漂移與生命週期)
+- [禁止事項](#禁止事項)
+
+## 定位與角色邊界
+
+- CER 正式角色只有 C、E1、R、E2。平行候選生產者不是第五角色，不使用正式
+  title、cycle、ready、result、batch lifecycle 或 Reviewer 身份。
+- 生產者是 C 的 inline、非正式、按需候選能力。不得新增 slash command、
+  lock、registry、run id、常駐模式或背景服務。
+- 生產者不代替 E1 寫入正式 project，不代替 R 獨立反證，也不直接與 E1、E2
+  或 R 通訊。
+- 正式 project writer 仍只有 E1。只有既有接管條件成立後，才可改由 E2；
+  任何 producer、C 或 R 都不得成為平行 project writer。
+
+## 使用者操作保持簡單
+
+正常 CER 使用只保留既有明示觸發與五個操作指令。使用者無須設定 producer、
+lane、scratch root、hash、角色或額外審閱程序，也無須學習「平行候選生產者」
+詞彙。C 在內部判斷是否值得平行、分配及驗證隔離位置；不值得或不可證明安全時
+自動使用零名 producer 並回到串行分析。對使用者只報告會影響結果的成果、未知、
+阻礙或風險，不展示內部 lane 儀式。
+
+## 啟動資格
+
+C 只有在以下條件全部成立時，才可啟動兩條或以上的平行 lane：
+
+1. 至少兩條工作線互不依賴，不需要彼此結果、共享可變狀態或固定執行次序。
+2. 每條 lane 的輸入及來源身份已凍結。
+3. C 同期有不重複的關鍵分析、守門或裁決工作，不退化為候選整理員。
+4. 每條候選可由 C 按權威來源獨立驗證。
+5. 預期淨省時明顯高於啟動、讀回、hash、去重及裁決成本。
+6. 所需平行槽可用，且不會壓縮正式 E1 或 fresh R 的必要能力。
+
+任一條不成立、不可判定，或一次有界讀取已足夠時，`producer_count=0`，C 串行
+完成分析。這是正常 auto-idle，不是降級、錯誤或需要使用者設定的模式。
+
+## Lane 凍結契約
+
+C 在每條 lane 啟動前凍結以下完整內容：
+
+- `lane_label`：只供本次候選辨識，不是正式角色或 run id。
+- `mode`：只能是 `read_only` 或 `isolated_artifact`。
+- 單一目標。
+- 輸入身份與版本、來源身份及可核實座標。
+- 允許範圍與禁止範圍。
+- 預期候選輸出。
+- 驗收方式。
+- 停止條件。
+- `isolated_artifact` 另須有 C 明確提供並已通過機械邊界檢查的 lane 專屬
+  `scratch_root`。
+
+未凍結、互相矛盾或中途被 producer 改寫的 lane 不啟動或立即失效。生產者不得
+自行擴張目標、來源、權限、輸出或驗收。
+
+## 模式與寫入邊界
+
+### `read_only`
+
+- 在任何位置都必須零寫入，包括 project、scratch、暫存、外部系統及 producer
+  自己可見的 workspace。
+- 只可讀取 C 指定的輸入與來源，並回傳文字候選。
+
+### `isolated_artifact`
+
+- 只可寫入 C 明確提供、lane 專屬、task-owned 的 `scratch_root`。
+- 不得寫 target project、正式真源、另一 lane、使用者根目錄、系統位置、
+  外部服務或任何未列目標。
+- artifact 是候選，不是正式 project 成果。它只能由 C 讀回、重算 hash 及合流；
+  不得由 producer 直接交給 E1 或 R 採用。
+
+## Scratch root 機械邊界
+
+C 必須在啟動 artifact lane 前解析實際絕對路徑，並逐項證明：
+
+1. `scratch_root` 與 target project 互不包含，兩者都不是另一方的祖先。
+2. `scratch_root` 不是磁碟根、使用者根、系統根或其等價高風險根。
+3. 現存路徑鏈不含 symlink、junction、Windows reparse point、mount 或其他會把
+   寫入導向未核實位置的連結。
+4. 每條 lane root 彼此不相等、互不為祖先，且不與正式真源、其他 lane 或外部
+   系統重疊。
+5. 實際工具權限只容許該 lane 的明示 root；不能以相對路徑、萬用字元、環境
+   fallback 或 producer 自選位置擴張。
+
+任一項不能證明即不啟動該 lane。不得退回 project 內 staging、共享 scratch、
+使用者根或其他較危險位置。
+
+## 候選回傳
+
+每條自然到達的候選至少包含：
+
+- `lane_label`。
+- 凍結的輸入身份。
+- 實際來源座標。
+- `claims`：可由來源逐項核實的候選主張。
+- `unknowns`：缺失、矛盾、未核實或受限制部分。
+
+`isolated_artifact` 另須列每個 artifact 的實際絕對路徑與 SHA-256。回傳不是正式
+CER ready/result，不使用正式 batch 身份，也不構成接納、進度或 Reviewer 證據。
+
+## C 的讀回、裁決與合流
+
+- C 親自讀回支撐關鍵主張的來源與 artifact，不以 producer 摘要代替。
+- C 對每個 artifact 重算 SHA-256，並核對路徑仍在已驗 scratch root、輸入身份
+  未漂移、來源座標可重播。
+- 來源或候選衝突時，C 按使用者裁決、專案真源及任務所需權威來源判斷；不得
+  投票、按數量、完成先後或相同答案接納。
+- C 只合流仍在本次 intake 邊界內、來源與 hash 未漂移、可獨立驗證的部分。
+- 只有 C 完成讀回、去重、衝突裁決及合流後，才可形成給 E1 的正式自足 batch。
+  E1 只接收該 C 合流批次，不得直接使用 producer 原始通訊、lane 摘要或未合流
+  scratch artifact。
+- R 仍從凍結原始證據獨立反證；producer 候選不能冒充 fresh R 證據。
+
+## 失敗、漂移與生命週期
+
+- C 不 wait、poll 或背景監察 producer，只採用自然到達且仍在 intake 邊界內的
+  候選。
+- 遲到候選在 intake 已關閉、正式 batch 已凍結、`CER-stop` 或 `CER-close`
+  開始後失效；不得重開已裁決批次。
+- 輸入或來源漂移時，只淘汰依賴該身份的 lane；未受影響 lane 不重跑。
+- artifact 路徑越界、hash drift、tamper、來源不可重播或 lane 合約漂移時，該
+  候選 fail closed 並不得合流。
+- producer 建立失敗、沒有 subagent 能力、逾時、自然沒有回傳或候選不可驗證時，
+  C 回到一般串行分析，不重複相同失敗。只有缺失證據本身是任務 blocker 時，
+  CER 才因證據缺口受阻。
+- `/CER-stop` 與 `/CER-close` 不等待 producer。C 停止採用新候選，讓遲到內容
+  失效，並依正式 E1／R 生命週期完成停用或收尾。
+
+## 禁止事項
+
+- producer 冒充 C、E1、R、E2 或 fresh Reviewer。
+- producer 使用正式 title、cycle、ready、result、slash、lock、registry 或
+  run id。
+- C、R 或 producer 寫入 target project；E1 以外出現共享 workspace writer。
+- `read_only` 產生任何寫入。
+- `isolated_artifact` 寫出已驗 lane root，或使用 project 內／祖先、磁碟根、
+  使用者根、系統根、link、junction、reparse point、mount 或重疊 lane。
+- producer 直接向 E1／E2／R 傳送候選，或 E1 採用未經 C 合流的 scratch。
+- 以 producer 數量、票數、速度或一致答案代替 C 的權威來源裁決。
+- 為了 producer 要求使用者設定 lane、scratch、hash、角色、審閱程序或新增指令。
+- 為等候 producer 而輪詢、背景監察、延遲 stop／close，或採用已遲到、漂移、
+  tamper、越界的候選。

package/skills/cer-workflow/references/roadmap.md

@@ -0,0 +1,182 @@
+# 使用者停點與路線圖
+
+## 目錄
+
+- [兩種介面](#兩種介面)
+- [Inline visualizer 標準時機](#inline-visualizer-標準時機)
+- [固定生命週期卡](#固定生命週期卡)
+- [其他固定停點卡](#其他固定停點卡)
+- [小熊卡使用時機](#小熊卡使用時機)
+- [顯示優先序](#顯示優先序)
+- [角色顯示邊界](#角色顯示邊界)
+- [路線圖真源](#路線圖真源)
+
+## 兩種介面
+
+- **Inline visualizer 路線圖**是長期、多階段、多批次，或需要首次公開對齊的 CER
+  任務的標準進度面，
+  不要求使用者每次介入。版面、階段數和附加欄位按項目需要動態決定，不使用
+  固定四格或固定表格代替實際任務資訊；最低內容依「顯示優先序」。需要收斂的
+  任務同時顯示活的任務簡報、本批凍結和下一個可觀察停點。
+- **ASCII 小熊四色卡**是 checkpoint 訊號，只回答「現在是否需要使用者預覽、決定、
+  處理阻礙或驗收」。它不代替路線圖，也不作持續進度表。
+
+同一訊息可同時有兩者，但內容不重複：路線圖顯示全局位置，卡片只說明本次停點。
+
+## Inline visualizer 標準時機
+
+1. C 判定任務會跨多階段或多批次，或屬新產品、流程、設計、內容、體驗型成果而
+   需要首次公開對齊時，在第一個實際批次前顯示初始路線圖；內容包括活的任務簡報、
+   本批凍結、下一個預覽或裁決點。
+2. C 讀回並接納一批成果，而且某項使用者完成條件取得成果差異，或必要診斷改變下一承接路徑時，更新路線圖。
+3. 使用者裁決、實際新限制或 R 的反證令方向／範圍／交付形狀、風險或接納狀態
+   實質改變時，先顯示與上一版的差異，再更新路線圖。
+4. 階段交付、技術驗收、用途校正或收工時，顯示相應終態。
+
+普通內部讀檔、E1 子步驟、輪詢結果、未經 C 裁決的候選、審閱完成、格式通過、
+檔案一致、問題記錄、設計完成，以及沒有改變使用者完成條件的細節，不更新
+路線圖。進度只來自 direct-push 後的有界讀回、C 裁決及 `outcome_anchor` 的已接納成果差異。
+
+## 固定生命週期卡
+
+每次顯示任何 lifecycle 或 checkpoint 小熊卡前，重新讀取本 Skill 根目錄
+`VERSION`。穩定 semver `X.Y.Z` 顯示為 `vX.Y.Z`；缺失、不可讀或格式錯誤時
+顯示 `version unverified`。以下卡片中的 `{package_version}` 是模板佔位；
+輸出前必須以當次讀到的 `VERSION` 完整替換，絕不可把佔位文字原樣顯示。
+每張卡必須作為獨立 fenced `text` code block 輸出；不得放入 bullet、引用、
+普通段落或與其他文字同一個 Markdown 區塊。
+
+```text
+   ()_()   CER 工作法 v{package_version}
+  ( o.o )  🔵 CER 已啟動
+   ( ^ )
+```
+
+每次成功接受 `CER-start` 都使用以上固定開眼啟動卡，包括簡單單批任務。啟動
+卡保留完整三行 ASCII 小熊；版本在第一行，狀態在第二行，第三行只保留小熊底線。
+
+成功 `/CER-stop` 使用固定閉眼停用卡：
+
+```text
+   ()_()   CER 工作法 v{package_version}
+  ( -.- )  ⚪ CER 已停用 · CER inactive
+   ( ^ )
+```
+
+成功 `/CER-close` 使用固定閉眼收尾卡：
+
+```text
+   ()_()   CER 工作法 v{package_version}
+  ( -.- )  🟢 CER 已收尾 · writer closed
+   ( ^ )
+```
+
+閉眼卡是已驗證終態，不是意圖回執。停用卡只可在沒有 active writer 或 writer
+已停止且必要讀回完成後顯示；收尾卡只可在 `writer closed`、必要讀回，以及該輪
+可核實 C／E／R title 的 cycle 編號加 `✓` 或 `title sync warning` 已讀回後顯示。
+閉眼收尾卡只代表 writer close／必要讀回完成，不代表 title sync 全綠。任一證據不足時使用開眼紅色 blocker 卡：
+
+```text
+   ()_()   CER 工作法 v{package_version}
+  ( o.o )  🔴 重大阻礙 · checkpoint blocked
+   ( ^ )
+```
+
+## 其他固定停點卡
+
+生命週期卡以外的停點沿用開眼 ASCII 小熊，同樣使用獨立 fenced `text` code
+block；版本在第一行，狀態按場景替換在第二行。若版本無效，同樣顯示
+`version unverified`。
+
+- `🟡 方向抉擇`
+- `🔴 重大阻礙`
+- `🟢 階段性交付／最終驗收`
+
+## 小熊卡使用時機
+
+CER 是連續閉環，不代表每個小步都發卡：
+
+1. 每次成功接受 `CER-start`，先用一次固定 `🔵 CER 已啟動` 卡作啟動回執；
+   單批也必須顯示。長期／多批次或需要首次公開對齊的任務，由同訊息 inline
+   路線圖承載完整階段資訊。
+2. 重大方向、範圍、交付形狀、成本、知識來源或驗收標準需要使用者取捨時，
+   用 `🟡 方向抉擇`。
+3. 通訊鏈、threadId 或平台等價座標、權限、真源、知識底座、平台能力或安全條件
+   不足，不能可靠繼續時，用 `🔴 重大阻礙`。
+4. E1 完成可觀察階段、C 已讀回裁決，或 R 完成高風險反證後形成使用者可驗收
+   成果時，用
+   `🟢 階段性交付`。
+5. 成功 `/CER-stop` 顯示固定閉眼 `⚪ CER 已停用` 卡；成功 `/CER-close` 顯示
+   固定閉眼 `🟢 CER 已收尾` 卡。一般最終驗收仍可用開眼
+   `🟢 最終驗收`，不得冒充生命週期終態。
+
+普通內部讀檔、低風險小修、E1 子步驟、普通批次接納、R 完成但沒有形成用戶
+停點，以及已清楚不需使用者介入的下一步不發卡；需要時只更新 inline 路線圖。
+
+## 顯示優先序
+
+Inline 路線圖最少顯示：可驗收終點；有次序的階段及已完成／目前／待辦狀態；
+整體進度；目前動作及已核實證據或 blocker；C／E1／R 狀態；下一停點；知識性
+任務才加知識底座狀態。首次公開對齊另顯示範圍／排除、關鍵假設、最小可觀察
+成果、技術驗收與用途校正是否適用，以及是否需要使用者決定。需要收斂的任務
+加上活的任務簡報：已確認要求／排除、可安全推定、關鍵缺口、最新回饋、
+本批凍結、下一個預覽或裁決點，以及與上一版相比改變了甚麼。停點卡只把當前
+情況壓成「預覽、決定、停下或驗收」。
+兩者都只派生自既有 project plan／progress 或已核實執行狀態，不是第二套計劃
+或進度。
+任何用戶可見的活的任務簡報都必須明示 `CER`，並保留 C／E1／R 或
+Controller／Executor／Reviewer 語境；不得以「Codex 任務簡報」、「Goal plan」、
+「assistant plan」或無品牌的內部功能樣式呈現。
+活的任務簡報也只由最高可用權威來源與 C 已裁決事實派生。
+長期多批任務還要顯示 `outcome_anchor` 的未完成條件、已接納成果差異、診斷／
+機制改善是否只屬非主線，以及下一批如何承接完成條件；不得以批次、task 或審閱
+數量代替成果進度。
+
+1. Codex 有可調用的 in-conversation visualization 能力時，預設建立 inline HTML visualization，並使用該能力要求的正式呈現指令，例如 `::codex-inline-vis{file="..."}`。
+2. Mermaid 不算完成第一層要求。只有 inline visualization 能力不存在、不可調用、不可寫入其指定視覺目錄，或實際呈現失敗時，才使用 Mermaid。
+3. Mermaid 也不可用時，才使用固定 Markdown／純文字。
+4. 降級時用一句話明示原因；不可靜默降級，也不可因視覺能力缺失阻塞項目。
+
+純文字 fallback：
+
+```text
+CER 路線圖｜活簡報
+CER 目標：<終點>
+CER 範圍／排除：<本次會做／不做>
+CER 假設：<已確認／安全推定／需要裁決>
+CER 活簡報：已確認=<...>｜安全推定=<...>｜待裁決=<...>
+CER 成果錨：未完成=<完成條件>｜已接納差異=<成果差異／無>
+CER 本批凍結：<只本批會做>
+CER 工作線：<mainline_outcome／diagnostic／mechanism_improvement／governance_self_improvement>
+CER 上次回饋／變更：<...／無>
+[公開對齊：<已確認／安全推定／需要裁決>]
+[✓] 已完成 → [● 現在] 當前階段 → [○] 後續階段 → [○] 最終交付／收工
+目前：<一句>
+最小可觀察成果：<下一次你會看見>
+驗收：技術驗收=<條件／不適用>；用途校正=<條件／不適用>
+下一停點：<一句>
+知識底座：<已確認／缺來源／不適用>
+CER 角色：C=<狀態>｜E1=<狀態>｜R=<未建立／驗收中／完成>
+```
+
+## 角色顯示邊界
+
+路線圖與生命週期卡只顯示正式 C、E1、R，以及接管時的 E2。平行候選生產者是
+C 的內部按需能力，不加入角色欄、生命週期卡、使用者設定或獨立進度；只有其
+缺失證據成為實質 blocker 時，才用一般風險語言呈現結果。
+
+## 路線圖真源
+
+只用最高可用權威來源，不建立第二份進度；活的任務簡報與 `outcome_anchor` 也只由最高可用權威來源
+和 C 已裁決的本輪事實派生，不是第二套計劃、固定文件或新 workflow：
+
+1. 目標專案已有權威進度／Roadmap 時，由它派生。
+2. 只有已確認計劃而未有進度來源時，由計劃加已核實執行狀態暫態派生。
+3. 未有計劃時，由使用者本次需求與已核實角色／阻礙事實暫態派生，標示「初始／待收斂」。
+
+若同時使用 `$project-context-workflow`，只讀取其已確認計劃與進度，不重做五步或
+建立第二道相同共識關卡。
+
+普通工程細節不發卡。方向或交付形狀取捨用 🟡；可靠性 blocker 用開眼 🔴；
+可觀察階段成果與一般最終驗收用開眼 🟢。只有已證明終態的 stop／close 使用
+閉眼卡。普通批次狀態不發卡；只有符合成果錨進展閘門時，才更新 inline 路線圖。