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