flower-trellis 0.6.4 → 0.6.6

package/README.md

@@ -85,7 +85,11 @@ flower-trellis -v
 
 > 已全局安装时可直接写 `flower-trellis`、`ftl` 或 `ft`(三者等价);未安装则在命令前加 `npx`。
 
-为统计安装活跃度和版本分布，CLI 默认在远程版本检查及 `init` / `update` 成功后上报随机设备 ID、Flower/Trellis 版本、开发者名称和运行平台。开发者名称优先读取项目 `.trellis/.developer`，缺失时回退到目标目录可见的 Git `user.name`，并缓存最近一次有效名称供后续上报；不采集 Git 邮箱、MAC、主机名、系统用户名、项目路径或仓库地址。可用 `flower-trellis telemetry disable` 持久停用，或用 `FLOWER_NO_TELEMETRY=1` 临时停用。
+默认启用安装与使用遥测：远程版本检查及 `init` / `update` 成功后保留原安装快照；新版还记录 Claude Code / Codex（0.6 full 集成）的 UTC 每日活动，以及 `init`、`update`、`self-update`、`plugin add` 的可观测终态。帮助、预览、菜单和未执行的自更新不计操作。
+
+载荷包含随机安装/事件 ID、观测时间、操作系统/架构、明确的 AI 平台、Flower 和捆绑/项目 Trellis/已装强化包版本；操作另含结果、有限错误分类和耗时口径。强化包版本沿用安装时 Flower 发布版本。开发者名称优先取项目 `.trellis/.developer`，其次 Git `user.name` 和缓存，可为空；不采集提示词、对话、session ID、错误原文、命令参数、外部插件 ID、Git 邮箱、MAC、主机名、系统用户名、项目路径或仓库地址。
+
+事件先进入用户配置目录下的 `telemetry-v2/`，后台独立进程一次最多发送 20 条，不等待网络即可结束主命令。本地最多保留 200 条、72 小时，失败退避重试；完全离线、强杀或关闭遥测可能造成样本缺口。`flower-trellis telemetry status` 只读展示待发数、丢弃数和最近诊断；`telemetry disable` 持久停用并清待发记录，已发出的请求无法撤回；`FLOWER_NO_TELEMETRY=1` 临时停用采集和发送且不写本地状态。旧版进程不具备新版共锁协议，不承诺与所有历史二进制之间的并发强一致。
 
 ### 命令
 
@@ -141,6 +145,21 @@ flower-trellis enable --target .
 
 项目处于 disabled 时，`flower-trellis update`、`self-update` 的项目更新链，以及 `plugin add/update/remove/replay` 会临时恢复必要入口，完成写操作后再次 detach，并校验最终仍为 disabled；外部 Plugin 内容不会被当作 Trellis 入口删除。直接运行上游 `trellis update` 不经过这一控制面，可能重新生成入口，此时 `flower-trellis status` 会报告 `drifted`。`disable` 也不等同于 `uninstall`：历史数据和恢复能力会继续保留。
 
+## Astra 工作流提示
+
+Codex 的 SessionStart 在 `startup`、`clear`、`compact` 时，只有事件输入的当前模型精确为 `gpt-6-astra`，才会在 state 分段追加一份英文工作流提示。其他模型（包括 5.5）、缺失模型和未知别名不会追加；普通用户轮次不重复注入。
+
+提示用于辅助遵循技能、工作流、模板和证据陈述，效果仍需行为对照验证。它不能删除宿主或历史指令，也不保证覆盖更高优先级要求。会话中切换模型后，要等下次 SessionStart 才重新判断是否追加。
+
+默认开启。要独立关闭，在项目 `.trellis/config.yaml` 已有的 `codex` 配置下合并这一项，保留原有字段：
+
+```yaml
+codex:
+  astra_workflow_hint: false
+```
+
+设置 `true` 或删除该字段恢复默认。开关只影响后续新增提示；做无历史干扰的对照时应使用新会话。原工作流上下文继续注入，Trellis 全局禁用、resume 和非交互跳过规则保持原有行为。`no-trellis` 仍只跳过本轮 UserPromptSubmit。
+
 ## Flower Plugin
 
 Flower Plugin 是 flower-trellis 的标准运行时格式。GitHub 公共仓库可自动识别 Flower、Codex、Claude Code 与 Skill-only 包，并先规范化为标准 Flower package，再进入同一套来源解析、依赖锁定、能力校验、内容投影、事务写入和卸载所有权。外部 `skills/` 与 Claude legacy `commands/*.md` 可导入；hooks、agents、MCP、LSP、monitor、bin、settings、themes、output styles 和 apps 只展示兼容性诊断，不会执行。

