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

> 2026-04-23

beta.12 的补丁跟进。`task.py start` 现在会把 `task.json` 的 status 从 `planning` 真正切到 `in_progress`，之前只改了 `.current-task` 指针，status 字段未修复，导致 cc 的 status line 会一直显示 `planning`。

## Bug Fixes

### `task.py start` 会把 `task.json` 状态切到 `in_progress`

原 `cmd_start` 写入 `.current-task` 并触发 `after_start` hook 后即返回，未修改 `task.json` 的 `status` 字段。该字段只由 `create`（写入 `planning`）和 `archive`（写入 `completed`）维护，没有任何路径写入 `in_progress`。因此进入实际开发的 task 在 `list --status in_progress` 中不可见，session-start 面包屑也持续显示 `Status: PLANNING`。

修复后，`cmd_start` 在写入 `.current-task` 之后读取 `task.json`，仅当 `status == "planning"` 时改写为 `in_progress`，其他状态保留：

| 当前 status     | `task.py start` 之后             |
| ------------- | ------------------------------ |
| `planning`    | `in_progress`                  |
| `in_progress` | `in_progress`（幂等）              |
| `review`      | `review`（保留；review 返工重启不应清零状态） |
| `completed`   | `completed`（保留）                |

代码位置：`packages/cli/src/templates/trellis/scripts/task.py:cmd_start`。

### Codex agent 模板回填 Phase 1.3 fallback 段

beta.11 的 init-context-removal 在两个 Codex agent 文件开头新增了 "Required: Load Trellis Context First" 段，指示 sub-agent 跳过 `{"_example": ...}` seed 行，并在 `implement.jsonl` / `check.jsonl` 无 curated 条目时回退为读取 `prd.md` + 通过 `get_context.py --mode packages` 自行筛选 spec。

该编辑仅写入项目根目录的 dogfood 副本，未同步至 `packages/cli/src/templates/codex/agents/`。截至 beta.12，通过 `trellis init` / `trellis update` 分发的 Codex agent prompt 缺失此段，遇到 seed-only jsonl 时无 fallback 路径，sub-agent 直接阻塞。

本版补齐：

* `packages/cli/src/templates/codex/agents/trellis-check.toml`
* `packages/cli/src/templates/codex/agents/trellis-implement.toml`

回填文本与 `configurators/shared.ts:buildPullBasedPrelude` 为 Copilot / Gemini / Qoder 生成的 prelude 完全一致，Codex 行为与其余 pull-based 平台对齐。

## Docs

### `.codex/config.toml` 文档化 `features.codex_hooks` 开关

Trellis 的 Codex 集成依赖 `.codex/hooks.json` 中声明的 SessionStart 与 UserPromptSubmit hook。Codex 仅在 **user-level** 的 `~/.codex/config.toml` 设置了 `[features] codex_hooks = true` 时加载这些 hook；项目级 `.codex/config.toml` 无法启用 `features.*`。未开启该 flag 时，`hooks.json` 被静默忽略，Trellis 的上下文注入不执行，表现为 Trellis 未生效。

项目级 `.codex/config.toml` 现以注释形式指明：用户需在 `~/.codex/config.toml` 中添加的 TOML 片段及其位置。同时移除了无关的 `shell_environment_policy` 段。

## Upgrade

已有项目：

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

本版无迁移步骤。已有 task、jsonl 文件与 `.current-task` 均保持原样。升级后对仍处于 `planning` 的旧 task 首次执行 `task.py start`，`status` 字段自动写入 `in_progress`。手动修改过 `.codex/agents/trellis-*.toml` 的用户将在 update 阶段看到两个文件的 hash drift 提示，按交互选项处理。

全新安装：

```bash theme={null}
npm i -g @mindfoldhq/trellis@0.5.0-beta.13
```