docs: track orchestrator design handoff in repo (AUT-53) - #24
Conversation
Living design doc for the plan-prover-review orchestrator we're introducing into KIP. Captures all decisions through 2026-05-07: - 23 locked decisions (§2) - Architecture diagram + schema contracts (§3, §5) - Open questions for builder implementation (§6) - Phase roadmap with Phase 0 (AUT-52, .kip/ → .dashboard/+.orchestrator/) marked landed (§8) Updated after each design meeting; "Last updated" line at top tracks the date so reviewers can tell at a glance whether the doc is current. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0caa5841a5
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | **16** | **builder 角色窄化** | builder 只做"file 聚类 + comment 消费",不"代 plan 决定任务组织"。plan 升格为 cycle 协调者 | | ||
| | **17** | **plan 每轮跑、看全部 task** | 同时承担 (a) pre-flight routing(看 informal proof 设计 Lean 路线)+ (b) adaptive recovery(看 past_attempts 失败时换路子)。retry-only 切片不走 | | ||
| | **18** | **`informal_proof` 字段** | prove 阶段带,formalize 不带。多 proof 块全部拼接(用 `--- alternative proof ---` 分隔)。plan 也看 informal_proof | | ||
| | **19** | **`section_header` 字段** | 从 status.yaml `chapter`+`subsection` 拼,作为 nl_brief 前置上下文 | |
There was a problem hiding this comment.
This contract points builders at status.yaml for chapter/subsection, but the current blueprint/status.yaml entries do not contain those keys; the repo derives them from blueprint/src/chapters/*.tex in tools/kip-state/index.py via parse_chapters(). If Phase B follows this doc literally, section_header will be empty or the builder will fail for every existing node, so the source should be corrected to the TeX/parsed chapter metadata path.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Pull request overview
Adds an initial “living” orchestrator design handoff document to the repo to capture the current plan–prover–review loop architecture and schema/contracts for driving blueprint nodes through nl_reviewed → bound → aligned → proved.
Changes:
- Introduces
ORCHESTRATOR_DESIGN_HANDOFF.mdwith the current architecture, phased rollout plan, and locked decisions. - Documents proposed directory layout for
.orchestrator/and the newagents/orchestrator/structure. - Specifies draft schema/wire-format contracts and builder open questions.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| 五个核心 dataclass(用 pydantic v2 实现),数据流: | ||
|
|
||
| ``` | ||
| list[PlannedTask] (build_objectives 写) | ||
| → list[FileJob] (build_jobs 写,plan & runner 读) | ||
| → cycle_plan.md (plan 写自由文本,prover 读) | ||
| → list[TaskOutcome] (runner 聚合 prover JSONL) | ||
| → list[Milestone] (review 写,writer 读) | ||
| → status.yaml + AuditEntry (writer 写) | ||
| ``` | ||
|
|
||
| 关键字段: | ||
|
|
||
| ```python | ||
| @dataclass(frozen=True) | ||
| class PlannedTask: | ||
| node_id: str | ||
| fqn: str | ||
| stage: Literal["formalize", "prove", "polish"] | ||
| file: Path |
| follow_up: str | ||
| ``` | ||
|
|
||
| **Wire format**:JSON 文件 + JSONL,LLM 用 Write 工具产出,Python 端 `model_validate_json`。 |
|
|
||
| **最后更新:2026-05-07** | ||
|
|
||
| 把 Archon (`/inspire/hdd/project/qproject-fundationmodel/czxs25250150/Archon`) 的 plan-prover-review 循环引入 KIP,作为推进 blueprint 节点生命周期 **后半程**(formalize 与 prove,即 `nl_reviewed → bound → aligned → proved`)的引擎。前半程(extract → reviewed)继续靠现有 `agents/blueprint-absorber/`。 |
Summary
First commit of
ORCHESTRATOR_DESIGN_HANDOFF.mdto the repo. This is the living design doc for the plan-prover-review orchestrator we're introducing into KIP (vendored & adapted from Archon's loop, scoped to drivenl_reviewed → bound → aligned → provedlifecycle on blueprint nodes).The doc captures all decisions through 2026-05-07 design meetings:
informal_prooffield,.dashboard/+.orchestrator/rename, etc.)PlannedTask,FileJob,Milestone)Living doc convention
Last updatedline at the top tracks the date. Updated after each design meeting. Future PRs that change orchestrator behavior should also update this doc in the same PR.Linear: AUT-53
🤖 Generated with Claude Code