flower-trellis 0.4.0-beta.4 → 0.4.0-beta.5

package/enhancements/0.6/.agents/skills/trellis-push/SKILL.md

@@ -101,12 +101,13 @@ merge 目标仍从对应 package 的 `merge_target` 读取；父仓没有 packag
 ```bash
 # 在仓库根目录（含 .trellis/ 的项目根，不是 package 子目录）
 python3 ./.trellis/scripts/task.py current
+python3 ./.trellis/scripts/push_snapshot.py status --json
 ```
 
 - **无活动任务**（命令退出码非 0 或输出为空）：在计划中标记 `snapshot: 跳过（无活动任务）`。
 - **有活动任务**：解析输出拿到 task 路径（形如 `.trellis/tasks/MM-DD-name/`），并读取下列内容：
   - `<task_dir>/implement.md`（如有）— 步骤清单，AI 推断进度的主依据
-  - `<task_dir>/task.json` 的 `last_push_snapshot` 字段（如有）— 上次推送时的进度基线
+  - `push_snapshot.py status --json` 的 `snapshot` / `summary`（如有）— 上次推送时的进度基线；若返回 `no-snapshot` / `no-current-task`，按无上次 snapshot 继续
   - `<task_dir>/task.json` 的 `base_branch` 字段 — 用于 `git log <base_branch>..HEAD` 圈定本任务 commit 范围
 
 ---
@@ -192,6 +193,7 @@ commit message 生成规则：
 - branch: 执行成功后按实际分支补齐
 - pushed_commits: 执行成功后按实际 commit hash 补齐
 - snapshot_at: 执行成功后写入当前 ISO 8601 时间
+- push_mode: <push / commit-only / snapshot-only / 指定仓库 / reconfigure / 临时目标>
 - bookkeeping: 只提交 `<task_dir>/task.json`
 ```
 
@@ -205,6 +207,7 @@ commit message 生成规则：
     "frontend": "abc1234",
     "backend": "def5678"
   },
+  "push_mode": "push",
   "completed_steps": ["Step 1", "Step 2"],
   "partial_step": "Step 3（可选）",
   "next_step": "Step 4（可选）",
@@ -214,7 +217,9 @@ commit message 生成规则：
 
 > `pushed_commits`、`snapshot_at`、实际 branch / commit hash 是运行后字段。用户确认的是 snapshot 的语义内容和写入动作；执行成功后由 AI 按实际结果补齐。
 
-commit-only 模式下，字段名仍保持 `pushed_commits` 以兼容恢复逻辑；值记录本次生成的本地 commit hash，并在 `notes` 中注明“commit-only：本地已提交，未推送”。
+`push_mode` 记录本轮确认的模式。默认实际 push 模式写 `"push"`；commit-only 写 `"commit-only"`；snapshot-only 写 `"snapshot-only"`；指定仓库、reconfigure 或临时目标可写对应模式名。
+
+commit-only 模式下，字段名仍保持 `pushed_commits` 以兼容恢复逻辑；值记录本次生成的本地 commit hash，`push_mode` 写 `"commit-only"`，并在 `notes` 中注明“commit-only：本地已提交，未推送”。
 
 ### 2.3 展示确认模板
 
@@ -356,6 +361,7 @@ git checkout <current_branch>
 - `snapshot_at`：当前 ISO 8601 时间戳
 - `branch`：实际分支；多仓不同分支时使用字典
 - `pushed_commits`：各 package 的短 hash
+- `push_mode`：统一执行计划确认的模式；默认 push 写 `"push"`，commit-only 写 `"commit-only"`，snapshot-only 写 `"snapshot-only"`
 - `notes`：保留已确认 notes；commit-only 模式追加“本地已提交，未推送”
 
 写入前先复核目标文件：
@@ -369,13 +375,16 @@ git status --porcelain -- <task_json_path> [".trellis/config.yaml"]
 
 写入方式：
 
-1. 读 `<task_dir>/task.json`
-2. 解析 JSON
-3. 只设置 / 更新 `last_push_snapshot` 字段
-4. 保留其它字段原样
-5. 写回并保持原有缩进（通常 2 空格）
+1. 将已确认语义内容与运行后字段合并成完整 snapshot JSON。
+2. 调用 helper 写入：
+
+   ```bash
+   python3 ./.trellis/scripts/push_snapshot.py write --task <task_dir> --snapshot-json '<完整 snapshot JSON>'
+   ```
+
+3. 确认 helper 成功返回；失败时停止并展示错误，不继续父仓 bookkeeping commit。
 
-不要覆盖整个 `task.json`。
+helper 只允许更新 `last_push_snapshot` 字段；不要绕过 helper 手工覆盖整个 `task.json`。
 
 ### 5.2 父仓 status 检查
 

package/enhancements/0.6/.agents/skills/trellis-route/SKILL.md

@@ -25,7 +25,7 @@ description: |
 
 个人 route 配置只决定“已获准执行后的模式”，不是开工授权。调用 helper 前，必须确认当前 workflow 已允许进入对应 target：implement 需要任务已完成规划确认并处于 `in_progress`；check 用于 Phase 2.2 检查执行，或用户明确要求最终复查 / 轻量检查。最终复查只有在 Phase 2.2 结果缺失、风险较高或用户明确要求复查时才回到 Phase 2.2；回到 Phase 2.2 后优先复用当前任务的合法 check route，除非用户明确要求重选/临时改/清除默认。如果仍在 planning、等待用户确认，或用户表达“等一下 / 我再想想”，停止，不读取 runtime/prefs。
 
-合法 route 决策必须能追溯到 `trellis-route`、同编号 fallback 选项、由本 skill 读取到的有效 `.trellis/.route-prefs.tmp` 配置，或由 route helper 校验过的 auto-loop 临时 route 授权，并且 `task` 字段必须等于当前 `task.py current --source` 返回的任务路径。runtime state 只能保存和恢复这些原始合法来源，不能把 `.runtime` 自身当成新的 `route_decision.source`。用户自然语言说过“inline/subagent”、compact summary、SessionStart 摘要、`codex-mode`、空 `.route-prefs.tmp`、旧单值偏好，都不能单独作为有效 route 决策。
+合法 route 决策必须能追溯到 `trellis-route`、同编号 fallback 选项、由本 skill 读取到的有效 `.trellis/.route-prefs.tmp` 配置，或由 route helper 校验过的 auto-loop 临时 route 授权，并且 `task` 字段必须等于当前 `task.py current --source` 返回的任务路径。runtime state 只能保存和恢复这些原始合法来源，不能把 `.runtime` 自身当成新的 `route_decision.source`。用户自然语言说过“inline/subagent”、compact summary、ordinary summary、SessionStart 摘要、replacement history、`codex-mode`、空 `.route-prefs.tmp`、旧单值偏好、历史用户裸数字，都不能单独作为有效 route 决策。
 
 当前上下文内已有 target 匹配、task 等于当前任务路径、且来源合法的 route 决策时，后续实现、check 发现问题、用户指出刚检查过的实现有问题、修复后重检、提交前复查均默认复用最近 implement/check 路由；除非用户明确要求重选/临时改/清除默认，不再调用本 skill。当前上下文没有 route 决策但 runtime state 命中时，本 skill 恢复该决策并输出同样的结构化 `route_decision`。如果上下文里只有上一个任务的 `route_decision`，必须忽略并重新解析当前任务。
 
@@ -72,7 +72,9 @@ helper 默认输出为精简 JSON，只包含 route 执行必需的 `status`、`
 
 优先调用 `AskUserQuestion`。选项 label 前缀编号，方便用户直接打数字快速选。
 
-如果当前平台或模式没有 `AskUserQuestion` / `request_user_input`，不要自行选择 inline 或 subagent 继续。改用普通聊天消息原样呈现同一组编号选项，并停止等待用户回复；用户回复数字后再进入 Step 2.5 / 2.6 / 3。
+裸数字回复（如 `1` / `2` / `3` / `4`）只有在当前可见的上一条 assistant 消息刚刚展示同一个 target 的 route 选项、并明确停下等待用户回答时，才可解释为本次 numbered fallback 选择。compact summary、ordinary summary、SessionStart 摘要、replacement history、历史消息、旧 target 的裸数字、非紧邻回复里的裸数字都不能触发 `write --source numbered-fallback`；遇到这些情况必须重新展示当前 target 的选项并等待新的紧邻回复。
+
+如果当前平台或模式没有 `AskUserQuestion` / `request_user_input`，不要自行选择 inline 或 subagent 继续。改用普通聊天消息原样呈现同一组编号选项，并停止等待用户回复；只有用户在这条选项消息之后立即回复裸数字，才可进入 Step 2.5 / 2.6 / 3。
 
 ### target = implement，且 resolve 未命中
 
