task-ledger

name	task-ledger
description	Ledger development tasks to Feishu Base via dev-task-ledger.sh. Write roots from ~/.openclaw/tasks-allowlist.json (per agent). Use on accept/confirm/close of coding/ops work; not for pure Q&A.

Development task ledger (Feishu Base)

Hard rules

1. Development tasks must target an allowlisted root for the active agent (see Path guard / tasks-allowlist.json). main → wezdeck|team-repo; pm → FE1 (ops). Do not hard-code another machine's /home/... in commits.
2. If the user asks for another repo: do not open a ledger row as accepted work; refuse and explain allowlist policy.
3. When accepted, time loop must close:
   • open → (user confirms plan/初评/开发方式) → confirm if --confirm-required 1 → work → close
   • close --status done fails if still 需确认 and never confirmed
   • cancelled / blocked / failed may close without confirm
4. Never write secrets into the ledger.
5. Final reply must include task_id.
6. If CLI fails, say so; do not invent task_id.
7. When the request has a clear 需求提出人 (product / user who asked): record them on open/update with --requester-id <ou_…> (preferred). Feishu person field name: 需求提出人. Do not leave it blank when known.
8. Order with worktree: open first; after claw worktree exists, update cwd/分支; after user confirms 初评+开发方式, confirm; then implement.
9. Pure Q&A: do not open a row. As soon as the user accepts implementation, open before assess/create (same turn is OK if open is first).
10. Test hygiene: after every smoke / CLI self-test that opens a row, delete that row (and local index entry). Do not leave smoke / time-loop / *-test rows in the production Base table. Soft close is not enough for pure tests — use hard delete.

Path guard

• Config file (authoritative): ~/.openclaw/tasks-allowlist.json (from openclaw/config/tasks-allowlist.json.example).
• Resolver: openclaw/scripts/tasks-allowlist.py (show / check / roots).
• Agent: OPENCLAW_TASKS_AGENT or default main (paths come from config, not env).
• CLI allowlists local --cwd / path-form --repo only (not remote URLs).
• Base field 仓库 = https web URL (clickable in Feishu); cwd = local path. CLI rewrites git@… / ssh://… / ….git → https://host/org/repo.

CLI

# from wezterm-config checkout, or $WEZTERM_REPO if set
# --repo: local path (→ origin → https web URL in 仓库) or any git remote form
# --cwd: local path only → Base field cwd
./openclaw/scripts/dev-task-ledger.sh open \
  --title "…" \
  --repo "$HOME/work/team-repo" \
  --cwd "$HOME/work/team-repo" \
  --scope "packages/… or apps/…" \
  --acceptance "pnpm --filter … test" \
  --risk low|medium|high \
  --source feishu \
  --confirm-required 1 \
  --requester-id ou_xxx   # 需求提出人 (Feishu open_id); optional --requester "显示名"

./openclaw/scripts/dev-task-ledger.sh update \
  --task-id <uuid> \
  --requester-id ou_xxx

./openclaw/scripts/dev-task-ledger.sh confirm --task-id <uuid>

./openclaw/scripts/dev-task-ledger.sh close \
  --task-id <uuid> \
  --status done|failed|cancelled|blocked \
  --summary "…" \
  --branch "…" \
  --commits "abc1234" \
  --mr "https://…"

# Hard-delete a row (smoke/test cleanup — preferred over leaving closed test rows)
./openclaw/scripts/dev-task-ledger.sh delete --task-id <uuid>
# or: ./openclaw/scripts/dev-task-ledger.sh delete --record-id recXXXX

Test / smoke cleanup (mandatory)

After	Do
Any agent/CLI smoke that called open	delete --task-id … (or --record-id …)
Mistaken open	delete, not only close --status cancelled
Real work finished	close (keep the audit row)

Do not accumulate *smoke*, *time-loop*, *-test titles in Base.

需求提出人

CLI	Base 列	类型
--requester-id ou_…	需求提出人	人员（单选）
--requester "姓名"	仅当没有 open_id 时写入 record_note 兜底	文本

• Prefer open_id from Feishu mention / contact lookup.
• Owner who chats with OpenClaw is not automatically the requester; set when the asker is named (e.g. product feedback).

Config: ~/.config/shell-env.d/openclaw-tasks.env (local only; never commit filled file).

Time fields (Base) — closed loop

All times are local clock strings with second precision: YYYY-MM-DD HH:MM:SS (from date '+%Y-%m-%d %H:%M:%S').

In Feishu Base, 开始时间 / 确认时间 / 结束时间 must be 文本 (text), not datetime. Feishu datetime display formats only go to the minute (yyyy-MM-dd HH:mm max) — there is no …:ss enum — so a date-only or datetime column will drop seconds (or show only the day). Text keeps the full string the CLI writes.

Column	When set	Meaning
开始时间	open	Ledger row created / task accepted into the table
需确认	open true if --confirm-required 1; unchecked after confirm (or false from open if 0)	Live gate only — still waiting for plan/初评/开发方式 yes. Not history. Not 验收/merge
确认时间	confirm, or open when confirm-required=0 (same as 开始时间)	User approved plan / 初评 / 【开发方式】
结束时间	close	Ledger closed (done/failed/cancelled/blocked) — not auto PR-merge time

需确认 after confirm: clearing the checkbox is correct. “Was confirmed” is recorded by 确认时间 (non-empty), not by leaving 需确认 checked.

开始时间 vs 确认时间: they are not always equal.

• Default (--confirm-required 1): open writes 开始时间; later confirm writes 确认时间 → usually later.
• --confirm-required 0: no gate → 确认时间 = 开始时间 at open.
• Do not reuse 需确认 for 待验收 / 待 merge; put that in 结果摘要 / MR / 状态.

结束时间 ≠ PR merge 时间。

• 结束时间 = 在台账上结案的时刻（agent 跑 close 的秒级时间戳）。
• PR/MR 用字段 MR（链接）+ 可选摘要说明 merge；若以后要单独记 merge 时刻，再加列，不要占用 结束时间。

Flow

1. Path guard → allowlist (团队仓 | wezdeck).
2. open → writes 开始时间 + 需确认; capture task_id.
3. Plan / worktree 初评 + 【开发方式】→ user yes → confirm (writes 确认时间, 需确认=false, 状态=in_progress).
4. Create/reuse claw-* worktree; update ledger cwd (local) + 分支; 仓库 stays remote URL.
5. Implement (B/C/E/A); main still owns close.
6. close → 结束时间 + 终态; done requires prior confirm when required.
7. Ask reclaim (never auto).