ultragoal

Ultragoal —— 为无法在一次运行中交付的宏大目标打造的闭环

ultragoal 指跨越多个会话的北极星目标：分叉代码仓库，整合各自的优势，交付一款产品。一次 /closed-loop 运行是在闭环中执行的一项任务。一个 ultragoal 是一条阶段链，每个阶段都是一次完整的闭环运行，并会被跟踪，以便任何全新会话都能接续进度。

核心规则（源自 dwarves-kit，现已全面采用）：执行者绝不评判自己的作业，而且错误会在多个会话中累积——因此要验证每个阶段，而不只是最终结果。

适用场景

• /ultragoal <name> — 恢复或推进现有 ultragoal
• /ultragoal new "<north-star>" — 为新的 ultragoal 制定章程
• /ultragoal status — 报告注册表中的所有 ultragoal
• 触发语句：“把这件事做成 ultragoal”、“这是一个长期目标”、“随着时间推移把这些整合成一款产品”

不要将其用于单次运行的工作（应使用 /closed-loop），也不要在请求中从未提出此需求时启动 ultragoal。经验法则：如果需要拆分阶段且无法在今天完成，那它就是一个 ultragoal。

文件（一个目标 = 一个文件夹）

文件	作用
04-projects/harness/ultragoals.md	注册表：所有 ultragoal、状态、当前阶段
04-projects/<goal>/spec.md	合约：北极星目标 + AC-n 验收标准 + 阶段 P0…Pn + 可追溯性矩阵
04-projects/<goal>/STATUS.md	动态进度账本：阶段状态、当前阶段、未完成的 AC-n、下一步操作（从此处恢复）
04-projects/<goal>/evidence/P<n>/	各阶段的证据包（ledger.md + CP-* 文件）

代码（如有）存放在 vault 之外（例如 ~/code/<goal>/）——spec/status/evidence 保留在 vault 中。

阶段 0 — 制定章程（/ultragoal new）

1. 通过访谈让用户用一句话说明北极星目标（“完成”是什么样子）。
2. 根据 ../closed-loop/references/spec-template.md 编写 04-projects/<goal>/spec.md：
   • 北极星目标陈述
   • 可证伪的 AC-n 验收标准（这些定义了整个目标的完成条件）
   • 阶段拆分 P0…Pn —— 每个阶段都是可交付的增量，并映射到一部分 AC-n
   • 可追溯性矩阵（AC-n ↔ 阶段 ↔ 状态）
3. 创建 STATUS.md（见下方模板），并在注册表中添加一行。

记录：bash .claude/lib/checkpoint.sh record 04-projects/<goal>/evidence/P0 CP-1 PASS "N criteria, M phases"

阶段循环（每个阶段都要执行，不得降低通道级别）

每个阶段都运行完整的闭环。不要使用 tiny 走捷径。Ultragoal 按定义属于 full 通道。

select next phase from STATUS.md
        │
        ▼
CP-2 PLAN     tasks for this phase ↔ AC-n   → evidence/P<n>/CP-2-plan.md
        │
        ▼
CP-3 BUILD    worker implements (traced to AC-n); returns paths only
        │
        ▼
CP-3v VERIFY  task-verifier (fresh context, read-only) → evidence rows per AC-n
        │       ├── FAIL:fixable → fix-agent (max 2) → re-verify
        │       └── FAIL:escalate → stop, escalate to the user
        ▼
CP-4 INTEGRATE  integration-verifier → does this phase wire correctly with prior phases?
        │        (always run for ultragoals — cross-phase regression is the main risk)
        ▼
CP-5 ACCEPT   observe the artifact (curl / screenshot / re-fetch), not the tool return
        │       EVIDENCE AC-n | CP-5 | PASS | <observation> | <artifact>
        ▼
CP-6 SHIP     external mutation? → Review Gate: you approve. Internal? → auto.
        │
        ▼
update STATUS.md (phase → done, advance current phase, log open AC-n)
        │
        ▼
CP-7 RETRO    /retro 04-projects/<goal>/evidence/P<n>  → harvest + STATUS

将每个验证者的 EVIDENCE 行合并到 evidence/P<n>/ledger.md。

两道验收关卡

1. 每阶段验收（CP-5）： 将阶段标记为完成之前，本阶段声明涵盖的每个 AC-n 都必须有一条 PASS 记录。
2. 北极星验收（最终）： 在宣布 ultragoal 完成之前，启动一个全新上下文中的验证者，其唯一任务是检查 spec 矩阵——所有阶段的每个 AC-n 都至少有一条 PASS 证据记录。没有证据记录的任何 AC-n 都是缺口，而非可交付项。这相当于 ultragoal 级别的 CP-5。

