@xulthekl/team-flow 0.57.0 → 0.59.0

package/skills/code-reviewer/SKILL.md

@@ -133,6 +133,12 @@ Check for:
 - **Performance**: No obvious N+1 queries, no unnecessary loops, appropriate caching
 - **Security**: Input validation, SQL injection prevention, XSS prevention, auth checks
 
+**Structural criteria (clean-code, v0.58.0)**：本节另有一套可判定判据——机械阈值（魔法值 Critical；长度/嵌套/参数/命名 Minor）+ 两项必答（单一职责、DRY）。
+
+**执行处是派发模板** `skills/code-reviewer/code-reviewer-prompt.md`（其 Code quality 段已内联完整判据），**不是本文件**。原因：由该模板派发的 `general-purpose` 子代理**读不到**本 SKILL.md 或 `clean-code` skill——子代理不继承父 Agent 的 Skills（CLAUDE.md 明文）。注：该模板经**直接路径读取**（本文件 `Procedure` 步骤 2 指明），**不**经 `tf runtime asset read` 的 `ASSETS` 白名单——后者仅含 `skills/build-executor/implementer-prompt.md` 与 `task-reviewer-prompt.md` 两个模板，写此文时曾误述为「白名单放行本模板」。
+
+本 SKILL.md 与 `clean-code` skill 是判据的**真相源**，供 agent 路径预加载与维护参考；两侧核心判据 MUST 保持一致（由 P4 一致性检查守护）。
+
 ### Step 4: Architecture Review
 
 Check for:
@@ -194,12 +200,16 @@ Check for:
 
 ## Verdict Criteria
 
+本表用于**报告内**的结论表述；写入 receipt 时只有 `pass | fail` 两值，映射规则见末行。
+
 | Verdict | Condition |
 |---------|-----------|
 | **PASS** | No Critical or Important findings |
 | **PASS_WITH_WARNINGS** | No Critical, but Important findings exist |
 | **FAIL** | Any Critical finding (including Test Matrix Compliance gaps — v0.12 §44.3) |
 
+**receipt 映射（v0.58.0 统一，消除此前四处口径分歧）**：`tf execution review --verdict` 只接受 `pass | fail`。**PASS → `pass`**；**PASS_WITH_WARNINGS 与 FAIL 均 → `fail`** —— 即 **Important 亦须阻断**，与 `code-reviewer-prompt.md`、`task-reviewer-prompt.md`、`build-executor/SKILL.md` 三处的「Critical/Important findings require a `fail` receipt」保持一致。此前本表的「FAIL 仅 Critical」是四处口径中唯一的异类，且 `PASS_WITH_WARNINGS` 在二值 receipt 中**无法表达**，已按此统一。
+
 Test Matrix Compliance Critical findings carry the same weight as Spec Compliance violations — matrix gaps are always Critical, never Important.
 
 ## Calibration Rules

package/skills/code-reviewer/code-reviewer-prompt.md

@@ -69,6 +69,43 @@ Subagent (general-purpose):
     - DRY without premature abstraction?
     - Edge cases handled?
 
