<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/2.x/2026-02-09-1-canonical-wp-status-model/">
  <id>https://docs.spec-kitty.ai/adr/2.x/2026-02-09-1-canonical-wp-status-model/</id>
  <title>Canonical WP Status Model Using Append-Only JSONL Event Log</title>
  <updated>2026-02-09T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/2.x/2026-02-09-1-canonical-wp-status-model/"/>
  <summary>Replaces five mutable status artifacts with one append-only JSONL event log and a derived snapshot, giving work package state a single, replayable authority.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Work package and feature status in Spec Kitty is spread across multiple mutable artifacts: &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tasks.md&lt;/code&gt; checkboxes, WP front-matter &lt;code dir=&quot;auto&quot;&gt;lane&lt;/code&gt; fields, &lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt; workspace context, and target-repo implementation state. This distributed authority causes observable failure modes:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Phantom state&lt;/strong&gt;: Lane updates written to non-authoritative artifacts appear real but aren’t canonical.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Split-brain&lt;/strong&gt;: Planning artifacts say one thing while implementation evidence says another.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Monotonic conflict resolution&lt;/strong&gt;: “Most done wins” can override a valid review rollback.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Unauditable force transitions&lt;/strong&gt;: Status can be changed without durable record of who, when, or why.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Workspace residue&lt;/strong&gt;: Stale worktree contexts cause phantom ownership and noisy operations.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;The system needs a single canonical, auditable source of truth for WP and feature status that supports concurrent multi-agent work, offline operation, and deterministic merge.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Auditability&lt;/strong&gt; — Every status change must be recorded with actor, timestamp, and context&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Git-native merges&lt;/strong&gt; — Concurrent branches must merge without manual conflict resolution&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Offline-first&lt;/strong&gt; — Must work entirely in git with no network dependency&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Replayability&lt;/strong&gt; — Must be able to reconstruct state at any historical point&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Multi-agent safety&lt;/strong&gt; — Multiple human and AI agents must be able to work concurrently&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Option 1:&lt;/strong&gt; Front-matter / tasks.md canonical (current implicit model)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 2:&lt;/strong&gt; Mutable snapshot-only (&lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt;) canonical&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 3:&lt;/strong&gt; SQLite file in git&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 4:&lt;/strong&gt; External database canonical (SaaS Postgres)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 5:&lt;/strong&gt; Append-only JSONL event log with derived snapshot&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option:&lt;/strong&gt; “Option 5: Append-only JSONL event log with derived snapshot”, because it provides git-friendly merges (line-append), full audit trail, event replay, offline capability, and deterministic merge semantics for concurrent multi-agent work.&lt;/p&gt;