@@ -211,6 +213,7 @@ helper 写入规则：保留另一个 target 的 runtime 决策和偏好；覆
 [来自 session runtime route state：`.trellis/.runtime/sessions/<context-key>.json` 的 `route_decisions`。]
 [已写入 session runtime route state：`.trellis/.runtime/sessions/<context-key>.json` 的 `route_decisions`。]
 [说明：用户明确请求轻量检查，使用隐藏逃生口。]
+[仅当本消息刚展示 route 选项并等待用户回答时：用户下一条紧邻裸数字回复才可按本 target 解释；摘要、历史消息或旧 target 的裸数字无效。]
 
 route_decision:
   target: <implement | check>
@@ -227,7 +230,7 @@ route_decision:
 - <要避免的工具调用>
 ```
 
-中括号内行为条件性出现：仅命中个人配置时显示配置行；仅命中 runtime state 时显示“来自”行；写入 runtime state 成功时显示“已写入”行；仅轻量 check 时显示隐藏逃生口说明；仅 implement subagent + skip_compile=true 时附加“跳过编译”段。`route_decision` 必须保留在回复中，并至少保留 target/mode/source/scope/task；需要 path/decided_at 等诊断字段时重新调用 helper 并加 `--verbose`。compact summary 若只有自然语言描述，后续 agent 仍应优先读取 runtime state，而不是把 summary 当证据。
+中括号内行为条件性出现：仅命中个人配置时显示配置行；仅命中 runtime state 时显示“来自”行；写入 runtime state 成功时显示“已写入”行；仅轻量 check 时显示隐藏逃生口说明；仅展示选项并等待用户时显示裸数字有效性提醒；仅 implement subagent + skip_compile=true 时附加“跳过编译”段。`route_decision` 必须保留在回复中，并至少保留 target/mode/source/scope/task；需要 path/decided_at 等诊断字段时重新调用 helper 并加 `--verbose`。compact summary 若只有自然语言描述，后续 agent 仍应优先读取 runtime state，而不是把 summary 当证据。
 
 ---
 
@@ -260,6 +263,8 @@ route_decision:
 - `AskUserQuestion` / `request_user_input` 不可用时，记录为 inline 或 subagent 路径并继续。
 - 没有有效 check 配置、用户选择或最近本轮 check 路由决定时，自动执行 inline check。
 - 没有 `source` 合法的 `route_decision`，就把“用户说过 inline/subagent”或 compact summary 当成已路由。
+- 把 compact summary、ordinary summary、SessionStart 摘要、replacement history 或历史消息里的裸数字 `1` 当成当前 target 的 numbered fallback 选择。
+- 用户裸数字回复不是紧邻当前 route 选项消息时，仍调用 `write --source numbered-fallback`。
 - check 发现问题后，把当前任务内已有合法 route 的修复/重检当成新的 route 边界再次询问模式。
 - 给 check 任何模式附加“跳过编译”指令。
 - 询问后忽视用户答案默认 subagent。

package/enhancements/0.6/.claude/skills/trellis-push/SKILL.md

@@ -101,12 +101,13 @@ merge 目标仍从对应 package 的 `merge_target` 读取；父仓没有 packag
 ```bash
 # 在仓库根目录（含 .trellis/ 的项目根，不是 package 子目录）
 python3 ./.trellis/scripts/task.py current
+python3 ./.trellis/scripts/push_snapshot.py status --json
 ```
 
 - **无活动任务**（命令退出码非 0 或输出为空）：在计划中标记 `snapshot: 跳过（无活动任务）`。
 - **有活动任务**：解析输出拿到 task 路径（形如 `.trellis/tasks/MM-DD-name/`），并读取下列内容：
   - `<task_dir>/implement.md`（如有）— 步骤清单，AI 推断进度的主依据
-  - `<task_dir>/task.json` 的 `last_push_snapshot` 字段（如有）— 上次推送时的进度基线
+  - `push_snapshot.py status --json` 的 `snapshot` / `summary`（如有）— 上次推送时的进度基线；若返回 `no-snapshot` / `no-current-task`，按无上次 snapshot 继续
   - `<task_dir>/task.json` 的 `base_branch` 字段 — 用于 `git log <base_branch>..HEAD` 圈定本任务 commit 范围
 
 ---
@@ -192,6 +193,7 @@ commit message 生成规则：
 - branch: 执行成功后按实际分支补齐
 - pushed_commits: 执行成功后按实际 commit hash 补齐
 - snapshot_at: 执行成功后写入当前 ISO 8601 时间
+- push_mode: <push / commit-only / snapshot-only / 指定仓库 / reconfigure / 临时目标>
 - bookkeeping: 只提交 `<task_dir>/task.json`
 ```
 
@@ -205,6 +207,7 @@ commit message 生成规则：
     "frontend": "abc1234",
     "backend": "def5678"
   },
+  "push_mode": "push",
   "completed_steps": ["Step 1", "Step 2"],
   "partial_step": "Step 3（可选）",
   "next_step": "Step 4（可选）",
@@ -214,7 +217,9 @@ commit message 生成规则：
 
 > `pushed_commits`、`snapshot_at`、实际 branch / commit hash 是运行后字段。用户确认的是 snapshot 的语义内容和写入动作；执行成功后由 AI 按实际结果补齐。
 
-commit-only 模式下，字段名仍保持 `pushed_commits` 以兼容恢复逻辑；值记录本次生成的本地 commit hash，并在 `notes` 中注明“commit-only：本地已提交，未推送”。
+`push_mode` 记录本轮确认的模式。默认实际 push 模式写 `"push"`；commit-only 写 `"commit-only"`；snapshot-only 写 `"snapshot-only"`；指定仓库、reconfigure 或临时目标可写对应模式名。
+
+commit-only 模式下，字段名仍保持 `pushed_commits` 以兼容恢复逻辑；值记录本次生成的本地 commit hash，`push_mode` 写 `"commit-only"`，并在 `notes` 中注明“commit-only：本地已提交，未推送”。
 
 ### 2.3 展示确认模板
 
@@ -356,6 +361,7 @@ git checkout <current_branch>
 - `snapshot_at`：当前 ISO 8601 时间戳
 - `branch`：实际分支；多仓不同分支时使用字典
 - `pushed_commits`：各 package 的短 hash
+- `push_mode`：统一执行计划确认的模式；默认 push 写 `"push"`，commit-only 写 `"commit-only"`，snapshot-only 写 `"snapshot-only"`
 - `notes`：保留已确认 notes；commit-only 模式追加“本地已提交，未推送”
 
 写入前先复核目标文件：
@@ -369,13 +375,16 @@ git status --porcelain -- <task_json_path> [".trellis/config.yaml"]
 
 写入方式：
 
-1. 读 `<task_dir>/task.json`
-2. 解析 JSON
-3. 只设置 / 更新 `last_push_snapshot` 字段
-4. 保留其它字段原样
-5. 写回并保持原有缩进（通常 2 空格）
+1. 将已确认语义内容与运行后字段合并成完整 snapshot JSON。
+2. 调用 helper 写入：
+
+   ```bash
+   python3 ./.trellis/scripts/push_snapshot.py write --task <task_dir> --snapshot-json '<完整 snapshot JSON>'
+   ```
+
+3. 确认 helper 成功返回；失败时停止并展示错误，不继续父仓 bookkeeping commit。
 
-不要覆盖整个 `task.json`。
+helper 只允许更新 `last_push_snapshot` 字段；不要绕过 helper 手工覆盖整个 `task.json`。
 
 ### 5.2 父仓 status 检查
 

package/enhancements/0.6/.claude/skills/trellis-route/SKILL.md

@@ -25,7 +25,7 @@ description: |
 
 个人 route 配置只决定“已获准执行后的模式”，不是开工授权。调用 helper 前，必须确认当前 workflow 已允许进入对应 target：implement 需要任务已完成规划确认并处于 `in_progress`；check 用于 Phase 2.2 检查执行，或用户明确要求最终复查 / 轻量检查。最终复查只有在 Phase 2.2 结果缺失、风险较高或用户明确要求复查时才回到 Phase 2.2；回到 Phase 2.2 后优先复用当前任务的合法 check route，除非用户明确要求重选/临时改/清除默认。如果仍在 planning、等待用户确认，或用户表达“等一下 / 我再想想”，停止，不读取 runtime/prefs。
 
