落地任务复用治理规则与 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]>

.agents/skills/trellis-before-dev/SKILL.md

@@ -5,6 +5,8 @@ description: "Load the task and affected-layer guidelines before implementation
 
 # Before Development
 
+On entry or a scope/worktree change, verify official `task.py current --source` in the execution root matches the intended approved task. Correct a mismatch with `task.py start <task>` and read back current/phase before editing. Reuse this verification while unchanged; follow project-governance.md → Active Task And Worktree Alignment for degraded identity and worktree boundaries.
+
 1. Read the current PRD and applicable design/implementation notes if not already current in context.
 2. Identify the smallest behavior gap, affected files, exclusions and validation commands. Reuse the approved plan rather than writing another checklist.
 3. Discover package indexes only when the affected layer is unknown. Read its relevant coding and quality contracts; follow references needed for this change.

.agents/skills/trellis-brainstorm/SKILL.md

@@ -29,9 +29,9 @@ Use this skill during Phase 1 planning to turn the user's request into clear req
 
 ## Preconditions
 
-Use this skill only after task-creation consent has been given and the user is ready to enter Trellis planning.
+Use this skill when the user is ready to plan within an existing task or has approved a genuinely needed new task. Follow project-governance.md → Task Reuse; no new-directory approval is needed merely to refine an existing contract.
 
-If no task exists yet, create one:
+First check the current and directly related existing tasks. Reuse one with matching ownership and acceptance, adding only missing requirements and checks. If none is suitable and creation is authorized, create one:
 
 ```bash
 TASK_DIR=$(python3 ./.trellis/scripts/task.py create "<short task title>" --description "<one-line summary>" --slug <slug>)

.agents/skills/trellis-check/SKILL.md

@@ -5,6 +5,8 @@ description: "Verify the current task diff against its acceptance criteria and a
 
 # Task-Scoped Quality Check
 
+Verify the active task and actual validation worktree match the task/diff being checked; run official `task.py current --source` again if scope or cwd changed. Checks from the main checkout do not validate an edited isolated copy. Follow project-governance.md → Active Task And Worktree Alignment; record worktree and candidate separately from deployment and independent review.
+
 1. Identify files changed by this task. Git dirty state is evidence, not permission to include other work.
 2. Read acceptance criteria and applicable quality contracts not already loaded. Check the complete task diff, not only the last chunk.
 3. Run the minimum meaningful checks: targeted regressions for behavior changes, relevant syntax/type/build checks for affected layers, and governance/reference checks for rules. Expand for shared contracts and cross-layer risks.

.agents/skills/trellis-continue/SKILL.md

@@ -11,6 +11,8 @@ Resume work on the current task — pick up at the right phase/step in `.trellis
 
 ## Step 1: Load Current Context
 
+Run `python3 .trellis/scripts/task.py current --source` from the worktree that will actually be edited. Compare with the intended approved task. If mismatched, use official `task.py start <task>` and read back current before resuming. A previous turn's workflow-state may refer to the old task. Follow project-governance.md → Active Task And Worktree Alignment; do not create a legacy global pointer.
+
 ```bash
 python3 ./.trellis/scripts/get_context.py
 ```

.agents/skills/trellis-finish-work/SKILL.md

@@ -5,6 +5,8 @@ description: "Close out an explicitly requested session or completed task with t
 
 # Finish Work
 
+Before closeout, match the active task to the actual execution worktree and record phase, verification, remaining acceptance and who/what is pending. Follow project-governance.md → Active Task And Worktree Alignment. Official `task.py finish` only clears the session pointer; it is not task completion or archive. Do not silently switch to another business task or treat isolated-worktree notes as integrated changes.
+
 1. Compare this task with its acceptance criteria and latest validation evidence. Do not scan unrelated active tasks for cleanup.
 2. Report implementation, tests, independent review and deployment separately. A completed stage can leave the overall task active; unresolved acceptance must not be checked off.
 3. Update existing task notes with concise, redacted results and remaining steps. Record a journal only when useful or requested; avoid duplicating stable facts across documents.

.agents/skills/trellis-start/SKILL.md

@@ -6,9 +6,11 @@ description: "Initialize or resume non-trivial work in this Trellis project. Ski
 # Start Session
 
 1. Classify the request before loading context. Pure consultation and small isolated edits do not need a task or a task-creation question. Preserve risk boundaries in AGENTS.md.
-2. For tracked work, obtain current task and status from already supplied context, or run get_context.py when missing or stale. Do not enumerate unrelated journals and historical tasks.
+2. For tracked work, verify `python3 .trellis/scripts/task.py current --source` from the actual execution worktree when entering or switching scope/worktrees. Match it to the intended task; do not treat a previously injected task as proof. Reuse the result while scope and cwd remain unchanged. Do not enumerate unrelated journals and historical tasks.
 3. Read the workflow Phase Index and current step on demand. Read the current PRD, then design and implementation notes if needed. Reuse unchanged material already loaded in this session.
-4. With no task, obtain task-creation consent for non-trivial work unless already authorized. With a planning task, complete missing decisions; once its plan is approved, start and execute without asking again. An existing PRD alone is not proof of approval.
+4. Prefer the current or directly related existing task; add a scoped repair stage rather than creating a directory for every fix. Only seek new-task consent when independently managed work has no suitable owner. Follow project-governance.md → Task Reuse. With a planning task, complete missing decisions; an approved unchanged plan needs no repeat approval.
 5. For implementation load trellis-before-dev; for verification load trellis-check. Load spec indexes only for affected layers and follow relevant links, not every guideline.
 
 The project workflow and task status are authoritative over legacy user-level Trellis skills. Missing optional tools require a supported fallback or a precise limitation report, not repeated permission requests.
+
+For an already approved task, use official `task.py start <task>` on mismatch, then read back current and phase before implementation. Follow `.trellis/spec/hyb-oa/project-governance.md` → Active Task And Worktree Alignment; never create a shared pointer or infer hook delivery from start's success message.

.trellis/spec/hyb-oa/project-governance.md

@@ -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

.trellis/tasks/09-09-trellis-workflow-alignment/design.md

@@ -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 明确选择下一项已获批工作。不改其他任务的验收或状态，不删除既有未跟踪目录。

.trellis/tasks/09-09-trellis-workflow-alignment/implement.md

@@ -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，不把经验更新冒充预检产品修复。

.trellis/tasks/09-09-trellis-workflow-alignment/prd.md

@@ -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官方指南，检查并修复工作流”授权本范围；不包含升级或部署。方案先公布，按同范围实施。

.trellis/tasks/09-09-trellis-workflow-alignment/task.json

@@ -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": {}
+}

.trellis/workflow.md

@@ -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. -->