@pennixrv/trellis 0.7.1-beta.16 → 0.7.1-beta.17

package/dist/migrations/manifests/0.7.1-beta.17.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.7.1-beta.17",
+  "description": "区分合同内返工与合同变更，恢复终态任务的受控重开",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "Execution rework preserves verified unchanged implementation authorization. New implementation contracts require a nonempty acceptance coverage table. Completed and cancelled tasks can explicitly reopen into planning, preserving terminal history and discarding stale runtime and authorization.",
+  "migrations": [],
+  "notes": "Run trellis update to refresh task scripts, the native workflow and phase Skills. Existing acceptance and authorization remain valid; new acceptance or authorization requires the coverage table. Reopen and phase return remain separate operations."
+}

package/dist/templates/common/bundled-skills/trellis-solution-design-and-convergence/workflow.md

@@ -8,6 +8,8 @@
 
 合同结果已接受、实施尚未授权时，发现需要返修，应通过 `task.py phase return` 回到本阶段或更早受影响阶段，记录理由和证据。受影响的接受与授权随之失效；修订后重新接受当前产物，再核验实施授权。
 
+接受 `implementation_contract` 前，在合同中建立 `## 验收覆盖` 表，表头为 `接受条件 | 工作包 | Owner | 验证入口 | 交付证据 | 停止条件`。逐条映射已接受条件，核对实际源码 owner、可运行验证、证据落点和停止条件；单一工作包可以覆盖多条条件。CLI 仅检查表结构及非空内容，不能代替语义审查。目标、合同、决策与执行记录分别使用明确的文件引用，执行细节追加到 execution 或 research，避免修改已接受的上游合同。
+
 逐项决定回答后，将已决目标、候选依据、接口与数据流、owner、依赖顺序、实施和验证，以及适用的迁移、发布、资源和失败恢复安排组织为一个完整方案。核对需求覆盖、跨产物一致性、可实施性和可验收性；有净收益时使用有界反例或压力测试，先修复可查缺口。向用户展示可识别的整体方案和实质剩余取舍后，再记录当前 revision 的接受及实施授权。逐项答复不自动等于整体批准；用户已充分明确批准整体方案时不重复索取。目标或候选问题回最早受影响阶段，局部方案问题在本阶段解决，不增设外部封口状态。
 
 研究、原型和协作证据写回现有阶段产物、research 或 execution 自然落点，注明来源与版本、事实和假设、适用性、限制及决定影响。证据足够即停止扩搜；工具、报告或模板不能替代用户决定和 Trellis 原生接受事实。

package/dist/templates/common/bundled-skills/trellis-task-implementation/workflow.md

@@ -28,4 +28,6 @@ flowchart TD
 
 ### 委派、回退与收敛
 
+合同不变的局部修复在当前活动阶段处理；需要撤销实施或交付接受事实时，使用 `phase return --return-kind execution_rework` 并提供原因、证据及目标阶段。仅在需求、合同摘要、路线和依赖仍有效时保留实施授权；CLI 拒绝时核对真实失效原因，不重复索取已有效的用户决定。合同实质变化使用默认 `contract_change` 回到最早受影响阶段并重新接受、授权。终态任务先经独立的 `reopen` 恢复到 `planning`，再操作工作流阶段；重开不复用旧授权。
+
 回退使用当前 owner 的 Git 和资源合同，不覆盖无关改动，也不删除仍需核验的现场。只有当前合同无法安全覆盖目标、授权、依赖、基线、接受条件或停止条件的变化时，才回退到最早受影响阶段。结束任务实施与测试验证阶段前，记录适用验证结果、未运行处置、合同差异和未结发现；仅当路线实际创建或委派资源时，记录其处置状态。

package/dist/templates/trellis/scripts/common/task_workflow.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import argparse
 import contextlib
+import copy
 from datetime import datetime, timezone
 import hashlib
 import json
@@ -445,6 +446,31 @@ def _show(state: dict) -> int:
     return 0
 
 