package/enhancements/0.6/overrides/bundles/control-plane-integrity.json

@@ -5,6 +5,8 @@
   "installMode": "full-only",
   "patches": [
     "scripts/task-store-write-integrity",
+    "scripts/task-current-query-contract",
+    "scripts/task-reference-resolution",
     "scripts/runtime-state-integrity",
     "scripts/session-context-update-boundary",
     "hooks/session-start/update-boundary"

package/enhancements/0.6/overrides/bundles/intent-routing.json

@@ -32,6 +32,7 @@
     "skills/trellis-brainstorm/planning-authorization",
     "skills/trellis-brainstorm/auto-task-create",
     "skills/trellis-brainstorm/planning-handoff",
-    "scripts/task-start-brief-gate"
+    "scripts/task-start-brief-gate",
+    "scripts/task-current-query-contract"
   ]
 }

package/enhancements/0.6/overrides/bundles/task-reference-contract.json

@@ -0,0 +1,24 @@
+{
+  "schemaVersion": 1,
+  "id": "task-reference-contract",
+  "aliases": [
+    "decision-log",
+    "task-progress",
+    "progress",
+    "push-snapshot",
+    "snapshot",
+    "trellis-auto-loop",
+    "auto-loop",
+    "auto-loop-runner",
+    "trellis-finish-work",
+    "finish-work",
+    "finish-work-enhancement",
+    "trellis-continue",
+    "continue",
+    "progress-recovery",
+    "trellis-push",
+    "push"
+  ],
+  "installMode": "full-or-selected",
+  "patches": ["scripts/task-reference-resolution"]
+}

package/enhancements/0.6/overrides/conflicts.json

@@ -137,9 +137,9 @@
           "<!-- BEGIN skill-garden patch brainstorm-planning-handoff v0.6 -->\n## Quality Bar",
           "## Planning Handoff",
           "<!-- BEGIN skill-garden patch brainstorm-planning-readiness v0.6 -->\n8. Load `trellis-task-brief`",
-          "The latest full Brief has been presented to the user.",
+          "Only valid explicit preauthorization for the current final Brief, as defined by `trellis-task-brief`, permits same-turn start within unchanged scope.",
           "The final Brief must cover Goal, Scope, Non-Goals, Key Decisions, Key Context, Acceptance, one-hop Next Step",
-          "Implementation intent expressed before the final artifacts and full Brief are shown authorizes planning only",
+          "Ordinary implementation intent expressed before the final artifacts and full Brief are shown authorizes planning only",
           "unresolved items are `- [ ]`",
           "Do not write bare placeholders"
         ]
@@ -161,9 +161,9 @@
           "<!-- BEGIN skill-garden patch brainstorm-planning-handoff v0.6 -->\n## Quality Bar",
           "## Planning Handoff",
           "<!-- BEGIN skill-garden patch brainstorm-planning-readiness v0.6 -->\n8. Load `trellis-task-brief`",
-          "The latest full Brief has been presented to the user.",
+          "Only valid explicit preauthorization for the current final Brief, as defined by `trellis-task-brief`, permits same-turn start within unchanged scope.",
           "The final Brief must cover Goal, Scope, Non-Goals, Key Decisions, Key Context, Acceptance, one-hop Next Step",
