Consider removing heuristic orchestrate mode

[lolipopshock]

@sepo-agent /answer since we've transitioned to the fully agentic reviewing mode, maybe that is not needed?

[sepo-agent-app]

Yes. I’d remove heuristics as a user-configurable orchestrator mode, but keep the deterministic transition logic as an internal safety policy.

Current state:

• Packaged entry paths already default AGENT_AUTOMATION_MODE to agent: agent-router.yml, agent-entrypoint.yml, agent-label.yml.
• The orchestrator planner only runs when mode is agent: orchestrator-preflight.ts.
• heuristics is still exposed in docs/config and implemented as a full mode: configuration-list.md, handoff.ts, handoff.ts.
• There is one important internal dependency: child issue delegation currently dispatches the child orchestrator with automation_mode: "heuristics" so the child runs the normal concrete chain instead of asking another planner immediately: orchestrate-handoff.ts.

Recommended direction:

1. Deprecate/remove AGENT_AUTOMATION_MODE=heuristics from public docs and workflow input descriptions.
2. Make orchestrator mode effectively agent whenever orchestration is enabled.
3. Keep the existing deterministic handoff state machine, but rename/reframe it as runtime validation/fallback policy rather than “heuristic mode”. Agent mode already uses it to validate planner-selected follow-ups: handoff.ts.
4. Replace the child-delegation automation_mode: "heuristics" special case with either:
   • agent plus stronger child prompt/context telling the child to execute the bounded concrete task, or
   • an internal-only worker_chain/concrete_chain concept that is not exposed as user config.
5. Remove compatibility aliases like true -> heuristics only after deciding whether old installed repos need a release-note migration path.

So: yes, I think the public heuristic orchestrate mode is probably no longer worth carrying. I would not delete the underlying deterministic transition logic; it is still the right guardrail around planner output, review/fix-pr/self-approval transitions, round limits, and duplicate-safe handoffs.

[lolipopshock]

keep the deterministic transition logic as an internal safety policy

@sepo-agent /answer is the transition still used or not in the agentic mode?

[lolipopshock]

Also this discussion is related to #351

[sepo-agent-app]

Yes, it is still used in agent mode, but not as the primary decider.

In agent mode, the planner chooses the next action first. Then runtime policy checks whether that planner-selected action is allowed by the existing deterministic transition table:

• decideHandoff() routes automationMode === "agent" into decideAgentHandoff(): handoff.ts#L681-L693
• inside decideAgentHandoff(), for normal post-action handoffs, it calls decideHeuristicHandoff(input) and compares the planner’s requested nextAction against the allowed deterministic transition: handoff.ts#L658-L678

So the current behavior is:

• Initial /orchestrate in agent mode: planner decides directly, with explicit runtime checks for issue/PR starts.
• Action-originated handoff in agent mode, e.g. implement -> review, review -> fix-pr, fix-pr -> review: planner decides, but the old transition table is still used as an allowlist.
• If planner output is missing/invalid in agent mode, it stops; it does not silently fall back to heuristic decisioning: handoff.ts#L546-L551.

There is also one remaining explicit heuristic-mode use: delegate_issue dispatches the child orchestrator with automation_mode: "heuristics": orchestrate-handoff.ts#L1581-L1596. That is not just validation; it makes child issues run the concrete implementation/review/fix loop without immediately invoking another planner.

So I’d phrase the cleanup as:

• remove heuristics as a public/user-facing mode;
• keep and rename decideHeuristicHandoff() to something like decideAllowedTransition() or validatePlannedTransition();
• decide separately whether delegated child issues should remain deterministic workers or also become planner-backed.

[lolipopshock]

@sepo-agent /answer what's the point of using heuristic then.... I'd thought we can give agent heuristic route as the "suggestion" and then it can choose to stick or confirm with it?

[sepo-agent-app]

You’re basically right. The current split is awkward.

Today heuristics has three different roles mixed together:

1. Standalone low-cost mode: skip the planner and just run the fixed state machine. That is what public AGENT_AUTOMATION_MODE=heuristics means.
2. Runtime safety policy in agent mode: after the planner chooses a handoff, runtime calls decideHeuristicHandoff() to check whether that next action is allowed: handoff.ts#L658-L678.
3. Child issue worker shortcut: delegate_issue currently starts the child orchestrator in heuristics mode so the child runs the normal implement/review/fix loop instead of invoking another planner: orchestrate-handoff.ts#L1581-L1596.

The agent already gets the rules in the prompt under “Runtime Policy”: agent-orchestrator.md#L20-L63. But it does not currently get a computed suggestion like:

{
  "suggested_next_action": "fix-pr",
  "suggested_reason": "review verdict is MINOR_ISSUES and recommended next step is FIX_PR"
}

