Task Forest

Task Forest

Language Policy

All output directed at the user — task titles, node fields, proposals, reports, questions, confirmations, and exported user-facing content — must be written in the user's language. Detect the user's language from their message. Default to Chinese when unknown. Skill instructions are written in English; that does not affect the language of user-facing output.

Role

Maintain repo-local task structure. Record long-running goals, subtasks, dependencies, progress, deviations, todos, and session history under the current workspace. Export an offline HTML view of the task graph.

Portability

Resolve paths from the directory that contains this SKILL.md. Use the available Python command on the host (python3, python, or py -3). The scripts are intended for macOS, Windows, and Linux with Python 3 and the standard library. In portable builds, agents may set COMPASS_AGENT_NAME or AGENT_NAME when they want graph history to record the calling agent.

Core Principles

1. Write task-forest data only through scripts/task_forest.py; never edit files under .agent-workbench/task-forest/ directly. 2. The internal model is a DAG. The default presentation is a forest: one primary child_of parent per node, contributes_to for secondary ownership, and depends_on for execution prerequisites. 3. If user intent is unclear, apply $task-clarifier before task graph work. If intent is clear enough, present a proposal and wait for confirmation before applying it. 4. Keep unconfirmed assumptions in proposals. Write formal graph changes only after confirmation. 5. When execution diverges from the user's requirement, record a deviation and move related tasks to review_needed or wait for user confirmation. 6. Store canonical data in the current workspace at .agent-workbench/task-forest/. Store only lightweight registry data in the global SQLite index. 7. In concurrent sessions, read and write through the CLI so locking and stale-hash checks can run. 8. Treat HTML export as a primary product surface. Changes to the HTML template must satisfy references/html-visualization-contract.md and pass scripts/validate_task_forest_export.py.

CLI

Resolve <skill-dir> to the directory that contains this SKILL.md. Use the available Python command for the host (python3, python, or py -3). Examples use python3; adapt only the Python executable name when needed.

python3 <skill-dir>/scripts/task_forest.py --help

The default workspace is the current working directory. To target a specific workspace:

python3 <skill-dir>/scripts/task_forest.py init \
  --workspace /path/to/repo

Common commands:

python3 <skill-dir>/scripts/task_forest.py init

python3 <skill-dir>/scripts/task_forest.py add-node \
  --kind global_task \
  --title "Maintain the local agent workbench" \
  --requirement "Task data stays inside the workspace" \
  --acceptance "The task graph can be exported to HTML"

python3 <skill-dir>/scripts/task_forest.py add-node \
  --title "Implement task graph HTML export" \
  --parent TF-0001 \
  --estimate 120 \
  --difficulty medium

python3 <skill-dir>/scripts/task_forest.py todo
python3 <skill-dir>/scripts/task_forest.py export
python3 <skill-dir>/scripts/task_forest.py validate

Session Close Workflow

When the user asks to update the task forest, close the current session, or maintain the task list from the conversation:

1. Run init to ensure the data directory exists. 2. Run list --json and todo --json to read current nodes and open work. 3. Analyze the session and create candidate changes only: new nodes, node updates, edges, deprecations, deviations, or questions. 4. If the session goal is unclear, ask which goal this conversation mainly served. 5. If the goal is clear enough, show the proposal: where each new node goes, how it relates to existing tasks, and which fields would change. 6. Save the candidate changes as a proposal. Apply with proposal-apply --yes only after user confirmation. 7. After applying, run validate and export, inspect the HTML against references/html-visualization-contract.md, and tell the user the HTML path.

Proposal JSON fields and invariants live in references/schema.md. Complex session-close reasoning lives in references/session-close-workflow.md.

Read references/goal-alignment.md when judging how a task serves a global goal, whether it can achieve the user's purpose, or which candidate task plan to offer. Clarification methods come from $task-clarifier; task-forest owns graph meaning, candidate task structure, and proposal writes.

Read references/node-types.md only when adding or classifying nodes.

Concurrency and multi-session rules live in references/concurrency.md. Proposals store base_graph_hash; application rejects stale proposals by default. Use --allow-stale only after manual conflict review.

Outputs And Integration

Exports are fixed at:

.agent-workbench/task-forest/exports/task-forest.graph.json
.agent-workbench/task-forest/exports/task-forest.todos.json
.agent-workbench/task-forest/exports/task-forest.timeline.json
.agent-workbench/task-forest/exports/task-forest.html

gap-router and local-agent-control-room read these exports. They must leave canonical task-forest data unchanged. Field contracts live in references/integration-contract.md.

The CLI updates a lightweight global registry when possible during init, export, validate, proposal-save, and proposal-apply:

~/.agent-workbench/agent-workbench.sqlite3

The registry stores workspace paths, task-forest paths, export paths, export hashes, node/edge/status counts, command status, and error summaries. It omits node bodies, edge bodies, history snapshots, HTML, proposal content, and full conversation summaries. Use AGENT_WORKBENCH_DB to set another registry path. Set TASK_FOREST_DISABLE_GLOBAL_REGISTRY=1 to disable the global registry.

Full rebuild regression:

