Documentation Index
Fetch the complete documentation index at: https://docs.trytrellis.app/llms.txt
Use this file to discover all available pages before exploring further.
beta.18 重新设计了 workflow Phase 3：新增 Phase 3.4 Commit changes 步骤，让 AI 按本次 session 改动批量起草 commit；/trellis:finish-work 回归 archive + journal 语义，工作区还有未提交代码改动时拒绝执行。同时修复了子任务归档导致父任务进度回退的 bug、trellis update 期间 AGENTS.md 哈希追踪的问题，以及 OpenCode 在 Windows 下的 PowerShell context 注入。
Enhancements
Phase 3.4 Commit changes
workflow.md Phase 3 新增必选步骤 3.4 Commit changes，由 AI 主导 commit 节奏，不再丢给用户手动处理。
| Step | AI 的具体动作 |
|---|
| 1 | 跑 git status --porcelain 快照所有 dirty path |
| 2 | 跑 git log --oneline -5 学习 repo 的 commit message 风格（前缀 / 语言 / 长度） |
| 3 | 把 dirty 文件分成 AI 本会话编辑过 和 未识别 两组 |
| 4 | 起草多 commit plan，每批一个语义内聚的改动 |
| 5 | 一次性展示 plan 给用户 confirm |
| 6 | 用户确认后：每批跑 git add + git commit，不允许 --amend，不允许 git push |
| 7 | 用户拒绝（“不行” / “我自己来” / “manual” / 任何反对）：退出 commit 编排，不做第二次 plan，无需 flag |
3.4 的 Wrap-up reminder 顺移到 3.5。[workflow-state:completed] breadcrumb（以及 inject-workflow-state.py / inject-workflow-state.js 的四份 hook fallback）现在统一指向 /trellis:finish-work，不再走老的 task.py finish + task.py archive 提示。
/trellis:finish-work 回归 survey + archive + journal
skill 删掉了原本的 “Remind user to commit” 步骤，加了一步 survey 帮你发现遗忘的已完成任务。新流程是：
| Step | 动作 |
|---|
| 1 | get_context.py --mode record 输出 active tasks、git status 和 recent commits。如果除了当前 task 之外还有其它看起来已完成的 task，一次性问用户：“这 N 个一并归档吗？[y/N]“ |
| 2 | 跑 git status --porcelain，排除 .trellis/workspace/ 和 .trellis/tasks/（这两个路径由脚本 auto-commit 管理）。其它路径有 dirty 文件就拒绝执行。 |
| 3 | 对当前 active task 跑 task.py archive <task>（一定归档）+ Step 1 用户确认的其它 task。每条产生一个 chore(task): archive ... commit |
| 4 | 跑 add_session.py --commit <hashes> 写 session journal（产生 chore: record journal commit）。hash 取自 Step 1 的 Recent commits 输出 |
<3.4 阶段的 work commits> → chore(task): archive ...（可能多条）→ chore: record journal，bookkeeping commit 永远在 work commit 之后，不再交错。
common skill 模板用 {{CMD_REF:finish-work}} 占位符，每个平台按自己的 cmdRefPrefix 解析：Claude Code / OpenCode 是 /trellis:finish-work，Codex 是 $finish-work，Cursor 是 /trellis-finish-work。
Bug Fixes
子任务归档不再让父任务进度倒退
task.py list 之前会在子任务被归档后从父任务的 [x/y done] 计数里把它丢掉。
| 场景 | beta.18 之前 | beta.18 |
|---|
| 6 个子任务，1 个完成并归档 | [0/5 done] | [1/6 done] |
| 6 个子任务，2 个完成并归档 | [0/4 done] | [2/6 done] |
cmd_archive 不再从父任务的 children 列表里移除归档过的子任务，children_progress 把”不在活跃状态表里的 child”视为已完成（cmd_archive 在移动目录前总会把状态改成 completed）。这个 invariant 已写入 .trellis/spec/cli/backend/script-conventions.md 的 “Parent-child invariant” 一节。
trellis update 期间 AGENTS.md 哈希追踪
beta.18 之前的项目写过 AGENTS.md 但没记录模板哈希，所以 update 时会被当成 “modified by you” 冲突。beta.18 引入：
| 机制 | 行为 |
|---|
<!-- TRELLIS:START --> block | 标记 AGENTS.md 内的 Trellis 管理区域；update 只替换这个 block，外面的用户内容一律保留 |
LEGACY_UNTRACKED_AGENTS_MD_BLOCK_HASHES allowlist | 收录 beta.18 之前 pristine 状态下的 block hash（如 c1f511b1...），匹配中即静默通过，老项目不会被追问 |
| Hash tracking | template-hash.ts 此后会记录新模板的哈希，后续 update 走正常分类流程 |
OpenCode 在 Windows 下的 PowerShell context 注入
inject-subagent-context.js 现在按 host.platform 选择正确的 shell 语法：
| Platform | 注入的前缀 |
|---|
win32 | $env:TRELLIS_CONTEXT_ID = '<key>'; <command> |
| 其它 | export TRELLIS_CONTEXT_ID='<key>'; <command> |
TRELLIS_CONTEXT_ID=...、export TRELLIS_CONTEXT_ID=...）和 PowerShell 形式（$env:TRELLIS_CONTEXT_ID = ...），用户手动加过前缀的命令不会被二次包装。
Internal
Vitest 测试隔离：清掉 host shell 的 session env
packages/cli/test/setup.ts 通过 vitest.config.ts 的 setupFiles 注册，在 vitest 进程启动时 delete process.env.TRELLIS_CONTEXT_ID 和 process.env.OPENCODE_RUN_ID，这样 OpenCode resolver 的测试就不会被 Claude / OpenCode 宿主 session 的 env 漏进来 hijack 掉 platform-input 推导出的 contextKey。这个模式已写入 .trellis/spec/cli/unit-test/conventions.md 的 “Test Isolation” 一节。
Spec 更新
| Spec 文件 | 新增内容 |
|---|
.trellis/spec/cli/backend/script-conventions.md | 父子任务 children 列表 invariant —— 历史列表，归档时不剔除，children_progress 把缺失视为完成 |
.trellis/spec/cli/unit-test/conventions.md | Test Isolation 模式 —— 在 vitest setup 里清掉 host shell 的 session env vars |
Upgrade
存量项目：
本次 beta 不需要加 --migrate flag。