So your model is probably better:

• compute the deterministic transition as a suggested/default transition;
• pass it into the planner prompt;
• let the planner confirm it, stop, block, answer, or provide better handoff_context;
• still validate the final planner decision with deterministic policy before dispatch.

That would make the heuristic useful without treating it as a separate product mode. The public mode can probably go away, while the internal function becomes something like computeSuggestedTransition() plus validatePlannerTransition().

The only design decision left is child orchestration. If children should also be fully agentic, switch the delegate_issue child dispatch from automation_mode: "heuristics" to agent and give the child planner the computed suggestion/context. If children are meant to be concrete worker chains, keep that behavior but make it internal and name it explicitly rather than exposing it as “heuristics mode.”

[lolipopshock]

If children are meant to be concrete worker chains, keep that behavior but make it internal and name it explicitly rather than exposing it as “heuristics mode

@sepo-agent /answer

Ok good point. I think we should do one thing at a time but let's discuss the overall structure first.

So when we are in the meta orchestrator mode, we use the agent to create a next task right?

I thought the meta orchestrator always need that step to proceed with the plan?

[sepo-agent-app]

Yes, for meta orchestration, the agent planner is the thing that decides the next unit of work.

The current intended structure is roughly:

parent/meta issue
  -> agent planner decides next bounded step
  -> optionally creates/reuses/adopts one child issue
  -> child issue executes that concrete task
  -> when child reaches terminal state, parent planner resumes
  -> parent decides the next bounded step

So the meta orchestrator does need an agent step whenever the parent plan needs to advance. That is the point of delegate_issue: the parent planner chooses the next task, writes concrete child instructions, and dispatches the child. The prompt describes this as choosing one bounded next step and preferring delegate_issue for distinct subgoals/workstreams: agent-orchestrator.md#L47-L54, agent-orchestrator.md#L93-L101.

The subtle part is what happens inside the child.

Today, when the parent planner chooses delegate_issue, the dispatcher starts the child orchestrator with automation_mode: "heuristics": orchestrate-handoff.ts#L1581-L1596. That means the child is treated as a concrete worker chain:

child issue
  -> implement
  -> review
  -> fix-pr if needed
  -> review
  -> terminal result

The child does not need to re-plan the parent objective every round; it just executes the task the parent assigned. When the child finishes, terminal reporting resumes the parent planner in agent mode so the parent can decide the next task.

So I’d frame the overall structure as two layers:

• Meta planner layer: agentic. Owns decomposition, child selection, sequencing, stacking decisions, and stopping/blocking.
• Concrete worker layer: deterministic chain. Owns implementing and stabilizing one already-scoped task.

Your intuition is right for the meta layer: it should always use the agent to proceed with the plan. The current heuristic child mode is not meant to replace the meta planner; it is acting as the execution lane for a task the meta planner already chose.

[lolipopshock]

@sepo-agent /answer alright; then, what's the concrete plan for the fix then?

[sepo-agent-app]

Concrete plan: do this in two phases, with phase 1 solving the naming/structure problem without changing child execution semantics.

Current Architecture

• Public docs currently expose two orchestrator modes: heuristics and agent: agent-orchestrator.md#L7-L13.
• The deterministic transition table lives in decideHeuristicHandoff(): handoff.ts#L438-L544.
• In agent mode, that same table is already used as validation after the planner responds: handoff.ts#L658-L678.
• The planner prompt lists policy rules, but does not receive a computed “suggested next transition”: agent-orchestrator.md#L20-L64.
• Delegated child issues are currently launched in heuristic mode as concrete worker chains: orchestrate-handoff.ts#L1581-L1596.

Proposed Fix
Phase 1 should make the structure explicit:

1. Rename the concept internally:

   • decideHeuristicHandoff() → something like computeDeterministicTransition() or computeAllowedTransition().
   • Keep behavior the same initially.
   • This makes clear it is policy/suggestion, not a separate product mode.

2. Add a computed transition suggestion before the planner runs:

   • Extend orchestrator-preflight.ts or add a small pre-planner CLI.
   • Output fields like:
     • suggested_decision
     • suggested_next_action
     • suggested_reason
     • suggested_handoff_context
   • Pass those into agent-orchestrator.yml as ORCHESTRATOR_SUGGESTED_* env vars.

3. Update the orchestrator prompt:

   • Add a “Deterministic Suggestion” section.
   • Tell the planner: use this as the default path, but it may choose stop, blocked, answer, or better handoff_context when repo/user context warrants it.
   • Keep runtime validation mandatory.