+def _require_acceptance_coverage(task_dir: Path, contract_ref: str) -> None:
+    _artifact_digest(task_dir, [contract_ref])
+    lines = (task_dir / contract_ref).read_text(encoding="utf-8").splitlines()
+    heading = next((index for index, line in enumerate(lines) if line.strip() == "## 验收覆盖"), None)
+    headers = ["接受条件", "工作包", "Owner", "验证入口", "交付证据", "停止条件"]
+    if heading is not None:
+        section = []
+        for line in lines[heading + 1:]:
+            if line.startswith("#"):
+                break
+            if line.strip():
+                section.append(line.strip())
+        rows = [line.strip("|").split("|") for line in section if line.startswith("|") and line.endswith("|")]
+        rows = [[cell.strip() for cell in row] for row in rows]
+        if (
+            len(rows) >= 3
+            and rows[0] == headers
+            and len(rows[1]) == len(headers)
+            and all(re.fullmatch(r":?-{3,}:?", cell) for cell in rows[1])
+            and all(len(row) == len(headers) and all(row) for row in rows[2:])
+        ):
+            return
+    raise TaskWorkflowError("TASK_PHASE_COVERAGE_REQUIRED", "implementation contract requires ## 验收覆盖 with nonempty rows: " + " | ".join(headers))
+
+
 def _update(args: argparse.Namespace, task_dir: Path, data: dict, state: dict) -> int:
     action = args.phase_action
     child_dispositions: dict[str, str] = {}
@@ -531,6 +557,8 @@ def _update(args: argparse.Namespace, task_dir: Path, data: dict, state: dict) -
             raise TaskWorkflowError("TASK_PHASE_INVALID_TRANSITION", "Solution Design and Convergence Phase must remain active for pending_user_decision or deferred; accept implementation_contract, analysis_conclusion, or no_go")
         if result_ref not in record["artifact_refs"]:
             raise TaskWorkflowError("TASK_PHASE_RESULT_NOT_BOUND", "--result-ref must be included in the current phase artifact refs")
+        if current == PHASE_IDS[2] and outcome == "implementation_contract":
+            _require_acceptance_coverage(task_dir, result_ref)
         if current == PHASE_IDS[3]:
             authorization = state.get("implementation_authorization")
             if not isinstance(authorization, dict) or authorization.get("task_route_revision") != state["task_route_revision"]:
@@ -568,17 +596,38 @@ def _update(args: argparse.Namespace, task_dir: Path, data: dict, state: dict) -
             _advance(state, current)
     elif action == "return":
         target = _required_text(args.target_phase, "--target-phase")
+        return_kind = args.return_kind
+        execution_rework = return_kind == "execution_rework"
         if target not in state["phase_ids"] or (
             state["phase_ids"].index(target) >= state["phase_ids"].index(current)
-            and not ((reviewed_delivery or accepted_design_return) and target == current)
+            and not ((reviewed_delivery or accepted_design_return or execution_rework) and target == current)
         ):
             raise TaskWorkflowError("TASK_PHASE_INVALID_TRANSITION", "return target must be an earlier phase in the current route")
         reason = _required_text(args.reason, "--reason")
         evidence = _refs(args.evidence_ref, "--evidence-ref", required=True)
+        authorization = state.get("implementation_authorization")
+        admission = state.get("route_dependency_admission")
+        if execution_rework:
+            if current not in PHASE_IDS[3:] or target not in PHASE_IDS[3:]:
+                raise TaskWorkflowError("TASK_PHASE_INVALID_TRANSITION", "execution_rework is limited to implementation and delivery phases")
+            candidate = copy.deepcopy(data)
+            candidate_state = candidate["meta"]["task_workflow"]
+            _invalidate_from(candidate_state, target, keep_first=True)
+            candidate_state["implementation_authorization"] = authorization
+            _require_current_accepted_artifacts(task_dir, candidate_state)
+            candidate_state["current_phase_id"] = PHASE_IDS[3]
+            candidate_state["phases"][PHASE_IDS[3]]["status"] = "active"
+            if not implementation_start_ready(candidate, task_dir):
+                raise TaskWorkflowError("TASK_PHASE_IMPLEMENTATION_NOT_AUTHORIZED", "execution_rework requires the unchanged authorized implementation contract")
+            if admission is not None and (admission.get("admission_state") != "ready" or admission.get("task_route_revision") != state["task_route_revision"]):
+                raise TaskWorkflowError("TASK_PHASE_ADMISSION_REQUIRED", "execution_rework requires current ready dependency admission")
         state["input_revision"] = _increment(state["input_revision"])
         _invalidate_from(state, target, keep_first=True)