python3 <skill-dir>/scripts/validate_task_forest_export.py --skill-dir <skill-dir>

The validator creates a temporary workspace, initializes task-forest, builds a sample DAG with multiple states and edge types, runs validate/export, and checks exported JSON and HTML behavior.

Boundaries

• Explicit invocation is the reliable way to run this skill at session end.
• Low-confidence goal inference must become a question or stay in a proposal.
• Prefer deprecated for removed tasks so history remains reviewable.
• Estimates must include confidence. Use unknown or low confidence when evidence is thin.

并发与多 session 稳定性

目录

• 问题
• 设计原则
• 锁
• 原子写入
• Proposal 乐观并发控制
• 多 session 推荐流程
• 故障恢复

问题

同一个任务目录可能同时有多个 Codex、Claude 或其他 agent session 调用 $task-forest。如果它们同时读旧状态、各自写回，就可能出现：

• 节点 ID 重复；
• 后写入覆盖先写入；
• nodes.json 和 edges.json 读到不一致版本；
• proposal 基于旧图，应用后覆盖新 session 的更新；
• HTML 或导出 JSON 被半写入时读取。

设计原则

1. 所有正式写入必须通过 scripts/task_forest.py。 2. 所有读 canonical graph 的命令也要短暂持锁，保证读取的是同一版本。 3. 写入使用临时文件 + os.replace 原子替换。 4. proposal 保存时记录 base_graph_hash，应用时默认检查当前图是否仍是同一版本。 5. 多 session 可以并行生成 proposal，但正式应用必须串行。 6. 不用“最后写入者获胜”策略；这会静默丢失任务信息。

锁

CLI 使用 repo-local 锁文件：

.agent-workbench/task-forest/lock

锁文件包含：

{
  "token": "<random-token>",
  "pid": 12345,
  "started_at": "2026-06-13T00:00:00.000000Z",
  "path": "<lock-path>"
}

规则：

• 每个命令进入 canonical graph 读写区前获取锁。
• 默认等待 30 秒，可用 --lock-timeout 或 TASK_FOREST_LOCK_TIMEOUT 调整。
• 如果持锁进程已经不存在，CLI 会在短暂宽限后清理陈旧锁。
• 如果无法判断进程状态，只在锁超过 TASK_FOREST_STALE_LOCK_SECONDS 后清理，默认 6 小时。
• 释放锁时只删除自己 token 对应的锁，避免误删其他进程新建的锁。

原子写入

JSON、JSONL 和 HTML 写入策略：

