yoi/.yoi/tickets/closed/20260605-040104-ticket-local-files-backend/item.md

id	slug	title	status	kind	priority	labels	created_at	updated_at	assignee
20260605-040104-ticket-local-files-backend	ticket-local-files-backend	Ticket local files backend	closed	task	P1	ticket backend orchestration	2026-06-05T04:01:04Z	2026-06-05T04:45:46Z	null

Background

The first step toward Ticket-driven multi-agent orchestration is to make the current work-items/ + tickets.sh file format accessible through a typed Rust API.

The product/code concept name is Ticket. The current directory name work-items/ remains the LocalTicketBackend storage path for now; do not rename it in this ticket.

This ticket should produce a backend-shaped domain layer that future Pod tools, Intake workflows, Orchestrator routing, TUI views, and external tracker integrations can use without depending on tickets.sh shell execution or ad hoc markdown parsing.

Requirements

• Add a code-facing Ticket domain/backend layer.
  • Preferred crate: crates/ticket or crates/tickets; choose the name that reads best in Rust and avoids collision with tickets.sh scripts.
  • The public concept/type names should use Ticket, not WorkItem.
• Implement LocalTicketBackend over current work-items/ storage.
• Preserve the current markdown + frontmatter + thread.md + artifacts/ layout.
• Preserve compatibility with tickets.sh; existing script operations should continue to work on files written by the Rust backend.
• Keep git history and repository files authoritative.
• Implement typed operations equivalent to at least:
  • list;
  • show;
  • create;
  • comment / plan / decision / implementation_report events;
  • review approve/request-changes;
  • status transition;
  • close with resolution;
  • doctor/consistency check.
• Use a thin typed envelope with Markdown/freeform bodies.
• Include machine-readable fields needed by Orchestrator/TUI/policy:
  • id / slug / title;
  • kind / priority / labels;
  • status;
  • readiness;
  • needs-preflight;
  • risk flags;
  • action-required state;
  • event kind;
  • references to files, branches, commits, Pods, artifacts, URLs where practical.
• Keep enums extensible where backend compatibility needs raw values.
• Implement safe local-file mutation:
  • atomic writes where files are replaced;
  • lock/conflict handling sufficient for multiple Pod/tool users;
  • no writes outside the configured local ticket root except controlled temp files.
• Provide bounded errors/diagnostics suitable for later tool output.

Suggested API shape

The exact API can be adjusted during implementation, but should remain backend-shaped:

trait TicketBackend {
    fn list(&self, filter: TicketFilter) -> Result<Vec<TicketSummary>>;
    fn show(&self, id: TicketIdOrSlug) -> Result<Ticket>;
    fn create(&self, input: NewTicket) -> Result<TicketRef>;
    fn add_event(&self, id: TicketIdOrSlug, event: NewTicketEvent) -> Result<()>;
    fn review(&self, id: TicketIdOrSlug, review: TicketReview) -> Result<()>;
    fn set_status(&self, id: TicketIdOrSlug, status: TicketStatus) -> Result<()>;
    fn close(&self, id: TicketIdOrSlug, resolution: MarkdownText) -> Result<()>;
    fn doctor(&self) -> Result<TicketDoctorReport>;
}

Non-goals

• Exposing Pod tools.
• Implementing Intake Pod behavior.
• Implementing Orchestrator routing or scheduling.
• Renaming work-items/.
• Removing tickets.sh.
• Integrating GitHub Issues, Linear, Jira, MCP, or other external backends.
• Building a scheduler/lease system.
• Changing the session-local Task tool.

Acceptance criteria

• Rust code can read existing open/pending/closed tickets from work-items/.
• Rust code can create a ticket equivalent to tickets.sh create.
• Rust code can append typed thread events equivalent to tickets.sh comment roles.
• Rust code can record approve/request-changes reviews equivalent to tickets.sh review.
• Rust code can close a ticket with a resolution.md equivalent to tickets.sh close.
• Rust doctor catches the same core consistency failures as tickets.sh doctor or clearly documents any remaining gaps.
• Files written by the Rust backend pass ./tickets.sh doctor.
• Existing tickets.sh can still read/mutate tickets written by the Rust backend.
• Unit tests cover parsing, create, event append, review, status transition, close, doctor, lock/conflict handling, and corrupt input diagnostics.
• cargo test for the new crate passes.
• cargo check --workspace --all-targets, cargo fmt --check, git diff --check, and ./tickets.sh doctor pass.

Follow-up tickets

• ticket-built-in-feature-tools
• ticket-intake-workflow
• ticket-orchestrator-routing