落地任务复用治理规则与 worktree 对齐检查 [09-09-trellis-workflow-alignment]
2026-09-09 本地已验证完成、待交审的治理修复，一直未提交： - 6 个 skill（trellis-before-dev/brainstorm/check/continue/finish-work/start） 统一改为"先检查当前和直接相关既有任务，复用优先于新建"，取代原来"复杂任务 先请求新建 task"的默认动作；新增 worktree/active-task 一致性校验步骤。 - project-governance.md 新增两节：Task Reuse（任务复用判据）、Active Task And Worktree Alignment（激活任务与实际执行 worktree 一致性检查，防止跨 worktree 会话把上一个任务的 workflow-state 当成当前任务）。 - workflow.md 的 Request Triage / Parent-Child 章节、no_task 面包屑同步改写。 本地已过 task validate、check-trellis-governance.mjs、check-process-contract.mjs、 audit-docs.mjs、git diff --check；无业务代码改动。 Co-Authored-By: Claude Sonnet 5 <[email protected]>
这个提交包含在：
Claude Sonnet 5
@@ -22,6 +22,57 @@ tasks after TRELLIS2.
|
||||
- Keep edits scoped to the current Trellis task.
|
||||
- Commit only when explicitly requested, in Chinese with the task name or ID.
|
||||
|
||||
## Task Reuse
|
||||
|
||||
- A task is an execution contract, not a ticket for every tool call or fix.
|
||||
Check current and directly related tasks first, not every historical task.
|
||||
- Acceptance-related fixes stay in the current task. A different domain's fix
|
||||
goes to its suitable existing task as a scoped follow-up; link the blocker
|
||||
from the discovering task instead of duplicating implementation plans.
|
||||
- Create only when independently managed work has no suitable existing owner.
|
||||
Size, complexity, worktree isolation or a separate commit alone do not require
|
||||
a new task. Tiny standalone edits may stay untracked unless tracking is requested.
|
||||
- Task ownership, physical isolation and commit boundaries are separate choices.
|
||||
Reuse does not authorize mixed diffs, scope creep, production changes or commits.
|
||||
- Append only changed scope/acceptance/evidence, preserving historical results.
|
||||
New risk or business decisions still need approval; unchanged approved fixes
|
||||
do not. Do not bulk merge/archive tasks or reopen archived tasks to reduce counts.
|
||||
|
||||
## Active Task And Worktree Alignment
|
||||
|
||||
- On tracked-work entry, task scope change or execution worktree change, run
|
||||
`python3 .trellis/scripts/task.py current --source` in the actual execution
|
||||
root. Match the returned task to the intended work. Reuse unchanged context;
|
||||
this is not a requirement to reload all specs or run checks every turn.
|
||||
- For an already approved task, correct a mismatch using official
|
||||
`task.py start <task>`, then read back current and phase with
|
||||
`get_context.py --mode phase --platform codex`. Announce the task and phase
|
||||
when switching. Starting a task does not replace plan or risk approval.
|
||||
- Current task is session-scoped in `.trellis/.runtime/sessions/`, not the
|
||||
legacy `.trellis/.current-task`. Do not write runtime JSON or shared pointers
|
||||
manually. A missing legacy pointer is not evidence of runtime failure.
|
||||
If identity is unavailable, report degraded mode and retain explicit task
|
||||
context; do not claim the session pointer was repaired from exit code alone.
|
||||
- Previously injected workflow-state can be stale after switching tasks. Use
|
||||
official current/phase output for this turn; distinguish that verification
|
||||
from actual next-turn platform injection. Do not enable hooks or change
|
||||
user configuration merely to hide an execution mismatch.
|
||||
- Run validation in the worktree whose files changed. Record its baseline,
|
||||
task and evidence location. Isolated edits are not main-checkout integration;
|
||||
do not copy unrelated changes or activate unrelated tasks to tidy a status.
|
||||
- Inline mode changes who implements/checks, not the task contract. Keep
|
||||
PRD/design/implementation, targeted check and spec/status update steps.
|
||||
Static governance checks cannot prove that the correct task was used or
|
||||
replace business acceptance and independent review.
|
||||
- At stage handoff, record implementation, deployment, acceptance and pending
|
||||
owner/action separately. Use official `task.py finish` only to clear a session
|
||||
pointer when ending work; it does not complete or archive the task. Activate
|
||||
the intended task explicitly if current reports `session-fallback`; official
|
||||
resolution can infer the sole remaining session after a pointer is cleared.
|
||||
Do not treat that inferred task as new execution approval. Activate
|
||||
the next approved task explicitly when work actually resumes. Commit, push,
|
||||
archive and production operations retain their separate approval boundaries.
|
||||
|
||||
## Risk-Scoped Execution
|
||||
|
||||
- Pure consultation and small isolated edits do not need a task-creation
|
||||
|
||||
@@ -0,0 +1,22 @@
|
||||
# 设计与依据
|
||||
|
||||
## 官方依据
|
||||
|
||||
- 已安装 CLI：0.6.16。本轮使用随附指南，不声称已核对在线最新版本。
|
||||
- `.agents/skills/trellis-meta/references/local-architecture/task-system.md`：active task 为会话级状态，官方 start/current/finish 管理，不依赖旧全局 .current-task。
|
||||
- `.agents/skills/trellis-meta/references/local-architecture/context-injection.md`：workflow-state 从当前状态选块；收到的上一轮注入不代替切换后的读取。
|
||||
- `.agents/skills/trellis-meta/references/customize-local/overview.md`：先 current --source，最小修改项目文件，不编辑全局 npm 缓存。
|
||||
|
||||
## 根因与修复
|
||||
|
||||
实际恢复 task 与当时 current 返回的付款 task 不一致；官方会话解析正常，不能将旧 .current-task 不存在诊断为运行时损坏。工作迁移到隔离副本后，也未把相应命令的 cwd 和 task 核验作为固定入口。
|
||||
|
||||
采用既有 project-governance 记录完整合同，start/continue/before-dev/check/finish 各加短检查。工作范围或 cwd 变化时，从实际执行根目录读取 current --source；获批任务不匹配则用 start 显式切换并回读 task/phase。没有稳定身份时报告降级，不手写共享指针，不以 CLI 退出 0 代替回读成功。
|
||||
|
||||
验证始终在实际修改副本运行。主工作树 phase 和隔离副本验证分别记录；不把副本更新称为已集成。finish 清空会话指针与 archive 完成任务不同，未获授权不归档。保持 inline，无需开启子代理或改 hooks。
|
||||
|
||||
这是 AI 执行合同修复，不宣称新增了自动强制拦截。真正下一轮平台注入需观察下一轮消息；本轮可验证官方读取和渲染结果。
|
||||
|
||||
## 回退
|
||||
|
||||
仅撤销本 task 的治理文本差异；会话指针若要恢复，使用官方 start 明确选择下一项已获批工作。不改其他任务的验收或状态，不删除既有未跟踪目录。
|
||||
@@ -0,0 +1,55 @@
|
||||
# 执行清单
|
||||
|
||||
- [x] 读取随附官方指南、CLI 版本和当前任务来源，确认不是会话解析故障。
|
||||
- [x] 公布最小方案，建立本任务合同；不扩业务或部署范围。
|
||||
- [x] 官方 start 激活本 task，回读 current 和 phase。
|
||||
- [x] 同步治理 spec、相关五个 skill 及既有交付事实源。
|
||||
- [x] 临时 fixture 验证会话隔离与任务切换；验证实际修改根目录和本轮 diff。
|
||||
- [x] 记录本地验证、独立复核、平台下一轮注入及提交状态。
|
||||
|
||||
## 验证命令
|
||||
|
||||
- `python3 .trellis/scripts/task.py current --source`
|
||||
- `python3 .trellis/scripts/get_context.py --mode phase --step 2.1 --platform codex`
|
||||
- `python3 .trellis/scripts/task.py validate .trellis/tasks/09-09-trellis-workflow-alignment`
|
||||
- `node scripts/qa/check-trellis-governance.mjs`
|
||||
- `node scripts/qa/check-process-contract.mjs --baseline --json`
|
||||
- `node scripts/qa/audit-docs.mjs --check-registry`
|
||||
- `git diff --check`
|
||||
|
||||
本轮不运行产品测试或部署；无业务代码更改。会话切换 fixture 使用临时目录和显式测试 context id，不触碰真实付款/恢复任务。
|
||||
|
||||
## 2026-09-09 执行与验证结果
|
||||
|
||||
执行根目录：主工作树，产品基线 b918530；本轮主工作树治理修复与 ops-preparation 既有未提交记录物理分离。未复制、修改或提交其恢复/错误解释文档。
|
||||
|
||||
- 官方 start/current --source 回读为本 task，session 来源；phase 2.1 返回主会话实施指引。没有写旧全局指针，没有改会话运行时实现。
|
||||
- 临时目录调用官方 common.active_task：同会话 first→second 切换、两会话隔离、finish 清除当前指针但不修改 task 状态、剩余唯一会话 fallback 均通过。fixture 自动清理，没有改真实业务任务。
|
||||
- 首轮 fixture 将 finish 后默认 current 应为 none 当作前提而失败；阅读官方实现后确认存在 single-session fallback，修正测试预期并补充核对来源的规约，未为让测试通过修改官方代码。
|
||||
- 以当前会话环境手动运行既有 inject-workflow-state.py，断言输出含本 task、inline、trellis-before-dev，不再含旧付款任务标题。此为渲染验证，非新一轮平台实际投递验收。
|
||||
- 首轮 governance 报本 task 缺 Scope/Out of Scope/Test Plan 与 metadata scope；已补齐合同并使用官方 set-scope，再跑 PASS。task validate、process contract、diff 检查通过。
|
||||
- docs registry：errors=0、warnings=1，提示 22 个未注册文档。本轮没有新增 docs 文件，未扩范围批量登记或清理该警告。
|
||||
- inline 主会话完成只读差异检查，无独立 reviewer；真实下一轮平台注入待观察。没有新增自动强制拦截，规则与官方解析是两层证据。
|
||||
|
||||
| 实施 | 发布 | 验收 | 等谁/什么 |
|
||||
| --- | --- | --- | --- |
|
||||
| 本地治理修复完成，未提交 | 不适用，不部署 | 本地运行时/渲染与治理检查通过 | 下一轮观察真实注入；独立复核未做；提交/推送/归档另批 |
|
||||
|
||||
官方 start 提示当前 main 与 base_branch 相同，未来 archive 的分支/PR 门禁尚未处理。本轮无新建分支或归档授权，不为消警告伪造 branch/PR/完成状态；本 task 保持 in_progress，处于本地验证完成、待交审阶段。下一项 seed 治理未激活或实施。
|
||||
|
||||
### 后续交接更新
|
||||
|
||||
用户采纳后续队列建议后，本会话实际收到的平台 workflow-state 已显示 trellis-workflow-alignment，补齐了前轮仅手动渲染、下一轮投递待观察这一项。主会话复核既有 diff 与授权边界，未发现需扩大本次修复的项；独立 reviewer 仍未执行。文件保留待提交，用户“采纳建议”不扩展成提交/推送授权。
|
||||
|
||||
通过官方 create 转入 09-09-existing-deploy-seed-separation 的 planning 阶段，仅创建规划合同和只读核对源码；未开始 seed 实现。前段“下一项未激活”为当时状态。后续 seed 产品改动必须独立执行工作树，不叠加到本轮待交审的治理文件。
|
||||
|
||||
|
||||
### 经验精简：优先复用 task（用户已批准）
|
||||
|
||||
本轮用户明确要求更新、精简不合适经验，复用本 task 承载，不再为规则修正规划新目录。已修正 workflow 的“复杂任务先请求新建”、start 的“无当前任务就新建”以及 brainstorm 的“必须先取得新建授权”三个入口，统一为先检查当前和直接相关既有任务。完整归属规则集中在 project-governance 的 Task Reuse，其余入口引用，不为每次小修复制整套文档。
|
||||
|
||||
任务归属、工作树隔离、提交拆分分别决定；小修并非一律归当前任务，跨领域有现成归属则回对应 task。新增风险或实质范围仍需批准，纯咨询/微小编辑不强制 task；不批量合并、归档或重开历史任务。
|
||||
|
||||
本次实例：迁移状态 SIGPIPE 误判由 09-06-release-gate-integrity 的新增修复阶段承接。seed task 保留已复现证据和依赖链接，撤回“必须独立新建 task”的建议；主工作树与 seed 副本的本 task 记录同步，不迁移产品差异。门禁旧冻结交审材料及旧验收不改，新增阶段仍未实施。
|
||||
|
||||
本轮只读主会话检查及文档治理验证；没有独立 reviewer、提交、推送、部署或新任务目录。当前继续激活工作流修复 task，不把经验更新冒充预检产品修复。
|
||||
@@ -0,0 +1,36 @@
|
||||
# 修复 Trellis 任务切换与执行闭环
|
||||
|
||||
## Goal
|
||||
|
||||
依据已安装官方指南修复任务激活与实际执行脱节，保持 inline 和授权边界，不改运行时或业务代码
|
||||
|
||||
## Requirements
|
||||
|
||||
- 以已安装 Trellis 0.6.16 随附的 trellis-meta 官方指南及实际 CLI 为依据，核对 session active task、上下文和工作树边界。
|
||||
- 修复本项目入口与收口规则中未明确检查“实际执行任务与激活任务一致”的缺口；使用官方 task.py，不新造任务指针或运行器。
|
||||
- 保留 inline、session_auto_commit=false 和分别授权的提交/推送/生产操作边界。
|
||||
- 本轮仅主工作树的治理文档与本 task；不搬运 ops-preparation 的恢复/错误解释改动，不改产品、官方运行时、全局安装或用户 hooks 配置。
|
||||
|
||||
## Scope
|
||||
|
||||
主工作树 Trellis workflow、六个相关入口 skill、project-governance spec、既有 Agent 交付实践及本 task 合同；仅同步预检 finding 在已有 seed/门禁 task 间的归属，不改产品或旧门禁验收结果。
|
||||
|
||||
## Out of Scope
|
||||
|
||||
升级、运行时或 hooks 改造、产品代码、生产、提交推送归档、其他工作树的改动与其他任务状态。
|
||||
|
||||
## Test Plan
|
||||
|
||||
按 implement.md 执行官方 current/phase、临时会话 fixture、现有 hook 手动渲染与本 task 的文档治理检查。真实下一轮注入和独立复核分别标注，不以本地检查代替。
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [x] 本会话 current 与本任务一致；phase 输出为当前任务的 inline 实施流程。
|
||||
- [x] start/continue/before-dev/check/finish 入口同步任务与工作树核对合同，不要求每轮重复读未变化资料。
|
||||
- [x] 在临时隔离 fixture 中验证官方任务切换及会话隔离，不改其他真实任务状态。
|
||||
- [x] task validate、Trellis governance、process contract、docs registry 与 diff 检查通过，或如实记录失败。
|
||||
- [x] 明确区分运行时上下文验证、真实下一轮注入、独立复核及未提交状态。
|
||||
|
||||
## Notes
|
||||
|
||||
- 用户请求“按照trellis官方指南，检查并修复工作流”授权本范围；不包含升级或部署。方案先公布，按同范围实施。
|
||||
@@ -0,0 +1,26 @@
|
||||
{
|
||||
"id": "trellis-workflow-alignment",
|
||||
"name": "trellis-workflow-alignment",
|
||||
"title": "修复 Trellis 任务切换与执行闭环",
|
||||
"description": "依据已安装官方指南修复任务激活与实际执行脱节，保持 inline 和授权边界，不改运行时或业务代码",
|
||||
"status": "in_progress",
|
||||
"dev_type": null,
|
||||
"scope": "trellis-workflow",
|
||||
"package": null,
|
||||
"priority": "P2",
|
||||
"creator": "shunli",
|
||||
"assignee": "shunli",
|
||||
"createdAt": "2026-09-09",
|
||||
"completedAt": null,
|
||||
"branch": "main",
|
||||
"base_branch": "main",
|
||||
"worktree_path": null,
|
||||
"commit": null,
|
||||
"pr_url": null,
|
||||
"subtasks": [],
|
||||
"children": [],
|
||||
"parent": null,
|
||||
"relatedFiles": [],
|
||||
"notes": "",
|
||||
"meta": {}
|
||||
}
|
||||
+5
-5
@@ -180,8 +180,8 @@ Phase 3: Finish → verify, update spec, commit, and wrap up
|
||||
|
||||
### Request Triage
|
||||
|
||||
- Pure consultation and small, isolated edits need no task unless requested. Non-trivial work needs a task and an approved plan; ask for task creation only when not already authorized.
|
||||
- Complex task: ask whether you may create a Trellis task and enter planning. If the user says no, do not do broad inline implementation; explain, clarify scope, or suggest a smaller split.
|
||||
- Pure consultation and small, isolated edits need no new task unless requested. Non-trivial work needs a task contract and approved plan, not necessarily a new directory.
|
||||
- Check the current task and directly related existing tasks first. Put acceptance-related fixes in the current task; put another domain's fixes in its existing task with a scoped follow-up stage. Create a task only for independently managed work without a suitable existing owner, with creation consent when not already authorized. Do not expand an existing task silently or reopen archived tasks automatically.
|
||||
- User approval to create a task is not approval to start implementation. Planning still happens first.
|
||||
|
||||
### Planning Artifacts
|
||||
@@ -194,7 +194,7 @@ Phase 3: Finish → verify, update spec, commit, and wrap up
|
||||
|
||||
### Parent / Child Task Trees
|
||||
|
||||
Use a parent task when one user request contains several independently verifiable deliverables. The parent task owns the source requirement set, the task map, cross-child acceptance criteria, and final integration review; it normally should not be the implementation target unless it also has direct work.
|
||||
Use a parent task when genuinely new, independently managed deliverables need one; reuse suitable existing task contracts first. A small fix, separate worktree or separate commit alone does not require a child task. The parent owns cross-deliverable requirements and acceptance, not every incidental fix.
|
||||
|
||||
Use child tasks for deliverables that can be planned, implemented, checked, and archived independently. Parent/child structure is not a dependency system: if one child must wait for another, write that ordering in the child `prd.md` / `implement.md` and keep each child's acceptance criteria testable.
|
||||
|
||||
@@ -203,9 +203,9 @@ Create new children with `task.py create "<title>" --slug <name> --parent <paren
|
||||
<!-- Per-turn breadcrumb: shown when there is no active task (before Phase 1) -->
|
||||
|
||||
[workflow-state:no_task]
|
||||
No active task. First classify the current turn and ask for task-creation consent before creating any Trellis task.
|
||||
No active task. First classify the turn; no active pointer does not mean no suitable task exists.
|
||||
Pure consultation or a small isolated edit: respond or execute within scope without asking to create a task.
|
||||
Complex task: ask the user if you can create a Trellis task and enter the planning phase. If the user says no, explain, clarify scope, or suggest a smaller split.
|
||||
For tracked work, check directly related existing tasks and reuse a suitable contract. Activate already approved work with the official task command; new scope still needs review. Only request new-task creation when no suitable owner exists and creation is not already authorized. Do not create tasks merely for separate commits or worktrees.
|
||||
[/workflow-state:no_task]
|
||||
|
||||
<!-- Per-turn breadcrumb: shown when the active task record cannot be read. -->
|
||||
|
||||
在新工单中引用
屏蔽一个用户