flower-trellis 0.4.0-beta.4 → 0.4.0

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 -->