onevoke: Instructions file for Codex

Repository Guidelines

本文件是 Onevoke 仓库自身的开发规则. 仓库对外发布的工作流规则在 rules/, 那些文件是交付物, 不是本仓库的开发指引.

本仓库特例

• 本仓库第二阶段安全角色 CSA 和 Hacker 一律标记 N/A, 不运行; PM 和 QA 保持适用.
• 审核 base 以来全部改动都是 Markdown 规则或文档时, 不运行审核. 只要包含任一脚本, 代码或其他非 Markdown 文件, 就按适用规则运行 PM 和 QA; CSA 和 Hacker 仍按上一条标记 N/A.
• 对外发布的分支模型固定为 main 稳定分支加 develop 集成分支, 不提供其他长期分支或集成分支选项; 缺少 develop 时从 main 自动初始化.
• 功能或修复改完后默认: 在 develop 提交 → fast-forward 合入 main → 推送 develop 与 main → POSIX 运行 ./install.sh, 原生 Windows 运行 install.ps1 更新本机安装; 用户另有指示时除外.

Project Structure & Module Organization

• rules/ONEVOKE-AGENTS.md 是发布规则的入口, 只放分册索引, 优先级和默认行为. 其余分册由它的分册表按需引用: BASE-RULES.md 跨项目通用条款, KANBAN-RULES.md 看板行为契约, GIT-RULES.md Git 工作流, REVIEW-RULES.md 审核契约, CODE-RULES.md 架构与代码质量契约. 它们是面向用户和 Agent 的对外接口, 改动前确认与 bin/ 下实现一致. 全部装到 ~/.agents/ 下的同名文件.
• install.sh 与 install.ps1 分别是 POSIX 和原生 Windows 安装器. 两者遍历 bin/* 和 rules/*.md, 把全部普通文件直接覆盖到 ~/.local/bin/ 与 ~/.agents/, 包括 ONEVOKE-AGENTS.md; Windows 安装器不修改用户 PATH, 必须提示用户把 ~/.local/bin 加入 PATH, 命令通过 .cmd 包装入口运行. Windows 安装器读取既有配置语言时必须实际执行候选 Python 3, py -3 失败后继续探测 python.exe, 再探测 python3.exe; 跳过 0 字节的 Windows App Execution Alias (会打开微软商店的重定向器), 已安装的商店版 Python 从其 AppX 包目录取真实 python.exe; 不得从 PowerShell 当前 FileSystem provider 位置或 Win32 进程当前目录选择同名程序, 拒绝这些候选后须继续探测 PATH 中后续同名程序. 若存在 share/kanban-web/, 同步安装到 ~/.local/share/onevoke/kanban-web/ 供 kanban web 使用. 升级时检测已退役的 codex-review.sh、claude-review.sh 和 grok-review.sh, 提示用户且仅在明确确认后删除; 拒绝或无输入时保留. ~/.agents/AGENTS.md 不存在时, POSIX 创建指向 ONEVOKE-AGENTS.md 的相对符号链接, Windows 优先创建硬链接并回落到符号链接, 两者都不得用独立副本冒充入口; 已有任何同名入口时保持不变. 唯一稳定 stdout 按 locale 为 Onevoke 已安装 或 Onevoke installed; 全局安装最后必须用绝对路径运行 onevoke welcome. POSIX install.sh --project <目录> 把同一套载荷只装到目标 Git 项目主 worktree 的 .onevoke/ (命令、规则、share), 幂等写入本地 /.onevoke/ exclude, 目标从任一 worktree 指定都归一到主 worktree; 不创建、修改或探测 HOME 下 Onevoke 路径, 不运行 welcome, 不修改 PATH, 不迁移或卸载全局安装. 非 Git、无效参数、目录或符号链接目标拒绝且不回落全局安装. 项目安装成功时 stdout 在稳定安装行之后给出项目本地 onevoke 与 kanban 绝对路径. 同名目标是目录或 Windows reparse point 时须在写任何文件前拒绝, 防止安装器把源文件写入错误边界.
• bin/onevoke_config.py 是 onevoke 与 kanban 共用的配置边界, 配置默认在 ~/.config/onevoke/config.json, 测试用 ONEVOKE_CONFIG 隔离. install_paths() 按当前入口解析作用域: 入口位于 .onevoke/bin/ 时为项目模式, 路径落在 Git 主 worktree 的 .onevoke/ (config, rules, bin, share), 否则为全局模式并保持 ~/.config/onevoke/config.json, ~/.agents, ~/.local/bin, ~/.local/share/onevoke; 源码树的 bin/ 与 rules/ 不得判为项目安装. ONEVOKE_CONFIG 仍覆盖 config_path(). project_install_paths(project) 供安装器把目标归一到主 worktree; ensure_project_git_exclude(project) 幂等写入 /.onevoke/ 到本地 info/exclude, 保持既有权限, 复用 onevoke_fs 的 no-follow 追加与锁, 不安全链接边界必须失败. 配置写入必须校验 schema; POSIX 用同目录临时文件加 os.replace() 原子替换, 权限为 0600. Windows 的 configured_language, 读取和写入必须从卷/UNC anchor 逐分量 no-follow, 拒绝符号链接、junction 等 reparse point; load 在不共享 WRITE/DELETE 的同一固定句柄上完成读取、schema 校验和旧配置 DACL 迁移, 无效配置不迁移 ACL; save 仅收紧本次新建的配置目录, 临时文件必须先变为当前用户独占的受保护 DACL 再写入, 最后相对固定父句柄原子替换; 不得收紧既有祖先目录. 任一权限或安全后端失败必须报错. language 为 cn/en, 默认 cn, 可在 welcome 设置; 生效优先级为 --lang (经 ONEVOKE_LANG_CLI 跨进程传递) > 配置 > 环境变量. launcher 允许 auto/tmux/tmux-session/herdr/foreground/console, POSIX 默认 auto, Windows 默认 console; console 仅支持 Windows; auto 与 herdr 仅支持 POSIX. kanban_agent 是默认执行 Agent, 可选的 kanban_agents 段按 large/small 两种任务卡规模分别指定执行 Agent, 缺失的规模回落到 kanban_agent, 未知规模或非法 Agent 拒绝, kanban_agent_for(config, kind) 与 execution_agents_in_use(config) 是 kanban/onevoke 共用的读取口; models 段保存 kanban 与 review 的模型和推理档位, 缺失层级用默认值补齐, 未知键拒绝; model/large_model/small_model 允许空串表示用 CLI 默认模型. review_stages 为 PM/CSA/Hacker/QA 各指定 auto/skip/required, 缺省全为 auto. 它同时是脚本, review-model <agent> 子命令输出两行 (<model> 与 <effort>, model 可为空行) 供 onevoke_review.py 读取; review-stages 按角色顺序输出四行环节策略; configured-language 在配置文件存在时输出 cn/en.
• bin/onevoke 提供 welcome, doctor, config, review. 入口位于 .onevoke/bin/ 时四个子命令都使用项目安装上下文: 配置读写项目 .onevoke/config.json, doctor/welcome 的命令检查与规则接入以项目命令根和规则入口为准, POSIX review 只执行同目录 onevoke-review.sh; 本地配置或审核门禁缺失时不得回落全局配置、~/.local/bin 或 PATH 中的同名入口. 源码树与全局入口保持既有 PATH 行为. welcome 只在 tty 中提问, 无 tty 时诊断后正常提示重跑; 它显示当前配置总览, 只进入用户选择的单项编辑; stdin/stderr 均为 tty 时用方向键菜单 (Enter 确认, 数字跳转, 总览默认停在保存, q 取消; yes/no 为是/否并支持 y/n), 否则回落编号/文本输入. 「执行 Agent」菜单先问大任务 Agent 再问小任务 Agent, 写入 kanban_agents 并把 kanban_agent 设为大任务 Agent; doctor, 规则接入检查和 onevoke config 都按 execution_agents_in_use 覆盖实际用到的每个执行 Agent; MemSearch 由 reconcile_memsearch 按最终配置对账: 在菜单确认启用时执行, 以及执行 Agent 集合相对既有配置有变化时在保存前执行 (未改 Agent 的既有配置原样保留), 对每个受支持 (Codex, Claude) 且尚未覆盖的在用 Agent 执行安装或给出安装提示 (既有已启用配置里的受支持 Agent 视为已覆盖), 不受支持的在用 Agent 逐个告警, 全部不受支持时关闭 MemSearch 并告警. 依赖安装必须经用户明确选择; 模型菜单只列本次配置用到的执行 Agent 和 Reviewer; Windows 优先用 PATH 中的 <name>.exe, 只有 .cmd/.bat 时通过 cmd.exe /d /s /v:off /c 启动并可执行 --version; Windows launcher 菜单只列 console 与 foreground, POSIX 把 auto 放在最前, 再按 tmux 与 herdr 可用性列适用选项; herdr 已安装或当前已选 herdr 时列在 tmux-session 之后, foreground 之前; 审核环节菜单为四角色配置 auto/skip/required. MemSearch Codex 插件只克隆官方仓库并运行上游安装脚本, 不检查仓库和安装状态; 上游安装器需要 Bash, 因此原生 Windows 当前不启用该集成. review 按角色配置选择 Codex、Claude、Grok 或 Cursor, POSIX 全局模式分发到 PATH 中的 onevoke-review.sh, Windows 直接用当前 Python 进入同目录的 onevoke_review.py, 两者共享唯一门禁实现.
• bin/kanban 命令细节 (自 rules/KANBAN-RULES.md 迁入, 改实现时同步更新本条): init 幂等创建看板和 7 个状态目录 (backlog, todo, working, review, done, archived, trash); 旧看板缺 review 且其余 6 个目录齐全时, ensure_layout 在任一命令定位看板时用同一 create_state_directory 自动补建, 其他目录缺失或 review 被文件/reparse point 占用仍全部失败, Git 项目只写本地 .git/info/exclude, 最后输出当前作用域规则路径; Windows 新看板目录必须用固定父句柄和 CREATE_NEW 在创建时应用私有 DACL, 创建竞态失败关闭, 既有目录只迁移叶目录 ACL; Git exclude 的父链逐分量 no-follow, 既有 ACL 保持不变, 去重读取与追加使用同一固定叶句柄及文件锁. rules 不要求已有看板, 按当前入口输出全局 ~/.agents/KANBAN-RULES.md 或项目 .onevoke/rules/KANBAN-RULES.md, 项目模式不回落全局规则. list 按状态分组、组内按显示时间倒序, 同时或缺失时按任务 ID 倒序, 默认彩色表格并标出规模, --mobile 输出竖屏布局; working 显示开始时间, done 显示完成时间, 旧卡缺完成时间时用文档最后修改时间. new 在 backlog/ 创建小任务, --large 创建含 spec.md 的大任务目录. pick 执行 backlog -> todo 及完整性校验, 不给 ID 时只列候选; move 只执行状态模型允许且满足目标要求的迁移, review 只能从 working 进入且要求已填 任务分支, 可迁回 working 或进 done. start 只接受 todo 卡, 按卡片规模用 kanban_agent_for 选 Agent (--agent 优先), 卡片有 任务组 时 prompt 改为任务组版本 (开发, 验证, 提交 push 并汇入组分支后 move review 退出, 不自行审核集成), 否则为单卡版本, 原子执行 todo -> working、写负责人, 开始时间和 会话 (Claude/Grok 预分配 UUID 经 --session-id 传入, Cursor 先 create-chat 预建 chat 并以 --resume <chat> 启动, 失败不领取; Codex 只记 Agent 名; 旧卡缺 会话 行时插在负责人后) 再启动 Agent, 成功输出含规模与实际 Agent; resume 只接受 review/working 卡, 必须且只能给 --message 或 --message-file 之一, 用卡片 会话 记录的原 Agent 恢复会话 (Claude/Grok --resume <uuid>, Cursor --resume <chat>, Codex resume <id> 且 id 在 CODEX_HOME/~/.codex 的 sessions/**/rollout-*.jsonl 中按 mtime 倒序检索以该任务 start/resume prompt 开头的用户消息), review 卡先迁回 working, 启动失败迁回, working 卡不迁移, prompt 为固定说明加事项正文; start 与 resume 共用 prepare_launch/launch_agent/rollback_launch/report_launch, 回滚先恢复文档再迁回原状态, 文档没恢复就不迁回且报错写明卡片实际所在目录, 项目模式 prompt 使用命令根下 kanban 与主 worktree AGENTS.md 的绝对路径且从 task worktree 调用仍指向主 worktree 安装; 模型和大小任务的推理档位读生效配置的 models.kanban.<agent>, 默认值为 Codex gpt-5.6-sol high/medium, Claude opus high/medium, Grok 不锁模型 xhigh/high, Cursor 用完整模型 id cursor-grok-4.6-xhigh/cursor-grok-4.6-high 且无 effort, 模型为空串时不传 --model; 六种 launcher 的 cwd 都是项目根, auto 在启动当时按 HERDR_ENV 再 TMUX 解析为 herdr 或 tmux 且不写回配置, 两者都不在则失败且不领取, 不回落到 tmux-session 或 foreground, tmux 只在当前 session 建 kb-<任务标题> window 不建 session, tmux-session 按项目根绝对路径算出 kb-<目录名>-<sha256 前 8 位> 的专属 session, 不存在时 new-session -d 新建并 best-effort 写 @onevoke_project 标记, 已存在且标记为空或匹配时复用并 new-window, 标记属于其他项目时退避到 -2…-9 候选, herdr 要求 HERDR_ENV=1 且 herdr 在 PATH, 在当前 workspace 新建 tab 后用 pane wait-output --regex '\S' --source visible --timeout 等根 pane 渲染出首帧输出 (未就绪时 pane run 的命令文本会被终端丢弃), 再在根 pane 执行与 tmux 相同的 Agent 命令, 创建 tab, 就绪等待或 pane run 失败时回滚卡片, 后两者还须关闭本次新建的 tab, foreground 要求三个标准流都是 TTY 并等待 Agent 退出, console 仅支持 Windows, 用独立控制台启动后返回 PID. console 不创建或复用 session, 不支持 attach 或输出抓取, 不得描述为 tmux 等价实现. 前置任务 固定写在 讨论与决策 开头, 允许用 ASCII 逗号混写任务 ID 与任务组 ID, N/A 或整行缺失表示无依赖; task_dependencies 统一返回组内卡、组外卡、任务组三类引用以及任务组当前成员展开后的任务 ID. check 不带目标时默认列出除 done/archived 外的无效入口并校验这些卡片的依赖引用存在且无环, --all 才纳入 done 与 archived; 指定任务 ID 时只检查这些精确目标及其跨状态/形态冲突和可达依赖图, 无关无效入口不影响结果, 显式指定的 done/archived 卡仍检查; 默认遇 done/archived 前置卡只确认引用存在, --all 才沿完整可达图检查; 依赖尚未满足不导致失败. 无参和 --all 探测全部 working/ 卡, 定向只探测指定目标中的 working/ 卡且跳过 review/; 四态为 alive/stopped/drifted/unknown, 纯只读且不影响退出码, Windows 与 foreground/console 恒为 unknown, herdr 未上报会话身份但 Agent 与状态匹配时为 alive 并提示无法直投. subscribe 校验显式任务组与成员后输出稳定 JSON Lines: 初始 snapshot, 状态变化 state-change, 默认 15 分钟无变化的 heartbeat; 探测集合包含指定成员及可选 --watch 展开的外部目标, 并沿用 no-follow/reparse 拒绝边界; heartbeat 仅在存在 working/ 被监控任务时携带 liveness 映射, 每项含 agent/status/channel/detail, 探测失败折算 unknown 且不结束订阅. 其他命令忽略无关的无效入口只在目标任务违规时失败, 状态目录缺失或不可写时全部失败. web 的 --host/--port 覆盖监听地址, --refresh 控制服务端扫描秒数, --assets 覆盖资源目录, --open 尝试打开浏览器; tui 的 --single 强制单栏, 默认每栏最小 40 列并按宽度自适应显示部分或全部栏目, 可用 -/= 调节栏宽并写入当前作用域配置目录的 tui.json (测试用 ONEVOKE_CONFIG 同目录), 不足最小栏宽时按实际宽度显示单栏并保证选中栏可见, --refresh 控制自动刷新秒数 (默认 30), --theme 指定 auto/light/dark 配色 (运行中用 t 循环切换), 且要求 stdin/stdout 都是 TTY. start 还在紧随 会话 的 窗口 字段记录投递地址: herdr 为 herdr:<tab-id>:<pane-id>, tmux/tmux-session 为 <launcher>:<session-id>:<window-id>:<pane-id>, foreground/console 为 launcher 名, 缺字段的旧卡在 start 时插入. tmux/tmux-session 先创建占位 window/pane, 持久化地址后才 respawn-pane 启动 Agent, 再用 tmux set-option -p -t <pane-id> @onevoke_session <会话-id> 写入 pane 会话标记; Claude/Grok/Cursor 取卡片记录的 id, Codex 复用 notify/resume 的 rollout 解析取得 id. 地址写入、Agent 启动或 pane 会话标记写入失败都关闭本次 window 并回滚. notify 是主控派回事项的单一接口, 与 resume 使用相同的消息入参与状态范围并接受 --pane herdr 覆盖及大于 60 的有限 --timeout (默认 120 秒). 地址优先取 --pane, 再取 窗口; 缺窗口时按 Agent 与会话 id 从 herdr pane list 唯一反查并回写, 卡片已有 id 的 Agent 直接比对, 只有旧 Codex 缺 id 时复用 rollout 检索. 反查不设 Agent 白名单, 覆盖范围取决于 herdr 版本和各 Agent 集成是否报告 agent_session.value; tmux 缺窗口时不可反查. herdr 按 pane、Agent、会话 id 并仅在 idle 或 done 状态直投; tmux 系同时校验 pane_current_command, pane_in_mode, pane_dead 和 pane 的 @onevoke_session, 后者必须非空且与卡片解析出的会话 id 完全一致, 缺失时因身份不可证而回落, 不降级为进程名级放行; 不一致属于地址过期, 先反查并只在唯一命中且复检通过后直投. 两类会话标记都只防同用户环境内的误投, 不构成抵御同用户恶意伪造的安全边界. 只在直投地址与探查通过后创建正文载荷, foreground/console 回落不创建; 正文写入创建时即收紧的 0700 私有目录中的 0600 文件, 终端只接收以 # onevoke-notify: 开头的单行路径与 marker 指令; herdr 用 agent prompt <pane-id> <instruction> 投给 pane 内已在运行的 Agent TUI (按 pane 实际的 bracketed-paste 模式送正文并延时补一次编码后的 Enter, Agent 停在审批或提问 UI 时先行拒绝), 不用面向 shell 的 pane run (同批写入的结尾 CR 在 Cursor 等 TUI 不算提交, 正文会停在输入栏), 也不用只接受按键名的 pane send-keys, tmux 用 send-keys -l 后单独发送 Enter. herdr 用 pane wait-output --match <marker> --source recent 做字面子串匹配, tmux 用有界 capture-pane 按字面子串轮询 marker. 投递动作成功即迁卡并成功返回, marker 超时只警告未确认且不恢复; foreground/console、无通道、探查或发送失败才由 notify 内部恢复原会话; process 型恢复观察完整 timeout, foreground 迁卡后继续附着等待 Agent, herdr 恢复对本次新建 pane 校验 Agent 与 idle/working/blocked 状态, 有非空 agent_session.value 时还须与卡片会话匹配, 未上报有效身份时不因此失败; 该存活判据只判断已知新 pane, 不作为同用户安全边界; done/unknown 仍拒绝; 清理失败与原错误合并并提示新 Agent 可能仍存活. 两路都失败时保持正文与状态并同时报告原因; 主控只调用一次 notify, 不自行执行回落. resume 也接受大于 60 的有限 --timeout (默认 120 秒), 启动成功后复用 notify 恢复分支的 validate_resumed_agent: herdr 对本次新建 pane 使用上一条的存活判据, tmux/tmux-session 按可寻址终端判活, foreground 与 console 在完整 timeout 观察期内要求进程不退出. 这里的启动失败包括存活校验失败; 失败时先收集可取得的 Agent 原始输出并清理新实例, 再由 rollback_launch 恢复原文档和状态, 文档恢复失败则不迁回并报告卡片实际目录. 只有校验通过才报告 已唤醒. resume 默认恢复卡片原 Agent 和原会话; 显式 --agent (即使同名) 表示用户授权以全新会话接管, 覆写 负责人/会话/窗口 而不改 开始时间, 失败时整文和状态回滚. tmux/tmux-session 的新 Codex 会话发现精确 id 后写回卡片; herdr/进程型保留无 id 的 codex. 新 Agent 存活后按 dismiss 的身份及单 pane 拓扑门禁尝试优雅退出和关闭原容器; 无地址、foreground/console、Windows 或新旧地址相同记 N/A, 校验或清理失败只报告原容器保留, 不强杀且不回滚接管. 存活与清理各可占用一次完整 timeout, 最坏约 2 倍; 先输出原容器清理/保留行, 再输出 已接管. herdr 的 pane run 成功且卡片会话 reference 非空时, start 与 resume/notify 恢复通道共用 launcher 内的上报路径: Onevoke 通过 HERDR_SOCKET_PATH 调用 pane.report_agent_session, 参数取本次 pane id、卡片 Agent、卡片 reference、source=herdr:<agent> 与单调递增的 seq, 再在有界预算内用 pane get 读回相同的 agent_session.value; 空 reference (包括新启动且尚未发现 id 的 Codex) 不上报. socket、响应或读回失败只输出一条告警, 不使启动失败, 不回滚卡片或关闭 tab. herdr 自身集成仍可上报同一身份; Onevoke 的路径用于补齐未触发集成钩子的启动方式. herdr 在 pane run 成功后即算启动成功, 后续上报不进入 LaunchFailure 的清理与回滚路径. Windows 的 notify 消息临时根只用 GetTempPathW 取得词法路径, 不经 tempfile 探测或 Path.resolve(); 后续由 no-follow 句柄边界逐分量拒绝 reparse point, 再创建 protected DACL 的私有目录与文件. subscribe --watch 可重复指定组外任务或任务组, 后者通过 task_group_members 共用读取口展开当前成员; 不校验外部目标的组归属, 但拒绝不存在, 空展开及与成员或其他外部目标重复. 三类事件的 tasks 同时包含成员和外部目标, 传入 --watch 时每条事件另含顶层 watched 外部任务 ID 数组, 外部变化同样触发状态事件并重置心跳; 未传时保持既有 JSON 输出和探测边界. dismiss 只接受 done/ 或 archived/ 卡且不修改卡片, --timeout 必须是大于 60 的有限秒数并默认 120 秒. 它按卡片地址定位 herdr 或 tmux/tmux-session pane; 缺地址的旧 herdr 卡与 pane 不存在/已死, Agent, 会话标记或前台进程不匹配的过期地址允许按 Agent 与会话唯一反查, 0 或多命中与忙态仍拒绝. 反查后以命中 pane 的实际 herdr tab 或 tmux session/window 重跑身份和拓扑校验, 不回写卡片地址; 投递退出命令前必须验证 Agent、会话、运行状态、pane 当前所属容器与定位结果完全一致, 并确认容器只含该 pane. Claude/Codex 送 /exit, Grok/Cursor 送 /quit; 仅在有界等待确认 Agent 退出后关闭经验证的 tab/window. 身份、拓扑、投递、退出确认、关闭或超时失败均保留现场且不强杀; Windows、foreground 与 console 在无部分动作下拒绝.
• bin/kanban 的 start 未传 --agent 时按卡片规模读取生效的 kanban_agents.large/kanban_agents.small; --agent 始终优先. --launcher 可覆盖本次启动且不改机器配置; launcher 为 auto 时在领取前解析且 Windows 拒绝, 为 tmux 时在当前 session 后台创建独立 window 且必须已在 tmux session 内, 为 tmux-session 时不要求已在 tmux 内, 新建或复用 session 时都后台创建 window, 启动后不 attach 或 switch-client, 只打印 session 名, window id 和 attach 提示, 为 herdr 时必须处于 herdr (HERDR_ENV=1) 且 herdr 在 PATH, 后台新建不获取焦点的 tab 后打印 tab id 和 pane id, Windows 拒绝 herdr 和 auto, 为 foreground 时必须有交互 tty 并在当前终端等待 Agent 退出, 为 console 时必须是 Windows, 创建独立控制台进程后打印 PID 并立即返回. web 启动只读看板 UI, 默认 127.0.0.1:8080, 服务端默认每 60 秒扫描并仅在内容变化时通过 SSE 推送, 客户端按任务 ID 原位更新; 资源来自当前作用域 share/kanban-web/ (全局为源码树或 ~/.local/share/onevoke/kanban-web/, 项目为 .onevoke/share/kanban-web/, 项目模式不回落全局资源), 由 bin/kanban_web.py 用标准库 HTTP 服务和 string.Template 渲染, 是原生 Windows 第一阶段保证的看板 UI. tui 复用 Web payload 的扫描、排序和搜索字段 (经 scan 而非 load_board, 不向 stderr 注入无效入口警告), 默认按终端宽度显示活跃栏目, 宽度不足时少显示或按实际宽度显示单栏并保持选中栏可见, -/= 调节并记住栏宽, a 切换到全部 7 栏, y 复制当前任务 ID, 任务卡与详情支持鼠标拖选自动复制, 详情内 v/V 切换字符/行选择并用 y 复制; bin/kanban_tui.py 依赖 curses 负责多栏/单栏导航、鼠标点选与滚轮、任务详情 (vim 翻页与正文搜索)、终端缩放和默认每 30 秒的原位刷新, 刷新时按任务 ID 更新并尽量保留选中项和滚动位置. Windows 上只有当前 Python 提供可用 curses 后端时才能运行 TUI, 本阶段不保证.
• 新增分册时把它加进 ONEVOKE-AGENTS.md 的分册表即可; install.sh, install.ps1 和安装测试都遍历 rules/*.md, 不必改.
• 本仓库根目录的 AGENTS.md 是本仓库自己的开发规则, 与 rules/ 下的发布物是两回事, 不要混改.
• bin/kanban 是 Python 3 CLI 的唯一实现入口, 包含看板定位、任务校验、状态迁移和命令解析; bin/kanban_probe.py 封装 herdr/tmux pane 事实采集, 不包含投递或存活策略; bin/kanban_liveness.py 封装 check/subscribe 共用的只读存活分类和 notify 共用的会话反查; bin/kanban_notify.py 封装 notify 的 ready/busy/stale/fallback 分类、忙态重试和过期地址反查决策; bin/kanban.cmd 是 Windows 包装入口. bin/kanban_web.py 与 bin/kanban_tui.py 分别封装只读 Web 和终端界面. bin/onevoke 负责首次引导、环境诊断、配置展示和 Reviewer 分发, bin/onevoke.cmd 是 Windows 包装入口.
• bin/onevoke_process.py 集中解析 Agent CLI, 创建 UTF-8 任务文件与构建进程调用. 执行 Agent 和 Reviewer 都只把必需控制参数与短文件指令交给 CLI; 任务文件不检查 POSIX 权限或 Windows ACL, 并要求 Agent 在完成后尝试删除, 遗留不影响结果. Windows 优先解析 .exe, 只有 .cmd/.bat 时用显式 cmd.exe /d /s /v:off /c 和环境变量承载的已编码参数启动, 不用 shell=True, 不作为任意批处理脚本的通用契约. bin/onevoke_review.py 是 Codex、Claude、Grok 与 Cursor 共用的单一审核门禁实现, 集中维护 commit 校验、evidence、prompt 骨架、超时监督和 worktree 篡改检测; 第 7 个可选位置参数 reviewed-commit 触发增量复审: 它必须是完整 SHA, 在 base 之后且在 commit 之前, evidence 追加 reviewed..commit 的 FIX RANGE 段, prompt 的范围规则换成「只核实上轮 finding 闭环 + 只审修复范围」, 空串表示全量审核; POSIX 的公开入口是 bin/onevoke-review.sh, Windows 的人工交互入口是 bin/onevoke-review.cmd, onevoke review 的 Windows 程序化分发直接进入该 Python 实现. 模型与推理档位按 环境变量 > Onevoke 配置 > 内置默认 解析, 配置读取失败时回落到内置默认, 不阻塞审核. 用户可见输出语言优先级为 ONEVOKE_LANG_CLI 标记的显式 --lang > 配置 > 环境变量. Codex 在目标 worktree 内以 --sandbox read-only --ephemeral 运行; Claude 在外部 runtime 目录以 --permission-mode plan --tools Read,Grep,Glob --safe-mode --no-session-persistence 运行; Grok 在外部 runtime 目录以 --sandbox read-only --no-memory --no-subagents 运行且只开放 read_file,grep,list_dir; Cursor 在外部 runtime 目录以 --print --output-format json --trust 运行, 把 CURSOR_CONFIG_DIR/CURSOR_DATA_DIR 指向该 runtime, 不做 --sandbox 事前阻断. Reviewer 退出后一律对其进程组发 SIGKILL 并等到组内无非 zombie 成员, 收不尽即审核失败; 「是否因残留而拒绝结果」按 AgentSettings.spawns_helper_processes 分两档: 默认档 (Codex, Claude, Grok) 保持 Reviewer 退出瞬间进程组非空即拒绝; Cursor 置位该标记, 因为 cursor-agent 必然为自己拉起 worker-server 及经 npx 启动的 language server 且不等其收尾, 严格判定会恒定拒绝每一次正常审核. 置位后改用父链归属判定: monitor_process 在 Reviewer 存活期间按 TREE_OBSERVE_INTERVAL 采样进程表, 把能经父链回到组长的成员记为 Reviewer 自身进程树, 只有组内却已脱离父链的 detached 后代 (双 fork 后被 init 收养) 才判为残留并拒绝结果. 采样只能在 Reviewer 存活时进行 — 它一退出子进程即被收养, 父链随即丢失. 拿不到采样结果或拿不到进程表时 fail-closed, 回到默认档的严格判定. 该放宽不改变容器边界 (整组仍被 SIGKILL 收尽), 只改变信任判定, 兜底仍是审核结束后的工作树闸门. Windows 通过 GetTempPathW 只取得临时根的词法路径, 不允许 tempfile 在 no-follow 校验前写探测; runtime 从固定临时根句柄以 CREATE_NEW 和创建时 protected DACL 生成, 随机名碰撞重试, 不得先发布继承 ACL 的目录再收紧. runtime 的根句柄必须不共享 WRITE/DELETE 并持有到 Reviewer 进程树收集、worktree 校验和敏感文件清理完成, 阻止入口改名及原地切换为 reparse point; 清理必须从该固定句柄逐层拒绝 reparse point, 并受深度、条目与轮次预算约束, 任一清理失败都使审核失败. Windows 适配不得改变隔离参数. 新增 reviewer 只扩展该实现的 agent 适配层, 不新增脚本.
• bin/onevoke_fs.py 是跨平台安全文件边界. POSIX 继续使用 no-follow/openat 语义、0600/0700 和 flock; Windows 必须拒绝符号链接、junction 等所有 reparse point, 用已校验的 Win32 句柄完成普通文件读写、同边界原子替换与迁移, 用受保护 DACL 限制私有对象的当前用户访问, 用 LockFileEx 实现阻塞式独占锁. 私有对象不得回落到继承 ACL; Git exclude 等明确保持既有权限的中性对象可继承父 ACL, 但仍必须逐分量 no-follow 并固定句柄. 不得在 Windows 回落到未经句柄校验的 Path.rename() 或无锁实现. bin/merge-worktree-memory.py 在集成后合并 worktree 的 memsearch 记忆, 清除合并结果中的非法 UTF-8 字节, 并通过该文件系统层固定来源/目标句柄、拒绝 reparse point、迁移目标记忆 DACL 及加锁; Linux 合并成功后还须用 pidfd 固定并停止来源 .memsearch/.watch.pid 指向的同路径 MemSearch watcher, 等待独立进程组全部退出并再次合并停止期间的最终写入, 其他 POSIX 遇到存活 watcher 时 fail-closed, 失败时保留 worktree; Windows 由 bin/merge-worktree-memory.cmd 包装启动.
• tests/test-onevoke.py 用临时 HOME 和伪终端覆盖 welcome、配置和 Reviewer 分发, 并覆盖项目安装上下文的成功与拒绝路径. tests/test-onevoke-config.py 覆盖安装上下文解析与项目 Git exclude 的成功和拒绝路径; tests/test-onevoke-process.py 覆盖跨平台 Agent 解析、临时任务文件与 Windows batch 参数编码. tests/test-kanban.py 覆盖看板生命周期 (含 review 状态迁移)、按规模选 Agent、会话 记录、resume 的四种 Agent 恢复参数、Codex rollout 检索与回滚、POSIX launcher (含 tmux-session 的建/复用/退避/回滚和 herdr 的成功、拒绝与回滚)、安装及初始化, 并用伪终端覆盖 TUI 启动退出; tests/kanban_notify_liveness_tests.py 以 mixin 覆盖 notify 过期地址反查和忙态重试; tests/kanban_takeover_tests.py 作为测试 mixin 覆盖 resume 接管、回滚和旧容器清理; tests/kanban_dismiss_tests.py 作为测试 mixin 覆盖 dismiss 过期地址反查; tests/test-kanban-probe.py 覆盖 pane 事实层的消失、选项缺失和探测失败分类. tests/test-merge-worktree-memory.py 覆盖跨平台记忆合并; 四个 agent 的 POSIX 审核测试覆盖共用门禁. tests/test-install-windows.py, tests/test-windows-automation.py, tests/test-windows-console.py, tests/test-windows-fs.py, tests/test-windows-review.py, tests/test-windows-web.py 分别覆盖 PowerShell 安装、不可用 py.exe 到 python.exe / python3.exe 的实际回退与 .cmd 入口、Windows 自动化文档的包装入口和 argv 边界、Windows console 领取/启动/PID/失败回滚、显式或配置 herdr 的拒绝、Win32 reparse/ACL/LockFileEx 文件安全 (含配置及 Git exclude 的 parent/leaf junction、FSCTL 原地切换、固定叶替换、创建时私有 DACL、创建碰撞、校验期写入/替换、无效配置 ACL、新建目录与相对 override)、Windows 审核 runtime 创建时 DACL、全生命周期 WRITE/DELETE 根句柄租约、根 FSCTL 切换拒绝、安全清理、临时根 reparse、隔离/超时/篡改检测与分发、原生 Windows Web 的 UTF-8 HTTP 端到端流程.
• 运行时创建的 kanban/ 是本机共享数据, 不属于仓库源码, 不得提交.