-          "Implementation intent expressed before the final artifacts and full Brief are shown authorizes planning only",
+          "Ordinary implementation intent expressed before the final artifacts and full Brief are shown authorizes planning only",
           "unresolved items are `- [ ]`",
           "Do not write bare placeholders"
         ]
@@ -1647,6 +1647,39 @@
       },
       "owner": "trellis-finish-work",
       "reason": "finish-work 只能归档已 completed 任务，不能替代 trellis-push 写完成状态。"
+    },
+    {
+      "id": "task-current-required-query-contract",
+      "severity": "error",
+      "target": ".trellis/scripts/task.py",
+      "whenOperations": ["task-current-query-contract"],
+      "assertion": {
+        "type": "required-literal",
+        "values": [
+          "# BEGIN skill-garden patch task-current-query-contract v0.6",
+          "print(colored(\"No current task set\", Colors.YELLOW))",
+          "\"current_task\": task_obj"
+        ]
+      },
+      "owner": "task-current-query-contract",
+      "reason": "current 查询的有效空状态必须以退出码 0 和明确输出表达。"
+    },
+    {
+      "id": "task-reference-required-strict-resolver",
+      "severity": "error",
+      "target": ".trellis/scripts/common/task_utils.py",
+      "whenOperations": ["task-reference-resolution"],
+      "assertion": {
+        "type": "required-literal",
+        "values": [
+          "# BEGIN skill-garden patch task-reference-resolution v0.6",
+          "def resolve_task_reference(task_ref: str, repo_root: Path) -> Path:",
+          "任务引用存在歧义",
+          "任务引用必须指向活动任务目录"
+        ]
+      },
+      "owner": "task-reference-resolution",
+      "reason": "消费 helper 必须复用确定性解析器，并拒绝歧义或越界路径。"
     }
   ]
 }

package/enhancements/0.6/overrides/patches/scripts/task-current-query-contract/patch.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": 2,
+  "id": "task-current-query-contract",
+  "purpose": "cli_query_contract",
+  "operations": [
+    {
+      "id": "task-current-query-contract",
+      "operation": "replace",
+      "targets": [{
+        "kind": "file",
+        "path": ".trellis/scripts/task.py",
+        "missing": "error",
+        "markerStyle": "hash"
+      }],
+      "selector": { "type": "literal", "source": "task-current-selector.py" },
+      "content": { "source": "task-current-content.py" }
+    }
+  ]
+}

package/enhancements/0.6/overrides/patches/scripts/task-current-query-contract/task-current-content.py

@@ -0,0 +1,39 @@
+def cmd_current(args: argparse.Namespace) -> int:
+    """Show active task."""
+    repo_root = get_repo_root()
+    active = resolve_active_task(repo_root)
+
+    if getattr(args, "json", False):
+        task_obj = None
+        if active.task_path:
+            data = read_json(repo_root / active.task_path / FILE_TASK_JSON) or {}
+            task_obj = {
+                "dir": active.task_path,
+                "id": data.get("id") or data.get("name"),
+                "title": data.get("title"),
+                "status": data.get("status"),
+                "parent": data.get("parent"),
+                "children": data.get("children", []),
+                "branch": data.get("branch"),
+                "base_branch": data.get("base_branch"),
+            }
+        print(json.dumps({
+            "current_task": task_obj,
+            "source": active.source,
+            "stale": active.stale,
+        }, ensure_ascii=False))
+        return 0
+
+    if args.source:
+        print(f"Current task: {active.task_path or '(none)'}")
+        print(f"Source: {active.source}")
+        if active.stale:
+            print("State: stale")
+        return 0
+
+    if active.task_path:
+        print(active.task_path)
+        return 0
+
+    print(colored("No current task set", Colors.YELLOW))
+    return 0

package/enhancements/0.6/overrides/patches/scripts/task-current-query-contract/task-current-selector.py

