Immutable Decisions: Option C Reconsidered

Output

You're Absolutely RightDecisions are immutable. Pivots are new decisions.
This changes everything about the sync concern.
The Event Sourcing Pattern
Decision Timeline (append-only)

t1: ○ claude decides: "Use SQLite for storage"
       id: dec-001
       status: made

t2: ● human reviews: marks dec-001 as reviewed
       (status update - but this IS immutable too!)
       (we can model as: reviewedAt timestamp added)

t3: ● human pivots: "Actually use JSONL"
       NEW decision: dec-002
       dec-002.supersedes: dec-001
       dec-001 stays as-is (historical record)

Result:
  dec-001: { status: "superseded", supersededBy: "dec-002" }
  dec-002: { status: "made", supersedes: "dec-001" }

Revised Option C: No Sync Needed
// On decision creation:
1. Append to gvdecisions.jsonl (source of truth)
2. Append summary to flow.decisions[] (denormalized)

// On pivot:
1. Append NEW decision to gvdecisions.jsonl
2. Append NEW summary to flow.decisions[]
3. Old decision untouched (immutable)
   Link via supersedes/supersededBy

No sync = no drift = no bugs

Wait, What About "reviewed" Status?
Option A: Status is mutable
  made → reviewed → documented
  ✗ Breaks immutability, needs sync

Option B: Status transitions are events ← Better
  Decision has: createdAt, reviewedAt?, documentedAt?
  Status is computed from timestamps:
    - reviewedAt null → "made"
    - reviewedAt set → "reviewed"
    - documentedAt set → "documented"
  ✓ Still append-only (just add timestamps)

Option C: Review is separate event ← Purest
  gvdecisions.jsonl: immutable decisions
  gvevents.jsonl: { type: "review", decisionId, at }
  ✓ Full event sourcing
  △ More complex

Practical Recommendation
interface gvDecision {
  id: string;
  flowId: string;
  turnId: string;
  
  // Core (immutable)
  madeBy: "claude" | "human";
  type: DecisionType;
  title: string;
  chosen: string;
  alternatives: string[];
  rationale: string;
  impact: "low" | "medium" | "high";
  
  // Timestamps (append-only)
  createdAt: Date;         // When made
  reviewedAt?: Date;       // When human acknowledged
  documentedAt?: Date;     // When exported to docs
  
  // Lineage (append-only)
  supersedes?: string;     // ID of decision this replaces
  supersededBy?: string;   // ID of decision that replaced this
}

// Computed status (not stored)
function getStatus(d: gvDecision): string {
  if (d.supersededBy) return "superseded";
  if (d.documentedAt) return "documented";
  if (d.reviewedAt) return "reviewed";
  return "made";
}

The "Sync" Was My MistakeI was thinking mutably. You caught it.
My mental model:
  Update status in gvdecisions.jsonl
  Must update denormalized copy in flow
  → Sync problem

Correct model:
  Append timestamp to gvdecisions.jsonl
  Denormalized copy in flow has same ID
  Status computed at read time
  → No sync needed
Revised RecommendationOption C (Hybrid) is now viable!

With immutable decisions + append-only timestamps:
gvdecisions.jsonl - full decision records
flow.decisions[] - summaries for fast flow reads
No sync because both are append-only
Status computed, not stored
This gives fast flow-scoped reads AND fast cross-flow queries. Best of both worlds, no downside.

Quick Actions

Original Request

No layout configured

Details

Type General

Status Completed

Scope vibetools

Tags gvshellgvhubdecisionsdata-model

Created 9 Jan 2026, 1:25 pm

Updated 9 Jan 2026, 1:25 pm

Timing

⏱️ 55.0s

0 tools

● TTFE 0% ● Thinking 100% ● Tools 0%

Created By claude

Raw Data

