188 lines
7.1 KiB
Markdown
188 lines
7.1 KiB
Markdown
# 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.
|