-合法 route 决策必须能追溯到 `trellis-route`、同编号 fallback 选项、由本 skill 读取到的有效 `.trellis/.route-prefs.tmp` 配置，或由 route helper 校验过的 auto-loop 临时 route 授权，并且 `task` 字段必须等于当前 `task.py current --source` 返回的任务路径。runtime state 只能保存和恢复这些原始合法来源，不能把 `.runtime` 自身当成新的 `route_decision.source`。用户自然语言说过“inline/subagent”、compact summary、SessionStart 摘要、`codex-mode`、空 `.route-prefs.tmp`、旧单值偏好，都不能单独作为有效 route 决策。
+合法 route 决策必须能追溯到 `trellis-route`、同编号 fallback 选项、由本 skill 读取到的有效 `.trellis/.route-prefs.tmp` 配置，或由 route helper 校验过的 auto-loop 临时 route 授权，并且 `task` 字段必须等于当前 `task.py current --source` 返回的任务路径。runtime state 只能保存和恢复这些原始合法来源，不能把 `.runtime` 自身当成新的 `route_decision.source`。用户自然语言说过“inline/subagent”、compact summary、ordinary summary、SessionStart 摘要、replacement history、`codex-mode`、空 `.route-prefs.tmp`、旧单值偏好、历史用户裸数字，都不能单独作为有效 route 决策。
 
 当前上下文内已有 target 匹配、task 等于当前任务路径、且来源合法的 route 决策时，后续实现、check 发现问题、用户指出刚检查过的实现有问题、修复后重检、提交前复查均默认复用最近 implement/check 路由；除非用户明确要求重选/临时改/清除默认，不再调用本 skill。当前上下文没有 route 决策但 runtime state 命中时，本 skill 恢复该决策并输出同样的结构化 `route_decision`。如果上下文里只有上一个任务的 `route_decision`，必须忽略并重新解析当前任务。
 
@@ -72,7 +72,9 @@ helper 默认输出为精简 JSON，只包含 route 执行必需的 `status`、`
 
 优先调用 `AskUserQuestion`。选项 label 前缀编号，方便用户直接打数字快速选。
 
-如果当前平台或模式没有 `AskUserQuestion` / `request_user_input`，不要自行选择 inline 或 subagent 继续。改用普通聊天消息原样呈现同一组编号选项，并停止等待用户回复；用户回复数字后再进入 Step 2.5 / 2.6 / 3。
+裸数字回复（如 `1` / `2` / `3` / `4`）只有在当前可见的上一条 assistant 消息刚刚展示同一个 target 的 route 选项、并明确停下等待用户回答时，才可解释为本次 numbered fallback 选择。compact summary、ordinary summary、SessionStart 摘要、replacement history、历史消息、旧 target 的裸数字、非紧邻回复里的裸数字都不能触发 `write --source numbered-fallback`；遇到这些情况必须重新展示当前 target 的选项并等待新的紧邻回复。
+
+如果当前平台或模式没有 `AskUserQuestion` / `request_user_input`，不要自行选择 inline 或 subagent 继续。改用普通聊天消息原样呈现同一组编号选项，并停止等待用户回复；只有用户在这条选项消息之后立即回复裸数字，才可进入 Step 2.5 / 2.6 / 3。
 
 ### target = implement，且 resolve 未命中
 
@@ -211,6 +213,7 @@ helper 写入规则：保留另一个 target 的 runtime 决策和偏好；覆
 [来自 session runtime route state：`.trellis/.runtime/sessions/<context-key>.json` 的 `route_decisions`。]
 [已写入 session runtime route state：`.trellis/.runtime/sessions/<context-key>.json` 的 `route_decisions`。]
 [说明：用户明确请求轻量检查，使用隐藏逃生口。]
+[仅当本消息刚展示 route 选项并等待用户回答时：用户下一条紧邻裸数字回复才可按本 target 解释；摘要、历史消息或旧 target 的裸数字无效。]
 
 route_decision:
   target: <implement | check>
@@ -227,7 +230,7 @@ route_decision:
 - <要避免的工具调用>
 ```
 
-中括号内行为条件性出现：仅命中个人配置时显示配置行；仅命中 runtime state 时显示“来自”行；写入 runtime state 成功时显示“已写入”行；仅轻量 check 时显示隐藏逃生口说明；仅 implement subagent + skip_compile=true 时附加“跳过编译”段。`route_decision` 必须保留在回复中，并至少保留 target/mode/source/scope/task；需要 path/decided_at 等诊断字段时重新调用 helper 并加 `--verbose`。compact summary 若只有自然语言描述，后续 agent 仍应优先读取 runtime state，而不是把 summary 当证据。
+中括号内行为条件性出现：仅命中个人配置时显示配置行；仅命中 runtime state 时显示“来自”行；写入 runtime state 成功时显示“已写入”行；仅轻量 check 时显示隐藏逃生口说明；仅展示选项并等待用户时显示裸数字有效性提醒；仅 implement subagent + skip_compile=true 时附加“跳过编译”段。`route_decision` 必须保留在回复中，并至少保留 target/mode/source/scope/task；需要 path/decided_at 等诊断字段时重新调用 helper 并加 `--verbose`。compact summary 若只有自然语言描述，后续 agent 仍应优先读取 runtime state，而不是把 summary 当证据。
 
 ---
 
@@ -260,6 +263,8 @@ route_decision:
 - `AskUserQuestion` / `request_user_input` 不可用时，记录为 inline 或 subagent 路径并继续。
 - 没有有效 check 配置、用户选择或最近本轮 check 路由决定时，自动执行 inline check。
 - 没有 `source` 合法的 `route_decision`，就把“用户说过 inline/subagent”或 compact summary 当成已路由。
+- 把 compact summary、ordinary summary、SessionStart 摘要、replacement history 或历史消息里的裸数字 `1` 当成当前 target 的 numbered fallback 选择。
+- 用户裸数字回复不是紧邻当前 route 选项消息时，仍调用 `write --source numbered-fallback`。
 - check 发现问题后，把当前任务内已有合法 route 的修复/重检当成新的 route 边界再次询问模式。
 - 给 check 任何模式附加“跳过编译”指令。
 - 询问后忽视用户答案默认 subagent。

package/enhancements/0.6/overrides/skills/trellis-finish-work.md

@@ -70,4 +70,18 @@ Do not write `None`, `No release operations identified`, or `Rollback code only`
 
 If multiple tasks will be archived in the same finish-work run, process the active task at minimum. Process extra archived tasks only when Step 1 provides enough local context to infer safely; do not add per-task confirmation prompts.
 
+#### Finish Bookkeeping Auto-push Step
+
+Run this step after finish-work Step 4 records the session journal and produces the `chore: record journal` commit, before the final finish-work report.
+
+Read the active task's `last_push_snapshot.push_mode` with `python3 ./.trellis/scripts/push_snapshot.py status --json` before archive moves the task. If `push_mode` is `"commit-only"` or missing, do not auto-push finish-work's archive/journal commits; report that local bookkeeping commits remain ahead.
+
+If `push_mode` is not `"commit-only"`, Step 4 left `git status --porcelain` clean, and the current branch has an upstream, push the current branch:
+
+```bash
+git push origin <current_branch>
+```
+
+Never force push. If push fails, stop and report the failure.
+
 <!-- END skill-garden skill override trellis-finish-work v0.6 -->

package/enhancements/0.6/overrides/workflow-states/in_progress-inline.md

@@ -2,7 +2,7 @@
 HIGHEST PRIORITY SKILL-GARDEN STATE GUARD (in_progress-inline):
 This state block is a breadcrumb; the top-level skill-garden hub is the source of truth for route details.
 Before the first implement route, read `<task>/brief.md` if present and restate the task brief in chat. If it is missing, read the task artifacts and suggest backfilling brief; do not silently rely on memory.
