From a06d007202d3bb1a9015480db45ae04b62577842 Mon Sep 17 00:00:00 2001 From: Hare Date: Fri, 5 Jun 2026 14:37:54 +0900 Subject: [PATCH] ticket: preflight ticket feature tools --- .../artifacts/delegation-intent.md | 187 ++++++++++++++++++ .../item.md | 2 +- .../thread.md | 57 ++++++ 3 files changed, 245 insertions(+), 1 deletion(-) create mode 100644 work-items/open/20260605-040104-ticket-built-in-feature-tools/artifacts/delegation-intent.md diff --git a/work-items/open/20260605-040104-ticket-built-in-feature-tools/artifacts/delegation-intent.md b/work-items/open/20260605-040104-ticket-built-in-feature-tools/artifacts/delegation-intent.md new file mode 100644 index 00000000..93925dc5 --- /dev/null +++ b/work-items/open/20260605-040104-ticket-built-in-feature-tools/artifacts/delegation-intent.md @@ -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 /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 `/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 `/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. diff --git a/work-items/open/20260605-040104-ticket-built-in-feature-tools/item.md b/work-items/open/20260605-040104-ticket-built-in-feature-tools/item.md index 21b8b2b7..cb2057a4 100644 --- a/work-items/open/20260605-040104-ticket-built-in-feature-tools/item.md +++ b/work-items/open/20260605-040104-ticket-built-in-feature-tools/item.md @@ -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 --- diff --git a/work-items/open/20260605-040104-ticket-built-in-feature-tools/thread.md b/work-items/open/20260605-040104-ticket-built-in-feature-tools/thread.md index 96d51d9b..5d77f8cd 100644 --- a/work-items/open/20260605-040104-ticket-built-in-feature-tools/thread.md +++ b/work-items/open/20260605-040104-ticket-built-in-feature-tools/thread.md @@ -4,4 +4,61 @@ Created by tickets.sh create. +--- + + + +## 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. + + +--- + + + +## 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`. + + ---