docs/BE-PR-001-rename-impact.md

@@ -0,0 +1,31 @@
+# BE-PR-001: Propose → Proposal Rename Impact Checklist
+
+## Summary
+Unified all backend Python-level naming from `Propose` to `Proposal`. DB table and column names kept unchanged for backward compatibility (no migration needed).
+
+## Files Changed
+
+### New Files
+- `app/models/proposal.py` — Canonical model: `Proposal`, `ProposalStatus`
+- `app/api/routers/proposals.py` — Canonical router at `/projects/{id}/proposals`
+
+### Modified Files
+- `app/models/propose.py` — Now a backward-compat shim re-exporting from `proposal.py`
+- `app/api/routers/proposes.py` — Now a backward-compat shim delegating to `proposals.py` (legacy `/proposes` URL still works)
+- `app/schemas/schemas.py` — Renamed: `ProposalStatusEnum`, `ProposalBase`, `ProposalCreate`, `ProposalUpdate`, `ProposalResponse` (old names kept as aliases)
+- `app/main.py` — Registers both `proposals_router` (canonical) and `proposes_router` (legacy compat)
+- `app/init_wizard.py` — Updated comments to say "Proposal" (permission names `propose.*` kept for DB compat)
+- `tests/test_propose.py` — Updated all tests to use `/proposals` URL; added legacy endpoint compat tests
+
+## What Was Kept for Backward Compatibility
+| Item | Kept As-Is | Reason |
+|------|-----------|--------|
+| DB table name | `proposes` | Avoid DB migration |
+| DB column | `propose_code` | Avoid DB migration |
+| Permission names | `propose.accept`, `propose.reject`, `propose.reopen` | Already stored in DB |
+| Legacy API path | `/projects/{id}/proposes/*` | Client compat |
+| Python aliases | `Propose`, `ProposeStatus`, `ProposeCreate`, etc. | Import compat |
+
+## API Endpoints
+- **Canonical:** `/projects/{project_id}/proposals` (new)
+- **Legacy:** `/projects/{project_id}/proposes` (still works, delegates to canonical)

docs/proposal-essential-story-migration.md

