flower-trellis 0.4.0-beta.1 → 0.4.0-beta.2

package/enhancements/0.6/.agents/skills/trellis-auto-loop/SKILL.md

@@ -12,10 +12,13 @@ description: "启动、恢复和推进 Trellis 自动任务循环。用于用户
 - 只有用户明确要求自动跑、auto loop、goal-like、继续自动 run、批量任务队列时才启动或恢复；不要把普通实现请求自动升级为 auto-loop。
 - 每次开始、恢复、压缩后继续时，先运行 runner 的 `resume` 或 `next`，不要凭聊天摘要推断下一步。
 - 每完成一个 action，必须用 `record --action <next 返回的 action>` 精确写回结果；runner 会拒绝缺失或不匹配的 action。写回后立即再调用 `next`，直到 `done`、`blocked` 或需要用户决策。
+- run 进入 `blocked` 后不要用 `start --force` 新建 run 来纠正参数；先补齐缺失 route/context，然后用 `retry-blocked` 在同一个 run 内恢复。
+- runner 默认输出是紧凑 JSON，只包含当前 action、队列计数、简短 blocked/pending/completed 列表和最近少量决策摘要；排障时才给 `status` / `resume` / `next` / `record` / `retry-blocked` 加 `--verbose` 读取完整 item、blocked detail 和 decision data。
 - 默认 profile 是 `commit-only`：自动推进到本地 commit，不 push、不发布、不归档。
 - 多任务只按用户显式给出的任务顺序执行；同一 worktree 不并发。
 - 启动 runner 前先完成 route 准备度判断：已有当前任务 runtime route 决策或个人 `.trellis/.route-prefs.tmp` 时可启动；没有时先进入 `trellis-route` 正常询问 / fallback，写入真实决策后再启动。
-- auto-loop 不默认写 `route_authorization`；如果未来显式传 route 参数，只能表示用户本次明确给出的临时策略，不能当成模型真实执行结果。
+- auto-loop 不默认写 `route_authorization`；只有用户本次明确给出的临时 route 策略，才能通过 `--route-implement` / `--route-check` 传给 runner，且不能当成模型真实执行结果。
+- auto-loop 启动前若 implement 与 check 都缺 route，优先展示 auto-loop 专用的合并选择，不要把 `trellis-route` 的两套完整 fallback 原样贴给用户。仍允许用户回复高级格式 `implement 1, check 1`。
 - 代码提交必须走 `trellis-push` 的 commit-only 语义；不要裸 `git commit` / `git push`。
 
 ## 启动
@@ -29,12 +32,35 @@ python3 .agents/skills/trellis-route/scripts/route_state.py resolve --target imp
 python3 .agents/skills/trellis-route/scripts/route_state.py resolve --target check
 ```
 
-如果任一 target 返回 `status=miss`，先按 `trellis-route` 的正常 numbered fallback 询问用户并写入 runtime；不要替用户默认 inline 或 subagent。route 准备完成后启动 runner：
+如果两个 target 都返回 `status=miss`，优先用 auto-loop 专用合并选择询问用户，避免把两套 route fallback 列表完整贴出：
+
+```text
+auto-loop 需要你先选执行路线，才能启动。
+
+推荐：
+1. 本次全 Inline：implement inline + check-all inline（只影响本次 run）
+2. 本次全 Subagent：implement subagent + check-all subagent（只影响本次 run）
+3. 保存默认全 Inline：写入个人默认，后续自动复用
+4. 保存默认全 Subagent：写入个人默认，后续自动复用
+
+高级：也可以回复 `implement 1, check 2` 分别选择。
+```
+
+映射规则：
+
+- `1` → `--route-implement inline --route-check check-all-inline`
+- `2` → `--route-implement subagent --route-check check-all-subagent`
+- `3` → 先用 `trellis-route` helper 分别写入 `implement=inline`、`check=check-all-inline` 且 `--save-pref`，再启动 runner
+- `4` → 先用 `trellis-route` helper 分别写入 `implement=subagent`、`check=check-all-subagent` 且 `--save-pref`，再启动 runner
+
+如果只有一个 target 返回 `status=miss`，再按 `trellis-route` 的对应 target 正常 numbered fallback 询问。不要替用户默认 inline 或 subagent。若用户选择的是本次临时策略，把选择映射为 runner route 参数一起传入，例如 `implement 1, check 1` 对应 `--route-implement inline --route-check check-all-inline`。若用户选择保存默认，则由 `trellis-route` 写入偏好后再启动 runner。
 
 ```bash
 python3 ./.trellis/scripts/auto_loop.py start \
   --tasks <task> [<task> ...] \
-  --profile commit-only
+  --profile commit-only \
+  [--route-implement inline|subagent] \
+  [--route-check check-all-inline|check-all-subagent]
 ```
 
 多任务队列中，当前任务切换到下一个任务且缺少该任务 route 决策时，回到 `trellis-route` 获取该任务真实选择，再继续 `next` / `record`。个人 `.trellis/.route-prefs.tmp` 会由 `trellis-route` 统一复用并写回 runtime。
@@ -54,7 +80,22 @@ python3 ./.trellis/scripts/auto_loop.py resume
 python3 ./.trellis/scripts/auto_loop.py next
 ```
 
