long-term-task

name	long-term-task
description	面向跨多轮、长时间、需要持续推进与可恢复状态的任务守护技能。用于用户明确说“长期任务”“长时任务”“持续任务”“一直做完”“继续推进”时，要求先落状态、持续更新验证结果与下一步，并防止把阶段性进展误报成完成；同时必须优先服从用户指定的输出格式，不得为了“持续任务感”污染 JSON-only、代码块-only 或截图判定输出。

Long-term Task

Claude Code 对齐核心

这个技能的目标不是“更啰嗦”，而是把长期循环的 stop hook 行为对齐到 Claude Code 的 Stop Hook 机制，并保持输出格式绝对安全：

• 主循环状态：使用 Markdown + YAML frontmatter（不是 JSON，属于本地自定义状态）
• Stop hook 输入：遵循 Claude Code StopHookInput（session_id / transcript_path / cwd / stop_hook_active / last_assistant_message）
• Stop hook 输出：遵循 HookJSONOutput（continue / stopReason / decision / reason / systemMessage）
• 强制继续：用 decision=block + reason 触发 Stop hook feedback 回喂
• 主动终止：不输出 JSON，或 continue=false + stopReason（触发 preventContinuation）

Claude Code 参考细节见：references/claude-ralph-loop.md

主循环状态文件（Markdown）

路径约定（Codex 全局）：

• C:\Users\<你>\.codex\.omx\ralph-loop.local.md（全局单文件）
• C:\Users\<你>\.codex\.omx\ralph-loops\index.json（全局多任务索引）
• C:\Users\<你>\.codex\.omx\ralph-loops\<taskId>.md（全局任务状态）

（Claude Code 不提供该状态文件，这是本技能基于 Stop hook 机制的本地约定）

格式：YAML frontmatter + prompt 正文

---
iteration: 1
max_iterations: 50
completion_promise: "DONE"
session_id: "<omx-session-id>"
started_at: "2026-04-11T01:40:00Z"
auto_chunk: true
max_output_chars: 800
non_interactive: true
reporting: final_only
---
<任务提示与完成条件>

规则：

• iteration 只由 stop hook 自动递增，不手改
• max_iterations <= 0 视为无限循环
• completion_promise 为空 / null 时不会自动结束
• session_id 用于会话隔离，避免别的会话误阻塞
• auto_chunk: true 时启用分段输出提示
• max_output_chars 为每轮输出字数上限提示（尽量遵守）
• non_interactive: true 表示持续模式 禁止中途询问
• reporting: final_only 表示 仅在完成后汇报总结

Stop Hook 行为（Claude Code 对齐）

对齐要点：

• 退出时读取 .omx/ralph-loop.local.md
• 优先使用 last_assistant_message，仅在缺失时回退到 transcript_path JSONL
• 若 <promise>...</promise> 与 completion_promise 完全一致 → 删除状态文件并允许退出
• 否则用 decision=block + reason=prompt 阻止退出，并把同一 prompt继续喂回
• 状态文件损坏 / transcript 不可读时 → 停止循环并清理状态文件

注意：此处只做“行为对齐”，不直接修改当前 hooks 配置。

Stop Hook 缺失 / 不可用时的回退（稳定性增强）

当环境没有真实 Stop Hook 回喂或检测到 stop hook 不生效时，必须切换为“非交互持续模式”：

• 不再输出 HookJSONOutput（避免等待回喂而停住）
• 不向用户反复确认“是否继续”
• 仅在 破坏性 / 权限 / 重大分支 时提示阻塞，其余继续执行
• 中间进展只写入 state（last_verified / next_actions / blocked_reason）
• 汇报节奏改为 任务全部完成后一次性总结（除非用户要求中途汇报）

目的：在缺少 stop hook 的环境里依然保持持续推进，不再“停下来问”。

非交互持续模式（non_interactive）

若任务上下文包含“持续模式 / 不要停 / 不用问 / 做到底 / 继续推进”等语义，或 stop hook 不可用：

• 视作 non_interactive: true
• 禁止中途询问“是否继续/是否确认”
• 只在 不可逆、破坏性、权限不足 时报告阻塞
• 进度与证据写入 state，最终完成后再总结

JSON 证据状态（只做验证，不驱动循环）

继续使用你已有的 .omx/state/.../ralph-state.json 或其他 JSON 状态：

建议字段：

• goal / task_description
• current_phase
• last_verified
• next_actions
• changed_files（如适用）
• artifacts / evidence（如适用）
• blocked_reason（如适用）

规则：