+        if execution_rework:
+            state["implementation_authorization"] = authorization
+            state["route_dependency_admission"] = admission
         state["phases"][target]["input_revision"] = state["input_revision"]
-        state["return_record"] = {"from": current, "to": target, "reason": reason, "evidence_refs": evidence, "task_route_revision": state["task_route_revision"]}
+        state["return_record"] = {"from": current, "to": target, "return_kind": return_kind, "authorization_retained": execution_rework, "reason": reason, "evidence_refs": evidence, "task_route_revision": state["task_route_revision"]}
     elif action == "route":
         phases = _validate_route(args.phase_ids)
         task_kind = args.task_kind if args.task_kind is not None else state["task_kind"]
@@ -690,6 +739,7 @@ def _update(args: argparse.Namespace, task_dir: Path, data: dict, state: dict) -
                 raise TaskWorkflowError("TASK_PHASE_STALE_ARTIFACT", "Solution Design and Convergence Phase implementation contract changed after acceptance; refresh and accept the current artifact before authorization")
         elif contract_ref not in state.get("skip_records", {}).get(PHASE_IDS[2], {}).get("evidence_refs", []):
             raise TaskWorkflowError("TASK_PHASE_CONTRACT_NOT_ACCEPTED", "when Solution Design and Convergence Phase is omitted, the implementation contract must be among its route evidence")
+        _require_acceptance_coverage(task_dir, contract_ref)
         state["implementation_authorization"] = {"contract_ref": contract_ref, "contract_revision": _artifact_digest(task_dir, [contract_ref]), "approval_ref": approval_ref, "task_route_revision": state["task_route_revision"]}
         if current == PHASE_IDS[2]:
             _advance(state, current)
@@ -1011,6 +1061,56 @@ def cmd_cancel_task(args: argparse.Namespace) -> int:
         return 1
 
 
+def cmd_reopen_task(args: argparse.Namespace) -> int:
+    try:
+        task_dir = _task_dir(args.task_dir)
+        with _task_lock(task_dir):
+            data, meta = _load(task_dir)
+            previous_status = data.get("status")
+            if previous_status not in {"completed", "cancelled"}:
+                raise TaskWorkflowError("TASK_PHASE_REOPEN_INVALID_STATUS", "only completed or cancelled tasks can be reopened")
+            reason = _required_text(args.reason, "--reason")
+            evidence = _refs(args.evidence_ref, "--evidence-ref", required=True)
+            _assert_delegated_resources_closed(task_dir, data)
+            recoveries = meta.setdefault("task_lifecycle_recoveries", [])
+            if not isinstance(recoveries, list) or any(not isinstance(record, dict) for record in recoveries):
+                raise TaskWorkflowError("TASK_PHASE_TASK_INVALID", "task lifecycle recovery history is malformed")
+            recovery = {
+                "from_status": previous_status,
+                "to_status": "planning",
+                "reason": reason,
+                "evidence_refs": evidence,
+                "reopened_at": datetime.now(timezone.utc).isoformat(),
+                "terminal_completed_at": data.get("completedAt"),
+                "terminal_cancellation": copy.deepcopy(meta.get("task_cancellation")),
+            }
+            state = meta.get("task_workflow")
+            if state is not None:
+                state = _state(meta)
+                state["implementation_authorization"] = None
+                state["route_dependency_admission"] = None
+                state["closeout_disposition"] = None
+            recoveries.append(recovery)
+            data["status"] = "planning"
+            data["completedAt"] = None
+            from .task_move import relocate_task
+            from .active_task import clear_task_from_sessions
+            from .task_continuity import clear_task_runtime_records
+
+            repo_root = get_repo_root()
+            # Relocation rewrites runtime paths; terminal runtime must be discarded first.
+            for runtime_dir in (task_dir, repo_root / ".trellis/tasks/planning" / task_dir.name):
+                clear_task_from_sessions(str(runtime_dir), repo_root)
+                if not clear_task_runtime_records(repo_root, runtime_dir.relative_to(repo_root).as_posix()):
+                    raise TaskWorkflowError("TASK_PHASE_RUNTIME_CLEANUP_FAILED", "could not discard terminal task runtime; task remains terminal")
+            task_dir = relocate_task(repo_root, task_dir, data)
+            print(json.dumps({"status": "planning", "task_lifecycle_recovery": recovery, "runtime_records_cleared": True}, ensure_ascii=False))
+            return 0
+    except TaskWorkflowError as error:
+        print(f"{error.code}: {error}", file=sys.stderr)
+        return 1
+
+
 def task_closeout_readiness(data: dict, disposition: str) -> str | None:
     if "meta" in data and not isinstance(data["meta"], dict):
         return "task metadata is malformed"