-`resume_capsule` 只用于展示；下一步以 `next` 返回的 JSON 为准。
+`resume` 默认只输出紧凑状态；`resume_capsule` 不再持久写入 runtime JSON，仅在 `resume --verbose` / `status --verbose` 等诊断输出中动态生成。下一步以 `next` 返回的 JSON 为准。
+
+## Blocked 后重试
+
+如果 `next` 或 `status` 显示 run 内有 blocked 队列项，先根据 blocked reason 补齐条件，然后复用同一个 run：
+
+```bash
+python3 ./.trellis/scripts/auto_loop.py retry-blocked \
+  [--run-id <run-id>] \
+  [--task <task>] \
+  [--route-implement inline|subagent] \
+  [--route-check check-all-inline|check-all-subagent]
+python3 ./.trellis/scripts/auto_loop.py next
+```
+
+常见场景：启动时漏传临时 route，导致 `missing-implement-context` / `missing-check-context`。此时不要 `start --force`，直接用 `retry-blocked --route-implement ... --route-check ...` 重置 blocked 项。
 
 ## Action 映射
 
@@ -92,6 +133,8 @@ python3 ./.trellis/scripts/auto_loop.py record \
 
 runner 会按 3 轮 fix/recheck 预算决定继续、跳过当前任务或结束队列。
 
+`record` 默认只返回当前 item 的 `task`、`item_status`、`current_step`、`commit` 和紧凑 `summary`；只有排查状态漂移时才加 `--verbose` 查看完整 `item`。
+
 route action 成功回写时必须带上 `trellis-route` 输出里的真实 `mode` / `source`，例如
 `--route-mode inline --route-source route-prefs` 或
 `--route-mode check-all-subagent --route-source trellis-route`；不要写 auto-loop 默认值。

package/enhancements/0.6/.claude/skills/trellis-auto-loop/SKILL.md

@@ -12,10 +12,13 @@ description: "启动、恢复和推进 Trellis 自动任务循环。用于用户
 - 只有用户明确要求自动跑、auto loop、goal-like、继续自动 run、批量任务队列时才启动或恢复；不要把普通实现请求自动升级为 auto-loop。
 - 每次开始、恢复、压缩后继续时，先运行 runner 的 `resume` 或 `next`，不要凭聊天摘要推断下一步。
 - 每完成一个 action，必须用 `record --action <next 返回的 action>` 精确写回结果；runner 会拒绝缺失或不匹配的 action。写回后立即再调用 `next`，直到 `done`、`blocked` 或需要用户决策。
+- run 进入 `blocked` 后不要用 `start --force` 新建 run 来纠正参数；先补齐缺失 route/context，然后用 `retry-blocked` 在同一个 run 内恢复。
+- runner 默认输出是紧凑 JSON，只包含当前 action、队列计数、简短 blocked/pending/completed 列表和最近少量决策摘要；排障时才给 `status` / `resume` / `next` / `record` / `retry-blocked` 加 `--verbose` 读取完整 item、blocked detail 和 decision data。
 - 默认 profile 是 `commit-only`：自动推进到本地 commit，不 push、不发布、不归档。
 - 多任务只按用户显式给出的任务顺序执行；同一 worktree 不并发。
 - 启动 runner 前先完成 route 准备度判断：已有当前任务 runtime route 决策或个人 `.trellis/.route-prefs.tmp` 时可启动；没有时先进入 `trellis-route` 正常询问 / fallback，写入真实决策后再启动。
-- auto-loop 不默认写 `route_authorization`；如果未来显式传 route 参数，只能表示用户本次明确给出的临时策略，不能当成模型真实执行结果。
+- auto-loop 不默认写 `route_authorization`；只有用户本次明确给出的临时 route 策略，才能通过 `--route-implement` / `--route-check` 传给 runner，且不能当成模型真实执行结果。
+- auto-loop 启动前若 implement 与 check 都缺 route，优先展示 auto-loop 专用的合并选择，不要把 `trellis-route` 的两套完整 fallback 原样贴给用户。仍允许用户回复高级格式 `implement 1, check 1`。
 - 代码提交必须走 `trellis-push` 的 commit-only 语义；不要裸 `git commit` / `git push`。
 
 ## 启动
@@ -29,12 +32,35 @@ python3 .agents/skills/trellis-route/scripts/route_state.py resolve --target imp
 python3 .agents/skills/trellis-route/scripts/route_state.py resolve --target check
 ```
 
-如果任一 target 返回 `status=miss`，先按 `trellis-route` 的正常 numbered fallback 询问用户并写入 runtime；不要替用户默认 inline 或 subagent。route 准备完成后启动 runner：
+如果两个 target 都返回 `status=miss`，优先用 auto-loop 专用合并选择询问用户，避免把两套 route fallback 列表完整贴出：
+
+```text
+auto-loop 需要你先选执行路线，才能启动。
+
+推荐：
+1. 本次全 Inline：implement inline + check-all inline（只影响本次 run）
+2. 本次全 Subagent：implement subagent + check-all subagent（只影响本次 run）
+3. 保存默认全 Inline：写入个人默认，后续自动复用
+4. 保存默认全 Subagent：写入个人默认，后续自动复用
+
+高级：也可以回复 `implement 1, check 2` 分别选择。
+```
+
+映射规则：
+
+- `1` → `--route-implement inline --route-check check-all-inline`
+- `2` → `--route-implement subagent --route-check check-all-subagent`
+- `3` → 先用 `trellis-route` helper 分别写入 `implement=inline`、`check=check-all-inline` 且 `--save-pref`，再启动 runner
+- `4` → 先用 `trellis-route` helper 分别写入 `implement=subagent`、`check=check-all-subagent` 且 `--save-pref`，再启动 runner
+
+如果只有一个 target 返回 `status=miss`，再按 `trellis-route` 的对应 target 正常 numbered fallback 询问。不要替用户默认 inline 或 subagent。若用户选择的是本次临时策略，把选择映射为 runner route 参数一起传入，例如 `implement 1, check 1` 对应 `--route-implement inline --route-check check-all-inline`。若用户选择保存默认，则由 `trellis-route` 写入偏好后再启动 runner。
 
 ```bash
 python3 ./.trellis/scripts/auto_loop.py start \
   --tasks <task> [<task> ...] \
