docs: rewrite top-level README — full component map

List all 7 submodules with stack/role, correct architecture and ports, replace stale Issues model with tasks/milestones/proposals, add Security notes (mandatory strong SECRET_KEY) and cross-links to component READMEs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
quick fix
2026-05-16 17:50:52 +01:00 · 2026-04-15 07:14:36 +01:00 · 2026-04-05 22:18:03 +00:00 · 2026-04-05 22:14:41 +00:00 · 2026-04-05 22:11:44 +00:00 · 2026-04-03 16:25:48 +00:00
8 changed files with 255 additions and 227 deletions
--- a/HarborForge.Backend
+++ b/HarborForge.Backend
--- a/HarborForge.Cli
+++ b/HarborForge.Cli
--- a/HarborForge.Frontend
+++ b/HarborForge.Frontend
--- a/HarborForge.Monitor
+++ b/HarborForge.Monitor
--- a/HarborForge.OpenclawPlugin
+++ b/HarborForge.OpenclawPlugin
--- a/HarborForge.Test
+++ b/HarborForge.Test
--- a/README.md
+++ b/README.md
@@ -1,34 +1,45 @@
 # HarborForge

-Agent/人类协同任务管理平台
+Agent / 人类协同任务管理平台 —— 用严格的状态机管理 提案 → 里程碑 → 任务 的完整生命周期，配套 CLI、监控与 OpenClaw 集成。

 ## 项目结构

+本仓库是 umbrella 仓库，所有组件以 git 子模块形式组织：
+
 ```
 HarborForge/
-├── HarborForge.Backend/    # 后端 (FastAPI + MySQL)
-├── HarborForge.Frontend/   # 前端 (React + Vite)
-├── docker-compose.yml      # Docker 部署配置
-├── nginx-host.conf.example # 宿主机 nginx 配置示例
-└── .env.example            # 环境变量模板
+├── AbstractWizard/             # Go，安全初始化服务（SSH 隧道，端口 8080）
+├── HarborForge.Backend/        # Python/FastAPI，核心 REST API + RBAC（端口 8000）
+├── HarborForge.Frontend/       # React + TypeScript + Vite，单页前端（端口 3000）
+├── HarborForge.Cli/            # Go，命令行客户端 `hf`
+├── HarborForge.Monitor/        # Go，主机遥测客户端（可选本地 bridge 9100）
+├── HarborForge.OpenclawPlugin/ # Node，OpenClaw 插件 `harbor-forge`
+├── HarborForge.Test/           # 集成测试（后端 pytest / 前端 Playwright）
+├── docker-compose.yml          # Docker 编排配置
+├── nginx-host.conf.example     # 宿主机 nginx 配置示例
+└── .env.example                # 环境变量模板
 ```

 ## 快速开始

 ```bash
-# 克隆并初始化子模块
-git clone https://git.hangman-lab.top/zhi/HarborForge.git
+# 克隆并初始化所有子模块
+git clone --recurse-submodules https://git.hangman-lab.top/zhi/HarborForge.git
 cd HarborForge
+# 若已克隆但未初始化子模块：
 git submodule update --init --recursive

+# 配置环境变量（不要使用默认值，见“安全”一节）
+cp .env.example .env
+# 编辑 .env，至少设置强随机 SECRET_KEY 与数据库口令
+
 # 启动服务
 docker compose up -d
 ```

 ## 首次部署 — 初始化向导

