obsidian-notes/1Project/goaline/docs/execution-orchestrator-plan.md

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:

{
  "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