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

# v0.5.0-beta.16

> 2026-04-28

beta.16 是 beta.15 之后的 template hash 可移植性、task archive 参数和 Claude Code statusLine 升级兼容补丁。

## Bug Fixes

### Template hash portability

template hash 存储现在使用 POSIX path key，并在计算 hash 前把内容归一化为 LF。

`.trellis/.template-hashes.json` 现在使用带版本的 envelope：

```json theme={null}
{
  "__version": 2,
  "hashes": {
    ".trellis/scripts/task.py": "<sha256>"
  }
}
```

| 范围                     | beta.16 行为                                       |
| ---------------------- | ------------------------------------------------ |
| Hash key               | 所有宿主都用 `/` 分隔符存储                                 |
| Hash input             | SHA256 前先把 CRLF 内容归一化为 LF                        |
| 旧 flat hash 文件         | 丢弃，并从已安装 template 重新生成                           |
| Directory safety check | `path.relative()` 输出先归一化，再做 template/hash lookup |
| OpenCode template      | collector 用 POSIX 形式存储 `.opencode/*` key         |

这修复了 Windows checkout 场景：backslash hash key 或 CRLF line ending 会让未修改 template 被误判为 modified。

### `task.py archive` input contract

`task.py archive` 现在接受和其他 task-directory 命令一致的 task 输入。

| 输入形式               | 示例                                                                            |
| ------------------ | ----------------------------------------------------------------------------- |
| Bare task name     | `python3 .trellis/scripts/task.py archive 04-27-example`                      |
| Relative task path | `python3 .trellis/scripts/task.py archive .trellis/tasks/04-27-example`       |
| Absolute task path | `python3 .trellis/scripts/task.py archive /repo/.trellis/tasks/04-27-example` |

之前 `archive` 是唯一一个只用 slug lookup 的 dir-style task command。传入 `.trellis/tasks/<slug>` 会报 `Task not found`，但其他 task 命令接受这种形式。

### 已安装的 Claude Code statusLine 会保留

beta.15 开始，新项目默认不再安装 Claude Code `statusLine`。这个默认行为不变。

升级路径现在更保守：

| 场景                                            | beta.16 行为                                                                           |
| --------------------------------------------- | ------------------------------------------------------------------------------------ |
| 新项目                                           | Trellis 不创建 `.claude/hooks/statusline.py`，也不在 `.claude/settings.json` 写 `statusLine` |
| 已有项目存在 `.claude/hooks/statusline.py`          | `trellis update` 保留这个文件                                                              |
| 已有项目的 `.claude/settings.json` 里有 `statusLine` | `trellis update` 会把这段配置带到更新后的 settings 文件里                                           |

也就是说，beta.16 不再把 Claude Code statusLine 当成 cleanup 目标。如果用户不再需要它，可以手动删除文件和 settings entry。

### Shared-hook cleanup 仍适用于其他平台的孤立文件

非 Claude 平台的 `statusline.py` 清理项仍然保留，并且仍是 hash-verified safe delete。那些平台没有 `statusLine` event，所以这些文件不会被调用：

* `.cursor/hooks/statusline.py`
* `.codex/hooks/statusline.py`
* `.gemini/hooks/statusline.py`
* `.qoder/hooks/statusline.py`
* `.github/copilot/hooks/statusline.py`
* `.codebuddy/hooks/statusline.py`
* `.factory/hooks/statusline.py`
* `.kiro/hooks/statusline.py`

## Upgrade

已有项目：

```bash theme={null}
trellis update
```

这个补丁不需要 `--migrate`。