spec-kitty / spec-kitty/spec-kitty
Required-on-close structured Op debrief — optional field + executor-seam enforcement + graduated depth
- Dominant language
- Python
- Stars
- 1.6k
- Forks
- 165
- Avg merge
- 14h 22m
- Merged PRs (30d)
- 343
Description
**Parent:** #2400 (native sub-issue, sibling of #2399). **Independent — ships now.**
## What
Make an Op record persist **why/what** on close: attach an optional structured `OpDebrief` to the Op-completed record and enforce required-presence with `mode_of_work`-graduated depth at the write seam.
- **Optional on the model (read path).** Add `debrief` as an **optional** field on `OpCompletedEvent`. A required field would reclassify every existing `kitty-ops/*.jsonl` completed line as `LegacyRecordError` on read (BLOCKER **B2**) — keeping it optional on the model preserves historical read-back.
- **Required + graduated at the emission seam.** Enforce required-presence and graduated depth at **`executor.complete_invocation`**, which already reads the started `mode_of_work` via `_read_started_mode()`. The graduated-depth validator **cannot** live on a `model_validator` of the completed model: `mode_of_work` lives on `OpStartedEvent`, not `OpCompletedEvent`, so a completed-model validator literally cannot read it and would fire on every historical read (BLOCKER **B1**). "Required on close" is preserved — presence is still mandatory, just enforced at the write seam.
## Why
Closes the **"Ops persist why/what"** gap. Today the Op record shape is frozen (`invocation/record.py`, schema v2) and carries no scope/intent/debrief. An optional field is a clean **field-extension under ADR 2026-06-11-1**, respecting `MinimalViableTrailPolicy` (opt-in Tier-2, C-005 no-parallel-primitive). It attaches to **#2400** (metadata & profile authority) as a record-shape extension — sibling in shape to #2399's invocation-context enforcement — not a new epic.
## Scope
- Add optional `OpDebrief` to `OpCompletedEvent`; `parse_op_event` continues to accept historical lines with no `debrief`.
- Enforce presence + `mode_of_work`-graduated depth at `executor.complete_invocation`.
- No Op-record migration required (optional on the model by construction).
## Sequencing
**Independent** of the runtime-state eviction mission and the WP-schema flip. The three squad reviewers agree this is a clean, low-risk slice to carve out and ship first. Grounded in `wp-op-schema-proposal.md` Part 4 (B1/B2, "Op debrief — LANDABLE on its own").
Contributor guide
Research direction
Start with invocation/record.py and the OpCompletedEvent shape, then trace executor.complete_invocation, including _read_started_mode() and parse_op_event. Review wp-op-schema-proposal.md Part 4 for the B1/B2 constraints. Done means historical completed lines still parse, while new completion writes require the structured debrief with depth based on mode_of_work.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- backend
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 58/100