flower-trellis 0.3.1 → 0.4.0-beta.0

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

@@ -13,9 +13,9 @@ description: |
 
 # Trellis 路由器：implement / check 执行模式选择
 
-主 agent 进入 Phase 2.1 实现路由或 Phase 2.2 检查路由时调用本 skill。当前上下文或 session runtime state 内已有合法来源的最近 route 决策时，后续实现、修复、重检默认复用该决策；没有合法决策时才进入本 skill 或同编号 fallback。提交前确实需要最终复查时，回到 Phase 2.2 并复用当前任务的合法 check route，除非用户明确要求重选。
+主 agent 进入 Phase 2.1 实现路由或 Phase 2.2 检查路由时调用本 skill。当前上下文或 session runtime state 内已有合法来源、target 匹配、且 task 等于当前任务路径的最近 route 决策时，后续实现、修复、重检默认复用该决策；没有合法决策时才进入本 skill 或同编号 fallback。提交前确实需要最终复查时，回到 Phase 2.2 并复用当前任务的合法 check route，除非用户明确要求重选。
 
-个人配置只写入 `.trellis/.route-prefs.tmp`。该文件匹配 `.trellis/.gitignore` 的 `*.tmp` 规则，属于开发者本地偏好，不纳入 git，也不影响其他开发者。
+个人配置只写入 `.trellis/.route-prefs.tmp`。该文件匹配 `.trellis/.gitignore` 的 `*.tmp` 规则，属于开发者本地偏好，不纳入 git，也不影响其他开发者。auto-loop 可在 `.trellis/.runtime/auto-loop/<run-id>.json` 写入临时 route 授权；它不是个人偏好，优先级低于 `.route-prefs.tmp`，只用于减少 auto 模式下的交互打断。
 
 本轮 route 决策写入当前 session runtime 文件 `.trellis/.runtime/sessions/<context-key>.json` 的 `route_decisions` 字段。该文件匹配 `.trellis/.gitignore` 的 `.runtime/` 规则，只保存当前 AI session/window 的执行状态，用于压缩后恢复；它不是任务属性，不写入 `.trellis/tasks/**`，也不是长期团队配置。
 
@@ -25,9 +25,9 @@ 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` 配置。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、SessionStart 摘要、`codex-mode`、空 `.route-prefs.tmp`、旧单值偏好，都不能单独作为有效 route 决策。
 
-当前上下文内已有 target 匹配且来源合法的 route 决策时，后续实现、check 发现问题、用户指出刚检查过的实现有问题、修复后重检、提交前复查均默认复用最近 implement/check 路由；除非用户明确要求重选/临时改/清除默认，不再调用本 skill。当前上下文没有 route 决策但 runtime state 命中时，本 skill 恢复该决策并输出同样的结构化 `route_decision`。
+当前上下文内已有 target 匹配、task 等于当前任务路径、且来源合法的 route 决策时，后续实现、check 发现问题、用户指出刚检查过的实现有问题、修复后重检、提交前复查均默认复用最近 implement/check 路由；除非用户明确要求重选/临时改/清除默认，不再调用本 skill。当前上下文没有 route 决策但 runtime state 命中时，本 skill 恢复该决策并输出同样的结构化 `route_decision`。如果上下文里只有上一个任务的 `route_decision`，必须忽略并重新解析当前任务。
 
 Codex inline mode 只表示主会话默认直接执行，不是 route 选项过滤器。即使当前上下文出现 `<codex-mode>inline...do not dispatch...</codex-mode>` 或 `workflow-state:in_progress-inline`，也不能推断“只能 inline”或跳过 subagent 选项；仍必须通过 helper resolve runtime/prefs，或在无有效配置时展示正常 inline/subagent 选项。若本 skill 的紧邻路由决定是 subagent，本步骤允许主 agent dispatch 对应 implement/check sub-agent；禁止的是绕过 `trellis-route` 直接 dispatch。
 
@@ -50,7 +50,7 @@ Codex inline mode 只表示主会话默认直接执行，不是 route 选项过
 
 ## Step 0.5: 解析已有 route state
 
-仅在没有覆盖意图、当前上下文没有 target 匹配的合法 `route_decision` 时调用 helper 解析已有状态。helper 的解析顺序固定为：当前 session runtime 文件里的 `route_decisions` → `.trellis/.route-prefs.tmp`。命中 `.route-prefs.tmp` 时，helper 会自动把 `source=route-prefs` 的决策写回当前 session runtime，后续压缩恢复不需要再次读 prefs。
+仅在没有覆盖意图、当前上下文没有 target + 当前 task 匹配的合法 `route_decision` 时调用 helper 解析已有状态。helper 的解析顺序固定为：当前 session runtime 文件里的 `route_decisions` → `.trellis/.route-prefs.tmp` → `.trellis/.runtime/auto-loop/<run-id>.json` 临时授权。命中 `.route-prefs.tmp` 或 auto-loop 临时授权时，helper 会自动把对应决策写回当前 session runtime，后续压缩恢复不需要再次读 prefs 或 auto-loop 状态。
 
 调用随本 skill 分发的 helper；不要在对话中内嵌或改写 helper 逻辑：
 
@@ -60,7 +60,7 @@ python3 .agents/skills/trellis-route/scripts/route_state.py resolve --target <im
 python3 .claude/skills/trellis-route/scripts/route_state.py resolve --target <implement|check>
 ```
 