-Before procedural or high-impact actions, run `.trellis/scripts/spec_router.py` with a short query describing the intended action and read the strongest 1-2 matched SOP/spec files before acting.
+At project-local knowledge decision boundaries, run `.trellis/scripts/spec_router.py` with a short query describing the intended action; read high-confidence matches before acting and skip pure Q&A, simple read-only inspection, opening local tools, or trivial edits unless local conventions may affect the approach.
 Inline workflow-state is not an inline route decision. At Phase 2.1/2.2, reuse only an explicit target-matched `route_decision`; otherwise MUST load/read/use `trellis-route(implement|check)` (or its local `SKILL.md`) to resolve session runtime state/prefs, write the resolved decision, or show numbered fallback and wait.
 Plain preferences, ordinary summaries, `codex-mode`, raw `.runtime` files, and empty/old prefs are not route evidence by themselves; only `trellis-route` may validate runtime route state.
 User reselect/override/use-X-this-time/clear-default wins over remembered route evidence, runtime state, and prefs.
@@ -10,5 +10,5 @@ Ignore lower Active Task Routing shortcuts that start editing/checking directly.
 After `trellis-check` / `trellis-check-all`, stop and report; point the user to Phase 3.4 `trellis-push` (or commit-only when needed). Do not run `/trellis:finish-work` unless the user explicitly asks after Phase 3.4 is complete.
 This guard overrides any lower `Flow: ... -> /trellis:finish-work` line in this state block.
 At Phase 3.4, code commit/push still goes through `trellis-push` (commit-only for commit-without-push); never bare `git commit`/`git push` on code (hub: Code Commit Confirmation Gate).
-If active task.json has `last_push_snapshot`, relay `partial_step` + `next_step` once before starting new work.
+Push snapshot recovery: follow the hub; use `push_snapshot.py status --json` only when needed.
 <!-- END skill-garden workflow-state in_progress_inline v0.6 -->

package/enhancements/0.6/overrides/workflow-states/in_progress.md

@@ -2,7 +2,7 @@
 HIGHEST PRIORITY SKILL-GARDEN STATE GUARD (in_progress):
 This state block is a breadcrumb; the top-level skill-garden hub is the source of truth for route details.
 Before the first implement route, read `<task>/brief.md` if present and restate the task brief in chat. If it is missing, read the task artifacts and suggest backfilling brief; do not silently rely on memory.
-Before procedural or high-impact actions, run `.trellis/scripts/spec_router.py` with a short query describing the intended action and read the strongest 1-2 matched SOP/spec files before acting.
+At project-local knowledge decision boundaries, run `.trellis/scripts/spec_router.py` with a short query describing the intended action; read high-confidence matches before acting and skip pure Q&A, simple read-only inspection, opening local tools, or trivial edits unless local conventions may affect the approach.
 At Phase 2.1/2.2, reuse only an explicit target-matched `route_decision`; otherwise MUST load/read/use `trellis-route(implement|check)` (or its local `SKILL.md`) to resolve session runtime state/prefs, write the resolved decision, or show numbered fallback and wait.
 Plain preferences, ordinary summaries, `codex-mode`, raw `.runtime` files, and empty/old prefs are not route evidence by themselves; only `trellis-route` may validate runtime route state.
 User reselect/override/use-X-this-time/clear-default wins over remembered route evidence, runtime state, and prefs.
@@ -10,5 +10,5 @@ Ignore lower Active Task Routing shortcuts that dispatch implement/check directl
 After `trellis-check` / `trellis-check-all`, stop and report; point the user to Phase 3.4 `trellis-push` (or commit-only when needed). Do not run `/trellis:finish-work` unless the user explicitly asks after Phase 3.4 is complete.
 This guard overrides any lower `Flow: ... -> /trellis:finish-work` line in this state block.
 At Phase 3.4, code commit/push goes through `trellis-push` (commit-only mode for commit-without-push); never bare `git commit`/`git push` on code (hub: Code Commit Confirmation Gate).
-If active task.json has `last_push_snapshot`, relay `partial_step` + `next_step` once before starting new work.
+Push snapshot recovery: follow the hub; use `push_snapshot.py status --json` only when needed.
 <!-- END skill-garden workflow-state in_progress v0.6 -->

package/enhancements/0.6/overrides/workflow-states/no_task.md

@@ -2,8 +2,8 @@
 HIGHEST PRIORITY SKILL-GARDEN STATE GUARD (no_task):
 Creating or resuming a task is not implementation permission.
 After PRD is ready and the task is started, the next implementation action is Phase 2.1 `trellis-route(implement)` unless a valid current-task implement route decision already exists.
-If no active task exists, scan `.trellis/tasks/*/task.json` once per session for in-progress tasks with `last_push_snapshot`; surface `completed_steps` + `next_step` and suggest rebinding the active task before resuming.
-Before procedural or high-impact actions, run `.trellis/scripts/spec_router.py` with a short query describing the intended action and read the strongest 1-2 matched SOP/spec files before acting.
+If no active task exists, use `push_snapshot.py status --json` once per session; if it returns candidates, relay them and suggest rebinding before resuming.
+At project-local knowledge decision boundaries, run `.trellis/scripts/spec_router.py` with a short query describing the intended action; read high-confidence matches before acting and skip pure Q&A, simple read-only inspection, opening local tools, or trivial edits unless local conventions may affect the approach.
 Do NOT call the harness built-in plan mode (`EnterPlanMode` / `ExitPlanMode`) for Trellis planning. It is not a substitute for Trellis task-creation consent, Trellis planning, or the route gate. For complex work, classify the turn, ask for task-creation consent, then use `trellis-brainstorm`.
 If the turn is a meta edit to Trellis itself and Trellis tracking would be overkill, say so and ask to skip Trellis; never silently swap built-in plan mode in for the consent gate.
 <!-- END skill-garden workflow-state no_task v0.6 -->

package/enhancements/0.6/overrides/workflow-states/planning-inline.md

@@ -4,6 +4,6 @@ Planning is not implementation permission.
 Complete prd.md + required context first.
 If the active workflow later routes to sub-agent execution, required context includes real curated entries in both `implement.jsonl` and `check.jsonl`; the seed `_example` row alone is not ready.
 Before `task.py start`, use `trellis-task-brief` to refresh `brief.md` from the latest task artifacts and display it in chat for review.
-Before procedural or high-impact actions, run `.trellis/scripts/spec_router.py` with a short query describing the intended action and read the strongest 1-2 matched SOP/spec files before acting.
+At project-local knowledge decision boundaries, run `.trellis/scripts/spec_router.py` with a short query describing the intended action; read high-confidence matches before acting and skip pure Q&A, simple read-only inspection, opening local tools, or trivial edits unless local conventions may affect the approach.
 After status becomes in_progress, next action = `trellis-route(implement)`, not direct edits.
 <!-- END skill-garden workflow-state planning_inline v0.6 -->

package/enhancements/0.6/overrides/workflow-states/planning.md

@@ -4,6 +4,6 @@ Planning is not implementation permission.
 Complete prd.md + required context first.
 For sub-agent-dispatch platforms, required context includes real curated entries in both `implement.jsonl` and `check.jsonl`; the seed `_example` row alone is not ready.
 Before `task.py start`, use `trellis-task-brief` to refresh `brief.md` from the latest task artifacts and display it in chat for review.
-Before procedural or high-impact actions, run `.trellis/scripts/spec_router.py` with a short query describing the intended action and read the strongest 1-2 matched SOP/spec files before acting.
+At project-local knowledge decision boundaries, run `.trellis/scripts/spec_router.py` with a short query describing the intended action; read high-confidence matches before acting and skip pure Q&A, simple read-only inspection, opening local tools, or trivial edits unless local conventions may affect the approach.
 After status becomes in_progress, next action = `trellis-route(implement)`, not direct edits.
 <!-- END skill-garden workflow-state planning v0.6 -->

package/enhancements/0.6/overrides/workflow.md

@@ -6,13 +6,17 @@
 
 **Priority**: This hub overrides any conflicting Trellis workflow, skill, or command text for the scoped behaviors below.
 
-**Scope**: project knowledge discovery for procedural/high-impact actions, Phase 1.4 task brief handoff, Phase 2.1 implement routing, Phase 2.2 check/check-all routing, current-task route reuse, post-check stop, auto-loop commit-only preauthorization, Phase 3.4 trellis-push, explicit Phase 3.5 finish-work bookkeeping, and push-progress recovery. State blocks should keep one short skill-garden sentinel; long-form rules live here.
+**Scope**: project knowledge discovery at project-local knowledge decision boundaries, Phase 1.4 task brief handoff, Phase 2.1 implement routing, Phase 2.2 check/check-all routing, current-task route reuse, post-check stop, auto-loop commit-only preauthorization, Phase 3.4 trellis-push, explicit Phase 3.5 finish-work bookkeeping, and push-progress recovery. State blocks should keep one short skill-garden sentinel; long-form rules live here.
 
 **Mechanical rule**: use this hub as the source of truth. Do not add separate top-level skill-garden override sections or multiple skill-garden sentinels inside the same `workflow-state:*` block.
 
 #### Project Knowledge Discovery
 