• JSON 和 HTML 先写到同目录隐藏临时文件；
• flush + fsync 后使用 os.replace 替换目标文件；
• JSONL 事件追加发生在锁内，并 fsync；
• 派生产物 exports/*.json 和 task-forest.html 也使用原子替换。

这样读者不会看到半个 JSON 或半个 HTML。

Proposal 乐观并发控制

保存 proposal 时，CLI 记录当前图 hash：

{
  "base_graph_hash": "<sha256>",
  "base_summary": {
    "node_count": 10,
    "edge_count": 12,
    "workspace_path": "/path/to/repo"
  }
}

应用 proposal 时：

• 当前图 hash 与 base_graph_hash 一致：允许应用。
• 当前图 hash 已变化：默认拒绝应用，提示重新生成 proposal。
• 用户人工确认无冲突后，可以传入 --allow-stale。

不要默认使用 --allow-stale。它只适合用户明确确认“虽然图变了，但这个 proposal 仍然可以应用”的场景。

多 session 推荐流程

每个 session 结束时：

1. 读取当前图。 2. 生成独立 proposal，proposal_id 使用唯一 ID 或包含 session 标识。 3. 保存 proposal，不直接应用。 4. 给用户展示变更摘要。 5. 用户确认后应用。 6. 如果应用时提示 stale，重新读取当前图并重新生成 proposal。

多个 session 同时保存 proposal 是允许的；多个 session 同时应用 proposal 会被锁串行化，且 stale 检查会防止旧 proposal 覆盖新状态。

故障恢复

如果命令异常退出：

• 首先运行 validate 检查当前图；
• 如果提示锁被占用，查看锁文件里的 pid；
• 如果 pid 已不存在，重新运行命令，CLI 会清理陈旧锁；
• 不要手动编辑 nodes.json、edges.json 或 config.json；
• 需要修正错误时，生成新的 proposal 或使用 CLI 的更新命令。

Goal Alignment And Candidate Task Design

Contents

• Boundary With task-clarifier
• Goal Alignment Workflow
• Task Fit Assessment
• Candidate Plan Format
• Writing To task-forest
• Anti-Patterns And Fallbacks

Boundary With task-clarifier

task-clarifier decides:

• whether to ask the user;
• whether to ask one question, batch questions, offer method choices, or run an intent interview;
• whether to research, confirm risk, or block before execution.

task-forest decides:

• what the current work means inside the global task graph;
• which global goal it serves;
• whether the proposed task can achieve the user's purpose;
• which candidate task plan would serve the purpose more effectively;
• how candidate plans compare on feasibility, effectiveness, accuracy, completeness, stability, robustness, and complexity.

Keep task-clarifier focused on need alignment. Keep task-forest focused on graph structure, candidate task plans, and purpose-to-task fit.

Goal Alignment Workflow

When the user proposes a new task, changes a task, asks to generate tasks, or the current session purpose is unclear:

1. Read the current graph:

python3 scripts/task_forest.py list --json
python3 scripts/task_forest.py todo --json

2. Apply $task-clarifier rules for any decision about asking the user, researching first, offering method choices, confirming risk, or blocking. This file must not define its own clarification route.

3. Convert the confirmed purpose into structured fields:

user_goal: the result the user wants
why_now: why this matters now
success_metrics: how success will be recognized
constraints: hard boundaries
non_goals: explicit exclusions
risk_tolerance: preference across complexity, accuracy, speed, and stability

4. Align the purpose with the task forest:

• If it fits an existing global task, use child_of or update the existing node.
• If it serves multiple goals, choose one primary parent and connect the rest with contributes_to.
• If it does not belong under any existing global task, create a global_task.
• If the existing task cannot achieve the purpose, create a better candidate plan.

Task Fit Assessment

Assess each candidate task with at least:

fit: aligned | partial | weak | misaligned | unknown
why_this_task: how it serves the user's purpose
why_not_enough: uncovered needs or risks
feasibility: low | medium | high
effectiveness: low | medium | high
accuracy: low | medium | high
completeness: low | medium | high
stability: low | medium | high
robustness: low | medium | high
complexity: low | medium | high
confidence: 0.0-1.0
validation_plan: how to verify the task achieved the purpose

For weak, misaligned, or unknown fit, ask a clarifying question, record a risk, or propose a stronger candidate. Do not mark the task as ready.

Candidate Plan Format

When the user needs to choose among task plans, offer 2-3 meaningfully different options.

I understand your real goal as: ...

Option A: Low-complexity quick version
- Task:
- Why it fits:
- Coverage:
- Gaps:
- Feasibility:
- Effectiveness:
- Accuracy:
- Completeness:
- Stability/robustness:
- Cost:
- Validation:

Option B: Balanced version (recommended)
...

Option C: High-completeness version
...

My recommendation: B, because ...
The decision needed from you is: speed first, balanced, or completeness first.

Each option must be executable. Avoid filler options.

Writing To task-forest

After confirmation, create a proposal. Important node fields should include:

{
  "purpose": "the user's real goal",
  "desired_outcomes": ["expected result"],
  "success_metrics": ["signals that the goal is achieved"],
  "non_goals": ["explicit exclusions"],
  "assumptions": ["key assumptions"],
  "alignment": {
    "user_goal": "the user's real goal",
    "fit": "aligned",
    "fit_confidence": 0.85,
    "why_this_task": "why this task serves the goal",
    "why_not_enough": "remaining gaps",
    "validation_plan": ["verification steps"]
  }
}

To preserve an alignment audit, add this to the proposal:

{
  "action": "record_alignment",
  "alignment": {
    "related_task_ids": ["TF-0001"],
    "user_goal": "the user's real goal",
    "candidate_summary": "summary of candidate task plans",
    "selected_option": "B",
    "rejected_options": ["A", "C"],
    "reason": "why B was selected",
    "node_alignment": {
      "user_goal": "the user's real goal",
      "fit": "aligned",
      "fit_confidence": 0.85,
      "why_this_task": "why it fits",
      "why_not_enough": "remaining boundary",
      "validation_plan": ["how to verify"]
    },
    "confidence": 0.85
  }
}

Anti-Patterns And Fallbacks

Avoid:

• creating a task while the user's purpose is unclear;
• treating the requested action as the user's real outcome without checking fit;
• generating weak options to reach an option count;
• describing the task without describing how it serves the global purpose;
• ignoring the risk that a task may fail to achieve the purpose.

Fallbacks:

• Unclear purpose: ask one $task-clarifier style question.
• Unreliable plans: say the information is insufficient and save a question node or proposal.
• Task-purpose conflict: record record_deviation or add a risk node.
• User wants quick progress: give one recommended plan and two brief alternatives with assumptions.

HTML 可视化契约

目标

task-forest.html 是用户理解任务森林的主要界面。它必须让用户在不打开 JSON 的情况下看清：

• 当前任务主层级；
• 完整 DAG 关系；
• 哪些任务未完成、阻塞或待复核；
• 每次 session 如何改变任务图；
• 每个节点的目的、要求、验收、风险、偏差和关系边。

导出 HTML 必须是离线、无外部依赖、可分享的静态文件。交互状态只存在于当前浏览器页面中，不能写回 canonical graph。

必备视图

树视图

• 默认使用 child_of 生成主层级树。
• 树应竖向分层：根节点在上，子节点在下。
• 节点卡片只展示短标题和进度条；详细说明放在右侧详情面板。
• 节点必须可点击，点击后右侧显示完整节点详情。
• 支持全部展开、全部折叠、搜索和状态筛选。

DAG 视图

• 按完整 DAG 展示所有可见节点和关系边。
• 关系边必须按类型使用稳定颜色，并带可点击中文标签。
• child_of 在用户界面中显示为 子任务，不要显示“父子分解”。
• 边标签应跟随对应边的位置；拖动节点时，边路径和边标签必须同步移动。
• DAG 节点可单独拖拽，用于整理视图；拖拽位置只保存在页面运行态，不能写入任务图。
• 必须提供 重置布局，清空运行态拖拽位置并恢复自动布局。

历史变化

• 使用 snapshots 展示任务图如何随 session 增长或变化。
• 支持滑块手动查看历史。
• 支持播放、暂停、上一步、下一步、循环和播放速度选择。
• 每个快照应展示新增节点、新增边、状态变化和进度变化摘要。

状态队列和 todo

• 左侧必须显示待复核、阻塞、可执行、持续目标和未完成事项。
• 顶部统计中的 待复核、阻塞、未完成 应可点击筛选，再次点击应取消筛选。
• review_needed 不能只显示数字；用户必须能点到具体节点并看到复核说明。

节点详情

• 右侧详情必须展示：
• 状态、类型、进度、优先级；
• 全局目的；
• 为什么该任务符合目的；
• 不足或风险；
• 期望结果、成功指标、具体要求、验收标准、非目标、关键假设；
• 验证计划、执行提示、证据、关系边、偏差记录。
• review_needed 节点必须展示“待复核要看什么”，包括复核对象、通过复核如何生成 proposal、不通过复核如何记录缺口。
• 复核说明应提供可复制的通过/不通过指令，但不能直接在 HTML 中修改正式任务图。

边详情

• 所有边都必须可点击。
• 点击边后右侧显示边详情，包括方向、起点任务、目标任务、类型、阻塞属性、置信度、原因和创建信息。
• 边详情应有“返回上一项”和“返回当前节点”入口，避免用户迷失上下文。

布局和交互

• 左右面板默认展开，允许收起。
• 左右面板收起后应保留窄侧栏；页面向下滚动时，折叠按钮和竖排标题仍必须保持在视口内。
• 画布支持拖拽空白区域平移。
• 按住 Ctrl、Command 或 Alt 并滚轮可缩放。
• 提供缩小、放大、重置缩放、适配画布按钮。
• 首次打开或切换视图后，应尽量适配画布，让用户能看到整体结构。
• 搜索、筛选和工具栏不能遮挡任务图。

中文和术语

界面面向中文用户时，核心标签应使用中文：

树视图
DAG 视图
全部
全部展开
全部折叠
清除筛选
重置布局
历史与队列
节点详情
边详情
子任务
依赖
贡献
澄清
待复核
阻塞
可执行
持续目标

避免在用户界面直接暴露内部术语，除非它是节点 ID、边 ID 或字段名。特别是：

• child_of 对用户显示为 子任务；
• review_needed 对用户显示为 待复核；
• global_task 对用户显示为 全局任务。

数据边界

• HTML 读取 exports/task-forest.graph.json 等价数据的内嵌快照，但不是权威存储。
• 权威状态仍是 graph/nodes.json 和 graph/edges.json。
• HTML 中的搜索、筛选、缩放、平移、DAG 节点拖拽、折叠面板、历史播放都是视图状态。
• HTML 不能直接 apply proposal、改状态、写节点或写边；它只能生成可复制指令，引导用户回到 $task-forest 走 proposal 流程。

从零验收

从空 workspace 验证时，至少应覆盖：

• 初始化空 task-forest；
• 创建一个 evergreen / in_progress 顶层目标；
• 创建 review_needed、ready、done、risk、follow_up 等不同状态和类型节点；
• 创建 child_of、depends_on、contributes_to、clarifies 等多种边；
• 生成至少两个快照，使历史播放有内容；
• 运行 validate；
• 运行 export；
• 检查 HTML 中存在树视图、DAG 视图、可点击边、DAG 节点拖拽、标签跟随、重置布局、待复核说明、历史播放、sticky 折叠侧栏和中文术语。

推荐命令：

python3 scripts/validate_task_forest_export.py --skill-dir /path/to/task-forest

task-forest 集成契约

目录

• 固定导出文件
• gap-router 读取方式
• local-agent-control-room 读取方式
• 写入边界
• 全局 SQLite 边界

固定导出文件

每次 export 后生成：

.agent-workbench/task-forest/exports/task-forest.graph.json
.agent-workbench/task-forest/exports/task-forest.todos.json
.agent-workbench/task-forest/exports/task-forest.timeline.json
.agent-workbench/task-forest/exports/task-forest.html

消费者应读取 exports/，不要读取 graph/nodes.json 和 graph/edges.json，更不要直接写它们。

gap-router 读取方式

gap-router 的任务池来源应优先使用 task-forest.todos.json。推荐候选条件：

• status 属于 proposed、ready、in_progress、review_needed；
• ready == true；
• 排除 done、deprecated、archived；
• 排除 blocked_by 非空的任务，除非用户明确想处理阻塞。

可用字段：

id
title
purpose
kind
status
progress
priority
difficulty
remaining_minutes_min
remaining_minutes_max
ready
blocked_by
next_action
confidence
context_tags
desired_outcomes
success_metrics
alignment

推荐逻辑可以结合 gap-router 自己的等待时间、切入成本、切回成本和精力参数。若需要记录用户执行结果，gap-router 应写入 task-forest proposal，而不是直接改 task-forest 图。

推荐给用户时，优先使用 purpose 和 alignment.why_this_task 解释“为什么这件事符合当前 global 目的”；如果这些字段为空，应降低推荐置信度或提示需要先做目标对齐。

如果需要更快获得候选队列，也可以读取 task-forest.graph.json 中的派生字段：

status_queues.actionable_todos
status_queues.ready
status_queues.review_needed
status_queues.evergreen_open_goals

其中 evergreen_open_goals 代表长期持续目标，不能简单按剩余分钟推荐给用户；应只作为当前上下文和目的解释来源。真正适合碎片时间推荐的是 actionable_todos 和 ready 中具备估时、低切换成本、低阻塞风险的节点。

local-agent-control-room 读取方式

local-agent-control-room 应读取 task-forest.graph.json，把 agent/session 状态叠加到任务节点上：

session_id -> source_sessions 或 proposal.session_id
waiting_human -> question / review_needed
risk finding -> risk / deviation proposal
completed session -> review_needed 或 done proposal

控制室可以展示：

• 哪个 session 正在处理哪个任务节点；
• 哪些节点完成但待 review；
• 哪些节点被风险事件影响；
• 哪些任务等待用户回答；
• 哪些任务长时间无进展。

新版 task-forest.graph.json 提供了便于控制室展示的派生字段：

status_queues.blocked
status_queues.review_needed
status_queues.open
edge_index.<node_id>.incoming
edge_index.<node_id>.outgoing
edge_index.<node_id>.blocking_edges
edge_index.<node_id>.cross_edges
edge_type_counts
tree_edges
cross_edges

控制室应使用这些字段定位“谁卡住、谁待复核、谁有跨任务依赖”。展示层可以默认使用 child_of 作为层级树，把 depends_on、contributes_to、clarifies 等边作为可点击关系边展示，避免把 DAG 误读成纯树。

如果控制室复用 task-forest.html 的交互经验，应遵守 html-visualization-contract.md 的用户语义：child_of 面向用户显示为 子任务，DAG 节点拖拽只是展示层布局，不是任务事实，不能把拖拽后的坐标写回 task-forest graph。

控制室不应直接修改 task-forest 的正式状态。它可以生成 proposal：

.agent-workbench/task-forest/proposals/<proposal_id>.json

然后由 $task-forest 读取、解释、请求用户确认并应用。

写入边界

唯一允许正式写入 task-forest 的程序是：

scripts/task_forest.py

其他插件只允许：

• 读取 exports/；
• 写入未确认 proposal；
• 写入外部观察日志，再由 task-forest 转成 proposal。

HTML 中的按钮、搜索、筛选、播放、缩放、平移、DAG 节点拖拽和侧栏折叠都属于浏览器本地视图状态。其他插件不应把这些 UI 状态当成任务状态，也不应从 HTML 反向解析任务事实；需要任务数据时读取 JSON export。

全局 SQLite 边界

全局 SQLite 可以保留轻量 registry：

workspace_path
task_forest_path
exports_dir
graph_export_path
todos_export_path
timeline_export_path
html_export_path
last_seen_at
last_export_at
last_export_hash
node_count
edge_count
ready_count
review_needed_count
blocked_count
evergreen_count
status
last_error

推荐表名：

aw_task_forests
aw_task_forest_runs

task_forest.py 会在 init、export、validate、proposal-save、proposal-apply 后尽力更新该 registry。gap-router 和 local-agent-control-room 也可以在读取某个 workspace 的导出文件时刷新该 registry，以便下一次能够发现这个 workspace。

不要把节点、边、事件、快照、HTML、proposal 内容或完整对话摘要保存到全局 SQLite。完整数据必须留在 repo-local task-forest 目录。全局 registry 只是发现入口和健康状态摘要，不是任务事实源。

Node Types

Read this file only when adding or classifying task-forest nodes.

Classification Order

Classify new content in this order:

• global_task: a long-running user goal that does not naturally belong under an existing global task.
• task / subtask: concrete work needed to complete an existing task.
• requirement: a new or corrected acceptance requirement that is not standalone work.
• decision: a design choice, boundary, or tradeoff settled in the session.
• risk: a blocker, safety issue, data risk, accuracy risk, or execution deviation.
• question: something the user must answer before progress can continue.
• follow_up: a small item to handle after the session.

When one piece of work serves multiple goals, keep one primary child_of parent and use contributes_to for other goals.

Important Fields

Record these fields for important tasks when evidence supports them:

• purpose: the user's real goal served by the task.
• desired_outcomes: concrete results the user expects.
• success_metrics: how success will be recognized.
• non_goals: explicit exclusions.
• assumptions: assumptions required by the current plan.
• alignment: why the task fits the goal, remaining gaps, and how fit will be verified.

task-forest 数据模型

目录

• 存储位置
• 节点
• 边
• 状态
• DAG 与树形视图
• HTML 可视化契约
• 事件和快照
• Proposal 格式
• 校验规则

存储位置

默认目录：

<workspace>/.agent-workbench/task-forest/

核心文件：

config.json
graph/nodes.json
graph/edges.json
graph/forest.json
events/events.jsonl
proposals/<proposal_id>.json
deviations/deviations.jsonl
alignments/alignments.jsonl
todos/todos.json
snapshots/<sequence>.json
exports/task-forest.graph.json
exports/task-forest.todos.json
exports/task-forest.timeline.json
exports/task-forest.html
lock

nodes.json 和 edges.json 是当前状态的权威来源。events.jsonl 是历史审计日志。exports/ 和 todos/ 是派生产物，可以通过 export 重建。

并发写入规则见 concurrency.md。任何 session 都不能绕过 CLI 直接编辑这些文件。

节点

节点是任务、要求、决策、风险或待办。字段：

{
  "id": "TF-0001",
  "title": "实现任务森林 skill",
  "kind": "global_task",
  "status": "in_progress",
  "summary": "repo-local 维护任务 DAG、历史和 HTML。",
  "purpose": "让用户长期看清当前 repo 的真实任务结构和进展",
  "desired_outcomes": ["用户能看到任务森林和历史变化"],
  "requirements": ["数据留在 repo 内"],
  "acceptance_criteria": ["可以导出 HTML", "可以校验 DAG 无环"],
  "success_metrics": ["HTML 能展示任务图、历史和未完成事项"],
  "non_goals": ["不直接执行用户任务"],
  "assumptions": ["用户愿意在 session 结束时显式调用 skill"],
  "alignment": {
    "user_goal": "准确维护当前任务目录的全局任务结构",
    "fit": "aligned",
    "fit_confidence": 0.85,
    "why_this_task": "该任务提供 repo-local 任务图和历史导出，能支撑用户长期追踪全局目标",
    "why_not_enough": "不能保证自动在每个 session 结束时运行",
    "validation_plan": ["运行 validate", "打开 HTML 检查节点详情"]
  },
  "alignment_records": [],
  "progress": 40,
  "progress_source": "manual",
  "priority": 3,
  "difficulty": "medium",
  "estimated_total_minutes": 180,
  "remaining_minutes_min": 60,
  "remaining_minutes_max": 90,
  "confidence": 0.8,
  "context_tags": ["agent-workbench"],
  "execution_hints": ["先运行 validate"],
  "source_sessions": ["session-2026-06-13"],
  "evidence": ["用户明确要求做成 skill"],
  "deviations": [],
  "created_at": "2026-06-13T00:00:00.000000Z",
  "updated_at": "2026-06-13T00:00:00.000000Z",
  "deprecated_at": null
}

允许的 kind：

global_task, milestone, task, subtask, requirement, decision, risk, question, follow_up

允许的 status：

proposed, ready, in_progress, blocked, review_needed, done, deprecated, archived

允许的 difficulty：

low, medium, high, very_high, unknown

边

边表达任务之间的关系。字段：

{
  "id": "TFE-0001",
  "from": "TF-0002",
  "to": "TF-0001",
  "type": "child_of",
  "blocking": true,
  "reason": "TF-0002 是 TF-0001 的实现子任务",
  "confidence": 0.85,
  "created_from_session": "session-2026-06-13",
  "created_at": "2026-06-13T00:00:00.000000Z",
  "updated_at": "2026-06-13T00:00:00.000000Z"
}

允许的 type：

child_of, depends_on, contributes_to, related_to, duplicates, supersedes, clarifies, derived_from

语义：

• child_of：结构分解关系，from 是 to 的主子任务。每个节点最多一个 child_of 父节点。HTML 用户界面中显示为“子任务”。
• depends_on：执行依赖，from 必须等 to 完成后才算 ready。
• contributes_to：一个任务同时贡献给另一个目标，不改变主树位置。
• related_to：弱相关，不影响进度或 ready 判断。
• duplicates：语义重复，应合并或废止其中之一。
• supersedes：from 替代 to。
• clarifies：from 澄清 to 的要求或问题。
• derived_from：from 来源于 to，常用于将讨论拆成任务。

DAG 与树形视图

task-forest 的权威数据模型是有向无环图（DAG），不是纯树。原因是一个任务可能既属于一个主分解路径，又依赖、贡献、澄清或替代另一个任务。

为了让用户容易理解层级，HTML 默认使用 child_of 边生成竖向树形主视图：

• child_of 是唯一主父边：每个节点最多只能有一个 child_of 父节点。
• 非 child_of 边是跨边：用于表达依赖、贡献、澄清、替代、重复、来源等关系，不改变节点在主树中的位置。
• 所有边仍然保留在 DAG 中，HTML 的 DAG 视图 和节点详情会展示这些边的方向、类型、原因和置信度。

因此，“树”只是默认可读视图；“DAG”才是完整任务关系。

HTML 可视化契约

HTML 导出不是数据模型本身，但它是 task-forest 的主要用户界面。task-forest.html 必须遵守 references/html-visualization-contract.md：

• 树视图用 child_of 展示主层级；
• DAG 视图展示所有可见边，不应叫“DAG 边”；
• child_of 对用户显示为 子任务；
• 边标签可点击并跟随对应边移动；
• DAG 节点拖拽只改变当前页面运行态布局，不写回 nodes.json 或 edges.json；
• review_needed 必须能定位到具体节点，并解释复核对象和下一步；
• 历史快照必须支持手动查看和播放；
• 左右侧栏收起后，滚动页面时仍应保留可展开按钮。

导出视图模型

exports/task-forest.graph.json 除了节点、边、根节点和统计信息外，还包含面向下游工具和 HTML 的派生字段：

{
  "tree_edges": ["TFE-0001"],
  "cross_edges": ["TFE-0002"],
  "edge_index": {
    "TF-0001": {
      "incoming": ["TFE-0001"],
      "outgoing": ["TFE-0002"]
    }
  },
  "edge_type_counts": {
    "child_of": 5,
    "depends_on": 1
  },
  "status_queues": {
    "open": ["TF-0001", "TF-0002"],
    "blocked": [],
    "review_needed": ["TF-0002"],
    "ready": ["TF-0005"],
    "evergreen_open_goals": ["TF-0001"],
    "actionable_todos": ["TF-0002", "TF-0005"]
  },
  "status_legend": {
    "review_needed": "已经基本完成，但需要用户或执行者复核后才能转为 done。"
  },
  "edge_type_legend": {
    "depends_on": "执行依赖：from 必须等 to 完成后才算 ready。"
  }
}

这些字段都是派生视图，不是新的权威状态。下游工具应该优先读取 nodes 和 edges，用派生字段减少重复计算：

• gap-router 可以读取 status_queues.actionable_todos、evergreen_open_goals 和节点的 remaining_minutes_*，给用户推荐等待间隙可做事项。
• local-agent-control-room 可以读取 status_queues.blocked、review_needed、edge_index 和 edge_type_counts，展示谁卡住、谁待复核、哪些任务存在依赖或跨任务关系。
• HTML 可以读取 status_legend 和 edge_type_legend，把“待复核”等统计数字解释清楚，并让用户点到具体节点或边。

事件和快照

每次正式写入都追加 events/events.jsonl，并生成一个 snapshots/<sequence>.json。HTML 的历史滑块使用 snapshots 展示任务图如何随 session 变化。

不要编辑历史事件。需要修正时追加新事件。

Proposal 格式

AI 对 session 的归纳必须先保存为 proposal：

{
  "proposal_id": "TFP-example",
  "session_id": "session-2026-06-13",
  "rationale": "本轮对话要求实现 task-forest skill。",
  "status": "proposed",
  "changes": [
    {
      "action": "add_node",
      "alias": "new-global",
      "node": {
        "title": "实现 task-forest skill",
        "kind": "global_task",
        "status": "in_progress",
        "requirements": ["repo-local 存储", "HTML 可视化"],
        "acceptance_criteria": ["validate 通过", "HTML 导出成功"],
        "confidence": 0.9
      }
    },
    {
      "action": "add_node",
      "alias": "html-export",
      "node": {
        "title": "导出历史任务图 HTML",
        "kind": "subtask",
        "status": "ready"
      }
    },
    {
      "action": "add_edge",
      "from": "html-export",
      "to": "new-global",
      "type": "child_of",
      "edge": {
        "reason": "HTML 导出是该 global task 的验收子任务"
      }
    }
  ]
}

保存并预校验：

python3 scripts/task_forest.py proposal-save --proposal-file proposal.json

用户确认后应用：

python3 scripts/task_forest.py proposal-apply TFP-example --yes

保存 proposal 时 CLI 会自动加入 base_graph_hash。应用时如果当前任务图已经被其他 session 更新，默认拒绝应用；只有人工确认无冲突时才使用 --allow-stale。

支持的 action：

add_node, update_node, set_status, deprecate_node, add_edge, remove_edge, record_deviation, record_alignment

record_alignment 用于审计“为什么当前任务符合用户真实目的、为什么选择某个候选方案、如何验证”。详细工作流见 goal-alignment.md。

校验规则

CLI 必须拒绝：

• 不存在的节点引用；
• 自指边；
• 重复边；
• 非法 kind、status、type；
• 多个 child_of 主父节点；
• child_of 环；
• depends_on 环。

低置信度、估时缺失、difficulty 不规范等问题可以作为 warning。

session 关闭工作流

目录

• 目标
• 判断流程
• 何时询问用户
• 偏差检测
• 进度和估时
• 推荐回答格式

目标

session 关闭时，目标是把本轮对话对任务结构的影响准确写入 task-forest。不要把完整聊天记录无筛选地保存进去；只保留对任务图有长期价值的结构化信息。

判断流程

1. 读取当前状态：

python3 scripts/task_forest.py list --json
python3 scripts/task_forest.py todo --json

2. 从本轮对话提取候选事实：

• 用户明确提出的新目标；
• 用户真实目的、受众、成功标准或非目标；
• 对旧目标的要求修正；
• 已完成、部分完成、废止或阻塞的任务；
• 新发现的依赖关系；
• 设计决策；
• 风险和偏差；
• 需要用户回答的问题；
• session 结束后的 follow-up。

3. 与已有节点对齐：

• 标题近似但要求不同：更新旧节点并记录新要求，不要重复创建。
• 新工作服务于旧目标：建子任务并加 child_of。
• 一个工作服务多个目标：选择一个主父节点，再加 contributes_to。
• 前置关系：加 depends_on，不要误用 child_of。
• 讨论产物只是解释旧任务：建 clarifies 或直接更新旧节点。
• 用户说的动作不能达成用户目的：不要直接建 ready 任务；先生成候选方案或记录 risk/deviation。

4. 生成 proposal，先预校验，再让用户确认。

5. 应用 proposal 后运行：

python3 scripts/task_forest.py validate
python3 scripts/task_forest.py export

6. 如果本轮影响了节点、边、状态、历史或 HTML 模板，按 html-visualization-contract.md 抽查导出 HTML。至少确认：

• 树视图 可展示主层级，节点卡片短小且点击后显示详情；
• DAG 视图 可展示多种关系边，边标签为中文且可点击；
• child_of 在界面中显示为 子任务；
• DAG 节点可拖拽，拖动时边和边标签跟随，重置布局 可恢复；
• 顶部 待复核、阻塞、未完成 等统计可筛选并可取消；
• review_needed 节点详情解释“待复核要看什么”；
• 历史变化支持滑块和播放；
• 左右侧栏收起后，页面向下滚动仍能看到展开按钮。

如果应用 proposal 时提示当前图已经变化，不要直接加 --allow-stale。先重新读取 list --json 和 todo --json，重新判断本轮变更是否仍然成立。只有用户明确确认无冲突时，才允许使用 --allow-stale。

何时询问用户

必须询问：

• 无法判断本轮对话服务哪个目标；
• 新任务可能成为 global task，也可能是旧任务子任务；
• 一个节点看似有多个主父节点；
• 更新会把任务标为 done、deprecated 或 archived；
• 发现高严重度偏差，需要用户决定是否接受；
• 估时、完成度或难度会影响其他插件推荐。
• 任务是否真的能达成用户目的存在实质不确定性。

可以先提出确认：

• 能基本判断关系，但存在低到中等不确定性；
• 只是新增子任务、补充要求、更新进度；
• 用户已经明确说“按你的判断更新”。

不用询问但仍要说明：

• 初始化空 task-forest；
• 导出 HTML；
• 只读查询 todo/list/show；
• 保存未确认 proposal，不应用正式变更。

目标对齐和方案生成

当本轮对话涉及“应该做什么任务”“这个任务的意义是什么”“它是否能达到用户目的”时，读取 goal-alignment.md。

先用 task-clarifier 的问题质量规则确认真实目的。然后生成 2-3 个候选任务方案，比较可行性、有效性、准确性、完整性、稳定性、鲁棒性、复杂度和代价。用户选择后再写入 proposal。

每个被写入的重要任务应补充 purpose、desired_outcomes、success_metrics、non_goals、assumptions 和 alignment 字段。需要保留本次选择过程时，使用 record_alignment。

偏差检测

比较三类信息：

• 用户原始要求和验收标准；
• 本轮实际执行或产物；
• 现有任务节点的状态和进度。

发现偏差时，proposal 中加入 record_deviation：

{
  "action": "record_deviation",
  "deviation": {
    "related_task_ids": ["TF-0001"],
    "severity": "medium",
    "expected_requirement": "数据应保留在 repo 内",
    "observed_action_or_result": "实现方案仍依赖全局 SQLite 保存完整任务",
    "evidence": "本轮设计中提到完整任务写入全局 SQLite",
    "recommendation": "改为 repo-local graph 文件，全局 SQLite 只保留 registry",
    "status": "open",
    "confidence": 0.8
  }
}

严重度建议：

• low：描述或文档不够精确，但不影响执行。
• medium：实现方向可能偏离用户要求，需要修正。
• high：会导致错误交付、数据丢失、隐私问题或明显违反用户要求。

进度和估时

进度来源优先级：

1. 用户明确说明； 2. 验收标准完成比例； 3. 子任务加权平均； 4. agent 基于证据的低置信度估计。

估时必须保留不确定性：

• 有明确范围时写 remaining_minutes_min/max。
• 只有粗略判断时使用宽范围，并降低 confidence。
• 没有依据时写 difficulty: unknown，不要编造精确分钟数。

推荐回答格式

确认前：

我准备这样更新 task-forest：

新增：
- TF-????：<标题>，作为 <父节点> 的子任务，因为 ...

更新：
- TF-0001：把状态从 ready 改为 in_progress；新增要求 ...

关系：
- <新节点> child_of TF-0001
- <新节点> contributes_to TF-0003

偏差：
- 发现 ...，建议记录为 medium deviation。

确认后我会应用 proposal、运行 validate，并重新导出 HTML。

应用后：

已应用 proposal <id>。
校验结果：通过。
HTML：<absolute path>/task-forest.html
HTML 抽查：通过 / 未运行（原因：...）。
未完成任务：N 个，其中 ready X 个、blocked Y 个、review_needed Z 个。