ticket: close typed ticket event log
This commit is contained in:
-102
@@ -1,102 +0,0 @@
|
||||
# Delegation intent: typed Ticket thread event log
|
||||
|
||||
## Classification
|
||||
|
||||
`implementation-ready` foundational backend/API slice before `explicit-ticket-workflow-state`.
|
||||
|
||||
The explicit workflow-state ticket needs a reliable audit/event path for state transitions. This ticket should first make the existing Ticket thread format more typed and useful without rewriting history or changing panel workflow semantics yet.
|
||||
|
||||
## Intent
|
||||
|
||||
Turn `thread.md` into a concise typed append-only event log for durable Ticket events, especially state transitions and Intake summaries. Keep current state in `item.md` frontmatter; keep full conversations in Pod/session logs.
|
||||
|
||||
## Worktree / branch
|
||||
|
||||
- worktree: `/home/hare/Projects/yoi/.worktree/typed-ticket-thread-event-log`
|
||||
- branch: `work/typed-ticket-thread-event-log`
|
||||
|
||||
This ticket may read tracked `.yoi/tickets` records/design artifacts. Do not read or edit `.yoi/memory/`.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Add/formalize typed event kinds for at least:
|
||||
- `state_changed`;
|
||||
- `intake_summary`.
|
||||
- Preserve existing event kinds and historical compatibility:
|
||||
- `create`;
|
||||
- `comment`;
|
||||
- `plan`;
|
||||
- `decision`;
|
||||
- `implementation_report`;
|
||||
- `review`;
|
||||
- `status_changed`;
|
||||
- `close`.
|
||||
- Add typed Rust data/API for appending a `state_changed` event with fields such as:
|
||||
- `from`;
|
||||
- `to`;
|
||||
- `actor` or `author`;
|
||||
- `reason`;
|
||||
- optional concise `summary` / refs body.
|
||||
- Add typed Rust data/API for appending an `intake_summary` event with a bounded Markdown body and/or structured heading metadata.
|
||||
- Keep `thread.md` append-only.
|
||||
- Do not use thread events as the current-state authority; this ticket may add event APIs, but `explicit-ticket-workflow-state` owns current workflow frontmatter fields.
|
||||
- If a minimal state-transition helper is added, keep it forward-compatible with frontmatter state updates; do not invent a separate scheduler/state machine.
|
||||
- Update parser/doctor to understand the new event kinds and required attributes where practical.
|
||||
- `state_changed` should require `from`, `to`, `author/actor`, and `at` or equivalent.
|
||||
- `intake_summary` should require normal event metadata and a non-empty body where practical.
|
||||
- Keep existing Ticket tools/CLI working.
|
||||
- Avoid mass rewriting historical `thread.md` records.
|
||||
- Update docs/comments that describe thread role/event meanings.
|
||||
|
||||
## Current code map
|
||||
|
||||
- `crates/ticket/src/lib.rs`
|
||||
- `TicketEventKind` currently supports `StatusChanged` and `Other`.
|
||||
- `LocalTicketBackend::append_thread_event(...)` writes HTML comment event metadata.
|
||||
- `parse_thread(...)`, `parse_event_comment(...)`, `doctor_thread_events(...)` parse/validate thread events.
|
||||
- `LocalTicketBackend::add_event(...)`, `review(...)`, `status(...)`, and `close(...)` are existing mutation paths.
|
||||
- `crates/ticket/src/tool.rs`
|
||||
- `TicketComment` currently exposes only `comment`, `plan`, `decision`, `implementation_report` roles. Consider whether to expose new event kinds now or keep them backend-only for first slice.
|
||||
- `crates/yoi/src/ticket_cli.rs`
|
||||
- Direct CLI paths for comment/review/status/close; update only if new event API needs direct maintainer exposure.
|
||||
- `docs/development/work-items.md`
|
||||
- Update thread semantics if touched.
|
||||
|
||||
## Non-goals
|
||||
|
||||
- Implementing explicit `workflow_state` frontmatter fields; next ticket owns that.
|
||||
- Replacing Pod/session logs.
|
||||
- Capturing full Intake conversations in Ticket thread.
|
||||
- Rewriting all historical thread files.
|
||||
- Building scheduler/lease/queue behavior.
|
||||
- Panel layout changes.
|
||||
|
||||
## Validation
|
||||
|
||||
Run at least:
|
||||
|
||||
- `cargo test -p ticket thread` or targeted new thread event tests;
|
||||
- `cargo test -p ticket`;
|
||||
- `cargo test -p yoi ticket` if CLI/tool-visible behavior changes;
|
||||
- `cargo test -p pod ticket --lib` if Ticket tools change;
|
||||
- `cargo check --workspace --all-targets`;
|
||||
- `cargo fmt --check`;
|
||||
- `git diff --check`;
|
||||
- `cargo build -p yoi`;
|
||||
- `target/debug/yoi ticket doctor`.
|
||||
|
||||
Run `nix build .#yoi --no-link` if feasible.
|
||||
|
||||
## Completion report
|
||||
|
||||
Report:
|
||||
|
||||
- worktree path / branch;
|
||||
- commit hash;
|
||||
- new event kinds and metadata fields;
|
||||
- backend APIs added;
|
||||
- parser/doctor behavior;
|
||||
- tool/CLI/doc updates, if any;
|
||||
- historical compatibility behavior;
|
||||
- validation results;
|
||||
- whether `explicit-ticket-workflow-state` can proceed.
|
||||
@@ -1,102 +0,0 @@
|
||||
---
|
||||
id: 20260606-221301-typed-ticket-thread-event-log
|
||||
slug: typed-ticket-thread-event-log
|
||||
title: Typed Ticket thread event log for workflow state changes
|
||||
status: open
|
||||
kind: task
|
||||
priority: P1
|
||||
labels: [ticket, orchestration, state, audit]
|
||||
created_at: 2026-06-06T22:13:01Z
|
||||
updated_at: 2026-06-06T22:16:04Z
|
||||
assignee: null
|
||||
legacy_ticket: null
|
||||
---
|
||||
|
||||
## Background
|
||||
|
||||
The explicit workflow state design moves current Ticket workflow state into frontmatter, but frontmatter alone only records the current value. The system also needs a small append-only audit trail explaining why state changed and which actor changed it.
|
||||
|
||||
The current Ticket thread is too freeform to be a reliable workflow record. It tends to become a place for arbitrary comments and AI-generated prose, while still not clearly recording state transitions or Intake decisions.
|
||||
|
||||
## Goal
|
||||
|
||||
Make `thread.md` a concise typed event log for durable Ticket events, especially workflow state changes and Intake summaries, rather than a general conversation transcript.
|
||||
|
||||
## Authority split
|
||||
|
||||
- `item.md` frontmatter: current mechanical state authority.
|
||||
- `item.md` body: current human-readable Ticket snapshot: background, goal, requirements, non-goals, acceptance criteria.
|
||||
- `thread.md`: append-only typed event log explaining state transitions, important decisions, implementation reports, reviews, and close events.
|
||||
- Pod/session logs: full conversational/runtime transcript. Do not copy full Pod conversations into Ticket thread.
|
||||
|
||||
## Event model
|
||||
|
||||
Add or formalize typed thread events for at least:
|
||||
|
||||
```text
|
||||
create
|
||||
state_changed
|
||||
intake_summary
|
||||
decision
|
||||
implementation_report
|
||||
review
|
||||
close
|
||||
```
|
||||
|
||||
`comment` may remain for manual escape hatches if needed, but Orchestrator/Intake/panel workflow should not rely on freeform comments as the primary record.
|
||||
|
||||
## State transition logging
|
||||
|
||||
Every workflow state mutation should append a concise `state_changed` event containing at least:
|
||||
|
||||
```text
|
||||
from
|
||||
to
|
||||
actor
|
||||
reason
|
||||
summary or refs
|
||||
```
|
||||
|
||||
State transitions should be performed through backend APIs that update frontmatter and append the thread event as one logical mutation. Avoid separate call sites that can update frontmatter without an event or append an event without updating current state.
|
||||
|
||||
## Intake logging
|
||||
|
||||
Intake should not dump the full Intake Pod conversation into `thread.md`. When Intake materializes a Ticket or marks it `ready`, it should write a concise `intake_summary` event containing:
|
||||
|
||||
- accepted user intent;
|
||||
- important clarified decisions;
|
||||
- requirements / acceptance criteria summary;
|
||||
- known non-goals;
|
||||
- unresolved questions, if any.
|
||||
|
||||
The Ticket body should hold the current snapshot. The thread should hold the reason/history for how that snapshot became accepted.
|
||||
|
||||
## Constraints
|
||||
|
||||
- Keep events concise and bounded.
|
||||
- Do not persist hidden reasoning.
|
||||
- Do not paste raw transcripts by default.
|
||||
- Do not use thread events as the source of current workflow state; current state lives in frontmatter.
|
||||
- Do not store transient Pod activity as Ticket state.
|
||||
- Preserve existing historical thread records; do not mass-rewrite old history unless a migration explicitly requires it.
|
||||
|
||||
## Relationship to explicit workflow state
|
||||
|
||||
This ticket is a companion/prerequisite to `explicit-ticket-workflow-state`. That ticket defines the current-state fields and panel semantics. This ticket defines the audit/event-log mechanics so state transitions remain explainable without relying on noisy freeform thread prose.
|
||||
|
||||
## Non-goals
|
||||
|
||||
- Building a scheduler/lease system.
|
||||
- Replacing Pod/session logs.
|
||||
- Capturing full Intake conversations in Ticket records.
|
||||
- Rewriting all historical threads.
|
||||
- Changing public UI layout by itself.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- A typed event model exists for `state_changed` and `intake_summary` at minimum.
|
||||
- Workflow state changes have an API path that updates current state and appends a `state_changed` event together.
|
||||
- Intake-ready/materialization flow has a bounded `intake_summary` event path.
|
||||
- Panel/Orchestrator state changes do not rely on freeform comments for auditability.
|
||||
- Existing Ticket doctor/lint checks accept the new event types and reject malformed required fields where practical.
|
||||
- Documentation explains the split between current state, current Ticket snapshot, append-only thread events, and Pod/session transcripts.
|
||||
@@ -1,31 +0,0 @@
|
||||
<!-- event: create author: yoi ticket at: 2026-06-06T22:13:01Z -->
|
||||
|
||||
## Created
|
||||
|
||||
Created by LocalTicketBackend create.
|
||||
|
||||
---
|
||||
|
||||
<!-- event: plan author: hare at: 2026-06-06T22:14:29Z -->
|
||||
|
||||
## Plan
|
||||
|
||||
Created as a companion split from `explicit-ticket-workflow-state`.
|
||||
|
||||
This ticket owns making Ticket `thread.md` a concise typed append-only event log for workflow state transitions and Intake summaries, rather than a freeform transcript/comment sink. It should define/implement events such as `state_changed` and `intake_summary`, and provide backend APIs that keep frontmatter current state and thread transition events in sync.
|
||||
|
||||
|
||||
---
|
||||
|
||||
<!-- event: plan author: hare at: 2026-06-06T22:16:04Z -->
|
||||
|
||||
## Plan
|
||||
|
||||
Preflight result: `implementation-ready` as the foundational backend/API slice before `explicit-ticket-workflow-state`.
|
||||
|
||||
This ticket should formalize Ticket `thread.md` as a concise typed append-only event log by adding state-transition and Intake-summary event types/APIs while preserving existing historical thread compatibility. It should not add workflow_state frontmatter yet; that is the next ticket.
|
||||
|
||||
Detailed delegation intent is recorded in `artifacts/delegation-intent.md`.
|
||||
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user