docs: draft v0.2.0 release notes

docs/releases/v0.2.0.md

@@ -0,0 +1,184 @@
+# HALF v0.2.0 Release Notes
+
+Release date: 2026-04-27
+
+## English
+
+`v0.2.0` focuses on first-run onboarding. Compared with `v0.1.0`, this release
+makes a fresh HALF deployment immediately explorable: a built-in demo project is
+seeded by default, Quick Start documentation has been verified from a clean
+environment, and README screenshots now show the main product surfaces.
+
+This remains a `v0.x` self-hosted evaluation release. HALF is still a
+human-in-the-loop coordination console, not an automated agent runner.
+
+### What's New
+
+- **Built-in demo project.** Fresh deployments now create a browsable demo
+  project, `(Demo) 修复一个bug`, using the public repository
+  `https://github.com/keting/half.git` and collaboration directory
+  `demo/half-demo-collaboration`.
+- **Demo workflow seed data.** The demo includes one final plan, five tasks, one
+  completed task output, two ready tasks, and two dependency-blocked downstream
+  tasks so users can inspect the project board, DAG, task queue, and handoff
+  prompts without creating their own project first.
+- **Demo agents and process template.** Fresh demo-enabled deployments seed the
+  three demo agent types used by the sample workflow: `claude-max`,
+  `chatgpt-pro`, and `copilot-pro`, plus a reusable process template.
+- **Demo seed control.** Operators can disable demo data before first startup by
+  setting `HALF_DEMO_SEED_ENABLED=false`.
+- **Cleaner demo agent settings.** Demo-enabled fresh deployments now show only
+  the demo-related agent catalog in `/agents/settings`, avoiding unrelated
+  legacy defaults in the first-run experience.
+- **Current default agent catalog.** Fresh deployments that disable demo seed
+  still start with the current `claude-max`, `chatgpt-pro`, and `copilot-pro`
+  agent type catalog instead of the older `claude`, `codex`, `cursor`, and
+  `windsurf` defaults.
+- **Verified Quick Start guide.** `docs/quickstart.md` was added and README
+  links now point first-time users through setup, login, demo exploration,
+  project creation, plan generation, and common troubleshooting.
+- **README screenshots.** README and README.zh-CN now include compact product
+  previews for the demo DAG, available agents, agent settings, and the project
+  board.
+
+### Fixes and Behavioral Polish
+
+- Project-level predecessor readiness now reports blocked tasks consistently, so
+  downstream tasks such as `T4_EVAL` and `T5_SYNC` are not shown as ready before
+  their required predecessor outputs exist.
+- The single-task predecessor diagnostic endpoint was aligned with the
+  project-level readiness semantics.
+- Demo task output field names and result paths were polished for clearer sample
+  data.
+- The Docker Compose deployment path now passes `HALF_DEMO_SEED_ENABLED` into
+  the backend container.
+- Fresh deployments that set `HALF_DEMO_SEED_ENABLED=false` no longer expose the
+  legacy default agent type catalog in `/agents/settings`.
+
+### Upgrade and Deployment Notes
+
+- Existing deployments are not expected to receive demo seed data retroactively.
+  The demo seed path is intended for fresh databases.
+- `HALF_ADMIN_PASSWORD` must be set in `.env` before the first deployment. The
+  initial login user is `admin`, and the password is the value of
+  `HALF_ADMIN_PASSWORD`.
+- To start without the built-in demo project, set
+  `HALF_DEMO_SEED_ENABLED=false` before the first `docker compose up`.
+- For real workflows, use a repository that the operator can write to, such as
+  a personal repository or fork. The built-in demo repository is public and
+  intended for browsing the product shape.
+
+### Not Included in v0.2.0
+
+- The README 30-60 second minimal-loop GIF is intentionally not included in this
+  release. It is tracked separately in #39.
+- `release/roadmap-to-main` is not included because the roadmap content is not
+  finalized.
+
+### Validation Status
+
+Validated on 2026-04-27 against latest `main` after #42:
+
+- `HALF_DEMO_SEED_ENABLED=false` fresh deployment starts successfully.
+- Demo data remains disabled: no projects, demo agents, tasks, or process
+  templates are created.
+- The default agent catalog contains only `claude-max`, `chatgpt-pro`, and
+  `copilot-pro`.
+- Legacy defaults `claude`, `codex`, `cursor`, and `windsurf` are not present.
+- Restarting the backend does not duplicate agent type or model mappings.
+
+One validation host had an unrelated local port conflict on `localhost:8000`,
+so the backend host port was temporarily mapped to `18000:8000`; container
+behavior and frontend access were otherwise unchanged.
+
+### Related Work
+
+- Demo project seed: #29 / #36
+- Demo agent settings cleanup: #37
+- Default agent catalog cleanup: #42
+- Clean Quick Start guide: #27 / #38
+- README screenshots: #26 / #40
+- Deferred README GIF: #39
+
+## 简体中文
+
+`v0.2.0` 的重点是首次启动体验。相比 `v0.1.0`，这个版本让全新部署后的
+HALF 可以立即被浏览和理解：系统默认创建内置 Demo 项目，Quick Start 文档
+已经经过干净环境验证，README 也补充了主要产品界面的截图预览。
+
+HALF 仍然处于 `v0.x` 自托管评估阶段。它仍是 human-in-the-loop 的协作控制
+台，不是自动执行 agent 的 runner。
+
+### 新增内容
+
+- **内置 Demo 项目。** 全新部署默认创建可浏览的 Demo 项目
+  `(Demo) 修复一个bug`，使用公开仓库 `https://github.com/keting/half.git`
+  和协作目录 `demo/half-demo-collaboration`。
+- **Demo 流程种子数据。** Demo 包含 1 个 final plan、5 个任务、1 个已完成
+  任务产物、2 个 ready 任务，以及 2 个因上游输出缺失而 blocked 的下游任
+  务。用户无需先创建自己的项目，就可以查看项目看板、DAG、任务队列和
+  handoff prompt。
+- **Demo agents 与流程模板。** 启用 demo seed 的全新部署会创建示例流程中
+  使用的 3 类 demo agent：`claude-max`、`chatgpt-pro`、`copilot-pro`，以及
+  一个可复用流程模板。
+- **Demo seed 开关。** 如果不希望首次启动时创建内置 Demo 数据，可以在首
+  次启动前设置 `HALF_DEMO_SEED_ENABLED=false`。
+- **更干净的 demo agent 设置页。** 启用 demo seed 的全新部署中，
+  `/agents/settings` 只显示 demo 相关 agent catalog，避免首次体验中出现无
+  关 legacy 默认项。
+- **当前默认 agent catalog。** 即使全新部署关闭 demo seed，系统也会使用
+  当前的 `claude-max`、`chatgpt-pro`、`copilot-pro` agent type catalog，而
+  不是旧的 `claude`、`codex`、`cursor`、`windsurf` 默认项。
+- **经过验证的 Quick Start。** 新增 `docs/quickstart.md`，README 会引导首
+  次用户完成部署、登录、浏览 Demo、创建项目、生成 Plan 和常见故障排除。
+- **README 截图。** README 和 README.zh-CN 现在包含紧凑的产品预览，覆盖
+  Demo DAG、可用 agents、agent 设置和项目看板。
+
+### 修复与体验打磨
+
+- 项目级前置任务状态现在会一致地报告 blocked 任务，避免 `T4_EVAL` 和
+  `T5_SYNC` 在上游输出缺失时被误显示为 ready。
+- 单任务前置状态诊断接口已与项目级 ready/blocked 语义对齐。
+- Demo 任务输出字段和结果路径经过整理，示例数据更清晰。
+- Docker Compose 部署路径现在会把 `HALF_DEMO_SEED_ENABLED` 传入后端容器。
+- 设置 `HALF_DEMO_SEED_ENABLED=false` 的全新部署不再在 `/agents/settings`
+  中暴露 legacy 默认 agent type catalog。
+
+### 升级与部署说明
+
+- 已有部署通常不会被 retroactively 写入 Demo seed 数据。Demo seed 主要面
+  向全新数据库的首次启动体验。
+- `HALF_ADMIN_PASSWORD` 必须在第一次部署前写入 `.env`。初始登录用户名为
+  `admin`，密码就是 `HALF_ADMIN_PASSWORD` 的值。
+- 如果希望首次启动时不创建内置 Demo 项目，请在第一次 `docker compose up`
+  前设置 `HALF_DEMO_SEED_ENABLED=false`。
+- 实际运行自己的流程时，请使用操作者有写权限的仓库，例如个人仓库或 fork。
+  内置 Demo 仓库是公开仓库，主要用于浏览产品形态。
+
+### 不纳入 v0.2.0
+
+- README 30-60 秒最小闭环 GIF 不纳入本次发布，已拆到 #39 单独跟踪。
+- `release/roadmap-to-main` 不纳入本次发布，因为 ROADMAP 内容尚未定稿。
+
+### 验证状态
+
+已在 2026-04-27 基于 #42 合并后的最新 `main` 完成验证：
+
+- `HALF_DEMO_SEED_ENABLED=false` 的全新部署可以正常启动。
+- Demo 数据保持关闭：不会创建 projects、demo agents、tasks 或 process
+  templates。
+- 默认 agent catalog 只包含 `claude-max`、`chatgpt-pro`、`copilot-pro`。
+- legacy 默认项 `claude`、`codex`、`cursor`、`windsurf` 均不存在。
+- 重启 backend 后不会重复创建 agent type 或 model mapping。
+
+其中一台验证宿主机存在无关的 `localhost:8000` 端口占用，因此临时将 backend
+宿主端口映射为 `18000:8000`；容器内行为和前端访问路径不受影响。
+
+### 相关工作
+
+- Demo project seed：#29 / #36
+- Demo agent settings 清理：#37
+- 默认 agent catalog 清理：#42
+- 干净环境 Quick Start：#27 / #38
+- README 截图：#26 / #40
+- 后续 README GIF：#39