ticket: preflight ticket feature tools
This commit is contained in:
parent
229b8e4ee0
commit
a06d007202
|
|
@ -0,0 +1,187 @@
|
||||||
|
# Delegation intent: Ticket built-in feature tools
|
||||||
|
|
||||||
|
## Classification
|
||||||
|
|
||||||
|
`implementation-ready` with one important architectural constraint:
|
||||||
|
|
||||||
|
- Ticket domain/backend and Ticket tool behavior should live in the `ticket` crate as much as possible.
|
||||||
|
- `pod` should contain only the thin built-in feature adapter: descriptor, host-authority/backend-root wiring, and feature contribution registration.
|
||||||
|
|
||||||
|
This avoids repeating the earlier Task split problem where stateful feature behavior lived in the generic `tools` crate while lifecycle/state ownership lived in `pod`.
|
||||||
|
|
||||||
|
## Intent
|
||||||
|
|
||||||
|
Expose typed Ticket operations as built-in Pod tools without granting arbitrary filesystem write scope over `work-items/`.
|
||||||
|
|
||||||
|
The tools must operate through the `ticket` crate's `TicketBackend` / `LocalTicketBackend`, not through `tickets.sh` shell execution and not through generic file write tools.
|
||||||
|
|
||||||
|
## Worktree / branch
|
||||||
|
|
||||||
|
- worktree: `/home/hare/Projects/yoi/.worktree/ticket-built-in-feature-tools`
|
||||||
|
- branch: `work/ticket-built-in-feature-tools`
|
||||||
|
|
||||||
|
## Architecture decision
|
||||||
|
|
||||||
|
Use this dependency/ownership shape:
|
||||||
|
|
||||||
|
```text
|
||||||
|
crates/ticket
|
||||||
|
- Ticket domain/backend
|
||||||
|
- Ticket tool input/output types
|
||||||
|
- Ticket tool implementations as llm-worker Tool impls
|
||||||
|
- ticket_tools(...) factory
|
||||||
|
|
||||||
|
crates/pod
|
||||||
|
- built-in Ticket feature descriptor
|
||||||
|
- local backend root resolution, initially <workspace>/work-items
|
||||||
|
- host authority declaration/grant wiring
|
||||||
|
- FeatureContribution registration
|
||||||
|
|
||||||
|
crates/tools
|
||||||
|
- unchanged; do not add Ticket tools here
|
||||||
|
```
|
||||||
|
|
||||||
|
Allowed dependency direction:
|
||||||
|
|
||||||
|
```text
|
||||||
|
ticket -> llm-worker # for Tool/ToolDefinition only
|
||||||
|
ticket -> serde/schemars/etc.
|
||||||
|
pod -> ticket
|
||||||
|
```
|
||||||
|
|
||||||
|
Forbidden dependency direction:
|
||||||
|
|
||||||
|
```text
|
||||||
|
ticket -> pod
|
||||||
|
```
|
||||||
|
|
||||||
|
Do not extract a lower `feature-api` crate in this ticket. A fully crate-contained feature contribution can be revisited later if/when feature API is moved below `pod`.
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- Add Ticket tool behavior to the `ticket` crate.
|
||||||
|
- Add a thin `pod::feature::builtin::ticket` adapter that installs those tools through the existing FeatureContribution/ToolRegistry path.
|
||||||
|
- Do not put Ticket tools in `crates/tools`.
|
||||||
|
- Do not shell out to `tickets.sh`.
|
||||||
|
- Use `LocalTicketBackend` over the configured/local backend root.
|
||||||
|
- Initial backend root may be resolved as `<workspace>/work-items` by the Pod adapter.
|
||||||
|
- Register Ticket tools only when the built-in Ticket feature is explicitly installed by the Pod host adapter.
|
||||||
|
- It is acceptable for the current Pod controller to install it when `<workspace>/work-items` exists or when the project config path is otherwise clearly resolved.
|
||||||
|
- If the root is missing/unusable, fail closed or do not register tools; do not create arbitrary directories silently.
|
||||||
|
- Treat Ticket operations as typed backend authority, not generic filesystem write scope.
|
||||||
|
- If adding a new `HostAuthority` variant is appropriate, prefer an explicit Ticket/backend authority over reusing generic `Filesystem` in a way that implies arbitrary FS access.
|
||||||
|
- Preserve existing PreToolCall/tool permission path: registered tools still go through normal tool-call policy.
|
||||||
|
- Keep outputs bounded and model-readable.
|
||||||
|
- Keep write paths compatible with `./tickets.sh doctor`.
|
||||||
|
- Add focused tests for both the `ticket` crate tool behavior and the Pod feature adapter.
|
||||||
|
|
||||||
|
## Tool surface
|
||||||
|
|
||||||
|
Implement the MVP tool set unless a clear blocker appears:
|
||||||
|
|
||||||
|
- `TicketCreate`
|
||||||
|
- `TicketList`
|
||||||
|
- `TicketShow`
|
||||||
|
- `TicketComment`
|
||||||
|
- `TicketReview`
|
||||||
|
- `TicketStatus`
|
||||||
|
- `TicketClose`
|
||||||
|
- `TicketDoctor`
|
||||||
|
|
||||||
|
Optional follow-up, not required for MVP:
|
||||||
|
|
||||||
|
- `TicketArtifactWrite`
|
||||||
|
- `TicketArtifactRead`
|
||||||
|
- `TicketSearch`
|
||||||
|
|
||||||
|
## Suggested tool semantics
|
||||||
|
|
||||||
|
Keep exact schemas practical, but preserve these intentions:
|
||||||
|
|
||||||
|
- `TicketList`
|
||||||
|
- filter by status (`open`, `pending`, `closed`, `all`) and optionally label/kind/priority if easy.
|
||||||
|
- output summaries, not full bodies by default.
|
||||||
|
- `TicketShow`
|
||||||
|
- read one ticket by id/slug/query and return bounded item/thread/resolution/artifact metadata.
|
||||||
|
- `TicketCreate`
|
||||||
|
- create a Ticket with title, optional slug/kind/priority/labels, and Markdown body sections.
|
||||||
|
- do not create unresolved drafts unless the caller asks for an explicit requirements-sync/spike-style Ticket body.
|
||||||
|
- `TicketComment`
|
||||||
|
- append a typed event role: `comment`, `plan`, `decision`, or `implementation_report`.
|
||||||
|
- `TicketReview`
|
||||||
|
- append approve/request-changes review.
|
||||||
|
- `TicketStatus`
|
||||||
|
- move among open/pending/closed where supported; prefer `TicketClose` for close-with-resolution.
|
||||||
|
- `TicketClose`
|
||||||
|
- close with Markdown resolution.
|
||||||
|
- `TicketDoctor`
|
||||||
|
- report backend doctor diagnostics in bounded form.
|
||||||
|
|
||||||
|
## Non-goals
|
||||||
|
|
||||||
|
- Implementing Intake workflow/profile.
|
||||||
|
- Implementing Orchestrator routing/scheduling.
|
||||||
|
- Renaming `work-items/`.
|
||||||
|
- Removing `tickets.sh`.
|
||||||
|
- External tracker integration.
|
||||||
|
- MCP/plugin loading.
|
||||||
|
- Scheduler/lease/queue automation.
|
||||||
|
- TUI changes.
|
||||||
|
- Moving feature API into a new crate.
|
||||||
|
- Adding Ticket tools to `crates/tools`.
|
||||||
|
|
||||||
|
## Current code map
|
||||||
|
|
||||||
|
- `crates/ticket/src/lib.rs`
|
||||||
|
- Ticket domain/backend, `TicketBackend`, `LocalTicketBackend`, local tests.
|
||||||
|
- Add `tools` module or submodule here for Ticket tool behavior if the file is getting large.
|
||||||
|
- `crates/ticket/Cargo.toml`
|
||||||
|
- May need `llm-worker`, `serde`, `serde_json`, `schemars`, `async-trait`, and possibly `tokio` depending on tool implementation style.
|
||||||
|
- `crates/pod/src/feature/builtin.rs`
|
||||||
|
- Add/export built-in Ticket module.
|
||||||
|
- `crates/pod/src/feature/builtin/ticket.rs` or `crates/pod/src/feature/builtin/ticket/mod.rs`
|
||||||
|
- Thin adapter that contributes Ticket tools.
|
||||||
|
- `crates/pod/src/controller.rs`
|
||||||
|
- Installs built-in features. Add Ticket feature installation only through an explicit, bounded backend-root resolution path.
|
||||||
|
- `crates/pod/src/feature.rs`
|
||||||
|
- Host authority definitions if a Ticket/backend authority variant or tests are needed.
|
||||||
|
- `crates/pod/Cargo.toml`
|
||||||
|
- Add dependency on `ticket`.
|
||||||
|
|
||||||
|
## Critical risks
|
||||||
|
|
||||||
|
- Putting Ticket tool implementations in `pod` would undercut the purpose of extracting the Ticket backend and make the feature harder to reuse.
|
||||||
|
- Putting Ticket tools in `tools` would repeat the Task-tools responsibility problem.
|
||||||
|
- Making Ticket tools equivalent to generic filesystem write scope would violate the authority model.
|
||||||
|
- Auto-creating `work-items/` in arbitrary workspaces would surprise users; fail closed or do not register when no backend root is configured/found.
|
||||||
|
- Returning unbounded full ticket/thread/artifact content would make tool output too large.
|
||||||
|
|
||||||
|
## Validation
|
||||||
|
|
||||||
|
Run at least:
|
||||||
|
|
||||||
|
- `cargo test -p ticket`
|
||||||
|
- focused Pod feature tests, e.g. `cargo test -p pod ticket --lib` if test names allow it
|
||||||
|
- `cargo test -p pod feature --lib`
|
||||||
|
- `cargo test -p pod --lib`
|
||||||
|
- `cargo test -p tools --lib`
|
||||||
|
- `cargo check --workspace --all-targets`
|
||||||
|
- `cargo fmt --check`
|
||||||
|
- `git diff --check`
|
||||||
|
- `./tickets.sh doctor`
|
||||||
|
|
||||||
|
Run `nix build .#yoi --no-link` if feasible.
|
||||||
|
|
||||||
|
## Completion report
|
||||||
|
|
||||||
|
Report:
|
||||||
|
|
||||||
|
- worktree path / branch;
|
||||||
|
- commit hash;
|
||||||
|
- final module layout;
|
||||||
|
- exact tool names/schemas/output style;
|
||||||
|
- how backend root/authority is wired;
|
||||||
|
- evidence Ticket tools are not in `crates/tools`;
|
||||||
|
- validation results;
|
||||||
|
- unresolved risks/follow-ups;
|
||||||
|
- whether ready for external review.
|
||||||
|
|
@ -7,7 +7,7 @@ kind: task
|
||||||
priority: P1
|
priority: P1
|
||||||
labels: [ticket, feature, tool, orchestration]
|
labels: [ticket, feature, tool, orchestration]
|
||||||
created_at: 2026-06-05T04:01:04Z
|
created_at: 2026-06-05T04:01:04Z
|
||||||
updated_at: 2026-06-05T04:01:25Z
|
updated_at: 2026-06-05T05:37:42Z
|
||||||
assignee: null
|
assignee: null
|
||||||
legacy_ticket: null
|
legacy_ticket: null
|
||||||
---
|
---
|
||||||
|
|
|
||||||
|
|
@ -4,4 +4,61 @@
|
||||||
|
|
||||||
Created by tickets.sh create.
|
Created by tickets.sh create.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<!-- event: decision author: hare at: 2026-06-05T05:37:41Z -->
|
||||||
|
|
||||||
|
## Decision
|
||||||
|
|
||||||
|
Decision: keep Ticket tool behavior mostly in the `ticket` crate and use `pod` only as a thin built-in feature adapter.
|
||||||
|
|
||||||
|
Rationale:
|
||||||
|
|
||||||
|
- `ticket` should own the Ticket domain/backend and the behavior of Ticket operations.
|
||||||
|
- `pod::feature` is still owned by the `pod` crate, so feature installation/authority wiring cannot be fully crate-contained without extracting a lower `feature-api` crate.
|
||||||
|
- Extracting `feature-api` is explicitly out of scope for this ticket.
|
||||||
|
- Putting Ticket tools in `crates/tools` would repeat the Task tool responsibility problem.
|
||||||
|
|
||||||
|
Dependency shape:
|
||||||
|
|
||||||
|
```text
|
||||||
|
ticket -> llm-worker # Tool/ToolDefinition implementation only
|
||||||
|
pod -> ticket # built-in feature adapter and backend-root wiring
|
||||||
|
```
|
||||||
|
|
||||||
|
Forbidden:
|
||||||
|
|
||||||
|
```text
|
||||||
|
ticket -> pod
|
||||||
|
```
|
||||||
|
|
||||||
|
Implementation direction:
|
||||||
|
|
||||||
|
- `crates/ticket` may add Ticket tool input/output types and Tool implementations.
|
||||||
|
- `crates/pod/src/feature/builtin/ticket.*` should only install/register those tools through `FeatureContribution` and resolve host/backend authority.
|
||||||
|
- Ticket tools must operate through typed `TicketBackend`/`LocalTicketBackend`, not through `tickets.sh` or generic filesystem writes.
|
||||||
|
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<!-- event: plan author: hare at: 2026-06-05T05:37:42Z -->
|
||||||
|
|
||||||
|
## Plan
|
||||||
|
|
||||||
|
Preflight result: `implementation-ready`.
|
||||||
|
|
||||||
|
Prerequisites are complete:
|
||||||
|
|
||||||
|
- `ticket-local-files-backend` added the typed Ticket backend and `LocalTicketBackend`.
|
||||||
|
- `feature-api-authority-separation` clarified host-authority naming in `pod::feature`.
|
||||||
|
|
||||||
|
Scope for implementation:
|
||||||
|
|
||||||
|
- Add the MVP Ticket tool surface: create/list/show/comment/review/status/close/doctor.
|
||||||
|
- Keep Ticket tool behavior in `crates/ticket` and use a thin `pod` adapter for built-in feature registration and backend-root/authority wiring.
|
||||||
|
- Do not implement Intake workflow, Orchestrator routing, TUI changes, external trackers, MCP/plugin loading, scheduler/lease behavior, or `work-items/` rename.
|
||||||
|
|
||||||
|
Detailed delegation intent is recorded in `artifacts/delegation-intent.md`.
|
||||||
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue
Block a user