auto nightly sync
This commit is contained in:
Build Bot
328
1Project/goaline/docs/execution-orchestrator-plan.md
Normal file
328
1Project/goaline/docs/execution-orchestrator-plan.md
Normal file
@@ -0,0 +1,328 @@
|
|||||||
|
# Goaline Execution Orchestrator Plan
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
Introduce a Goaline-native execution orchestrator that replaces `/goal` only for the execution loop, while preserving the existing document-first intake and archive flow.
|
||||||
|
|
||||||
|
The target operating model is:
|
||||||
|
|
||||||
|
1. `phase-doc-intake` handles exploratory conversation and mainline phase docs.
|
||||||
|
2. `goal-plan-intake` turns a target phase or repair request into a concise executable plan.
|
||||||
|
3. A new execution orchestrator consumes the frozen plan and runs `exec -> review -> verify -> retry` loops until completion or stop.
|
||||||
|
4. `plan-archive-promote` archives the completed plan and promotes only stable conclusions back into the mainline docs.
|
||||||
|
|
||||||
|
## Non-Goals
|
||||||
|
|
||||||
|
- Do not replace the interactive planning and grill-me style convergence used before a plan is frozen.
|
||||||
|
- Do not force the phase-doc or plan intake stages into a rigid scripted workflow.
|
||||||
|
- Do not treat review-only subjective approval as sufficient completion evidence.
|
||||||
|
|
||||||
|
## Why This Split
|
||||||
|
|
||||||
|
The current Goaline skills already form a clean document lifecycle:
|
||||||
|
|
||||||
|
- `phase-doc-intake`: converges scope and writes human-readable mainline docs.
|
||||||
|
- `goal-plan-intake`: writes a short execution plan intended for `/goal`.
|
||||||
|
- `plan-archive-promote`: closes the loop after execution.
|
||||||
|
|
||||||
|
What is missing is a dedicated execution controller between plan creation and archival. That controller should not own discovery. It should only own execution-state transitions, verification, and retry routing.
|
||||||
|
|
||||||
|
## Proposed Architecture
|
||||||
|
|
||||||
|
### Layer 1: Interactive Planning
|
||||||
|
|
||||||
|
Owned by the existing intake skills and a general-purpose coding agent.
|
||||||
|
|
||||||
|
Responsibilities:
|
||||||
|
|
||||||
|
- ask questions
|
||||||
|
- grill for ambiguity
|
||||||
|
- converge on scope
|
||||||
|
- write/update `docs/README.md`
|
||||||
|
- write/update ordered phase docs
|
||||||
|
- derive a concise executable plan under `docs/plans/`
|
||||||
|
|
||||||
|
This layer remains conversational and human-driven.
|
||||||
|
|
||||||
|
### Layer 2: Contract Freeze
|
||||||
|
|
||||||
|
Before execution starts, freeze a small execution contract derived from the plan. This can live in the plan file itself or in a sibling artifact.
|
||||||
|
|
||||||
|
The frozen execution contract should contain at least:
|
||||||
|
|
||||||
|
- Goal
|
||||||
|
- Scope / non-goals
|
||||||
|
- Constraints
|
||||||
|
- Guardrails
|
||||||
|
- Done signals
|
||||||
|
- Verification expectations
|
||||||
|
- Stop conditions
|
||||||
|
|
||||||
|
This is the boundary between exploratory planning and deterministic execution.
|
||||||
|
|
||||||
|
### Layer 3: Execution Orchestrator
|
||||||
|
|
||||||
|
Introduce a new Goaline execution workflow that replaces `/goal` in the middle of the lifecycle.
|
||||||
|
|
||||||
|
Core responsibilities:
|
||||||
|
|
||||||
|
- read the frozen execution plan/contract
|
||||||
|
- dispatch `exec`
|
||||||
|
- dispatch `review`
|
||||||
|
- run an external verification gate
|
||||||
|
- decide whether to return to `exec`, return to `review`, escalate back to planning, or complete
|
||||||
|
- produce an archive-ready completion summary
|
||||||
|
|
||||||
|
This layer is a workflow controller, not a discovery agent.
|
||||||
|
|
||||||
|
### Layer 4: Archive and Promote
|
||||||
|
|
||||||
|
After successful completion, pass the plan into `plan-archive-promote`.
|
||||||
|
|
||||||
|
Responsibilities:
|
||||||
|
|
||||||
|
- append archive summary
|
||||||
|
- archive the executed plan
|
||||||
|
- promote stable conclusions only
|
||||||
|
- update mainline docs without mixing in temporary execution noise
|
||||||
|
|
||||||
|
## Execution State Machine
|
||||||
|
|
||||||
|
Recommended loop:
|
||||||
|
|
||||||
|
`plan freeze -> exec -> review -> verify gate -> retry or archive`
|
||||||
|
|
||||||
|
Detailed state flow:
|
||||||
|
|
||||||
|
1. `Plan Ready`
|
||||||
|
- intake is complete
|
||||||
|
- plan exists on disk
|
||||||
|
- execution contract is frozen
|
||||||
|
|
||||||
|
2. `Exec`
|
||||||
|
- implement the smallest next closed loop
|
||||||
|
- write required verification artifacts
|
||||||
|
- do not claim completion by chat text alone
|
||||||
|
|
||||||
|
3. `Review`
|
||||||
|
- inspect implementation
|
||||||
|
- inspect whether tests actually prove the intended behavior
|
||||||
|
- reject weak or misaligned acceptance tests
|
||||||
|
|
||||||
|
4. `Verify Gate`
|
||||||
|
- run mechanical verification outside the agent's self-report
|
||||||
|
- decide pass/fail from executable evidence
|
||||||
|
|
||||||
|
5. `Retry Routing`
|
||||||
|
- implementation defect -> back to `exec`
|
||||||
|
- weak or invalid acceptance test -> back to `review` or `exec`
|
||||||
|
- requirement ambiguity discovered late -> back to planning
|
||||||
|
|
||||||
|
6. `Archive Ready`
|
||||||
|
- only reachable after verify gate success
|
||||||
|
- hand off to archive/promote flow
|
||||||
|
|
||||||
|
## Verify Gate Requirements
|
||||||
|
|
||||||
|
The verify gate must be external to agent self-report. The agent may propose tests and commands, but completion is decided by the runner.
|
||||||
|
|
||||||
|
Minimum checks:
|
||||||
|
|
||||||
|
1. Required artifacts exist and are valid.
|
||||||
|
2. Acceptance tests pass on the changed tree.
|
||||||
|
3. Acceptance tests fail on the base tree when applicable.
|
||||||
|
4. Regression checks show no new failures.
|
||||||
|
5. Missing or insufficient proof fails closed.
|
||||||
|
|
||||||
|
## Base Isolation Rules
|
||||||
|
|
||||||
|
The base tree must be isolated well enough that red-proof execution cannot silently run against the modified tree.
|
||||||
|
|
||||||
|
Required controls:
|
||||||
|
|
||||||
|
### 1. Code Tree Isolation
|
||||||
|
|
||||||
|
- capture `base_commit` at execution start
|
||||||
|
- create a separate tree using `git worktree add <tmpdir> <base_commit>`
|
||||||
|
- run red-proof verification only inside that base worktree
|
||||||
|
|
||||||
|
`base_commit` is the before-change comparison point, usually the target branch `HEAD` at the start of execution.
|
||||||
|
|
||||||
|
### 2. Command Path Isolation
|
||||||
|
|
||||||
|
- reject or rewrite hardcoded absolute paths that point back to the modified working tree
|
||||||
|
- do not allow verification commands to escape back into the changed tree
|
||||||
|
- require repo-relative execution commands where possible
|
||||||
|
|
||||||
|
### 3. Test Overlay Isolation
|
||||||
|
|
||||||
|
- copy only declared `test_paths` into the base worktree
|
||||||
|
- never copy changed implementation files into the base worktree during red proof
|
||||||
|
- reject absolute paths, parent escapes, and repo-external test paths
|
||||||
|
|
||||||
|
### 4. Runtime Import Isolation
|
||||||
|
|
||||||
|
- allow environment/dependency reuse only when code import still resolves to the current tree under verification
|
||||||
|
- do not rely on editable installs that import the changed code regardless of current worktree
|
||||||
|
- prefer repo-relative imports and explicit root execution
|
||||||
|
|
||||||
|
### 5. Build/Cache Isolation
|
||||||
|
|
||||||
|
- avoid reusing stale build output or caches that can mask failures
|
||||||
|
- clear or isolate targeted caches when necessary
|
||||||
|
|
||||||
|
### 6. Environment Isolation
|
||||||
|
|
||||||
|
- do not blindly forward all environment variables into verification
|
||||||
|
- strip or rewrite environment variables that point back to the modified tree
|
||||||
|
- prefer a constrained environment whitelist
|
||||||
|
|
||||||
|
## Verification Artifact Contract
|
||||||
|
|
||||||
|
A minimal verification artifact should be required from execution before the gate runs.
|
||||||
|
|
||||||
|
Suggested shape:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"testable": true,
|
||||||
|
"acceptance_tests": [
|
||||||
|
{
|
||||||
|
"name": "short label",
|
||||||
|
"command": "repo-relative command",
|
||||||
|
"test_paths": ["path/to/test_file"]
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"regression_command": "optional regression command",
|
||||||
|
"assumptions": [],
|
||||||
|
"not_testable_reason": ""
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Rules:
|
||||||
|
|
||||||
|
- no artifact means verification cannot start
|
||||||
|
- invalid JSON means failure
|
||||||
|
- empty acceptance set means failure when `testable=true`
|
||||||
|
- missing `test_paths` means the red state is not provable
|
||||||
|
|
||||||
|
## Test Validity Strategy
|
||||||
|
|
||||||
|
Like TDD, test validity cannot be proven absolutely. The orchestrator should instead combine mechanical proof with semantic review.
|
||||||
|
|
||||||
|
### Mechanical Validity Checks
|
||||||
|
|
||||||
|
The runner should enforce:
|
||||||
|
|
||||||
|
- the acceptance command executes
|
||||||
|
- it passes on the changed tree
|
||||||
|
- it fails on the base tree for the same target behavior
|
||||||
|
- regression checks do not add failures
|
||||||
|
- missing proof fails closed
|
||||||
|
|
||||||
|
### Semantic Validity Review
|
||||||
|
|
||||||
|
The review step should explicitly ask:
|
||||||
|
|
||||||
|
- Does this test assert the intended behavior, or only an implementation detail?
|
||||||
|
- Does the red failure happen for the right reason?
|
||||||
|
- Was the test weakened to make the change look successful?
|
||||||
|
- Does the test have meaningful distinguishing power between before and after?
|
||||||
|
- Is the test stable, deterministic, and not dependent on irrelevant machine state?
|
||||||
|
|
||||||
|
### Anti-Fake-Pass Guardrails
|
||||||
|
|
||||||
|
Reject or escalate when any of these patterns appear:
|
||||||
|
|
||||||
|
- acceptance test trivially passes before the fix
|
||||||
|
- test fails only because the environment is broken
|
||||||
|
- command depends on the modified tree via absolute path
|
||||||
|
- assertions are weakened away from the intended behavior
|
||||||
|
- the test proves only a mocked path that bypasses the real defect
|
||||||
|
- time, network, random, or GUI instability dominates the signal without being part of the requirement
|
||||||
|
|
||||||
|
## Retry / Feedback Model
|
||||||
|
|
||||||
|
Verification failure should be converted into structured feedback and routed back into the appropriate stage.
|
||||||
|
|
||||||
|
### Feedback Inputs
|
||||||
|
|
||||||
|
Each failure summary should include:
|
||||||
|
|
||||||
|
- failure type
|
||||||
|
- failing command
|
||||||
|
- exit code when available
|
||||||
|
- bounded output tail
|
||||||
|
- explicit instruction not to weaken or delete the acceptance test unless the issue is test invalidity
|
||||||
|
|
||||||
|
### Retry Routing Rules
|
||||||
|
|
||||||
|
- implementation incorrect -> return to `exec`
|
||||||
|
- acceptance test invalid or weak -> return to `review`, then likely to `exec`
|
||||||
|
- ambiguous requirement discovered during review or verification -> return to planning
|
||||||
|
- repeated identical failure signature -> stop instead of thrashing
|
||||||
|
|
||||||
|
## Integration with Existing Goaline Skills
|
||||||
|
|
||||||
|
### `phase-doc-intake`
|
||||||
|
|
||||||
|
Keep unchanged as the conversational entrypoint for project or phase shaping.
|
||||||
|
|
||||||
|
### `goal-plan-intake`
|
||||||
|
|
||||||
|
Update its wording and expectations so the produced plan is consumable by the new Goaline execution orchestrator, not specifically tied to `/goal`.
|
||||||
|
|
||||||
|
### New Orchestrator Skill or Script
|
||||||
|
|
||||||
|
Add a new middle component, for example:
|
||||||
|
|
||||||
|
- `goal-exec-orchestrator`
|
||||||
|
- `plan-exec-orchestrator`
|
||||||
|
- `goal-runner`
|
||||||
|
|
||||||
|
This component should own the `exec -> review -> verify -> retry` lifecycle.
|
||||||
|
|
||||||
|
### `plan-archive-promote`
|
||||||
|
|
||||||
|
Keep as the final archival and promotion stage after verify gate success.
|
||||||
|
|
||||||
|
## Recommended Deliverables
|
||||||
|
|
||||||
|
1. ✅ `skills/goaline-exec-orchestrator/SKILL.md` — New Goaline execution orchestrator skill with exec/review/verify/retry loop.
|
||||||
|
2. ✅ `goal-plan-intake` updated — Frozen execution contract shape defined in plan output.
|
||||||
|
3. ✅ Verification artifact schema — Defined in orchestrator SKILL.md (JSON contract with acceptance_tests, test_paths, etc.).
|
||||||
|
4. ✅ Verify-gate implementation spec with base isolation rules — Documented in orchestrator SKILL.md (6 isolation domains, fail-closed rules).
|
||||||
|
5. ✅ Retry-routing rules — Routing table for exec/review/planning fallback with stop-on-thrash.
|
||||||
|
6. ✅ Archive handoff fields — Execution summary shape defined in orchestrator SKILL.md.
|
||||||
|
|
||||||
|
## Implementation Status
|
||||||
|
|
||||||
|
- All deliverables are complete.
|
||||||
|
- Existing skill files updated: `goal-plan-intake/SKILL.md`, `plan-archive-promote/SKILL.md`.
|
||||||
|
- Root docs updated: `README.md`, `.codex-plugin/plugin.json`.
|
||||||
|
- No changes to `phase-doc-intake/SKILL.md` needed — it remains the conversational entrypoint unchanged.
|
||||||
|
|
||||||
|
## Stop Conditions
|
||||||
|
|
||||||
|
Stop the execution loop and report instead of retrying indefinitely when:
|
||||||
|
|
||||||
|
- the same failure signature repeats with no progress
|
||||||
|
- proof cannot be established due to environment breakage
|
||||||
|
- the task turns out not to be automatically testable under current constraints
|
||||||
|
- the requirement is still materially ambiguous after execution begins
|
||||||
|
|
||||||
|
## Suggested Next Steps
|
||||||
|
|
||||||
|
1. ✅ Retarget `goal-plan-intake` documentation from "consumed by `/goal`" to "consumed by Goaline execution orchestrator".
|
||||||
|
2. ✅ Define the frozen execution contract format.
|
||||||
|
3. ✅ Define the verification artifact schema and fail-closed rules.
|
||||||
|
4. ✅ Add a new Goaline orchestration skill or script for `exec -> review -> verify -> retry`.
|
||||||
|
5. ✅ Define the archive handoff shape consumed by `plan-archive-promote`.
|
||||||
|
|
||||||
|
## Closed Items
|
||||||
|
|
||||||
|
All items from the plan are now complete. The new lifecycle is:
|
||||||
|
|
||||||
|
```
|
||||||
|
phase-doc-intake -> goal-plan-intake -> goaline-exec-orchestrator -> plan-archive-promote
|
||||||
|
```
|
||||||
@@ -1,16 +0,0 @@
|
|||||||
## 要做的内容
|
|
||||||
- 启动/管理子进程
|
|
||||||
- 解析 --json 输出
|
|
||||||
- 保存 codexSessionId
|
|
||||||
- 做 SSE 给网页
|
|
||||||
- 做一层本地 session 映射
|
|
||||||
- 处理超时、取消、错误展示
|
|
||||||
- 结构 ``` type ChatSession = {
|
|
||||||
codexSessionId: string // codex 的真实 session id
|
|
||||||
cwd: string
|
|
||||||
createdAt: string
|
|
||||||
updatedAt: string```
|
|
||||||
|
|
||||||
## 具体业务
|
|
||||||
- 碎片->立项
|
|
||||||
- 待阅读->立项
|
|
||||||
Reference in New Issue
Block a user