harveyz-skill 0.32.0 → 0.33.0

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.33.0] - 2026-09-15
+
+### Added
+- `store_config.py`（`learn-video`/`clip-url`/`sync-xtimeline`/`sync-ytchannel`/`sync-website` 共用）：新增 `check-downstream`，核对统一存储根的产物与 vdl / scholia 两个下游读取方是否同步，五份 SKILL.md 的前置检查步骤接入该核对
+
+### Changed
+- `handoff`（1.8.0 → 1.11.0）：新增 Phase 2.5 接手方自测闸门 + 打回复修回路（此前「接手方完工 → 待验收」这个状态转移毫无前置条件）；建工作区改为显式给基线分支并 `EnterWorktree(path:)` 进去，三方指令统一，修复了两次因裸 git 命令落到主工作树而夹带他人未合并提交的翻车；关闭 `using-git-worktrees` 前置调用（它会另起一个 `.worktrees/` 下的第二工作区，与 handoff 自己的工作区约定冲突）；平台专属指令（`EnterWorktree` 等 Claude Code harness 特性）拆进独立「平台适配」章节，避免 pi/hermes/Codex 上的接手方读到卡住
+- `publish-skill` 审计：`init-skill`（1.2.0→1.2.1）、`learn-skill`（2.0.0→2.0.1）、`research/survey-skillrepo`（2.0.1→2.0.2）——内容已变但 version 未 bump，属于 F8 硬性检查项，现已按 patch 补齐；另有 6 个 skill（`handoff`/`sync-website`/`sync-xtimeline`/`sync-ytchannel`/`clip-url`/`learn-video`）此前 version 已 bump 但 `skills-index.json` 里的 `contentHash` 记录没跟上，已同步
+
+### Fixed
+- `learn-video` / `clip-url` / `sync-xtimeline` / `sync-ytchannel` / `sync-website` 共用的 `knowledgeRoot` 默认建议路径从 `~/Documents/knowledge` 改为 `~/knowledge`：前者在无 Full Disk Access 的 agent 执行环境下写入会静默失败，且此前没有护栏阻止 agent 擅自把配置改到别的路径绕过，导致产物在用户不知情的情况下分裂到两个根目录；五份 SKILL.md 加"写入失败必须如实报告并停下问用户"的护栏指令
+- `tests/install.bats` / `tests/interactive.bats`：`survey-skillrepo` 测试夹具的硬编码版本号随上面的 F8 审计一并更新为 `2.0.2`，此前的 bump 一度导致 3 个断言失败
+
 ## [0.32.0] - 2026-09-07
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harveyz-skill",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "Skill manager for Claude Code, Cursor, Codex, OpenClaw, Hermes, OpenCode, and Pi",
   "type": "module",
   "bin": {

package/skills/coding/handoff/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: handoff
-description: Use when handing a task across sessions — writing a self-contained handoff doc for a fresh session to pick up (author), sanity-checking an inbound handoff before starting (verify), or accepting completed work against the criteria agreed at handoff time (accept). Triggers on phrases like "write a handoff", "hand this off", "pick up this task", "sign off on this work". Generic skill — project-specific conventions are read from .hskill/handoff/config.md.
-version: "1.8.0"
+description: Use when handing a task across sessions — writing a self-contained handoff doc for a fresh session to pick up (author), sanity-checking an inbound handoff before starting (verify), self-testing against the agreed criteria before reporting the work done or re-submitting after a rejection (self-test), or accepting completed work against the criteria agreed at handoff time (accept). Triggers on phrases like "write a handoff", "hand this off", "pick up this task", "sign off on this work". Generic skill — project-specific conventions are read from .hskill/handoff/config.md.
+version: "1.11.0"
 user_invocable: true
 ---
 
@@ -15,6 +15,10 @@ user_invocable: true
 2. 文本未指明 → 看上下文：刚做完规划 → author；拿到别人的交接文档准备开工 → verify；接手方回报完成、要核收 → accept。
 3. 仍不确定 → **问用户，不猜**。
 
+**Phase 2.5（自测）没有对应的斜杠命令**，因为它不是谁"调"出来的：接手方干完活、准备把
+`status` 推到「待验收」的那一刻就该执行它，被打回后复修完再执行一遍。它写在 Phase 2 与
+Phase 3 之间。
+
 判定后跳到对应 phase 段执行。
 
 ## Phase 1 — author（写交接）
@@ -30,8 +34,15 @@ user_invocable: true
    分支和 worktree 都由**你**建好，不留给接手方建。这是整条交接链能闭环的关键——工作区是你建的，
    你就一直知道它在哪；验收时直接回到这里读那份被接手方改过的文档，不必去别处找、更不必扫描。
    - 已经在一条 feature worktree 里干活 → 就用它，别新建。
-   - 否则 `git worktree add <路径> -b <分支名>`；路径按 `.hskill/handoff/config.md` 的 workflow
-     段给的习惯，没给就自己定一个仓库内的稳定位置。
+   - 否则 `git worktree add <路径> -b <分支名> <基线分支>`；路径按 `.hskill/handoff/config.md`
+     的 workflow 段给的习惯，没给就用 `.claude/worktrees/<分支名把 / 换成 +>`。
+     **基线分支必须显式写出来**（通常是 `staging`）。不写就从主工作树当前 HEAD 拉分支，而主
+     工作树未必停在集成分支上——它可能正停在**别的 session 的分支**上。那样你的新分支会静默
+     夹带别人未合并的提交，合并时等于替对方把没写完的东西发布出去。这种错不会有任何报错，
+     merge 会干净利落地成功。
+   - **建完立刻进去**（怎么进见文末「平台适配」）。不进去的话，你后面每一条不带限定的
+     git 命令都作用在**主工作树**上而不是这个工作区。进不去的平台上，就把「限定到工作区」
+     当成每条命令的硬要求，别靠记性。
    - **建完不要 `git worktree remove`。** 接手方要进来干活，你验收时还要再进来一次。这个工作区
      在整条交接链上一直活着，直到验收通过。
    - 把分支名填进 frontmatter 的 `branch`、工作区**绝对路径**填进 `worktree`。
@@ -57,7 +68,9 @@ user_invocable: true
 
    ```
    接手任务。工作区已建好，不要自己建：
-     cd <worktree 绝对路径>
+     <worktree 绝对路径>
+   按你所在平台的方式进入它（Claude Code 用 EnterWorktree(path: "<路径>")；
+   没有这类能力就每条命令都限定到这个路径，别靠裸 cd）。
    分支 <branch>，已被这个工作区 checkout（git worktree add 会失败，属正常）。
    <若 config.md 的 workflow 段有开工前置命令，原样列在这里>
    交接文档：<相对于工作区的文档路径>
@@ -118,8 +131,9 @@ user_invocable: true
   **只建这一条边。**不要顺带把自己挂到交接源节点实现的需求上（不建 `implements`），也不要调
   `capture-requirement` 另立需求——需求已经挂在交接源节点上，接手节点该不该关联需求是另一个
   问题，不在这次交接的范围内。
-- **进 author 备好的工作区开工**（frontmatter 有 `worktree` 时）：`cd <worktree>`，核对
-  `git rev-parse --abbrev-ref HEAD` 与 `branch` 一致，然后就在这里干活。
+- **进 author 备好的工作区开工**（frontmatter 有 `worktree` 时）：按文末「平台适配」进去，
+  然后核对 `git rev-parse --abbrev-ref HEAD` 与 `branch` 一致，就在这里干活。
+  - **绝不要销毁这个工作区**（`git worktree remove`，或平台的"退出并删除"）——验收还要用。
   - **不要自己 `git worktree add`。** 那条分支已经被这个工作区 checkout 了，再建会直接失败；
     而且你另建一个，原 session 验收时会回到它自己建的那个，看不到你的改动。
   - **不要 `git worktree remove`**，验收还要用。
@@ -128,13 +142,53 @@ user_invocable: true
     改它等于单方面改约。
 - 无缺口 → `status` 置 `执行中`，若文档有「工作流约定」章节按其开工，没有就直接开工。
 
+## Phase 2.5 — 自测（接手方推 `status` 到「待验收」之前的硬闸门）
+
+**「待验收」不是「我改完了」，是「我自己已经按锚点跑过一遍、拿得出结果」。** 这两件事之间
+隔着一整轮 accept：没自测就推上来，红的那条要等 accept 方耗掉整轮才发现，而它本来可以由你
+自己在几分钟内跑掉。
+
+推 `status` 之前做完这四件事，缺一件就别推：
+
+1. **逐条实跑「最小验收锚点」全集**——不是只跑你改动相关的那几条。`acceptance: hard`
+   逐条判对错；`soft` 按其描述做定性判断。文档若还点名了「必须复跑的既有资产」，一并跑。
+   项目自己的验证约定（跑什么测、要不要真产物 E2E）见 `.hskill/handoff/config.md` 的
+   `verification` 段。
+2. **判成败的命令不接管道。** `cmd | tail` 的退出码是 `tail` 的，它恒为 0；输出还被截断，
+   连哪些用例根本没被发现都看不出来——两个信息一起丢。
+3. **结果写成独立小节**，标题形如 `## 接手方自测记录（<日期>）`——**标题里必须有「自测」
+   二字**，`validate-handoff.sh` 按这个词认这一节。逐条列 pass/fail，附实际跑的命令。
+   写进你自己这一节，别混进原 session 的验收记录。
+4. **有红就不许推 `status`。** 两条出路，没有第三条：
+   - 修到绿；
+   - 或者认为那条红不构成未达成（例如它在你动手之前就红），**在自测记录里那一条旁边写出
+     归因证据**（比如在分叉点上跑同一条命令的结果），并显式声明「带着这条红送验」。
+     **沉默地推上来不行**——accept 方一定会跑到它，届时你既丢了一轮，也丢了信用。
+
+自测**不替代** accept：accept 方一律不采信接手方结论、逐条自己重跑（Phase 3）。自测的作用
+是让「送验」这个动作有成本、有记录，不是让 accept 省事。
+
+### 复修轮（被打回之后）
+
+打回不是「改那一条就完事」。范围小、心态是「就改一行」，恰恰是二次打回最常见的来源。
+
+- 复修完**重新走一遍本 phase**，`status` 才能再置回「待验收」。
+- **自测范围默认是锚点全集，不是被打回的那几条。** 要缩小，必须在复修自测记录里给出两样
+  东西：改动范围证据（`git diff --name-only <打回点提交>..HEAD`）+「为什么其余条目不可能
+  被这些改动波及」的论证。给不出就跑全集。
+- 记录**另起一节**，标题形如 `## 接手方复修自测记录（第 N 轮）`，同样必须含「自测」二字。
+  不覆盖、不合并前几轮——几轮并排放着，后来人才看得出哪条判据反复红过。
+- 打回记录点名了修法就照做；**不认同要在复修记录里写出理由退回讨论，不要静默换一种改法**。
+  尤其不要把一条刚开始真的会红的断言改回恒真——那不是修复，是把判据废掉。
+
 ## Phase 3 — accept（原 session 验收）
 
 **先到位，再验收。** 验收在**被验代码所在的工作区**跑——不在主工作树、不在核心分支
 （staging / main / master）上跑。主工作树通常停在集成分支，那里根本没有接手方的改动：
 在那里跑出来的绿是**别的代码的绿**，比不跑更有害，因为它看起来像验过了。
 
-1. **回到交接工作区**：`cd` 进 author 阶段第 4 步建的那个 worktree。路径有三个可能来源，
+1. **回到交接工作区**：按文末「平台适配」进 author 阶段第 4 步建的那个 worktree。
+   路径有三个可能来源，
    哪个在手用哪个——你自己的上下文（你就是 author 时）、用户粘贴的验收指令（author 第 9 步
    输出的那段）、或文档 frontmatter 的 `worktree`（文档已在手时）。三个都没有 → 用
    `git worktree list` 按分支名查回来。确认这次交接根本不涉及独立工作区（同目录同分支续做）
@@ -142,31 +196,82 @@ user_invocable: true
    - **在那里重读一遍交接文档。** 你手上这份可能是 author 时写的旧版；接手方的自测记录、
      `status`、以及被修正过的字段，全都只存在于那个工作区里的那一份。读错版本不会报错，
      只会让你对着过时的内容验收。
-   - 后面**每一条**验收命令都在这个目录里跑（`cd` 进去，或 `git -C <worktree>`）。
+   - 后面**每一条**验收命令都在这个工作区里跑。
    - 路径不在了（被谁 remove 了）→ `git worktree list` 看这条分支现在挂在哪；都没有就用
      `git worktree add --detach <临时路径> <branch>` 重建，验完 remove。**必须带 `--detach`**——
      一条分支不能被两个 worktree 同时 checkout。
    - 跑第一条验收命令之前确认到位：`git -C <验收目录> rev-parse --abbrev-ref HEAD` 落在
      staging/main/master 上，说明你还在主工作树，停下来查，别接着跑。
-2. 找文档里的**最小验收锚点**——这是唯一固定依据。**接手方自填的结论一律不采信，逐条自己跑**：验证产物"存在"不等于"跑得过"，点得出脚本名不等于那个脚本此刻是绿的。frontmatter 的 `acceptance` 指明是哪一档：`hard`（逐条对/错）→ 按锚点描述**逐条实跑**（单测/E2E/核验）；`soft`（定性描述）→ 按其描述做定性判断。字段与锚点正文不符时**以正文为准**并把字段改对——字段是索引，正文才是判据。
-3. 把验收结果（每条 pass/fail，或整体达成/未达成）追加记录到最小验收锚点所在章节末尾。**接手方若已自填过验收记录，另起小节并列，不覆盖也不合并**——两份并排放着，后来人才看得出哪些结论被第二方复核过。其中若有与实跑不符的陈述，**显式写出更正**，不要静默改掉：静默改掉等于把同一个错误留给下一次。
-4. 达成 → `status` 置 `已验收`；未达成 → `status` 置 `打回` 并写明哪里没达成、为什么，退回接手方。
-5. **达成才算真正完成**（硬判据要求逐条全绿；软判据按其描述定性判断是否达成）。
+2. **先跑一次机器校验**：`bash <skill 目录>/scripts/validate-handoff.sh <文档路径>`。
+   `status` 是「待验收」却没有含「自测」的小节 → 脚本直接 exit 1。**这种情况按未达成处理，
+   当场置「打回」退回去，不必开始逐条重跑**：接手方连自己那一遍都没跑，你这一轮多半是在
+   替它跑第一遍。
+
+3. 找文档里的**最小验收锚点**——这是唯一固定依据。**接手方自填的结论一律不采信，逐条自己跑**：验证产物"存在"不等于"跑得过"，点得出脚本名不等于那个脚本此刻是绿的。frontmatter 的 `acceptance` 指明是哪一档：`hard`（逐条对/错）→ 按锚点描述**逐条实跑**（单测/E2E/核验）；`soft`（定性描述）→ 按其描述做定性判断。字段与锚点正文不符时**以正文为准**并把字段改对——字段是索引，正文才是判据。
+4. 把验收结果（每条 pass/fail，或整体达成/未达成）追加记录到最小验收锚点所在章节末尾。**接手方若已自填过验收记录，另起小节并列，不覆盖也不合并**——两份并排放着，后来人才看得出哪些结论被第二方复核过。其中若有与实跑不符的陈述，**显式写出更正**，不要静默改掉：静默改掉等于把同一个错误留给下一次。
+5. 达成 → `status` 置 `已验收`；未达成 → `status` 置 `打回`。打回记录必须写清三件事，
+   缺了接手方只能猜：**哪几条未达成**、**为什么**（判据原文 vs 实跑结果）、以及
+   **复修后要重跑的范围**（默认全集；认为可以只跑子集就在这里点名）。退回接手方后，
+   它重新走 Phase 2.5 才能再置回「待验收」。
+6. **达成才算真正完成**（硬判据要求逐条全绿；软判据按其描述定性判断是否达成）。
 
 ## 状态生命周期
 
-`待执行`（author 写完）→ `执行中`（verify 通过 / 接手方开工）→ `待验收`（接手方回报完成）→ `已验收`（accept 判定达成）/ `打回`（accept 判定未达成，退回执行中）。
+`待执行`（author 写完）→ `执行中`（verify 通过 / 接手方开工）→ `待验收`（接手方**自测通过后**
+回报完成，见 Phase 2.5）→ `已验收`（accept 判定达成）/ `打回`（accept 判定未达成，退回执行中）。
+
+`打回` 之后的回路是闭合的：**接手方复修 → 重新走一遍 Phase 2.5 → 才能再置回 `待验收`**。
+直接从复修跳回「待验收」不算数。
 
-`status` 是三 phase 间唯一协调锚点，无需外部状态存储。
+`status` 是各 phase 间唯一协调锚点，无需外部状态存储。
 
 要扫「哪些交接还没验收」，**别在当前工作树里 grep**——在途交接的文档都在各自的交接工作区里，
 主工作树上那份（如果有）是合并后的历史归档，状态是旧的。正确做法是先 `git worktree list`
 列出所有工作区，再到每个工作区的 `<output_dir>` 里 grep `status`。
 
-**写入权按 phase 分：接手方最多只能把 `status` 推到「待验收」。`已验收` / `打回` 只能由原 session 在 accept 之后写。**
+**写入权按 phase 分：接手方最多只能把 `status` 推到「待验收」，且推之前必须过 Phase 2.5。`已验收` / `打回` 只能由原 session 在 accept 之后写。**
 
-校验脚本查不了这条——它看不出某个值是谁写的。这是约定，靠 accept 方兜底（见本节末）。
+校验脚本查不了「谁写的」——它看不出某个值出自哪一方。这是约定，靠 accept 方兜底（见本节末）。
+它查得了的是「有没有自测记录」：`status` 为「待验收」而正文没有含「自测」的小节，脚本 exit 1。
+这一条堵的是「改完就推」，堵不住「自测跑了但结论是编的」——后者仍然只能靠 accept 方逐条重跑。
 
 这条不是流程洁癖。「已验收」的全部信息量就是**做事的人之外的另一方查过**；做事的人一旦能自己写它，它就退化成「做事的人说做完了」——而这个信息「待验收」里已经有了，两个状态变成同义词，字段失效。风险还会反向放大：一份自填的「已验收」通常附着一张全 PASS 的表，比没有记录更难被怀疑。
 
 接手方若跳档自填，accept 方**按未验收处理**，照常逐条重跑。
+
+## 平台适配（怎么进出交接工作区）
+
+author 之后的每个 phase 都要求"到被验代码所在的工作区里去"。**这个要求是平台无关的，实现手段不是**——
+所以正文只说"进去"，具体动作查本节。你所在的平台不在下表里，按「通用兜底」办。
+
+判据只有一条：**后续命令的工作目录是不是那个工作区**。谁能做到都行。
+
+### Claude Code
+
+| 动作 | 手段 |
+|---|---|
+| 进入 | `EnterWorktree(path: "<工作区绝对路径>")` |
+| 离开 | `ExitWorktree(action: "keep")` |
+
+- **只用 `path` 模式，绝不用 `name`。** `name` 会**自己建**工作区和分支：分支名形如
+  `worktree-<name 把 / 换成 +>`（过不了多数仓库的分支命名 hook），基线由 `worktree.baseRef`
+  决定、默认 `fresh` 取 `origin/<默认分支>`——仓库若不常推远程，那可能落后几百个提交。
+  交接要的分支名和基线都得由 author 自己定，所以只能**先 `git worktree add` 建、再 `path` 进**。
+- `path` 只认**当前仓库**（或嵌套在其中的仓库）注册过的工作区，跨仓库直接拒绝。
+  交接双方在同一仓库时不是问题；跨仓库按「通用兜底」办。
+- 必须由当前会话**直接调**，不能交给 fork/subagent 代调。
+- 离开一律 `action: "keep"`。以 `path` 进入的工作区它本来就不会删，但显式 `keep` 更稳；
+  **`remove` 在交接期间绝对不能用**——验收方还要回来。
+
+### 通用兜底（无此类能力，或跨仓库）
+
+每条命令自带限定，**不要靠裸 `cd`**：多数 agent harness 里 `cd` 只在单条命令内有效，
+下一条又回到原目录，你会以为自己在工作区里、其实命令全打在主工作树上。
+
+- git：`git -C <工作区> <命令>`
+- 其他 shell 命令：`cd <工作区> && <命令>` 写在**同一条**命令里
+- **读写文件一律用绝对路径。** 这条最容易漏：`git -C` 只管得住 git，管不住
+  Read / Edit / Write / Grep / Glob——那些按**会话当前目录**解析相对路径。会话在主工作树、
+  你以为在工作区里改文件，一个相对路径就改到了另一份同名文件上，**而且会成功**。
+
+人类接手时同理：`cd <工作区>` 之后不要再切回去。

package/skills/coding/handoff/assets/handoff-template.md

@@ -4,7 +4,7 @@
 
 ## 固定骨架：frontmatter + 两个锚点
 
-frontmatter 的字段是给机器读的（`status` 驱动三个 phase，`source_node`/`target_node` 驱动画布关系，`branch` 与 `worktree` 由 author 建好工作区后填，接手方照它进去开工、accept 方照它回来验收），由 `scripts/validate-handoff.sh` 校验；「交接目的」和「最小验收锚点」是给人读的，任何情况下不能省。文档必须包含以下开头结构和「最小验收锚点」一节：
+frontmatter 的字段是给机器读的（`status` 驱动各 phase，`source_node`/`target_node` 驱动画布关系，`branch` 与 `worktree` 由 author 建好工作区后填，接手方照它进去开工、accept 方照它回来验收），由 `scripts/validate-handoff.sh` 校验；「交接目的」和「最小验收锚点」是给人读的，任何情况下不能省。文档必须包含以下开头结构和「最小验收锚点」一节：
 
 ```
 ---
@@ -22,11 +22,17 @@ target_node:              # 留空，接手方在 verify 建完 hands-off-to 后
 
 **交接目的**：<一句话，自由描述这次交接是为了什么，不受预设分类约束>
 
-> **接手方须知**：你正在接手一个任务。本文档是完整交接与唯一权威入口：从头读到尾，若文档里有「工作流约定」章节按其开工，没有就直接开工。**完成后把 frontmatter 的 `status` 置为「待验收」并停在这里**——`已验收` / `打回` 由原 session 按「最小验收锚点」判定后写，不要代填。你的自测结果写成独立小节，别写进原 session 的验收记录里。
+> **接手方须知**：你正在接手一个任务。本文档是完整交接与唯一权威入口：从头读到尾，若文档里有「工作流约定」章节按其开工，没有就直接开工。
+>
+> **完成后不是直接推状态，先自测**（skill 的 Phase 2.5）：逐条实跑「最小验收锚点」**全集**（不是只跑你改动相关的那几条），外加文档点名要复跑的既有资产；判成败的命令不接管道（`| tail` 的退出码是 `tail` 的，恒为 0）。把结果写成**独立小节**，标题里必须有「自测」二字（如「接手方自测记录（日期）」），逐条列 pass/fail 并附实际命令——写你自己这一节，别混进原 session 的验收记录。**有红就别推状态**：要么修到绿，要么在那一条旁边写出归因证据并显式声明「带着这条红送验」，不许沉默推上来。`validate-handoff.sh` 会拦：`status` 是「待验收」而正文没有含「自测」的小节直接 exit 1。
+>
+> 自测过了，才把 frontmatter 的 `status` 置为「待验收」并**停在这里**——`已验收` / `打回` 由原 session 按「最小验收锚点」判定后写，不要代填。
+>
+> **被打回之后同理，而且默认跑全集**：打回轮范围小、容易觉得「就改一行」，恰恰是二次打回最常见的来源。复修完重新走一遍自测才能再置回「待验收」；要只跑子集，必须在记录里附改动范围证据（`git diff --name-only <打回点提交>..HEAD`）和「其余条目不可能被波及」的论证。复修记录另起一节（如「接手方复修自测记录（第 N 轮）」，同样含「自测」二字），不覆盖前几轮。
 >
 > **开工前**：若 frontmatter 有 `source_node`、且你也在 Agent Canvas 画布节点里，先建一条 `hands-off-to` 关系（`agent-canvas-ctl whoami` 取自己的 id，核对 `node-relations` 里没有后 `link-nodes --from <source_node> --to <自己> --type hands-off-to`），建完把自己的 id 填进 `target_node`。**只建这一条**——别建 `implements`、别另立需求节点。
 >
-> **在哪开工**：frontmatter 有 `worktree` 时，`cd` 进去，核对当前分支与 `branch` 一致，就在那里干活。**不要自己 `git worktree add`**（那条分支已被这个工作区占用，再建会失败，而且原 session 验收时回的是它自己建的那个，看不到你的改动），**也不要 `git worktree remove`**（验收还要用）。路径不存在就打回原 session 重建，别自己挑地方。
+> **在哪开工**：frontmatter 有 `worktree` 时，进那个工作区干活，核对当前分支与 `branch` 一致。**怎么进按你所在平台来**（Claude Code 用 `EnterWorktree(path: <worktree>)` 的 `path` 模式；没有这类能力就每条命令自带限定 `git -C <worktree>`，读写文件用绝对路径，别靠裸 `cd`——它只在单条命令内有效）。判据只有一条：后续命令的工作目录确实是那个工作区。**不要自己 `git worktree add`**（那条分支已被这个工作区占用，再建会失败，而且原 session 验收时回的是它自己建的那个，看不到你的改动），**也绝不要销毁它**（`git worktree remove`，或平台的"退出并删除"）——验收还要用。路径不存在就打回原 session 重建，别自己挑地方。
 
 ---
 

package/skills/coding/handoff/evals/evals.json

@@ -142,7 +142,7 @@
         {
           "id": "entered-author-worktree",
           "source": "transcript",
-          "text": "执行轨迹显示验收命令是在交接工作区（setup 打印的 wt 目录）里跑的——cd 进去、或 git -C/命令 cwd 指向它——而不是全程只在仓库主工作树里操作"
+          "text": "执行轨迹显示验收命令是在交接工作区（setup 打印的 wt 目录）里跑的——EnterWorktree(path:) 进去、cd 进去、或 git -C / 命令 cwd 指向它——而不是全程只在仓库主工作树里操作。注意：本 fixture 的仓库刻意建在 jail 之外（见 setup.sh 的说明），对被测会话属跨仓库，EnterWorktree 会被拒；走 git -C / cd 兜底是 SKILL.md 明写的预期行为，不扣分。"
         },
         {
           "id": "used-three-criteria-not-stale-two",

package/skills/coding/handoff/scripts/validate-handoff.sh

@@ -151,6 +151,16 @@ grep -qE '^##[[:space:]]*最小验收锚点' "$file" \
 grep -qE '\*\*交接目的\*\*' "$file" \
   || err "正文缺「**交接目的**」行——任何情况下不能省"
 
+# status=「待验收」时，正文必须有一节标题含「自测」的接手方自测记录。
+# 「待验收」的全部信息量是「接手方声称做完了」；它若是在锚点还红着的时候推上来的，
+# accept 方要耗掉一整轮才发现。这条把它压缩成 accept 开跑前的一条命令。
+# 只认**标题行**，不认散文里顺嘴提到的「自测过了」——那不构成一份可复核的记录。
+# 因此模板的 author 骨架里**不能**预置这个标题（预置=空标题也能过，规则当场恒真）。
+if [[ -n "$fm" ]] && has_field status && [[ "$(field status)" == "待验收" ]]; then
+  grep -qE '^#{2,}[[:space:]]*.*自测' "$file" \
+    || err "status 是「待验收」却没有标题含「自测」的小节——接手方须先逐条实跑最小验收锚点、把结果写成独立小节，才能推到这个状态（复修轮同理，另起「接手方复修自测记录」一节）"
+fi
+
 # ── 引用路径（只警告，不阻断：可能指向本次待创建的产物）────────────────────
 while IFS= read -r link; do
   [[ -z "$link" ]] && continue

package/skills/coding/handoff/tests/validate-handoff.bats

@@ -285,3 +285,68 @@ branch: $BRANCH"
   [[ "$output" == *WARN* ]]
   [[ "$output" == *worktree* ]]
 }
+
+# ── status=待验收 时必须有接手方自测小节 ───────────────────────────────────
+# 「待验收」的全部信息量是「接手方声称做完了」。接手方若没自测就推这个状态，accept 方
+# 要花一整轮才发现锚点根本是红的。这条把它变成开跑前一条命令就能查出来的事。
+# 只认**标题行**里的「自测」，不认正文里顺嘴提到的——散文提一句不构成一份记录。
+# 其余 status 一律不受这条约束（30/31/32 是对照臂：规则确实按 status 分叉，不是恒真）。
+
+@test "29 pending-accept status without self-test section -> exit 1" {
+  write_doc 'status: 待验收
+date: 2026-09-06
+author_model: opus-5
+acceptance: hard'
+  run bash "$VALIDATOR" "$DOC"
+  [ "$status" -eq 1 ]
+  [[ "$output" == *自测* ]]
+}
+
+@test "30 pending-accept status with self-test section -> exit 0" {
+  write_doc 'status: 待验收
+date: 2026-09-06
+author_model: opus-5
+acceptance: hard' "$(printf '# 交接：示例\n\n**交接目的**：把实现交给下一个 session\n\n## 最小验收锚点\n- demo() 返回 1\n\n## 接手方自测记录（2026-09-06）\n- demo() 返回 1 → PASS\n')"
+  run bash "$VALIDATOR" "$DOC"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *ERROR* ]]
+}
+
+@test "31 pending-accept with selftest word in prose only -> exit 1" {
+  write_doc 'status: 待验收
+date: 2026-09-06
+author_model: opus-5
+acceptance: hard' "$(printf '# 交接：示例\n\n**交接目的**：把实现交给下一个 session\n\n我已经自测过了，没问题。\n\n## 最小验收锚点\n- demo() 返回 1\n')"
+  run bash "$VALIDATOR" "$DOC"
+  [ "$status" -eq 1 ]
+  [[ "$output" == *自测* ]]
+}
+
+@test "32 todo status without self-test section -> exit 0" {
+  write_doc "$VALID_FM"
+  run bash "$VALIDATOR" "$DOC"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *自测* ]]
+}
+
+@test "33 other statuses without self-test section -> exit 0" {
+  for s in 执行中 已验收 打回; do
+    write_doc "status: $s
+date: 2026-09-06
+author_model: opus-5
+acceptance: hard"
+    run bash "$VALIDATOR" "$DOC"
+    [ "$status" -eq 0 ]
+    [[ "$output" != *自测* ]]
+  done
+}
+
+@test "34 pending-accept with rework self-test heading -> exit 0" {
+  write_doc 'status: 待验收
+date: 2026-09-06
+author_model: opus-5
+acceptance: hard' "$(printf '# 交接：示例\n\n**交接目的**：把实现交给下一个 session\n\n## 最小验收锚点\n- demo() 返回 1\n\n### 接手方复修自测记录（第 2 轮）\n- demo() 返回 1 → PASS\n')"
+  run bash "$VALIDATOR" "$DOC"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *ERROR* ]]
+}

package/skills/feed/sync-website/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sync-website
-version: "0.2.0"
+version: "0.2.2"
 description: "Run one incremental fetch over every website channel on the roster, produce a translated Markdown digest of what is new since last run, and archive each new article's title, translated title, publish date and URL to a per-channel JSON store. Trigger phrases: '/sync-website run', '/sync-website calibrate <handle>', '/sync-website', 'check my watched websites for new articles', or a request to run sync-website on a schedule via /loop or schedule. Adding or removing a watched website is manage-creators, not this skill. Listing only — never downloads article bodies or images, and never ingests into Obsidian (use clip-url for a single article). Display of archived articles is left to external tooling reading the JSON archive directly, not this skill."
 user_invocable: true
 ---
@@ -41,8 +41,19 @@ python3 scripts/roster_locate.py
 sync-xtimeline / sync-ytchannel 共用同一份 `knowledgeRoot` 配置（各自渠道
 各占 `feeds/` 下一个子目录）。运行 `python3 scripts/store_config.py check`，
 若输出 `MISSING:`，询问用户"抓取产物统一存到哪个目录？（直接回车使用默认：
-`~/Documents/knowledge`）"，写入 `~/.hskill/config.json` 的 `knowledgeRoot`
-字段（若已有 `skillDir` 等字段，只增改 `knowledgeRoot`）。
+`~/knowledge`）"，写入 `~/.hskill/config.json` 的 `knowledgeRoot`
+字段（若已有 `skillDir` 等字段，只增改 `knowledgeRoot`）。**默认值刻意不选
+`~/Documents/...`、`~/Desktop/...`、`~/Downloads/...`**——这几个目录受 macOS
+TCC 隐私保护，无 Full Disk Access 的 agent 执行环境写入会被拒绝；`$HOME` 下
+的普通目录（如 `~/knowledge`）不受此限制。
+
+**再核对下游是否同步。** 运行 `python3 scripts/store_config.py check-downstream` 核对 vdl、scholia 当前配置是否等于 `knowledgeRoot` 推出的期望值。输出 `DRIFT:` 时把对应的 `fix:` 命令原样报告给用户，由用户决定要不要执行——不要代替用户改这些下游程序的配置文件；输出 `SKIP:` 表示对应工具未安装，忽略即可。
+
+**运行中写入失败时的处理。** 若 `store_config.py check` 通过、但实际写入
+`<knowledgeRoot>/feeds/website/` 时仍然失败（权限不足、目录只读等），必须
+原样把错误报告给用户并停下来，禁止擅自把 `knowledgeRoot` 改指到别的路径来
+"绕过"——这是多个 skill 共用的配置，擅自改会让产物静默散落到不同目录，用户
+毫不知情，且难以事后排查。
 
 ## 用法
 

package/skills/feed/sync-website/scripts/store_config.py

@@ -9,13 +9,18 @@ clip-url / learn-video / sync-xtimeline / sync-ytchannel 四个 skill 提供
 
 支持 HSKILL_CONFIG 环境变量覆盖 config 路径，供测试注入临时根；每次调用
 时读取（不在 import 时绑定），进程内 monkeypatch 才能生效。
+
+check-downstream 子命令核对 vdl / scholia 当前配置是否等于 knowledgeRoot
+推出的期望值——knowledgeRoot 是唯一事实依据，vdl/scholia 的值只是被检查
+的对象，不参与仲裁。只读，不改任何下游文件；发现漂移只打印修复命令。
 """
 import json
 import os
+import subprocess
 import sys
 from pathlib import Path
 
-_INIT_HINT = "抓取产物统一存到哪个目录？（直接回车使用默认：~/Documents/knowledge）"
+_INIT_HINT = "抓取产物统一存到哪个目录？（直接回车使用默认：~/knowledge）"
 
 
 def _config_path() -> Path:
@@ -45,6 +50,76 @@ def feeds_dir(channel: str) -> Path:
     return get_root() / "feeds" / channel
 
 
+def _run_downstream_command(cmd):
+    """跑一个下游程序的 CLI，拿不到（未安装/非 0 退出）时返回 None。"""
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=10)
+    except FileNotFoundError:
+        return None
+    if result.returncode != 0:
+        return None
+    return result.stdout
+
+
+def _check_vdl():
+    output = _run_downstream_command(["vdl", "config", "get"])
+    if output is None:
+        return [("SKIP", "vdl not installed (command not found)")]
+    actual = ""
+    for line in output.splitlines():
+        line = line.strip()
+        if line.startswith("workRoot:"):
+            actual = line.split(":", 1)[1].strip()
+    expected = str(videos_dir())
+    if actual == expected:
+        return [("OK", "vdl WORK_ROOT")]
+    return [
+        ("DRIFT", f"vdl WORK_ROOT={actual} (expect {expected})"),
+        ("FIX", f"vdl config set work-root {expected}"),
+    ]
+
+
+def _check_scholia():
+    output = _run_downstream_command(["scholia", "config", "list"])
+    if output is None:
+        return [("SKIP", "scholia not installed (command not found)")]
+    actual = {}
+    for line in output.splitlines():
+        if "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        actual[key.strip()] = value.strip()
+    expected = {
+        "work-dir": str(videos_dir() / "work"),
+        "content-dir": str(articles_dir()),
+        "x-dir": str(feeds_dir("tweets") / "creators"),
+    }
+    results = []
+    for key, exp in expected.items():
+        act = actual.get(key, "")
+        if act == exp:
+            results.append(("OK", f"scholia {key}"))
+        else:
+            results.append(("DRIFT", f"scholia {key}={act} (expect {exp})"))
+            results.append(("FIX", f"scholia config set {key} {exp}"))
+    return results
+
+
+def check_downstream() -> int:
+    get_root()  # 触发 MISSING 异常，交给调用方处理
+    entries = _check_vdl() + _check_scholia()
+    has_drift = False
+    for kind, message in entries:
+        if kind == "FIX":
+            print(f"  fix: {message}")
+        elif kind == "DRIFT":
+            has_drift = True
+            print(f"DRIFT: {message}")
+        else:
+            print(f"{kind}: {message}")
+    return 1 if has_drift else 0
+
+
 def main():
     if len(sys.argv) > 1 and sys.argv[1] == "check":
         try:
@@ -53,7 +128,14 @@ def main():
             print(f"MISSING: {e}", file=sys.stderr)
             sys.exit(1)
         return
-    print("Usage: store_config.py check", file=sys.stderr)
+    if len(sys.argv) > 1 and sys.argv[1] == "check-downstream":
+        try:
+            sys.exit(check_downstream())
+        except (FileNotFoundError, KeyError) as e:
+            print(f"MISSING: {e}", file=sys.stderr)
+            sys.exit(1)
+        return
+    print("Usage: store_config.py check|check-downstream", file=sys.stderr)
     sys.exit(1)