package/dist/templates/trellis/scripts/task.py

@@ -14,6 +14,7 @@ Usage:
     python3 task.py workflow <id>|--clear       # Set/clear per-task workflow selection
     python3 task.py phase <action> <task-dir>    # Read/update task phase workflow state
     python3 task.py cancel <task-dir> --reason <text> --evidence-ref <ref>  # Cancel task lifecycle
+    python3 task.py reopen <task-dir> --reason <text> --evidence-ref <ref>  # Restore terminal task to planning
     python3 task.py set-branch <dir> <branch>   # Set git branch
     python3 task.py set-base-branch <dir> <branch>  # Set PR target branch
     python3 task.py set-scope <dir> <scope>     # Set scope for PR title
@@ -79,6 +80,7 @@ from common.task_context import (
 from common.task_workflow import (
     TaskWorkflowError,
     cmd_cancel_task,
+    cmd_reopen_task,
     cmd_complete_task,
     cmd_delegate_start,
     cmd_phase,
@@ -779,6 +781,7 @@ def main() -> int:
     p_phase.add_argument("--route-reason", help="Reason when initialization omits one or more phases")
     p_phase.add_argument("--route-evidence-ref", action="append", help="Evidence supporting an abbreviated initial route")
     p_phase.add_argument("--target-phase", help="Earlier phase to revisit, or first affected phase for route change")
+    p_phase.add_argument("--return-kind", choices=("contract_change", "execution_rework"), default="contract_change", help="Contract change invalidates authorization; execution rework retains a verified unchanged contract")
     p_phase.add_argument("--artifact-ref", action="append", help="Task-relative file in the current phase output")
     p_phase.add_argument("--artifact-revision", help="Current artifact_revision required for acceptance")
     p_phase.add_argument("--result-ref", help="Task result artifact reference")
@@ -803,6 +806,11 @@ def main() -> int:
     p_cancel.add_argument("--reason", required=True, help="Why the task is cancelled")
     p_cancel.add_argument("--evidence-ref", action="append", required=True, help="Task-relative cancellation evidence")
 
+    p_reopen = subparsers.add_parser("reopen", help="Recover a terminal task to planning without implementation authorization")
+    p_reopen.add_argument("task_dir", help="Task directory or task name")
+    p_reopen.add_argument("--reason", required=True, help="Why the same task must continue")
+    p_reopen.add_argument("--evidence-ref", action="append", required=True, help="Recovery decision evidence")
+
     # set-branch
     p_branch = subparsers.add_parser("set-branch", help="Set git branch")
     p_branch.add_argument("dir", help="Task directory")
@@ -880,6 +888,7 @@ def main() -> int:
         "delegate-start": cmd_delegate_start,
         "complete": cmd_complete_task,
         "cancel": cmd_cancel_task,
+        "reopen": cmd_reopen_task,
         "set-branch": cmd_set_branch,
         "set-base-branch": cmd_set_base_branch,
         "set-scope": cmd_set_scope,

package/dist/templates/trellis/workflow.md

@@ -30,12 +30,19 @@ python3 ./.trellis/scripts/task.py validate <task>
 python3 ./.trellis/scripts/task.py start <task>
 python3 ./.trellis/scripts/task.py complete <task>
 python3 ./.trellis/scripts/task.py cancel <task> --reason "<reason>" --evidence-ref <reference>
+python3 ./.trellis/scripts/task.py reopen <task> --reason "<reason>" --evidence-ref <reference>
 ```
 
 使用 `phase artifact`、`accept`、`skip`、`wait`、`block`、`resume`、`return`、`route` 和 `authorize` 执行对应的阶段操作。准确参数以 `task.py --help` 为准。跳过阶段必须提供理由和证据；目标探索与需求核对阶段不可省略。
 
 只有阶段路线已到达获准的实施入口时，`task.py start` 才会将任务从 `planning` 改为 `in_progress`。分析任务可在交付审查与现场收尾阶段后仍处于 `planning` 时完成。`complete` 将任务移入 `completed/YYYY-MM/<task>`，`cancel` 将任务移入 `cancelled/<task>`，并在同一事务中清除任务的运行时会话指针。
 
+工作流阶段回流与原生任务生命周期恢复分别操作。`completed` 或 `cancelled` 任务需要在原线程继续时，先用 `reopen` 恢复到 `planning`，保留终态事实、取消原因和恢复证据，清除旧运行态、实施授权和依赖准入；工作流阶段保持原记录。随后用 `phase return` 回到最早受影响阶段。实现任务重新接受合同、取得新的实施授权并核验准入后，才由 `start` 进入 `in_progress`。`phase return` 不能直接修改终态任务。
+
+`phase return` 默认采用 `contract_change`，使受影响阶段接受和实施授权失效。合同不变的局部实施或证据返工可显式使用 `--return-kind execution_rework`，目标限于实施或交付阶段，可重入当前阶段；CLI 核验需求、已接受合同、授权摘要、路线 revision 和已声明依赖准入仍有效后，保留授权，清理目标阶段及下游的接受事实。不能以此修改目标、合同或绕过待决依赖。普通局部修复可直接在当前活动阶段完成，无需为了记录进展而回流。
+
+新接受的 `implementation_contract`（以及省略设计阶段时新授权的合同）必须包含 `## 验收覆盖` 表，表头固定为 `接受条件 | 工作包 | Owner | 验证入口 | 交付证据 | 停止条件`，至少一行且各单元格非空。CLI 负责结构检查，阶段 Skill 负责逐条核对已接受条件的语义覆盖。既有接受和授权不会因本次升级自动失效；再次接受或授权时执行新检查。
+
 旧布局须先预览 `task.py migrate-layout`，核对后执行 `task.py migrate-layout --apply`；旧 `archive/YYYY-MM` 中已完成的任务保留原月份，其他任务按真实状态放置。迁移会同步 JSON/JSONL 机器引用、会话指针和运行态索引，保留任务身份与父子关系，不重授历史授权。未完成事务会阻止普通任务命令，须用 `task.py migrate-layout --recover` 恢复；输入被外部改动时停止并保留现场。路径或产物内容改变导致接受证据失效时，须经原生阶段接受或 continuity 核对重新收敛。
 
 在支持原生实施或检查 agent 的平台上，任务上下文清单（`implement.jsonl`、`check.jsonl`）用于提供相关规范和研究资料。只有这些 agent 会读取清单时才需要维护；清单不能替代任务资产或阶段证据。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pennixrv/trellis",
-  "version": "0.7.1-beta.16",
+  "version": "0.7.1-beta.17",
   "description": "AI capabilities grow like ivy — Trellis provides the structure to guide them along a disciplined path",
   "type": "module",
   "main": "./dist/index.js",
@@ -35,7 +35,7 @@
     "inquirer": "^9.3.7",
     "undici": "^6.21.0",
     "zod": "^4.4.2",
-    "@pennixrv/trellis-core": "0.7.1-beta.16"
+    "@pennixrv/trellis-core": "0.7.1-beta.17"
   },
   "devDependencies": {
     "@eslint/js": "^9.18.0",