@@ -0,0 +1,263 @@
+# HarborForge — Proposal / Essential / Story Restricted 迁移说明
+
+> 更新时间：2026-03-29
+> 本文档描述 Propose → Proposal 重命名、Proposal Accept 语义变更、Essential 新增、以及 story/* restricted 的迁移细节与兼容策略。
+
+---
+
+## 一、Propose → Proposal 命名调整
+
+### 1.1 变更范围
+
+| 层 | 旧命名 | 新命名 | 涉及文件 |
+|---|--------|--------|---------|
+| **数据库表** | `proposes` | `proposals`（新表名） | Alembic migration |
+| **Model** | `Propose`, `ProposeStatus` | `Proposal`, `ProposalStatus` | `models/propose.py` → `models/proposal.py` |
+| **Schema** | `ProposeCreate`, `ProposeUpdate`, `ProposeResponse`, `ProposeStatusEnum`, `ProposeBase` | `ProposalCreate`, `ProposalUpdate`, `ProposalResponse`, `ProposalStatusEnum`, `ProposalBase` | `schemas/schemas.py` |
+| **Router** | `proposes.py`, 路由前缀 `/proposes` | `proposals.py`, 路由前缀 `/proposals` | `api/routers/proposes.py` → `api/routers/proposals.py` |
+| **Helper 函数** | `_find_propose()`, `_serialize_propose()`, `_generate_propose_code()`, `_can_edit_propose()` | `_find_proposal()`, `_serialize_proposal()`, `_generate_proposal_code()`, `_can_edit_proposal()` | 同上 router 文件 |
+| **Code 字段** | `propose_code` | `proposal_code` | Model、Schema、序列化逻辑 |
+| **Activity log** | `entity_type="propose"` | `entity_type="proposal"` | `log_activity()` 调用处 |
+| **权限 key** | `propose.accept`, `propose.reject`, `propose.reopen` | `proposal.accept`, `proposal.reject`, `proposal.reopen` | `check_permission()` 调用处、RBAC 数据 |
+| **前端** | 页面标题、菜单、API 调用中的 `propose` 文案 | 统一为 `proposal` | 前端组件、路由、API 调用 |
+| **CLI** | `hf propose`, `hf propose-create`, `hf propose-accept` 等 | `hf proposal`, `hf proposal create`, `hf proposal accept` 等 | CLI 命令注册与 help 文案 |
+
+### 1.2 数据库迁移策略
+
+```sql
+-- Alembic migration
+ALTER TABLE proposes RENAME TO proposals;
+ALTER TABLE proposals CHANGE propose_code proposal_code VARCHAR(64);
+```
+
+- `proposal_code` 的已有编码值（如 `HF:P00001`）不变，仅字段名变更
+- 所有外键引用（如 `proposals.id`）保持不变（表内 PK 不变）
+
+### 1.3 API 兼容策略
+
+**方案：直接切换，不保留旧路由**
+
+理由：
+- HarborForge 目前为内部系统，无外部消费者
+- CLI 和前端同步更新，不存在旧客户端兼容问题
+- 保留兼容别名会增加长期维护负担
+
+具体做法：
+1. 后端路由从 `/projects/{pid}/proposes` 切换为 `/projects/{pid}/proposals`
+2. 前端所有 API 调用同步更新
+3. CLI 命令同步更新
+4. **不保留** `/proposes` 旧路由
+
+> 如果未来需要面向外部提供 API，应在 API 版本化层面处理兼容，而非在路由别名层面。
+
+---
+
+## 二、Proposal Accept 语义变化
+
+### 2.1 旧行为
+
+```
+Proposal (open) ──accept──▶ Proposal (accepted)
+                                │
+                                ▼
+                         单个 story/feature Task
+                         feat_task_id 回填到 Proposal
+```
+
+- Accept 时自动创建 **1 个** `story/feature` task
+- `feat_task_id` 字段记录生成的 task ID
+
+### 2.2 新行为
+
+```
+Proposal (open)
+   ├── Essential (feature)   ──┐
+   ├── Essential (improvement) ─┤── accept ──▶ Proposal (accepted)
+   └── Essential (refactor)  ──┘                    │
+                                                    ▼
+                                        story/feature Task   ← from Essential(feature)
+                                        story/improvement Task ← from Essential(improvement)
+                                        story/refactor Task  ← from Essential(refactor)
+                                        全部落入选定 Milestone
+```
+
+- Proposal 下维护多个 **Essential**（可落地核心条目）
+- Accept 时，遍历该 Proposal 下全部 Essential
+- 按 Essential.type 映射生成对应 `story/*` task：
+  - `feature` → `story/feature`
+  - `improvement` → `story/improvement`
+  - `refactor` → `story/refactor`
+- 生成目标 Milestone 在 Accept 时明确选择（与旧行为一致）
+- **批量创建在同一个数据库事务中完成**
+
+### 2.3 Accept 前置条件变更
+
+| 条件 | 旧 | 新 |
+|------|----|----|
+| 操作者权限 | `propose.accept` | `proposal.accept` |
+| 目标 Milestone | 必须选择，状态 `open` | 同上 |
+| Essential 数量 | 无此概念 | **必须至少 1 个 Essential**，否则 Accept 报错 |
+
+### 2.4 Accept 返回值变更
+
+- 旧：返回 Proposal 详情（含 `feat_task_id`）
+- 新：返回 Proposal 详情 + 嵌套的 Essential 列表 + 每个 Essential 生成的 task 信息
+
+---
+
+## 三、story/* 改为 Restricted 的影响面
+
+### 3.1 当前状态
+
+后端 `tasks.py` 中已有 restricted 机制：
+
+```python
+RESTRICTED_TYPE_SUBTYPES = {
+    ("story", "feature"),
+}
+```
+
+目前仅 `story/feature` 是 restricted。
+
+### 3.2 变更内容
+
+将 **所有 `story/*` 组合** 标记为 restricted：
+
+```python
+RESTRICTED_TYPE_SUBTYPES = {
+    ("story", "feature"),
+    ("story", "improvement"),
+    ("story", "refactor"),
+}
+```
+
+### 3.3 影响面
+
+| 入口 | 影响 | 处理 |
+|------|------|------|
+| **通用 Task Create API** (`POST /projects/{pid}/milestones/{mid}/tasks`) | 无法创建任何 `story/*` task | 已有 `_validate_task_type_subtype()` 校验，扩展 restricted 集合即可 |
+| **Proposal Accept** | 内部受控入口，`allow_restricted=True` | 保留，唯一合法创建 `story/*` 的途径 |
+| **前端 Task 创建表单** | `story` 类型从选择器中移除或标为不可选 | 前端调整 |
+| **CLI `hf task create`** | 阻止 `--type story` | CLI 侧校验或依赖后端 403 |
+| **CSV 导入**（如有） | 阻止 `story/*` 行 | 导入逻辑需加校验 |
+| **Milestone 下 Task Create** (`milestones.py` 路由) | 已有 `story/feature` 限制逻辑 | 扩展为全部 `story/*` |
+
+### 3.4 已有数据兼容
+
+- 历史上通过旧 Accept 创建的 `story/feature` task **保持不变**
+- 不需要迁移或修改已有 story task
+- restricted 仅影响 **新建**，不影响已有记录的读取/更新/状态流转
+
+---
+
+## 四、旧数据与旧接口兼容策略
+
+### 4.1 `feat_task_id` 字段
+
+| 处理方式 | 说明 |
+|---------|------|
+| **保留字段，标记为 deprecated** | 数据库列保留，避免破坏已有数据 |
+| **只读** | API 继续返回 `feat_task_id`（已有 Proposal 的值不丢失） |
+| **新 Proposal 不再写入** | 新的 Accept 流程不再设置 `feat_task_id` |
+| **新增追踪方式** | 通过 Essential → Task 的关联关系（`essential_id` 或关联表）替代 |
+| **未来清理** | 等所有旧 Proposal 迁移完毕后，可选择 DROP 该列 |
+
+### 4.2 旧 Proposal 数据读取
+
+- 旧的 `accepted` 状态 Proposal 仍有 `feat_task_id`，前端继续支持 "View Generated Task" 跳转
+- 旧 Proposal 没有 Essential，详情页 Essential 区域显示空列表
+- 不需要为旧 Proposal 补建 Essential 记录
+
+### 4.3 Proposal Code 格式
+
+- 已有编码如 `HF:P00001` 保持不变
+- 新 Proposal 继续使用相同格式
+- 字段名从 `propose_code` 变为 `proposal_code`，但值的格式不变
+
+### 4.4 权限 Key 迁移
+
+| 旧 | 新 | 迁移方式 |
+|----|----|----|
+| `propose.accept` | `proposal.accept` | 数据库中更新 RBAC permission 记录 |
+| `propose.reject` | `proposal.reject` | 同上 |
+| `propose.reopen` | `proposal.reopen` | 同上 |
+
+```sql
+-- RBAC permission key migration
+UPDATE permissions SET key = REPLACE(key, 'propose.', 'proposal.') WHERE key LIKE 'propose.%';
+```
+
+> 如果权限 key 存储在 code 中而非数据库，则只需修改代码常量。
+
+### 4.5 Activity Log 兼容
+
+- 旧 activity log 中 `entity_type="propose"` 的记录保留不动
+- 前端展示时做兼容映射：`propose` → 显示为 "Proposal"
+- 新 activity log 统一使用 `entity_type="proposal"`
+
+---
+
+## 五、Essential 新增概要
+
+### 5.1 数据模型
+
+```
+Essential
+├── id (PK)
+├── essential_code (UNIQUE) — 格式参考 ProjectCode / TaskCode
+├── proposal_id (FK → proposals.id)
+├── type (Enum: feature, improvement, refactor)
+├── title
+├── description (nullable)
+├── created_by_id (FK → users.id, nullable)
+├── created_at
+└── updated_at
+```
+
+### 5.2 EssentialCode 编码
+
+- 格式：`{proposal_code}:E{i:05x}`
+- 示例：`HF:P00001:E00001`
+- 每个 Proposal 独立递增
+
+### 5.3 Essential 生命周期
+
+1. Proposal `open` 状态下可创建/编辑/删除 Essential
+2. Proposal Accept 时，全部 Essential 用于生成 `story/*` task
+3. Proposal 进入 `accepted`/`rejected` 后，Essential 不可修改
+
+### 5.4 API 端点
+
+| 操作 | 方法 | 路径 |
+|------|------|------|
+| 列出 | GET | `/projects/{pid}/proposals/{proposal_id}/essentials` |
+| 创建 | POST | `/projects/{pid}/proposals/{proposal_id}/essentials` |
+| 详情 | GET | `/projects/{pid}/proposals/{proposal_id}/essentials/{id}` |
+| 编辑 | PATCH | `/projects/{pid}/proposals/{proposal_id}/essentials/{id}` |
+| 删除 | DELETE | `/projects/{pid}/proposals/{proposal_id}/essentials/{id}` |
+
+---
+
+## 六、迁移执行顺序
+
+推荐按以下顺序执行，确保每一步可独立验证：
+
+1. **后端 Model/Schema 重命名** — `Propose` → `Proposal`（BE-PR-001, BE-PR-002）
+2. **数据库 migration** — 表名、字段名变更
+3. **新增 Essential Model/Schema** — （BE-PR-003, BE-PR-004, BE-PR-005）
+4. **新增 Essential CRUD API** — （BE-PR-006）
+5. **重构 Accept 逻辑** — （BE-PR-007, BE-PR-008）
+6. **收紧 story restricted** — （BE-PR-009）
+7. **清理 feat_task_id** — （BE-PR-010）
+8. **前端同步更新** — （FE-PR-001 ~ FE-PR-005）
+9. **CLI 同步更新** — （CLI-PR-001 ~ CLI-PR-004）
+10. **测试补全** — （BE-PR-011, TEST-BE-PR-001, TEST-FE-PR-001, TEST-CLI-PR-001）
+
+---
+
+## 七、风险与注意事项
+
+1. **表重命名的 downtime** — `ALTER TABLE RENAME` 在 MySQL 中是瞬时操作，但需确保无长事务锁表
+2. **权限 key 更新** — 如果有缓存层，需要在迁移后清理缓存
+3. **前后端同步部署** — 建议同时部署前后端，避免前端调旧路由 404
+4. **回滚方案** — 如需回滚，反向执行表重命名和字段重命名即可；Essential 表作为新增表，回滚时 DROP 即可

docs/wave-2026-03-scope.md

@@ -0,0 +1,106 @@
+# 本波开发范围说明
+
+> Date: 2026-03-29
+> Wave: 2026-03 (Calendar & Proposal 重构)
+
+---
+
+## 一、两条功能线概述
+
+本波开发包含两条独立的功能线：
+
+### 功能线 1：Calendar 日程系统（独立功能线）
+
+全新功能模块，为 HarborForge 增加日程调度能力。
+
+**包含内容：**
+- `TimeSlot` 日程槽模型与 CRUD API
+- `SchedulePlan` 周期性计划模型与管理 API
+- Agent 状态管理（Idle / Busy / OnCall / Exhausted / Offline）
+- `MinimumWorkload` 最小工作量配置
+- Plan 虚拟 slot 标识与物化策略
+- Overlap 校验与 Workload warning 规则
+- 不可变过去 slot 规则
+- Agent 心跳唤醒机制与 Exhausted 恢复
+- 前端 Calendar 页面
+- CLI `hf calendar` 命令组
+- OpenClaw 插件 Calendar 心跳联动
+
+### 功能线 2：Proposal / Essential / Story restricted（项目结构调整线）
+
+对已有的 Propose 流程进行重构和增强。
+
+**包含内容：**
+- `Propose` → `Proposal` 统一重命名
+- 新增 `Essential` 概念及数据模型
+- `EssentialCode` 编码规则
+- Proposal Accept 语义变更：遍历 Essential 批量生成 story task
+- `story/*` 整个大类设为 restricted，仅允许通过 Proposal Accept 创建
+- 清理旧 `feat_task_id` 语义
+- 前端 Proposal 详情页 Essential 管理
+- CLI Proposal Essential 子命令
+
+---
+
+## 二、两条线的交叉点
+
+两条功能线设计上相互独立，交叉点仅限于以下层面：
+
+| 交叉点 | 说明 |
+|--------|------|
+| `event_data` | Calendar 的 TimeSlot 通过 `event_data` JSON 字段引用 Task/Essential code，但不直接依赖 Proposal/Essential 的数据模型 |
+| Agent 调度引用层 | Calendar 心跳唤醒 Agent 执行任务时，任务可能是 story task（由 Proposal Accept 生成），但 Calendar 只关心 task code，不关心其来源 |
+
+**关键原则：**
+- Calendar 不直接 FK 到 Essential 或 Proposal 表
+- Proposal/Essential 不直接 FK 到 TimeSlot 或 SchedulePlan 表
+- 两者通过 code 引用（字符串）松耦合
+- 可以独立开发、独立测试、独立部署
+
+---
+
+## 三、本波必须完成 vs 仅设计保留
+
+### ✅ 必须本波完成
+
+#### Calendar 线
+
+| 范围 | 任务 ID 区间 | 说明 |
+|------|-------------|------|
+| 后端基础模型 | BE-CAL-001 ~ BE-CAL-008 | TimeSlot、SchedulePlan、Agent 扩展、MinimumWorkload、物化策略、overlap/warning/不可变规则 |
+| 后端 API | BE-CAL-API-001 ~ BE-CAL-API-007 | 日程 CRUD、计划 CRUD、date-list |
+| 后端 Agent 协作 | BE-AGT-001 ~ BE-AGT-004 | 心跳查询、状态流转、多 slot 竞争、Exhausted 恢复 |
+| 前端 | FE-CAL-001 ~ FE-CAL-005 | 页面骨架、slot 列表、计划列表、CRUD 交互、状态提示 |
+| CLI | CLI-CAL-001 ~ CLI-CAL-010 | `hf calendar` 全部子命令 |
+| 插件 | PLG-CAL-001 ~ PLG-CAL-004 | 心跳格式、唤醒处理、Deferred 分支、ScheduledGatewayRestart |
+
+#### Proposal 线
+
+| 范围 | 任务 ID 区间 | 说明 |
+|------|-------------|------|
+| 后端 | BE-PR-001 ~ BE-PR-011 | 重命名、Essential 模型/schema/API、Accept 重构、story restricted、测试 |
+| 前端 | FE-PR-001 ~ FE-PR-005 | 重命名、Essential 列表/表单、Accept milestone 选择、story 限制 |
+| CLI | CLI-PR-001 ~ CLI-PR-004 | 重命名、Essential 命令、Accept 更新、story 限制 |
+
+#### 文档与测试
+
+| 范围 | 任务 ID 区间 | 说明 |
+|------|-------------|------|
+| 文档 | DOC-001 ~ DOC-003 | 范围说明、迁移说明、验收清单 |
+| 测试 | TEST-* | 各子模块测试补充 |
+
+### 📐 仅设计保留（不在本波实现）
+
+| 内容 | 说明 |
+|------|------|
+| Entertainment 事件子类型 | `event_data` 中 Entertainment 的具体结构待设计 |
+| 用户级时区支持 | 本波统一使用服务器时区 |
+| 前端日程表详细 UI 设计 | 本波实现基础功能骨架，精细 UI 留后续迭代 |
+| Agent 唤醒的提示词模板 | 本波实现唤醒机制，提示词模板留后续打磨 |
+| Proposal/Essential 数据迁移工具 | 旧数据兼容读取即可，自动化迁移工具留后续 |
+
+---
+
+## 四、Bug Fix（附带修复）
+
+- **acc-mgr 密码修改限制**：后端禁止修改 acc-mgr 用户密码；前端隐藏修改密码入口

plans/CALENDAR_ACCEPTANCE_CHECKLIST.md

@@ -0,0 +1,169 @@
+# Calendar 验收清单
+
+> 基于 `NEXT_WAVE_DEV_DIRECTION.md` 设计文档整理
+> Date: 2026-03-29
+
+---
+
+## 一、后端验收项 (Backend)
+
+### 1.1 数据模型
+
+- [ ] `TimeSlot` 模型已创建，字段完整（slot_id, user_id, date, slot_type, estimated_duration, scheduled_at, started_at, attended, actual_duration, event_type, event_data, priority, status, plan_id, created_at, updated_at）
+- [ ] `SchedulePlan` 模型已创建，字段完整（id, user_id, slot_type, estimated_duration, event_type, event_data, at_time, on_day, on_week, on_month, created_at, updated_at）
+- [ ] Agent 表已扩展字段：status, last_heartbeat, exhausted_at, recovery_at, exhaust_reason
+- [ ] 枚举类型已定义：SlotType (Work, OnCall, Entertainment, System)、SlotStatus (NotStarted, Ongoing, Deferred, Skipped, Paused, Finished, Aborted)、EventType (Job, Entertainment, SystemEvent)、AgentStatus (Idle, OnCall, Busy, Exhausted, Offline)、ExhaustReason (RateLimit, Billing)
+- [ ] SchedulePlan 周期参数层级约束已实现（on_month 需 on_week，on_week 需 on_day，at 始终必填）
+- [ ] MinimumWorkload 存储方案已实现（用户级配置读写）
+
+### 1.2 Slot ID 策略与物化
+
+- [ ] 已物化 slot 使用数据库自增 ID
+- [ ] Plan 虚拟 slot 使用 `plan-{plan_id}-{date}` 标识
+- [ ] 虚拟 slot 被 edit/cancel 时物化到数据库，断开 plan 关联
+- [ ] Plan 不预展开，只存规则
+
+### 1.3 验证规则
+
+- [ ] Overlap 检测：同日时间重叠 → 拒绝并报错
+- [ ] Overlap 检测区分 create 与 edit 场景
+- [ ] MinimumWorkload warning：不满足时返回 warning 但允许提交
+- [ ] Warning 数据结构统一定义
+- [ ] 计算 daily / weekly / monthly / yearly 工作量
+
+### 1.4 不可变性规则
+
+- [ ] 禁止 edit 过去的 slot
+- [ ] 禁止 cancel 过去的 slot
+- [ ] plan-edit / plan-cancel 不追溯过去已物化 slot
+
+### 1.5 Calendar API
+
+- [ ] `POST` 单次日程创建：支持 slot_type, scheduled_at, estimated_duration, job/system/event_data，接入 overlap 与 workload warning
+- [ ] `GET` 某日 Calendar 查询：返回真实 slot + 合成当日 plan 虚拟 slot，统一排序
+- [ ] `PATCH/PUT` Calendar 编辑：支持真实 slot 编辑 + 虚拟 slot 编辑并触发物化
+- [ ] `DELETE/POST` Calendar 取消：支持真实 slot cancel + 虚拟 slot cancel 并触发物化，状态字段更新
+- [ ] `POST` plan-schedule：创建周期性计划
+- [ ] `GET` plan-list：列出所有计划
+- [ ] `PATCH/PUT` plan-edit：编辑计划，不追溯过去已物化数据
+- [ ] `POST/DELETE` plan-cancel：取消计划，不追溯过去已物化数据
+- [ ] `GET` date-list：仅列出有已物化未来 slot 的日期，排除纯 plan 未物化日期
+
+### 1.6 Agent / 心跳协作
+
+- [ ] 心跳查询服务：筛选当天 NotStarted / Deferred 且 scheduled_at 已过的 slot，按优先级排序
+- [ ] Agent 状态流转：Idle ↔ Busy/OnCall、超时→Offline、API错误→Exhausted
+- [ ] 多 slot 竞争：选最高 priority 执行，其余 Deferred，Deferred slot priority += 1
+- [ ] Exhausted 恢复时间解析：解析 retry-after / reset in / resets at，失败默认 5 小时，到期恢复 Idle
+
+---
+
+## 二、前端验收项 (Frontend)
+
+### 2.1 页面骨架
+
+- [ ] Calendar 路由入口已添加
+- [ ] 侧边栏 Calendar 入口已添加
+- [ ] Calendar 基础页面布局完成
+
+### 2.2 日程展示
+
+- [ ] 某日 slot 列表展示（时间轴或列表视图）
+- [ ] 区分真实 slot 与 plan 虚拟 slot（视觉区分）
+- [ ] 展示 status / type / duration / priority 等核心字段
+
+### 2.3 计划展示
+
+- [ ] 计划列表展示：规则、周期参数
+- [ ] 支持从计划列表跳转编辑
+
+### 2.4 日程操作交互
+
+- [ ] 新建 slot 表单（含 slot_type, scheduled_at, estimated_duration, event_data 等）
+- [ ] 编辑 slot 表单
+- [ ] Cancel 操作确认弹窗
+- [ ] 展示后端返回的 warning（workload 不足等）
+
+### 2.5 状态提示
+
+- [ ] Deferred 状态提示
+- [ ] Overlap 报错展示
+- [ ] Workload warning 展示
+- [ ] Exhausted 状态展示（含预计恢复时间）
+
+### 2.6 权限
+
+- [ ] 普通用户仅查看/调整自己的日程表
+- [ ] Admin 可查看/调整所有用户的日程表
+
+---
+
+## 三、CLI 验收项 (CLI)
+
+### 3.1 命令组
+
+- [ ] `hf calendar` 命令组已注册，help 正常输出
+
+### 3.2 日程操作命令
+
+- [ ] `hf calendar schedule <slot-type> <scheduled-at> <estimated-duration> [--job <code>] [--date <yyyy-mm-dd>]` 正常工作
+- [ ] `hf calendar show [--date <yyyy-mm-dd>]` 正常展示当日日程（真实 + 虚拟 slot 合并）
+- [ ] `hf calendar edit [--date] <slot-id> [--slot-type] [--estimated-duration] [--job] [--scheduled-at]` 正常工作
+- [ ] `hf calendar cancel [--date] <slot-id>` 正常工作
+- [ ] `hf calendar date-list` 列出有已物化日程的未来日期
+
+### 3.3 计划操作命令
+
+- [ ] `hf calendar plan-schedule <slot-type> <estimated-duration> --at <HH:mm> [--on-day] [--on-week] [--on-month]` 正常工作
+- [ ] `hf calendar plan-list` 列出所有计划
+- [ ] `hf calendar plan-edit <plan-id> [options]` 正常工作
+- [ ] `hf calendar plan-cancel <plan-id>` 正常工作
+
+### 3.4 输出格式
+
+- [ ] 所有命令支持 JSON 输出（`--json` 或类似选项）
+- [ ] 错误信息（overlap 等）清晰明确
+- [ ] Warning 信息（workload 不足等）正常展示
+
+### 3.5 用户创建扩展
+
+- [ ] `hf user create` 支持 `--agent-id` + `--claw-identifier` 参数
+- [ ] 两参数必须同时出现或同时不出现
+- [ ] pcexec 模式下自动从环境变量 / openclaw config 获取
+
+---
+
+## 四、插件联动验收项 (OpenclawPlugin)
+
+### 4.1 心跳请求
+
+- [ ] 插件每分钟向 HarborForge 发送心跳
+- [ ] 心跳请求正确传递 claw_identifier 和 agent_id
+- [ ] 正确接收返回的 slot 列表
+
+### 4.2 唤醒逻辑
+
+- [ ] Agent Idle 时：唤醒 agent，透传任务上下文，更新 attended/started_at/status
+- [ ] Agent 非 Idle 时：上报 Deferred
+- [ ] 多 slot 竞争时正确选择最高 priority
+
+### 4.3 状态管理
+
+- [ ] 超过 2 分钟无心跳 → Agent 标记 Offline
+- [ ] API rate-limit / billing 错误 → Agent 标记 Exhausted
+- [ ] Exhausted 恢复计时器到期 → Agent 恢复 Idle
+
+### 4.4 ScheduledGatewayRestart 处理
+
+- [ ] 收到 ScheduledGatewayRestart 事件后持久化状态
+- [ ] 发送最终心跳
+- [ ] 暂停定时任务
+
+---
+
+## 五、跨模块集成验收
+
+- [ ] 完整流程：创建 plan → 心跳触发物化 → Agent 被唤醒执行 → slot 状态更新为 Finished
+- [ ] 完整流程：schedule 单次日程 → CLI 查看 → 前端查看 → Agent 执行
+- [ ] Overlap / Warning 全链路：后端检测 → CLI 展示 → 前端展示
+- [ ] Exhausted 全链路：Agent 报错 → 后端标记 Exhausted → 前端展示 → 恢复后自动 Idle

plans/TASKLIST.md

@@ -1,379 +1,380 @@
 # TASKLIST.md
 
-> 说明：如果某个进行中的 Task 没有完全完成，或者在执行过程中遇到 block，需要在该 Task 下继续拆分若干子 TODO item：本次开发中已经完成的部分标记为已完成，block / pending / 尚未完成的部分标记为未完成。
+> 说明:如果某个进行中的 Task 没有完全完成,或者在执行过程中遇到 block,需要在该 Task 下继续拆分若干子 TODO item:本次开发中已经完成的部分标记为已完成,block / pending / 尚未完成的部分标记为未完成。
 >
-> 拆分原则：尽量保证 Task 之间相互独立；每个 Task 最好只改动一个子模块（如 `HarborForge.Backend` / `HarborForge.Frontend` / `HarborForge.Cli` / `HarborForge.OpenclawPlugin` / 根目录文档），避免一次任务同时横跨多个子模块。只有在确实无法避免时，才建立跨模块 Task。
+> 拆分原则:尽量保证 Task 之间相互独立;每个 Task 最好只改动一个子模块(如 `HarborForge.Backend` / `HarborForge.Frontend` / `HarborForge.Cli` / `HarborForge.OpenclawPlugin` / 根目录文档),避免一次任务同时横跨多个子模块。只有在确实无法避免时,才建立跨模块 Task。
 
 ---
 
 # TODOLIST
 
-## A. Root / Docs（根目录与规划文档）
-
-- [ ] DOC-001：整理本波开发范围说明（root docs only）
-  - [ ] 明确 Calendar 属于独立功能线
-  - [ ] 明确 Proposal / Essential 属于项目结构调整线
-  - [ ] 明确两条线的交叉点仅限 `event_data` / Agent 调度引用层
-  - [ ] 将“必须本波完成”和“仅设计保留”区分写清楚
-
-- [ ] DOC-002：整理 Proposal / Essential / Story restricted 的迁移说明（root docs only）
-  - [ ] 说明 `Propose -> Proposal` 的命名调整
-  - [ ] 说明 `Proposal Accept` 语义变化
-  - [ ] 说明 `story/*` 改为 restricted 的影响面
-  - [ ] 说明旧数据和旧接口的兼容策略
-
-- [ ] DOC-003：整理 Calendar 验收清单（root docs only）
-  - [ ] 列出后端验收项
-  - [ ] 列出前端验收项
-  - [ ] 列出 CLI 验收项
-  - [ ] 列出插件联动验收项
-
-## B. HarborForge.Backend — Proposal / Essential / Story restricted
-
-- [ ] BE-PR-001：后端统一重命名 `Propose` 概念为 `Proposal`（backend only）
-  - [ ] 盘点 `models / schemas / routers / services / tests` 中 `propose` 命名
-  - [ ] 明确保留兼容别名还是直接切换
-  - [ ] 输出重命名影响清单
-
-- [ ] BE-PR-002：新增 Proposal 数据模型调整（backend only）
-  - [ ] 调整 Proposal 模型命名与字段注释
-  - [ ] 确认 Proposal 与 `project_id / created_by_id / feat_task_id` 的后续关系
-  - [ ] 标记 `feat_task_id` 是否废弃或替换
-
-- [ ] BE-PR-003：新增 Essential 模型（backend only）
-  - [ ] 新增 `Essential` SQLAlchemy model
-  - [ ] 增加 `proposal_id` 外键
-  - [ ] 增加 `essential_code`
-  - [ ] 增加 `type / title / description / created_by_id / created_at / updated_at`
-
-- [ ] BE-PR-004：实现 EssentialCode 编码规则（backend only）
-  - [ ] 参考现有 `ProjectCode / MilestoneCode / TaskCode / ProposeCode` 生成方式
-  - [ ] 设计 Essential code 前缀
-  - [ ] 实现唯一编号生成逻辑
-  - [ ] 明确是否需要独立 counter 表
-
-- [ ] BE-PR-005：新增 Essential 的 schema 定义（backend only）
-  - [ ] 新增 create schema
-  - [ ] 新增 update schema
-  - [ ] 新增 response schema
-  - [ ] 新增 Proposal detail 中嵌套 Essential 的返回结构
-
-- [ ] BE-PR-006：新增 Proposal 下 Essential CRUD API（backend only）
-  - [ ] 实现创建 Essential
-  - [ ] 实现编辑 Essential
-  - [ ] 实现删除 Essential
-  - [ ] 实现 Proposal 详情返回 Essential 列表
-
-- [ ] BE-PR-007：重构 Proposal Accept 逻辑（backend only）
-  - [ ] 移除“accept 后生成单个 `story/feature` task”的旧逻辑
-  - [ ] Accept 时要求显式选择目标 Milestone
-  - [ ] 遍历 Proposal 下全部 Essential
-  - [ ] 按 Essential.type 生成对应 `story/*` task
-  - [ ] 保证批量创建在一个事务中完成
-
-- [ ] BE-PR-008：补充 Proposal Accept 追踪字段/关系（backend only）
-  - [ ] 明确 Proposal 与生成 tasks 的映射方式
-  - [ ] 设计是用反查字段、关联表还是事件记录
-  - [ ] 实现最小可用追踪能力
-
-- [ ] BE-PR-009：收紧 Task 类型规则，限制全部 `story/*`（backend only）
-  - [ ] 更新 `TASK_SUBTYPE_MAP` 相关约束
-  - [ ] 将所有 `story/*` 组合标记为 restricted
-  - [ ] 禁止通用 create endpoint 直接创建任何 story
-  - [ ] 保留内部受控入口用于 Proposal Accept
-
-- [ ] BE-PR-010：清理旧的 `feat_task_id` 语义（backend only）
-  - [ ] 判断字段是否保留但废弃
-  - [ ] 如果废弃，给出兼容读取策略
-  - [ ] 如果替换，落地新的字段或关联方式
-
-- [ ] BE-PR-011：补 Proposal / Essential / Story restricted 的后端测试（backend only）
-  - [ ] Essential CRUD 测试
-  - [ ] Proposal Accept 批量生成 story task 测试
-  - [ ] 非受控入口创建 `story/*` 的失败测试
-  - [ ] 兼容旧 proposal 数据的测试
-
-## C. HarborForge.Backend — Calendar 基础模型与规则
-
-- [ ] BE-CAL-001：新增 Calendar 基础模型 `TimeSlot`（backend only）
-  - [ ] 新增表结构
-  - [ ] 定义 slot status / slot type / event type 枚举
-  - [ ] 定义时间字段与时长字段
-  - [ ] 定义 `plan_id` 关联
-
-- [ ] BE-CAL-002：新增 Calendar 基础模型 `SchedulePlan`（backend only）
-  - [ ] 新增表结构
-  - [ ] 定义 `at_time / on_day / on_week / on_month`
-  - [ ] 加入层级参数校验约束
-  - [ ] 处理 user 归属关系
-
-- [ ] BE-CAL-003：新增 Agent 扩展字段（backend only）
-  - [ ] 为 Agent 增加 `status / last_heartbeat`
-  - [ ] 增加 `exhausted_at / recovery_at / exhaust_reason`
-  - [ ] 明确与现有 user / monitor 标识的关系
-
-- [ ] BE-CAL-004：实现 MinimumWorkload 存储方案（backend only）
-  - [ ] 确定 JSON 字段还是独立表
-  - [ ] 实现用户级配置读写
-  - [ ] 提供后续校验调用入口
-
-- [ ] BE-CAL-005：实现 Plan 虚拟 slot 标识与物化策略（backend only）
-  - [ ] 实现 `plan-{plan_id}-{date}` 标识规则
-  - [ ] 实现虚拟 slot 转真实 slot 的物化逻辑
-  - [ ] 实现 edit / cancel 后断开 plan 关联
-
-- [ ] BE-CAL-006：实现 Calendar overlap 校验（backend only）
-  - [ ] 校验同日时间冲突
-  - [ ] 返回明确的冲突错误信息
-  - [ ] 区分 create 与 edit 两种场景
-
-- [ ] BE-CAL-007：实现 MinimumWorkload warning 规则（backend only）
-  - [ ] 计算 daily / weekly / monthly / yearly 工作量
-  - [ ] 不阻止提交，仅返回 warning
-  - [ ] 统一 warning 数据结构
-
-- [ ] BE-CAL-008：实现不可修改过去 slot 的规则（backend only）
-  - [ ] 禁止 edit 过去 slot
-  - [ ] 禁止 cancel 过去 slot
-  - [ ] 保证 plan-edit / plan-cancel 不追溯过去已物化 slot
-
-## D. HarborForge.Backend — Calendar API
-
-- [ ] BE-CAL-API-001：实现单次日程创建 API（backend only）
-  - [ ] 创建 slot
-  - [ ] 支持 job/system/event_data
-  - [ ] 接入 overlap 与 workload warning
-
-- [ ] BE-CAL-API-002：实现某日 Calendar 查询 API（backend only）
-  - [ ] 返回真实 slot
-  - [ ] 合成当日 plan 虚拟 slot
-  - [ ] 输出统一排序结构
-
-- [ ] BE-CAL-API-003：实现 Calendar 编辑 API（backend only）
-  - [ ] 支持真实 slot 编辑
-  - [ ] 支持虚拟 slot 编辑并触发物化
-  - [ ] 返回编辑后的真实结果
-
-- [ ] BE-CAL-API-004：实现 Calendar 取消 API（backend only）
-  - [ ] 支持真实 slot cancel
-  - [ ] 支持虚拟 slot cancel 并触发物化
-  - [ ] 处理状态字段更新
-
-- [ ] BE-CAL-API-005：实现 plan-schedule / plan-list API（backend only）
-  - [ ] 创建计划
-  - [ ] 列出计划
-  - [ ] 返回计划规则字段
-
-- [ ] BE-CAL-API-006：实现 plan-edit / plan-cancel API（backend only）
-  - [ ] 编辑计划
-  - [ ] 取消计划
-  - [ ] 不追溯已物化过去数据
-
-- [ ] BE-CAL-API-007：实现 date-list API（backend only）
-  - [ ] 仅列出有已物化未来 slot 的日期
-  - [ ] 排除纯 plan 未物化日期
-
-## E. HarborForge.Backend — Agent / Plugin Calendar 协作
-
-- [ ] BE-AGT-001：定义心跳查询待执行 slot 的服务层（backend only）
-  - [ ] 筛选当天 `NotStarted / Deferred`
-  - [ ] 仅返回 `scheduled_at` 已过的 slot
-  - [ ] 按优先级排序
-
-- [ ] BE-AGT-002：实现 Agent 状态流转服务（backend only）
-  - [ ] Idle -> Busy / OnCall
-  - [ ] Busy / OnCall -> Idle
-  - [ ] 超时无心跳 -> Offline
-  - [ ] API 配额错误 -> Exhausted
-
-- [ ] BE-AGT-003：实现多 slot 竞争处理（backend only）
-  - [ ] 选最高 priority 执行
-  - [ ] 其余 slot 标记 Deferred
-  - [ ] Deferred slot 自动 priority += 1
-
-- [ ] BE-AGT-004：实现 Exhausted 恢复时间解析（backend only）
-  - [ ] 解析 retry-after / reset in / resets at
-  - [ ] 解析失败时默认 5 小时
-  - [ ] 到期恢复 Idle
-
-## F. HarborForge.Frontend — Proposal / Essential / Story restricted
-
-- [ ] FE-PR-001：前端统一重命名 Propose -> Proposal（frontend only）
-  - [ ] 调整页面标题与菜单文案
-  - [ ] 调整类型名与 API 调用命名
-  - [ ] 清理旧 propose 文案
-
-- [ ] FE-PR-002：Proposal 详情页增加 Essential 列表区（frontend only）
-  - [ ] 展示 Essential 列表
-  - [ ] 展示 Essential type / code / title
-  - [ ] 处理空状态
-
-- [ ] FE-PR-003：新增 Essential 创建/编辑表单（frontend only）
-  - [ ] 创建表单
-  - [ ] 编辑表单
-  - [ ] type 选择器
-  - [ ] 提交后局部刷新
-
-- [ ] FE-PR-004：Proposal Accept 增加目标 Milestone 选择（frontend only）
-  - [ ] Accept 前展示 milestone 选择控件
-  - [ ] 校验必须选择 milestone
-  - [ ] 展示 Accept 成功后的生成结果
-
-- [ ] FE-PR-005：限制前端直接创建 `story/*`（frontend only）
-  - [ ] 从 Task 创建入口移除 story
-  - [ ] 或将 story 整体设为不可选
-  - [ ] 调整相关提示文案
-
-## G. HarborForge.Frontend — Calendar
-
-- [ ] FE-CAL-001：新增 Calendar 页面基础骨架（frontend only）
-  - [ ] 增加路由入口
-  - [ ] 增加侧边栏入口
-  - [ ] 增加基础页面布局
-
-- [ ] FE-CAL-002：实现某日 slot 列表展示（frontend only）
-  - [ ] 展示时间轴或列表
-  - [ ] 区分真实 slot 与 plan 虚拟 slot
-  - [ ] 展示状态 / 类型 / 时长 / 优先级
-
-- [ ] FE-CAL-003：实现计划列表展示（frontend only）
-  - [ ] 展示计划规则
-  - [ ] 展示周期参数
-  - [ ] 支持跳转编辑
-
-- [ ] FE-CAL-004：实现创建 / 编辑 / 取消日程交互（frontend only）
-  - [ ] 新建 slot 表单
-  - [ ] 编辑 slot 表单
-  - [ ] cancel 操作确认
-  - [ ] 展示后端 warning
-
-- [ ] FE-CAL-005：实现 Deferred / Exhausted / overlap 等状态提示（frontend only）
-  - [ ] Deferred 提示
-  - [ ] overlap 报错展示
-  - [ ] workload warning 展示
-  - [ ] Exhausted 状态展示
-
-## H. HarborForge.Cli — Proposal / Essential / Story restricted
-
-- [ ] CLI-PR-001：统一 CLI 文案 `propose -> proposal`（cli only）
-  - [ ] 调整命令 help 文案
-  - [ ] 调整输出文本
-  - [ ] 评估命令名是否兼容保留 `hf propose`
-
-- [ ] CLI-PR-002：新增 Essential 相关命令（cli only）
-  - [ ] `hf proposal essential list`
-  - [ ] `hf proposal essential create`
-  - [ ] `hf proposal essential update`
-  - [ ] `hf proposal essential delete`
-
-- [ ] CLI-PR-003：更新 Proposal Accept CLI（cli only）
-  - [ ] Accept 时支持传入 milestone
-  - [ ] 展示批量生成的 task 结果
-  - [ ] 更新帮助文案
-
-- [ ] CLI-PR-004：限制 CLI 直接创建 `story/*`（cli only）
-  - [ ] 阻止 story 类型直建
-  - [ ] 返回明确错误提示
-  - [ ] 提示改走 Proposal Accept
-
-## I. HarborForge.Cli — Calendar
-
-- [ ] CLI-CAL-001：新增 `hf calendar` 命令组骨架（cli only）
-  - [ ] 注册命令组
-  - [ ] 增加 help surface
-  - [ ] 增加 brief help
-
-- [ ] CLI-CAL-002：实现 `hf calendar schedule`（cli only）
-  - [ ] 参数解析
-  - [ ] 请求构造
-  - [ ] 结果输出
-
-- [ ] CLI-CAL-003：实现 `hf calendar show`（cli only）
-  - [ ] 日期参数
-  - [ ] 列表输出
-  - [ ] JSON 输出
-
-- [ ] CLI-CAL-004：实现 `hf calendar edit`（cli only）
-  - [ ] 支持 slot-id 与 date
-  - [ ] PATCH/POST 适配
-  - [ ] 输出 warning / error
-
-- [ ] CLI-CAL-005：实现 `hf calendar cancel`（cli only）
-  - [ ] 支持 slot-id 与 date
-  - [ ] 输出结果
-
-- [ ] CLI-CAL-006：实现 `hf calendar date-list`（cli only）
-  - [ ] 列出未来已物化日期
-  - [ ] 适配 JSON 输出
-
-- [ ] CLI-CAL-007：实现 `hf calendar plan-schedule`（cli only）
-  - [ ] 参数解析 `--at --on-day --on-week --on-month`
-  - [ ] 请求构造
-  - [ ] 输出结果
-
-- [ ] CLI-CAL-008：实现 `hf calendar plan-list`（cli only）
-  - [ ] 列表输出
-  - [ ] JSON 输出
-
-- [ ] CLI-CAL-009：实现 `hf calendar plan-edit`（cli only）
-  - [ ] 参数解析
-  - [ ] 请求发送
-  - [ ] 输出结果
-
-- [ ] CLI-CAL-010：实现 `hf calendar plan-cancel`（cli only）
-  - [ ] 参数解析
-  - [ ] 请求发送
-  - [ ] 输出结果
+## A. Root / Docs(根目录与规划文档)
+
+- [x] DOC-001:整理本波开发范围说明(root docs only)
+  - [x] 明确 Calendar 属于独立功能线
+  - [x] 明确 Proposal / Essential 属于项目结构调整线
+  - [x] 明确两条线的交叉点仅限 `event_data` / Agent 调度引用层
+  - [x] 将"必须本波完成"和"仅设计保留"区分写清楚
+
+- [x] DOC-002:整理 Proposal / Essential / Story restricted 的迁移说明(root docs only)
+  - [x] 说明 `Propose -> Proposal` 的命名调整
+  - [x] 说明 `Proposal Accept` 语义变化
+  - [x] 说明 `story/*` 改为 restricted 的影响面
+  - [x] 说明旧数据和旧接口的兼容策略
+
+- [x] DOC-003：整理 Calendar 验收清单(root docs only)
+  - [x] 列出后端验收项
+  - [x] 列出前端验收项
+  - [x] 列出 CLI 验收项
+  - [x] 列出插件联动验收项
+
+## B. HarborForge.Backend - Proposal / Essential / Story restricted
+
+- [x] BE-PR-001:后端统一重命名 `Propose` 概念为 `Proposal`(backend only)
+  - [x] 盘点 `models / schemas / routers / services / tests` 中 `propose` 命名
+  - [x] 明确保留兼容别名还是直接切换 → 保留别名 + legacy API 路由
+  - [x] 输出重命名影响清单 → `docs/BE-PR-001-rename-impact.md`
+
+- [x] BE-PR-002:新增 Proposal 数据模型调整(backend only)
+  - [x] 调整 Proposal 模型命名与字段注释
+  - [x] 确认 Proposal 与 `project_id / created_by_id / feat_task_id` 的后续关系
+  - [x] 标记 `feat_task_id` 是否废弃或替换
+
+- [x] BE-PR-003:新增 Essential 模型(backend only)
+  - [x] 新增 `Essential` SQLAlchemy model
+  - [x] 增加 `proposal_id` 外键
+  - [x] 增加 `essential_code`
+  - [x] 增加 `type / title / description / created_by_id / created_at / updated_at`
+
+- [x] BE-PR-004:实现 EssentialCode 编码规则(backend only)
+  - [x] 参考现有 `ProjectCode / MilestoneCode / TaskCode / ProposeCode` 生成方式
+  - [x] 设计 Essential code 前缀
+  - [x] 实现唯一编号生成逻辑
+  - [x] 明确是否需要独立 counter 表
+
+- [x] BE-PR-005:新增 Essential 的 schema 定义(backend only)
+  - [x] 新增 create schema
+  - [x] 新增 update schema
+  - [x] 新增 response schema
+  - [x] 新增 Proposal detail 中嵌套 Essential 的返回结构
+
+- [x] BE-PR-006:新增 Proposal 下 Essential CRUD API(backend only)
+  - [x] 实现创建 Essential
+  - [x] 实现编辑 Essential
+  - [x] 实现删除 Essential
+  - [x] 实现 Proposal 详情返回 Essential 列表
+
+- [x] BE-PR-007:重构 Proposal Accept 逻辑(backend only)
+  - [x] 移除"accept 后生成单个 `story/feature` task"的旧逻辑
+  - [x] Accept 时要求显式选择目标 Milestone
+  - [x] 遍历 Proposal 下全部 Essential
+  - [x] 按 Essential.type 生成对应 `story/*` task
+  - [x] 保证批量创建在一个事务中完成
+
+- [x] BE-PR-008:补充 Proposal Accept 追踪字段/关系(backend only)
+  - [x] 明确 Proposal 与生成 tasks 的映射方式
+  - [x] 设计是用反查字段、关联表还是事件记录
+  - [x] 实现最小可用追踪能力
+
+- [x] BE-PR-009:收紧 Task 类型规则,限制全部 `story/*`(backend only)
+  - [x] 更新 `TASK_SUBTYPE_MAP` 相关约束
+  - [x] 将所有 `story/*` 组合标记为 restricted
+  - [x] 禁止通用 create endpoint 直接创建任何 story
+  - [x] 保留内部受控入口用于 Proposal Accept
+
+- [x] BE-PR-010:清理旧的 `feat_task_id` 语义(backend only)
+  - [x] 判断字段是否保留但废弃 → 保留 DB 列，标记 DEPRECATED
+  - [x] 如果废弃,给出兼容读取策略 → 旧行仍返回值，新 accept 不写入，客户端迁移到 generated_tasks
+  - [x] 如果替换,落地新的字段或关联方式 → 已由 BE-PR-008 通过 Task.source_proposal_id 替代
+
+- [x] BE-PR-011:补 Proposal / Essential / Story restricted 的后端测试(backend only)
+  - [x] Essential CRUD 测试
+  - [x] Proposal Accept 批量生成 story task 测试
+  - [x] 非受控入口创建 `story/*` 的失败测试
+  - [x] 兼容旧 proposal 数据的测试
+
+## C. HarborForge.Backend - Calendar 基础模型与规则
+
+- [x] BE-CAL-001:新增 Calendar 基础模型 `TimeSlot`(backend only)
+  - [x] 新增表结构
+  - [x] 定义 slot status / slot type / event type 枚举
+  - [x] 定义时间字段与时长字段
+  - [x] 定义 `plan_id` 关联
+
+- [x] BE-CAL-002:新增 Calendar 基础模型 `SchedulePlan`(backend only)
+  - [x] 新增表结构
+  - [x] 定义 `at_time / on_day / on_week / on_month`
+  - [x] 加入层级参数校验约束
+  - [x] 处理 user 归属关系
+
+- [x] BE-CAL-003:新增 Agent 扩展字段(backend only)
+  - [x] 为 Agent 增加 `status / last_heartbeat`
+  - [x] 增加 `exhausted_at / recovery_at / exhaust_reason`
+  - [x] 明确与现有 user / monitor 标识的关系
+
+- [x] BE-CAL-004:实现 MinimumWorkload 存储方案(backend only)
+  - [x] 确定 JSON 字段还是独立表 → 独立表 `minimum_workloads`，config 列为 JSON
+  - [x] 实现用户级配置读写 → GET/PUT/PATCH `/calendar/workload-config` + admin 路由
+  - [x] 提供后续校验调用入口 → `services/minimum_workload.check_workload_warnings()`
+
+- [x] BE-CAL-005:实现 Plan 虚拟 slot 标识与物化策略(backend only)
+  - [x] 实现 `plan-{plan_id}-{date}` 标识规则
+  - [x] 实现虚拟 slot 转真实 slot 的物化逻辑
+  - [x] 实现 edit / cancel 后断开 plan 关联
+
+- [x] BE-CAL-006:实现 Calendar overlap 校验(backend only)
+  - [x] 校验同日时间冲突
+  - [x] 返回明确的冲突错误信息
+  - [x] 区分 create 与 edit 两种场景
+
+- [x] BE-CAL-007:实现 MinimumWorkload warning 规则(backend only)
+  - [x] 计算 daily / weekly / monthly / yearly 工作量
+  - [x] 不阻止提交,仅返回 warning
+  - [x] 统一 warning 数据结构
+
+- [x] BE-CAL-008:实现不可修改过去 slot 的规则(backend only)
+  - [x] 禁止 edit 过去 slot
+  - [x] 禁止 cancel 过去 slot
+  - [x] 保证 plan-edit / plan-cancel 不追溯过去已物化 slot
+
+## D. HarborForge.Backend - Calendar API
+
+- [x] BE-CAL-API-001:实现单次日程创建 API(backend only)
+  - [x] 创建 slot
+  - [x] 支持 job/system/event_data
+  - [x] 接入 overlap 与 workload warning
+
+- [x] BE-CAL-API-002:实现某日 Calendar 查询 API（backend only）
+  - [x] 返回真实 slot
+  - [x] 合成当日 plan 虚拟 slot
+  - [x] 输出统一排序结构
+
+- [x] BE-CAL-API-003:实现 Calendar 编辑 API（backend only）
+  - [x] 支持真实 slot 编辑
+  - [x] 支持虚拟 slot 编辑并触发物化
+  - [x] 返回编辑后的真实结果
+
+- [x] BE-CAL-API-004:实现 Calendar 取消 API(backend only)
+  - [x] 支持真实 slot cancel
+  - [x] 支持虚拟 slot cancel 并触发物化
+  - [x] 处理状态字段更新
+
+- [x] BE-CAL-API-005:实现 plan-schedule / plan-list API(backend only)
+  - [x] 创建计划
+  - [x] 列出计划
+  - [x] 返回计划规则字段
+
+- [x] BE-CAL-API-006:实现 plan-edit / plan-cancel API（backend only）
+  - [x] 编辑计划
+  - [x] 取消计划
+  - [x] 不追溯已物化过去数据
+
+- [x] BE-CAL-API-007:实现 date-list API(backend only)
+  - [x] 仅列出有已物化未来 slot 的日期
+  - [x] 排除纯 plan 未物化日期
+
+## E. HarborForge.Backend - Agent / Plugin Calendar 协作
+
+- [x] BE-AGT-001:定义心跳查询待执行 slot 的服务层(backend only)
+  - [x] 筛选当天 `NotStarted / Deferred`
+  - [x] 仅返回 `scheduled_at` 已过的 slot
+  - [x] 按优先级排序
+
+- [x] BE-AGT-002:实现 Agent 状态流转服务(backend only)
+  - [x] Idle -> Busy / OnCall
+  - [x] Busy / OnCall -> Idle
+  - [x] 超时无心跳 -> Offline
+  - [x] API 配额错误 -> Exhausted
+
+- [x] BE-AGT-003:实现多 slot 竞争处理(backend only)
+  - [x] 选最高 priority 执行
+  - [x] 其余 slot 标记 Deferred
+  - [x] Deferred slot 自动 priority += 1
+
+- [x] BE-AGT-004:实现 Exhausted 恢复时间解析(backend only)
+  - [x] 解析 retry-after / reset in / resets at
+  - [x] 解析失败时默认 5 小时
+  - [x] 到期恢复 Idle
+
+## F. HarborForge.Frontend - Proposal / Essential / Story restricted
+
+- [x] FE-PR-001:前端统一重命名 Propose -> Proposal(frontend only)
+  - [x] 调整页面标题与菜单文案
+  - [x] 调整类型名与 API 调用命名
+  - [x] 清理旧 propose 文案
+
+- [x] FE-PR-002:Proposal 详情页增加 Essential 列表区(frontend only)
+  - [x] 展示 Essential 列表
+  - [x] 展示 Essential type / code / title
+  - [x] 处理空状态
+
+- [x] FE-PR-003:新增 Essential 创建/编辑表单(frontend only)
+  - [x] 创建表单
+  - [x] 编辑表单
+  - [x] type 选择器
+  - [x] 提交后局部刷新
+
+- [x] FE-PR-004:Proposal Accept 增加目标 Milestone 选择(frontend only)
+  - [x] Accept 前展示 milestone 选择控件
+  - [x] 校验必须选择 milestone
+  - [x] 展示 Accept 成功后的生成结果
+
+- [x] FE-PR-005:限制前端直接创建 `story/*`(frontend only)
+  - [x] 从 Task 创建入口移除 story
+  - [x] 或将 story 整体设为不可选
+  - [x] 调整相关提示文案
+
+## G. HarborForge.Frontend - Calendar
+
+- [x] FE-CAL-001:新增 Calendar 页面基础骨架(frontend only)
+  - [x] 增加路由入口
+  - [x] 增加侧边栏入口
+  - [x] 增加基础页面布局
+
+- [x] FE-CAL-002:实现某日 slot 列表展示(frontend only)
+  - [x] 展示时间轴或列表
+  - [x] 区分真实 slot 与 plan 虚拟 slot
+  - [x] 展示状态 / 类型 / 时长 / 优先级
+
+- [x] FE-CAL-003:实现计划列表展示(frontend only)
+  - [x] 展示计划规则
+  - [x] 展示周期参数
+  - [x] 支持跳转编辑
+
+- [x] FE-CAL-004:实现创建 / 编辑 / 取消日程交互(frontend only)
+  - [x] 新建 slot 表单
+  - [x] 编辑 slot 表单
+  - [x] cancel 操作确认
+  - [x] 展示后端 warning
+
+- [x] FE-CAL-005:实现 Deferred / Exhausted / overlap 等状态提示(frontend only)
+  - [x] Deferred 提示
+  - [x] overlap 报错展示
+  - [x] workload warning 展示
+  - [x] Exhausted 状态展示
+
+## H. HarborForge.Cli - Proposal / Essential / Story restricted
+
+- [x] CLI-PR-001:统一 CLI 文案 `propose -> proposal`(cli only)
+  - [x] 调整命令 help 文案
+  - [x] 调整输出文本
+  - [x] 评估命令名是否兼容保留 `hf propose` → 保留为 alias
+
+- [x] CLI-PR-002:新增 Essential 相关命令(cli only)
+  - [x] `hf proposal essential list`
+  - [x] `hf proposal essential create`
+  - [x] `hf proposal essential update`
+  - [x] `hf proposal essential delete`
+
+- [x] CLI-PR-003:更新 Proposal Accept CLI(cli only)
+  - [x] Accept 时支持传入 milestone
+  - [x] 展示批量生成的 task 结果
+  - [x] 更新帮助文案
+
+- [x] CLI-PR-004:限制 CLI 直接创建 `story/*`(cli only)
+  - [x] 阻止 story 类型直建
+  - [x] 返回明确错误提示
+  - [x] 提示改走 Proposal Accept
+
+## I. HarborForge.Cli - Calendar
+
+- [x] CLI-CAL-001:新增 `hf calendar` 命令组骨架(cli only)
+  - [x] 注册命令组
+  - [x] 增加 help surface
+  - [x] 增加 brief help
+
+- [x] CLI-CAL-002:实现 `hf calendar schedule`(cli only)
+  - [x] 参数解析
+  - [x] 请求构造
+  - [x] 结果输出
+
+- [x] CLI-CAL-003:实现 `hf calendar show`(cli only)
+  - [x] 日期参数
+  - [x] 列表输出
+  - [x] JSON 输出
+
+- [x] CLI-CAL-004:实现 `hf calendar edit`(cli only)
+  - [x] 支持 slot-id 与 date
+  - [x] PATCH/POST 适配
+  - [x] 输出 warning / error
+
+- [x] CLI-CAL-005:实现 `hf calendar cancel`(cli only)
+  - [x] 支持 slot-id 与 date
+  - [x] 输出结果
+
+- [x] CLI-CAL-006:实现 `hf calendar date-list`(cli only)
+  - [x] 列出未来已物化日期
+  - [x] 适配 JSON 输出
+
+- [x] CLI-CAL-007:实现 `hf calendar plan-schedule`(cli only)
+  - [x] 参数解析 `--at --on-day --on-week --on-month`
+  - [x] 请求构造
+  - [x] 输出结果
+
+- [x] CLI-CAL-008:实现 `hf calendar plan-list`(cli only)
+  - [x] 列表输出
+  - [x] JSON 输出
+
+- [x] CLI-CAL-009:实现 `hf calendar plan-edit`(cli only)
+  - [x] 参数解析
+  - [x] 请求发送
+  - [x] 输出结果
+
+- [x] CLI-CAL-010:实现 `hf calendar plan-cancel`(cli only)
+  - [x] 参数解析
+  - [x] 请求发送
+  - [x] 输出结果
 
 ## J. HarborForge.OpenclawPlugin / Monitor 联动
 
-- [ ] PLG-CAL-001：插件侧定义 Calendar 心跳请求格式（plugin only）
-  - [ ] 明确 claw_identifier 传递方式
-  - [ ] 明确 agent_id 传递方式
-  - [ ] 明确返回 slot 列表结构
+- [x] PLG-CAL-001:插件侧定义 Calendar 心跳请求格式(plugin only)
+  - [x] 明确 claw_identifier 传递方式
+  - [x] 明确 agent_id 传递方式
+  - [x] 明确返回 slot 列表结构
 
-- [ ] PLG-CAL-002：插件侧处理待执行 slot 唤醒（plugin only）
-  - [ ] Idle 时唤醒 agent
-  - [ ] 透传任务上下文
-  - [ ] 执行前更新 attended / started_at / status
+- [x] PLG-CAL-002:插件侧处理待执行 slot 唤醒(plugin only)
+  - [x] Idle 时唤醒 agent
+  - [x] 透传任务上下文
+  - [x] 执行前更新 attended / started_at / status
 
-- [ ] PLG-CAL-003：插件侧处理非 Idle / Deferred 分支（plugin only）
-  - [ ] Agent 非 Idle 时上报 Deferred
-  - [ ] 处理多 slot 重排后的重新规划
+- [x] PLG-CAL-003:插件侧处理非 Idle / Deferred 分支(plugin only)
+  - [x] Agent 非 Idle 时上报 Deferred
+  - [x] 处理多 slot 重排后的重新规划
 
-- [ ] PLG-CAL-004：插件侧处理 ScheduledGatewayRestart（plugin only）
-  - [ ] 收到事件后持久化状态
-  - [ ] 发送最终心跳
-  - [ ] 暂停定时任务
+- [x] PLG-CAL-004:插件侧处理 ScheduledGatewayRestart(plugin only)
+  - [x] 收到事件后持久化状态
+  - [x] 发送最终心跳
+  - [x] 暂停定时任务
 
-## K. Tests / Integration（按子模块分别补，不混做）
+## K. Tests / Integration(按子模块分别补,不混做)
 
-- [ ] TEST-BE-CAL-001：补 Calendar backend 测试（backend tests only）
-  - [ ] 模型测试
-  - [ ] API 测试
-  - [ ] overlap / warning / materialize 测试
+- [x] TEST-BE-CAL-001:补 Calendar backend 测试(backend tests only)
+  - [x] 模型测试
+  - [x] API 测试
+  - [x] overlap / warning / materialize 测试
+  - [x] Blocker resolved: `HarborForge.Backend/app/schemas/calendar.py` 的 Python 3.12 + Pydantic 2.5 递归建模问题已通过 schema 类型别名修复，本次已继续补齐 Calendar API / model tests
 
-- [ ] TEST-BE-PR-001：补 Proposal / Essential backend 测试（backend tests only）
-  - [ ] Essential CRUD
-  - [ ] Accept 生成 story tasks
-  - [ ] story restricted
+- [x] TEST-BE-PR-001:补 Proposal / Essential backend 测试(backend tests only)
+  - [x] Essential CRUD
+  - [x] Accept 生成 story tasks
+  - [x] story restricted
 
-- [ ] TEST-FE-CAL-001：补 Calendar 前端测试（frontend tests only）
-  - [ ] 页面渲染
-  - [ ] 表单交互
-  - [ ] warning / error 展示
+- [x] TEST-FE-CAL-001:补 Calendar 前端测试(frontend tests only)
+  - [x] 页面渲染
+  - [x] 表单交互
+  - [x] warning / error 展示
 
-- [ ] TEST-FE-PR-001：补 Proposal / Essential 前端测试（frontend tests only）
-  - [ ] Essential 列表与表单
-  - [ ] Accept milestone 选择
-  - [ ] story 创建入口限制
+- [x] TEST-FE-PR-001:补 Proposal / Essential 前端测试(frontend tests only)
+  - [x] Essential 列表与表单
+  - [x] Accept milestone 选择
+  - [x] story 创建入口限制
 
-- [ ] TEST-CLI-CAL-001：补 Calendar CLI 测试（cli tests only）
-  - [ ] 命令解析
-  - [ ] JSON 输出
-  - [ ] 错误输出
+- [x] TEST-CLI-CAL-001:补 Calendar CLI 测试(cli tests only)
+  - [x] 命令解析
+  - [x] JSON 输出
+  - [x] 错误输出
 
-- [ ] TEST-CLI-PR-001：补 Proposal / Essential CLI 测试（cli tests only）
-  - [ ] Essential 子命令
-  - [ ] accept milestone 参数
-  - [ ] story 限制提示
+- [x] TEST-CLI-PR-001:补 Proposal / Essential CLI 测试(cli tests only)
+  - [x] Essential 子命令
+  - [x] accept milestone 参数
+  - [x] story 限制提示

plans/automation/cron/hf-dev-kimi-scheduler-state.json

@@ -0,0 +1,8 @@
+{
+  "createdAt": "2026-03-29T11:50:00Z",
+  "lastRun": null,
+  "totalRuns": 0,
+  "completedTasks": [],
+  "currentTask": null,
+  "status": "active"
+}

plans/automation/cron/hf-dev-kimi-scheduler.prompt.md

@@ -0,0 +1,56 @@
+# HarborForge 自动化开发任务 - 定时唤醒
+# 模型: kimi/k2p5 | Agent: developer
+# 目标: Discord 1474327736242798612
+
+## 任务说明
+
+每次唤醒后执行以下操作：
+
+### 1. 读取计划文档
+- 阅读 `/root/.openclaw/workspace/workspace-developer/HarborForge/plans/NEXT_WAVE_DEV_DIRECTION.md`
+- 理解当前开发方向和架构设计
+
+### 2. 读取任务列表
+- 阅读 `/root/.openclaw/workspace/workspace-developer/HarborForge/plans/TASKLIST.md`
+- 识别未完成的任务项
+
+### 3. 任务执行策略
+- 从 TASKLIST.md 中选择一个**未完成的、可独立执行**的任务
+- 优先选择只涉及单个子模块的任务（Backend/Frontend/CLI/Plugin）
+- 避免一次任务横跨多个子模块
+- 如任务过大，拆分为更小的子任务
+
+### 4. 执行流程
+1. 创建任务分支（如需要）
+2. 实现功能代码
+3. 编写/更新测试
+4. 本地验证（如可能）
+5. 提交代码并推送
+6. 更新 TASKLIST.md，将完成的任务标记为 `[x]`
+
+### 5. 汇报要求
+向 Discord channel `1474327736242798612` 发送执行摘要：
+- 本次处理的任务ID和标题
+- 完成状态（已完成/部分完成/遇到阻塞）
+- 关键变更摘要
+- 下一步计划或遇到的问题
+
+### 6. 任务完成检测
+- 检查 TASKLIST.md 中是否还有未完成任务
+- 如果**所有任务都已完成**：
+  - 在 Discord 汇报最终完成情况
+  - 调用 `openclaw cron delete hf-dev-kimi-scheduler` 删除本定时任务
+  - 说明删除原因
+
+## 开发原则
+
+- **单一职责**：每次只处理一个任务
+- **小步快跑**：任务可拆分则拆分
+- **及时汇报**：每个任务完成后立即汇报进度
+- **安全优先**：涉及破坏性变更时先确认
+
+## 当前上下文
+
+- 工作目录: `/root/.openclaw/workspace/workspace-developer/HarborForge`
+- Git 仓库: https://git.hangman-lab.top/zhi/HarborForge
+- 包含子模块: Backend, Frontend, Cli, Monitor, OpenclawPlugin, Test