🏗️ Architecture: How should the manifest schema evolve given that v3.0 has 13...

Date: 2026-03-27
Time: 14:28:28 UTC
Session: gspace2-0
Agent: documentation
Confidence: 93%
Status: ✅ Documented

📋 Decision Context

Question:

How should the manifest schema evolve given that v3.0 has 13/25 fields with 0% usage across 217 manifests?

Task: Smart Session System v13.0 — schema overhaul

🎯 Decision Made

Chosen:

Schema v13.0: strip all unused fields, promote actually-used fields from nested wrappers to root level, add lifecycle fields (archivedAt, completedAt), restructure into stats/context/handoff groups. Migration is lazy — read both v12.0 and v13.0, migrate on update, no bulk rewrite.

Options Considered:

1. A) Keep v3.0 schema and start populating empty fields
2. B) Strip to v13.0 matching reality + add lifecycle fields (CHOSEN)
3. C) Abandon manifests entirely — use MongoDB as sole store
4. D) Bulk-migrate all 217 manifests in one operation

💭 Reasoning

Empirical analysis: 217 manifests, 13 fields at 0% usage (context, progress, outputs, handoff, metadata, parentSession, etc.), decisions array in only 1/217 manifests (0.5%). The schema was aspirational, not operational. The 'legacy' wrapper around workspace was universal but added indirection for no benefit. v13.0 aligns schema with reality: workspace at root, stats object for counters, context.gitBranch promoted from buried-in-subSessions to top-level (critical for resolution), handoff only populated on completion. Lazy migration avoids risky bulk rewrites — v12.0 manifests are unpacked on read and rewritten as v13.0 when next updated.

📁 Files Involved

• sessions/schemas/session-manifest.schema.json
• sessions/schemas/session-manifest.template.json
• MCP/mcp-gograb-ai/src/storage/docs-data-integration.ts

🔗 Related

• Decision ID: dev_1774621708755_ndh8rhs
• Session: 0
• Workspace: gspace2

Auto-generated by MCP Smart Consolidation