ticket: use base32 project record ids
This commit is contained in:
@@ -0,0 +1,102 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,95 @@
|
||||
---
|
||||
title: "Typed Ticket thread event log for workflow state changes"
|
||||
state: "closed"
|
||||
created_at: "2026-06-06T22:13:01Z"
|
||||
updated_at: "2026-06-06T22:48:18Z"
|
||||
---
|
||||
|
||||
## 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.
|
||||
@@ -0,0 +1,35 @@
|
||||
Implemented typed Ticket thread event logging for workflow audit events.
|
||||
|
||||
Changes:
|
||||
- Added event kinds:
|
||||
- `state_changed`
|
||||
- `intake_summary`
|
||||
- Preserved existing event kinds and historical compatibility.
|
||||
- Added typed backend data/API:
|
||||
- `TicketStateChange`
|
||||
- `TicketIntakeSummary`
|
||||
- `TicketBackend::add_state_changed(...)`
|
||||
- `TicketBackend::add_intake_summary(...)`
|
||||
- `TicketBackend::set_state_field(...)` as a frontmatter-field update plus `state_changed` event helper for the next workflow-state slice.
|
||||
- Parser now understands quoted event attributes and exposes typed metadata such as `from`, `to`, `reason`, `state_field`, and full attributes.
|
||||
- Doctor validates required fields for `state_changed` and `intake_summary` where practical.
|
||||
- `TicketShow` tool output includes new event metadata fields/attributes.
|
||||
- Thread event append now prevalidates and prerenders metadata before opening/appending `thread.md`, preventing failed appends from corrupting the log.
|
||||
- Create event author validation happens before writing a ticket record.
|
||||
- Documentation now describes `thread.md` as append-only audit history, not current-state authority.
|
||||
|
||||
Validation after merge:
|
||||
- `cargo test -p ticket thread`
|
||||
- `cargo test -p ticket`
|
||||
- `cargo test -p yoi ticket`
|
||||
- `cargo test -p pod ticket --lib`
|
||||
- `cargo check --workspace --all-targets`
|
||||
- `cargo fmt --check`
|
||||
- `git diff --check HEAD~1..HEAD`
|
||||
- `cargo build -p yoi`
|
||||
- `target/debug/yoi ticket doctor`
|
||||
- `nix build .#yoi --no-link --print-out-paths`
|
||||
|
||||
External review approved after fixing prevalidation/partial-append safety.
|
||||
|
||||
`explicit-ticket-workflow-state` can proceed next.
|
||||
@@ -0,0 +1,91 @@
|
||||
<!-- 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`.
|
||||
|
||||
|
||||
---
|
||||
|
||||
<!-- event: review author: hare at: 2026-06-06T22:48:18Z status: approve -->
|
||||
|
||||
## Review: approve
|
||||
|
||||
External reviewer approved the implementation after one requested-changes cycle.
|
||||
|
||||
Review summary:
|
||||
- `state_changed` and `intake_summary` are typed event kinds.
|
||||
- Existing event kinds and historical compatibility are preserved.
|
||||
- Thread event metadata is prevalidated/prerendered before append, so failed appends do not corrupt `thread.md`.
|
||||
- Create event author validation happens before writing a ticket record.
|
||||
- Parser/doctor understand the new event kinds and validate required fields where practical.
|
||||
- No premature `workflow_state` authority or scheduler/state-machine behavior was introduced.
|
||||
|
||||
|
||||
---
|
||||
|
||||
<!-- event: close author: hare at: 2026-06-06T22:48:18Z status: closed -->
|
||||
|
||||
## Closed
|
||||
|
||||
Implemented typed Ticket thread event logging for workflow audit events.
|
||||
|
||||
Changes:
|
||||
- Added event kinds:
|
||||
- `state_changed`
|
||||
- `intake_summary`
|
||||
- Preserved existing event kinds and historical compatibility.
|
||||
- Added typed backend data/API:
|
||||
- `TicketStateChange`
|
||||
- `TicketIntakeSummary`
|
||||
- `TicketBackend::add_state_changed(...)`
|
||||
- `TicketBackend::add_intake_summary(...)`
|
||||
- `TicketBackend::set_state_field(...)` as a frontmatter-field update plus `state_changed` event helper for the next workflow-state slice.
|
||||
- Parser now understands quoted event attributes and exposes typed metadata such as `from`, `to`, `reason`, `state_field`, and full attributes.
|
||||
- Doctor validates required fields for `state_changed` and `intake_summary` where practical.
|
||||
- `TicketShow` tool output includes new event metadata fields/attributes.
|
||||
- Thread event append now prevalidates and prerenders metadata before opening/appending `thread.md`, preventing failed appends from corrupting the log.
|
||||
- Create event author validation happens before writing a ticket record.
|
||||
- Documentation now describes `thread.md` as append-only audit history, not current-state authority.
|
||||
|
||||
Validation after merge:
|
||||
- `cargo test -p ticket thread`
|
||||
- `cargo test -p ticket`
|
||||
- `cargo test -p yoi ticket`
|
||||
- `cargo test -p pod ticket --lib`
|
||||
- `cargo check --workspace --all-targets`
|
||||
- `cargo fmt --check`
|
||||
- `git diff --check HEAD~1..HEAD`
|
||||
- `cargo build -p yoi`
|
||||
- `target/debug/yoi ticket doctor`
|
||||
- `nix build .#yoi --no-link --print-out-paths`
|
||||
|
||||
External review approved after fixing prevalidation/partial-append safety.
|
||||
|
||||
`explicit-ticket-workflow-state` can proceed next.
|
||||
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user