@@ -0,0 +1,38 @@
+def cmd_current(args: argparse.Namespace) -> int:
+    """Show active task."""
+    repo_root = get_repo_root()
+    active = resolve_active_task(repo_root)
+
+    if getattr(args, "json", False):
+        task_obj = None
+        if active.task_path:
+            data = read_json(repo_root / active.task_path / FILE_TASK_JSON) or {}
+            task_obj = {
+                "dir": active.task_path,
+                "id": data.get("id") or data.get("name"),
+                "title": data.get("title"),
+                "status": data.get("status"),
+                "parent": data.get("parent"),
+                "children": data.get("children", []),
+                "branch": data.get("branch"),
+                "base_branch": data.get("base_branch"),
+            }
+        print(json.dumps({
+            "current_task": task_obj,
+            "source": active.source,
+            "stale": active.stale,
+        }, ensure_ascii=False))
+        return 0 if active.task_path else 1
+
+    if args.source:
+        print(f"Current task: {active.task_path or '(none)'}")
+        print(f"Source: {active.source}")
+        if active.stale:
+            print("State: stale")
+        return 0 if active.task_path else 1
+
+    if active.task_path:
+        print(active.task_path)
+        return 0
+
+    return 1

package/enhancements/0.6/overrides/patches/scripts/task-reference-resolution/patch.json

@@ -0,0 +1,20 @@
+{
+  "schemaVersion": 2,
+  "id": "task-reference-resolution",
+  "purpose": "cli_task_reference",
+  "operations": [
+    {
+      "id": "task-reference-resolution",
+      "operation": "insert",
+      "position": "after",
+      "targets": [{
+        "kind": "file",
+        "path": ".trellis/scripts/common/task_utils.py",
+        "missing": "error",
+        "markerStyle": "hash"
+      }],
+      "selector": { "type": "literal", "source": "task-reference-selector.py" },
+      "content": { "source": "task-reference-content.py" }
+    }
+  ]
+}

package/enhancements/0.6/overrides/patches/scripts/task-reference-resolution/task-reference-content.py

@@ -0,0 +1,64 @@
+
+
+def resolve_task_reference(task_ref: str, repo_root: Path) -> Path:
+    """Resolve an existing active task reference deterministically.
+
+    Args:
+        task_ref: Exact task name, unique suffix, relative path, or absolute path.
+        repo_root: Repository root path.
+
+    Returns:
+        Resolved active task directory.
+
+    Raises:
+        ValueError: The reference is empty, ambiguous, missing, or outside active tasks.
+    """
+    raw = task_ref.strip() if isinstance(task_ref, str) else ""
+    if not raw:
+        raise ValueError("任务引用不能为空")
+
+    tasks_dir = get_tasks_dir(repo_root).resolve()
+    normalized = raw.replace("\\", "/")
+    while normalized.startswith("./"):
+        normalized = normalized[2:]
+
+    candidate = Path(raw)
+    if candidate.is_absolute() or "/" in normalized or normalized.startswith(".trellis"):
+        candidate = candidate if candidate.is_absolute() else repo_root / Path(normalized)
+        try:
+            resolved = candidate.resolve()
+        except (OSError, RuntimeError) as error:
+            raise ValueError(f"无法解析任务引用：{task_ref}") from error
+        if resolved.parent != tasks_dir or resolved.name == "archive":
+            raise ValueError(f"任务引用必须指向活动任务目录：{task_ref}")
+        if not resolved.is_dir():
+            raise ValueError(f"任务不存在：{task_ref}")
+        return resolved
+
+    exact = tasks_dir / raw
+    if exact.is_dir():
+        resolved = exact.resolve()
+        if resolved.parent != tasks_dir or resolved.name == "archive":
+            raise ValueError(f"任务引用必须指向活动任务目录：{task_ref}")
+        return resolved
+
+    try:
+        named_matches = sorted(
+            path
+            for path in tasks_dir.iterdir()
+            if path.is_dir() and path.name != "archive" and path.name.endswith(f"-{raw}")
+        )
+    except OSError as error:
+        raise ValueError(f"无法读取活动任务目录：{tasks_dir}") from error
+    matches = []
+    for path in named_matches:
+        resolved = path.resolve()
+        if resolved.parent != tasks_dir or resolved.name == "archive":
+            raise ValueError(f"任务引用必须指向活动任务目录：{task_ref}")
+        matches.append(resolved)
+    if len(matches) == 1:
+        return matches[0]
+    if len(matches) > 1:
+        names = ", ".join(path.name for path in matches)
+        raise ValueError(f"任务引用存在歧义：{task_ref}；候选：{names}；请使用完整目录名")
+    raise ValueError(f"任务不存在：{task_ref}")