+    **Structural criteria (clean-code) — mechanical thresholds:**
+    - **Magic values** (unnamed numeric/string literals) → **Critical**. Front-end code too.
+    - Function length >20 lines / nesting depth >2 levels / parameters >3 / naming form
+      (constants SCREAMING_SNAKE; booleans `is`/`has`/`can` prefix) → Minor. When counting
+      nesting, exclude try/catch's own level and guard-clause `return`/`continue` levels;
+      framework-fixed signatures are exempt from the parameter rule.
+      These thresholds are **readability advisories**. The "Do not use line count as
+      evidence" rule under Minimality And Scope concerns *removing* required code; this
+      one NEVER justifies deleting validation, security, or error handling.
+
+    **Incremental boundary — applies to ALL criteria above and below**: judge only the code
+    units this diff adds or modifies. When a hit sits inside a function that already existed
+    before this change, downgrade it to **Minor** and register it as `存量待整改` in your
+    report — never ask for a rewrite outside the task scope.
+
+    **Structural criteria — mandatory answers** (no threshold: answer AND justify):
+    - **Single responsibility**: can the function name cover ALL steps in the body?
+    - **DRY**: is there a structurally equivalent logic block within this diff OR this
+      repository (ignore comments, whitespace, identifier names)? Answer "yes" only when
+      you cite BOTH `file:line` sides.
+      - Disposition: same shared publish unit (same package / module / directory) →
+        **Critical**, extract a shared layer. Cross-repo duplication is NOT judgeable
+        here (your worktree is single-repo).
+
+    **Judgement cases** — when a structural hit is genuinely not blocking, cite it as
+    `judgement-exception: <id>` **plus the structural similarity** (e.g. "all guard clauses,
+    no nesting"). Match by **structural features, not line count** — the numbers below
+    illustrate the case, they are not thresholds. Available ids:
+    - `P1` — long function (≈37 lines) whose body is all guard clauses, one abstraction level → not blocking
+    - `P2` — cross-repo isomorphic fix, no shared publish unit → not blocking
+    - `N1` — long function (≈54 lines) that is guard clauses + one switch, no nesting → not blocking
+    - `N2` — deep nesting arising from try/catch + guard-clause `continue` → already covered
+      by the nesting rule (cite only if that rule's intent is disputed)
+    - `N4` — ≈35 lines, single abstraction level (error mapping) → advisory only
+    - Magic-value exemptions beyond the criterion's list: no id needed — apply the criterion's
+      own test ("does changing this value change behavior?") and state your reasoning.
+
     **Architecture:**
     - Sound design decisions?
     - Reasonable scalability and performance?
@@ -124,6 +161,18 @@ Subagent (general-purpose):
     a fresh review and replacement `pass` receipt before any dependent wave or
     closing transition.
 
+    ### Structural Criteria (mandatory answers)
+
+    Answer both; cite `file:line` for each. If you downgrade by citing a judgement
+    case, name it here as `judgement-exception: <id>` plus the structural similarity.
+
+    - **Single responsibility**: [Yes | No — if No, list the steps the function name
+      cannot cover, with file:line]
+    - **DRY**: [Yes | No — if Yes, cite BOTH `file:line` sides + shared-layer disposition]
+
+    **存量待整改** (pre-existing hits downgraded to Minor — one per line, or "none"):
+    - [e.g. `src/foo/Bar.java:120` — function length >20 lines, pre-existing]
+
     ### Strengths
     [What's well done? Be specific.]
 
@@ -188,8 +237,23 @@ Subagent (general-purpose):
 - Comprehensive test coverage (18 tests, all edge cases)
 - Good error handling with fallbacks (summarizer.ts:85-92)
 
+### Structural Criteria
+
+- Single responsibility: Yes — each handler covers one step
+- DRY: No — `search.ts:25-27` duplicates the date-validation block in `parse.ts:88-90`
+  (structurally equivalent, comments/identifiers ignored). Same package → shared layer
+  recommended (Critical)
+
 ### Issues
 
+#### Critical (Must Fix)
+1. **Structurally duplicated date-validation block**
+   - File: `search.ts:25-27` (duplicates `parse.ts:88-90`)
+   - Issue: Same package, structurally equivalent — the two copies will drift
+   - Fix: Extract to a shared helper in the package's utils
+   - Note: A Critical finding forces `--verdict fail`; a repair requires a fresh
+     review and a replacement `pass` receipt before any dependent wave
+
 #### Important
 1. **Missing help text in CLI wrapper**
    - File: index-conversations:1-31
@@ -213,7 +277,9 @@ Subagent (general-purpose):
 
 ### Assessment
 
-**Ready to merge: With fixes**
+**Ready to merge: No** — a Critical finding is open
 
-**Reasoning:** Core implementation is solid with good architecture and tests. Important issues (help text, date validation) are easily fixed and don't affect core functionality.
+**Reasoning:** Core implementation is solid with good architecture and tests, but the
+structurally duplicated validation block (Critical) must be extracted into a shared layer
+before merge. The Important issues (help text, date validation) are easily fixed.
 ```

package/skills/decision-surrogate/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: decision-surrogate
+description: This skill should be used when the user asks to "启动替身", "夜间替身", "我要睡了，今晚把 X 推下去", "睡前布置任务", "surrogate mode", or wants an agent to take over team-flow decision points while away (overnight or otherwise). It loads the user's decision-preference library and a surrogate home, dispatches workers via Orca orchestration on team-flow projects, adjudicates pre-authorized decision points, and delivers a decision log in the morning. Optional, opt-in only.
+---
+
+# 决策替身（Decision Surrogate）
+
+在用户离席期间扮演「决策代理」：用户睡前布置任务并逐点预授权，替身在夜间派 worker 跑 team-flow 工作流、裁决**可代答**的决策点、其余一律 HOLD 等用户，早上交付决策过程汇总。
+
+**核心边界**：替身只做决策与编排，**不写代码、不改状态文件、不发明任务方向**。
+
+## 何时使用
+
+- 用户要睡前（或离席前）布置任务，希望期间持续推进
+- 当前会话承担替身角色（本 skill 由主会话加载，不是 dispatch 的子代理）
+
+## Phase 0：首次接入（环境探测 + 初始化）
+
+**每次启动先跑探测**；缺项即引导补齐，**不降级、不跳过**。完整探测矩阵、初始化步骤与偏好库访谈问题见 `references/onboarding.md`。
+
+| 探测项 | 命令 | 缺失时 |
+|--------|------|--------|
+| Orca CLI | `which orca` | 引导安装（`brew install orca`） |
+| Orca runtime | `orca status --json` → `result.runtime.state == "ready"` | 引导 `orca open` |
+| orchestration 可用 | `orca orchestration run-list --json` → 返回 JSON 且 `ok: true` | 引导开启 Settings → Experimental |
+| 已绑定的 Run | `orca orchestration run-current --json`（确认当前会话可作协调者） | 说明须在 Orca 管理的终端内运行 |
+| 可用项目 | `orca worktree list --json` | 列出项目供用户选择目标 |
+| 偏好库 | `~/.claude/lt-preferences/decision-preferences.md` 存在 | 走「偏好库初始化」（onboarding.md §2） |
+| 替身 home | 用户指定路径（默认 `~/Documents/work/code/practice/surrogate-home/`）含 `state/` | 创建 + `git init`（onboarding.md §3） |
+| 项目空间判据 | 目标含 `.team-flow/` + `changes/` | **拒绝派发**（普通模式本期不支持） |
+| 机器不休眠 | `pmset -g` 的 `sleep` 为 0 | 引导 `caffeinate -i` |
+
+探测结果向用户报告一张「就绪/待补齐」清单，补齐后方可进 Phase 1。
+
+## Phase 1：睡前授权（用户在场，约 5 分钟）
+
+1. 接收任务：项目空间、change、完成标准
+2. **预案扫描**：读 change 现状 + 偏好库，列出预期决策点及其默认裁决，一并确认**架构门状态**与**执行模式**（两者决定夜间能走多远）
+3. **读回**：把任务 + 逐点授权 + 红线完整读给用户
+4. **落盘**：用户确认后写 `state/mandate-<YYYY-MM-DD>.md`（模板见 `references/protocols.md`）
+5. **派发**：`run-create` → `task-create --spec <...>` → `worker-start --task <id> --worktree "path:<项目根>" --agent claude`
+   - task spec **必须**包含两条硬指令：**禁止使用 AskUserQuestion**；决策点一律 `orca ask` 转协调者
+
+## Phase 2：夜间执行
+
+循环处理：
+
+1. `orca orchestration check --wait --types question,worker_done,escalation --timeout-ms 600000 --json`
+2. 逐条处置：
+   - `question` → 按 `references/decision-points.md` 的三档裁决 → `reply`（代答）或 `reply --body "HOLD: <原因>"`
+   - `worker_done` → 处置 worker（`worker-release`；有后续 task 则转派）
+   - `escalation` → 记入早报「等你决定」
+3. **每个裁决即时写日志**（不等收工）：`state/decisions-<YYYY-MM-DD>.log`
+4. 处理完再确认：`orca orchestration check --ack <delivery_id> --wait ...`
+5. **`check` 超时未收到 `worker_done` 时**：用 `orca orchestration worker-show --dispatch <id>` 判状态并处置——
+   - `ready` → 继续等（长任务常态）
+   - `failed` / `stopped` → `orca orchestration worker-start --task <t> --retry-of <dispatch> --on <saved-environment> --worktree <...> --agent claude` 重启（`--retry-of` **不继承位置**——须显式重复 `--on` / `--worktree` / `--agent`，否则多 server 场景会落到默认 server）
+   - `outcome_unknown` → `worker-stop --dispatch <id>` 后检查
+   - **注意**：worker 停在人工应答（`observation.agentWait`）是**健康态**，不是故障
+   - 每次判状态后追加一条 `health` 日志行
+6. **替身自身异常的恢复**（通道堵死 / 会话崩溃）：
+   - **通道停更判据**：`check --wait` 连续 2 次满超时（各 10 分钟）且期间零消息 → 记 `health` 行 `channel_stalled`，改用 `worker-show --dispatch <id>` 逐个轮询既有 dispatch，不再依赖长等待
+   - **崩溃恢复**：替身会话中断后，状态**只在磁盘**——重入时先读 `state/mandate-<date>.md` + `decisions-<date>.log`，再用 `worker-show` 逐个对账 dispatch 状态，**禁止凭记忆续跑**
+   - **续跑依赖 `send --to dispatch` 唤醒 worker（未实证，见设计文档 §7.5 ⑧⑨）**——已实证的是 `reply` 通路，**与主动 `send` 不是同一条路**；首次启用前须实测，通不过则退化为人工重新派发
+
+**裁决依据优先级（高→低）**：授权书红线 > 授权书逐点授权 > 偏好库条目 > 可推断。
+**冲突时红线优先**（例如偏好库里「收尾即提交推送」在夜间不适用，一律不 push）。
+
+## Phase 3：早上交付
+
+从决策日志渲染早报 `state/report-<YYYY-MM-DD>.md`（格式见 `references/protocols.md`），六段式：① 夜间健康度 ② 各 change 进度 ③ 我替你做的决策 ④ 等你决定的 ⑤ 试过但失败的 ⑥ 成本。
+
+**早报必须逐条列出 HOLD 项**，每项附「问题 + 选项 + 替身倾向 + 依据」，便于用户批量裁决。
+
+## 硬约束
+
+- **禁止 AskUserQuestion**：P0 实证 `orca terminal send` 会返回 `agent_prompt_stalled`——一旦 worker 弹出 TUI 模态，**没有任何自动化手段能救它**。故此禁令是硬要求，不是建议
+- **替身不改状态文件**：决策点状态由 worker 经 `tf state set` 写入（`dp_4_result` 由 `tf execution plan --confirm` 程序化写入，不可 set；**HOLD 场景不写任何决策点字段**——`dp_{1,2,3,5,6,7}_decisions` 等 12 个字段在白名单内但不可落盘，见 `references/protocols.md` §三）
+- **HOLD 是主要形态**：无法代答的点一律 HOLD，**不得静默放行**
+- **不做沉默即同意**：`ask` 超时不产生默认裁决，保留 thread id 待恢复
+- **不假设未验证的机制**：worker 遵循指示是靠 task spec 约束的运行时行为；每次任务须核对早报与**决策日志 + change 的 `state` 位置**是否一致（HOLD 项按设计不写 `dp_N_result`；字段能否落盘须实测，勿据白名单推断）
+
+## 参考文件
+
+- **`references/onboarding.md`** — 首次接入：环境探测矩阵、偏好库初始化（三种方式）、替身 home 初始化、就绪检查
+- **`references/decision-points.md`** — 9 个决策点 + 5 个确认点的代答权限、三档处置规则、夜间红线清单
+- **`references/protocols.md`** — 授权书模板、worker task spec 模板、HOLD 六步协议、**决策日志与早报格式**

package/skills/decision-surrogate/references/decision-points.md

@@ -0,0 +1,87 @@
+# 决策点代答权限与处置规则
+
+> 来源：工作区仓 `docs/plan/decision-surrogate-design.md`（v4.1 §6）；决策点权威定义见插件内 `docs/decision-points.md`
+
+## 一、完整清单（9 个 DP 门 + 5 个确认点）
+
+| 决策点 | 名称 | 守门者 | 位置证据 |
+|--------|------|--------|---------|
+| DP-0 | 设计前确认 | 主会话 | workflow-start |
+| DP-1 | 需求确认 | 主进程（need-explorer 为交互式澄清） | `skills/workflow-start/SKILL.md:71` |
+| DP-2 | 工件审查 | 待 P0/P2 确认 | `skills/spec-writer/SKILL.md:151` |
+| DP-A | 架构设计确认 | 主会话（AskUserQuestion） | `skills/workflow-start/references/routing-rules.md:104,153` |
+| DP-3 | 契约批准（硬门禁） | 主会话 | `skills/workflow-start/references/routing-rules.md:212` |
+| DP-4 | 执行模式选择 | 主会话 | `skills/workflow-start/references/routing-rules.md:215` |
+| DP-5 | 调试升级（3+ 失败） | 待确认 | `skills/bug-investigator/SKILL.md:50` |
+| DP-6 | 验证失败 | 待确认 | `skills/release-archivist/references/closing-procedures.md:65` |
+| DP-7 | 归档确认 | 待确认 | 同上 `:82` |
+| G4 | 同步 change 规划制品 | 主会话 | `skills/workflow-start/SKILL.md:124` |
+| G5 | 归档相关 | 随 DP-7 | — |
+| **Code Landing** | `tf deisolate --merge`（**不可逆**） | — | `skills/release-archivist/SKILL.md:110` |
+| **S3.5 publish** | `tf publish --arch --push`（含 push） | — | — |
+| Step 5b E2E | E2E 验证 | — | `skills/release-archivist/SKILL.md:87` |
+
+## 二、代答权限
+
+| 决策点 | 判定 | 条件 |
+|--------|------|------|
+| DP-0 | ✅ **无条件代答** | 照 change-brief 继承 |
+| DP-1 | ⚠️ 条件代答 | 授权书写明需求范围 |
+| DP-2 | ⚠️ 条件代答 | 独立评审已通过 |
+| **DP-A** | ⛔ **一律挂起** | 架构门禁（用户决定，2026-09-12） |
+| DP-3 | ⚠️ 条件代答 | 见下节四条件 |
+| DP-4 | ⚠️ 条件代答 | 授权书**明确指定**执行模式；未指定 → 挂起 |
+| DP-5 | ⛔ 挂起 | — |
+| DP-6 | ⛔ 挂起 | — |
+| DP-7 | ⛔ 挂起 | — |
+| G4 | ⚠️ 条件代答 | 随 DP-3 判定 |
+| G5 | ⛔ 挂起 | 随 DP-7 |
+| Code Landing | ⛔ 挂起 | 不可逆 |
+| S3.5 publish | ⛔ 挂起 | 含 push |
+| Step 5b E2E | ⚠️ 条件代答 | 结果客观 |
+
+**汇总**：无条件代答 1 ｜ 条件代答 6 ｜ 挂起 7。
+
+## 三、DP-3 条件代答四条件
+
+**同时满足**才批准，缺一 HOLD（命中的条件编号写入决策日志）：
+
+1. 授权书授予本次 change 的 DP-3 代答权
+2. 独立评审已通过（**锚点待 P0 出结论**，候选：`tf execution review` receipt 或 change 内 review 报告）
+3. test-matrix 就绪——判据以 `scripts/guard/checks/test-matrix-ready.mjs:25-55` 为准
+4. 契约内容未超出授权书声明的范围
+
+## 四、合并组处置
+
+合并组（`docs/decision-points.md:101-111`）：`DP-0+DP-A`（架构判定 `skipped` 时）、`DP-3+G4+DP-4`、`DP-7+代码落地+G5`；判定 `required` 时 DP-A 必须独立。
+
+**规则**：对批次内**逐项独立裁决、逐项落盘**；**以最靠前的 HOLD 项决定 change 停止位置**。
+
+- 全部可代答 → 逐项给裁决
+- 含 HOLD 项 → 可代答项**照常裁决并落盘**；HOLD 项及其之后停止推进
+
+（合并只是交互层的降轮次手段，**门禁强度不变**——`docs/decision-points.md:103`）
+
+## 五、三档处置与优先级
+
+| 档 | 判据 | 处置 |
+|---|------|------|
+| 已授权 | 授权书明确写了 | 直接答 |
+| 可推断 | 与已授权项同类 **且偏好库有对应条目** | 答，早报标「待复核」 |
+| HOLD | 方向/路线分叉；不可逆；偏好库无对应；上表标 ⛔ | HOLD（见 protocols.md §三） |
+
+**优先级（高→低）**：授权书红线 > 授权书逐点授权 > 偏好库条目 > 可推断。
+
+## 六、夜间红线（用户确认 2026-09-12）
+
+**允许**：worktree 内本地提交（可整体丢弃）。
+
+**禁止清单**：
+
+1. `push`（含 `tf publish --arch --push`）
+2. 发布（`npm publish`）
+3. 删除任何文件/分支/worktree
+4. 修改契约范围外的公共接口
+5. 任何对外发送（消息/邮件/评论）
+6. 自行发明任务方向
+7. 执行 Code Landing（`tf deisolate --merge`）

package/skills/decision-surrogate/references/onboarding.md

@@ -0,0 +1,79 @@
+# 首次接入：环境探测与初始化
+
+> 目标：把「一台裸机 + 一个想用替身的人」带到可启动状态。全部探测**只读**；所有写操作（建目录、写偏好库）**先向用户说明再执行**。
+
+## 1. 环境探测矩阵
+
+按顺序执行，记录每项状态；任何一项不可用都应给出**具体引导命令**，而非笼统报错。
+
+| # | 探测项 | 命令 | 就绪判据 | 缺失时的引导 |
+|---|--------|------|---------|-------------|
+| 1 | Orca CLI | `which orca` | 返回路径 | `brew install orca`（macOS） |
+| 2 | Orca runtime | `orca status --json` | `result.runtime.state == "ready"` | `orca open`（启动桌面应用并等待 runtime 可达） |
+| 3 | orchestration 可用 | `orca orchestration run-list --json` | 返回 JSON 且 `ok: true` | 在 Orca 打开 **Settings → Experimental** 启用 orchestration |
+| 4 | 协调者锚点 | `orca orchestration run-current --json` | 能显示当前终端绑定的 Run（或可 `run-create` 绑定） | 说明：本 skill 须在 **Orca 管理的终端**内运行，普通终端无法接收 worker 消息 |
+| 5 | 可用项目 | `orca worktree list --json` | 列出项目 | 用 `orca repo add --path <路径>` 注册项目 |
+| 6 | 目标项目空间 | 目标路径含 `.team-flow/` 与 `changes/` | 两者存在 | **拒绝派发**——普通模式本期不支持，改用 workflow-start 常规推进 |
+| 7 | 偏好库 | `test -f ~/.claude/lt-preferences/decision-preferences.md` | 文件存在 | 走 §2 |
+| 8 | 替身 home | `test -d <home>/state` | 目录存在 | 走 §3 |
+| 9 | 机器不休眠 | `pmset -g` 的 `sleep` 为 0；`pgrep -x caffeinate` 有进程 | 两者满足 | `caffeinate -i`（前台保持）；或说明夜间须保持机器唤醒 |
+
+**输出**：一张「就绪 / 待补齐」清单交给用户，**补齐后才进 Phase 1**。
+
+## 2. 偏好库初始化（三种方式，按投入递增）
+
+偏好库是替身判断力的唯一来源；**没有它就不要启动替身**（否则替身只能全量 HOLD，等于没做）。
+
+### 方式 A：交互式最小收集（约 5 分钟，建议起步用）
+
+逐条询问用户，**一次问 3-4 个**避免疲劳；把答案按偏好库格式落成 `~/.claude/lt-preferences/decision-preferences.md`：
+
+| # | 情境 | 记录字段 |
+|---|------|---------|
+| 1 | **文档与实现不一致**时：补强代码 / 修正文档 / 两者都改？ | 情境 / 选项 / 倾向 |
+| 2 | **方案评审强度**：每方案必评 / 仅中大型评 / 看情况？ | + Why（追问一句） |
+| 3 | **流程与任务规模失配**：砍流程环节 / 忍受 / 重构流程本身？ | + How to apply |
+| 4 | **信息不足**时：直接问 / 按最可能猜并标注 / 挂起等确认？ | 置信度 = 用户明述 |
+| 5 | **不可逆操作**（发布 / 合并 / 删除）：一律确认 / 满足条件可自动 / 看影响面？ | |
+| 6 | **收尾动作**：完成即提交推送 / 等确认 / 只提交不推送？ | |
+| 7 | **最在意的质量维度**（列 3 个，如可维护性 / 一致性 / 可回溯性）？ | |
+| 8 | **绝对红线**：无论如何都不做的操作？ | 单列「红线」节 |
+
+每条写成：`情境 → 倾向（选项全集）→ Why → How to apply → 置信度`。
+
+### 方式 B：从既有资产提炼（可与 A 并行）
+
+读 `~/.claude/CLAUDE.md`、项目 `CLAUDE.md` 的「强制要求 / 禁止」条目、以及 memory 目录下的既有条目，提炼成偏好条目。
+
+**注意**：显式规则（"不允许用魔法常量"这类）可靠性最高，优先收录；从语气/风格推断的结论标 `[断]`。
+
+### 方式 C：从历史会话挖掘（最完整，成本最高）
+
+适用：用户已积累数月会话记录，希望替身更贴近本人。
+
+1. 定位会话：`~/.claude/projects/<按路径转义的项目目录>/*.jsonl`
+2. 提取人类输入（过滤 `tool_result`、以 `<` 开头的注入块、上下文压缩摘要、skill 内容）
+3. 分片派**独立子代理**提炼：新偏好 / 已有偏好的新证据 / 矛盾证据
+4. 合并去重后落盘，标注置信度与出处
+
+**建议**：先用 A+B 起步运行，积累几周后再用 C 做一次深度校准。
+
+## 3. 替身 home 初始化
+
+```bash
+mkdir -p <home>/state
+cd <home> && git init
+```
+
+- 默认路径 `~/Documents/work/code/practice/surrogate-home/`（用户可指定其他路径）
+- `state/` 承载：授权书 `mandate-<date>.md`、决策日志 `decisions-<date>.log`、早报 `report-<date>.md`、任务队列 `queue.md`
+- home **与业务项目解耦**；偏好库不放这里（它在 `~/.claude/lt-preferences/`，属用户级、跨项目可用）
+
+## 4. 就绪检查（进 Phase 1 前）
+
+- [ ] 环境探测矩阵 9 项全部就绪
+- [ ] 偏好库存在且非空（≥1 条）
+- [ ] 替身 home 存在且含 `state/`
+- [ ] 用户已确认目标项目空间与 change
+
+全部打勾后，向用户复述一次本次任务的**范围与红线**，再进 Phase 1。

package/skills/decision-surrogate/references/protocols.md

@@ -0,0 +1,116 @@
+# 协议模板集
+
+## 一、授权书模板 → `state/mandate-<YYYY-MM-DD>.md`
+
+```markdown
+# 授权书 <日期> ｜ change：<name>
+
+## 任务
+- 项目空间：<路径>
+- change：<name>
+- 完成标准：<可验证的完成条件>
+- **架构门状态：已过 / 未过**（未过则夜间止于 exploring）
+- 需求范围：<scope 摘要，供 DP-1 条件代答判据>
+- **执行模式：<TDD|SDD|inline|不指定>**（不指定则夜间止于 approved-for-build）
+
+## 逐点授权
+| 决策点 | 授权 | 条件 |
+|--------|------|------|
+| DP-0 | 代答 | 照 change-brief 继承 |
+| DP-1 | 条件代答 | 不超出上述需求范围 |
+| DP-2 | 条件代答 | 独立评审通过 |
+| DP-A | 挂起 | 架构门禁 |
+| DP-3 | 条件代答 | 四条件（见 decision-points.md §三）|
+| DP-4 | 条件代答 | 已指定执行模式（见上）|
+| DP-5 ~ DP-7 | 挂起 | — |
+| G4 | 条件代答 | 随 DP-3 |
+| G5 | 挂起 | 随 DP-7 |
+| Code Landing / S3.5 publish | 挂起 | 不可逆 / 含 push |
+| Step 5b E2E | 条件代答 | 结果客观 |
+
+## 红线
+允许 worktree 内本地提交；禁止：push / 发布 / 删除 / 改契约外接口 / 对外发送 / 发明任务 / Code Landing
+```
+
+## 二、Worker task spec 模板（**硬指令不可省**）
+
+```
+<任务描述：项目空间、change、完成标准>
+
+【协调协议 — 必须遵守】
+1. 严格禁止使用 AskUserQuestion 工具。任何需要用户确认的点，一律用
+   `orca orchestration ask --question "<问题>" --options "<选项逗号分隔>" --timeout-ms 600000`
+   转给协调者（替身），等待 reply 后再继续。
+2. 子代理上报的决策请求同样转给协调者，不得自行裁决。
+3. **若 `ask` 超时：禁止自行裁决**。保留 message_id，用
+   `orca orchestration ask --resume <message_id> --timeout-ms 600000` 续等；
+   续等仍超时则停止推进并向协调者上报。
+4. 完成或阻塞时用
+   `orca orchestration send --type worker_done --outcome <succeeded|failed> --subject "<状态>" --body "<三句话：做了什么、发现了什么、还剩什么>" --json`
+   报告，随后结束本轮。task/dispatch ID 使用 Orca 启动时注入的值，**不要自行编造**。
+
+【红线 — 绝对禁止（违反即停）】
+- `push`（含 `tf publish --arch --push`）
+- 发布（`npm publish`）
+- 删除任何文件、分支或 worktree
+- 修改契约范围外的公共接口
+- 任何对外发送（消息 / 邮件 / 评论）
+- 自行发明任务方向
+- 执行 Code Landing（`tf deisolate --merge`）
+```
+
+> 派发命令：`orca orchestration worker-start --task <task_id> --worktree "path:<项目根>" --agent claude --json`
+> `path:` 只能指向**项目根**（Orca 注册主 worktree）；`tf isolate` 建的 `.worktrees/...` 路径不可用（返回 `selector_not_found`）。
+
+## 三、HOLD 协议（worker 侧六步）
+
+| 步骤 | 动作 |
+|------|------|
+| ① 替身裁决 | `orca orchestration reply --id <msg_id> --body "HOLD: <原因>"` |
+| ② worker | 停止当前 change 推进；不提交半成品；已落 worktree 的工作**保留** |
+| ③ worker 记录 | **不写任何决策点字段**。两条禁令：① `dp_N_result` 是门禁判据（`dp-gate-passed` 只校验非空），写入 HOLD 值会让 change 呈现"已批准"假象；② `dp_{1,2,3,5,6,7}_decisions` 与 `dp_{1,2,3,5,6,7}_confirmed`（共 12 个）**不可落盘**——它们在 `cmd-state.mjs` 的 `SETTABLE_FIELDS` 白名单内，但 `state-loader.mjs` 的 `writeState` 无对应序列化分支，`tf state set` **回显 ✅ 却零写入**（v0.59.0 P4 亲测；**注意 `dp_0_decisions`/`dp_0_confirmed` 不在此列，它们确实会落盘**）。HOLD 的持久锚点 = 步④ 的 escalation 消息 + 步⑥ 的替身决策日志 + change 的 `state` 仍停在门禁前（客观事实）。**约束**：不得新建 `changes/<name>/` 下任何文件（Artifact Ownership：主会话 MUST NOT 直接 Edit/Write `changes/` 或 `.worktrees/`） |
+| ④ worker 上报 | `orca orchestration send --type escalation --subject "HOLD at <门>" --body "<摘要>" --json` |
+| ⑤ worker 处置 | 用 `orca orchestration worker-retain --dispatch <id>` 标记保留（**不可用 `worker-release`**——官方禁止因 escalation/question/idle 释放） |
+| ⑥ 替身 | 写决策日志 + 早报「等你决定」段（问题/选项/替身倾向/依据/msg_id） |
+
+**多任务**：一个 HOLD 不阻塞其他 worker。
+**早上恢复**：用户批阅早报 → 给出裁决 → `orca orchestration send --to dispatch:<id> --subject "<裁决>"` 投递 → worker 解除 HOLD 继续。
+
+> ⚠️ **此路径依赖 §7.5 ⑧⑨（未实证）**：附录 D ⑧ 验证的是 `reply` 唤醒（ask→reply 通道），**与「向 dispatch 主动 `send`」不是同一条路径**。首次启用前必须实测；不通则退化为人工续跑（重新派发任务）。**不得据相邻机制的实测结论推断本路径可用**。
+
+## 四、决策日志格式 → `state/decisions-<YYYY-MM-DD>.log`（append-only）
+
+**多类型行**（早报六段各有数据源）：
+
+```
+decision | [HH:MM] | <change> | <决策点> | <问题摘要> | 选项:<...> | 裁决:<代答值|HOLD> | 理由:<...> | 依据:<授权书§N|偏好库#N> | 命中条件:<...> | msg:<id> | 置信:<高|中|低>
+progress | [HH:MM] | <change> | 停止位置:<...> | 推进步数:<N> | 隔离位置:<路径> | diff:<摘要>
+health   | [HH:MM] | <dispatch> | 状态:<ready|agentWait|failed|stopped|outcome_unknown|channel_stalled> | 心跳:<时间戳>
+cost     | [HH:MM] | 累计:<token|时长>
+```
+
+**即时写**（不等收工）——日志是抗压缩的锚点，也是早报的唯一数据源。
+
+## 五、早报格式 → `state/report-<YYYY-MM-DD>.md`
+
+```
+# 替身早报 <日期>
+
+## ① 夜间健康度
+心跳时间戳范围 / 是否卡过 / 有无告警
+
+## ② 各 change 进度
+| change | 停止位置 | 推进步数 | 隔离位置 | diff 摘要 |
+
+## ③ 我替你做的决策
+| 时间 | change | 决策点 | 选择 | 理由 | 依据 | 置信 |
+
+## ④ 等你决定的（HOLD）
+| 决策点 | 问题 | 选项 | 替身倾向 | 依据 | 恢复命令 |
+（逐条列全，便于批量裁决）
+
+## ⑤ 试过但失败的
+## ⑥ 成本
+```
+
+**渲染原则**：从决策日志渲染，**不从对话记忆渲染**（抗压缩、可审计）。

package/skills/workflow-orchestrator/references/s5-monitoring.md

@@ -24,10 +24,14 @@
 
 ### 2. 跨 change 一致性检测
 
-调用 `cross-change-consistency-checker` agent（插件 agent，跨 skill 复用价值）检测：
-- 共享聚合/实体的变更是否冲突
-- API 变更是否影响其他 change
-- 原型漂移（change 实现与全局 prototype/ 是否一致）
+调用 `cross-change-consistency-checker` agent（插件 agent，跨 skill 复用价值）检测 5 个维度：
+- 共享聚合/实体的变更是否冲突（Dim 1）
+- API 变更是否影响其他 change（Dim 2）
+- 架构锚点漂移（Dim 3）
+- 原型漂移（change 实现与全局 prototype/ 是否一致）（Dim 4）
+- **同构横展完整性（Dim 5，v0.58.0）**：本 change 处置的代码模式，是否在其**全部**出现位置都已处置
+
+**Dim 5 传参**：须向 agent 传 `repo_layout`（读 `<项目根>/.team-flow/team-flow.config.json` 的 `repo_layout.repos`）；缺失时 agent 跳过 Dim 5 并注明。**触发条件**：change 性质为缺陷修复 / 规则对齐 / 同构同步时启用；纯新功能开发跳过（无既有模式可横展）。**真空对照**：agent 对零命中的模式须显式报告「模式未命中，需人工确认」，不得记为 CLEAN。
 
 ### 3. 复利晋升
 

package/skills/workflow-start/SKILL.md

@@ -141,6 +141,10 @@ The current planned wave is implemented and ready for spec-compliance + code-qua
 ### Route to release-archivist (dispatch sub-agent)
 Guard: `... check <dir> executing closing --json` → fail = BLOCK. Implementation complete, verification complete/nearly complete. Include `DP-7: 归档确认`.
 
+**Dim 5 横展完整性检查（v0.58.0）**：`executing → closing` 前，若本 change 性质为缺陷修复 / 规则对齐 / 同构同步，调度 `cross-change-consistency-checker` agent 执行 **Dim 5**——传 `change_dirs`（本 change）+ `repo_layout`（读 `.team-flow/team-flow.config.json` 的 `repo_layout.repos`）。agent 以**模式驱动**扫描本 change diff 中被处置的具名结构元素在**全部仓**的出现位置，差异集即遗漏候选（可达 → Important，须先修复或登记；零调用方 → Minor）。**纯新功能开发跳过**（无既有模式可横展）。**零命中时 agent 须显式报告「模式未命中」而非 CLEAN**（防真空断言）。
+
+> 为何单 change 也要查：横展缺口发生在**单个 change 内部**（v1 实证：一个 change 修了 2 个同构仓、漏了 2 个），而 `cross-change-consistency-checker` 此前仅在 S5（change ≥ 2）被调度——**该场景下 Dim 5 永不触发**。此处是本检查对单 change 的唯一入口。
+
 ### Route to spec-merger
 Delta specs exist that need merging, change closing with ADDED/MODIFIED/REMOVED/RENAMED specs.
 

package/templates/conventions/glaf4-compliant/java-testing.md

@@ -326,7 +326,7 @@ void testGetUser_InactiveUser() { ... }  // status = INACTIVE
 
 ## 8. 测试质量规则
 
-参见 `references/test-quality-rules.md`，主要包括：
+参见 team-flow 插件 `skills/test-strategy/references/test-quality-rules.md`，主要包括：
 
 1. 断言质量规则（missing-meaningful-assertion、weak-assertion-only、verify-only-without-assertion）
 2. 调试代码残留规则（system-out、print-stack-trace）
@@ -339,7 +339,7 @@ void testGetUser_InactiveUser() { ... }  // status = INACTIVE
 
 ## 9. 测试隔离
 
-参见 `references/integration-test-isolation.md`，主要包括：
+参见 team-flow 插件 `skills/test-strategy/references/integration-test-isolation.md`，主要包括：
 
 - Repository 层：H2 内存库
 - Service 层（同步）：@Transactional
@@ -350,7 +350,7 @@ void testGetUser_InactiveUser() { ... }  // status = INACTIVE
 
 ## 10. 集成测试契约
 
-参见 `references/integration-test-contracts.md`，主要包括：
+参见 team-flow 插件 `skills/test-strategy/references/integration-test-contracts.md`，主要包括：
 
 - 入口契约：API 端点、消息队列、定时任务
 - 协作者契约：真实/mock/stub 分级

package/templates/conventions/js-testing.md

@@ -244,7 +244,7 @@ describe('UserService', () => {
 
 ## 7. 测试质量规则
 
-参见 `references/test-quality-rules.md`，主要包括：
+参见 team-flow 插件 `skills/test-strategy/references/test-quality-rules.md`，主要包括：
 
 1. 断言质量规则（missing-meaningful-assertion、weak-assertion-only）
 2. 调试代码残留规则（console.log）

package/templates/conventions/python-testing.md

@@ -316,7 +316,7 @@ def mock_external_api(mocker):
 
 ## 9. 测试质量规则
 
-参见 `references/test-quality-rules.md`，主要包括：
+参见 team-flow 插件 `skills/test-strategy/references/test-quality-rules.md`，主要包括：
 
 1. 断言质量规则（missing-meaningful-assertion、weak-assertion-only）
 2. 调试代码残留规则（print）

package/.zcode/hooks.json

@@ -1,8 +0,0 @@
-{
-  "hooks": [
-    {
-      "event": "sessionStart",
-      "command": "bash /Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/.zcode/team-flow/hooks/session-start"
-    }
-  ]
-}

package/.zcode/rules/phase-guard.mdc

@@ -1,33 +0,0 @@
----
-description: team-flow phase guard — 防止阶段漂移和未授权实现
-alwaysApply: true
----
-
-# Phase Guard
-
-## 入口规则
-
-- 所有工作必须从 "/workflow-start" 入口开始。
-- 在 .team-flow.yaml 中确认当前 state 和 workflow 模式之前，不要开始写代码。
-
-## 全局禁止
-
-- 没有 execution-contract.md 或未经用户明确批准，不得进入实现。
-- full/hotfix 必须先运行 tf execution plan <change-dir> ...；没有 current execution plan 不得开始实现。
-- 只有 all pass review receipts 后才可 closing；不得把未审查的 wave 当作完成。
-- 上述 plan/receipt gates 仅适用于 full/hotfix；tweak 免除这些 gates (tweak exempt)。
-- 执行过程中如果发现需求/范围变化，必须回退到 specifying 或 bridging，而不是直接改代码。
-- 不要直接调用执行类 skill（如 "/build-executor"），必须通过入口路由。
-
-## 决策点协议
-
-- DP-0：设计前确认
-- DP-1：需求确认
-- DP-2：工件审查
-- DP-3：是否批准 execution contract？
-- DP-4：先运行 tf execution recommend，展示可用模式与推荐；用户用 --confirm 确认，非推荐选择额外使用 --acknowledge-recommendation
-- DP-5：调试升级
-- DP-6：验证失败
-- DP-7：是否收口归档？
-
-> 本文件由 scripts/install-zcode.mjs 生成；对具体变更的 guard 内容请运行 tf inject <change-dir> 更新。