-helper 只接受当前 session 或唯一 session fallback 的 `.trellis/.runtime/sessions/<context-key>.json`，并只从 `route_decisions.<target>` 恢复决策。命中时输出 `{"status":"hit", ...}`，其中默认输出里的 `mode` / `source` 已经过 task/target/source/mode/scope 校验，可跳过 Step 2 并进入 Step 3 输出决策。`origin=route-prefs` 表示来自个人 route 配置，并且 helper 已写回 session runtime state；`origin=runtime` 表示来自 session runtime state。
+helper 只接受当前 session 或唯一 session fallback 的 `.trellis/.runtime/sessions/<context-key>.json`，并只从 `route_decisions.<target>` 恢复当前任务的决策。命中时输出 `{"status":"hit", ...}`，其中默认输出里的 `task` / `mode` / `source` 已经过 task/target/source/mode/scope 校验，可跳过 Step 2 并进入 Step 3 输出决策。`origin=route-prefs` 表示来自个人 route 配置，并且 helper 已写回 session runtime state；`origin=auto-loop` 表示来自 auto-loop 临时授权且 helper 已写回 session runtime state；`origin=runtime` 表示来自 session runtime state。
 
 helper 默认输出为精简 JSON，只包含 route 执行必需的 `status`、`origin`、`mode`、`source`/`reason` 等字段。需要排查完整 `decision`、session 文件、context key、任务路径、个人配置路径或写回标记时，在同一命令末尾加 `--verbose`；不要为了诊断信息额外读取 runtime 文件。
 
@@ -181,7 +181,9 @@ python3 .agents/skills/trellis-route/scripts/route_state.py clear-pref --target
 python3 .claude/skills/trellis-route/scripts/route_state.py clear-pref --target <implement|check>
 ```
 
-helper 写入规则：保留另一个 target 的 runtime 决策和偏好；覆盖当前 target；`source` 保持原始合法来源，正常 skill 交互用 `trellis-route`，普通聊天编号 fallback 用 `numbered-fallback`，prefs 命中由 helper 写 `route-prefs`；保留 session runtime 文件中的 `platform`、`current_task`、`current_run` 等既有字段；内部 `task` 必须写当前 `task.py current --source` 的任务路径。写入失败不阻塞本次 route 输出，但要在回复中简短说明未持久化，压缩后可能再次询问。
+helper 写入规则：保留另一个 target 的 runtime 决策和偏好；覆盖当前 target；`source` 保持原始合法来源，正常 skill 交互用 `trellis-route`，普通聊天编号 fallback 用 `numbered-fallback`，prefs 命中由 helper 写 `route-prefs`，auto-loop 临时授权命中由 helper 写 `auto-loop`；保留 session runtime 文件中的 `platform`、`current_task`、`current_run`、`current_auto_run` 等既有字段；内部 `task` 必须写当前 `task.py current --source` 的任务路径。写入失败不阻塞本次 route 输出，但要在回复中简短说明未持久化，压缩后可能再次询问。
+
+当同一 session 从一个任务切换到另一个任务时，helper 写入当前任务任一 target 的决策前会清理 runtime 中属于其他任务的 `route_decisions`。个人默认仍保留在 `.trellis/.route-prefs.tmp`；清理只影响当前 session 的临时恢复状态，目的是避免新任务的 check 阶段误复用上一个任务的 check 路由。
 
 ---
 
@@ -205,6 +207,7 @@ helper 写入规则：保留另一个 target 的 runtime 决策和偏好；覆
 ```markdown
 路由决定：<inline/subagent> <implement | check-all | check>
 [来自个人 route 配置：`.trellis/.route-prefs.tmp` (<key>=<value>)。]