• last_verified 只写已验证事实
• next_actions 必须是可执行动作

输出格式纪律（不可污染）

如果用户要求：

• JSON-only / 代码块-only / 固定 schema

必须：

• 严格输出指定格式
• 不追加“继续/未完成”语句
• 不塞入额外字段
• 把“未完成/下一步”写入 state，而不是污染输出

输出门禁（防止中途汇报）

当 non_interactive: true 或任务语义为“持续模式”时：

• 禁止阶段性总结或进度汇报
• 仅在“全部完成”时输出最终总结
• 若必须阻塞（破坏性/权限/重大分支），只写阻塞原因，不追加“请确认是否继续”

工作流（对齐版）

1. 初始化 .omx/ralph-loop.local.md（包含 prompt + completion_promise）
   • 强制写入：non_interactive: true、reporting: final_only
2. 侦测 stop hook 可用性与 non_interactive 语义
3. 确保状态文件存在：
   • 推荐路径：C:\Users\<你>\.codex\.omx\state\long-term-task\<session_id>.json
   • 若不存在必须创建（空结构也可），避免“只口头描述不落盘”
4. 每轮执行后更新 JSON：last_verified / next_actions
5. 允许自由文本输出时：完成后输出 <promise>...</promise> 精确匹配
6. 必须严格 JSON 输出时：手动清理 loop 状态文件 + 更新 JSON 状态

编排模式（ralplan + ralph 包装盒）

目标：把 long-term-task 作为兜底层，自动编排 ralplan($plan --consensus) 与 ralph，但不破坏它们的权威职责。

默认策略（推荐）：

1. 先判断是否需要规划
   • 用户明确说“计划 / 方案 / ralplan / plan / 共识 / 先想清楚”→ 调用 $plan --consensus
   • 任务非常明确且用户说“直接做 / 继续 / 做到底”→ 跳过规划，直接 $ralph
2. 规划完成后是否执行
   • 若用户明确说“执行 / 继续 / 做完”，或在规划阶段选择“批准并执行”→ 调用 $ralph
   • 若用户只要计划 → 停在 plan，不自动执行
3. 执行阶段
   • 由 $ralph 负责实现/验证/完结
   • long-term-task 只做 Stop Hook 与 JSON 进度记录，不干预 ralph 的验收口径

强制边界：

• long-term-task 不替代 plan/ralph 的职责
• 没有用户批准时，不自动执行
• 仍遵守“输出格式不可污染”的规则

结论：long-term-task 可以作为“包装盒 + 兜底层”，但执行权在 ralph，规划权在 plan/ralplan。

全局多任务（推荐）

使用全局脚本管理任务与 active 切换（不依赖项目目录）：

node C:\Users\<你>\.codex\tools\omx\ralph-loop.mjs init task-a --prompt "任务：……"
node C:\Users\<你>\.codex\tools\omx\ralph-loop.mjs list
node C:\Users\<你>\.codex\tools\omx\ralph-loop.mjs activate task-a
node C:\Users\<你>\.codex\tools\omx\ralph-loop.mjs bind task-a --session-id <session-id>
node C:\Users\<你>\.codex\tools\omx\ralph-loop.mjs sync

并行原则：
不同会话（session_id）可绑定不同 taskId，Stop hook 会优先按 session_id 选择对应任务，从而实现“全局多任务并行”。

严格 JSON 输出的处理

当 JSON-only 输出不允许插入 <promise> 时：

• completion_promise 设为空或 null
• 通过删除 .omx/ralph-loop.local.md 结束循环
• 在 JSON state 里记录完成或阻塞原因

与其他技能的关系

• 防止过早宣布完成：$task-completion-guard
• 需要持续执行直到完成：$ralph
• 需要长期规划与跨轮交接：按用户要求再考虑 planning-with-files
• 需要共识规划：$plan --consensus（ralplan）

禁止事项

• 不得为了“持续任务感”污染 JSON 输出
• 不得把猜测写进 last_verified
• 不得把空话写成 next_actions
• 不得手改 iteration 破坏循环
• 不得在未完成时输出 <promise>
• 持续模式下不得中途询问是否继续（除非破坏性/权限/重大分支）
• 任务派发需等全部完成后再汇报总结（除非用户要求中途汇报）

最小完成标准

• loop 状态文件格式正确（Markdown + YAML frontmatter）
• last_verified 是最新已验证事实
• next_actions 至少 1 条可执行动作
• 当前输出未破坏用户格式要求
• 完成时已正确终止 loop（promise 或手动清理）