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)

Open
#2,093 8 comments 0 reactions 0 assignees View on GitHub
enhancement priority:P1 reliability workflow
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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.