diff --git a/.yoi/tickets/open/20260527-000018-tui-user-model-setup/item.md b/.yoi/tickets/open/20260527-000018-tui-user-model-setup/item.md index 55b5cffb..10a52ced 100644 --- a/.yoi/tickets/open/20260527-000018-tui-user-model-setup/item.md +++ b/.yoi/tickets/open/20260527-000018-tui-user-model-setup/item.md @@ -7,9 +7,10 @@ kind: task priority: P2 labels: [migrated] created_at: 2026-05-27T00:00:18Z -updated_at: 2026-05-27T00:00:18Z +updated_at: '2026-06-08T07:29:10Z' assignee: null legacy_ticket: tickets/tui-user-model-setup.md +workflow_state: 'ready' --- ## Migration reference diff --git a/.yoi/tickets/open/20260527-000018-tui-user-model-setup/thread.md b/.yoi/tickets/open/20260527-000018-tui-user-model-setup/thread.md index 8a767303..64b39a70 100644 --- a/.yoi/tickets/open/20260527-000018-tui-user-model-setup/thread.md +++ b/.yoi/tickets/open/20260527-000018-tui-user-model-setup/thread.md @@ -5,3 +5,67 @@ Migrated from tickets/tui-user-model-setup.md. No legacy review file was present at migration time. --- + + + +## Decision + +## Intake refinement: current Yoi context + +This is an existing migrated Ticket; no duplicate Ticket was created. The original body remains useful for the desired wizard shape, but several migrated assumptions are stale and must be treated as superseded where they conflict with current Yoi code and project decisions. + +### Current request snapshot + +Add an interactive TUI setup flow that helps a first-time user choose a provider/model from the provider catalog and persist a user-level default model configuration so a normal fresh `yoi` spawn can resolve a model without manual TOML editing. + +### Binding decisions / invariants + +- Product entrypoint is the installed `yoi` binary, not an old standalone `tui`/`insomnia` binary. The CLI surface should be chosen under the `yoi` CLI owner boundary; the migrated `tui setup-model` spelling is only historical/placeholder text. +- Current config paths use `manifest::paths::config_dir()` with default `$XDG_CONFIG_HOME/yoi` / `$HOME/.config/yoi`, not `~/.config/insomnia`. +- Normal reusable runtime configuration is Profile-oriented. The implementation must decide, with preflight, whether this wizard writes/updates `profiles.toml`, a profile-local model fragment, or another explicit user config surface; it must not silently reintroduce the removed ambient manifest-cascade model. +- Current catalog auth hints are `AuthHint::None`, `AuthHint::ApiKey`, `AuthHint::SecretRef { ref_ }`, and `AuthHint::CodexOAuth`; the migrated `ApiKey { env: Option }` flow is stale. +- Secret values must not be written into Ticket bodies, logs, diagnostics, or generated artifacts. Prefer the existing local secret-store / `yoi keys` boundary for normal provider credentials; raw `model.auth.file` remains a low-level explicit-file source, not the default UX if a safer secret-ref path is available. +- The wizard must be cancel-safe: no user config/secret writes before explicit confirmation, and failed parsing/writing must leave existing config usable. + +### Implementation latitude + +- The exact command name may be settled during preflight, but should fit existing `yoi` CLI semantics and help text. +- A simple vertical provider/model list is sufficient for the first implementation; search/filtering can be deferred unless preflight finds the catalog size makes it necessary. +- If only one model exists for the selected provider, skipping the model-choice step is acceptable. +- Preview may show the generated/surgical config change rather than a full diff, as long as overwrite of an existing model/default is explicit. + +### Acceptance criteria + +- A first-time user can launch the setup flow from the `yoi` CLI without entering normal Pod spawn by accident. +- The flow loads current `provider::catalog::load_providers()` and `load_models()` data, displays provider/model choices, and handles all current `AuthHint` variants. +- The confirmed result persists a user-level default model/profile configuration at the current Yoi config path, without storing plaintext secrets in config by default. +- Existing user config with an existing model/default is detected and requires overwrite confirmation; malformed config is reported and not rewritten. +- Esc/Ctrl-C cancel before confirmation leaves files unchanged. +- After setup, a normal fresh `yoi` spawn can resolve the selected model/profile without a model-resolve error. +- Validation includes focused Rust tests for CLI parsing/config rendering/update behavior and `nix build .#yoi` because this changes CLI/TUI/runtime resources/packaging-visible code. + +### Readiness / routing signal + +- readiness: spike_needed +- needs_preflight: true +- risk_flags: [cli-ux, profiles-config, secrets, auth-boundary, migration-staleness, tui] + +This Ticket is ready for Orchestrator routing to preflight/spike, not direct implementation. Preflight should first settle the current user-config write target and command spelling, then either update the Ticket body or record a concise binding decision before implementation. + +--- + + + +## Intake summary + +Updated existing Ticket 20260527-000018-tui-user-model-setup in place; no duplicate was created. The migrated request is now clarified as a Yoi CLI/TUI first-run model setup flow, with stale `tui`/`insomnia`/old AuthHint assumptions explicitly superseded in the thread. Routing readiness is spike/preflight, not direct implementation: first settle current `yoi` command spelling and the user-level config write target for Profile-oriented model defaults, then implement the wizard. needs_preflight=true; risk_flags=[cli-ux, profiles-config, secrets, auth-boundary, migration-staleness, tui]. + +--- + + + +## State changed + +Intake clarification completed for the existing Ticket. The Ticket is ready for Orchestrator routing to preflight/spike; implementation should not begin until the preflight decisions called out in the intake summary are recorded. + +--- diff --git a/.yoi/tickets/open/20260607-225448-replace-intake-state-with-planning/item.md b/.yoi/tickets/open/20260607-225448-replace-intake-state-with-planning/item.md index ab08ecb8..6ee10ede 100644 --- a/.yoi/tickets/open/20260607-225448-replace-intake-state-with-planning/item.md +++ b/.yoi/tickets/open/20260607-225448-replace-intake-state-with-planning/item.md @@ -6,9 +6,9 @@ status: open kind: task priority: P1 labels: [ticket, workflow-state, orchestrator, panel, intake, planning] -workflow_state: intake +workflow_state: 'ready' created_at: 2026-06-07T22:54:48Z -updated_at: 2026-06-07T22:54:48Z +updated_at: '2026-06-08T07:22:47Z' assignee: null legacy_ticket: null --- diff --git a/.yoi/tickets/open/20260607-225448-replace-intake-state-with-planning/thread.md b/.yoi/tickets/open/20260607-225448-replace-intake-state-with-planning/thread.md index aecfeb35..d535f571 100644 --- a/.yoi/tickets/open/20260607-225448-replace-intake-state-with-planning/thread.md +++ b/.yoi/tickets/open/20260607-225448-replace-intake-state-with-planning/thread.md @@ -5,3 +5,55 @@ Created by LocalTicketBackend create. --- + + + +## Decision + +## Decision: remove standalone `preflight` concept; use return-to-planning + +Do not preserve `preflight` as a separate workflow concept, operation, or long-lived routing bucket. + +The desired model is: + +- Intake/Planning prepares a Ticket until it can become `ready`. +- Orchestrator reads queued/ready work and may find that implementation cannot be planned safely yet. +- In that case, Orchestrator records the missing information/decision and returns the Ticket to `planning` with a visible reason. +- There is no separate `preflight_needed` state, no separate preflight lane, and no Intake-authored `needs_preflight` gate. + +Responsibility split: + +- Intake/Planning owns requirements clarification and Ticket shaping. +- Orchestrator owns routing and may reject/return work to planning when the Ticket lacks required decisions, constraints, or implementation intent. +- Planning owns resolving that returned reason. + +Workflow/documentation implications: + +- Remove `needs_preflight` from Intake-facing concepts. Intake may record `risk_flags`, open questions, and readiness, but should not decide that a future Orchestrator preflight operation is required. +- Replace Orchestrator `preflight_needed` classification with a planning-return classification such as `planning_needed` / `return_to_planning` / `requirements_sync_needed`. +- Remove or fold `ticket-preflight-workflow` into the planning workflow/docs. The useful content is the checklist for deciding whether a Ticket has enough binding decisions and implementation intent; it should not be exposed as a separate operation/lane. +- Risk flags are reviewer/orchestrator attention markers, not stop gates. +- If Orchestrator cannot name a concrete missing decision/information item, it should not return the Ticket to planning merely because the area is risky; it should proceed with an IntentPacket plus escalation/reviewer focus. + +Acceptance impact: + +- The implementation should update workflow-state terminology, prompts/workflows, panel labels/actions, and tests so missing implementation readiness is represented as a return to `planning`, not as `preflight_needed`. +- Existing mentions of `preflight_needed` should be removed, renamed, or treated as migration/legacy compatibility only where needed. + +--- + + + +## Intake summary + +Existing Ticket was refined as an implementation-ready planning-state replacement task. The binding direction is to replace the user-facing `intake` workflow state with a planning-oriented state/lane, preserve the Intake role name as separate terminology, and remove standalone `preflight` / `needs_preflight` concepts from the user-facing workflow. Orchestrator missing-readiness routing should record a concrete reason and return the Ticket to planning, not create a separate preflight lane. Implementation should update state parsing/normalization or migration, transition graph, panel labels/actions, role/workflow prompts/docs, Ticket tools/CLI surfaces, and tests. Risk flags for routing/review attention: workflow-state, migration, panel-ux, orchestrator-routing, prompt-workflow-docs. No separate preflight gate remains; risk flags are attention markers, not blockers. + +--- + + + +## State changed + +Ticket has enough binding decisions, invariants, acceptance criteria, and validation expectations for Orchestrator routing. Marking ready for user queueing; implementation must not start until the user/panel performs `ready -> queued` and Orchestrator accepts it. + +--- diff --git a/.yoi/tickets/open/20260608-071722-orchestrator-return-to-planning-context-policy/artifacts/.gitkeep b/.yoi/tickets/open/20260608-071722-orchestrator-return-to-planning-context-policy/artifacts/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/.yoi/tickets/open/20260608-071722-orchestrator-return-to-planning-context-policy/item.md b/.yoi/tickets/open/20260608-071722-orchestrator-return-to-planning-context-policy/item.md new file mode 100644 index 00000000..1868ee7b --- /dev/null +++ b/.yoi/tickets/open/20260608-071722-orchestrator-return-to-planning-context-policy/item.md @@ -0,0 +1,71 @@ +--- +id: '20260608-071722-orchestrator-return-to-planning-context-policy' +slug: 'orchestrator-return-to-planning-context-policy' +title: 'Require project context before Orchestrator returns Tickets to planning' +status: 'open' +kind: 'task' +priority: 'P1' +labels: ['ticket', 'orchestrator', 'planning', 'workflow', 'prompt'] +workflow_state: 'intake' +created_at: '2026-06-08T07:17:22Z' +updated_at: '2026-06-08T07:17:22Z' +assignee: null +legacy_ticket: null +--- + +## Background + +`replace-intake-state-with-planning` removes the standalone `preflight` concept and represents implementation-readiness gaps as a return to the `planning` lane with a visible reason. + +That creates an important follow-up requirement for Orchestrator routing: returning a Ticket to planning must not become the new form of blind preflight rejection. The Orchestrator should not look only at Ticket text, `risk_flags`, or broad risky domains and decide to stop. It must consider relevant project context before deciding that implementation cannot proceed. + +The recent `allow-spawnpod-child-workspace-cwd` discussion exposed the failure mode: a Ticket can touch authority/Pod/scope areas while still containing enough binding decisions and acceptance criteria to route to implementation. In that case, risk should become reviewer focus and escalation conditions, not an automatic return to planning. + +## Goal + +Update Orchestrator routing guidance so a Ticket is returned to planning only when the Orchestrator can identify concrete missing information or binding decisions after checking enough project context. + +## Requirements + +- Treat this as a follow-up to `replace-intake-state-with-planning`. + - First remove/fold the standalone `preflight` concept into planning. + - Then apply this policy to the Orchestrator's return-to-planning decision. +- Update `ticket-orchestrator-routing` or equivalent prompt/workflow guidance. +- Before returning a queued/ready Ticket to planning, the Orchestrator must inspect enough context to distinguish: + - a genuinely missing binding decision, requirement, invariant, or acceptance criterion; + - an existing recorded decision in the Ticket thread, related Tickets, docs, workflows, code, or durable project context; + - a bounded local implementation tactic that a coder can resolve during implementation. +- Risk flags are context lookup triggers and reviewer focus, not stop gates. + - `authority-boundary`, `scope`, `permission`, `Pod`, `persistence`, `prompt-context`, `public-api`, and similar risk areas should cause targeted context checking. + - They should not by themselves justify returning to planning. +- If the Orchestrator returns a Ticket to planning, it must record: + - the concrete missing decision/information; + - the context it checked; + - why the gap cannot be safely handled as implementation latitude; + - the next planning question/action. +- If the Orchestrator cannot name a concrete missing decision/information item after context checking, it should not return the Ticket to planning merely because it is risky. + - It should instead proceed as implementation-ready when other criteria are satisfied, with an IntentPacket that includes invariants, implementation latitude, escalation conditions, and reviewer focus. +- Keep the context check bounded and relevant. + - Do not require broad repository audits for every Ticket. + - Prefer targeted reads of Ticket thread/artifacts, related Tickets, known workflows/docs, current code map, git/worktree/Pod state, and relevant durable decisions. +- Ensure the routing decision template includes an `Evidence checked` section strong enough to reveal whether the Orchestrator actually considered project context. + +## Non-goals + +- Reintroducing `preflight` as a separate operation, state, or lane. +- Making every queued Ticket require extensive code archaeology. +- Removing Orchestrator judgment; the point is to make the judgment evidence-based. +- Letting coder Pods silently decide product/API/authority boundaries that are genuinely missing. + +## Acceptance criteria + +- Orchestrator workflow/prompt guidance says Tickets must not be returned to planning from Ticket text or risk flags alone. +- Returning to planning requires a concrete missing decision/information item and an evidence record of relevant context checked. +- Risk flags are documented as lookup/reviewer-focus signals, not gates. +- Implementation-ready routing explicitly allows risky-but-specified Tickets to proceed with IntentPacket invariants, escalation conditions, and reviewer focus. +- The workflow includes or references an example equivalent to `allow-spawnpod-child-workspace-cwd`: authority-adjacent work with explicit binding decisions should proceed rather than be returned to planning solely because of risk category. +- Focused tests or prompt/workflow validation cover at least: + - risky but specified Ticket -> implementation-ready; + - genuinely missing decision -> return to planning; + - risk flag alone is insufficient as the reason. +- `target/debug/yoi ticket doctor` and `git diff --check` pass. diff --git a/.yoi/tickets/open/20260608-071722-orchestrator-return-to-planning-context-policy/thread.md b/.yoi/tickets/open/20260608-071722-orchestrator-return-to-planning-context-policy/thread.md new file mode 100644 index 00000000..3e801da9 --- /dev/null +++ b/.yoi/tickets/open/20260608-071722-orchestrator-return-to-planning-context-policy/thread.md @@ -0,0 +1,7 @@ + + +## Created + +Created by LocalTicketBackend create. + +--- diff --git a/.yoi/tickets/open/20260608-072732-typed-ticket-relation-metadata/artifacts/.gitkeep b/.yoi/tickets/open/20260608-072732-typed-ticket-relation-metadata/artifacts/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/.yoi/tickets/open/20260608-072732-typed-ticket-relation-metadata/item.md b/.yoi/tickets/open/20260608-072732-typed-ticket-relation-metadata/item.md new file mode 100644 index 00000000..01718163 --- /dev/null +++ b/.yoi/tickets/open/20260608-072732-typed-ticket-relation-metadata/item.md @@ -0,0 +1,92 @@ +--- +id: '20260608-072732-typed-ticket-relation-metadata' +slug: 'typed-ticket-relation-metadata' +title: 'Add typed Ticket relation metadata' +status: 'open' +kind: 'task' +priority: 'P1' +labels: ['ticket', 'relations', 'planning', 'panel', 'orchestrator'] +workflow_state: 'intake' +created_at: '2026-06-08T07:27:32Z' +updated_at: '2026-06-08T07:28:29Z' +assignee: null +legacy_ticket: null +--- + +## Background + +Ticket orchestration needs two distinct kinds of cross-Ticket coordination: + +1. Project-level Ticket relations that are intrinsic to the Tickets themselves: + - this feature depends on that Ticket; + - this problem must be resolved before that Ticket is meaningful; + - this Ticket blocks another Ticket; + - this is an umbrella/child or related/superseding Ticket relationship. + +2. Orchestrator execution-plan decisions: + - these two Tickets are conceptually independent but touch conflicting code paths, so do not run them in parallel; + - start Ticket A before B for the current batch; + - wait for current reviewer/coder capacity; + - this Ticket is planned queued but not yet accepted. + +The existing `ticket-orchestration-plan-tool` belongs to the second category. It may be durable, but it is still about Orchestrator execution planning and local/current workset coordination. + +This Ticket covers the first category: typed, durable Ticket-to-Ticket relations that can be shown and validated before the Orchestrator runs. + +## Goal + +Add typed Ticket relation metadata for project-level dependencies, blockers, hierarchy, and related/superseding links, stored with the Ticket system and visible through CLI/Panel/Ticket APIs independently of Orchestrator runtime plans. + +## Requirements + +- Provide a typed way to record Ticket-to-Ticket relations as project records. +- Support at least these relation kinds, with final naming to be decided during implementation: + - `depends_on`: this Ticket requires another Ticket to be completed/resolved first; + - `blocks`: this Ticket blocks another Ticket; + - `parent` / `child`: umbrella or decomposition relationship; + - `related`: non-blocking relation worth showing; + - `supersedes` / `superseded_by` or `duplicate_of`: replacement/duplication relationship. +- Decide whether inverse relations such as `blocked_by`, `children`, and `superseded_by` are stored explicitly or derived from forward relations. +- Store relations in the Ticket backend in a durable, git-trackable form. + - Prefer a typed field/artifact/event model that can be validated by the Ticket backend. + - Avoid relying only on freeform Markdown thread text for mechanical relationships. +- Make relations visible before Orchestrator execution: + - `TicketShow` should display relevant relations; + - `TicketList` or Panel summaries should show at least blocking/dependency hints where space allows; + - Panel/CLI should be able to indicate that a Ticket is blocked by unresolved dependencies. +- Add validation: + - `ticket doctor` should detect dangling Ticket references; + - invalid relation kinds should fail validation; + - self-dependencies and obvious invalid cycles should be rejected or diagnosed; + - closed/resolved dependencies should be distinguishable from open blockers. +- Integrate with Intake/Planning: + - Intake/Planning should be able to record known project-level relations when materializing/refining a Ticket; + - duplicate/supersedes/parent-child relations should be available for Ticket shaping and review. +- Integrate with Orchestrator routing as input, not as runtime plan state: + - Orchestrator should consult Ticket relations before accepting queued work; + - unresolved `depends_on` / blocking relations should prevent acceptance or return the Ticket to planning/blocked with a visible reason; + - OrchestrationPlan may use Ticket relations as constraints, but should not own or invent project-level dependency metadata. +- Keep this distinct from local execution state: + - do not store Pod/session claims, worktree paths, active branch ownership, or reviewer/coder assignments in Ticket relation metadata; + - those remain in the local role session registry / OrchestrationPlan / Pod metadata as appropriate. + +## Non-goals + +- Replacing OrchestrationPlan execution decisions such as current capacity, do-not-parallelize because of code conflicts, or planned queued order for the current batch. +- Implementing a full dependency graph scheduler. +- Making every related Ticket relation block queuing automatically. +- Encoding transient local Pod/worktree claims in git-tracked Ticket metadata. + +## Acceptance criteria + +- Project-level Ticket relations can be recorded in a typed durable form. +- `TicketShow` displays relation metadata. +- `ticket doctor` validates dangling references, invalid kinds, self-relations, and at least obvious invalid dependency cycles or reports bounded diagnostics. +- Panel or Ticket list can surface dependency/blocking hints before the Orchestrator runs. +- Intake/Planning workflow guidance explains when to create project-level relations. +- Orchestrator routing guidance treats these relations as input constraints distinct from OrchestrationPlan runtime decisions. +- Documentation clearly distinguishes: + - `depends_on` / `blocks` as Ticket relation metadata; + - `do_not_parallelize` / capacity / current planned order as OrchestrationPlan execution decisions; + - Pod/session/worktree ownership as local runtime claims. +- Focused tests, `target/debug/yoi ticket doctor`, `cargo fmt --check`, and `git diff --check` pass. diff --git a/.yoi/tickets/open/20260608-072732-typed-ticket-relation-metadata/thread.md b/.yoi/tickets/open/20260608-072732-typed-ticket-relation-metadata/thread.md new file mode 100644 index 00000000..ce6053f6 --- /dev/null +++ b/.yoi/tickets/open/20260608-072732-typed-ticket-relation-metadata/thread.md @@ -0,0 +1,37 @@ + + +## Created + +Created by LocalTicketBackend create. + +--- + + + +## Decision + +## Design consideration: Queue gate should account for unresolved dependencies + +This relation metadata should be available before Orchestrator planning. That implies a stronger queue-time question: + +If a Ticket has a project-level dependency such as `depends_on: X`, and `X` is still in `planning` / not ready / not resolved, should the user be prevented or warned before Queueing the dependent Ticket? + +This needs explicit design before implementation. + +Considerations: + +- A dependency that is still `planning` likely means the dependent Ticket is not truly runnable yet. +- Queue should probably reject or strongly warn when unresolved `depends_on` / blocking relations remain. +- The behavior may differ by relation kind: + - `depends_on` unresolved: likely hard block or confirmation-required; + - `blocks`: informational for the blocked Ticket; + - `related`: never blocks; + - `parent` / `child`: depends on workflow semantics; + - `supersedes` / `duplicate_of`: may redirect or discourage Queue. +- The Panel should be able to show why Queue is unavailable or risky before involving the Orchestrator. +- CLI Queue/state transitions should enforce the same rule or at least expose the same diagnostics. +- Orchestrator should still re-check relations at acceptance time, because relations may change between Queue and routing. + +The implementation should decide whether unresolved dependencies make Queue invalid, require confirmation, or allow Queue with a visible blocked state. The important requirement is that dependency relation metadata is not only an Orchestrator input; it should also inform the human Queue gate. + +---