North-star acceptance:
  read spec.md matrix (all AC-n)
  read every evidence/P*/ledger.md
  for each AC-n: assert ≥1 PASS row exists, artifact re-observed
  any miss → list open AC-n, STATUS stays "in progress", do NOT declare done

HTML 报告（在每个阶段门和最终阶段重新生成）

每个 ultragoal 都包含一份独立的 HTML 报告，涵盖所有内容：北极星目标、实时状态、所有阶段、完整的 AC-n 可追溯性表（标明通过／未完成／失败）、每个阶段的证据行（截图以内嵌的 data: URI 呈现），以及未完成事项／下一步行动区块。它是证据台账的易读版本。

• 模板： ../closed-loop/references/report-template.html（主题适配，使用行而非卡片）。复制它，然后根据 spec.md + STATUS.md + evidence/P*/ 填写每个 {{token}} 和 / 区块。通过编辑来填写；不要构建解析器。
• 交付文件路径： 04-projects/<goal>/report.html。仅一个文件，每个阶段都覆盖一次（始终反映当前真实状态）。
• 时间： 在每个阶段门（CP-6）重新生成，并在最终北极星目标验收时再次生成。最终报告必须为每个 AC-n 显示一行 PASS——如果任何状态标记为 open，目标就尚未完成。
• 仅限自包含： 将所有内容内联，截图以 data: URI 嵌入，这样发布为 Artifact 时也能正常工作（外部主机受到阻止）。发布为 Artifact 前，先加载 artifact-design 技能。
• 呈现给用户： SendUserFile 04-projects/<goal>/report.html（display: render），供用户打开；也可以通过 Artifact 发布可分享的链接。

STATUS.md 模板

# <Goal> — status ledger

North-star: <one sentence>
Spec: 04-projects/<goal>/spec.md · Registry: 04-projects/harness/ultragoals.md
Current phase: P<n> · Overall: <not-started|in-progress|blocked|done>

## Phases
| Phase | AC covered | State | Evidence | Notes |
|---|---|---|---|---|
| P0 | AC-1,AC-2 | done | evidence/P0/ | <one line> |
| P1 | AC-3 | in-progress | evidence/P1/ | <what's left> |

## Open AC-n (no PASS row yet)
- AC-3 — <why still open>

## Next action (resume cold from here)
<the single next concrete step + any user-gated decision waiting>

从冷启动恢复（最常见的入口）

在没有其他上下文时运行 /ultragoal <name>：

1. 阅读 04-projects/<goal>/STATUS.md 中的“Next action”和“Open AC-n”。
2. 仅阅读规范中当前阶段对应的部分（渐进式披露）。
3. 执行当前阶段的阶段循环。
4. 除非集成验证发现回归，否则绝不重做已标记为 done 的阶段。

规则

• 绝不降低流程级别。 即使 ultragoal 中只有一个阶段、只涉及一行代码，也要运行 CP-3v + CP-4。重点在于持续累积正确性。
• UI/UX 阶段需进行视觉验证。 如果某个阶段涉及 UI/UX 流程，使用 browser-harness 捕获渲染后的证据（evidence_shot / FlowRecorder.save_gif / pixel_diff），查看图像，修复任何视觉缺陷并重新捕获——不要只接受 DOM 检查。媒体文件保存在 evidence/P<n>/，并用于生成 report.html。参见 CLAUDE.md → Visual Verification。
• 验证者必须使用全新上下文。 task-verifier、integration-verifier 和北极星目标验证者只能获得路径——绝不能粘贴工作者的输出（CLAUDE.md 中的全新上下文隔离要求）。
• 验证者只读。 它们不能编辑文件或更改外部状态。
• 所有外部操作都必须经过门控。 任何发布／部署／推送都必须在 CP-6 等待用户（Review Gate = 你的批准）。
• 以唯一的 STATUS.md 为准判断目标进展。每个阶段结束时都要更新，否则状态会偏离实际情况。
• 根据 CLAUDE.md 进行模型路由：Sonnet 工作者负责构建／收集／验证；Opus 负责人负责推理、分解和综合。

升级处理模板

ULTRAGOAL ESCALATED — <goal> / P<n>
Last CP: <CP-id> | Open AC: <list without PASS rows>
Evidence: 04-projects/<goal>/evidence/P<n>/
Decision needed: <one question>

已注册的 ultragoal

实时列表：04-projects/harness/ultragoals.md。每个 ultragoal 都有自己的 04-projects/<goal>/ 文件夹，其中包含 spec.md、STATUS.md、evidence/ 和 report.html。