+[来自 auto-loop 临时 route 授权：`.trellis/.runtime/auto-loop/<run-id>.json`。]
 [来自 session runtime route state：`.trellis/.runtime/sessions/<context-key>.json` 的 `route_decisions`。]
 [已写入 session runtime route state：`.trellis/.runtime/sessions/<context-key>.json` 的 `route_decisions`。]
 [说明：用户明确请求轻量检查，使用隐藏逃生口。]
@@ -212,8 +215,9 @@ helper 写入规则：保留另一个 target 的 runtime 决策和偏好；覆
 route_decision:
   target: <implement | check>
   mode: <inline | subagent | check-all-inline | check-all-subagent | check-inline | check-subagent>
-  source: <trellis-route | route-prefs | numbered-fallback>
+  source: <trellis-route | route-prefs | auto-loop | numbered-fallback>
   scope: task
+  task: <current task path>
 
 接下来主 agent 应当：
 - <路由表里对应的工具调用形式>
@@ -223,7 +227,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 当证据。
 
 ---
 
@@ -233,13 +237,14 @@ route_decision:
 2. **runtime state 私有**：`.trellis/.runtime/sessions/` 是 session/window 状态，gitignored，不能进入提交计划。
 3. **压缩恢复少打断**：当前上下文没有 route 决策时，先读 runtime state；命中当前任务/target 的合法决策就复用，不查 `trellis mem`，也不重问。
 4. **个人默认次于本轮决策**：runtime state 表示“本轮已选”，优先于 `.route-prefs.tmp`。
-5. **显式覆盖优先于一切**：用户要求临时改、重新选择或清除默认时，必须重新展示选项，不能让 runtime state 或配置优先。
-6. **当前任务复用路由**：当前任务内已有合法来源的最近 implement/check 路由时，后续实现、修复、重检和复查默认沿用，不再次询问模式。
-7. **check 默认全面检查**：普通 check 路由只展示 `check-all` inline/subagent，不推荐轻量 `trellis-check`。
-8. **轻量 check 是隐藏逃生口**：只有用户明确请求 `light check` / `轻量检查` 时才可走轻量 `trellis-check`。
-9. **决策与执行分离**：本 skill 只输出指令，下一轮由主 agent 调工具。
-10. **严格执行用户选择**：路由结论一旦输出，主 agent 必须按指令执行，不可“出于谨慎”再换路径。
-11. **Codex inline 不裁剪选项**：Codex inline 是默认执行模式，不是只能 inline 的强制模式；route 明确选中 subagent 时，本步骤可按 subagent 路径执行。
+5. **auto 授权低于个人默认**：auto-loop 临时授权只在 runtime 和个人偏好都 miss 时生效。
+6. **显式覆盖优先于一切**：用户要求临时改、重新选择或清除默认时，必须重新展示选项，不能让 runtime state 或配置优先。
+7. **当前任务复用路由**：当前任务内已有合法来源的最近 implement/check 路由时，后续实现、修复、重检和复查默认沿用，不再次询问模式。
+8. **check 默认全面检查**：普通 check 路由只展示 `check-all` inline/subagent，不推荐轻量 `trellis-check`。
+9. **轻量 check 是隐藏逃生口**：只有用户明确请求 `light check` / `轻量检查` 时才可走轻量 `trellis-check`。
+10. **决策与执行分离**：本 skill 只输出指令，下一轮由主 agent 调工具。
+11. **严格执行用户选择**：路由结论一旦输出，主 agent 必须按指令执行，不可“出于谨慎”再换路径。
+12. **Codex inline 不裁剪选项**：Codex inline 是默认执行模式，不是只能 inline 的强制模式；route 明确选中 subagent 时，本步骤可按 subagent 路径执行。
 
 ---
 

package/enhancements/0.6/.claude/skills/trellis-route/scripts/route_state.py

@@ -12,7 +12,7 @@ from pathlib import Path
 from typing import Any
 
 