-HarborForge 使用 [AbstractWizard](https://git.hangman-lab.top/hzhang/AbstractWizard) 进行安全初始化。
-Wizard 仅监听 `127.0.0.1`，必须通过 SSH 隧道访问。
+HarborForge 使用 [AbstractWizard](./AbstractWizard) 进行安全初始化。Wizard 仅监听 `127.0.0.1`，必须通过 SSH 隧道访问。

 ```bash
 # 1. SSH 隧道映射 wizard 端口到本地
@@ -37,65 +48,81 @@ ssh -L 18080:127.0.0.1:18080 user@your-server
 # 2. 浏览器访问前端（或通过宿主机 nginx）
 #    前端检测到后端未就绪 → 自动跳转初始化向导

-# 3. 在向导中配置:
-#    - 数据库连接信息
-#    - 管理员账号
-#    - 默认项目（可选）
+# 3. 在向导中配置：数据库连接、管理员账号、默认项目（可选）

-# 4. 配置保存后，后端自动检测到配置并启动
-#    刷新页面 → 进入登录界面
+# 4. 配置保存后，后端自动检测到配置并启动；刷新页面 → 登录界面
 ```

 ### 启动流程

 ```
 docker compose up
-  ├── mysql       → 数据库启动
-  ├── wizard      → AbstractWizard 启动 (127.0.0.1:18080)
-  ├── backend     → 等待配置文件... (轮询 /config/harborforge.json)
-  └── frontend    → 检测后端状态
-                    ├── 后端未就绪 → 显示初始化向导 (SSH 隧道连 wizard)
-                    └── 后端就绪   → 正常登录界面
+  ├── mysql    → 数据库启动
+  ├── wizard   → AbstractWizard 启动（127.0.0.1，SSH 隧道访问）
+  ├── backend  → 阻塞等待配置文件（轮询 /config/harborforge.json）
+  └── frontend → 检测后端状态
+                 ├── 后端未就绪 → 显示初始化向导（SSH 隧道连 wizard）
+                 └── 后端就绪   → 正常登录界面
 ```

 ### 安全模型

- Wizard 端口绑定 `127.0.0.1`，不暴露到外部网络
- 初始化必须通过 SSH 隧道完成（与 AbstractWizard 安全模型一致）
- 配置完成后 Wizard 自动切换为只读模式
- 配置通过 Docker volume 共享给后端（不走网络）
+- Wizard 端口绑定 `127.0.0.1`，不暴露到外部网络；初始化必须经 SSH 隧道完成。
+- 配置通过 Docker volume 共享给后端（不走网络），后端以只读方式挂载。

 ## 部署架构

 ```
 宿主机 nginx (80/443)
-  ├── /     → frontend (Docker, port 3000)
-  └── /api/ → backend  (Docker, port 8000)
+  ├── /     → frontend (Docker, 端口 3000)
+  └── /api/ → backend  (Docker, 端口 8000)

-Docker 内部 (不暴露):
-  wizard (127.0.0.1:18080) → 配置管理，SSH 隧道访问
-  wizard_config volume     → wizard 写入，backend 读取
+Docker 内部（不对外）:
+  wizard (127.0.0.1) → 配置管理，SSH 隧道访问
+  wizard_config vol  → wizard 写入，backend 只读读取
+  mysql (127.0.0.1)  → 数据持久化
 ```

 ## 子模块

- [HarborForge.Backend](https://git.hangman-lab.top/zhi/HarborForge.Backend) - FastAPI 后端 API
- [HarborForge.Frontend](https://git.hangman-lab.top/zhi/HarborForge.Frontend) - React 前端
+| 子模块 | 技术栈 | 作用 |
+|--------|--------|------|
+| [AbstractWizard](./AbstractWizard) | Go | 首次安装向导，安全写配置（原子写 + 备份），init/readonly 模式 |
+| [HarborForge.Backend](./HarborForge.Backend) | Python / FastAPI / SQLAlchemy / MySQL | 核心 API：用户、项目、任务、里程碑、提案、RBAC、Webhook、工时、通知 |
+| [HarborForge.Frontend](./HarborForge.Frontend) | React 18 / TS / Vite | SPA，~20 页面；自动检测未初始化 → 引导安装向导 |
+| [HarborForge.Cli](./HarborForge.Cli) | Go | 权限感知命令行客户端 `hf` |
+| [HarborForge.Monitor](./HarborForge.Monitor) | Go | 独立主机遥测客户端，心跳上报 |
+| [HarborForge.OpenclawPlugin](./HarborForge.OpenclawPlugin) | Node / TS | OpenClaw 插件，桥接遥测，可安装 `hf` 技能与日历调度 |
+| [HarborForge.Test](./HarborForge.Test) | pytest / Playwright | 后端与前端集成测试 |
+
+## 核心业务模型
+
+- **里程碑**：`open → freeze → undergoing → completed`（freeze 时须恰好 1 个 release 任务）
+- **任务**（issue / story / test / maintenance / research / review / resolution）：`pending → open → undergoing → completed`，完成须带评论
+- **提案**：用户提 propose → 管理者 accept → 自动在里程碑内创建 feature story 任务；reject 可重开
+- **RBAC**：细粒度权限 + 项目角色层级（guest < viewer < member < dev < mgr < admin）

 ## 端口

-| 服务 | 默认端口 | 绑定 | 环境变量 |
+| 服务 | 容器端口 | 绑定 | 环境变量 |
 |------|----------|------|----------|
-| Frontend | 3000 | 0.0.0.0 | `FRONTEND_PORT` |
-| Backend | 8000 | 0.0.0.0 | `BACKEND_PORT` |
-| MySQL | 3306 | 127.0.0.1 | `MYSQL_PORT` |
-| Wizard | 18080 | 127.0.0.1 | `WIZARD_PORT` |
+| Frontend | 3000 | 见 compose | `FRONTEND_PORT` |
+| Backend  | 8000 | 见 compose | `BACKEND_PORT` |
+| MySQL    | 3306 | 127.0.0.1  | `MYSQL_PORT` |
+| Wizard   | 8080 | 127.0.0.1  | `WIZARD_PORT` |

-## 前端页面
+> SSH 隧道示例使用本地端口 `18080` 转发到服务器 wizard。

- 🔧 初始化向导 — 首次部署配置（SSH 隧道）
- 📊 仪表盘 — 统计概览
- 📋 Issues — 创建、列表、详情、状态变更、评论
- 📁 项目 — 项目管理、成员、关联 issue
- 🏁 里程碑 — 进度追踪、完成百分比
- 🔔 通知 — 实时通知中心、未读计数
+## 安全
+
+部署前务必：
+
+- **设置强随机 `SECRET_KEY`**（如 `openssl rand -hex 32`）。后端在检测到弱/默认/过短密钥时会拒绝启动。
+- 不要使用 `.env.example` 中的占位口令；为 MySQL 设置强口令。
+- 不要将含真实密钥的 `.env` 提交进版本库。
+
+后端的鉴权/RBAC/SSRF 加固详见 [HarborForge.Backend 的 README](./HarborForge.Backend) “Security” 一节。
+
+## 前端
+
+前端采用集中式自定义设计系统（“Foundry Deck” 工业主题），细节见 [HarborForge.Frontend 的 README](./HarborForge.Frontend)。
--- a/plans/TASKLIST.md
+++ b/plans/TASKLIST.md
@@ -144,236 +144,237 @@
  - [x] 支持 job/system/event_data
  - [x] 接入 overlap 与 workload warning

- [ ] BE-CAL-API-002:实现某日 Calendar 查询 API(backend only)
-  - [ ] 返回真实 slot
-  - [ ] 合成当日 plan 虚拟 slot
-  - [ ] 输出统一排序结构
+- [x] BE-CAL-API-002:实现某日 Calendar 查询 API（backend only）
+  - [x] 返回真实 slot
+  - [x] 合成当日 plan 虚拟 slot
+  - [x] 输出统一排序结构

- [ ] BE-CAL-API-003:实现 Calendar 编辑 API(backend only)
-  - [ ] 支持真实 slot 编辑
-  - [ ] 支持虚拟 slot 编辑并触发物化
-  - [ ] 返回编辑后的真实结果
+- [x] BE-CAL-API-003:实现 Calendar 编辑 API（backend only）
+  - [x] 支持真实 slot 编辑
+  - [x] 支持虚拟 slot 编辑并触发物化
+  - [x] 返回编辑后的真实结果

- [ ] BE-CAL-API-004:实现 Calendar 取消 API(backend only)
-  - [ ] 支持真实 slot cancel
-  - [ ] 支持虚拟 slot cancel 并触发物化
-  - [ ] 处理状态字段更新
+- [x] BE-CAL-API-004:实现 Calendar 取消 API(backend only)
+  - [x] 支持真实 slot cancel
+  - [x] 支持虚拟 slot cancel 并触发物化
+  - [x] 处理状态字段更新

- [ ] BE-CAL-API-005:实现 plan-schedule / plan-list API(backend only)
-  - [ ] 创建计划
-  - [ ] 列出计划
-  - [ ] 返回计划规则字段
+- [x] BE-CAL-API-005:实现 plan-schedule / plan-list API(backend only)
+  - [x] 创建计划
+  - [x] 列出计划
+  - [x] 返回计划规则字段

- [ ] BE-CAL-API-006:实现 plan-edit / plan-cancel API(backend only)
-  - [ ] 编辑计划
-  - [ ] 取消计划
-  - [ ] 不追溯已物化过去数据
+- [x] BE-CAL-API-006:实现 plan-edit / plan-cancel API（backend only）
+  - [x] 编辑计划
+  - [x] 取消计划
+  - [x] 不追溯已物化过去数据

- [ ] BE-CAL-API-007:实现 date-list API(backend only)
-  - [ ] 仅列出有已物化未来 slot 的日期
-  - [ ] 排除纯 plan 未物化日期
+- [x] BE-CAL-API-007:实现 date-list API(backend only)
+  - [x] 仅列出有已物化未来 slot 的日期
+  - [x] 排除纯 plan 未物化日期

 ## E. HarborForge.Backend - Agent / Plugin Calendar 协作

- [ ] BE-AGT-001:定义心跳查询待执行 slot 的服务层(backend only)
-  - [ ] 筛选当天 `NotStarted / Deferred`
-  - [ ] 仅返回 `scheduled_at` 已过的 slot
-  - [ ] 按优先级排序
+- [x] BE-AGT-001:定义心跳查询待执行 slot 的服务层(backend only)
+  - [x] 筛选当天 `NotStarted / Deferred`
+  - [x] 仅返回 `scheduled_at` 已过的 slot
+  - [x] 按优先级排序

- [ ] BE-AGT-002:实现 Agent 状态流转服务(backend only)
-  - [ ] Idle -> Busy / OnCall
-  - [ ] Busy / OnCall -> Idle
-  - [ ] 超时无心跳 -> Offline
-  - [ ] API 配额错误 -> Exhausted
+- [x] BE-AGT-002:实现 Agent 状态流转服务(backend only)
+  - [x] Idle -> Busy / OnCall
+  - [x] Busy / OnCall -> Idle
+  - [x] 超时无心跳 -> Offline
+  - [x] API 配额错误 -> Exhausted

- [ ] BE-AGT-003:实现多 slot 竞争处理(backend only)
-  - [ ] 选最高 priority 执行
-  - [ ] 其余 slot 标记 Deferred
-  - [ ] Deferred slot 自动 priority += 1
+- [x] BE-AGT-003:实现多 slot 竞争处理(backend only)
+  - [x] 选最高 priority 执行
+  - [x] 其余 slot 标记 Deferred
+  - [x] Deferred slot 自动 priority += 1

- [ ] BE-AGT-004:实现 Exhausted 恢复时间解析(backend only)
-  - [ ] 解析 retry-after / reset in / resets at
-  - [ ] 解析失败时默认 5 小时
-  - [ ] 到期恢复 Idle
+- [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

- [ ] FE-PR-001:前端统一重命名 Propose -> Proposal(frontend only)
-  - [ ] 调整页面标题与菜单文案
-  - [ ] 调整类型名与 API 调用命名
-  - [ ] 清理旧 propose 文案
+- [x] FE-PR-001:前端统一重命名 Propose -> Proposal(frontend only)
+  - [x] 调整页面标题与菜单文案
+  - [x] 调整类型名与 API 调用命名
+  - [x] 清理旧 propose 文案

- [ ] FE-PR-002:Proposal 详情页增加 Essential 列表区(frontend only)
-  - [ ] 展示 Essential 列表
-  - [ ] 展示 Essential type / code / title
-  - [ ] 处理空状态
+- [x] FE-PR-002:Proposal 详情页增加 Essential 列表区(frontend only)
+  - [x] 展示 Essential 列表
+  - [x] 展示 Essential type / code / title
+  - [x] 处理空状态

- [ ] FE-PR-003:新增 Essential 创建/编辑表单(frontend only)
-  - [ ] 创建表单
-  - [ ] 编辑表单
-  - [ ] type 选择器
-  - [ ] 提交后局部刷新
+- [x] FE-PR-003:新增 Essential 创建/编辑表单(frontend only)
+  - [x] 创建表单
+  - [x] 编辑表单
+  - [x] type 选择器
+  - [x] 提交后局部刷新

- [ ] FE-PR-004:Proposal Accept 增加目标 Milestone 选择(frontend only)
-  - [ ] Accept 前展示 milestone 选择控件
-  - [ ] 校验必须选择 milestone
-  - [ ] 展示 Accept 成功后的生成结果
+- [x] FE-PR-004:Proposal Accept 增加目标 Milestone 选择(frontend only)
+  - [x] Accept 前展示 milestone 选择控件
+  - [x] 校验必须选择 milestone
+  - [x] 展示 Accept 成功后的生成结果

- [ ] FE-PR-005:限制前端直接创建 `story/*`(frontend only)
-  - [ ] 从 Task 创建入口移除 story
-  - [ ] 或将 story 整体设为不可选
-  - [ ] 调整相关提示文案
+- [x] FE-PR-005:限制前端直接创建 `story/*`(frontend only)
+  - [x] 从 Task 创建入口移除 story
+  - [x] 或将 story 整体设为不可选
+  - [x] 调整相关提示文案

 ## G. HarborForge.Frontend - Calendar

- [ ] FE-CAL-001:新增 Calendar 页面基础骨架(frontend only)
-  - [ ] 增加路由入口
-  - [ ] 增加侧边栏入口
-  - [ ] 增加基础页面布局
+- [x] FE-CAL-001:新增 Calendar 页面基础骨架(frontend only)
+  - [x] 增加路由入口
+  - [x] 增加侧边栏入口
+  - [x] 增加基础页面布局

- [ ] FE-CAL-002:实现某日 slot 列表展示(frontend only)
-  - [ ] 展示时间轴或列表
-  - [ ] 区分真实 slot 与 plan 虚拟 slot
-  - [ ] 展示状态 / 类型 / 时长 / 优先级
+- [x] FE-CAL-002:实现某日 slot 列表展示(frontend only)
+  - [x] 展示时间轴或列表
+  - [x] 区分真实 slot 与 plan 虚拟 slot
+  - [x] 展示状态 / 类型 / 时长 / 优先级

- [ ] FE-CAL-003:实现计划列表展示(frontend only)
-  - [ ] 展示计划规则
-  - [ ] 展示周期参数
-  - [ ] 支持跳转编辑
+- [x] FE-CAL-003:实现计划列表展示(frontend only)
+  - [x] 展示计划规则
+  - [x] 展示周期参数
+  - [x] 支持跳转编辑

- [ ] FE-CAL-004:实现创建 / 编辑 / 取消日程交互(frontend only)
-  - [ ] 新建 slot 表单
-  - [ ] 编辑 slot 表单
-  - [ ] cancel 操作确认
-  - [ ] 展示后端 warning
+- [x] FE-CAL-004:实现创建 / 编辑 / 取消日程交互(frontend only)
+  - [x] 新建 slot 表单
+  - [x] 编辑 slot 表单
+  - [x] cancel 操作确认
+  - [x] 展示后端 warning

- [ ] FE-CAL-005:实现 Deferred / Exhausted / overlap 等状态提示(frontend only)
-  - [ ] Deferred 提示
-  - [ ] overlap 报错展示
-  - [ ] workload warning 展示
-  - [ ] Exhausted 状态展示
+- [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

- [ ] CLI-PR-001:统一 CLI 文案 `propose -> proposal`(cli only)
-  - [ ] 调整命令 help 文案
-  - [ ] 调整输出文本
-  - [ ] 评估命令名是否兼容保留 `hf propose`
+- [x] CLI-PR-001:统一 CLI 文案 `propose -> proposal`(cli only)
+  - [x] 调整命令 help 文案
+  - [x] 调整输出文本
+  - [x] 评估命令名是否兼容保留 `hf propose` → 保留为 alias

- [ ] CLI-PR-002:新增 Essential 相关命令(cli only)
-  - [ ] `hf proposal essential list`
-  - [ ] `hf proposal essential create`
-  - [ ] `hf proposal essential update`
-  - [ ] `hf proposal essential delete`
+- [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`

- [ ] CLI-PR-003:更新 Proposal Accept CLI(cli only)
-  - [ ] Accept 时支持传入 milestone
-  - [ ] 展示批量生成的 task 结果
-  - [ ] 更新帮助文案
+- [x] CLI-PR-003:更新 Proposal Accept CLI(cli only)
+  - [x] Accept 时支持传入 milestone
+  - [x] 展示批量生成的 task 结果
+  - [x] 更新帮助文案

- [ ] CLI-PR-004:限制 CLI 直接创建 `story/*`(cli only)
-  - [ ] 阻止 story 类型直建
-  - [ ] 返回明确错误提示
-  - [ ] 提示改走 Proposal Accept
+- [x] CLI-PR-004:限制 CLI 直接创建 `story/*`(cli only)
+  - [x] 阻止 story 类型直建
+  - [x] 返回明确错误提示
+  - [x] 提示改走 Proposal Accept

 ## I. HarborForge.Cli - Calendar

- [ ] CLI-CAL-001:新增 `hf calendar` 命令组骨架(cli only)
-  - [ ] 注册命令组
-  - [ ] 增加 help surface
-  - [ ] 增加 brief help
+- [x] CLI-CAL-001:新增 `hf calendar` 命令组骨架(cli only)
+  - [x] 注册命令组
+  - [x] 增加 help surface
+  - [x] 增加 brief help

- [ ] CLI-CAL-002:实现 `hf calendar schedule`(cli only)
-  - [ ] 参数解析
-  - [ ] 请求构造
-  - [ ] 结果输出
+- [x] CLI-CAL-002:实现 `hf calendar schedule`(cli only)
+  - [x] 参数解析
+  - [x] 请求构造
+  - [x] 结果输出

- [ ] CLI-CAL-003:实现 `hf calendar show`(cli only)
-  - [ ] 日期参数
-  - [ ] 列表输出
-  - [ ] JSON 输出
+- [x] CLI-CAL-003:实现 `hf calendar show`(cli only)
+  - [x] 日期参数
+  - [x] 列表输出
+  - [x] JSON 输出

- [ ] CLI-CAL-004:实现 `hf calendar edit`(cli only)
-  - [ ] 支持 slot-id 与 date
-  - [ ] PATCH/POST 适配
-  - [ ] 输出 warning / error
+- [x] CLI-CAL-004:实现 `hf calendar edit`(cli only)
+  - [x] 支持 slot-id 与 date
+  - [x] PATCH/POST 适配
+  - [x] 输出 warning / error

- [ ] CLI-CAL-005:实现 `hf calendar cancel`(cli only)
-  - [ ] 支持 slot-id 与 date
-  - [ ] 输出结果
+- [x] CLI-CAL-005:实现 `hf calendar cancel`(cli only)
+  - [x] 支持 slot-id 与 date
+  - [x] 输出结果

- [ ] CLI-CAL-006:实现 `hf calendar date-list`(cli only)
-  - [ ] 列出未来已物化日期
-  - [ ] 适配 JSON 输出
+- [x] CLI-CAL-006:实现 `hf calendar date-list`(cli only)
+  - [x] 列出未来已物化日期
+  - [x] 适配 JSON 输出

- [ ] CLI-CAL-007:实现 `hf calendar plan-schedule`(cli only)
-  - [ ] 参数解析 `--at --on-day --on-week --on-month`
-  - [ ] 请求构造
-  - [ ] 输出结果
+- [x] CLI-CAL-007:实现 `hf calendar plan-schedule`(cli only)
+  - [x] 参数解析 `--at --on-day --on-week --on-month`
+  - [x] 请求构造
+  - [x] 输出结果

- [ ] CLI-CAL-008:实现 `hf calendar plan-list`(cli only)
-  - [ ] 列表输出
-  - [ ] JSON 输出
+- [x] CLI-CAL-008:实现 `hf calendar plan-list`(cli only)
+  - [x] 列表输出
+  - [x] JSON 输出

- [ ] CLI-CAL-009:实现 `hf calendar plan-edit`(cli only)
-  - [ ] 参数解析
-  - [ ] 请求发送
-  - [ ] 输出结果
+- [x] CLI-CAL-009:实现 `hf calendar plan-edit`(cli only)
+  - [x] 参数解析
+  - [x] 请求发送
+  - [x] 输出结果

- [ ] CLI-CAL-010:实现 `hf calendar plan-cancel`(cli only)
-  - [ ] 参数解析
-  - [ ] 请求发送
-  - [ ] 输出结果
+- [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(按子模块分别补,不混做)

- [ ] 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 限制提示
Author	SHA1	Message	Date
hzhang	d69bd5213c	docs: rewrite top-level README — full component map List all 7 submodules with stack/role, correct architecture and ports, replace stale Issues model with tasks/milestones/proposals, add Security notes (mandatory strong SECRET_KEY) and cross-links to component READMEs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-16 17:50:52 +01:00
hzhang	19174c899e	quick fix	2026-04-15 07:14:36 +01:00
zhi	b9242a1588	chore: update HarborForge.Test submodule pointer to main head	2026-04-05 22:18:03 +00:00
zhi	08cae38b42	chore: update HarborForge submodule pointers	2026-04-05 22:14:41 +00:00
h z	e42926ec65	Merge pull request 'dev-2026-03-29' (#7 ) from dev-2026-03-29 into main Reviewed-on: #7	2026-04-05 22:11:44 +00:00
orion	27817fb0b9	chore: bump HarborForge component pointers for code-first indexing	2026-04-03 16:25:48 +00:00
zhi	7b3eb7b940	TEST-CLI-CAL-001 TEST-CLI-PR-001 complete CLI test tasks	2026-04-01 12:03:37 +00:00
zhi	fbc88f908b	TEST-FE-PR-001: Mark task as completed - Essential 列表与表单 ✓ - Accept milestone 选择 ✓ - story 创建入口限制 ✓	2026-04-01 11:41:56 +00:00
zhi	bdb8586612	TEST-FE-CAL-001 complete calendar frontend test coverage	2026-04-01 11:06:05 +00:00
zhi	69b2d2774e	TEST-BE-CAL-001 record calendar backend test completion	2026-04-01 10:35:57 +00:00
zhi	dced5bbcd3	TEST-BE-PR-001 verify backend proposal tests	2026-04-01 10:04:50 +00:00
zhi	77fc66c0fc	PLG-CAL-004: Mark task as complete - ScheduledGatewayRestart handling - Update submodule to include state persistence and restart handling - Mark PLG-CAL-004 tasks as complete in TASKLIST.md	2026-04-01 09:41:24 +00:00
zhi	8a886a1dff	PLG-CAL-003 complete plugin deferred replanning	2026-04-01 08:52:16 +00:00
zhi	ac94f7aa32	PLG-CAL-002: Mark task as complete - Update TASKLIST.md to mark PLG-CAL-002 as completed - Plugin submodule updated with scheduler implementation	2026-04-01 08:45:38 +00:00
zhi	0b7fb3a002	chore: mark PLG-CAL-001 complete in TASKLIST.md - PLG-CAL-001: Calendar heartbeat format — all 3 sub-items completed: claw_identifier 传递方式 / agent_id 传递方式 / slot 列表结构 - Spec documented in HarborForge.OpenclawPlugin/docs/PLG-CAL-001-calendar-heartbeat-format.md	2026-04-01 07:52:39 +00:00
zhi	28b21c96c4	feat(OpenclawPlugin): PLG-CAL-001: Calendar heartbeat format — submodule update Update HarborForge.OpenclawPlugin to commit 55d7d11: - plugin/calendar/types.ts: heartbeat request/response TypeScript types - plugin/calendar/calendar-bridge.ts: CalendarBridgeClient HTTP client - plugin/calendar/index.ts: module exports - docs/PLG-CAL-001-calendar-heartbeat-format.md: full format specification - plugin/openclaw.plugin.json: calendar config options Ref: HarborForge.NEXT_WAVE_DEV_DIRECTION.md §6, PLG-CAL-001	2026-04-01 07:52:07 +00:00
zhi	fec154f14f	CLI-CAL-001/002/003/004/005/006/007/008/009/010: Calendar CLI commands	2026-04-01 07:02:47 +00:00
zhi	15360f2a4b	CLI-PR-001/002/003/004: Proposal rename, Essential commands, story restriction	2026-04-01 06:56:30 +00:00
zhi	50fdd0f50b	FE-CAL-004/005: Calendar create/edit/cancel + status warnings	2026-04-01 06:50:11 +00:00
zhi	a540506752	FE-CAL-001/002/003: Calendar page skeleton with slot list and plans view	2026-04-01 06:48:22 +00:00
zhi	1bc9ba7dab	Update Frontend submodule: FE-PR-005 story restriction	2026-04-01 06:46:27 +00:00
zhi	cd137f3b69	FE-PR-003/004/005: Mark existing Essential forms & Accept modal done; remove story from task creation - FE-PR-003: Essential create/edit modal with type selector and partial refresh already implemented in ProposalDetailPage - FE-PR-004: Accept modal with milestone selector and generated tasks display already implemented - FE-PR-005: Remove 'story' from TASK_TYPES in CreateTaskPage and CreateTaskModal - all story/* must come from Proposal Accept workflow	2026-04-01 06:46:01 +00:00
zhi	75ccb17742	FE-PR-002: Mark task as completed in TASKLIST.md	2026-04-01 06:28:52 +00:00
zhi	235d636fee	FE-PR-002: Update Frontend submodule for Essential list feature	2026-04-01 06:25:54 +00:00
zhi	86250e0c0f	FE-PR-001: Update Frontend submodule - Propose -> Proposal rename	2026-04-01 04:46:50 +00:00
zhi	c9fe8f1f51	BE-AGT-004 complete exhausted recovery parsing	2026-04-01 04:18:48 +00:00
zhi	fe7b1408ad	BE-AGT-003: mark task complete, update Backend submodule ref	2026-04-01 02:50:20 +00:00
zhi	dafac0305d	BE-AGT-002: mark task complete, update Backend submodule ref	2026-04-01 00:46:23 +00:00
zhi	b1ea8ccccd	BE-AGT-001: mark task complete, update backend submodule	2026-03-31 23:01:52 +00:00
zhi	c73fd07295	BE-CAL-API-007: update submodule ref and mark task complete	2026-03-31 20:46:53 +00:00
zhi	b5cdd5c3c2	BE-CAL-API-006: implement plan-edit and plan-cancel API endpoints - PATCH /calendar/plans/{plan_id}: edit a recurring schedule plan - Validates period-parameter hierarchy after merge - Rejects edits to inactive (cancelled) plans - Detaches future materialized slots so they keep old data - Past materialized slots remain untouched - POST /calendar/plans/{plan_id}/cancel: cancel (soft-delete) a plan - Sets is_active=False - Detaches future materialized slots (plan_id -> NULL) - Preserves past materialized slots, returns their IDs - Added SchedulePlanEdit and SchedulePlanCancelResponse schemas - Imported guard_plan_edit/cancel_no_past_retroaction from slot_immutability	2026-03-31 16:46:22 +00:00
zhi	e74bde118a	Update Backend submodule: BE-CAL-API-005	2026-03-31 14:47:21 +00:00
zhi	9378a63af2	BE-CAL-API-005: implement plan-schedule / plan-list API - Add SchedulePlanCreate, SchedulePlanResponse, SchedulePlanListResponse schemas - Add DayOfWeekEnum, MonthOfYearEnum schema enums - Add POST /calendar/plans endpoint (create plan with hierarchy validation) - Add GET /calendar/plans endpoint (list plans, optional include_inactive) - Add GET /calendar/plans/{plan_id} endpoint (get single plan) - Mark BE-CAL-API-005 complete in TASKLIST.md	2026-03-31 14:46:45 +00:00
zhi	82331aeda2	BE-CAL-API-004: Implement Calendar cancel API for real and virtual slots - Add POST /calendar/slots/{slot_id}/cancel for real slot cancellation - Add POST /calendar/slots/virtual/{virtual_id}/cancel for virtual slot cancellation - Virtual cancel materializes the slot first, then marks as Skipped - Both endpoints enforce past-slot immutability guard - Both endpoints detach from plan (set plan_id=NULL) - Status set to SlotStatus.SKIPPED on cancel - Add TimeSlotCancelResponse schema - Import guard_cancel_real_slot and guard_cancel_virtual_slot	2026-03-31 12:47:56 +00:00
zhi	fb3fa0ca11	BE-CAL-API-003: implement Calendar edit API for real and virtual slots - Add TimeSlotEdit schema (partial update, all fields optional) - Add TimeSlotEditResponse schema - Add PATCH /calendar/slots/{slot_id} for editing real slots - Add PATCH /calendar/slots/virtual/{virtual_id} for editing virtual slots - Triggers materialization before applying edits - Detaches from plan after edit - Both endpoints enforce: - Past-slot immutability guard - Overlap detection (excluding self) - Plan detachment on edit - Workload warnings in response	2026-03-31 10:46:19 +00:00
zhi	cfed3a07ed	BE-CAL-API-002: Implement calendar day-view query API - Add GET /calendar/day endpoint with optional ?date= query param - Returns unified CalendarDayResponse merging real slots + virtual plan slots - New CalendarSlotItem schema supports both real (id) and virtual (virtual_id) slots - Excludes inactive slots (skipped/aborted) from results - All slots sorted by scheduled_at ascending	2026-03-31 07:19:01 +00:00
zhi	80afdd1c6a	BE-CAL-API-001: Update submodule ref + mark task complete	2026-03-31 05:46:03 +00:00
zhi	4309e3d39c	BE-CAL-API-001: Implement single slot creation API - Add TimeSlotCreate, TimeSlotResponse, TimeSlotCreateResponse schemas - Add SlotConflictItem, SlotTypeEnum, EventTypeEnum, SlotStatusEnum to schemas - Add POST /calendar/slots endpoint with: - Overlap detection (409 on conflict) - Workload warning computation (advisory, returned in response) - Support for event_type + event_data (job/system/entertainment) - Default date to today if not provided - Add _slot_to_response helper for ORM -> schema conversion	2026-03-31 05:45:51 +00:00
zhi	9deb1bf8d5	BE-CAL-007 + BE-CAL-008: mark completed, update Backend submodule	2026-03-31 04:16:58 +00:00
zhi	b14366ebd1	BE-CAL-006: mark overlap detection task complete in TASKLIST	2026-03-31 01:18:01 +00:00
zhi	bbe651c3e3	Update Backend submodule: BE-CAL-005 plan virtual-slot materialization	2026-03-30 23:47:15 +00:00
zhi	a5ec32656e	BE-CAL-005: Implement plan virtual-slot identification and materialization - Virtual slot ID: plan-{plan_id}-{YYYY-MM-DD} format with parse/make helpers - Plan-date matching: on_month/on_week/on_day hierarchy with week_of_month calc - Materialization: convert virtual slot to real TimeSlot row, copy plan template - Detach: clear plan_id after edit/cancel to break plan association - Bulk materialization: materialize_all_for_date for daily pre-compute - 23 tests covering all paths (matching, virtual gen, materialize, detach, bulk)	2026-03-30 23:46:51 +00:00
zhi	8b90c7d7f2	BE-CAL-004: update submodule pointer + mark task complete in TASKLIST	2026-03-30 22:27:15 +00:00
zhi	f984b6ddb4	BE-CAL-003: Agent model with status/heartbeat/exhausted fields (backend submodule)	2026-03-30 20:47:56 +00:00
zhi	6a4e7a7c0f	Mark BE-CAL-002 complete in TASKLIST.md	2026-03-30 19:16:33 +00:00
zhi	c33a1e7739	BE-CAL-001: Mark TimeSlot model task complete, update Backend submodule	2026-03-30 17:45:22 +00:00
zhi	963a5dc20d	BE-PR-011: Mark Proposal/Essential/Story restricted tests complete - Updated HarborForge.Backend submodule (test infra fix + 29 passing tests) - Marked BE-PR-011 complete in TASKLIST.md	2026-03-30 16:17:16 +00:00
zhi	63cb1d284d	BE-PR-010: clean up feat_task_id semantics — deprecate with read-only compat Decision: retain DB column, mark DEPRECATED. Existing rows still return feat_task_id via API. New accept flow (BE-PR-007) does not write it. Clients should migrate to generated_tasks / Task.source_proposal_id. - Backend: model/schema/router deprecation comments updated - Backend: added docs/BE-PR-010-feat-task-id-deprecation.md - Tests: updated to work with Essential-based accept flow - Tests: all 21 proposal tests pass - TASKLIST: BE-PR-010 marked complete	2026-03-30 12:50:14 +00:00
zhi	03c8b74968	BE-PR-009: restrict all story/* task types + fix test conftest imports	2026-03-30 11:46:28 +00:00
zhi	42703c2401	Mark BE-PR-008 complete in TASKLIST.md	2026-03-30 10:46:38 +00:00
zhi	97031a7a27	Update Backend submodule: BE-PR-008 tracking fields	2026-03-30 10:46:28 +00:00
zhi	45c8d43914	BE-PR-007: mark task complete, update Backend submodule ref	2026-03-30 07:46:28 +00:00
zhi	ce4ce6400f	Update Backend submodule ref for BE-PR-006	2026-03-30 07:16:34 +00:00
zhi	f9395fc41c	BE-PR-006: Add Essential CRUD API under Proposals - New router: /projects/{project_id}/proposals/{proposal_id}/essentials - GET (list) - list all essentials under a proposal - POST (create) - create essential with auto-generated EssentialCode - GET /{id} - get single essential by id or essential_code - PATCH /{id} - update essential (title, type, description) - DELETE /{id} - delete essential - All mutations restricted to open proposals only - Permission: creator, project owner, or global admin - Registered essentials router in main.py - Updated GET /proposals/{id} to return ProposalDetailResponse with embedded essentials list - Activity logging on all CRUD operations	2026-03-30 07:16:21 +00:00
zhi	d52cb44fec	Update Backend submodule ref for BE-PR-005	2026-03-30 06:45:30 +00:00
zhi	79b06f2d7d	BE-PR-005: Add Essential schema definitions (create/update/response) and ProposalDetailResponse with nested essentials	2026-03-30 06:45:06 +00:00
zhi	b1ddff0743	BE-PR-004: implement EssentialCode encoding rules (submodule update)	2026-03-30 06:16:05 +00:00
zhi	42c59ff62a	BE-PR-003: Update Backend submodule ref + mark task complete	2026-03-29 16:33:10 +00:00
zhi	e6c9459e22	BE-PR-003: Add Essential SQLAlchemy model - New app/models/essential.py with Essential model and EssentialType enum (feature, improvement, refactor) - Fields: id, essential_code (unique), proposal_id (FK to proposes), type, title, description, created_by_id (FK to users), created_at, updated_at - Added essentials relationship to Proposal model (cascade delete-orphan) - Added essentials table auto-migration in main.py _migrate_schema() - Registered essential module import in startup()	2026-03-29 16:32:40 +00:00
zhi	619bb07eed	chore: update Backend submodule pointer (BE-PR-002)	2026-03-29 16:02:22 +00:00
zhi	86758846bb	BE-PR-002: Proposal model naming & field adjustments - Add comprehensive docstring to Proposal model documenting all relationships - Add column comments for all fields (title, description, status, project_id, etc.) - Mark feat_task_id as DEPRECATED (will be replaced by Essential→task mapping in BE-PR-008) - Add proposal_code hybrid property as preferred alias for DB column propose_code - Update ProposalResponse schema to include proposal_code alongside propose_code - Update serializer to emit both proposal_code and propose_code for backward compat - No DB migration needed — only Python-level changes	2026-03-29 16:02:07 +00:00
zhi	48e52e3419	BE-PR-001: Rename Propose -> Proposal across backend - Backend: new canonical Proposal model + /proposals router - Backward-compat shims for old Propose imports and /proposes API - Tests updated to use /proposals, legacy compat tests added - Impact checklist: docs/BE-PR-001-rename-impact.md - TASKLIST.md: BE-PR-001 marked complete All 21 proposal tests pass.	2026-03-29 15:35:59 +00:00
zhi	0b9767d4a6	DOC-003: 整理 Calendar 验收清单 - 后端验收项: 数据模型、Slot ID 策略与物化、验证规则、不可变性、Calendar API、Agent/心跳协作 - 前端验收项: 页面骨架、日程展示、计划展示、操作交互、状态提示、权限 - CLI 验收项: 命令组、日程/计划操作命令、输出格式、用户创建扩展 - 插件联动验收项: 心跳请求、唤醒逻辑、状态管理、ScheduledGatewayRestart - 跨模块集成验收项	2026-03-29 15:01:35 +00:00
zhi	ba1349bad4	DOC-002: Proposal/Essential/Story restricted migration guide - Document Propose → Proposal naming changes across all layers - Document Proposal Accept semantic change (single task → Essential-based batch) - Document story/* restricted expansion and impact analysis - Document feat_task_id deprecation and backward compatibility strategy - Document migration execution order and rollback plan	2026-03-29 14:32:23 +00:00
zhi	becfc7d719	DOC-001: 整理本波开发范围说明 - 明确 Calendar 为独立功能线，Proposal/Essential 为项目结构调整线 - 明确两条线交叉点仅限 event_data / Agent 调度引用层 - 区分必须本波完成 vs 仅设计保留内容 - 新增 docs/wave-2026-03-scope.md	2026-03-29 14:01:10 +00:00
hzhang	835605aa42	Merge pull request 'chore/archive-plans-and-next-wave-doc' (#6 ) from chore/archive-plans-and-next-wave-doc into main Reviewed-on: #6	2026-03-29 11:45:01 +00:00