-Before procedural or high-impact actions, run project knowledge discovery:
+Before choosing an approach for non-trivial project work, run project knowledge
+discovery when project-local SOPs, package conventions, workflow rules,
+config/state contracts, release/publish/deploy steps, git history actions,
+data changes, cross-layer design, generated artifacts, install/sync pipelines,
+or destructive operations may affect the correct approach:
 
 ```bash
 python3 ./.trellis/scripts/spec_router.py "<short query describing the intended action>"
@@ -21,11 +25,15 @@ python3 ./.trellis/scripts/spec_router.py "<short query describing the intended
 Build the query from the current user request plus relevant immediate context:
 the intended action, commands about to run, files or systems involved, package/layer,
 and domain words such as release, publish, deploy, migration, config, CI, workflow,
-hooks, rollback, data fix, or destructive command.
+hooks, rollback, data fix, generated artifact, install/sync pipeline, or destructive command.
 
-Read the strongest 1-2 matched SOP/spec files before acting. Continue to lower-ranked
-matches only when their path, heading, or trigger reason is clearly relevant; if
-nothing matches, continue normally.
+Read high-confidence matches before acting. For medium-confidence matches, read only
+when the path, heading, index description, or reason clearly fits the intended change.
+If nothing matches, continue normally.
+
+Do not run discovery for pure Q&A, simple read-only inspection, opening local tools,
+or trivial edits unless the request mentions project conventions or local SOPs may
+change the approach.
 
 #### Task Brief Handoff
 
@@ -46,7 +54,7 @@ At each route boundary:
 3. If the platform cannot invoke skills directly, open the local `trellis-route/SKILL.md` copy first, then follow its numbered fallback choices in normal chat and wait.
 4. If the route helper cannot ask through `AskUserQuestion` / `request_user_input`, ask the same numbered choices from `trellis-route` in normal chat and wait.
 
-Plain user preference, ordinary compact/SessionStart summary, `codex-mode`, empty/old prefs, and raw `.trellis/.runtime/sessions/*` `route_decisions` content that has not been validated by `trellis-route` are not route evidence by themselves.
+Plain user preference, ordinary compact/SessionStart summary, ordinary summary, replacement history, historical bare numeric replies, `codex-mode`, empty/old prefs, and raw `.trellis/.runtime/sessions/*` `route_decisions` content that has not been validated by `trellis-route` are not route evidence by themselves; numbered fallback validity is governed by `trellis-route`.
 
 User reselect/override/use-X-this-time/clear-default wins over remembered route evidence, runtime state, and personal prefs.
 
@@ -80,10 +88,10 @@ This exception does not apply to ordinary `trellis-push`. If the plan contains u
 
 #### Push Progress Recovery / Snapshot
 
-`trellis-push` may write `last_push_snapshot` into an active task's `task.json` with this schema: `snapshot_at`, `branch`, `pushed_commits`, `completed_steps`, `partial_step`, `next_step`, and `notes`.
+Use `python3 ./.trellis/scripts/push_snapshot.py status --json` for recovery reads and `write --task ... --snapshot-json ...` for `trellis-push` writes; do not hand-scan or hand-edit `task.json`.
 
-When there is no active task, scan `.trellis/tasks/*/task.json` for `status="in_progress"` entries that carry `last_push_snapshot`. If any exist and this session has not already relayed recovery, surface the paused state to the user and suggest rebinding the active-task pointer before resuming.
+`trellis-push` still owns snapshot semantics, user confirmation, git operations, and post-run fields; the helper only touches `task.json.last_push_snapshot`.
 
-When an active in-progress task carries `last_push_snapshot`, briefly relay `partial_step` and `next_step` before starting new work. Skip the reminder if it was already relayed in this session or the field is absent.
+On recovery, relay the helper's `summary` / `candidates` once and suggest rebinding if there is no active task. Never auto-rebind, infer workflow phase, or hook this into SessionStart / workflow-state injection / `trellis-continue`.
 
 <!-- END skill-garden overrides v0.6 -->

package/enhancements/0.6/scripts/push_snapshot.py

@@ -0,0 +1,387 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""读取和写入 Trellis 任务的 last_push_snapshot。"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+
+DIR_WORKFLOW = ".trellis"
+DIR_TASKS = "tasks"
+FILE_TASK_JSON = "task.json"
+REQUIRED_FIELDS = {
+    "snapshot_at",
+    "branch",
+    "pushed_commits",
+    "completed_steps",
+    "next_step",
+}
+OPTIONAL_STRING_FIELDS = {"partial_step", "notes"}
+
+
+def _find_repo_root(start: Path) -> Path | None:
+    """从当前位置向上查找 Trellis 项目根目录。"""
+    current = start.resolve()
+    if current.is_file():
+        current = current.parent
+    while True:
+        if (current / DIR_WORKFLOW).is_dir():
+            return current
+        if current == current.parent:
+            return None
+        current = current.parent
+
+
+def _scripts_dir(repo_root: Path) -> Path:
+    """返回当前项目的 Trellis scripts 目录。"""
+    return repo_root / DIR_WORKFLOW / "scripts"
+
+
+def _load_common_modules(repo_root: Path) -> None:
+    """把 `.trellis/scripts` 加入 import path 以复用 Trellis 公共模块。"""
+    scripts_dir = _scripts_dir(repo_root)
+    if str(scripts_dir) not in sys.path:
+        sys.path.insert(0, str(scripts_dir))
+
+
+def _read_json(path: Path) -> dict[str, Any] | None:
+    """读取 JSON 对象，失败或非对象时返回 None。"""
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _write_json(path: Path, data: dict[str, Any]) -> None:
+    """用 Trellis 任务文件常见格式写回 JSON。"""
+    path.write_text(
+        json.dumps(data, indent=2, ensure_ascii=False) + "\n",
+        encoding="utf-8",
+    )
+
+
+def _rel_path(repo_root: Path, path: Path) -> str:
+    """尽量输出 repo-root 相对路径。"""
+    try:
+        return path.relative_to(repo_root).as_posix()
+    except ValueError:
+        return str(path)
+
+
+def _resolve_task_dir(repo_root: Path, task_ref: str) -> Path:
+    """解析任务目录引用。"""
+    _load_common_modules(repo_root)
+    from common.task_utils import resolve_task_dir  # type: ignore[import-not-found]
+
+    return resolve_task_dir(task_ref, repo_root)
+
+
+def _current_task_dir(repo_root: Path) -> Path | None:
+    """读取当前 session 的 active task 目录。"""
+    _load_common_modules(repo_root)
+    from common.active_task import resolve_active_task  # type: ignore[import-not-found]
+
+    active = resolve_active_task(repo_root)
+    if not active.task_path:
+        return None
+    task_dir = Path(active.task_path)
+    if task_dir.is_absolute():
+        return task_dir
+    return repo_root / task_dir
+
+
+def _task_json_path(task_dir: Path) -> Path:
+    """返回任务 task.json 路径。"""
+    return task_dir / FILE_TASK_JSON
+
+
+def _snapshot_summary(snapshot: dict[str, Any]) -> dict[str, Any]:
+    """提取恢复提示需要的精简 snapshot 字段。"""
+    return {
+        "completed_steps": snapshot.get("completed_steps", []),
+        "partial_step": snapshot.get("partial_step"),
+        "next_step": snapshot.get("next_step"),
+    }
+
+
+def _load_task_snapshot(repo_root: Path, task_dir: Path) -> dict[str, Any]:
+    """读取单个任务的 snapshot 状态。"""
+    task_json = _task_json_path(task_dir)
+    data = _read_json(task_json)
+    task_rel = _rel_path(repo_root, task_dir)
+    if data is None:
+        return {
+            "status": "error",
+            "reason": "invalid-task-json",
+            "task": task_rel,
+            "path": _rel_path(repo_root, task_json),
+        }
+    snapshot = data.get("last_push_snapshot")
+    if not isinstance(snapshot, dict):
+        return {"status": "no-snapshot", "task": task_rel}
+    return {
+        "status": "ok",
+        "task": task_rel,
+        "snapshot": snapshot,
+        "summary": _snapshot_summary(snapshot),
+    }
+
+
+def _iter_active_task_dirs(repo_root: Path) -> list[Path]:
+    """列出 active task tree 下的一层任务目录。"""
+    tasks_dir = repo_root / DIR_WORKFLOW / DIR_TASKS
+    try:
+        return [
+            path for path in sorted(tasks_dir.iterdir())
+            if path.is_dir() and path.name != "archive"
+        ]
+    except OSError:
+        return []
+
+
+def _snapshot_candidates(repo_root: Path) -> list[dict[str, Any]]:
+    """扫描 in_progress 且带 last_push_snapshot 的任务候选。"""
+    candidates: list[dict[str, Any]] = []
+    for task_dir in _iter_active_task_dirs(repo_root):
+        task_json = _task_json_path(task_dir)
+        data = _read_json(task_json)
+        if data is None:
+            continue
+        if data.get("status") != "in_progress":
+            continue
+        snapshot = data.get("last_push_snapshot")
+        if not isinstance(snapshot, dict):
+            continue
+        candidates.append({
+            "task": _rel_path(repo_root, task_dir),
+            **_snapshot_summary(snapshot),
+        })
+    return candidates
+
+
+def _validate_string(value: Any, field: str, errors: list[str]) -> None:
+    """校验字符串字段。"""
+    if not isinstance(value, str) or not value.strip():
+        errors.append(f"{field} 必须是非空字符串")
+
+
+def _validate_string_or_object(value: Any, field: str, errors: list[str]) -> None:
+    """校验字符串或对象字段。"""
+    if isinstance(value, str) and value.strip():
+        return
+    if isinstance(value, dict):
+        return
+    errors.append(f"{field} 必须是非空字符串或对象")
+
+
+def _validate_snapshot(snapshot: Any) -> tuple[dict[str, Any] | None, list[str]]:
+    """校验 last_push_snapshot schema。"""
+    if not isinstance(snapshot, dict):
+        return None, ["snapshot 必须是 JSON 对象"]
+
+    errors: list[str] = []
+    for field in sorted(REQUIRED_FIELDS):
+        if field not in snapshot:
+            errors.append(f"缺少必填字段 {field}")
+
+    if "snapshot_at" in snapshot:
+        _validate_string(snapshot.get("snapshot_at"), "snapshot_at", errors)
+    if "branch" in snapshot:
+        _validate_string_or_object(snapshot.get("branch"), "branch", errors)
+    if "pushed_commits" in snapshot:
+        _validate_string_or_object(
+            snapshot.get("pushed_commits"),
+            "pushed_commits",
+            errors,
+        )
+    completed_steps = snapshot.get("completed_steps")
+    if "completed_steps" in snapshot and (
+        not isinstance(completed_steps, list)
+        or any(not isinstance(item, str) for item in completed_steps)
+    ):
+        errors.append("completed_steps 必须是字符串数组")
+    if "next_step" in snapshot:
+        _validate_string(snapshot.get("next_step"), "next_step", errors)
+
+    for field in sorted(OPTIONAL_STRING_FIELDS):
+        if field in snapshot and snapshot.get(field) is not None and not isinstance(snapshot.get(field), str):
+            errors.append(f"{field} 存在时必须是字符串")
+
+    if errors:
+        return None, errors
+    return snapshot, []
+
+
+def _print_json(data: dict[str, Any], exit_code: int = 0) -> int:
+    """输出紧凑 JSON。"""
+    print(json.dumps(data, ensure_ascii=False, sort_keys=True))
+    return exit_code
+
+
+def _print_status_text(data: dict[str, Any]) -> int:
+    """输出给人和 AI 快速阅读的状态文本。"""
+    status = data.get("status")
+    if status == "ok":
+        summary = data.get("summary") if isinstance(data.get("summary"), dict) else {}
+        print(f"任务：{data.get('task')}")
+        print("snapshot：存在")
+        print(f"completed_steps: {summary.get('completed_steps', [])}")
+        print(f"partial_step: {summary.get('partial_step') or '(none)'}")
+        print(f"next_step: {summary.get('next_step') or '(none)'}")
+        return 0
+    if status == "candidates":
+        candidates = data.get("candidates")
+        print("无活动任务。snapshot 候选：")
+        if isinstance(candidates, list) and candidates:
+            for item in candidates:
+                print(f"- {item.get('task')}: next_step={item.get('next_step') or '(none)'}")
+        else:
+            print("(none)")
+        return 0
+    if status == "no-snapshot":
+        print(f"任务没有 last_push_snapshot：{data.get('task')}")
+        return 0
+    if status == "no-current-task":
+        print("没有活动任务，也没有可用的 snapshot 候选。")
+        return 0
+    print(f"错误：{data.get('reason') or status}", file=sys.stderr)
+    return 1
+
+
+def cmd_status(args: argparse.Namespace, repo_root: Path) -> int:
+    """执行 status 子命令。"""
+    if args.task:
+        task_dir = _resolve_task_dir(repo_root, args.task)
+        result = _load_task_snapshot(repo_root, task_dir)
+    else:
+        task_dir = _current_task_dir(repo_root)
+        if task_dir is None:
+            candidates = _snapshot_candidates(repo_root)
+            result = {
+                "status": "candidates" if candidates else "no-current-task",
+                "candidates": candidates,
+            }
+        else:
+            result = _load_task_snapshot(repo_root, task_dir)
+
+    exit_code = 1 if result.get("status") == "error" else 0
+    if args.json:
+        return _print_json(result, exit_code)
+    return _print_status_text(result)
+
+
+def cmd_write(args: argparse.Namespace, repo_root: Path) -> int:
+    """执行 write 子命令。"""
+    task_dir = _resolve_task_dir(repo_root, args.task)
+    task_json = _task_json_path(task_dir)
+    data = _read_json(task_json)
+    if data is None:
+        result = {
+            "status": "error",
+            "reason": "invalid-task-json",
+            "task": _rel_path(repo_root, task_dir),
+        }
+        if args.json:
+            return _print_json(result, 1)
+        print(f"错误：{result['reason']}", file=sys.stderr)
+        return 1
+
+    try:
+        raw_snapshot = json.loads(args.snapshot_json)
+    except json.JSONDecodeError as exc:
+        result = {
+            "status": "error",
+            "reason": "invalid-snapshot-json",
+            "message": str(exc),
+        }
+        if args.json:
+            return _print_json(result, 1)
+        print(f"错误：{result['reason']}：{result['message']}", file=sys.stderr)
+        return 1
+
+    snapshot, errors = _validate_snapshot(raw_snapshot)
+    if snapshot is None:
+        result = {
+            "status": "error",
+            "reason": "invalid-snapshot-schema",
+            "errors": errors,
+        }
+        if args.json:
+            return _print_json(result, 1)
+        print("错误：invalid-snapshot-schema", file=sys.stderr)
+        for error in errors:
+            print(f"- {error}", file=sys.stderr)
+        return 1
+
+    data["last_push_snapshot"] = snapshot
+    try:
+        _write_json(task_json, data)
+    except OSError as exc:
+        result = {
+            "status": "error",
+            "reason": "write-failed",
+            "message": str(exc),
+            "task": _rel_path(repo_root, task_dir),
+        }
+        if args.json:
+            return _print_json(result, 1)
+        print(f"错误：write-failed：{exc}", file=sys.stderr)
+        return 1
+
+    result = {
+        "status": "written",
+        "task": _rel_path(repo_root, task_dir),
+        "path": _rel_path(repo_root, task_json),
+        "summary": _snapshot_summary(snapshot),
+    }
+    if args.json:
+        return _print_json(result)
+    print(f"✓ 已更新 last_push_snapshot：{result['path']}")
+    print(f"next_step: {result['summary'].get('next_step') or '(none)'}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """创建命令行解析器。"""
+    parser = argparse.ArgumentParser(
+        description="读取或写入 Trellis 任务的 last_push_snapshot。",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    status = subparsers.add_parser("status", help="读取 last_push_snapshot")
+    status.add_argument("--task", help="任务目录、路径或任务名")
+    status.add_argument("--json", action="store_true", help="输出 JSON")
+
+    write = subparsers.add_parser("write", help="写入 last_push_snapshot")
+    write.add_argument("--task", required=True, help="任务目录、路径或任务名")
+    write.add_argument("--snapshot-json", required=True, help="snapshot JSON 对象")
+    write.add_argument("--json", action="store_true", help="输出 JSON")
+
+    return parser
+
+
+def main() -> int:
+    """命令入口。"""
+    repo_root = _find_repo_root(Path.cwd())
+    if repo_root is None:
+        print("错误：不是 Trellis 项目（缺少 .trellis/）", file=sys.stderr)
+        return 1
+
+    parser = build_parser()
+    args = parser.parse_args()
+    if args.command == "status":
+        return cmd_status(args, repo_root)
+    if args.command == "write":
+        return cmd_write(args, repo_root)
+    parser.print_help()
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/enhancements/0.6/scripts/spec_router.py

@@ -2,8 +2,8 @@
 # -*- coding: utf-8 -*-
 """从 `.trellis/spec/` 发现相关项目 SOP/spec 文件。
 
-这个 helper 刻意保持轻量：只返回候选路径和命中原因，让 AI 在执行流程性或
-高影响动作前读取匹配文件；它不把完整文档注入上下文。
+这个 helper 刻意保持轻量：只返回候选路径、置信度和命中原因，让 AI 在项目
+局部知识可能影响做法的决策边界前读取匹配文件；它不把完整文档注入上下文。
 """
 
 from __future__ import annotations
@@ -21,40 +21,72 @@ MAX_BODY_CHARS = 8000
 DEFAULT_LIMIT = 3
 MIN_SCORE = 3
 MIN_BODY_ONLY_HITS = 5
-MIN_HEADING_BODY_HITS = 3
-BODY_WEAK_TOKENS = {
+MIN_ANCHORED_BODY_HITS = 2
+WEAK_TOKENS = {
     "action",
     "actions",
     "after",
+    "and",
     "before",
+    "change",
+    "changes",
+    "cli",
     "command",
     "commands",
+    "commit",
     "context",
     "current",
+    "data",
+    "documentation",
+    "edit",
     "file",
     "files",
+    "flow",
+    "flower",
+    "for",
+    "from",
+    "guide",
+    "guides",
+    "in",
+    "index",
     "match",
     "matched",
     "matches",
     "matching",
+    "md",
     "normal",
+    "of",
+    "or",
     "path",
     "paths",
     "project",
+    "py",
     "read",
+    "readme",
     "reason",
     "reasons",
     "relevant",
+    "run",
+    "simple",
+    "small",
     "sop",
     "spec",
     "status",
     "task",
     "tasks",
+    "the",
+    "to",
+    "trellis",
+    "typo",
+    "update",
+    "with",
     "workflow",
 }
-TOKEN_RE = re.compile(r"[A-Za-z0-9_.@/-]+|[\u4e00-\u9fff]{2,}")
+TOKEN_RE = re.compile(r"[A-Za-z0-9@]+|[\u4e00-\u9fff]+")
+CJK_RE = re.compile(r"^[\u4e00-\u9fff]+$")
 HEADER_RE = re.compile(r"^\s{0,3}#{1,3}\s+(.+?)\s*$", re.MULTILINE)
 FRONTMATTER_BOUNDARY_RE = re.compile(r"^---\s*$")
+MARKDOWN_LINK_RE = re.compile(r"\[([^\]]+)\]\(([^)]+\.md(?:#[^)]+)?)\)")
 
 
 @dataclass
@@ -66,7 +98,9 @@ class Candidate:
     kind: str
     load: str
     priority: str
+    confidence: str
     reasons: list[str]
+    action: str
 
 
 def find_trellis_root(start: Path) -> Path | None:
@@ -183,8 +217,45 @@ def as_list(value: Any) -> list[str]:
     return [text] if text else []
 
 
+def add_token(tokens: list[str], seen: set[str], token: str) -> None:
+    """按原始顺序追加去重 token。
+
+    Args:
+        tokens: 正在构造的 token 列表。
+        seen: 已追加 token 集合。
+        token: 待追加 token。
+
+    Returns:
+        None。
+    """
+    if len(token) < 2 or token in seen:
+        return
+    seen.add(token)
+    tokens.append(token)
+
+
+def add_cjk_tokens(tokens: list[str], seen: set[str], text: str) -> None:
+    """为连续中文文本追加有限 n-gram token。
+
+    中文没有空格分词。这里生成 2 到 6 字的 n-gram，用 token 集合匹配替代旧
+    版任意子串匹配，同时保留 `发版` 命中 `发版流程` 这类常见能力。
+
+    Args:
+        tokens: 正在构造的 token 列表。
+        seen: 已追加 token 集合。
+        text: 连续中文文本。
+
+    Returns:
+        None。
+    """
+    max_size = min(6, len(text))
+    for size in range(2, max_size + 1):
+        for start in range(0, len(text) - size + 1):
+            add_token(tokens, seen, text[start : start + size])
+
+
 def normalize_tokens(text: str) -> list[str]:
-    """提取查询 token，用于确定性的轻量匹配。
+    """提取查询或文档 token，用于确定性的轻量匹配。
 
     Args:
         text: 查询或可搜索文本。
@@ -195,14 +266,129 @@ def normalize_tokens(text: str) -> list[str]:
     seen: set[str] = set()
     tokens: list[str] = []
     for match in TOKEN_RE.finditer(text.lower()):
-        token = match.group(0).strip("._-/")
-        if len(token) < 2 or token in seen:
-            continue
-        seen.add(token)
-        tokens.append(token)
+        token = match.group(0)
+        if CJK_RE.match(token):
+            add_cjk_tokens(tokens, seen, token)
+        else:
+            add_token(tokens, seen, token)
     return tokens
 
 
+def significant_hits(query_tokens: list[str], target_tokens: list[str]) -> list[str]:
+    """计算非弱词 token 命中，保留查询 token 顺序。
+
+    Args:
+        query_tokens: 查询 token。
+        target_tokens: 待匹配文本 token。
+
+    Returns:
+        非弱词命中列表。
+    """
+    target_set = set(target_tokens)
+    return [
+        token
+        for token in query_tokens
+        if token not in WEAK_TOKENS and token in target_set
+    ]
+
+
+def collect_index_descriptions(spec_dir: Path) -> dict[str, list[str]]:
+    """从 `index.md` 链接行收集目标文档的路由描述。
+
+    Args:
+        spec_dir: `.trellis/spec` 目录。
+
+    Returns:
+        以 spec 相对路径为 key 的描述文本列表。
+    """
+    descriptions: dict[str, list[str]] = {}
+    spec_root = spec_dir.resolve()
+    for index_path in iter_spec_files(spec_dir):
+        if index_path.name != "index.md":
+            continue
+
+        text = read_markdown(index_path)
+        if text is None:
+            continue
+        _, body = parse_frontmatter(text)
+
+        for line in body.splitlines():
+            matches = list(MARKDOWN_LINK_RE.finditer(line))
+            if not matches:
+                continue
+
+            clean_line = MARKDOWN_LINK_RE.sub(lambda item: item.group(1), line).strip()
+            for match in matches:
+                link_target = match.group(2).split("#", 1)[0].strip()
+                if "://" in link_target or link_target.startswith("#"):
+                    continue
+
+                target_path = (index_path.parent / link_target).resolve()
+                try:
+                    target_rel_path = target_path.relative_to(spec_root).as_posix()
+                except ValueError:
+                    continue
+
+                if not target_path.is_file() or target_path == index_path.resolve():
+                    continue
+
+                description = f"{match.group(1)} {clean_line}".strip()
+                if description:
+                    descriptions.setdefault(target_rel_path, []).append(description)
+    return descriptions
+
+
+def classify_confidence(
+    matched_triggers: list[str],
+    path_hits: list[str],
+    header_hits: list[str],
+    index_hits: list[str],
+    body_hits: list[str],
+) -> str | None:
+    """根据强锚点和弱证据判断候选置信度。
+
+    Args:
+        matched_triggers: frontmatter trigger 命中。
+        path_hits: 路径命中。
+        header_hits: 标题命中。
+        index_hits: index 描述命中。
+        body_hits: 正文样本命中。
+
+    Returns:
+        `high` / `medium`；证据不足时返回 None。
+    """
+    if matched_triggers:
+        return "high"
+
+    anchor_groups = [path_hits, header_hits, index_hits]
+    anchor_count = sum(1 for group in anchor_groups if group)
+    if len(path_hits) >= 2 or len(header_hits) >= 2 or len(index_hits) >= 2:
+        return "high"
+    if anchor_count >= 2:
+        return "high"
+    if anchor_count == 1 and len(body_hits) >= MIN_ANCHORED_BODY_HITS:
+        return "high"
+    if anchor_count == 1:
+        return "medium"
+    if len(body_hits) >= MIN_BODY_ONLY_HITS:
+        return "medium"
+    return None
+
+
+def action_for_confidence(confidence: str) -> str:
+    """按置信度返回读取建议。
+
+    Args:
+        confidence: 候选置信度。
+
+    Returns:
+        面向 AI 的行动建议。
+    """
+    if confidence == "high":
+        return "read before acting"
+    return "read if clearly relevant"
+
+
 def read_markdown(path: Path) -> str | None:
     """以容错 UTF-8 方式读取 Markdown 文件。
 
@@ -239,7 +425,13 @@ def iter_spec_files(spec_dir: Path) -> list[Path]:
     return sorted(result)
 
 
-def score_file(root: Path, path: Path, query: str, query_tokens: list[str]) -> Candidate | None:
+def score_file(
+    root: Path,
+    path: Path,
+    query: str,
+    query_tokens: list[str],
+    index_descriptions: dict[str, list[str]],
+) -> Candidate | None:
     """按查询为一个 Markdown spec 文件打分。
 
     Args:
@@ -247,6 +439,7 @@ def score_file(root: Path, path: Path, query: str, query_tokens: list[str]) -> C
         path: Markdown 文件路径。
         query: 原始查询文本。
         query_tokens: 标准化后的查询 token。
+        index_descriptions: 从 index.md 收集的目标文档描述。
 
     Returns:
         分数达到阈值时返回候选项，否则返回 None。
@@ -258,11 +451,13 @@ def score_file(root: Path, path: Path, query: str, query_tokens: list[str]) -> C
     metadata, body = parse_frontmatter(text)
     rel_path = path.relative_to(root).as_posix()
     spec_rel_path = path.relative_to(root / ".trellis" / "spec").as_posix()
-    spec_rel_lower = spec_rel_path.lower()
+    spec_rel_tokens = normalize_tokens(spec_rel_path)
     body_sample = body[:MAX_BODY_CHARS]
-    body_lower = body_sample.lower()
+    body_tokens = normalize_tokens(body_sample)
     headers = HEADER_RE.findall(body)
-    header_text = " ".join(headers).lower()
+    header_tokens = normalize_tokens(" ".join(headers))
+    index_text = " ".join(index_descriptions.get(spec_rel_path, []))
+    index_tokens = normalize_tokens(index_text)
 
     kind = str(metadata.get("kind") or "").strip()
     load = str(metadata.get("load") or "").strip()
@@ -282,31 +477,35 @@ def score_file(root: Path, path: Path, query: str, query_tokens: list[str]) -> C
         score += 8 * len(matched_triggers)
         reasons.append(f"matched triggers: {', '.join(matched_triggers[:5])}")
 
-    path_hits = [token for token in query_tokens if token in spec_rel_lower]
+    path_hits = significant_hits(query_tokens, spec_rel_tokens)
     if path_hits:
-        score += 4 * len(path_hits)
+        score += 5 * len(path_hits)
         reasons.append(f"matched path tokens: {', '.join(path_hits[:5])}")
 
-    header_hits = [token for token in query_tokens if token in header_text]
+    header_hits = significant_hits(query_tokens, header_tokens)
     if header_hits:
         score += 3 * len(header_hits)
         reasons.append(f"matched headings: {', '.join(header_hits[:5])}")
 
-    raw_body_hits = [token for token in query_tokens if token in body_lower]
-    body_hits = [token for token in raw_body_hits if token not in BODY_WEAK_TOKENS]
+    index_hits = significant_hits(query_tokens, index_tokens)
+    if index_hits:
+        score += 4 * len(index_hits)
+        reasons.append(f"matched index descriptions: {', '.join(index_hits[:5])}")
+
+    body_hits = significant_hits(query_tokens, body_tokens)
     if body_hits:
         score += len(body_hits)
         reasons.append(f"matched body tokens: {', '.join(body_hits[:5])}")
 
-    # 避免 `json` / `output` / `spec` 这类泛词把只有正文弱命中的文件全部拉进上下文。
-    strong_match = (
-        bool(matched_triggers)
-        or bool(path_hits)
-        or len(header_hits) >= 2
-        or (bool(header_hits) and len(body_hits) >= MIN_HEADING_BODY_HITS)
-        or len(body_hits) >= MIN_BODY_ONLY_HITS
+    # 避免 `to` / `flow` / `commit` 这类泛词或少量正文词把无关文件拉进上下文。
+    confidence = classify_confidence(
+        matched_triggers,
+        path_hits,
+        header_hits,
+        index_hits,
+        body_hits,
     )
-    if not strong_match:
+    if confidence is None:
         return None
 
     if kind.lower() in {"sop", "procedure", "guide", "thinking-guide"} and score > 0:
@@ -325,7 +524,9 @@ def score_file(root: Path, path: Path, query: str, query_tokens: list[str]) -> C
         kind=kind or ("thinking-guide" if "/guides/" in f"/{rel_path}" else "spec"),
         load=load,
         priority=priority,
+        confidence=confidence,
         reasons=reasons,
+        action=action_for_confidence(confidence),
     )
 
 
@@ -345,12 +546,20 @@ def find_candidates(root: Path, query: str, limit: int) -> list[Candidate]:
         return []
 
     candidates: list[Candidate] = []
-    for path in iter_spec_files(root / ".trellis" / "spec"):
-        candidate = score_file(root, path, query, query_tokens)
+    spec_dir = root / ".trellis" / "spec"
+    index_descriptions = collect_index_descriptions(spec_dir)
+    for path in iter_spec_files(spec_dir):
+        candidate = score_file(root, path, query, query_tokens, index_descriptions)
         if candidate:
             candidates.append(candidate)
 
-    candidates.sort(key=lambda item: (-item.score, item.path))
+    candidates.sort(
+        key=lambda item: (
+            0 if item.confidence == "high" else 1,
+            -item.score,
+            item.path,
+        )
+    )
     return candidates[:limit]
 
 
@@ -372,13 +581,14 @@ def format_markdown(candidates: list[Candidate]) -> str:
         lines.append(f"- {candidate.path}")
         lines.append(f"  kind: {candidate.kind}")
         lines.append(f"  score: {candidate.score}")
+        lines.append(f"  confidence: {candidate.confidence}")
         if candidate.load:
             lines.append(f"  load: {candidate.load}")
         if candidate.priority:
             lines.append(f"  priority: {candidate.priority}")
         if candidate.reasons:
             lines.append(f"  reason: {'; '.join(candidate.reasons)}")
-        lines.append("  action: read before acting")
+        lines.append(f"  action: {candidate.action}")
     return "\n".join(lines)
 
 
@@ -396,10 +606,11 @@ def format_json(candidates: list[Candidate]) -> str:
             "file": candidate.path,
             "kind": candidate.kind,
             "score": candidate.score,
+            "confidence": candidate.confidence,
             "load": candidate.load,
             "priority": candidate.priority,
             "reason": candidate.reasons,
-            "action": "read before acting",
+            "action": candidate.action,
         }
         for candidate in candidates
     ]

package/enhancements/MANIFEST.json

@@ -1,7 +1,7 @@
 {
-  "syncedAt": "2026-07-01T04:27:03.524Z",
+  "syncedAt": "2026-07-02T01:39:38.800Z",
   "syncedFrom": "vendor/skill-garden",
-  "sourceCommit": "7a9b882db76500b49b38cf423be682fb06effe1a",
+  "sourceCommit": "39a09335cc3e2878c1e1121137dd55524882b13f",
   "common": {
     "codexSkills": [
       "craft-rpa",
@@ -140,6 +140,7 @@
       ],
       "scripts": [
         "auto_loop.py",
+        "push_snapshot.py",
         "spec_router.py"
       ]
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flower-trellis",
-  "version": "0.4.0-beta.4",
+  "version": "0.4.0-beta.5",
   "description": "一键安装/升级 Trellis 并自动融合 skill-garden 强化包(默认 Claude + agents)",
   "type": "module",
   "bin": {

package/src/lib/copy-scripts.js

@@ -24,6 +24,8 @@ export function copyScriptAssets(target, variantDir, skills = []) {
     let aliases = [];
     if (name === "auto_loop") {
       aliases = ["auto-loop", "auto-loop-runner", "trellis-auto-loop"];
+    } else if (name === "push_snapshot") {
+      aliases = ["push-snapshot", "trellis-push", "push", "snapshot"];
     } else if (name === "spec_router") {
       aliases = [
         "spec-router",