-  --profile commit-only
+  --profile commit-only \
+  [--route-implement inline|subagent] \
+  [--route-check check-all-inline|check-all-subagent]
 ```
 
 多任务队列中，当前任务切换到下一个任务且缺少该任务 route 决策时，回到 `trellis-route` 获取该任务真实选择，再继续 `next` / `record`。个人 `.trellis/.route-prefs.tmp` 会由 `trellis-route` 统一复用并写回 runtime。
@@ -54,7 +80,22 @@ python3 ./.trellis/scripts/auto_loop.py resume
 python3 ./.trellis/scripts/auto_loop.py next
 ```
 
-`resume_capsule` 只用于展示；下一步以 `next` 返回的 JSON 为准。
+`resume` 默认只输出紧凑状态；`resume_capsule` 不再持久写入 runtime JSON，仅在 `resume --verbose` / `status --verbose` 等诊断输出中动态生成。下一步以 `next` 返回的 JSON 为准。
+
+## Blocked 后重试
+
+如果 `next` 或 `status` 显示 run 内有 blocked 队列项，先根据 blocked reason 补齐条件，然后复用同一个 run：
+
+```bash
+python3 ./.trellis/scripts/auto_loop.py retry-blocked \
+  [--run-id <run-id>] \
+  [--task <task>] \
+  [--route-implement inline|subagent] \
+  [--route-check check-all-inline|check-all-subagent]
+python3 ./.trellis/scripts/auto_loop.py next
+```
+
+常见场景：启动时漏传临时 route，导致 `missing-implement-context` / `missing-check-context`。此时不要 `start --force`，直接用 `retry-blocked --route-implement ... --route-check ...` 重置 blocked 项。
 
 ## Action 映射
 
@@ -92,6 +133,8 @@ python3 ./.trellis/scripts/auto_loop.py record \
 
 runner 会按 3 轮 fix/recheck 预算决定继续、跳过当前任务或结束队列。
 
+`record` 默认只返回当前 item 的 `task`、`item_status`、`current_step`、`commit` 和紧凑 `summary`；只有排查状态漂移时才加 `--verbose` 查看完整 `item`。
+
 route action 成功回写时必须带上 `trellis-route` 输出里的真实 `mode` / `source`，例如
 `--route-mode inline --route-source route-prefs` 或
 `--route-mode check-all-subagent --route-source trellis-route`；不要写 auto-loop 默认值。

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 any matched SOP/spec before acting.
+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.
 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.

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 any matched SOP/spec before acting.
+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 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.

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

@@ -3,7 +3,7 @@ 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 any matched SOP/spec before acting.
+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.
 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 any matched SOP/spec before acting.
+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.
 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 any matched SOP/spec before acting.
+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.
 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

@@ -23,7 +23,9 @@ the intended action, commands about to run, files or systems involved, package/l
 and domain words such as release, publish, deploy, migration, config, CI, workflow,
 hooks, rollback, data fix, or destructive command.
 
-Read any matched SOP/spec files before acting; if nothing matches, continue normally.
+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.
 
 #### Task Brief Handoff
 

package/enhancements/0.6/scripts/auto_loop.py

@@ -16,8 +16,17 @@ from typing import Any
 SCHEMA_VERSION = 1
 DEFAULT_PROFILE = "commit-only"
 MAX_FIX_RECHECK = 3
+DECISION_LOG_LIMIT = 20
 VALID_IMPLEMENT_ROUTES = {"inline", "subagent"}
 VALID_CHECK_ROUTES = {"check-all-inline", "check-all-subagent"}
+RECOVERABLE_BLOCK_REASONS = {
+    "missing-prd",
+    "open-questions",
+    "incomplete-complex-artifacts",
+    "missing-implement-context",
+    "missing-check-context",
+    "unknown-step",
+}
 STEP_ACTIONS = {
     "refresh_brief": "refresh_brief",
     "start_task": "start_task",
@@ -214,10 +223,10 @@ def _append_item_decision(
         "summary": summary,
         "data": data or {},
     })
-    item["decision_log"] = log[-50:]
+    item["decision_log"] = log[-DECISION_LOG_LIMIT:]
 
 
-def _decision_tail(state: dict[str, Any], limit: int = 8) -> list[dict[str, Any]]:
+def _decision_tail(state: dict[str, Any], limit: int = 8, include_data: bool = True) -> list[dict[str, Any]]:
     """返回 run 内最近的关键决策摘要。"""
     queue = state.get("queue") if isinstance(state.get("queue"), list) else []
     events: list[dict[str, Any]] = []
