yoi/work-items/open/20260605-040104-ticket-built-in-feature-tools/artifacts/delegation-intent.md

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:

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:

ticket -> llm-worker   # for Tool/ToolDefinition only
ticket -> serde/schemars/etc.
pod -> ticket

Forbidden dependency direction:

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.