package/enhancements/0.6/overrides/patches/scripts/task-reference-resolution/task-reference-selector.py

@@ -0,0 +1,2 @@
+    # Fallback to treating as relative path
+    return repo_root / Path(normalized)

package/enhancements/0.6/overrides/patches/skills/trellis-brainstorm/planning-handoff/content.md

@@ -9,15 +9,13 @@ Before declaring planning ready:
 - Complex tasks have `design.md` and `implement.md`.
 - Sub-agent-dispatch tasks have real curated entries in both `implement.jsonl` and `check.jsonl`; seed-only manifests are not ready.
 - Planning artifacts are ready for the final Brief handoff.
-- The latest full Brief has been presented to the user.
-- In a subsequent message, the user explicitly approved that Brief for implementation.
 
 Do not start implementation merely because the user originally asked for implementation.
 
 ## Planning Handoff
 
-Once the Quality Bar is satisfied, load `trellis-task-brief`, refresh `brief.md` from the final planning artifacts, display the full Brief in chat, and end the current turn. Wait for the user's planning review confirmation before running `task.py start` or beginning implementation.
+Once the Quality Bar is satisfied, load `trellis-task-brief`, refresh `brief.md` from the final planning artifacts, and display the full Brief in chat. By default, end the current turn and wait for the user's planning review confirmation. Only valid explicit preauthorization for the current final Brief, as defined by `trellis-task-brief`, permits same-turn start within unchanged scope.
 
-Implementation intent expressed before the final artifacts and full Brief are shown authorizes planning only; it cannot be reused as the final review confirmation.
+Ordinary implementation intent expressed before the final artifacts and full Brief are shown authorizes planning only; it cannot be reused as the final review confirmation.
 
 For `## Open Questions`, use Markdown checkbox state rather than placeholder prose: unresolved items are `- [ ]`; resolved items move into requirements/decisions or are removed; when no open questions remain, remove the section or leave it empty. Do not write bare placeholders such as `- None`, `- TBD`, or `- 已确认` because historical bare list items require an explicit auto-loop semantic review.

package/enhancements/0.6/overrides/patches/skills/trellis-brainstorm/planning-handoff/planning-contract-content.md

@@ -1 +1 @@
-For every non-trivial task, the user must respond at least once after the initial request before implementation begins. If no clarification is needed, that response must approve the final Brief described below.
+For every non-trivial task, follow `trellis-task-brief` for the final Brief review and its explicit preauthorization exception before implementation begins. Ordinary implementation or task-creation intent is not Brief approval.

package/enhancements/0.6/overrides/patches/skills/trellis-brainstorm/planning-handoff/readiness-content.md

@@ -1,2 +1,2 @@
-8. Load `trellis-task-brief`, refresh `brief.md` from the converged artifacts, display the full Brief, and stop. Do not run `task.py start` or edit product code in the same turn.
-9. Only a subsequent user message that explicitly approves the latest full Brief authorizes `task.py start` and implementation. If the artifacts change materially after approval, refresh and repeat the Brief review.
+8. Load `trellis-task-brief`, refresh `brief.md` from the converged artifacts, and display the full Brief. Follow its review gate and explicit preauthorization exception.
+9. Run `task.py start` and begin implementation only after that review gate is satisfied. If the artifacts change materially after approval, refresh and repeat the Brief review.

package/enhancements/0.6/overrides/patches/skills/trellis-brainstorm/planning-handoff/review-content.md