-VALID_SOURCES = {"trellis-route", "numbered-fallback", "route-prefs"}
+VALID_SOURCES = {"trellis-route", "numbered-fallback", "route-prefs", "auto-loop"}
 VALID_MODES = {
     "implement": {"inline", "subagent"},
     "check": {
@@ -83,6 +83,7 @@ def _output(args: argparse.Namespace, data: dict[str, Any], verbose: dict[str, A
 def _decision_summary(decision: dict[str, Any]) -> dict[str, Any]:
     """提取默认输出需要的最小 route 决策字段。"""
     return {
+        "task": decision.get("task"),
         "mode": decision.get("mode"),
         "source": decision.get("source"),
     }
@@ -129,6 +130,16 @@ def _pref_path(repo_root: Path) -> Path:
     return repo_root / ".trellis/.route-prefs.tmp"
 
 
+def _auto_loop_dir(repo_root: Path) -> Path:
+    """返回 auto-loop runtime 目录。"""
+    return repo_root / ".trellis/.runtime/auto-loop"
+
+
+def _auto_loop_pointer(repo_root: Path) -> Path:
+    """返回当前 auto-loop run 指针文件。"""
+    return _auto_loop_dir(repo_root) / "current.json"
+
+
 def _read_prefs(repo_root: Path) -> dict[str, str]:
     """读取个人 route 默认配置，只保留合法 key-value。"""
     path = _pref_path(repo_root)
@@ -149,6 +160,47 @@ def _read_prefs(repo_root: Path) -> dict[str, str]:
     return prefs
 
 
+def _auto_route_mode(repo_root: Path, context_key: str, target: str) -> tuple[str | None, Path | None, str | None]:
+    """读取当前 auto-loop run 的临时 route 授权。
+
+    auto 授权低于个人 `.route-prefs.tmp`，只在当前 session runtime 绑定了
+    `current_auto_run`，或全局 current 指针能指向唯一 running run 时生效。命中后
+    `resolve` 会写回 session runtime，后续压缩恢复仍走普通 route 决策路径。
+    """
+    session_path = _session_path(repo_root, context_key)
+    session = _read_json(session_path)
+    run_id = session.get("current_auto_run")
+
+    if not isinstance(run_id, str) or not run_id.strip():
+        pointer = _read_json(_auto_loop_pointer(repo_root))
+        run_id = pointer.get("run_id")
+
+    candidate_paths: list[Path] = []
+    if isinstance(run_id, str) and run_id.strip():
+        candidate_paths.append(_auto_loop_dir(repo_root) / f"{run_id.strip()}.json")
+    else:
+        for path in sorted(_auto_loop_dir(repo_root).glob("auto-*.json")):
+            state = _read_json(path)
+            if state.get("status") == "running":
+                candidate_paths.append(path)
+        if len(candidate_paths) != 1:
+            return None, None, "no-unique-auto-run"
+
+    path = candidate_paths[0]
+    state = _read_json(path)
+    if state.get("status") != "running":
+        return None, path, "auto-run-not-running"
+
+    auth = state.get("route_authorization")
+    if not isinstance(auth, dict):
+        return None, path, "no-route-authorization"
+
+    mode = auth.get(target)
+    if mode in PREF_MODES[target]:
+        return mode, path, None
+    return None, path, "invalid-auto-route-mode"
+
+
 def _write_prefs(repo_root: Path, prefs: dict[str, str]) -> None:
     """写入个人 route 默认配置；为空则删除文件。"""
     path = _pref_path(repo_root)
@@ -218,6 +270,13 @@ def _write_runtime_decision(
     decisions = context.get("route_decisions")
     if not isinstance(decisions, dict):
         decisions = {}
+    # 同一 AI session 可能连续处理多个 Trellis 任务。写入新任务的任一路由时，
+    # 先丢弃旧任务的 runtime 决策，避免后续 check 阶段绕过 helper 时误复用上个任务的选择。
+    decisions = {
+        key: value
+        for key, value in decisions.items()
+        if isinstance(value, dict) and value.get("task") == current_task
+    }
     decision = _decision(target, mode, source, current_task)
     decision["decided_at"] = now
     decisions[target] = decision
@@ -280,7 +339,7 @@ def read_runtime(args: argparse.Namespace) -> int:
 
 
 def resolve_route(args: argparse.Namespace) -> int:
-    """按 runtime → prefs 的优先级解析 route 决策。"""
+    """按 runtime → prefs → auto-loop 的优先级解析 route 决策。"""
     repo_root = _repo_root()
     if repo_root is None:
         return _print({"status": "miss", "reason": "not-trellis-project"})
@@ -337,15 +396,45 @@ def resolve_route(args: argparse.Namespace) -> int:
             }
         )
 
+    auto_mode, auto_path, auto_reason = _auto_route_mode(repo_root, context_key, args.target)
+    if auto_mode in PREF_MODES[args.target]:
+        written_path, auto_decision = _write_runtime_decision(
+            repo_root,
+            context_key,
+            current_task,
+            args.target,
+            auto_mode,
+            "auto-loop",
+        )
+        return _output(
+            args,
+            {
+                "status": "hit",
+                "origin": "auto-loop",
+                **_decision_summary(auto_decision),
+            },
+            {
+                "decision": auto_decision,
+                "path": _rel_path(repo_root, written_path),
+                "auto_path": _rel_path(repo_root, auto_path) if auto_path else None,
+                "pref_path": _rel_path(repo_root, _pref_path(repo_root)),
+                "context_key": context_key,
+                "task": current_task,
+                "wrote_runtime": True,
+            }
+        )
+
     return _output(
         args,
         {
             "status": "miss",
-            "reason": "no-valid-decision-or-pref",
+            "reason": "no-valid-decision-pref-or-auto",
         },
         {
             "path": _rel_path(repo_root, path),
             "pref_path": _rel_path(repo_root, _pref_path(repo_root)),
+            "auto_reason": auto_reason,
+            "auto_path": _rel_path(repo_root, auto_path) if auto_path else None,
             "context_key": context_key,
             "task": current_task,
         }

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

@@ -2,6 +2,7 @@
 HIGHEST PRIORITY SKILL-GARDEN STATE GUARD (planning-inline):
 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.
 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

@@ -2,6 +2,7 @@
 HIGHEST PRIORITY SKILL-GARDEN STATE GUARD (planning):
 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.
 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,7 +6,7 @@
 
 **Priority**: This hub overrides any conflicting Trellis workflow, skill, or command text for the scoped behaviors below.
 
-**Scope**: 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, 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**: 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.
 
@@ -41,6 +41,8 @@ After `trellis-check` or `trellis-check-all` finishes, stop and report the resul
 
 If checks pass, the next allowed workflow steps are Phase 3.3 `trellis-update-spec` and Phase 3.4 `trellis-push`/commit confirmation. `/trellis:finish-work` is explicit-only: run it only after Phase 3.4 is complete and the user asks to wrap up, archive, or finish the task.
 
+During a running `trellis-auto-loop`, the runner's `record` + `next` replaces the post-check stop gate: after a check pass, record the result, then continue to spec update / commit-only according to `.trellis/scripts/auto_loop.py`. Outside auto-loop, keep the normal stop gate.
+
 #### Code Commit Confirmation Gate
 
 Code commit/push belongs only to Phase 3.4 and must go through `trellis-push`; the main session must not run bare `git commit` / `git push` for code.
@@ -49,6 +51,12 @@ Code commit/push belongs only to Phase 3.4 and must go through `trellis-push`; t
 
 For "commit now, push later", use `trellis-push` commit-only mode; the later push still goes through `trellis-push`. `session_auto_commit` never authorizes code commits; it only affects bookkeeping commits below.
 
+#### Auto-loop Commit-only Preauthorization
+
+When the user explicitly starts `trellis-auto-loop` with `profile=commit-only`, that start preauthorizes only task-related local commits inside that run. When `.trellis/scripts/auto_loop.py status` reports `run_status=running`, `profile=commit-only`, and `outstanding_action.action=commit_only` for the active task, `trellis-push` may execute commit-only without an additional chat confirmation if the plan contains only files attributable to the current task, performs no push/merge/release/archive, and records the commit hash back to the runner.
+
+This exception does not apply to ordinary `trellis-push`. If the plan contains unrecognized staged files, conflicts, dirty files that cannot be attributed safely, push/merge/release/archive intent, external systems, credentials, or production data effects, stop or mark the current auto-loop task blocked.
+
 #### Bookkeeping Auto-commit Scope
 
 `session_auto_commit` only governs the bookkeeping commits `task.py archive` / `add_session.py` make for their own `.trellis/tasks/**` and `.trellis/workspace/**` files — never code (gated above). When `false`, those archive/journal writes stay disk-only (no compensating `git commit`).