@@ -227,7 +236,17 @@ def _decision_tail(state: dict[str, Any], limit: int = 8) -> list[dict[str, Any]
         log = item.get("decision_log")
         if isinstance(log, list):
             events.extend(event for event in log if isinstance(event, dict))
-    return events[-limit:]
+    tail = events[-limit:]
+    if include_data:
+        return tail
+    compact: list[dict[str, Any]] = []
+    for event in tail:
+        compact.append({
+            key: event.get(key)
+            for key in ("at", "type", "task", "summary")
+            if event.get(key) is not None
+        })
+    return compact
 
 
 def _run_path(repo_root: Path, run_id: str) -> Path:
@@ -235,6 +254,11 @@ def _run_path(repo_root: Path, run_id: str) -> Path:
     return _auto_dir(repo_root) / f"{run_id}.json"
 
 
+def _run_paths(repo_root: Path) -> list[Path]:
+    """返回按 run id 从新到旧排序的 auto run 文件。"""
+    return sorted(_auto_dir(repo_root).glob("auto-*.json"), reverse=True)
+
+
 def _new_run_id() -> str:
     """生成短小稳定的 run id。"""
     return "auto-" + datetime.now(timezone.utc).strftime("%Y%m%d%H%M%S")
@@ -417,7 +441,7 @@ def _load_current_state(repo_root: Path, run_id: str | None = None) -> tuple[Pat
             _clear_pointer_if_current(repo_root, current)
 
     running: list[tuple[Path, dict[str, Any]]] = []
-    for path in sorted(_auto_dir(repo_root).glob("auto-*.json")):
+    for path in _run_paths(repo_root):
         state = _read_json(path)
         if state.get("status") == "running":
             running.append((path, state))
@@ -431,10 +455,62 @@ def _load_current_state(repo_root: Path, run_id: str | None = None) -> tuple[Pat
     raise ValueError("没有可恢复的唯一 auto run")
 
 
+def _load_blocked_state(repo_root: Path, run_id: str | None = None) -> tuple[Path, dict[str, Any]]:
+    """加载可重试的 blocked auto run。"""
+    if run_id:
+        path, state = _load_current_state(repo_root, run_id)
+        if _blocked_items(state):
+            return path, state
+        raise ValueError(f"auto run 没有 blocked 队列项:{run_id}")
+
+    try:
+        path, state = _load_current_state(repo_root)
+        if _blocked_items(state):
+            return path, state
+    except ValueError:
+        pass
+
+    blocked_runs: list[tuple[Path, dict[str, Any]]] = []
+    for path in _run_paths(repo_root):
+        state = _read_json(path)
+        if state and _blocked_items(state):
+            blocked_runs.append((path, state))
+    if len(blocked_runs) == 1:
+        return blocked_runs[0]
+    if not blocked_runs:
+        raise ValueError("没有可重试的 blocked auto run")
+    run_ids = ", ".join(str(state.get("run_id") or path.stem) for path, state in blocked_runs[:8])
+    raise ValueError(f"存在多个 blocked auto run，请指定 --run-id。候选:{run_ids}")
+
+
+def _recent_run_summaries(repo_root: Path, limit: int = 8) -> list[dict[str, Any]]:
+    """返回最近 auto run 的轻量状态列表。"""
+    runs: list[dict[str, Any]] = []
+    for path in _run_paths(repo_root)[:limit]:
+        state = _read_json(path)
+        if not state:
+            continue
+        counts = _queue_counts(state)
+        current = _current_queue_item(state)
+        runs.append({
+            "run_id": state.get("run_id") or path.stem,
+            "path": _rel_path(repo_root, path),
+            "run_status": state.get("status"),
+            "profile": state.get("profile"),
+            "updated_at": state.get("updated_at"),
+            "completed": counts["completed"],
+            "blocked": counts["blocked"],
+            "remaining": counts["remaining"],
+            "current_task": current.get("task") if current else None,
+            "next_step": current.get("current_step") if current else "done",
+        })
+    return runs
+
+
 def _write_state(path: Path, state: dict[str, Any]) -> None:
     """刷新 auto run 状态和更新时间。"""
     state["updated_at"] = _utc_now()
-    state["resume_capsule"] = _resume_capsule(state)
+    state.pop("resume_capsule", None)
     _write_json(path, state)
 
 
@@ -459,72 +535,167 @@ def _clear_pointer_if_current(repo_root: Path, run_id: str | None) -> None:
 
 def _resume_capsule(state: dict[str, Any]) -> dict[str, Any]:
     """生成短小的人类可读恢复摘要。"""
-    queue = state.get("queue") if isinstance(state.get("queue"), list) else []
-    current = None
-    auto_completed = []
-    unarchived_tasks = []
-    blocked = []
-    for item in queue:
-        if not isinstance(item, dict):
-            continue
-        if current is None and item.get("status") in {"pending", "running"}:
-            current = item
-        if item.get("status") == "completed":
-            auto_completed.append(item.get("task"))
-            unarchived_tasks.append(item.get("task"))
-        if item.get("status") == "blocked":
-            blocked.append(item.get("task"))
+    queue = _queue_items(state)
+    current = _current_queue_item(state)
+    auto_completed = [item.get("task") for item in queue if item.get("status") == "completed"]
+    blocked = [item.get("task") for item in queue if item.get("status") == "blocked"]
+    counts = _queue_counts(state)
     return {
         "run_id": state.get("run_id"),
         "status": state.get("status"),
         "current_task": current.get("task") if current else None,
         "next_step": current.get("current_step") if current else "done",
-        "completed": sum(1 for item in queue if isinstance(item, dict) and item.get("status") == "completed"),
-        "blocked": sum(1 for item in queue if isinstance(item, dict) and item.get("status") == "blocked"),
-        "remaining": sum(1 for item in queue if isinstance(item, dict) and item.get("status") in {"pending", "running"}),
+        "completed": counts["completed"],
+        "blocked": counts["blocked"],
+        "remaining": counts["remaining"],
         "auto_completed_tasks": auto_completed,
-        "unarchived_tasks": unarchived_tasks,
         "task_lifecycle_note": "auto-loop completed means local commit completed; run finish-work/archive explicitly when ready" if auto_completed else None,
         "blocked_tasks": blocked,
-        "recent_decisions": _decision_tail(state, 5),
     }
 
 
-def _summary(state: dict[str, Any]) -> dict[str, Any]:
-    """返回队列状态摘要。"""
+def _terminal_status(queue: list[Any]) -> str:
+    """根据队列终态区分全完成和带阻塞结束。"""
+    has_blocked = any(isinstance(item, dict) and item.get("status") == "blocked" for item in queue)
+    return "blocked" if has_blocked else "completed"
+
+
+def _queue_items(state: dict[str, Any]) -> list[dict[str, Any]]:
+    """返回合法队列项。"""
     queue = state.get("queue") if isinstance(state.get("queue"), list) else []
-    outstanding_action = None
-    for item in queue:
-        if not isinstance(item, dict) or item.get("status") != "running":
+    return [item for item in queue if isinstance(item, dict)]
+
+
+def _queue_counts(state: dict[str, Any]) -> dict[str, int]:
+    """返回队列状态计数。"""
+    queue = _queue_items(state)
+    return {
+        "total": len(queue),
+        "completed": sum(1 for item in queue if item.get("status") == "completed"),
+        "blocked": sum(1 for item in queue if item.get("status") == "blocked"),
+        "remaining": sum(1 for item in queue if item.get("status") in {"pending", "running"}),
+    }
+
+
+def _current_queue_item(state: dict[str, Any]) -> dict[str, Any] | None:
+    """返回当前待处理队列项。"""
+    for item in _queue_items(state):
+        if item.get("status") in {"pending", "running"}:
+            return item
+    return None
+
+
+def _blocked_items(state: dict[str, Any]) -> list[dict[str, Any]]:
+    """返回 blocked 队列项。"""
+    return [item for item in _queue_items(state) if item.get("status") == "blocked"]
+
+
+def _outstanding_action(state: dict[str, Any]) -> dict[str, Any] | None:
+    """返回当前等待 record 回写的 action。"""
+    for item in _queue_items(state):
+        if item.get("status") != "running":
             continue
         last_action = item.get("last_action")
         if isinstance(last_action, dict):
-            outstanding_action = {
+            return {
                 "task": item.get("task"),
                 "action": last_action.get("action"),
                 "current_step": last_action.get("current_step"),
                 "issued_at": last_action.get("issued_at"),
             }
-        break
-    return {
+        return None
+    return None
+
+
+def _completed_task_summaries(state: dict[str, Any]) -> list[dict[str, Any]]:
+    """返回已完成任务的紧凑摘要。"""
+    completed: list[dict[str, Any]] = []
+    for item in _queue_items(state):
+        if item.get("status") != "completed":
+            continue
+        task = {"task": item.get("task")}
+        if item.get("commit"):
+            task["commit"] = item.get("commit")
+        completed.append(task)
+    return completed
+
+
+def _blocked_task_summaries(state: dict[str, Any], include_detail: bool = False) -> list[dict[str, Any]]:
+    """返回 blocked 任务摘要，默认不带 detail。"""
+    blocked_tasks: list[dict[str, Any]] = []
+    for item in _blocked_items(state):
+        blocked = item.get("blocked")
+        blocked_data = blocked if isinstance(blocked, dict) else {}
+        task = {
+            "task": item.get("task"),
+            "reason": blocked_data.get("reason"),
+            "summary": blocked_data.get("summary"),
+            "blocked_at": blocked_data.get("blocked_at"),
+        }
+        if include_detail:
+            task["detail"] = blocked_data.get("detail") or {}
+        blocked_tasks.append(task)
+    return blocked_tasks
+
+
+def _pending_task_summaries(state: dict[str, Any], include_status: bool = False) -> list[dict[str, Any]]:
+    """返回未完成任务摘要。"""
+    pending: list[dict[str, Any]] = []
+    for item in _queue_items(state):
+        if item.get("status") not in {"pending", "running"}:
+            continue
+        task = {
+            "task": item.get("task"),
+            "status": item.get("status"),
+            "current_step": item.get("current_step"),
+        }
+        if include_status:
+            task["last_failure"] = item.get("last_failure")
+            task["attempts"] = item.get("attempts")
+        pending.append(task)
+    return pending
+
+
+def _compact_summary(state: dict[str, Any]) -> dict[str, Any]:
+    """返回默认给 agent 消费的紧凑状态摘要。"""
+    current = _current_queue_item(state)
+    completed_tasks = _completed_task_summaries(state)
+    summary = {
         "run_id": state.get("run_id"),
         "run_status": state.get("status"),
         "profile": state.get("profile"),
         "current_index": state.get("current_index"),
-        "outstanding_action": outstanding_action,
-        "auto_completed": [i.get("task") for i in queue if isinstance(i, dict) and i.get("status") == "completed"],
-        "completed": [i.get("task") for i in queue if isinstance(i, dict) and i.get("status") == "completed"],
-        "unarchived_tasks": [i.get("task") for i in queue if isinstance(i, dict) and i.get("status") == "completed"],
-        "task_lifecycle_note": "completed 仅表示 auto-loop item 已本地提交；任务归档仍需显式 finish-work/archive",
-        "blocked": [
-            {"task": i.get("task"), "blocked": i.get("blocked")}
-            for i in queue
-            if isinstance(i, dict) and i.get("status") == "blocked"
-        ],
-        "pending": [i.get("task") for i in queue if isinstance(i, dict) and i.get("status") in {"pending", "running"}],
-        "recent_decisions": _decision_tail(state),
-        "resume_capsule": state.get("resume_capsule"),
+        "current_task": current.get("task") if current else None,
+        "next_step": current.get("current_step") if current else "done",
+        "outstanding_action": _outstanding_action(state),
+        "queue_counts": _queue_counts(state),
+        "completed_tasks": completed_tasks,
+        "blocked_tasks": _blocked_task_summaries(state),
+        "pending_tasks": _pending_task_summaries(state),
+        "recent_decisions": _decision_tail(state, 3, include_data=False),
     }
+    if completed_tasks:
+        summary["task_lifecycle_note"] = "completed 仅表示 auto-loop item 已本地提交；任务归档仍需显式 finish-work/archive"
+    return summary
+
+
+def _summary(state: dict[str, Any]) -> dict[str, Any]:
+    """返回 verbose 诊断状态摘要。"""
+    summary = _compact_summary(state)
+    summary.update({
+        "blocked_tasks": _blocked_task_summaries(state, include_detail=True),
+        "pending_tasks": _pending_task_summaries(state, include_status=True),
+        "recent_decisions": _decision_tail(state, DECISION_LOG_LIMIT, include_data=True),
+        "resume_capsule": _resume_capsule(state),
+    })
+    return summary
+
+
+def _format_summary(state: dict[str, Any], args: argparse.Namespace | None = None) -> dict[str, Any]:
+    """根据 --verbose 返回紧凑或详细摘要。"""
+    if args is not None and getattr(args, "verbose", False):
+        return _summary(state)
+    return _compact_summary(state)
 
 
 def _make_item(repo_root: Path, task_ref: str) -> dict[str, Any]:
@@ -662,12 +833,16 @@ def _next_item(repo_root: Path, state: dict[str, Any]) -> tuple[dict[str, Any] |
 
         _block_item(item, "unknown-step", f"未知 current_step:{step}")
 
-    state["status"] = "completed"
+    state["status"] = _terminal_status(queue)
     return None, {
-        "status": "done",
+        "status": "blocked" if state["status"] == "blocked" else "done",
         "finish_work_required_for_archive": True,
-        "instruction": "auto-loop 队列已结束；如需归档任务，请用户显式运行 trellis-finish-work。",
-        "summary": _summary(state),
+        "instruction": (
+            "auto-loop 队列存在 blocked 项；补齐条件后运行 retry-blocked 继续同一个 run。"
+            if state["status"] == "blocked"
+            else "auto-loop 队列已结束；如需归档任务，请用户显式运行 trellis-finish-work。"
+        ),
+        "summary": _compact_summary(state),
     }
 
 
@@ -686,6 +861,15 @@ def cmd_start(args: argparse.Namespace) -> int:
                 "run_id": current.get("run_id"),
                 "path": _rel_path(repo_root, current_path),
             })
+        if current.get("status") == "blocked" and not args.force:
+            return _print({
+                "status": "error",
+                "reason": "auto-run-blocked-retry-available",
+                "run_id": current.get("run_id"),
+                "path": _rel_path(repo_root, current_path),
+                "suggested_command": f"python3 ./.trellis/scripts/auto_loop.py retry-blocked --run-id {current.get('run_id')}",
+                "summary": _format_summary(current, args),
+            })
     except ValueError:
         pass
 
@@ -709,13 +893,12 @@ def cmd_start(args: argparse.Namespace) -> int:
         "current_index": 0,
         "route_authorization": route_authorization,
         "queue": queue,
-        "resume_capsule": {},
     }
     path = _run_path(repo_root, run_id)
     _write_state(path, state)
     _write_pointer(repo_root, run_id)
     _link_session_run(repo_root, run_id)
-    return _print({"status": "started", "path": _rel_path(repo_root, path), **_summary(state)})
+    return _print({"status": "started", "path": _rel_path(repo_root, path), **_format_summary(state, args)})
 
 
 def cmd_resume(args: argparse.Namespace) -> int:
@@ -728,7 +911,10 @@ def cmd_resume(args: argparse.Namespace) -> int:
     except ValueError as exc:
         return _print({"status": "error", "reason": "resume-failed", "message": str(exc)})
     _link_session_run(repo_root, str(state.get("run_id")))
-    return _print({"status": "resumed", "path": _rel_path(repo_root, path), **_summary(state)})
+    output = {"status": "resumed", "path": _rel_path(repo_root, path), **_format_summary(state, args)}
+    if getattr(args, "verbose", False):
+        output["resume_capsule"] = _resume_capsule(state)
+    return _print(output)
 
 
 def cmd_next(args: argparse.Namespace) -> int:
@@ -743,16 +929,106 @@ def cmd_next(args: argparse.Namespace) -> int:
     _link_session_run(repo_root, str(state.get("run_id")))
     if state.get("status") != "running":
         output_status = "done" if state.get("status") == "completed" else state.get("status") or "unknown"
-        return _print({"run_id": state.get("run_id"), "status": output_status, "summary": _summary(state)})
+        return _print({"run_id": state.get("run_id"), "status": output_status, "summary": _format_summary(state, args)})
     _, action = _next_item(repo_root, state)
     _write_state(path, state)
     if state.get("status") == "completed":
         _clear_pointer_if_current(repo_root, str(state.get("run_id") or ""))
-    if action.get("status") == "done":
-        action["summary"] = _summary(state)
+    if action.get("status") in {"done", "blocked"}:
+        action["summary"] = _format_summary(state, args)
     return _print({"run_id": state.get("run_id"), **action})
 
 
+def _apply_route_authorization_args(state: dict[str, Any], args: argparse.Namespace) -> dict[str, str]:
+    """把命令行 route 参数合并进 run 的临时授权。"""
+    route_authorization = state.get("route_authorization")
+    if not isinstance(route_authorization, dict):
+        route_authorization = {}
+    if getattr(args, "route_implement", None):
+        route_authorization["implement"] = args.route_implement
+    if getattr(args, "route_check", None):
+        route_authorization["check"] = args.route_check
+    state["route_authorization"] = route_authorization
+    return {str(key): str(value) for key, value in route_authorization.items()}
+
+
+def _blocked_reason(item: dict[str, Any]) -> str:
+    """读取队列项 blocked reason。"""
+    blocked = item.get("blocked")
+    if isinstance(blocked, dict):
+        reason = blocked.get("reason")
+        if isinstance(reason, str):
+            return reason
+    return ""
+
+
+def cmd_retry_blocked(args: argparse.Namespace) -> int:
+    """把可恢复的 blocked 队列项重置为 pending，复用同一个 auto run。"""
+    repo_root = _repo_root()
+    if repo_root is None:
+        return _print({"status": "error", "reason": "not-trellis-project"})
+    try:
+        path, state = _load_blocked_state(repo_root, args.run_id)
+    except ValueError as exc:
+        return _print({
+            "status": "error",
+            "reason": "retry-blocked-failed",
+            "message": str(exc),
+            "runs": _recent_run_summaries(repo_root),
+        })
+
+    task = _normalize_task_ref(repo_root, args.task) if args.task else None
+    route_authorization = _apply_route_authorization_args(state, args)
+    queue = state.get("queue") if isinstance(state.get("queue"), list) else []
+    reset: list[str] = []
+    skipped: list[dict[str, str]] = []
+
+    for index, item in enumerate(queue):
+        if not isinstance(item, dict) or item.get("status") != "blocked":
+            continue
+        if task and item.get("task") != task:
+            continue
+        reason = _blocked_reason(item)
+        if not args.all and not task and reason not in RECOVERABLE_BLOCK_REASONS:
+            skipped.append({"task": str(item.get("task")), "reason": reason or "unknown"})
+            continue
+        item["status"] = "pending"
+        item["blocked"] = None
+        item["last_action"] = None
+        item["task_status"] = _task_status(repo_root, str(item.get("task")))
+        item["updated_at"] = _utc_now()
+        state["current_index"] = min(int(state.get("current_index") or index), index)
+        reset.append(str(item.get("task")))
+        _append_item_decision(
+            item,
+            "retry_unblocked",
+            "blocked 队列项已重置，将在同一个 auto run 内重试",
+            {"previous_reason": reason, "route_authorization": route_authorization},
+        )
+
+    if not reset:
+        return _print({
+            "status": "error",
+            "reason": "no-retryable-blocked-items",
+            "message": "没有可自动重试的 blocked 队列项；如确认要重试，可加 --all 或指定 --task。",
+            "skipped": skipped,
+            "summary": _format_summary(state, args),
+        })
+
+    state["status"] = "running"
+    _write_state(path, state)
+    _write_pointer(repo_root, str(state.get("run_id")))
+    _link_session_run(repo_root, str(state.get("run_id")))
+    return _print({
+        "status": "retry-ready",
+        "run_id": state.get("run_id"),
+        "path": _rel_path(repo_root, path),
+        "reset": reset,
+        "skipped": skipped,
+        "summary": _format_summary(state, args),
+    })
+
+
 def _find_record_item(state: dict[str, Any], task_ref: str | None) -> dict[str, Any] | None:
     """找到 record 要更新的队列项。"""
     queue = state.get("queue") if isinstance(state.get("queue"), list) else []
@@ -880,7 +1156,7 @@ def cmd_record(args: argparse.Namespace) -> int:
             "status": "error",
             "reason": "auto-run-not-running",
             "run_status": state.get("status"),
-            "summary": _summary(state),
+            "summary": _format_summary(state, args),
         })
 
     task = _normalize_task_ref(repo_root, args.task) if args.task else None
@@ -926,7 +1202,18 @@ def cmd_record(args: argparse.Namespace) -> int:
             )
 
     _write_state(path, state)
