@xulthekl/team-flow 0.58.0 → 0.60.0

package/scripts/check-version-consistency.mjs

@@ -71,6 +71,9 @@ const TEXT_CHECKS = [
   { file: 'llms.txt',               extract: /Current version: v(\d+\.\d+\.\d+)\./ },
   { file: '.claude/always/phase-guard.md', extract: /# team-flow v(\d+\.\d+\.\d+) \|/ },
   { file: 'GEMINI.md',              extract: /# team-flow v(\d+\.\d+\.\d+) \|/ },
+  // v0.59.0：新增 usage-guide 版本锚点（此前不在扫描面内，0.58.0 与 0.59.0 两次发版均靠人工改；
+  // P3-15 ② 半项闭合——**检出**已覆盖，本段仍无 --fix 分支，自动修复待做）
+  { file: 'docs/usage-guide.md',    extract: /版本锚点：v(\d+\.\d+\.\d+)/ },
 ];
 
 for (const check of TEXT_CHECKS) {
@@ -103,9 +106,19 @@ const skillDirs = readdirSync(skillsDir, { withFileTypes: true })
 const ACTUAL_SKILL_COUNT = skillDirs.length;
 
 // JSON manifests: extract the "N skills" number from the description field.
+// v0.59.0：扫描面扩展至全部含计数的宿主 manifest——此前仅覆盖 2 个 JSON + 2 个 md，
+// 其余 10+ 处靠人工，是「计数漂移反复发生」的根因（0.58.0 漏 13+ 处、0.59.0 又漏
+// INSTALL.md / platform-matrix.md / usage-guide.md 共 3 文件）。path 支持嵌套与数组下标。
 const SKILL_COUNT_JSON_CHECKS = [
   { file: 'plugin.json', path: ['description'], extract: /(\d+) skills/ },
   { file: '.claude-plugin/plugin.json', path: ['description'], extract: /(\d+) skills/ },
+  { file: '.claude-plugin/marketplace.json', path: ['description'], extract: /(\d+) skills/ },
+  { file: '.claude-plugin/marketplace.json', path: ['plugins', '0', 'description'], extract: /(\d+) skills/ },
+  { file: '.cursor-plugin/plugin.json', path: ['description'], extract: /(\d+) skills/ },
+  { file: '.cursor-plugin/marketplace.json', path: ['plugins', '0', 'description'], extract: /(\d+) skills/ },
+  { file: '.codex-plugin/plugin.json', path: ['interface', 'longDescription'], extract: /(\d+) skills/ },
+  { file: 'gemini-extension.json', path: ['description'], extract: /(\d+) skills/ },
+  { file: 'package.json', path: ['description'], extract: /(\d+) skills/ },
 ];
 
 for (const check of SKILL_COUNT_JSON_CHECKS) {
@@ -123,11 +136,20 @@ for (const check of SKILL_COUNT_JSON_CHECKS) {
       errors.push({ file: `${check.file} [${check.path.join('.')}]`, found: 'PATTERN_NOT_MATCHED', expected: ACTUAL_SKILL_COUNT });
     } else if (Number(match[1]) !== ACTUAL_SKILL_COUNT) {
       if (AUTO_FIX) {
-        // Auto-fix: update skill count in JSON
+        // Auto-fix: update skill count in JSON.
+        // v0.59.0 修复：原实现只写顶层键（把 path[0] 直接赋成新值），对嵌套路径
+        // （plugins[0].description、interface.longDescription）会把父级整体覆盖成字符串 → 毁文件。
+        // 改为按完整路径回溯写回，并在路径不可写时显式报错而非静默跳过。
         const newVal = val.replace(check.extract, `${ACTUAL_SKILL_COUNT} skills`);
-        obj[check.path[0]] = newVal;
-        writeFileSync(fp, JSON.stringify(obj, null, 2) + '\n', 'utf-8');
-        fixes.push(`${check.file}: ${match[1]} → ${ACTUAL_SKILL_COUNT}`);
+        let target = obj;
+        for (let i = 0; i < check.path.length - 1; i += 1) target = target?.[check.path[i]];
+        if (target && typeof target === 'object') {
+          target[check.path[check.path.length - 1]] = newVal;
+          writeFileSync(fp, JSON.stringify(obj, null, 2) + '\n', 'utf-8');
+          fixes.push(`${check.file}: ${match[1]} → ${ACTUAL_SKILL_COUNT}`);
+        } else {
+          errors.push({ file: `${check.file} [${check.path.join('.')}]`, found: 'FIX_PATH_UNWRITABLE', expected: ACTUAL_SKILL_COUNT });
+        }
       } else {
         errors.push({ file: `${check.file} [${check.path.join('.')}]`, found: match[1], expected: ACTUAL_SKILL_COUNT });
       }
@@ -138,9 +160,17 @@ for (const check of SKILL_COUNT_JSON_CHECKS) {
 }
 
 // Text files: extract the documented skill count.
+// v0.59.0：新增 usage-guide / platform-matrix / INSTALL.md（后者 3 条精确规则——不能用全局
+// 「N 个 skill」替换，因为 :797 的「其余 27 个」是 count-1，会被误改）。
 const SKILL_COUNT_TEXT_CHECKS = [
   { file: 'README.md', extract: /(\d+) skills/, replace: (content, count) => content.replace(/(\d+) skills/, `${count} skills`) },
   { file: 'AGENTS.md', extract: /Skills 索引（(\d+) 个）/, replace: (content, count) => content.replace(/Skills 索引（(\d+) 个）/, `Skills 索引（${count} 个）`) },
+  { file: 'docs/usage-guide.md', extract: /(\d+) 个 skills/, replace: (content, count) => content.replace(/(\d+) 个 skills/, `${count} 个 skills`) },
+  { file: 'docs/platform-matrix.md', extract: /(\d+) 个 skill 部署/, replace: (content, count) => content.replace(/(\d+) 个 skill 部署/, `${count} 个 skill 部署`) },
+  { file: 'INSTALL.md', extract: /应有 (\d+) 个 skill 目录/, replace: (content, count) => content.replace(/(\d+) 个 skill 目录/g, `${count} 个 skill 目录`) },
+  { file: 'INSTALL.md', extract: /包含 (\d+) 个 skill、/, replace: (content, count) => content.replace(/(\d+) 个 skill、/, `${count} 个 skill、`) },
+  { file: 'INSTALL.md', extract: /← (\d+) 个 skill（/, replace: (content, count) => content.replace(/← (\d+) 个 skill（/, `← ${count} 个 skill（`) },
+  { file: 'docs/release-checklist.md', extract: /all (\d+) skills/, replace: (content, count) => content.replace(/all (\d+) skills/, `all ${count} skills`) },
 ];
 
 for (const check of SKILL_COUNT_TEXT_CHECKS) {

package/scripts/guard/checks/dp3-approved.mjs

@@ -7,7 +7,7 @@ export function checkDp3Approved(changeDir) {
   if (!decision) {
     return {
       pass: false,
-      failures: ['DP-3 (dp_3_result) is not recorded — minimal contract approval is required before hotfix build'],
+      failures: ['DP-3 (dp_3_result) is not recorded — contract approval is required before build'],
     };
   }
 

package/scripts/guard/guard.mjs

@@ -33,7 +33,13 @@ const TRANSITION_CHECKS = {
   //（arch_baseline 缺失 → WARN 不 FAIL，项目级豁免）。
   'exploring:specifying':           ['arch-design', 'arch-readiness'],
   'specifying:bridging':            ['artifacts-exist', 'schema-valid'],
-  'bridging:approved-for-build':    ['artifacts-exist', 'schema-valid', 'contract-fresh', 'dp-gate-passed'],
+  // v0.59.0（decision-surrogate P4 审查发现）：**dp3-approved 新增**——原状 full 该转换只查
+  // dp-gate-passed（仅要求 dp_3_result 非空），而取值严格校验的 dp3-approved 只挂在 hotfix
+  // （见下方 WORKFLOW_TRANSITION_CHECKS）→ **安全档位倒置**：更重要的 full 用弱校验。后果是
+  // 任何能写 dp_3_result 的主体（含夜间替身的 HOLD 落盘）都能让 change 呈现"已批准"假象，
+  // 从而在无真实批准的前提下跨过 DP-3 硬门。本维度要求取值以 "approved" 开头
+  // （判据实现见 checks/dp3-approved.mjs）。
+  'bridging:approved-for-build':    ['artifacts-exist', 'schema-valid', 'contract-fresh', 'dp-gate-passed', 'dp3-approved'],
   // v0.13 §49：test-matrix-ready 门禁前移——full 模式进入 executing 前强制测试准备度
   //（矩阵存在非空 OR 显式 skip 附理由；legacy 豁免）。hotfix/tweak 沿用 §45.3 豁免，不挂。
   'approved-for-build:executing':   ['artifacts-exist', 'contract-fresh', 'dp-gate-passed', 'execution-plan-ready', 'test-matrix-ready'],

package/scripts/lib/cmd-state.mjs

@@ -18,15 +18,18 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const SETTABLE_FIELDS = [
   'workflow', 'batches_completed', 'spec_merged',
   'dp_0_decisions', 'dp_0_confirmed', 'dp_0_timestamp', 'dp_0_result',
-  'dp_1_result', 'dp_1_timestamp', 'dp_1_decisions', 'dp_1_confirmed',
-  'dp_2_result', 'dp_2_timestamp', 'dp_2_decisions', 'dp_2_confirmed',
-  'dp_3_result', 'dp_3_timestamp', 'dp_3_decisions', 'dp_3_confirmed',
+  // v0.59.0（P4 实测）：dp_{1,2,3,5,6,7}_decisions / _confirmed 共 12 个字段已移除——
+  // 它们虽在旧白名单内，但 writeState 无对应序列化分支，tf state set 会**回显成功却零写入**
+  // （静默假成功；全仓零消费者）。dp_0_decisions / dp_0_confirmed 保留（二者确有序列化分支）。
+  'dp_1_result', 'dp_1_timestamp',
+  'dp_2_result', 'dp_2_timestamp',
+  'dp_3_result', 'dp_3_timestamp',
   // v2.1 §6.6/§6.7：GLAF4 委托决策与状态位（dp_4_result 仍由 tf execution plan --confirm 程序化写入，不在列表）
   'dp_4_glaf4_mode', 'dp_4_write_set_hash',
   'delegation_status', 'delegation_retry_count', 'delegation_partial_writes',
-  'dp_5_result', 'dp_5_timestamp', 'dp_5_decisions', 'dp_5_confirmed',
-  'dp_6_result', 'dp_6_timestamp', 'dp_6_decisions', 'dp_6_confirmed',
-  'dp_7_result', 'dp_7_timestamp', 'dp_7_decisions', 'dp_7_confirmed',
+  'dp_5_result', 'dp_5_timestamp',
+  'dp_6_result', 'dp_6_timestamp',
+  'dp_7_result', 'dp_7_timestamp',
   // Architecture design gate (v0.9 §26, v0.22.5 评审修复 F02)
   'arch_design_decision', 'arch_design_reason',
   'arch_design_timestamp', 'arch_design_artifacts',

package/scripts/lib/cmd-version.mjs

@@ -31,6 +31,10 @@ const TEXT_FILES = [
   { file: 'llms.txt',               pattern: /(Current version: v)\d+\.\d+\.\d+(\.)/g,             replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
   { file: '.claude/always/phase-guard.md', pattern: /(# team-flow v)\d+\.\d+\.\d+( \|)/g,      replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
   { file: 'GEMINI.md',              pattern: /(# team-flow v)\d+\.\d+\.\d+( \|)/g,              replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  // v0.60.0：补 usage-guide 的**同步面**——v0.59.0 只把它纳入检出（check-version-consistency.mjs），
+  // 漏了本列表，导致升版时「package.json 已改但 usage-guide 未同步 → 检出失败 → npm version 非 0 退出」
+  // 的脏状态。检出与同步现已同源（两处 pattern 对应同一锚点）。
+  { file: 'docs/usage-guide.md',    pattern: /(版本锚点：v)\d+\.\d+\.\d+/g,                     replacement: '$1%MAJOR%.%MINOR%.%PATCH%' },
   { file: 'skills/workflow-start/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)\d+\.\d+\.\d+( tf)/g, replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
   { file: 'skills/need-explorer/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)\d+\.\d+\.\d+( tf)/g, replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
   { file: 'skills/spec-writer/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)\d+\.\d+\.\d+( tf)/g, replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },

package/skills/jarvis/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: jarvis
+description: This skill should be used when the user asks to "启动 Jarvis", "让 Jarvis 接手决策", "我要睡了，今晚把 X 推下去", "睡前布置任务", "jarvis mode", or wants an agent to take over team-flow decision points — whether away (overnight handoff) or present (to offload decision bandwidth). It loads the user's decision-preference library and a Jarvis home, dispatches workers via Orca orchestration on team-flow projects, adjudicates pre-authorized decision points, and delivers a decision log. Optional, opt-in only.
+---
+
+# Jarvis（team-flow 决策代理）
+
+作为 **team-flow 工作流**的决策代理：在用户设定的授权范围内代做决策点裁决，缓解决策带宽瓶颈。Jarvis 派 worker 跑工作流、裁决**可代答**的决策点、其余一律 HOLD 交回用户。
+
+**两种典型场景**：
+
+| 场景 | 形态 |
+|------|------|
+| **夜间 / 离席值守**（核心） | 睡前逐点预授权 → 夜间派 worker → 裁决可代答点、其余 HOLD → 早上交付汇总 |
+| **在场分流** | 用户在时也先过一遍决策点，只把 HOLD 项交给人 —— 减少打断 |
+
+**核心边界**：Jarvis 只做决策与编排——**不写产线代码、不改 team-flow 状态文件（`.team-flow.yaml`）、不发明任务方向**。（「不改状态文件」专指 team-flow 的门禁真相源；Jarvis 自己的 `state/*.log|md` 当然要写。）
+
+> **与 firstmate 的分工**：Jarvis 是 **team-flow 专用**的决策代理，深度集成状态机 / 决策点 / 门禁；通用跨项目的「大副」角色由 firstmate 承担。两者不重叠——Jarvis 不做通用编码、调查或审计工作。
+
+> **命令形态以官方为准**：本文命令随 Orca 版本演进，**运行前先读一次** `orca skills get orchestration`，不要凭记忆推断子命令或参数——v0.60.0 实测暴露的 skill 缺陷之一即命令形态错误。
+
+## 何时使用
+
+- 用户要睡前（或离席前）布置任务，希望期间持续推进
+- 用户在场，但希望将某 change 的决策点分流给 Jarvis 处理
+- 当前会话承担 Jarvis 角色（本 skill 由主会话加载，不是 dispatch 的子代理）
+
+## Phase 0：首次接入（环境前置检查 + 初始化）
+
+**每次启动先跑检查**；缺项即引导补齐，**不降级、不跳过**。完整检查矩阵、初始化步骤与偏好库访谈问题见 `references/onboarding.md`。
+
+| 检查项 | 命令 / 判据 | 缺失时 |
+|--------|-----------|--------|
+| **shell 启动无交互提示** | 新开终端不停在等待输入；shell 配置无更新检查 / read | **派发会静默失败**——见「硬约束」 |
+| **目标目录已被 claude 信任** | `~/.claude.json` → `projects["<路径>"].hasTrustDialogAccepted == true` | 预置该字段（**先备份**），否则首次派发必失败 |
+| Orca CLI | `which orca` | `brew install orca` |
+| Orca runtime | `orca status --json` → `result.runtime.state == "ready"` | `orca open` |
+| orchestration 可用 | `orca orchestration run-list --json` → `ok: true` | 开启 Settings → Experimental |
+| 已绑定 Run | `orca orchestration run-current --json`（或可 `run-create` 绑定） | 须在 **Orca 管理的终端**内运行 |
+| 可用项目 | `orca worktree list --json` | `orca repo add --path <路径>` |
+| 偏好库 | `~/.claude/lt-preferences/decision-preferences.md` 存在 | 走 onboarding.md §2 |
+| Jarvis home | 用户指定（默认 `~/jarvis-home/`）含 `state/` | 创建 + `git init`（onboarding.md §3） |
+| 项目空间判据 | 目标含 `.team-flow/` + `changes/` | **拒绝派发**（普通模式本期不支持） |
+| 机器不休眠 | `pmset -g` 的 `sleep` 为 0 且 `pgrep -x caffeinate` 有进程 | `caffeinate -i` |
+
+**并取得自身会话名**（反向寻址的前提）：`ListAgents` 的首行 `This session is <name>` 即本会话名。**崩溃恢复后须重新取得**（重启即新会话，名可能变）。
+
+探测结果向用户报告一张「就绪 / 待补齐」清单，补齐后方可进 Phase 1。
+
+## Phase 1：睡前授权（用户在场，约 5 分钟）
+
+1. 接收任务：项目空间、change、完成标准
+2. **预案扫描**：读 change 现状 + 偏好库，列出预期决策点及其默认裁决，一并确认**架构门状态**与**执行模式**（两者决定夜间能走多远）
+3. **读回**：把任务 + 逐点授权 + 红线完整读给用户
+4. **落盘**：用户确认后写 `state/mandate-<YYYY-MM-DD>.md`（模板见 `references/protocols.md`，**须含 Jarvis 会话名字段**）
+5. **派发**：`run-create` → `task-create --spec <...>` → `worker-start --task <id> --worktree "path:<项目根>" --agent claude`
+   - task spec **必须含五条硬指令**（完整措辞见 `references/protocols.md` §二）：① **禁止使用 AskUserQuestion**；② 决策点一律 `orca orchestration ask` 转 Jarvis（**须补 `--from` / `--dispatch-capability` 鉴权参数**）；③ **`ask` 超时禁止自行裁决**——保留 message_id 用 `--resume` 续等，续等仍超时则停并上报；④ 完成或阻塞时用 `send --type worker_done` 上报；⑤ **附上 Jarvis 会话名**，供 worker 启动后主动联系（反向寻址）
+
+## Phase 2：夜间值守
+
+### 主循环（worker 提问 → 代答）
+
+1. `orca orchestration check --wait --types question,worker_done,escalation --timeout-ms 600000 --json`
+2. 逐条处置：
+   - `question` → 按 `references/decision-points.md` 三档裁决 → `orca orchestration reply --id <msg_id> --body "<答复>"`（代答）或 `--body "HOLD: <原因>"`
+   - `worker_done` → **先选定该 worker 终端的归宿**（官方强制：不得留活终端）：有后续 task 则 `worker-start --task <next> --terminal <worker.agent_terminal_handle>` 复用，否则 `orca orchestration worker-release --dispatch <id>`
+   - `escalation` → 记入早报「等你决定」
+3. **每个裁决即时写日志**（不等收工）：`state/decisions-<YYYY-MM-DD>.log`
+4. 处理完再确认：`orca orchestration check --ack <delivery_id> --wait ...`
+
+> **走 `ask` 还是等 worker 主动？** 二者的分野不在命令，而在**接收端是否有进程阻塞等待**：worker 阻塞在 `ask` 时消息必达；worker settle 后则无人读邮箱。
+
+### 唤醒通道（worker 已停）
+
+**`send --to dispatch` 唤醒已实证不可用**（消息 `read=0` 永久滞留邮箱）→ 改用 Claude Code 原生 **`SendMessage`**：
+
+- **发现**：`ListAgents` 能看到本机所有会话，含 Orca 派发的 worker
+- **唤醒 / 追问**：`SendMessage(to: <worker 会话名>)`——**已实测可唤起 idle 会话**
+- **反向寻址**：worker 会话名随机，Jarvis 无法预知 → 由 worker 启动后主动联系 Jarvis（task spec 已附 Jarvis 会话名；worker 侧地址来自其 session 的 `from=`）
+- **不可达时退化**：重新派发（`worker-start` 新 task，已实证可行，代价是原 worker 上下文丢失）
+
+### 异常处置
+
+5. **`check` 超时未收到 `worker_done`**：`worker-show --dispatch <id>` 判状态——
+   - `ready` → 继续等（长任务常态）
+   - `failed` / `stopped` → **先 `orca orchestration task-update --id <t> --status ready`**（失败会连坐 task，否则报 `task_not_startable`），再 `worker-start --task <t> --retry-of <dispatch> --on <saved-environment> --worktree <...> --agent claude`（`--task` 为必填；`--retry-of` **不继承位置**，须显式重复三个参数）
+   - `outcome_unknown` → `worker-stop --dispatch <id>` 后检查
+   - worker 停在 `observation.agentWait` 是**健康态**，不是故障
+   - 每次判状态后追加 `health` 日志行
+6. **Jarvis 自身异常恢复**（通道堵死 / 会话崩溃）：
+   - **通道停更判据**：`check --wait` 连续 2 次满超时（各 10 分钟）且期间零消息 → 记 `health` 行 `channel_stalled`，改用 `worker-show --dispatch <id>` 逐个轮询
+   - **崩溃恢复**：状态**只在磁盘**——重入时先读 `state/mandate-<date>.md` + `decisions-<date>.log`，再用 `worker-show` 逐个对账 dispatch 状态，**禁止凭记忆续跑**
+   - **会话名核对**（反向寻址的持久性）：重启后 `ListAgents` 重新取得自身会话名；**若与 mandate 记录不同，旧地址已失效** → 用 `ListAgents` 反查 worker 会话名后主动联系，或让 worker 重新上报
+
+**裁决依据优先级（高→低）**：授权书红线 > 授权书逐点授权 > 偏好库条目 > 可推断。
+**冲突时红线优先**（例如偏好库里「收尾即提交推送」在夜间不适用，一律不 push）。
+
+## Phase 3：早上交付
+
+从决策日志渲染早报 `state/report-<YYYY-MM-DD>.md`（格式见 `references/protocols.md`），六段式：① 夜间健康度 ② 各 change 进度 ③ 我替你做的决策 ④ 等你决定的 ⑤ 试过但失败的 ⑥ 成本。
+
+**早报必须逐条列出 HOLD 项**，每项附「问题 + 选项 + Jarvis 倾向 + 依据」，便于用户批量裁决。
+
+## 硬约束
+
+- **禁止 AskUserQuestion**：`agent_prompt_stalled` 在**派发阶段**最常见的触发点是 **shell 启动期的交互提示**（2026-09-12 实测：oh-my-zsh 更新提示吃掉 `claude` 命令首字母 → 实际执行 `laude`），故障发生在 worker 真正启动**之前**，报错完全不指向真因。**注意**：运行中弹 TUI 模态是另一触发点，同样无自动化手段可救——该结论**未被推翻**
+- **Jarvis 不改 team-flow 状态文件**：决策点状态由 worker 经 `tf state set` 写入（`dp_4_result` 由 `tf execution plan --confirm` 程序化写入，不可 set；**HOLD 场景不写任何决策点字段**——12 个字段已于 v0.59.0 移出白名单，写入即**显式报错**，见 `references/protocols.md` §三）
+- **HOLD 是主要形态**：无法代答的点一律 HOLD，**不得静默放行**
+- **不做沉默即同意**：`ask` 超时不产生默认裁决，保留 thread id 待恢复
+- **不假设未验证的机制**：worker 遵循指示是靠 task spec 约束的运行时行为；每次任务须核对早报与**决策日志 + change 的 `state` 位置**是否一致（字段能否落盘须实测，勿据白名单推断）
+
+## 参考文件
+
+- **`references/onboarding.md`** — 首次接入：环境检查矩阵、偏好库初始化（三种方式）、Jarvis home 初始化、就绪检查
+- **`references/decision-points.md`** — 9 个决策点 + 5 个确认点的代答权限、三档处置规则、夜间红线清单
+- **`references/protocols.md`** — 授权书模板、worker task spec 模板、HOLD 六步协议、**决策日志与早报格式**

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

@@ -0,0 +1,87 @@
+# 决策点代答权限与处置规则
+
+> 来源：工作区仓 `docs/plan/jarvis-design.md`（v4.2 §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 确认 | `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/jarvis/references/onboarding.md

@@ -0,0 +1,95 @@
+# 首次接入：环境检查与初始化
+
+> 目标：把「一台裸机 + 一个想用 Jarvis 的人」带到可启动状态。全部检查**只读**；所有写操作（建目录、写偏好库、改信任配置）**先向用户说明再执行**。
+
+## 1. 环境检查矩阵
+
+按顺序执行，记录每项状态；任何一项不可用都应给出**具体引导命令**，而非笼统报错。
+
+### 1.1 派发前置项（v0.60.0 新增，据 2026-09-12 实测）
+
+**这两项不满足时 worker 派发会静默失败**，且报错（`agent_prompt_stalled`）完全不指向真因——**故障发生在 worker 真正启动之前**。
+
+| # | 检查项 | 命令 / 判据 | 缺失时的引导 |
+|---|--------|-----------|-------------|
+| P1 | **shell 启动无交互提示** | 新开一个终端，观察是否停在等待输入（如更新提示）；检查 shell 配置有无更新检查 / `read` | 关闭自动更新检查（如 oh-my-zsh 的 `DISABLE_UPDATE_PROMPT` / `DISABLE_AUTO_UPDATE`）。**修复后仅对新建终端生效**，已存在的终端不受影响 |
+| P2 | **目标目录已被 claude 信任** | `~/.claude.json` → `projects["<路径>"].hasTrustDialogAccepted == true` | 预置该字段（**先备份** `~/.claude.json`；并发 claude 进程可能覆盖配置，改完尽快验证） |
+
+> **实测教训（2026-09-12）**：oh-my-zsh 更新提示吃掉 Orca 注入的 `claude` 命令首字母 → 实际执行 `laude` → claude 从未启动 → task spec 落进 shell。造成 **5 次连续派发失败**。
+> **现场特征**：spec 文本落在 shell 上（`zsh: parse error`）、启动命令被吃字符（`command not found: laude`）。**见到这两个特征先查 shell 提示，不要先怀疑 Orca。**
+
+### 1.2 环境项
+
+| # | 检查项 | 命令 | 就绪判据 | 缺失时的引导 |
+|---|--------|------|---------|-------------|
+| 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 | Jarvis home | `test -d <home>/state` | 目录存在 | 走 §3 |
+| 9 | 机器不休眠 | `pmset -g` 的 `sleep` 为 0；`pgrep -x caffeinate` 有进程 | 两者满足 | `caffeinate -i`（前台保持）；或说明夜间须保持机器唤醒 |
+
+**输出**：一张「就绪 / 待补齐」清单交给用户，**补齐后才进 Phase 1**。
+
+## 2. 偏好库初始化（三种方式，按投入递增）
+
+偏好库是 Jarvis 判断力的唯一来源；**没有它就不要启动**（否则只能全量 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：从历史会话挖掘（最完整，成本最高）
+
+适用：用户已积累数月会话记录，希望 Jarvis 更贴近本人。
+
+1. 定位会话：`~/.claude/projects/<按路径转义的项目目录>/*.jsonl`
+2. 提取人类输入（过滤 `tool_result`、以 `<` 开头的注入块、上下文压缩摘要、skill 内容）
+3. 分片派**独立子代理**提炼：新偏好 / 已有偏好的新证据 / 矛盾证据
+4. 合并去重后落盘，标注置信度与出处
+
+**建议**：先用 A+B 起步运行，积累几周后再用 C 做一次深度校准。
+
+## 3. Jarvis home 初始化
+
+```bash
+mkdir -p <home>/state
+cd <home> && git init
+```
+
+- 默认路径 `~/jarvis-home/`（用户可指定其他路径）
+- `state/` 承载：授权书 `mandate-<date>.md`、决策日志 `decisions-<date>.log`、早报 `report-<date>.md`、任务队列 `queue.md`
+- home **与业务项目解耦**；偏好库不放这里（它在 `~/.claude/lt-preferences/`，属用户级、跨项目可用）
+- 建议在 home 下加 `.gitignore`，排除实测沙箱等临时目录
+
+## 4. 就绪检查（进 Phase 1 前）
+
+- [ ] **派发前置项 2 项**（shell 提示 / 目录信任）
+- [ ] 环境项 9 项全部就绪
+- [ ] 偏好库存在且非空（≥1 条）
+- [ ] Jarvis home 存在且含 `state/`
+- [ ] 用户已确认目标项目空间与 change
+
+全部打勾后，向用户复述一次本次任务的**范围与红线**，再进 Phase 1。

package/skills/jarvis/references/protocols.md

@@ -0,0 +1,126 @@
+# 协议模板集
+
+> **命令形态以官方为准**：本文件与 SKILL.md 中的 `orca` 命令随 Orca 版本演进。**运行前建议先读一次版本匹配的官方指南**（`orca skills get orchestration`），不要凭记忆推断子命令或参数——v0.60.0 实测暴露的 4 处 skill 缺陷之一即命令形态错误（`orca ask` 简写不存在）。
+
+## 一、授权书模板 → `state/mandate-<YYYY-MM-DD>.md`
+
+```markdown
+# 授权书 <日期> ｜ change：<name>
+
+## 任务
+- 项目空间：<路径>
+- change：<name>
+- 完成标准：<可验证的完成条件>
+- **架构门状态：已过 / 未过**（未过则夜间止于 exploring）
+- 需求范围：<scope 摘要，供 DP-1 条件代答判据>
+- **执行模式：<TDD|SDD|inline|不指定>**（不指定则夜间止于 approved-for-build）
+- **Jarvis 会话名：<name>**（供 worker 主动联系用。**崩溃恢复后须核对是否仍有效**——重启即新会话、名可能变，失效时应让 worker 用 `ListAgents` 反查并重新上报，详见 §二「反向寻址」）
+
+## 逐点授权
+| 决策点 | 授权 | 条件 |
+|--------|------|------|
+| 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`
+   转给协调者（Jarvis），等待 reply 后再继续。
+   ⚠️ 须带鉴权参数 `--from` 与 `--dispatch-capability` —— 裸命令返回 `dispatch_capability_invalid`
+   （2026-09-12 实测）。两个值见你启动时收到的 preamble；无从获取时向 Jarvis 求助，**不要猜测**。
+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 "<三句话：做了什么、发现了什么、还剩什么>" --task-id <注入的 taskId> --dispatch-id <注入的 dispatchId> --json`
+   报告，随后结束本轮。**必须带 `--task-id` / `--dispatch-id`**——Orca 据此自动结算 task（不带则 task 不会自动完结）。两个 ID 使用 Orca 启动时注入的值，**不要自行编造**。
+5. **启动后主动联系 Jarvis**：用 SendMessage 向会话 `<Jarvis 会话名>` 发送
+   「worker 已就绪，工作目录 <路径>」。这一步让 Jarvis 得知你的会话名，
+   后续才能唤醒你（worker 会话名随机，Jarvis 无法预知 —— 反向寻址）。
+
+【红线 — 绝对禁止（违反即停）】
+- `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`）。
+> **派发失败的现场特征见 SKILL.md「硬约束」**——`agent_prompt_stalled` 多由 shell 启动期提示或目录未信任所致，**不是 Orca 故障**。
+
+## 三、HOLD 协议（worker 侧六步）
+
+| 步骤 | 动作 |
+|------|------|
+| ① Jarvis 裁决 | `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 个）**已于 v0.59.0 移出 `cmd-state.mjs` 的 `SETTABLE_FIELDS` 白名单**——写入即显式报错 `⛔ Field '...' is not settable` 并以非 0 退出（**原为「回显 ✅ 却零写入」的静默假成功，v0.59.0 P4 实测后改为 fail-loud**；`dp_0_decisions`/`dp_0_confirmed` 不在移除之列，二者确有序列化分支）。HOLD 的持久锚点 = 步④ 的 escalation 消息 + 步⑥ 的 Jarvis 决策日志 + change 的 `state` 仍停在门禁前（客观事实）。**约束**：不得新建 `changes/<name>/` 下任何文件（Artifact Ownership：「主会话」此处指 **worker 侧**的主会话——它 MUST NOT 直接 Edit/Write `changes/` 或 `.worktrees/`；与 Jarvis 侧会话无关） |
+| ④ worker 上报 | `orca orchestration send --type escalation --subject "HOLD at <门>" --body "<摘要>" --json` |
+| ⑤ worker 处置 | 用 `orca orchestration worker-retain --dispatch <id>` 标记保留（**不可用 `worker-release`**——官方禁止因 escalation/question/idle 释放）。**语义澄清**：`worker-retain` 的官方定位是 "keep one supervised worker terminal live for debugging"，**HOLD 保活属借用**该语义；保活效果与普通 settled 态的差异尚未实测（设计文档 §7.5 ⑪） |
+| ⑥ Jarvis | 写决策日志 + 早报「等你决定」段（问题/选项/Jarvis 倾向/依据/msg_id） |
+
+**多任务**：一个 HOLD 不阻塞其他 worker。
+**早上恢复**：用户批阅早报 → 给出裁决 → **用 `SendMessage` 投递到该 worker 会话** → worker 解除 HOLD 继续。
+
+> **为何不是 `send --to dispatch`**：2026-09-12 实测证明**该路径不可用**——HOLD 时 worker 已 settle（不在阻塞等待态），消息 `read=0` 永久滞留邮箱。改用 SendMessage（同场景实测可唤起 idle 会话）。
+> **⚠️ 待补验**：HOLD 的 `worker-retain` 保活态与实测的普通 settled 态**是否等价尚未验证**。补验前**先试 SendMessage，失败则退化为重新派发**（已实证可行，代价是上下文丢失）。
+
+## 四、决策日志格式 → `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`
+
+```
+# Jarvis 早报 <日期>
+
+## ① 夜间健康度
+心跳时间戳范围 / 是否卡过 / 有无告警
+
+## ② 各 change 进度
+| change | 停止位置 | 推进步数 | 隔离位置 | diff 摘要 |
+
+## ③ 我替你做的决策
+| 时间 | change | 决策点 | 选择 | 理由 | 依据 | 置信 |
+
+## ④ 等你决定的（HOLD）
+| 决策点 | 问题 | 选项 | Jarvis 倾向 | 依据 | 恢复命令 |
+（逐条列全，便于批量裁决）
+
+## ⑤ 试过但失败的
+## ⑥ 成本
+```
+
+**渲染原则**：从决策日志渲染，**不从对话记忆渲染**（抗压缩、可审计）。

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> 更新。