spec-kitty / spec-kitty/spec-kitty
runtime-state cutover — post-landing follow-ups (from PR #2848)
- Dominant language
- Python
- Stars
- 1.6k
- Forks
- 165
- Avg merge
- 14h 52m
- Merged PRs (30d)
- 303
Description
Surfaced by the 4-lens adversarial landing squad on **PR #2848** (runtime-state corpus cutover, #2816). None were must-folds; the MAJOR data-recovery fix and the stale-comment sweep landed in the PR. These are the remaining non-blocking items.
### 1. Idempotency has an unenforced identity-ordering precondition (architect-alphonso)
`backfill_runtime_state.py` namespaces seed IDs on `mission_id | wp_id | field`, falling back to the directory slug when no `mission_id` is minted. If runtime-state backfill runs **before** `backfill-identity` mints a `mission_id`, a re-run after minting recomputes different seed IDs → the idempotency skip misses → duplicate runtime seeds (harmless payload, broken byte-stability). The shipped corpus already carries `mission_id`, so this PR's data is unaffected. Fix: require a minted `mission_id` (fail-closed) before seeding, or document/enforce the "identity before runtime" ordering.
### 2. FR-011 — remove the inert `WPMetadata` runtime fields + tighten the #2093 detector (paula-patterns)
Retired runtime fields (`agent`, `assignee`, `shell_pid(_created_at)`, `tracker_refs`, `review_status`, `review_feedback`) are still declared on `WPMetadata` (needed today by the backfill legacy reader, C-010). No live code reads them as authority, but the surface remains, and the #2093 attribute-access detector only catches the **inline** `read_wp_frontmatter(...).field` form — a two-statement `m, _ = read_wp_frontmatter(f); m.agent` would slip past. Once the migration read-path no longer needs the fields (FR-011), remove them and extend the detector to the two-statement bind form. Relates #1059.
### 3. Rename `_persist_review_artifact_override` (architect-alphonso)
Behavior is fully event-sourced (emits `InnerStateChanged`), but the name still says "persist … override" (the old frontmatter-stamp verb). Rename to `_emit_review_override` for D-044 unification clarity.
### 4. One stale flag docstring missed by the comment sweep
`src/specify_cli/status/reducer.py:385` — `wp_snapshot_state` docstring still says "the phase-1 dual-write flag gating stays at each call site" (no call site gates on a flag anymore). Reword to the unconditional-snapshot framing.
Relates: #2848, #2816, #1619 (runtime/state overhaul).
Contributor guide
Research direction
Start with backfill_runtime_state.py and the backfill-identity ordering, then inspect the WPMetadata legacy reader and the #2093 detector before changing the retired fields. Review _persist_review_artifact_override and src/specify_cli/status/reducer.py:385 for the naming and docstring follow-ups. Done means the ordering is enforced or documented, inert fields and detector coverage are resolved, the helper is renamed, and the stale wording is removed.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- cli, tooling
- Issue type
- Refactor
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100