docs: move plans into archive and place next wave doc under plans

2026-03-29 11:19:33 +00:00
parent c2b9242aca
commit b416c60ae7
7 changed files with 0 additions and 0 deletions
--- a/plans/NEXT_WAVE_DEV_DIRECTION.md
+++ b/plans/NEXT_WAVE_DEV_DIRECTION.md
@@ -0,0 +1,382 @@
+# HarborForge Calendar System — Design Document
+
+> Date: 2026-03-22
+
+---
+
+## Overview
+
+为 HarborForge 新增日程表（Calendar）系统，支持 Agent/人类用户的任务调度、周期性计划、以及通过 OpenClaw 插件心跳自动唤醒 Agent 执行日程。
+
+同时记录一项项目结构调整：
+- Propose 改名为 Proposal
+- Proposal Accept 不再生成单个 Feature Task
+- 改为在 Proposal 下维护多个 Essential；Accept 时将该 Proposal 下所有 Essential 按类型生成对应的 story task，并落到 Proposal 选择的 Milestone
+- story 整个大类改为 restricted，只允许通过 Proposal Accept 创建
+- Essential 拥有独立的 EssentialCode，编码风格参考 ProjectCode / TaskCode 等既有结构
+
+同时包含一个 bug fix：acc-mgr 用户密码不可修改，前端隐藏修改密码入口。
+
+---
+
+## 一、数据模型
+
+### 1.1 TimeSlot（日程槽）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| slot_id | int (PK) | 已物化 slot 的数据库 ID |
+| user_id | FK -> users.id | 所属用户 |
+| date | date | 日期 |
+| slot_type | Enum(Work, OnCall, Entertainment, System) | 槽类型 |
+| estimated_duration | int (1-50) | 预估时长（分钟），设计上限 50 分钟，超过需拆分 |
+| scheduled_at | time (00:00-23:00) | 计划开始时间 |
+| started_at | time, nullable | 实际开始时间 |
+| attended | bool, default false | 是否已出席 |
+| actual_duration | int (0-65535), nullable | 实际时长（分钟），无上限 |
+| event_type | Enum(Job, Entertainment, SystemEvent), nullable | 事件类型 |
+| event_data | JSON, nullable | 事件详情（见下方 Event 子类型） |
+| priority | int (0-99) | 优先级 |
+| status | Enum(NotStarted, Ongoing, Deferred, Skipped, Paused, Finished, Aborted) | 状态 |
+| plan_id | FK -> schedule_plans.id, nullable | 来源计划（物化自 plan 时填入，被 edit/cancel 后置 NULL） |
+| created_at | datetime | 创建时间 |
+| updated_at | datetime | 更新时间 |
+
+### 1.2 Event 子类型（存储在 event_data JSON 中）
+
+**Job:**
+```json
+{
+  "type": "Task|Support|Meeting|Essential",
+  "code": "TASK-42",
+  "working_sessions": ["session-id-1", "session-id-2"]
+}
+```
+
+**SystemEvent:**
+```json
+{
+  "event": "ScheduleToday|SummaryToday|ScheduledGatewayRestart"
+}
+```
+
+- `ScheduleToday` — 每日日程规划
+- `SummaryToday` — 每日总结
+- `ScheduledGatewayRestart` — OpenClaw 网关计划重启前触发；插件收到后应持久化状态、发送最终心跳、暂停定时任务
+
+**Entertainment:**
+```
+待设计
+```
+
+### 1.3 SchedulePlan（周期性计划）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | int (PK) | plan-id |
+| user_id | FK -> users.id | 所属用户 |
+| slot_type | Enum(Work, OnCall, Entertainment, System) | 槽类型 |
+| estimated_duration | int (1-50) | 预估时长 |
+| event_type | Enum(Job, Entertainment, SystemEvent), nullable | 事件类型 |
+| event_data | JSON, nullable | 事件详情 |
+| at_time | time | 每天的计划时间 (--at HH:mm) |
+| on_day | Enum(Sun, Mon, Tue, Wed, Thu, Fri, Sat), nullable | 星期几 (--on-day) |
+| on_week | int (1-4), nullable | 第几周 (--on-week) |
+| on_month | Enum(Jan-Dec), nullable | 月份 (--on-month) |
+| created_at | datetime | 创建时间 |
+| updated_at | datetime | 更新时间 |
+
+**周期参数层级约束：**
+- 使用 `--on-month` 则 `--on-week` 必须也用
+- 使用 `--on-week` 则 `--on-day` 必须也用
+- `--at` 始终必填
+
+**示例：**
+- `--at 09:00 --on-day Sun --on-week 1 --on-month Jan` → 每年一月第一周周日 09:00
+- `--at 09:00 --on-day Sun --on-week 1` → 每月第一周周日 09:00
+- `--at 09:00 --on-day Sun` → 每周日 09:00
+- `--at 09:00` → 每天 09:00
+
+### 1.4 Agent 表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | int (PK) | |
+| user_id | FK -> users.id, UNIQUE | 关联用户 |
+| agent_id | VARCHAR, UNIQUE | OpenClaw agent name ($AGENT_ID) |
+| claw_identifier | VARCHAR | OpenClaw 实例 identifier（与 Monitor 碰巧一致，无 FK） |
+| status | Enum(Idle, OnCall, Busy, Exhausted, Offline), default Idle | Agent 当前状态 |
+| last_heartbeat | datetime, nullable | 最后心跳时间 |
+| created_at | datetime | 创建时间 |
+
+### 1.5 MinimumWorkload（最小工作量配置）
+
+```json
+{
+  "daily":   { "work": 0, "on_call": 0, "entertainment": 0 },
+  "weekly":  { "work": 0, "on_call": 0, "entertainment": 0 },
+  "monthly": { "work": 0, "on_call": 0, "entertainment": 0 },
+  "yearly":  { "work": 0, "on_call": 0, "entertainment": 0 }
+}
+```
+值为分钟数 (0-65535)。存储方式待定（可作为用户级配置存 JSON 字段或独立表）。
+
+---
+
+## 二、Slot ID 策略
+
+- **已物化的 slot**：使用数据库自增 ID
+- **Plan 虚拟 slot**（未物化）：使用 `plan-{plan_id}-{date}` 格式
+- 当虚拟 slot 被 `edit` 或 `cancel` 时，物化到数据库，获得真实 ID，同时该日期该 plan 不再生成虚拟 slot
+
+---
+
+## 三、存储与缓存策略
+
+### 3.1 Plan 不预展开
+
+Plan 只存规则，不为每一天生成数据行。
+
+### 3.2 物化时机
+
+以下情况写入 time_slots 表：
+1. `hf calendar schedule` 手动创建
+2. Plan 的虚拟 slot 被 `edit` 或 `cancel`（物化后断开 plan 关联）
+3. 每天预计算：服务器每日将当天所有 plan 匹配的 slot 物化到缓存/数据库
+
+### 3.3 当日缓存
+
+- 每天（凌晨或首次心跳时）预计算当天所有 plan → 物化为当日 slot 缓存
+- 当天新增 `schedule` / `plan-schedule` 影响当天时，同步更新缓存
+
+### 3.4 不可变性
+
+- `cancel` / `edit` 不能操作过去的 slot
+- `plan-cancel` / `plan-edit` 不追溯过去已物化的 slot
+
+---
+
+## 四、时区
+
+统一使用 HarborForge 服务器时区，不做用户级时区。
+
+---
+
+## 五、验证规则
+
+`schedule` / `plan-schedule` 提交时验证：
+1. **Overlap 检测**：与同日已有 slot 时间重叠 → **拒绝，报错**
+2. **最小工作量检查**：不满足 MinimumWorkload 配置 → **警告，但允许提交**
+
+---
+
+## 六、Agent 唤醒机制
+
+### 6.1 心跳流程
+
+1. 插件每分钟向 HarborForge 服务器发送心跳
+2. 服务器返回该插件（claw_identifier）对应所有 Agent 当前需要执行的日程
+   - 筛选条件：当天 slot，status 为 NotStarted 或 Deferred，scheduled_at 已过
+3. 插件检查 Agent 状态
+
+### 6.2 唤醒逻辑
+
+**Agent 状态为 Idle：**
+- 唤醒 Agent，提供提示词开始工作
+- 向服务器设置 Agent status = Busy 或 OnCall（取决于 slot_type）
+- 设置 slot: attended = true, started_at = now, status = Ongoing
+
+**Agent 状态非 Idle：**
+- 设置 slot status = Deferred
+
+### 6.3 多 Slot 竞争
+
+- 选 priority 最高的执行，其余 Deferred 且 priority += 1
+- 通知 Agent 当前任务完成后重新规划所有 Deferred + NotStarted 的 slot
+
+### 6.4 状态转移
+
+| 触发条件 | Agent Status 变化 |
+|---------|-----------------|
+| 超过 2 分钟无心跳 | → Offline |
+| 无待执行日程 | → Idle |
+| 被 TimeSlot 唤醒 | → Busy / OnCall |
+| 完成 TimeSlot | → Idle |
+| API rate-limit 或 billing 错误 | → Exhausted |
+| Exhausted 恢复计时器到期 | → Idle |
+
+### 6.5 Exhausted 状态详细规则
+
+**前提：** 所有 Agent 只使用一个主模型，没有 fallback 模型。
+
+**进入条件：**
+- Agent 调用 LLM API 时收到 rate-limit 错误（HTTP 429 等）
+- Agent 调用 LLM API 时收到 billing 相关错误（额度不足、配额耗尽等）
+
+**恢复逻辑：**
+- 解析错误信息，查找类似 `reset in X mins`、`retry after X`、`resets at <timestamp>` 的模式
+- 如果能解析出时间 → 设置 **X 分钟** 后恢复为 Idle
+- 如果无法解析 → 默认 **5 小时** 后恢复为 Idle
+
+**Exhausted 期间行为：**
+- Agent 视为不可用，不被心跳唤醒
+- 待执行的 slot 设为 Deferred
+- 前端/Monitor 显示 Exhausted 状态 + 预计恢复时间
+
+**Agent 表扩展字段：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| exhausted_at | datetime, nullable | 进入 Exhausted 的时间 |
+| recovery_at | datetime, nullable | 预计恢复时间 |
+| exhaust_reason | Enum(RateLimit, Billing), nullable | 原因 |
+
+---
+
+## 七、CLI 命令
+
+### 7.1 日程操作
+
+```bash
+# 创建单次日程
+hf calendar schedule <slot-type> <scheduled-at> <estimated-duration> \
+  [--job <code>] [--date <yyyy-mm-dd>]
+
+# 查看某天日程
+hf calendar show [--date <yyyy-mm-dd>]
+
+# 取消日程（plan 来源的 slot 物化后断开 plan）
+hf calendar cancel [--date <yyyy-mm-dd>] <slot-id>
+
+# 编辑日程（plan 来源的 slot 物化后断开 plan）
+hf calendar edit [--date <yyyy-mm-dd>] <slot-id> \
+  [--slot-type <type>] [--estimated-duration <mins>] \
+  [--job <code>] [--scheduled-at <HH:mm>]
+
+# 列出所有有已物化日程的未来日期（纯 plan 的不算）
+hf calendar date-list
+```
+
+### 7.2 计划操作
+
+```bash
+# 创建周期性计划
+hf calendar plan-schedule <slot-type> <estimated-duration> \
+  --at <HH:mm> [--on-day <day>] [--on-week <1-4>] [--on-month <month>]
+
+# 列出所有计划
+hf calendar plan-list
+
+# 取消计划（不追溯过去）
+hf calendar plan-cancel <plan-id>
+
+# 编辑计划（不追溯过去）
+hf calendar plan-edit <plan-id> \
+  [--at <HH:mm>] [--on-day <day>] [--on-week <1-4>] [--on-month <month>] \
+  [--slot-type <type>] [--estimated-duration <mins>]
+```
+
+### 7.3 用户创建（Agent 支持）
+
+```bash
+hf user create <username> [--agent-id <id>] [--claw-identifier <id>] ...
+```
+
+- `--agent-id` + `--claw-identifier` 必须同时出现或同时不出现
+- pcexec 模式下：
+  - `--agent-id` ← `$AGENT_ID`
+  - `--claw-identifier` ← `openclaw config get plugins.harbor-forge.identifier`
+- 后端 `POST /users` 扩展：接受 `agent_id` + `claw_identifier`，创建 User 同时写入 agents 表
+
+---
+
+## 八、项目结构调整记录（与 Calendar 相关联的设计备注）
+
+### 8.1 命名调整
+
+- `Propose` 统一改名为 `Proposal`
+
+### 8.2 新结构
+
+```text
+Project
+└─ Proposal
+   ├─ Essential
+   │  ├─ feature
+   │  ├─ improvement
+   │  └─ refactor
+   └─ accept -> 将该 Proposal 下所有 Essential 生成对应类型的 story task，并创建到 Proposal 选择的 Milestone
+```
+
+### 8.3 Proposal Accept 语义变更
+
+旧行为：
+- Proposal Accept 后生成单个 `story/feature` task
+
+新行为：
+- Proposal Accept **不再生成单个 Feature Task**
+- 每个 Proposal 可维护多个 Essential
+- Accept 时，遍历该 Proposal 下全部 Essential
+- 按 Essential 类型映射生成对应的 story task：
+  - `feature` -> `story/feature`
+  - `improvement` -> `story/improvement`
+  - `refactor` -> `story/refactor`
+- 生成目标 Milestone 由 Proposal 在 Accept 前或 Accept 时明确选择
+
+### 8.4 Story 创建限制
+
+- `story` 整个大类视为 **restricted**
+- 任何 `story/*` task 都不允许通过通用 task create endpoint 直接创建
+- `story` 仅允许通过 `Proposal Accept` 工作流生成
+
+### 8.5 Essential
+
+新增 `Essential` 概念，用于承载 Proposal 下的可落地核心条目。
+
+建议字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | int (PK) | |
+| essential_code | VARCHAR(64), UNIQUE | EssentialCode，风格参考 ProjectCode / TaskCode / MilestoneCode / ProposalCode |
+| proposal_id | FK -> proposals.id | 所属 Proposal |
+| type | Enum(feature, improvement, refactor) | Essential 类型 |
+| title | VARCHAR(255) | 标题 |
+| description | TEXT, nullable | 描述 |
+| created_by_id | FK -> users.id, nullable | 创建人 |
+| created_at | datetime | 创建时间 |
+| updated_at | datetime | 更新时间 |
+
+### 8.6 代码生成
+
+- `Essential` 拥有独立 `EssentialCode`
+- 编码规则参考现有类似结构，例如：
+  - `ProjectCode`
+  - `MilestoneCode`
+  - `TaskCode`
+  - `ProposalCode`
+- 具体前缀与编号策略待后续单独定稿
+
+## 九、前端
+
+- 每个用户可查看/调整自己的日程表
+- Admin 可查看/调整所有用户的日程表
+- 日程表页面展示（具体 UI 待设计）
+
+---
+
+## 十、Bug Fix
+
+- acc-mgr 用户：后端禁止修改密码（admin 也不行）
+- 前端：acc-mgr 用户不显示修改密码入口
+
+---
+
+## 十一、待定项
+
+- Entertainment 事件子类型设计
+- MinimumWorkload 存储方式（JSON 字段 vs 独立表）
+- 前端日程表 UI 详细设计
+- Agent 唤醒的提示词模板
+- Proposal / Essential 的详细数据模型、API、前端页面与 accept 流程实现细节
+- Story restricted 后，现有 task create / propose accept / milestone flow 的兼容迁移策略
--- a/plans/automation/cron/hf-bootstrap-2026-03-21-state.json
+++ b/plans/automation/cron/hf-bootstrap-2026-03-21-state.json
@@ -1,5 +0,0 @@
-{
-  "wakeCount": 4,
-  "createdAt": "2026-03-21T12:25:00Z",
-  "updatedAt": "2026-03-21T13:29:00Z"
-}
--- a/plans/automation/cron/hf-bootstrap-2026-03-21.prompt.md
+++ b/plans/automation/cron/hf-bootstrap-2026-03-21.prompt.md
@@ -1,54 +0,0 @@
-你是 developer agent 的一个 15 分钟编排 cron 任务。
-
-请在每次被唤醒时，维护并读取下面这个状态文件：
-`/root/.openclaw/workspace/workspace-developer/HarborForge/plans/automation/cron/hf-bootstrap-2026-03-21-state.json`
-
-规则：
-1. 读取 `wakeCount`。
-2. 将其 +1 并写回文件。
-3. 根据新的 wakeCount 执行对应动作。
-4. 每次执行结束后，向 Discord 频道 `1474327736242798612` announce 汇报执行结果。
-
-动作定义：
-
-## 第 1 次唤醒
-执行：
- 把 HarborForge 主仓和所有子模块从 `main` 拉取最新代码
- 给所有子模块创建开发分支：`dev-2026-03-21`
- 如分支已存在，则切换到该分支并确保它基于最新 main
-
-## 第 2 次唤醒
-执行：
- 创建第二个 cron 定时任务：`hf-dev-kimi-2026-03-21`
- 频率：每 30 分钟一次
- agent：`developer`
- model：`kimi-coding/k2p5`
- session：`isolated`
- announce：开启
- channel：`discord`
- to：`1474327736242798612`
- message 内容使用文件：
-  `/root/.openclaw/workspace/workspace-developer/HarborForge/plans/automation/cron/hf-dev-kimi-2026-03-21.prompt.md`
- 如果同名任务已存在，则不要重复创建
-
-## 第 3 次唤醒
-执行：
- 创建第三个 cron 定时任务：`hf-dev-opus-2026-03-21`
- 频率：每 30 分钟一次
- agent：`developer`
- model：`anthropic/claude-opus-4-6`
- 其余参数与第二个任务完全一致
- message 内容使用文件：
-  `/root/.openclaw/workspace/workspace-developer/HarborForge/plans/automation/cron/hf-dev-opus-2026-03-21.prompt.md`
- 如果同名任务已存在，则不要重复创建
-
-## 第 4 次唤醒
-执行：
- 删除你自己这个 cron 定时任务
- 先通过 `openclaw cron list --json` 找到名称为 `hf-bootstrap-2026-03-21` 的 job id
- 然后执行 `openclaw cron remove <jobId>`
-
-额外要求：
- 执行中可以使用 shell / openclaw CLI 完成 cron 管理
- 如果某一步失败，要在 announce 中说明失败原因
- 不要跳步；严格按 wakeCount 对应动作执行
--- a/plans/automation/cron/hf-dev-kimi-2026-03-21.prompt.md
+++ b/plans/automation/cron/hf-dev-kimi-2026-03-21.prompt.md
@@ -1,25 +0,0 @@
-你是 developer agent 的一个 cron 定时开发任务。
-
-目标：参考 HarborForge 主仓中的开发计划与 TODO list，寻找当前可以推进的任务并进行开发。
-
-严格要求：
-1. 工作目录以 `/root/.openclaw/workspace/workspace-developer/HarborForge` 为主。
-2. 优先参考：
-   - `plans/harborforge-cli-go-plan.md`
-   - `plans/hf-cross-project-todo.md`
-3. 只做当前明确可推进的任务，不要凭空发散。
-4. 无需做 Test 子模块下的复杂测试。
-5. 尤其禁止运行：`run-test-frontend`。
-6. 可以做轻量验证，例如：编译、lint、py_compile、类型检查、局部单测、静态检查等。
-7. 每次完成后，把所有脏模块分别提交并 push 到分支：`dev-2026-03-21`。
-8. 如果发现 todo list 中所有待办都已完成，则删除你自己这个 cron 定时任务。
-   - 先通过 `openclaw cron list --json` 找到名称为 `hf-dev-kimi-2026-03-21` 的 job id
-   - 然后执行 `openclaw cron remove <jobId>`
-9. 每次运行结束前，给 Discord 频道 `1474327736242798612` 做 announce 汇报。
-
-建议汇报内容：
- 本次选择的 TODO
- 修改了哪些子模块
- 做了哪些轻量验证
- push 了哪些分支/提交
- 是否发现阻塞
--- a/plans/automation/cron/hf-dev-opus-2026-03-21.prompt.md
+++ b/plans/automation/cron/hf-dev-opus-2026-03-21.prompt.md
@@ -1,25 +0,0 @@
-你是 developer agent 的一个 cron 定时开发任务。
-
-目标：参考 HarborForge 主仓中的开发计划与 TODO list，寻找当前可以推进的任务并进行开发。
-
-严格要求：
-1. 工作目录以 `/root/.openclaw/workspace/workspace-developer/HarborForge` 为主。
-2. 优先参考：
-   - `plans/harborforge-cli-go-plan.md`
-   - `plans/hf-cross-project-todo.md`
-3. 只做当前明确可推进的任务，不要凭空发散。
-4. 无需做 Test 子模块下的复杂测试。
-5. 尤其禁止运行：`run-test-frontend`。
-6. 可以做轻量验证，例如：编译、lint、py_compile、类型检查、局部单测、静态检查等。
-7. 每次完成后，把所有脏模块分别提交并 push 到分支：`dev-2026-03-21`。
-8. 如果发现 todo list 中所有待办都已完成，则删除你自己这个 cron 定时任务。
-   - 先通过 `openclaw cron list --json` 找到名称为 `hf-dev-opus-2026-03-21` 的 job id
-   - 然后执行 `openclaw cron remove <jobId>`
-9. 每次运行结束前，给 Discord 频道 `1474327736242798612` 做 announce 汇报。
-
-建议汇报内容：
- 本次选择的 TODO
- 修改了哪些子模块
- 做了哪些轻量验证
- push 了哪些分支/提交
- 是否发现阻塞
--- a/plans/harborforge-cli-go-plan.md
+++ b/plans/harborforge-cli-go-plan.md
--- a/plans/hf-cross-project-todo.md
+++ b/plans/hf-cross-project-todo.md
@@ -1,430 +0,0 @@
-# hf / HarborForge Cross-Project TODO
-
-> Scope: HarborForge.Cli, HarborForge.Backend, HarborForge.Frontend, HarborForge.OpenclawPlugin, HarborForge.Monitor, HarborForge.Test
->
-> Goal: land the new `hf` CLI and the supporting backend/frontend/plugin/monitor changes described in the main CLI plan.
-
---
-
-## 0. Cross-cutting / coordination
-
- [x] Finalize MVP scope for first shipping version of `hf`
-  - MVP includes: all CRUD commands for users, roles, projects, milestones, tasks, meetings, support, proposals, monitor
-  - Permission-aware help system, padded-cell/manual mode, code-first resource addressing
-  - Plugin installer `--install-cli` for automated deployment
- [x] Confirm which existing backend routes can be reused vs which new routes are needed
- [x] Define canonical code-first lookup policy across all resources
- [x] Define permission introspection strategy for `--help` / `--help-brief`
-  - settled as: token → current user → user role → role permissions
-  - `hf user create` remains a special account-manager-token flow and is not gated by ordinary user-token write permission
- [x] Define JSON output contract for CLI list/get commands
-  - current CLI contract: `--json` emits raw success payloads on stdout without a universal envelope; list/get responses should preserve canonical code-bearing fields when backend payloads provide them
- [x] Define CLI exit code / stderr conventions
-  - current CLI contract: success exits `0`; validation/runtime failures exit `1`; errors go to stderr and successful output goes to stdout
- [x] Define local plugin↔monitor communication protocol over `monitor_port`
-  - Monitor exposes `GET /health`, `GET /telemetry`, `POST /openclaw` on 127.0.0.1:MONITOR_PORT
-  - Plugin pushes OpenClaw metadata via POST /openclaw; Monitor enriches heartbeats with received data
-  - All communication is optional/degradable — both sides function independently
- [x] Define release order across submodules
-  - 1. Backend (code-first APIs, permission introspection)
-  - 2. CLI (depends on backend API surface)
-  - 3. Frontend (code-first UI, independent of CLI)
-  - 4. Monitor (standalone, bridge is optional)
-  - 5. Plugin (depends on CLI build for --install-cli, depends on Monitor for bridge)
- [x] Define rollback strategy if plugin / monitor bridge is unavailable
-  - Graceful degradation: Monitor operates normally without plugin data
-  - Plugin operates normally without Monitor bridge
-  - No hard dependency in either direction — bridge is optional enrichment
-
-> Note: the CLI contract items above are now documented from the currently implemented `HarborForge.Cli` behavior; they can still be refined later if a stricter release contract is needed.
-
---
-
-## 1. HarborForge.Cli
-
-### 1.1 Go project scaffold
- [x] Initialize Go module for `hf`
- [x] Add binary entrypoint (`cmd/hf/main.go` or equivalent)
- [x] Add internal package layout (`config`, `help`, `mode`, `passmgr`, `client`, `commands`)
- [x] Add build instructions to `README.md`
- [x] Add `.gitignore` for Go artifacts
- [x] Add repo-config-safe contribution note if needed
-  - CLI README already contains build/run/install docs; no separate contribution note needed for current scope
-
-### 1.2 Runtime mode detection
- [x] Implement `which pass_mgr` detection on startup
- [x] Add runtime mode enum: padded-cell mode / manual mode
- [x] Block manual credential flags in padded-cell mode
- [x] Return exact error when forbidden manual token flags are used:
-  - [x] `padded-cell installed, --token flag disabled, use command directly`
- [x] Define equivalent handling for `--acc-mgr-token` and related manual secret flags
-
-### 1.3 Config handling
- [x] Resolve binary directory correctly at runtime
- [x] Read `<binary-dir>/.hf-config.json`
- [x] Write/update `base-url` via `hf config --url`
- [x] Add config validation for malformed/missing config
- [x] Add `hf config --acc-mgr-token`
- [x] Implement `pass_mgr set --public --key hf-acc-mgr-token --secret <token>`
- [x] Return exact error on failure:
-  - [x] `--acc-mgr-token can only be set with padded-cell plugin`
-
-### 1.4 Help system
- [x] Implement `hf --help`
- [x] Implement `hf --help-brief`
- [x] Implement `<group> --help`
- [x] Implement `<group> --help-brief`
- [x] Implement leaf command `--help`
- [x] Implement leaf command `--help-brief`
- [x] Show all subcommands in normal help, marking unavailable ones as `(not permitted)`
- [x] Hide unavailable commands entirely in `--help-brief`
- [x] Ensure leaf `--help` for unavailable commands only prints `not permitted`
- [x] Hide manual auth flags from help in padded-cell mode
- [x] Show required manual auth flags in help in manual mode
- [x] Handle special help behavior for `hf user create`
-
-### 1.5 Auth/token resolution layer
- [x] Implement shared normal token resolution helper
- [x] In padded-cell mode, resolve via `pass_mgr get-secret --key hf-token`
- [x] In manual mode, require explicit `--token`
- [x] Emit exact error on missing manual token:
-  - [x] `--token <token> required or execute this with pcexec`
- [x] Ensure `hf --help` never requires token
- [x] Ensure subcommand help can render even when token is unavailable
-
-### 1.6 Output model
- [x] Add default human-readable output mode
- [x] Add `--json` output mode
- [x] Ensure list outputs include canonical resource code fields
- [x] Ensure machine-readable output is stable enough for agent use
-
-### 1.7 Base commands
- [x] Implement `hf version`
- [x] Implement `hf health`
-
-### 1.8 User commands
- [x] Implement `hf user create`
- [x] Forbid `--token` on `hf user create`
- [x] Do not support `--role` on `hf user create`
- [x] Default created accounts to `guest`
- [x] In padded-cell mode, auto-generate password with:
-  - [x] `pass_mgr generate --key hf --username <username>`
- [x] In padded-cell mode, auto-fetch account-manager token with:
-  - [x] `pass_mgr get-secret --public --key hf-acc-mgr-token`
- [x] Emit exact missing-password error:
-  - [x] `--pass <password> required or execute with pcexec`
- [x] Emit exact missing-account-manager-token error:
-  - [x] `--acc-mgr-token <token> required or execute with pcexec`
- [x] Implement `hf user list`
- [x] Implement `hf user get <username>`
- [x] Implement `hf user update <username>`
- [x] Implement `hf user activate <username>`
- [x] Implement `hf user deactivate <username>`
- [x] Implement `hf user delete <username>`
-
-### 1.9 Role / permission commands
- [x] Implement `hf role list`
- [x] Implement `hf role get <role-name>`
- [x] Implement `hf role create`
- [x] Implement `hf role update`
- [x] Implement `hf role delete`
- [x] Implement `hf permission list`
- [x] Implement `hf role set-permissions`
- [x] Implement `hf role add-permissions`
- [x] Implement `hf role remove-permissions`
-
-### 1.10 Project / milestone commands
- [x] Implement `hf project list`
- [x] Implement `hf project get <project-code>`
- [x] Implement `hf project create`
- [x] Implement `hf project update <project-code>`
- [x] Implement `hf project delete <project-code>`
- [x] Implement `hf project members <project-code>`
- [x] Implement `hf project add-member <project-code>`
- [x] Implement `hf project remove-member <project-code>`
- [x] Implement `hf milestone list --project <project-code>`
- [x] Implement `hf milestone get <milestone-code>`
- [x] Implement `hf milestone create`
- [x] Implement `hf milestone update <milestone-code>`
- [x] Implement `hf milestone delete <milestone-code>`
- [x] Implement `hf milestone progress <milestone-code>`
-
-### 1.11 Task commands
- [x] Implement `hf task list`
- [x] Add filters:
-  - [x] `--project <project-code>`
-  - [x] `--milestone <milestone-code>`
-  - [x] `--status <status>`
-  - [x] `--taken-by <me|null|username>`
-  - [x] `--due-today <true|false>`
-  - [x] repeated `--order-by <due-date|priority|created|name>`
- [x] Implement `hf task get <task-code>`
- [x] Implement `hf task create`
- [x] Implement `hf task update <task-code>`
- [x] Implement `hf task transition <task-code> <status>`
- [x] Implement `hf task take <task-code>`
- [x] Return clear error when task is already taken by someone else
- [x] Return clear error when caller lacks permission to take task
- [x] Implement `hf task delete <task-code>`
- [x] Implement `hf task search`
-
-### 1.12 Meeting commands
- [x] Implement `hf meeting list`
- [x] Implement `hf meeting get <meeting-code>`
- [x] Implement `hf meeting create`
- [x] Implement `hf meeting update <meeting-code>`
- [x] Implement `hf meeting attend <meeting-code>`
- [x] Ensure attend adds caller to participant list
- [x] Implement `hf meeting delete <meeting-code>`
-
-### 1.13 Support commands
- [x] Implement `hf support list`
- [x] Implement `hf support get <support-code>`
- [x] Implement `hf support create`
- [x] Implement `hf support update <support-code>`
- [x] Implement `hf support take <support-code>`
- [x] Implement `hf support transition <support-code> <status>`
- [x] Implement `hf support delete <support-code>`
-
-### 1.14 Propose commands
- [x] Implement `hf propose list --project <project-code>`
- [x] Implement `hf propose get <propose-code>`
- [x] Implement `hf propose create`
- [x] Implement `hf propose update <propose-code>`
- [x] Implement `hf propose accept <propose-code> --milestone <milestone-code>`
- [x] Implement `hf propose reject <propose-code>`
- [x] Implement `hf propose reopen <propose-code>`
-
-### 1.15 Monitor commands
- [x] Implement `hf monitor overview`
- [x] Implement `hf monitor server list`
- [x] Implement `hf monitor server get <identifier>`
- [x] Implement `hf monitor server create --identifier <identifier>`
- [x] Implement `hf monitor server delete <identifier>`
- [x] Implement `hf monitor api-key generate <identifier>`
- [x] Implement `hf monitor api-key revoke <identifier>`
-
-### 1.16 CLI packaging / release
- [x] Add cross-platform build targets if needed
- [x] Add release artifact naming for `hf`
- [x] Add install documentation
- [x] Add shell examples for padded-cell and manual mode
-
---
-
-## 2. HarborForge.Backend
-
-### 2.1 Code-first API support
- [x] Audit all CLI-targeted resources for code availability
- [x] Ensure `project-code` is accepted in get/update/delete/member APIs
- [x] Ensure `milestone-code` is accepted in get/update/delete/progress APIs
- [x] Ensure `task-code` is accepted in get/update/delete/transition APIs
- [x] Ensure `meeting-code` is accepted in get/update/delete/attend APIs
- [x] Ensure `support-code` is accepted in get/update/delete/take/transition APIs
- [x] Ensure `propose-code` is accepted in get/update/delete/accept/reject/reopen APIs
- [x] Add code-based list filters where missing
- [x] Ensure CLI-related list payloads always include canonical code fields
-
-### 2.2 User / account-manager flow
- [x] Review current `account-manager` permission implementation
- [x] Add dedicated backend flow for account-manager-based account creation if current `/users` route is insufficient
- [x] Ensure `hf user create` maps cleanly to backend account-manager permission model
- [x] Ensure new accounts default to `guest`
- [x] Ensure admin role cannot be assigned through normal user management APIs
-
-### 2.3 Permission introspection for CLI help
- [x] Decide how CLI will query effective permissions
- [x] Add/extend backend endpoint(s) for current-user permission introspection if needed
- [x] Ensure CLI can cheaply determine whether a subcommand is permitted
- [x] Support permission-aware help rendering without excessive API chattiness
-
-### 2.4 Task / meeting / support actions
- [x] Add/confirm backend route for task self-assignment (`task take`)
- [x] Add/confirm conflict behavior when task already has a different assignee
- [x] Add/confirm backend route for meeting attendance (`meeting attend`)
- [x] Ensure meeting attendance updates participant list
- [x] Add/confirm backend route for support self-assignment (`support take`)
-
-### 2.5 Frontend-facing code migration support
- [x] Add code-based detail endpoints or code query support for frontend routing
- [x] Ensure frontend can resolve resources by code without fallback to id-only APIs
- [x] Update serializers to expose code prominently wherever applicable
-
-### 2.6 Legacy Python CLI retirement
- [x] Track parity between new `hf` CLI and old backend Python CLI
- [x] Once parity is acceptable, remove legacy Python CLI from backend repo
- [x] Remove backend docs referencing the old Python CLI
-
---
-
-## 3. HarborForge.Frontend
-
-### 3.1 Code-first UI migration
- [x] Audit current routes and identify every place still using raw ids
- [x] Move project detail lookup toward `project-code`
- [x] Move milestone detail lookup toward `milestone-code`
- [x] Move task detail lookup toward `task-code`
- [x] Move meeting detail lookup toward `meeting-code`
- [x] Move support detail lookup toward `support-code`
- [x] Move propose detail lookup toward `propose-code`
- [x] Stop surfacing raw ids as the main visible identifier in lists/details
- [x] Display codes consistently in relevant list and detail views
-
-### 3.2 User / role UX alignment
- [x] Review current user management page against final backend behavior
- [x] Ensure only code/name-first identifiers are shown where relevant
- [x] Ensure account role display matches single-role model everywhere
-
-### 3.3 Meeting / support UI
- [x] Audit current frontend support for meeting resources
- [x] Add/adjust UI for meeting participant state if needed
- [x] Add/adjust UI for support take/ownership state if needed
-
-### 3.4 Monitor UI alignment
- [x] Ensure monitor views expose server identifier/code cleanly
- [ ] Review display of OpenClaw/plugin metadata once Monitor bridge is deployed
-
-### 3.5 Future CLI alignment aids
- [x] Consider showing canonical codes more prominently to help users map UI↔CLI
- [x] Ensure copyable resource codes are easy to find from the UI
-
---
-
-## 4. HarborForge.OpenclawPlugin
-
-### 4.1 Plugin identity and packaging
- [x] Rename plugin registration name to `harbor-forge`
- [x] Audit all docs/config/install references to old plugin name
- [x] Ensure plugin config keys and examples reflect the new registration name
-
-### 4.2 Remove sidecar architecture
- [x] Remove plugin-side `server/` telemetry sidecar
- [x] Remove sidecar startup/shutdown lifecycle logic
- [x] Remove sidecar-specific docs and examples
- [x] Replace old OpenClaw telemetry flow with direct plugin-exposed data path
-
-### 4.3 Plugin config updates
- [x] Add `monitor_port` to plugin config schema
- [x] Document `monitor_port` in plugin README/docs/examples
- [x] Ensure runtime reads and validates `monitor_port`
-
-### 4.4 CLI install support
- [x] Add install script flag `--install-cli`
- [x] Resolve OpenClaw profile bin directory (default `~/.openclaw/bin`)
- [x] Build `HarborForge.Cli`
- [x] Install compiled `hf` binary to profile `bin/`
- [x] `chmod +x` installed binary
- [x] Handle failure cases cleanly if CLI build/install fails
-
-### 4.5 Skills deployment
- [x] Add plugin `skills/` directory
- [x] Add `skills/hf/`
- [x] Add `skills/hf/SKILL.md`
- [x] In `SKILL.md`, explain basic `hf` usage
- [x] In `SKILL.md`, encourage agents to use `hf --help-brief`
- [x] In `SKILL.md`, point to normal `--help` for full command tree
- [x] Installer should copy normal plugin skills into profile `skills/`
- [x] Installer should **not** copy `skills/hf/` unless `--install-cli` is present
- [x] Installer should copy `skills/hf/` when `--install-cli` is present
-
-### 4.6 Monitor bridge endpoint
- [x] Define how plugin exposes OpenClaw metadata to Monitor over local port
-  - Plugin periodically POSTs metadata to Monitor bridge `POST /openclaw`
- [x] Decide HTTP endpoint structure / payload schema
-  - `POST /openclaw` with `{ version, plugin_version, agents }`
- [x] Expose OpenClaw version
- [x] Expose plugin version
- [x] Expose agent list / agent metadata
- [x] Ensure plugin remains functional even if Monitor never connects
-
---
-
-## 5. HarborForge.Monitor
-
-### 5.1 Docker/runtime changes
- [x] Add `MONITOR_PORT` env var
- [x] Ensure Monitor listens on `127.0.0.1:<MONITOR_PORT>`
- [x] Update Docker runtime docs/examples
- [x] Update docker-compose to expose that port to host `127.0.0.1`
-
-### 5.2 Plugin communication
- [x] Implement local communication client to query plugin over `MONITOR_PORT`
-  - Note: the architecture is reversed — Monitor hosts the bridge, plugin pushes via POST /openclaw
- [x] Define request timeout / retry / fallback policy
-  - Plugin uses 3s timeout; Monitor bridge uses 5s read/write timeouts
- [x] Keep startup independent of plugin communication success
- [x] Keep heartbeat/telemetry upload independent of plugin communication success
- [x] If plugin is reachable, enrich telemetry with:
-  - [x] OpenClaw version
-  - [x] plugin version
-  - [x] agent info
- [x] If plugin is unreachable, continue current behavior unchanged
-
-### 5.3 Telemetry model alignment
- [x] Ensure backend-facing telemetry payloads can carry optional OpenClaw metadata
- [x] Avoid making plugin-derived fields mandatory
- [x] Ensure monitor data model cleanly distinguishes:
-  - [x] host/hardware telemetry
-  - [x] optional OpenClaw metadata
-
-### 5.4 Docs / examples
- [x] Update Monitor README to explain `MONITOR_PORT`
- [x] Explain degraded mode when plugin bridge is absent
- [x] Provide example Docker run / compose snippet with host loopback exposure
-
---
-
-## 6. HarborForge.Test / HarborForge.Frontend.Test
-
-### 6.1 Keep test runner aligned
- [ ] Preserve Frontend.Test Dockerfile as owner of proxy startup
- [ ] Keep `run-test-frontend.sh` from overriding default test container CMD unless strictly necessary
- [ ] Keep expose-port mode working with 127.0.0.1 + proxy architecture
-
-### 6.2 Code-first frontend test updates
- [ ] Update tests to prefer resource codes over ids in assertions and navigation
- [ ] Remove assumptions that UI surfaces raw ids where codes should be primary
-
-### 6.3 Future CLI tests
- [ ] Add tests for `hf` help rendering
- [ ] Add tests for `hf --help-brief`
- [ ] Add tests for padded-cell mode vs manual mode
- [ ] Add tests for exact stderr messages
- [ ] Add tests for code-only command acceptance
-
---
-
-## 7. Suggested implementation order
-
-### Phase A — Foundations
- [x] Finalize CLI help / mode / output model
- [x] Finalize backend permission introspection approach
- [x] Finalize plugin↔monitor local protocol
-
-### Phase B — Backend first
- [x] Add/finish code-based backend support
- [x] Add/finish task take / meeting attend / support take
- [x] Add any missing account-manager creation behavior
-
-### Phase C — CLI MVP
- [x] Build `hf` scaffold
- [x] Ship `version`, `health`, `config`
- [x] Ship `user create`, `user list`, `user get`
- [x] Ship `task list`, `task get`, `task take`
- [x] Ship initial `monitor` commands
-
-### Phase D — Frontend alignment
- [x] Move frontend to code-first lookup/display
- [x] Surface canonical codes consistently in UI
-
-### Phase E — Plugin / Monitor integration
- [x] Rename plugin to `harbor-forge`
- [x] Remove plugin sidecar
- [x] Add `--install-cli`
- [x] Add `skills/hf`
- [x] Add `monitor_port` / `MONITOR_PORT` bridge
-
-### Phase F — Cleanup / retirement
- [x] Remove legacy backend Python CLI
- [x] Update all docs to point to `hf`
- [ ] Add final tests and packaging flow