-    return _print({"status": "recorded", "run_id": state.get("run_id"), "task": item.get("task"), "item": item, "summary": _summary(state)})
+    output = {
+        "status": "recorded",
+        "run_id": state.get("run_id"),
+        "task": item.get("task"),
+        "item_status": item.get("status"),
+        "current_step": item.get("current_step"),
+        "commit": item.get("commit"),
+        "summary": _format_summary(state, args),
+    }
+    if getattr(args, "verbose", False):
+        output["item"] = item
+    return _print(output)
 
 
 def cmd_status(args: argparse.Namespace) -> int:
@@ -937,8 +1224,14 @@ def cmd_status(args: argparse.Namespace) -> int:
     try:
         path, state = _load_current_state(repo_root, args.run_id)
     except ValueError as exc:
-        return _print({"status": "error", "reason": "status-failed", "message": str(exc)})
-    return _print({"status": "ok", "path": _rel_path(repo_root, path), **_summary(state)})
+        return _print({
+            "status": "ok",
+            "run_status": "no-current-run",
+            "reason": "status-list",
+            "message": str(exc),
+            "runs": _recent_run_summaries(repo_root),
+        })
+    return _print({"status": "ok", "path": _rel_path(repo_root, path), **_format_summary(state, args)})
 
 
 def cmd_stop(args: argparse.Namespace) -> int:
