spec-kitty / spec-kitty/spec-kitty
WP-metadata authority split: static design-intent stays frontmatter-canonical; dynamic runtime state (incl. agent/shell_pid/history/reviews) retires to event-log/invocation authority (generalize the lane retirement)
- Dominant language
- Python
- Stars
- 1.6k
- Forks
- 165
- Avg merge
- 14h 52m
- Merged PRs (30d)
- 303
Description
## Question (operator)
Given the substantial planning + status + topology metadata work this cycle — the MissionTopology SSOT (stored `topology` in `meta.json`), the coordination/primary surface-coherence fixes (#2087/#2091, merged in PR #2089), the mid8 identity work (#1918/#2091/#2090), and the residue-authority convergence (#1887/#2084/#2088) — should the **WP-metadata section** (the per-WP frontmatter: `owned_files`, `dependencies`, `execution_mode`, `authoritative_surface`, `requirement_refs`, lane assignment, `create_intent`, plus the `tasks.md` index/lane tables) be **reworked now to ensure full alignment** with that planning/status/topology metadata model, rather than continuing to drift?
## Why now
The WP-metadata and the mission/planning metadata (`meta.json` topology/mid8, status events, the surface resolvers) are evolving on parallel tracks. A post-tasks adversarial review of the active mission `single-authority-topology-cleanup-01KVRJ6P` surfaced concrete coherence drift:
- A WP whose `dependencies` in frontmatter disagreed with the `tasks.md` lane table.
- Same-lane `shared_owned_files` semantics that the ownership validator only recently learned to honour (#2088).
- `authoritative_surface` values in WP frontmatter that predate the surface-resolver SSOT (#2090) and may no longer map correctly.
These are symptoms of the two metadata surfaces not sharing one authority. Fixing them ad-hoc in each mission is more expensive than resolving the structural gap once.
## Scope of the research (what to answer)
1. **(a) Catalogue** — enumerate current WP-metadata fields (`owned_files`, `dependencies`, `execution_mode`, `authoritative_surface`, `requirement_refs`, lane assignment, `create_intent`, `tasks.md` index/lane tables); for each field: where it is read, where it is written, and which CLI commands consume it (`finalize-tasks`, `implement`, `review`, `merge`, `status`).
2. **(b) Identify drift** — compare each WP-metadata field against mission/planning/status metadata (`meta.json` topology, `mid8`, status event log, surface resolvers); mark single-source-of-truth gaps, duplications, and silent derivations.
3. **(c) Rework decision** — based on (a)+(b), recommend one of:
- **Rework now**: unify onto one metadata authority / derive WP-metadata from topology+planning model where possible; estimate scope.
- **Rework later**: document the structural gap + defer with a tracking ticket.
- **No rework**: the duplication is intentional (local WP-scope vs mission-scope concerns) — document why.
4. **(d) Epic placement** — does WP-metadata alignment belong inside the write-surface coherence epic (#1716) or stand as a sibling planning-infrastructure concern?
## Deliverable
A short **findings doc** (not an implementation) plus a **recommendation** (rework-now / rework-later / no-rework) with supporting rationale. The deliverable is input for the next planning cycle, not a code change.
## Cross-references
- **Epic**: #1716 write-surface / topology coherence — relate; let the maintainer decide if this is a child or a sibling planning-infrastructure concern.
- **resolve_target SSOT**: #2090 — does WP-metadata alignment depend on or extend that work?
- **Active mission**: #2070 single-authority-topology-cleanup — the mission where drift was first observed post-tasks.
- **Surface-resolver convergence**: PR #2089 (coordination/primary fix), #2088 (ownership validator), #2087/#2091 (mid8 identity).
## Discovery
Surfaced by operator question during the post-tasks adversarial review of the active mission `single-authority-topology-cleanup-01KVRJ6P`, 2026-06-23.
---
*Filed by Planner Priti (profile: `planner-priti`) under Directive 003 — Decision Documentation Requirement: planning and prioritisation rationale documented for traceability.*
Contributor guide
Research direction
Trace the WP frontmatter fields, tasks.md index and lane tables, meta.json topology and mid8 data, status event log, and surface resolvers. Check how finalize-tasks, implement, review, merge, and status read or write each surface. Done means a findings document cataloguing authority and drift, a rework-now/later/no-rework recommendation with rationale, and a placement recommendation for epic #1716.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- developer-experience, documentation, tooling
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 45/100