@@ -1,3 +1,3 @@
-Do not manufacture clarification questions when the request and repository evidence already resolve every decision. In that case, proceed directly to the final Brief handoff, which still requires a subsequent explicit approval.
+Do not manufacture clarification questions when the request and repository evidence already resolve every decision. In that case, proceed directly to the final Brief handoff through `trellis-task-brief`.
 
-The final Brief review is a required phase-transition gate, not a prohibited process question. Task-creation consent, the initial implementation request, and approval given before the latest full Brief do not satisfy this gate.
+The final Brief review is a required phase-transition gate, not a prohibited process question. Task-creation consent and ordinary implementation intent do not satisfy this gate; explicit preauthorization is evaluated only by `trellis-task-brief`.

package/enhancements/0.6/scripts/decision_log.py

@@ -47,6 +47,17 @@ def _repo_root() -> Path | None:
         current = current.parent
 
 
+def _load_common_modules(repo_root: Path) -> None:
+    """把 Trellis scripts 目录加入 import path。
+
+    Args:
+        repo_root: Trellis 项目根。
+    """
+    scripts_dir = repo_root / ".trellis/scripts"
+    if str(scripts_dir) not in sys.path:
+        sys.path.insert(0, str(scripts_dir))
+
+
 def _resolve_task_dir(repo_root: Path, task: str) -> Path:
     """把任务引用解析为活动任务目录。
 
@@ -60,21 +71,13 @@ def _resolve_task_dir(repo_root: Path, task: str) -> Path:
     Raises:
         DecisionLogError: 任务不存在或位于项目外。
     """
-    raw = task.strip()
-    candidate = Path(raw)
-    candidates = [candidate] if candidate.is_absolute() else [
-        repo_root / raw,
-        repo_root / ".trellis/tasks" / raw,
-    ]
-    for path in candidates:
-        try:
-            resolved = path.resolve()
-            resolved.relative_to((repo_root / ".trellis/tasks").resolve())
-        except (OSError, ValueError):
-            continue
-        if resolved.is_dir():
-            return resolved
-    raise DecisionLogError(f"任务不存在或不在活动任务目录:{task}")
+    _load_common_modules(repo_root)
+    from common.task_utils import resolve_task_reference  # type: ignore[import-not-found]
+
+    try:
+        return resolve_task_reference(task, repo_root)
+    except ValueError as exc:
+        raise DecisionLogError(str(exc)) from exc
 
 
 def _validate_event(event: Any, line_number: int) -> dict[str, Any]:
@@ -457,19 +460,21 @@ def build_parser() -> argparse.ArgumentParser:
     Returns:
         已配置的参数解析器。
     """
-    parser = argparse.ArgumentParser(description="Trellis AI decision log.")
+    parser = argparse.ArgumentParser(description="读取和审查 Trellis AI 决策日志。")
     subparsers = parser.add_subparsers(dest="command", required=True)
 
-    status = subparsers.add_parser("status")
-    status.add_argument("--task", required=True)
-    status.add_argument("--json", action="store_true")
+    task_help = "任务完整目录名、项目内路径、允许的绝对路径或唯一短名（例如 cli-invocation-contracts）"
+
+    status = subparsers.add_parser("status", help="读取任务决策审查状态")
+    status.add_argument("--task", required=True, help=task_help)
+    status.add_argument("--json", action="store_true", help="输出完整 JSON")
     status.set_defaults(func=cmd_status)
 
-    review = subparsers.add_parser("review")
-    review.add_argument("--task", required=True)
-    review.add_argument("--verdict", choices=sorted(VALID_VERDICTS), required=True)
-    review.add_argument("--decision-id", action="append", default=[])
-    review.add_argument("--notes")
+    review = subparsers.add_parser("review", help="记录人工审查结果")
+    review.add_argument("--task", required=True, help=task_help)
+    review.add_argument("--verdict", choices=sorted(VALID_VERDICTS), required=True, help="审查结论")
+    review.add_argument("--decision-id", action="append", default=[], help="需返工的决策 ID，可重复")
+    review.add_argument("--notes", help="人工审查备注")
     review.set_defaults(func=cmd_review)
     return parser
 

package/enhancements/0.6/scripts/task_progress.py

@@ -88,9 +88,9 @@ def _rel_path(repo_root: Path, path: Path) -> str:
 def _resolve_task_dir(repo_root: Path, task_ref: str) -> Path:
     """解析任务目录引用。"""
     _load_common_modules(repo_root)
-    from common.task_utils import resolve_task_dir  # type: ignore[import-not-found]
+    from common.task_utils import resolve_task_reference  # type: ignore[import-not-found]
 
-    return resolve_task_dir(task_ref, repo_root)
+    return resolve_task_reference(task_ref, repo_root)
 
 
 def _current_task_dir(repo_root: Path) -> Path | None:
@@ -127,6 +127,11 @@ def _utc_date() -> str:
     return datetime.now(timezone.utc).date().isoformat()
 
 
+def _utc_now() -> str:
+    """返回秒级 UTC ISO-8601 时间。"""
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
 def _legacy_progress(snapshot: dict[str, Any]) -> dict[str, Any]:
     """把旧 last_push_snapshot 映射为新进度结构。"""
     completed = snapshot.get("completed_steps")
@@ -273,6 +278,15 @@ def _validate_progress(value: Any) -> tuple[dict[str, Any] | None, list[str]]:
     return value, []
 
 
+def _normalize_progress_for_write(value: Any) -> Any:
+    """仅为完全缺失的 updatedAt 补充机械时间字段。"""
+    if not isinstance(value, dict) or "updatedAt" in value:
+        return value
+    normalized = dict(value)
+    normalized["updatedAt"] = _utc_now()
+    return normalized
+
+
 def _print_json(data: dict[str, Any], exit_code: int = 0) -> int:
     """输出紧凑 JSON。"""
     print(json.dumps(data, ensure_ascii=False, sort_keys=True))
@@ -379,7 +393,7 @@ def cmd_write(args: argparse.Namespace, repo_root: Path) -> int:
         print(f"错误：invalid-progress-json：{exc}", file=sys.stderr)
         return 1
 
-    progress, errors = _validate_progress(raw_progress)
+    progress, errors = _validate_progress(_normalize_progress_for_write(raw_progress))
     if progress is None:
         result = {
             "status": "error",
@@ -489,13 +503,29 @@ def build_parser() -> argparse.ArgumentParser:
     """创建命令行解析器。"""
     parser = argparse.ArgumentParser(description="读取或写入 Trellis 任务进度。")
     subparsers = parser.add_subparsers(dest="command", required=True)
+    task_help = "任务完整目录名、项目内路径、允许的绝对路径或唯一短名（例如 cli-invocation-contracts）"
 
     status = subparsers.add_parser("status", help="读取任务进度")
-    status.add_argument("--task", help="任务目录、路径或任务名")
+    status.add_argument("--task", help=task_help)
     status.add_argument("--json", action="store_true", help="输出 JSON")
 
-    write = subparsers.add_parser("write", help="写入任务进度")
-    write.add_argument("--task", required=True, help="任务目录、路径或任务名")
+    write = subparsers.add_parser(
+        "write",
+        help="写入任务进度",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""字段：
+  completedSteps  已完成步骤的字符串数组
+  partialStep     当前部分完成步骤，字符串或 null
+  nextStep        下一步，非空字符串
+  notes           补充说明字符串
+  updatedAt       可选；缺失时自动生成 UTC 时间，显式空值仍会失败
+
+最小示例：
+  task_progress.py write --task cli-invocation-contracts \\
+    --progress-json '{"completedSteps":[],"partialStep":null,"nextStep":"继续实现","notes":""}'
+""",
+    )
+    write.add_argument("--task", required=True, help=task_help)
     write.add_argument("--progress-json", required=True, help="progress JSON 对象")
     write.add_argument(
         "--complete",
@@ -505,7 +535,7 @@ def build_parser() -> argparse.ArgumentParser:
     write.add_argument("--json", action="store_true", help="输出 JSON")
 
     reopen = subparsers.add_parser("reopen", help="把 completed 任务恢复为 in_progress")
-    reopen.add_argument("--task", required=True, help="任务目录、路径或任务名")
+    reopen.add_argument("--task", required=True, help=task_help)
     reopen.add_argument("--json", action="store_true", help="输出 JSON")
 
     return parser
@@ -520,12 +550,23 @@ def main() -> int:
 
     parser = build_parser()
     args = parser.parse_args()
-    if args.command == "status":
-        return cmd_status(args, repo_root)
-    if args.command == "write":
-        return cmd_write(args, repo_root)
-    if args.command == "reopen":
-        return cmd_reopen(args, repo_root)
+    try:
+        if args.command == "status":
+            return cmd_status(args, repo_root)
+        if args.command == "write":
+            return cmd_write(args, repo_root)
+        if args.command == "reopen":
+            return cmd_reopen(args, repo_root)
+    except ValueError as exc:
+        payload = {
+            "status": "error",
+            "reason": "task-reference-error",
+            "message": str(exc),
+        }
+        if getattr(args, "json", False):
+            return _print_json(payload, 1)
+        print(f"错误：task-reference-error：{exc}", file=sys.stderr)
+        return 1
     parser.print_help()
     return 1
 

package/enhancements/0.6/scripts/untracked_flow.py

@@ -363,11 +363,11 @@ def read_untracked_state(
         repo_root: Trellis 项目根目录。
         platform_input: 可选平台 hook 输入。
         platform: 可选平台名称。
-        allow_active_task: 是否允许 session 同时已有 task，供 adoption 清理使用。
+        allow_active_task: 是否允许读取已有活动 task；状态查询会返回不适用结果。
         validate_workspace: 兼容旧调用方的废弃参数；不再读取或校验 Git workspace。
 
     Returns:
-        ``hit`` 或 ``miss`` 的结构化状态。
+        ``hit``、``miss`` 或 ``not-applicable`` 的结构化状态。
     """
     del validate_workspace
     scope = _runtime_scope(
@@ -376,6 +376,14 @@ def read_untracked_state(
         platform,
         allow_active_task=allow_active_task,
     )
+    current_task = scope.get("current_task")
+    if allow_active_task and isinstance(current_task, str) and current_task.strip():
+        return {
+            "status": "not-applicable",
+            "reason": "active-task-present",
+            "task": current_task,
+            "contextKey": scope["context_key"],
+        }
     raw = scope["context"].get(STATE_KEY)
     if raw is None:
         return {"status": "miss", "reason": "no-active-work", "contextKey": scope["context_key"]}
@@ -398,7 +406,7 @@ def clear_untracked_state(
     platform: str | None = None,
     *,
     work_id: str | None = None,
-    allow_active_task: bool = True,
+    allow_active_task: bool = False,
 ) -> dict[str, Any]:
     """按明确原因清理当前 session 的 untracked 状态。
 
@@ -408,7 +416,7 @@ def clear_untracked_state(
         platform_input: 可选平台 hook 输入。
         platform: 可选平台名称。
         work_id: 可选的精确事项 ID 防误清。
-        allow_active_task: 是否允许 session 已绑定 task。
+        allow_active_task: 是否显式允许 session 已绑定 task。
 
     Returns:
         清理结果和被清理事项 ID。
@@ -538,7 +546,7 @@ def main(argv: list[str] | None = None) -> int:
         elif args.command == "advance":
             payload = advance_stage(repo_root, args.stage)
         elif args.command == "status":
-            payload = read_untracked_state(repo_root)
+            payload = read_untracked_state(repo_root, allow_active_task=True)
         elif args.command == "session-start-hint":
             hint = session_start_hint(repo_root)
             payload = {"status": "hit", "hint": hint} if hint else {"status": "miss"}