docs: sharpen multi-repository positioning

README.md

@@ -8,15 +8,13 @@
 
 Repository: [libaie/onboard-code-projects](https://github.com/libaie/onboard-code-projects)
 
-onboard-code-projects is a Windows-first Codex Desktop multi-repository workflow-isolation Skill.
+`onboard-code-projects` is the Codex Desktop multi-repository workflow-isolation Skill that reduces context pollution with verified, reusable project tasks and `codebase-memory` indexes, plus an optional controller for cross-project coordination and evidence-backed reuse of accepted successes and deterministic failures.
 
 - **Use when:** work crosses two or more related repositories.
 - **You get:** exact-root, verified project-bound entry tasks, a `codebase-memory` index for each repository, and an optional controller for cross-project coordination.
 - **It does not:** create saved Codex projects or approve permissions.
 - **It is not:** a security sandbox, and it does not deploy software.
 
-This reduces the risk of repository instructions, branches, permissions, evidence, and edits being mixed in one long conversation.
-
 > **Preview:** Windows and Codex Desktop are the supported release surface. Other platforms are not yet release-tested end to end.
 
 ## Problems this Skill solves
@@ -43,23 +41,117 @@ Project entry tasks may still use subagents internally; the two approaches are c
 
 ## What you get
 
-```mermaid
-flowchart LR
-    U["User"] --> A["Project A entry task"]
-    U --> B["Project B entry task"]
-    U -.->|optional cross-project work| C["Controller"]
-    C --> A
-    C --> B
-    A --> RA["Repository A + index"]
-    B --> RB["Repository B + index"]
-```
-
 - For each source: one verified saved-project binding, one reusable local entry task, and one `codebase-memory` index.
 - Optionally: one controller directory and controller task outside every business repository.
 - Optionally: durable result return when the plugin Stop Hook and Node.js are available; automatic wake additionally requires validated rule, worker, and automation capabilities.
 
 The Skill cannot create a saved Codex project. Add each exact directory in Codex Desktop first; the Skill verifies and uses that identity.
 
+## Core workflows
+
+The four flows below cover the public lifecycle. Exact payloads, hashes, reason codes, and recovery commands remain in the [controller runtime reference](./references/controller-runtime.md).
+
+### 1. Onboard or reuse each repository
+
+```mermaid
+flowchart TD
+    O1["Local paths or Git URLs"] --> O2["Load or confirm the saved index mode, then parse inputs and run read-only preflight"]
+    O2 --> O3{"Source type?"}
+    O3 -->|Local directory| O7{"One exact saved project on this host?"}
+    O3 -->|Git URL| O4["Clone only into a new cloneRoot child"]
+    O4 --> O5["Return needs-project-add"]
+    O5 --> O6["User saves the exact clone and reruns"]
+    O6 --> O7
+    O7 -->|No or ambiguous| O8["Block with a precise next action"]
+    O7 -->|Yes| O9["Read AGENTS and verify root, branch, HEAD, and dirty state"]
+    O9 --> O10["Create or reuse one project-bound entry task"]
+    O10 --> O11["Build or refresh the selected codebase-memory index"]
+    O11 --> O12["Verify index root and revision"]
+    O12 --> O13["Repository lane ready for direct work"]
+    O13 -.->|Optional cross-project work| O14["Verify or initialize an external controller and register this entry"]
+    O14 -.->|Controller unavailable or creation result unknown| O15["Keep ready repositories; report pending registration or reconcile evidence without retrying"]
+```
+
+Saved projects stay user-owned. The Skill creates neither projectless tasks nor worktrees, and the optional controller must remain outside every business repository.
+
+### 2. Coordinate, dispatch, and accept cross-project work
+
+```mermaid
+flowchart TD
+    D1["Cross-project request"] --> D2["Four-quadrant intake; freeze objective, contract, scope, and acceptance"]
+    D2 --> D3["Queue work by project"]
+    D3 -->|Same project runs one active task in FIFO order| D4
+    D3 -->|Independent projects run in parallel| D4
+    D4["Seal the dispatch and select the model class by complexity and risk"] --> D5["Send only to the verified project entry task"]
+    D5 -.->|Timeout or empty delivery| D15["Stop or hold only this lane; never resend blindly or expand authority"]
+    D5 -->|Delivered| D6["Re-read AGENTS and verify root, baseline, and scope"]
+    D6 --> D7{"Runtime approval required?"}
+    D7 -->|Yes| D8["Only this project waits; other lanes continue"]
+    D7 -->|No| D9["Implement and test inside the repository"]
+    D8 -->|Approved| D9
+    D8 -.->|Declined| D15
+    D9 --> D10{"Available return channel?"}
+    D10 -->|Hook receipt, with optional wake| D11["Controller re-reads branch, HEAD, diff, tests, and contract; wake is not acceptance"]
+    D10 -->|native-callback| D11
+    D10 -->|foreground| D11
+    D11 --> D12{"Result and evidence disposition?"}
+    D12 -->|accepted success| D13["Record success, release the lease, and start the next FIFO item"]
+    D12 -->|Eligible business or review failure| D14["Keep the lease and enter the bounded convergence flow below"]
+    D12 -->|Cancelled, declined, or non-retryable blocked| D15
+```
+
+The controller writes governance state only. Repository edits and tests remain in the exact project entry task; a callback or receipt only signals that evidence is ready to inspect.
+
+### 3. Reuse evidence-backed experience and stop retry loops
+
+```mermaid
+flowchart TD
+    E1["Canonical goal logs and curated evidence-bound imports"] --> E2["ExperienceRead verifies the bounded experience index"]
+    E2 --> E3["Match problem, strategy family, and material conditions"]
+    E3 --> E4{"Prior verified outcome?"}
+    E4 -->|accepted success| E5["Reuse the proven strategy, then recheck current readiness"]
+    E4 -->|deterministic failure: reject the same mechanism| E6["Reserve the next allowed strategy"]
+    E4 -->|No match or proved material change| E6
+    E5 --> E7["Execute, test, and collect current evidence"]
+    E6 --> E7
+    E7 --> E8{"Reviewed outcome?"}
+    E8 -->|accepted success| E9["Store reusable success in the bounded index and close the lane"]
+    E8 -->|deterministic failure| E10["Store the hard failure in the bounded index"]
+    E8 -->|Transient, environment, superseded, cancelled, or authorization result| E11["Audit only; do not blacklist; cancellation or declined authorization stops the lane"]
+    E10 --> E12{"Which business attempt failed?"}
+    E11 -.->|Eligible environment change or supersession| E12
+    E12 -->|Initial| E13["Run one comprehensive repair"]
+    E12 -->|Repair| E14["Run one whole-goal rebaseline"]
+    E12 -->|Rebaseline| E15["convergence-failed: stop for a user decision"]
+    E13 --> E2
+    E14 --> E2
+```
+
+This is evidence reuse, not automatic learning. A changed material condition needs direct canonical evidence; renaming a task, opening a new conversation, or changing an unproved hash cannot erase a known deterministic failure. Only a zero-repository-write transport, tool-bootstrap, or payload-parse failure may receive one same-attempt preflight replay.
+
+### 4. Refresh a long-lived controller task set
+
+```mermaid
+flowchart TD
+    R1["Explicit reset request from an external coordinator"] --> R2{"Exact generated v3, task APIs, Node.js, single roots, and quiet state?"}
+    R2 -->|No| R3["Block without changing or deleting tasks"]
+    R2 -->|Yes| R4["Read-only Plan returns planHash"]
+    R4 --> R5["Separately authorized Apply uses the exact planHash"]
+    R5 --> R6["Re-read complete history, quiet state, and active work; prepare the runtime fence"]
+    R6 --> R7["Create bootstrap-only standby tasks exactly once; projects first, controller last"]
+    R7 --> R8["Read, sanitize, bound, and hash every old task history"]
+    R8 --> R9["Archive old project tasks, then the old controller, with readback"]
+    R9 --> R10{"Did archived history change?"}
+    R10 -->|Yes| R11["Re-read and rebuild the complete final handoff"]
+    R10 -->|No| R12["Persist and send the bounded handoff; verify standby acknowledgements"]
+    R11 --> R12
+    R12 --> R13["Atomically switch the whole task set; commit and read back runtime state"]
+    R13 --> R14["Seal, recover, and unfreeze; retain the same heartbeat"]
+    R14 --> R15["New tasks inherit canonical state; old tasks stay archived; coordinator archives last"]
+```
+
+Apply is forward-only. An interruption keeps the set frozen and resumes the same operation; it never rolls back, deletes tasks, mutates canonical work records, or retries a task creation whose result is unknown.
+
 ## Quick start
 
 ### 1. Install
@@ -126,7 +218,6 @@ When a controller and its project entry tasks need fresh conversations, exact ge
 ```text
 resetControllerTasks: true
 Action: Plan
-
 # Review the returned planHash, then send the same request with:
 Action: Apply
 planHash: <returned planHash>
@@ -153,18 +244,10 @@ indexMode: full
 
 The Skill clones only into a new child of `cloneRoot` and then returns `needs-project-add`. Save the exact clone as a Codex project and rerun the same request. The existing clone is reused only after its root, credential-free origin, and requested branch or ref are verified.
 
-## How it works
-
-1. Match each source to one exact saved project on the current host.
-2. Verify its task identity, root, Git baseline, dirty state, and `codebase-memory` index.
-3. Keep repository changes and tests in that repository's entry task.
-4. Use the optional controller only for shared contracts, sequencing, dispatch, and end-to-end acceptance.
-5. Validate returned branch, HEAD, diff, tests, contract impact, and remaining risk before accepting a result.
+## Boundaries
 
 This is **workflow isolation**, not a security sandbox. It does not change filesystem permissions, and manually mixing repositories in one task can reintroduce context pollution.
 
-Detailed queue, recovery, convergence, receipt, and controller-state contracts live in [the controller runtime reference](./references/controller-runtime.md), not in this project overview.
-
 ## Inputs
 
 | Field | Required | Meaning |

README.zh-CN.md

@@ -8,15 +8,13 @@
 
 开源仓库：[libaie/onboard-code-projects](https://github.com/libaie/onboard-code-projects)
 
-onboard-code-projects 是 Windows-first 的 Codex Desktop 多仓库工作流隔离 Skill。
+`onboard-code-projects` 是减少 Codex Desktop 多仓库上下文污染的工作流隔离 Skill：为每个仓库建立独立、经过核验且可复用的项目任务和 `codebase-memory` 索引，并通过可选中控协调跨项目工作、沉淀并复用有证据支撑的成功与确定性失败经验。
 
 - **适用于：** 工作横跨两个及以上仓库。
 - **你会得到：** 绑定到精确根目录、经过核验的项目入口任务，每个仓库对应一个 `codebase-memory` 索引，以及负责跨项目协作的可选中控。
 - **它不会：** 创建或保存 Codex 项目，也不会代替用户授权或批准权限。
 - **它不是：** 安全沙箱，也不会部署软件。
 
-它解决的核心问题是：多个仓库放在同一个长期会话里，会混淆项目指令、分支、权限、证据和修改范围。
-
 > **状态：预览版。** 当前支持的发布面是 Windows 和 Codex Desktop，其他平台尚未完成发布级端到端验证。
 
 ## 它解决什么痛点
@@ -43,23 +41,117 @@ onboard-code-projects 是 Windows-first 的 Codex Desktop 多仓库工作流隔
 
 ## 你会得到什么
 
-```mermaid
-flowchart LR
-    U["用户"] --> A["项目 A 入口任务"]
-    U --> B["项目 B 入口任务"]
-    U -.->|可选的跨项目工作| C["中控"]
-    C --> A
-    C --> B
-    A --> RA["仓库 A + 索引"]
-    B --> RB["仓库 B + 索引"]
-```
-
 - 每个 source：一个已核验的保存项目绑定、一个可复用的本地入口任务和一个 `codebase-memory` 索引。
 - 可选：位于所有业务仓库之外的一个中控目录和中控任务。
 - 可选：耐久结果回传需要插件 Stop Hook 与 Node.js；自动唤醒还需要额外的规则、worker 和自动化能力。
 
 Skill 不能创建 Codex 已保存项目。用户需先在 Codex Desktop 中添加每个精确目录，Skill 再核验并使用该身份。
 
+## 核心流程
+
+下面四张图覆盖对用户可见的完整生命周期。精确 payload、哈希、reason code 和恢复命令仍放在[中控运行时参考](./references/controller-runtime.md)中。
+
+### 1. 接入或复用每个仓库
+
+```mermaid
+flowchart TD
+    O1["本地路径或 Git URL"] --> O2["加载或确认已保存的索引模式，再解析输入并执行只读依赖预检"]
+    O2 --> O3{"source 类型？"}
+    O3 -->|本地目录| O7{"当前主机上是否存在唯一精确的已保存项目？"}
+    O3 -->|Git URL| O4["只克隆到 cloneRoot 的新子目录"]
+    O4 --> O5["返回 needs-project-add"]
+    O5 --> O6["用户保存精确克隆目录后重跑"]
+    O6 --> O7
+    O7 -->|不存在或有歧义| O8["阻断并返回明确的下一步"]
+    O7 -->|是| O9["读取 AGENTS，核验根目录、分支、HEAD 和脏工作区"]
+    O9 --> O10["创建或复用一个项目绑定入口任务"]
+    O10 --> O11["按所选模式建立或刷新 codebase-memory 索引"]
+    O11 --> O12["核验索引根目录与版本"]
+    O12 --> O13["仓库通道就绪，可直接工作"]
+    O13 -.->|可选跨项目工作| O14["核验或初始化仓库外中控，并登记该入口"]
+    O14 -.->|中控不可用或创建结果未知| O15["保持已就绪仓库；报告待登记状态，或根据权威证据恢复且不重试"]
+```
+
+Codex 已保存项目仍由用户管理。Skill 不创建 projectless 任务或 worktree；可选中控必须位于所有业务仓库之外。
+
+### 2. 协调、派发并验收跨项目工作
+
+```mermaid
+flowchart TD
+    D1["跨项目请求"] --> D2["四象限接收；冻结目标、契约、范围和验收标准"]
+    D2 --> D3["按项目进入队列"]
+    D3 -->|同一项目只运行一个活动任务并按 FIFO 排队| D4
+    D3 -->|独立项目并行执行| D4
+    D4["密封派发包，并按难度与风险选择模型等级"] --> D5["只发送给已核验的项目入口任务"]
+    D5 -.->|超时或空返回| D15["只停止或挂起当前通道；禁止盲目重发或扩大授权"]
+    D5 -->|已送达| D6["重读 AGENTS，核验根目录、基线和范围"]
+    D6 --> D7{"需要运行时授权？"}
+    D7 -->|是| D8["只等待当前项目，其他通道继续"]
+    D7 -->|否| D9["在仓库内实现并测试"]
+    D8 -->|已批准| D9
+    D8 -.->|已拒绝| D15
+    D9 --> D10{"当前可用的回传通道？"}
+    D10 -->|Hook 回执，可选自动唤醒| D11["中控重读分支、HEAD、diff、测试和契约；唤醒不等于验收"]
+    D10 -->|native-callback| D11
+    D10 -->|foreground| D11
+    D11 --> D12{"结果与证据应如何处置？"}
+    D12 -->|已接受的成功| D13["记录成功、释放租约并启动下一个 FIFO 项"]
+    D12 -->|符合条件的业务或评审失败| D14["保留租约并进入下方有界收敛流程"]
+    D12 -->|已取消、拒绝授权或不可重试的阻断| D15
+```
+
+中控只写治理状态。仓库修改和测试始终留在精确项目入口任务中；callback 或 receipt 只表示已有证据可供读取，不代表任务已通过验收。
+
+### 3. 复用有证据支撑的经验并终止重试循环
+
+```mermaid
+flowchart TD
+    E1["规范 goal 日志与绑定证据的人工导入"] --> E2["ExperienceRead 核验有界经验索引"]
+    E2 --> E3["匹配问题、策略族和关键前提"]
+    E3 --> E4{"此前已核验结果？"}
+    E4 -->|已接受的成功| E5["复用已证明策略，并重新核验当前 readiness"]
+    E4 -->|确定性失败：拒绝相同机制| E6["预留下一个允许的策略"]
+    E4 -->|无匹配或已证明关键前提变化| E6
+    E5 --> E7["执行、测试并收集本次证据"]
+    E6 --> E7
+    E7 --> E8{"评审结果？"}
+    E8 -->|已接受的成功| E9["把可复用成功写入有界索引并关闭通道"]
+    E8 -->|确定性失败| E10["把硬失败写入有界索引"]
+    E8 -->|瞬态、环境阻断、被取代、取消或授权结果| E11["只记审计，不拉黑；取消或拒绝授权会终止当前通道"]
+    E10 --> E12{"失败发生在哪次业务尝试？"}
+    E11 -.->|符合条件的环境变化或策略取代| E12
+    E12 -->|初始尝试| E13["执行一次完整修复"]
+    E12 -->|修复尝试| E14["执行一次全目标重新基线"]
+    E12 -->|重新基线| E15["convergence-failed：停止并等待用户决策"]
+    E13 --> E2
+    E14 --> E2
+```
+
+这是证据复用，不是自动学习。关键前提变化必须有直接规范证据；改任务名、新开会话或修改未经证明的哈希，都不能抹掉已知确定性失败。只有仓库零写入的 transport、tool-bootstrap 或 payload-parse 失败，才允许一次不消耗业务尝试的同 attempt 预检重放。
+
+### 4. 刷新长期运行的中控任务组
+
+```mermaid
+flowchart TD
+    R1["由集合外 coordinator 显式请求重置"] --> R2{"精确生成的 v3、任务 API、Node.js、单根目录且状态静默？"}
+    R2 -->|否| R3["不修改也不删除任务，安全阻断"]
+    R2 -->|是| R4["只读 Plan 返回 planHash"]
+    R4 --> R5["单独授权的 Apply 使用精确 planHash"]
+    R5 --> R6["重读完整历史、静默状态与活动工作；准备运行时 fence"]
+    R6 --> R7["仅创建一次 bootstrap 待命任务；项目在前，中控最后"]
+    R7 --> R8["读取、脱敏、限长并哈希每个旧任务的完整历史"]
+    R8 --> R9["先归档旧项目任务，再归档旧中控，并逐一回读"]
+    R9 --> R10{"归档后的历史发生变化？"}
+    R10 -->|是| R11["重新读取并重建完整最终交接"]
+    R10 -->|否| R12["持久化并发送有界交接；核验待命任务确认"]
+    R11 --> R12
+    R12 --> R13["原子切换整组任务；提交并回读运行时状态"]
+    R13 --> R14["封存、恢复并解冻；继续使用同一个 heartbeat"]
+    R14 --> R15["新任务继承规范状态；旧任务保持归档；coordinator 最后归档"]
+```
+
+Apply 是前向恢复流程。中断时保持冻结并继续同一 operation；不会回滚、删除任务、修改规范工作记录，也不会重试结果未知的任务创建。
+
 ## 快速开始
 
 ### 1. 安装
@@ -126,7 +218,6 @@ dispatchReturnMode: foreground
 ```text
 resetControllerTasks: true
 Action: Plan
-
 # 检查返回的 planHash，再使用相同请求发送：
 Action: Apply
 planHash: <返回的 planHash>
@@ -153,18 +244,10 @@ indexMode: full
 
 Skill 只克隆到 `cloneRoot` 的新子目录，随后返回 `needs-project-add`。把精确克隆目录保存为 Codex 项目，再使用相同请求重跑。只有根目录、不含凭据的 origin 以及请求的 branch 或 ref 均通过核验时，才会复用既有克隆。
 
-## 工作方式
-
-1. 把每个 source 匹配到当前主机上的精确已保存项目。
-2. 核验任务身份、根目录、Git 基线、脏工作区和 `codebase-memory` 索引。
-3. 仓库内修改和测试始终留在该仓库的入口任务中。
-4. 可选中控只负责共享契约、依赖顺序、任务下发与全链路验收。
-5. 验收前核对项目返回的分支、HEAD、diff、测试、契约影响和剩余风险。
+## 能力边界
 
 这是**工作流隔离（workflow isolation）**，不是安全沙箱。它不会改变文件系统权限；人为在一个任务中混合多个仓库时，上下文污染仍会回来。
 
-队列、恢复、收敛、回执和中控状态等详细契约见[中控运行时参考](./references/controller-runtime.md)，无需放在项目首页。
-
 ## 输入
 
 | 字段 | 是否必需 | 含义 |