4. Keep delegated children as concrete worker chains for now:

   • Do not change the delegate_issue child dispatch behavior in phase 1.
   • Rename docs around this from “heuristic mode” to “concrete worker chain” or “deterministic worker chain”.
   • This preserves the meta-orchestrator model: parent plans, child executes.

5. Deprecate public heuristic mode in docs:

   • Say AGENT_AUTOMATION_MODE defaults to agent.
   • Treat deterministic routing as internal policy/worker-chain behavior.
   • Keep accepting heuristics as a compatibility alias for now, but stop presenting it as a recommended public mode.

Tests
Add/update coverage for:

• deterministic suggestion generation for implement -> review, review -> fix-pr, fix-pr -> review, self-approval, and stop cases;
• planner prompt receives the suggestion env vars;
• agent mode still rejects planner choices that conflict with deterministic policy;
• delegated child issue still starts the concrete worker chain;
• docs/tests no longer describe heuristics as the primary user-facing alternative.

Follow-Up Phase
After phase 1 lands and behaves well, phase 2 can decide whether to fully remove public heuristics input support or leave it as a hidden compatibility alias. I would not combine that with phase 1, because phase 1 is a structural cleanup and prompt improvement, while phase 2 is a compatibility/breaking-change decision.

Approval request: proceed with phase 1 as above?

---

codex | default model | high | Macmini-runner-1

[lolipopshock]

Concrete plan: do this in two phases, with phase 1 solving the naming/structure problem without changing child execution semantics.

Current Architecture

• Public docs currently expose two orchestrator modes: heuristics and agent: agent-orchestrator.md#L7-L13.
• The deterministic transition table lives in decideHeuristicHandoff(): handoff.ts#L438-L544.
• In agent mode, that same table is already used as validation after the planner responds: handoff.ts#L658-L678.
• The planner prompt lists policy rules, but does not receive a computed “suggested next transition”: agent-orchestrator.md#L20-L64.
• Delegated child issues are currently launched in heuristic mode as concrete worker chains: orchestrate-handoff.ts#L1581-L1596.

Proposed Fix
Phase 1 should make the structure explicit:

1. Rename the concept internally:

   • decideHeuristicHandoff() → something like computeDeterministicTransition() or computeAllowedTransition().
   • Keep behavior the same initially.
   • This makes clear it is policy/suggestion, not a separate product mode.

2. Add a computed transition suggestion before the planner runs:

   • Extend orchestrator-preflight.ts or add a small pre-planner CLI.
   • Output fields like:
     • suggested_decision
     • suggested_next_action
     • suggested_reason
     • suggested_handoff_context
   • Pass those into agent-orchestrator.yml as ORCHESTRATOR_SUGGESTED_* env vars.

3. Update the orchestrator prompt:

   • Add a “Deterministic Suggestion” section.
   • Tell the planner: use this as the default path, but it may choose stop, blocked, answer, or better handoff_context when repo/user context warrants it.
   • Keep runtime validation mandatory.

4. Keep delegated children as concrete worker chains for now:

   • Do not change the delegate_issue child dispatch behavior in phase 1.
   • Rename docs around this from “heuristic mode” to “concrete worker chain” or “deterministic worker chain”.
   • This preserves the meta-orchestrator model: parent plans, child executes.

5. Deprecate public heuristic mode in docs:

   • Say AGENT_AUTOMATION_MODE defaults to agent.
   • Treat deterministic routing as internal policy/worker-chain behavior.
   • Keep accepting heuristics as a compatibility alias for now, but stop presenting it as a recommended public mode.

Tests
Add/update coverage for:

• deterministic suggestion generation for implement -> review, review -> fix-pr, fix-pr -> review, self-approval, and stop cases;
• planner prompt receives the suggestion env vars;
• agent mode still rejects planner choices that conflict with deterministic policy;
• delegated child issue still starts the concrete worker chain;
• docs/tests no longer describe heuristics as the primary user-facing alternative.

Follow-Up Phase
After phase 1 lands and behaves well, phase 2 can decide whether to fully remove public heuristics input support or leave it as a hidden compatibility alias. I would not combine that with phase 1, because phase 1 is a structural cleanup and prompt improvement, while phase 2 is a compatibility/breaking-change decision.

Approval request: proceed with phase 1 as above?

---

codex | default model | high | Macmini-runner-1

@sepo-agent /orchestrate

[sepo-agent-app]

Sepo is dispatching follow-up automation.

Source	Next	Target	Round	Status
orchestrate	implement	Issue #367	2 / 40	Dispatched

Reason: agent planner selected implement: The requester approved the phase 1 plan for issue #367, and the work is a bounded code/docs/test change on the current issue rather than a meta-planning subgoal that needs a child issue.