@@ -969,11 +1262,13 @@ def build_parser() -> argparse.ArgumentParser:
     start.add_argument("--route-implement", choices=sorted(VALID_IMPLEMENT_ROUTES))
     start.add_argument("--route-check", choices=sorted(VALID_CHECK_ROUTES))
     start.add_argument("--force", action="store_true")
+    start.add_argument("--verbose", action="store_true")
     start.set_defaults(func=cmd_start)
 
     for name, func in (("resume", cmd_resume), ("next", cmd_next), ("status", cmd_status)):
         sub = subparsers.add_parser(name)
         sub.add_argument("--run-id")
+        sub.add_argument("--verbose", action="store_true")
         sub.set_defaults(func=func)
 
     record = subparsers.add_parser("record")
@@ -990,8 +1285,18 @@ def build_parser() -> argparse.ArgumentParser:
     record.add_argument("--snapshot-commit")
     record.add_argument("--route-mode")
     record.add_argument("--route-source")
+    record.add_argument("--verbose", action="store_true")
     record.set_defaults(func=cmd_record)
 
+    retry = subparsers.add_parser("retry-blocked")
+    retry.add_argument("--run-id")
+    retry.add_argument("--task")
+    retry.add_argument("--route-implement", choices=sorted(VALID_IMPLEMENT_ROUTES))
+    retry.add_argument("--route-check", choices=sorted(VALID_CHECK_ROUTES))
+    retry.add_argument("--all", action="store_true")
+    retry.add_argument("--verbose", action="store_true")
+    retry.set_defaults(func=cmd_retry_blocked)
+
     stop = subparsers.add_parser("stop")
     stop.add_argument("--run-id")
     stop.add_argument("--reason")