&lt;h3 id=&quot;implementation&quot;&gt;Implementation&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Canonical state&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&amp;#x3C;feature&gt;/status.events.jsonl&lt;/code&gt; — per-feature append-only log&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Derived state&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&amp;#x3C;feature&gt;/status.json&lt;/code&gt; — materialized snapshot (regeneratable)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Generated views&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;tasks.md&lt;/code&gt; status sections and WP front-matter &lt;code dir=&quot;auto&quot;&gt;lane&lt;/code&gt; field are generated from the snapshot, never edited as authority&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Read/write contract&lt;/strong&gt;: All state changes append to the event log; a deterministic reducer materializes &lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Git-friendly — appending lines to JSONL rarely causes merge conflicts&lt;/li&gt;
&lt;li&gt;Full audit trail — every status change is an immutable record with actor, timestamp, and context&lt;/li&gt;
&lt;li&gt;Replayable state — can reconstruct status at any historical point&lt;/li&gt;
&lt;li&gt;Offline-capable — entire system works in git with no network dependency&lt;/li&gt;
&lt;li&gt;Foundation for deterministic merge (see ADR 2026-02-09-3)&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;No direct querying without materializing the snapshot first&lt;/li&gt;
&lt;li&gt;JSONL file grows unbounded without compaction strategy&lt;/li&gt;
&lt;li&gt;Extra tooling required — reducer, materializer, and validator must be built&lt;/li&gt;
&lt;li&gt;Migration complexity — existing WP status must be bootstrapped into event log format&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Extends the event-sourcing principle from the SaaS event log to local git-based project status tracking using JSONL instead of a database&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;status emit&lt;/code&gt; automatically materializes after each event, so reads are always fast&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;status validate&lt;/code&gt; CI check confirms materialized &lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt; matches reducer output, catching any drift&lt;/li&gt;
&lt;li&gt;Phased migration (PRD Section 14) reduces risk: immediate hardening → dual write → read cutover → cross-repo native&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;front-matter--tasksmd-canonical-current-model&quot;&gt;Front-matter / tasks.md canonical (current model)&lt;/h3&gt;
&lt;p&gt;Continue using WP front-matter &lt;code dir=&quot;auto&quot;&gt;lane&lt;/code&gt; fields and tasks.md checkboxes as the source of truth.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Already exists — zero migration cost&lt;/li&gt;
&lt;li&gt;Human-readable and editable in any text editor&lt;/li&gt;
&lt;li&gt;Familiar to all current users&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;No audit trail — status changes overwrite previous values&lt;/li&gt;
&lt;li&gt;Merge conflicts on concurrent edits to the same YAML front-matter block&lt;/li&gt;
&lt;li&gt;No transition validation — any state can be written directly&lt;/li&gt;
&lt;li&gt;Multiple artifacts can disagree with no reconciliation mechanism&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;mutable-snapshot-only-statusjson&quot;&gt;Mutable snapshot-only (&lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt;)&lt;/h3&gt;
&lt;p&gt;Replace front-matter with a single &lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt; file per feature as authoritative source.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Structured and queryable (JSON)&lt;/li&gt;
&lt;li&gt;Single file replaces multiple scattered fields&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;No history — current state only, previous states lost on write&lt;/li&gt;
&lt;li&gt;Merge conflicts on concurrent writes (entire JSON object is one blob)&lt;/li&gt;
&lt;li&gt;No audit trail for forced transitions or rollbacks&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;sqlite-file-in-git&quot;&gt;SQLite file in git&lt;/h3&gt;
&lt;p&gt;Store status in a SQLite database file committed to git.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Powerful querying (SQL)&lt;/li&gt;
&lt;li&gt;Transactional writes (ACID guarantees)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Binary diffs in git — poor merge semantics under concurrent writers&lt;/li&gt;
&lt;li&gt;Reduced review clarity — reviewers cannot see status changes in pull request diffs&lt;/li&gt;
&lt;li&gt;Page-level conflicts require manual resolution or custom merge drivers&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;external-database-canonical&quot;&gt;External database canonical&lt;/h3&gt;
&lt;p&gt;Store status in the SaaS platform’s Postgres instance.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Powerful querying and real-time access&lt;/li&gt;
&lt;li&gt;Native concurrent write support&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Requires centralized service — violates offline-first principle&lt;/li&gt;
&lt;li&gt;Contradicts non-goal: “Not replacing git with an online control plane”&lt;/li&gt;
&lt;li&gt;CLI cannot function without network access&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Related ADRs:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;ADR 2026-02-09-2 (WP Lifecycle State Machine) — consumes events from this log&lt;/li&gt;
&lt;li&gt;ADR 2026-02-09-3 (Event-Log Merge Semantics) — operates on this log&lt;/li&gt;
&lt;li&gt;ADR 2026-02-09-4 (Cross-Repo Evidence Completion) — extends this log with evidence payloads&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;References:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Martin Fowler: Event Sourcing — &lt;a href=&quot;https://martinfowler.com/eaaDev/EventSourcing.html&quot;&gt;https://martinfowler.com/eaaDev/EventSourcing.html&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;JSONL Specification — &lt;a href=&quot;https://jsonlines.org/&quot;&gt;https://jsonlines.org/&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;PRD: Feature Status State Model Remediation (Sections 2, 3, 5, 6, 15)&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
