spec-kitty / spec-kitty/spec-kitty

Required-on-close structured Op debrief — optional field + executor-seam enforcement + graduated depth

Open
#2,685 1 comment 0 reactions 0 assignees View on GitHub
enhancement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.