package/enhancements/0.6/scripts/spec_router.py

@@ -18,8 +18,40 @@ from typing import Any
 
 
 MAX_BODY_CHARS = 8000
-DEFAULT_LIMIT = 5
+DEFAULT_LIMIT = 3
 MIN_SCORE = 3
+MIN_BODY_ONLY_HITS = 5
+MIN_HEADING_BODY_HITS = 3
+BODY_WEAK_TOKENS = {
+    "action",
+    "actions",
+    "after",
+    "before",
+    "command",
+    "commands",
+    "context",
+    "current",
+    "file",
+    "files",
+    "match",
+    "matched",
+    "matches",
+    "matching",
+    "normal",
+    "path",
+    "paths",
+    "project",
+    "read",
+    "reason",
+    "reasons",
+    "relevant",
+    "sop",
+    "spec",
+    "status",
+    "task",
+    "tasks",
+    "workflow",
+}
 TOKEN_RE = re.compile(r"[A-Za-z0-9_.@/-]+|[\u4e00-\u9fff]{2,}")
 HEADER_RE = re.compile(r"^\s{0,3}#{1,3}\s+(.+?)\s*$", re.MULTILINE)
 FRONTMATTER_BOUNDARY_RE = re.compile(r"^---\s*$")
@@ -225,10 +257,11 @@ 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()
-    rel_lower = rel_path.lower()
+    spec_rel_path = path.relative_to(root / ".trellis" / "spec").as_posix()
+    spec_rel_lower = spec_rel_path.lower()
     body_sample = body[:MAX_BODY_CHARS]
     body_lower = body_sample.lower()