{
  "id": "ce48c062-2eda-4179-9b2f-44d38c876cd3",
  "type": "general",
  "status": "completed",
  "title": "Immutable Decisions: Option C Reconsidered",
  "description": "You're right - decisions are append-only, sync concern disappears",
  "context": {
    "output": "<div style=\"background:#1e1e1e;color:#e0e0e0;padding:20px;border-radius:8px;font-family:'Consolas','Monaco',monospace;\">\n<h2 style=\"font-family:sans-serif;color:#fff;margin:0 0 20px 0;\">You're Absolutely Right</h2>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:20px;border-left:4px solid #22c55e;\">\n<p style=\"margin:0;color:#22c55e;font-weight:bold;\">Decisions are immutable. Pivots are new decisions.</p>\n<p style=\"margin:8px 0 0 0;color:#e0e0e0;\">This changes everything about the sync concern.</p>\n</div>\n\n<h3 style=\"font-family:sans-serif;color:#fff;margin:0 0 12px 0;\">The Event Sourcing Pattern</h3>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<pre style=\"margin:0;line-height:1.8;color:#e0e0e0;font-size:13px;\">\n<span style=\"color:#c678dd;\">Decision Timeline (append-only)</span>\n\n<span style=\"color:#7f848e;\">t1:</span> <span style=\"color:#c678dd;\">○</span> claude decides: \"Use SQLite for storage\"\n       id: dec-001\n       status: <span style=\"color:#22c55e;\">made</span>\n\n<span style=\"color:#7f848e;\">t2:</span> <span style=\"color:#61afef;\">●</span> human reviews: marks dec-001 as <span style=\"color:#e5c07b;\">reviewed</span>\n       <span style=\"color:#7f848e;\">(status update - but this IS immutable too!)</span>\n       <span style=\"color:#7f848e;\">(we can model as: reviewedAt timestamp added)</span>\n\n<span style=\"color:#7f848e;\">t3:</span> <span style=\"color:#61afef;\">●</span> human pivots: \"Actually use JSONL\"\n       NEW decision: dec-002\n       dec-002.supersedes: dec-001\n       dec-001 stays as-is (historical record)\n\n<span style=\"color:#7f848e;\">Result:</span>\n  dec-001: { status: \"superseded\", supersededBy: \"dec-002\" }\n  dec-002: { status: \"made\", supersedes: \"dec-001\" }\n</pre>\n</div>\n\n<h3 style=\"font-family:sans-serif;color:#fff;margin:0 0 12px 0;\">Revised Option C: No Sync Needed</h3>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;border-left:4px solid #22c55e;\">\n<pre style=\"margin:0;line-height:1.6;color:#e0e0e0;font-size:12px;background:#1e1e1e;padding:12px;border-radius:4px;\">\n<span style=\"color:#7f848e;\">// On decision creation:</span>\n<span style=\"color:#c678dd;\">1.</span> Append to gvdecisions.jsonl <span style=\"color:#7f848e;\">(source of truth)</span>\n<span style=\"color:#c678dd;\">2.</span> Append summary to flow.decisions[] <span style=\"color:#7f848e;\">(denormalized)</span>\n\n<span style=\"color:#7f848e;\">// On pivot:</span>\n<span style=\"color:#c678dd;\">1.</span> Append NEW decision to gvdecisions.jsonl\n<span style=\"color:#c678dd;\">2.</span> Append NEW summary to flow.decisions[]\n<span style=\"color:#c678dd;\">3.</span> Old decision untouched <span style=\"color:#7f848e;\">(immutable)</span>\n   <span style=\"color:#7f848e;\">Link via supersedes/supersededBy</span>\n\n<span style=\"color:#22c55e;\">No sync = no drift = no bugs</span>\n</pre>\n</div>\n\n<h3 style=\"font-family:sans-serif;color:#fff;margin:0 0 12px 0;\">Wait, What About \"reviewed\" Status?</h3>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<pre style=\"margin:0;line-height:1.8;color:#e0e0e0;font-size:13px;\">\n<span style=\"color:#e5c07b;\">Option A: Status is mutable</span>\n  made → reviewed → documented\n  <span style=\"color:#f43f5e;\">✗ Breaks immutability, needs sync</span>\n\n<span style=\"color:#22c55e;\">Option B: Status transitions are events</span> <span style=\"color:#22c55e;\">← Better</span>\n  Decision has: createdAt, reviewedAt?, documentedAt?\n  Status is <span style=\"color:#c678dd;\">computed</span> from timestamps:\n    - reviewedAt null → \"made\"\n    - reviewedAt set → \"reviewed\"\n    - documentedAt set → \"documented\"\n  <span style=\"color:#22c55e;\">✓ Still append-only (just add timestamps)</span>\n\n<span style=\"color:#22c55e;\">Option C: Review is separate event</span> <span style=\"color:#22c55e;\">← Purest</span>\n  gvdecisions.jsonl: immutable decisions\n  gvevents.jsonl: { type: \"review\", decisionId, at }\n  <span style=\"color:#22c55e;\">✓ Full event sourcing</span>\n  <span style=\"color:#e5c07b;\">△ More complex</span>\n</pre>\n</div>\n\n<h3 style=\"font-family:sans-serif;color:#fff;margin:0 0 12px 0;\">Practical Recommendation</h3>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<pre style=\"margin:0;line-height:1.6;color:#e0e0e0;font-size:12px;background:#1e1e1e;padding:12px;border-radius:4px;\">\n<span style=\"color:#c678dd;\">interface</span> <span style=\"color:#e5c07b;\">gvDecision</span> {\n  id: <span style=\"color:#98c379;\">string</span>;\n  flowId: <span style=\"color:#98c379;\">string</span>;\n  turnId: <span style=\"color:#98c379;\">string</span>;\n  \n  <span style=\"color:#7f848e;\">// Core (immutable)</span>\n  madeBy: <span style=\"color:#98c379;\">\"claude\"</span> | <span style=\"color:#98c379;\">\"human\"</span>;\n  type: <span style=\"color:#e5c07b;\">DecisionType</span>;\n  title: <span style=\"color:#98c379;\">string</span>;\n  chosen: <span style=\"color:#98c379;\">string</span>;\n  alternatives: <span style=\"color:#98c379;\">string</span>[];\n  rationale: <span style=\"color:#98c379;\">string</span>;\n  impact: <span style=\"color:#98c379;\">\"low\"</span> | <span style=\"color:#98c379;\">\"medium\"</span> | <span style=\"color:#98c379;\">\"high\"</span>;\n  \n  <span style=\"color:#7f848e;\">// Timestamps (append-only)</span>\n  createdAt: <span style=\"color:#98c379;\">Date</span>;         <span style=\"color:#7f848e;\">// When made</span>\n  reviewedAt?: <span style=\"color:#98c379;\">Date</span>;       <span style=\"color:#7f848e;\">// When human acknowledged</span>\n  documentedAt?: <span style=\"color:#98c379;\">Date</span>;     <span style=\"color:#7f848e;\">// When exported to docs</span>\n  \n  <span style=\"color:#7f848e;\">// Lineage (append-only)</span>\n  supersedes?: <span style=\"color:#98c379;\">string</span>;     <span style=\"color:#7f848e;\">// ID of decision this replaces</span>\n  supersededBy?: <span style=\"color:#98c379;\">string</span>;   <span style=\"color:#7f848e;\">// ID of decision that replaced this</span>\n}\n\n<span style=\"color:#7f848e;\">// Computed status (not stored)</span>\n<span style=\"color:#c678dd;\">function</span> <span style=\"color:#61afef;\">getStatus</span>(d: gvDecision): <span style=\"color:#98c379;\">string</span> {\n  <span style=\"color:#c678dd;\">if</span> (d.supersededBy) <span style=\"color:#c678dd;\">return</span> <span style=\"color:#98c379;\">\"superseded\"</span>;\n  <span style=\"color:#c678dd;\">if</span> (d.documentedAt) <span style=\"color:#c678dd;\">return</span> <span style=\"color:#98c379;\">\"documented\"</span>;\n  <span style=\"color:#c678dd;\">if</span> (d.reviewedAt) <span style=\"color:#c678dd;\">return</span> <span style=\"color:#98c379;\">\"reviewed\"</span>;\n  <span style=\"color:#c678dd;\">return</span> <span style=\"color:#98c379;\">\"made\"</span>;\n}\n</pre>\n</div>\n\n<h3 style=\"font-family:sans-serif;color:#fff;margin:0 0 12px 0;\">The \"Sync\" Was My Mistake</h3>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:20px;border-left:4px solid #c678dd;\">\n<p style=\"margin:0 0 12px 0;color:#c678dd;font-weight:bold;\">I was thinking mutably. You caught it.</p>\n<pre style=\"margin:0;line-height:1.8;color:#e0e0e0;font-size:13px;\">\n<span style=\"color:#7f848e;\">My mental model:</span>\n  Update status in gvdecisions.jsonl\n  Must update denormalized copy in flow\n  <span style=\"color:#f43f5e;\">→ Sync problem</span>\n\n<span style=\"color:#7f848e;\">Correct model:</span>\n  Append timestamp to gvdecisions.jsonl\n  Denormalized copy in flow has same ID\n  Status computed at read time\n  <span style=\"color:#22c55e;\">→ No sync needed</span>\n</pre>\n</div>\n\n<hr style=\"border:none;border-top:1px solid #3d3d3d;margin:0 0 20px 0;\">\n\n<h3 style=\"font-family:sans-serif;color:#fff;margin:0 0 12px 0;\">Revised Recommendation</h3>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;border-left:4px solid #22c55e;\">\n<p style=\"margin:0;color:#22c55e;font-weight:bold;\">Option C (Hybrid) is now viable!</p>\n<p style=\"margin:12px 0 0 0;color:#e0e0e0;\">\nWith immutable decisions + append-only timestamps:\n</p>\n<ul style=\"margin:8px 0 0 0;padding-left:20px;color:#e0e0e0;\">\n<li><strong>gvdecisions.jsonl</strong> - full decision records</li>\n<li><strong>flow.decisions[]</strong> - summaries for fast flow reads</li>\n<li>No sync because both are append-only</li>\n<li>Status computed, not stored</li>\n</ul>\n<p style=\"margin:12px 0 0 0;color:#7f848e;font-size:13px;\">This gives fast flow-scoped reads AND fast cross-flow queries. Best of both worlds, no downside.</p>\n</div>\n\n</div>",
    "requestedAt": "2026-01-09T02:48:00.000Z",
    "requestId": "53861885-55b2-45c8-99f7-5f0e1f5fd641",
    "choices": [
      {
        "label": "Use hybrid (Option C)",
        "value": "Implement hybrid approach - top-level gvdecisions.jsonl plus denormalized summaries in flows, both append-only",
        "primary": true
      },
      {
        "label": "Keep it simple (Option B)",
        "value": "Stick with just top-level gvdecisions.jsonl, skip denormalization for now"
      },
      {
        "label": "Design the full schema",
        "value": "Write out the complete gvDecision, gvFlow, gvTurn, gvSession schemas before implementing"
      }
    ],
    "turnTiming": {
      "totalMs": 54982,
      "ttfeMs": 46,
      "thinkingMs": 54936,
      "toolExecutionMs": 0,
      "toolCallCount": 0,
      "thinkingPct": 100,
      "toolsPct": 0,
      "ttfePct": 0
    }
  },
  "createdBy": "claude",
  "createdAt": "2026-01-09T03:25:53.264Z",
  "updatedAt": "2026-01-09T03:25:59.039Z",
  "requestId": "53861885-55b2-45c8-99f7-5f0e1f5fd641",
  "scope": "vibetools",
  "tags": [
    "gvshell",
    "gvhub",
    "decisions",
    "data-model"
  ],
  "targetUser": "claude"
}