diff --git a/.yoi/tickets/open/20260607-035710-ticket-orchestration-plan-tool/item.md b/.yoi/tickets/open/20260607-035710-ticket-orchestration-plan-tool/item.md index 00b7c2b3..77644227 100644 --- a/.yoi/tickets/open/20260607-035710-ticket-orchestration-plan-tool/item.md +++ b/.yoi/tickets/open/20260607-035710-ticket-orchestration-plan-tool/item.md @@ -6,9 +6,9 @@ status: open kind: task priority: P1 labels: [ticket, orchestrator, planning, workflow, tools] -workflow_state: intake +workflow_state: 'ready' created_at: 2026-06-07T03:57:10Z -updated_at: 2026-06-07T03:57:10Z +updated_at: '2026-06-08T06:27:17Z' assignee: null legacy_ticket: null --- diff --git a/.yoi/tickets/open/20260607-035710-ticket-orchestration-plan-tool/thread.md b/.yoi/tickets/open/20260607-035710-ticket-orchestration-plan-tool/thread.md index c95fab60..64254d85 100644 --- a/.yoi/tickets/open/20260607-035710-ticket-orchestration-plan-tool/thread.md +++ b/.yoi/tickets/open/20260607-035710-ticket-orchestration-plan-tool/thread.md @@ -5,3 +5,64 @@ Created by LocalTicketBackend create. --- + + + +## Decision + +## Intake refinement: readiness and boundaries + +Readiness classification: `implementation_ready`, with design preflight recommended before implementation because this introduces a new Ticket/orchestration-domain tool/API surface and durable record format. + +Binding decisions / invariants: +- This is a Ticket/orchestration-domain capability, not a generic `TaskStore` replacement and not a scheduler. +- Durable project-relevant ordering/dependency/conflict/capacity decisions must survive compaction and be queryable later by Ticket id/slug and relation kind. +- Local runtime claims, Pod/session assignment details, sockets, and other ephemeral execution state must remain in the local role-session/runtime registry rather than git-tracked Ticket metadata. +- The first version must remain a lightweight note/plan surface; it must not silently introduce automatic topological scheduling or unattended queue reordering. +- Orchestrator prompts/workflows should consult these records before accepting queued Tickets, but human Queue and `queued -> inprogress` acceptance semantics remain unchanged. + +Implementation latitude: +- The implementer may choose the concrete storage shape within the Ticket backend, such as typed thread events, artifacts, or a small typed record file, if it satisfies queryability, validation, and durability requirements. +- The tool naming and exact relation schema can be adjusted during preflight/implementation, provided the supported relation classes remain ordering, dependency/blocker, conflict, capacity/waiting, and accepted-plan summary. +- The first implementation can favor explicit CRUD/query operations over graph solving or automatic route selection. + +Escalation conditions: +- Escalate before implementing if the design would change Ticket workflow-state semantics, mutate local role-session claims, require a migration of existing Ticket records, grant mutating capabilities to Companion, or make Orchestrator start work without the explicit Queue gate. +- Escalate if relation records need to include secret/private workspace details or raw session/model output; Ticket records should store bounded project-relevant decisions only. + +Validation expectations: +- Add focused tests for creating/querying relation records by Ticket and relation kind. +- Add tests or prompt/workflow coverage showing Orchestrator can consult the records before queued-ticket acceptance. +- Run the normal package validation for code/runtime-resource changes, including `nix build .#yoi` before completion. + +--- + + + +## Intake summary + +Existing Ticket `ticket-orchestration-plan-tool` was refined for readiness. It is implementation-ready as a bounded Ticket/orchestration-domain tool surface for recording/querying ordering, dependency/blocker, conflict, capacity/waiting, and accepted-plan decisions. Needs preflight: true, because it introduces a new durable Ticket-domain API/storage surface and touches Orchestrator routing workflow semantics. Risk flags: ticket-domain-tool, persistence, workflow-routing, feature-boundary, compaction. Key invariants: do not replace TaskStore, do not implement a scheduler/graph solver, keep local Pod/session claims out of git-tracked Ticket metadata, preserve the human Queue gate and queued->inprogress acceptance contract. + +--- + + + +## State changed + +Intake has clarified readiness, boundaries, implementation latitude, escalation conditions, and validation expectations. The Ticket is ready for human queueing and Orchestrator routing/preflight; implementation should not start until the ready Ticket is queued and accepted through the Orchestrator workflow. + +--- + + + +## Decision + +## Dependency ordering: planning lane before OrchestrationPlan tool + +`replace-intake-state-with-planning` owns the workflow cleanup for cases where implementation cannot be planned yet: such Tickets should return to the planning lane with a visible reason instead of remaining in a separate `preflight_needed` state/bucket. + +This Ticket should assume that planning-lane behavior exists before the OrchestrationPlan tool is implemented. The dependency/order should be: settle `replace-intake-state-with-planning` first, then implement the OrchestrationPlan tool on top of the clarified planning/queued/inprogress workflow. + +Do not add a Plan-tool-specific `preflight_needed` state or requirement here. At most, the tool may observe the resulting planning/queued/inprogress Ticket states produced by the workflow model. + +--- diff --git a/.yoi/tickets/open/20260608-061235-orchestrator-active-ticket-plan-iteration/artifacts/.gitkeep b/.yoi/tickets/open/20260608-061235-orchestrator-active-ticket-plan-iteration/artifacts/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/.yoi/tickets/open/20260608-061235-orchestrator-active-ticket-plan-iteration/item.md b/.yoi/tickets/open/20260608-061235-orchestrator-active-ticket-plan-iteration/item.md new file mode 100644 index 00000000..e4c11bff --- /dev/null +++ b/.yoi/tickets/open/20260608-061235-orchestrator-active-ticket-plan-iteration/item.md @@ -0,0 +1,135 @@ +--- +id: '20260608-061235-orchestrator-active-ticket-plan-iteration' +slug: 'orchestrator-active-ticket-plan-iteration' +title: 'Prevent idle starvation in Ticket orchestration planning' +status: 'open' +kind: 'task' +priority: 'P1' +labels: ['ticket', 'orchestrator', 'planning', 'panel', 'taskstore', 'queue'] +workflow_state: 'intake' +created_at: '2026-06-08T06:12:35Z' +updated_at: '2026-06-08T06:27:33Z' +assignee: null +legacy_ticket: null +--- + +## Background + +The current Panel Queue automation mostly handles the transition-time event: + +```text +ready -> queued + -> notify workspace Orchestrator +``` + +That is not enough for robust orchestration. Queued Tickets can remain after missed notifications, Orchestrator restarts, preflight returns, capacity limits, or multi-ticket coordination. The Orchestrator also needs a lightweight way to remember planned queued work across turns without relying only on session memory. + +There is an existing related Ticket: + +- `ticket-orchestration-plan-tool` + +That Ticket asks for a TaskStore-like surface for Ticket ordering/dependency/conflict/capacity/accepted-plan records. This Ticket folds that need together with queued-backlog re-kick semantics into a narrower operational requirement: + +> If runnable queued work exists and the Orchestrator is otherwise idle, the system should not wait indefinitely for another user instruction. The Orchestrator should be kicked with a bounded work set so it can either incorporate new queued work into the plan or start the next planned queued Ticket. + +This is starvation prevention and explicit work-set planning, not a constant background scheduler loop. + +## Goal + +Implement an Orchestrator attention/re-kick policy and planning store for active Ticket work: distinguish new queued work from planned queued work and accepted in-progress work, persist the plan, and kick the Orchestrator only when work can progress and no active Orchestrator-managed operation is already being waited on. + +## Planning model + +The OrchestrationPlan store should distinguish at least: + +- `new_queued`: Tickets with `workflow_state = queued` that have not yet been incorporated into the OrchestrationPlan. +- `planned_queued`: queued Tickets that the Orchestrator has considered and placed into an explicit plan/order/waiting set, but has not yet accepted as `inprogress`. +- `inprogress`: Tickets accepted by the Orchestrator and currently awaiting worktree/coder/reviewer/preflight/merge/cleanup progress. + +The names do not need to become final public API names, but the state distinction is required. + +## Requirements + +### Active work set discovery / re-kick + +- Provide a mechanism to identify Tickets that need Orchestrator attention, including at least: + - `workflow_state = queued` Tickets not yet present in the OrchestrationPlan (`new_queued`); + - planned queued Tickets that are not blocked/capacity-limited and can be started when there is no active in-progress work; + - `workflow_state = inprogress` Tickets accepted by Orchestrator whose next action is not merely waiting for an active coder/reviewer/preflight/merge step; + - queued Tickets left behind after Orchestrator restart, missed notification, or previous capacity stop. +- On Panel open/Orchestrator restore/spawn, or explicit user action, surface a bounded work list to the Orchestrator when there is actionable work. +- Avoid unbounded background polling. Prefer explicit events, Panel lifecycle kick, and explicit user/Orchestrator actions. +- Prevent duplicate starts: re-kick should prompt inspection/planning or acceptance of the next planned item, not blindly start coder Pods. + +### Re-kick / starvation-prevention semantics + +- If `new_queued` work exists and the Orchestrator is idle/not occupied by an active in-progress operation, kick or notify the Orchestrator so it can incorporate those Tickets into the plan. +- If no active `inprogress` work exists and runnable `planned_queued` work exists, kick or notify the Orchestrator so it can accept/start the next planned Ticket rather than waiting indefinitely for user instruction. +- If active `inprogress` work exists and the next expected event is coder/reviewer/preflight/merge completion, do not re-kick merely because queued/planned queued work also exists. +- If planned queued work is blocked, dependency-waiting, conflict-waiting, or capacity-limited, record the reason so the Panel/user can see why nothing starts. +- A re-kick is an attention signal plus bounded context, not authority to bypass `queued -> inprogress` acceptance or spawn implementation Pods without inspection. + +### Orchestration plan record + +- Provide or define a TaskStore-like but Ticket-domain planning surface for Orchestrator use. +- The plan should be scoped to Ticket orchestration and support records such as: + - current active target set; + - state bucket: `new_queued` / `planned_queued` / `inprogress` or equivalent; + - ordering: Ticket A before Ticket B; + - dependency/blocker: A blocks B / B blocked by A; + - conflict: do not run A and B in parallel; + - capacity/waiting notes; + - accepted work plan: worktree/branch/coder/reviewer plan; + - current next action for each target. +- Distinguish durable project-relevant routing decisions from local runtime/session claims. + - Project-relevant decisions should live in Ticket records/thread/artifacts or a typed Ticket orchestration record under project authority. + - Local Pod/session claims remain in the local role session registry. +- Records should survive compaction and be queryable by Ticket id/slug and relation kind. +- Keep the first version lightweight; do not implement a full scheduler/graph solver. + +### Plan update semantics + +- The Orchestrator should update the plan at meaningful routing boundaries: + - new queued work incorporated into the plan; + - queued -> inprogress acceptance; + - inprogress -> blocked/waiting/planning/done; + - capacity stop -> leave planned queued/waiting with reason; + - merge-ready/done -> mark complete and consider the next planned queued Ticket if no active work remains. +- Each update should produce a bounded, inspectable record of: + - what was considered; + - what was incorporated into the plan; + - what was accepted/started; + - what was blocked/deferred/returned to planning; + - what remains planned queued/waiting. +- Re-kick should use the current plan/work set so the Orchestrator does not forget leftover queued Tickets between turns. + +### Relationship to existing work + +- This Ticket should either subsume or update `ticket-orchestration-plan-tool` so there is one coherent plan/re-kick design. +- It should coordinate with: + - `replace-intake-state-with-planning` as a prerequisite that defines the planning lane before this plan/re-kick layer builds on it; + - `panel-close-done-tickets` for done -> closed handling; + - local role session registry for active Pod/session ownership; + - direct/delegation authority work for actual child Pod spawning. + +## Non-requirements + +- Do not turn the Panel itself into the scheduler. +- Do not auto-start unqueued Tickets. +- Do not re-kick continuously while active coder/reviewer/preflight/merge work is already in progress. +- Do not blindly spawn coder Pods from re-kick without Orchestrator inspection and `queued -> inprogress` acceptance. +- Do not implement a full dependency graph solver in the first version. + +## Acceptance criteria + +- The system can distinguish new queued work, planned queued work, and accepted in-progress work. +- New queued Tickets are not left unnoticed while the Orchestrator is otherwise idle. +- Runnable planned queued Tickets are not left unstarted when there is no active in-progress work and capacity/policy allows progress. +- The system does not re-kick merely because queued/planned work exists while Orchestrator-managed in-progress work is waiting on coder/reviewer/preflight/merge completion. +- Missed/stale queued Tickets can be surfaced to the Orchestrator without requiring the user to manually requeue each one. +- The Orchestrator can record and query a lightweight Ticket orchestration plan covering active targets, order/dependency/conflict/capacity, state bucket, and next actions. +- Plan records survive compaction and do not rely solely on session-lifetime TaskStore state. +- Re-kick/plan updates leave an auditable record of what was incorporated, started, blocked, returned to planning, or left waiting. +- Duplicate implementation starts are prevented by consulting current Ticket state, local role/session claims, and plan records. +- Relevant workflows/prompts/docs are updated. +- Focused tests, `target/debug/yoi ticket doctor`, `cargo fmt --check`, and `git diff --check` pass. diff --git a/.yoi/tickets/open/20260608-061235-orchestrator-active-ticket-plan-iteration/thread.md b/.yoi/tickets/open/20260608-061235-orchestrator-active-ticket-plan-iteration/thread.md new file mode 100644 index 00000000..689d677a --- /dev/null +++ b/.yoi/tickets/open/20260608-061235-orchestrator-active-ticket-plan-iteration/thread.md @@ -0,0 +1,50 @@ + + +## Created + +Created by LocalTicketBackend create. + +--- + + + +## Decision + +## Scope refinement: avoid idle starvation, not constant iteration + +The phrase "continuously iterate" should not mean that the Orchestrator constantly re-kicks itself regardless of current work. The desired behavior is narrower: + +- Do not leave newly queued work unnoticed while the Orchestrator is otherwise idle. +- Do not leave planned queued work unstarted when there is no in-progress work and capacity/policy allows starting it. +- Do not re-kick just because queued work exists if the Orchestrator is already waiting for an active coder/reviewer/preflight/merge step. + +Refined planning model: + +- `new_queued`: Tickets with `workflow_state = queued` that have not yet been incorporated into the OrchestrationPlan. +- `planned_queued`: queued Tickets that the Orchestrator has considered and placed into an explicit plan/order/waiting set, but has not yet accepted as `inprogress`. +- `inprogress`: Tickets accepted by the Orchestrator and currently awaiting worktree/coder/reviewer/preflight/merge/cleanup progress. + +Desired scheduling/re-kick semantics: + +1. If there is `new_queued` work and the Orchestrator is idle/not occupied by an active in-progress operation, it should be kicked or shown a bounded work list so it can incorporate the new Tickets into the plan. +2. If there is no `inprogress` work and there is `planned_queued` work that is not blocked/capacity-limited, the Orchestrator should be kicked to start/accept the next planned Ticket rather than waiting indefinitely for user instruction. +3. If there is active `inprogress` work whose next expected event is coder/reviewer/preflight/merge completion, do not re-kick merely because queued/planned work exists. The Orchestrator should wait for the active work or an explicit user action/capacity decision. +4. If planned queued work is blocked or waiting for capacity, the plan should record that reason so the panel/user can see why nothing starts. + +This should be framed as starvation prevention and explicit work-set planning, not a background scheduler loop. + +--- + + + +## Decision + +## Dependency ordering: planning lane before re-kick planning layer + +`replace-intake-state-with-planning` owns the behavior for cases where work cannot be planned/implemented yet because requirements or preflight are missing: return the Ticket to the planning lane with a visible reason. + +This Ticket assumes that behavior exists and builds the `new_queued` / `planned_queued` / `inprogress` re-kick model on top of the clarified workflow states. Implementation order should be: settle `replace-intake-state-with-planning` first, then implement the OrchestrationPlan/re-kick layer. + +Therefore, the OrchestrationPlan/re-kick layer should not introduce its own separate `preflight_needed` bucket or cleanup logic. + +---