-    headers = HEADER_RE.findall(body_sample)
+    headers = HEADER_RE.findall(body)
     header_text = " ".join(headers).lower()
 
     kind = str(metadata.get("kind") or "").strip()
@@ -249,7 +282,7 @@ 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 rel_lower]
+    path_hits = [token for token in query_tokens if token in spec_rel_lower]
     if path_hits:
         score += 4 * len(path_hits)
         reasons.append(f"matched path tokens: {', '.join(path_hits[:5])}")
@@ -259,11 +292,23 @@ def score_file(root: Path, path: Path, query: str, query_tokens: list[str]) -> C
         score += 3 * len(header_hits)
         reasons.append(f"matched headings: {', '.join(header_hits[:5])}")
 
-    body_hits = [token for token in query_tokens if token in body_lower]
+    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]
     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
+    )
+    if not strong_match:
+        return None
+
     if kind.lower() in {"sop", "procedure", "guide", "thinking-guide"} and score > 0:
         score += 2
     if load.lower() in {"before_action", "before-acting", "before_acting"} and score > 0:

package/enhancements/MANIFEST.json

@@ -1,7 +1,7 @@
 {
-  "syncedAt": "2026-06-29T10:34:58.491Z",
+  "syncedAt": "2026-06-30T00:30:48.425Z",
   "syncedFrom": "vendor/skill-garden/.trellis",
-  "sourceCommit": "43e16e445596067cb5d7278be9c9f3c8e97d085b",
+  "sourceCommit": "44b5b31a0c0346f4d615ad6f3f58af860cc3983d",
   "variants": {
     "old": {
       "claudeSkills": [],

package/package.json

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