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
|
||||
labels: [ticket, feature, tool, orchestration]
|
||||
created_at: 2026-06-05T04:01:04Z
|
||||
updated_at: 2026-06-05T04:01:25Z
|
||||
updated_at: 2026-06-05T05:37:42Z
|
||||
assignee: null
|
||||
legacy_ticket: null
|
||||
---
|
||||
|
|
|
|||
|
|
@ -4,4 +4,61 @@
|
|||
|
||||
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