New Capability: Unified Canonical Architecture

← Back to Capability Reports 2026-04-13

New Capability: Unified Canonical Architecture

Date: April 13, 2026 Origin: April 3 eight-agent audit revealed 70/71 presentation mismatches, 66/70 framework book mismatches, and 77 logos invisible to agents. Director couldn't find a show logo during live setup. Every new piece of content created was adding drift because no canonical source enforced consistency. Impact: Every agent and every human can find the right asset, methodology content, or documentation in one query. 24 entity types across 4 Unified Views, 10 canonical query tools, 52/52 methodology entities aligned across 5 systems. Zero hardcoded methodology content in the codebase.

What Was Built

The Unified Canonical Architecture is the data backbone for the entire Value-First operations system. It establishes one answer for where everything lives across 16 systems (Sanity CMS, Content Vault, HubSpot, Obsidian, filesystem, Google Drive, Mux, and more). Before UCA, agents guessed at file paths, presentations hardcoded methodology content that drifted from canonical articles, and 77 logos existed on disk that no agent could find.

The architecture follows a 9-layer build: inventory everything (Layer 1), design the data model through the Four Unified Views (Layer 2), map storage with write ownership per system (Layer 3), implement schemas and populate records (Layer 4), build query interfaces (Layer 5), wire consumers (Layer 6), clean up hardcoded sources (Layer 7), validate end-to-end (Layer 8), and design drift detection (Layer 9). All 9 layers are complete.

The system is designed from the decisions it serves, not from the inventory of what exists. Every entity earns its place through one of the Four Unified Views: Customer Health, Company Health, Context Health, or Community Health. An entity that doesn't help someone see a customer more clearly, understand the flow of value more honestly, access context at a decision point, or enable the team more effectively doesn't belong in the model.

Infrastructure Changes

Change Before After
Methodology content Hardcoded in 23+ TypeScript files, 4 divergent sources Canonical in Sanity CMS, queried at build time via methodology.ts
Content Vault 18 tables, ~2,500 records 42 tables, ~3,100 records (incl. 51 projects, 22 assets, 52 methodology)
Canonical query tools 0 10 (show-query.js, episode-query.js, article-query.js, friend-query.js, methodology-query.js, organization-query.js, customer-health-query.js, company-health-query.js, project-query.js, unified-audit.js)
Data model Undefined 24 entity types across 4 Unified Views, system-independent
Write ownership Ad hoc 12 systems, 12 designated write agents (Ledger, Canon, Vault, Scrivener, etc.)
Obsidian knowledge graph 58 notes, no operational connection 87 notes, standardized frontmatter, cross-referenced to Vault/Sanity/monorepo
Website methodology surfaces Hardcoded inline arrays in 19+ components Canonical imports from Sanity queries or shared sync modules
Show data in components Hardcoded arrays Sanity getActiveShows() queries
Sanity methodology schemas trap, valuePathStage, unifiedGoal, frameworkConcept, valueReality + coreBelief (5 documents created)
Website routes No Core Beliefs or Three-Org pages /learn/foundation/core-beliefs/ (index + detail) + /learn/foundation/three-org/
Cross-system alignment 24/52 entities at 5/5 (46%) 52/52 entities at 5/5 (100%)
Agent certification Manual, inconsistent /certify command covering agents, commands, skills, scripts, hooks
Drift detection None Tiered design (daily/weekly/on-demand) embedded in operational rhythm

Implementation

File Purpose
docs/plans/unified-canonical-architecture-5p-plan.md 5P plan (Purpose, People, Process, Platform, Performance)
docs/plans/unified-canonical-architecture-prd.md Product Requirements Document (8 Functional Requirements)
docs/plans/unified-canonical-data-model.md 24 entity types, attributes, relationships, lifecycle
docs/plans/canonical-architecture-remaining-scope.md Living scope tracker with change log
docs/plans/canonical-drift-detection-design.md Tiered detection approach
scripts/canonical/show-query.js Show entity query (43 shows, broadcast metadata)
scripts/canonical/episode-query.js Episode entity query (1,289 episodes, lifecycle)
scripts/canonical/article-query.js Article entity query (143 articles, authorship)
scripts/canonical/friend-query.js Friend entity query (145 contributors, HubSpot live)
scripts/canonical/methodology-query.js Methodology entity query (52 records, drift check)
scripts/canonical/organization-query.js Organization entity query (34 orgs, Value Path)
scripts/canonical/customer-health-query.js Session + Signal + Event combined audit
scripts/canonical/company-health-query.js Engagement + Investment + Offering + Deliverable audit
scripts/canonical/project-query.js Project entity query (51 projects, plan doc linkage)
scripts/canonical/unified-audit.js Full 24-entity census across all systems
skills/canonical/canonical-query-reference.md Query tool usage patterns and when-to-use guide
apps/website/src/lib/sanity/methodology.ts Typed Sanity query functions for all methodology content
apps/website/src/data/value-path-stages.ts Canonical sync cache for React components (8 VP stages)
apps/website/src/data/trap-metadata.ts Canonical sync cache for React components (12 traps)
apps/website/studio/schemas/coreBelief.ts Sanity schema for Core Belief documents
apps/website/src/pages/learn/foundation/core-beliefs/ Core Beliefs website pages (index + [slug] detail)
apps/website/src/pages/learn/foundation/three-org/index.astro Three-Org Model website page
.claude/commands/certify.md Agent/command/skill/script/hook certification
.claude/commands/project-management.md Marshal project coordination (includes Change Order process)
/mnt/d/Leadership/assessments/2026-04-07-unified-canonical-data-model.html Interactive visualization (Tron:Ares, 11 tabs)
/mnt/d/Obsidian/value-first/ 87 notes with standardized frontmatter across 13 directories

Usage

Canonical Queries (any agent or human)

# Find a show and its cross-system presence
node scripts/canonical/show-query.js "AI Daily"

# Check methodology drift across 5 systems
node scripts/canonical/methodology-query.js --drift

# Full 24-entity census
node scripts/canonical/unified-audit.js

# Project portfolio with plan doc linkage
node scripts/canonical/project-query.js --all

# Sync projects from HubSpot + filesystem
node scripts/canonical/project-query.js --sync

Agent Certification

/certify agent director       # Certify Director through constructive show setup
/certify command daily-ops    # Verify all references resolve, execute
/certify skill vf-platform-context  # Verify methodology accuracy
/certify script project-query.js    # Execute and verify output
/certify hook build-check     # Verify trigger fires correctly

Project Management with Change Orders

/project-management UCA              # Open project session
/project-management index            # Portfolio dashboard (51 projects)
/project-management change order UCA # Formal scope change process

Website Methodology (developers)

// Astro pages — direct Sanity query
import { getAllTraps, getTrapBySlug } from '@/lib/sanity/methodology';
const traps = await getAllTraps();

// React components — canonical sync cache
import { VALUE_PATH_STAGES } from '@/data/value-path-stages';
import { TRAPS, getTrapBySlug } from '@/data/trap-metadata';

Leader Applications

V (Operations)

UCA is V's primary architectural achievement. V uses canonical queries in every operational rhythm: /daily-ops runs unified-audit.js for system health, /weekly-review uses project-query.js for portfolio tracking, and /media-prep uses show-query.js and episode-query.js for production readiness. The /certify command is V's tool for ensuring every agent, command, skill, script, and hook in the system actually works. The data model document and interactive HTML visualization are V's architectural reference for all design decisions.

Sage (Customer)

Sage uses customer-health-query.js for session, signal, and event intelligence across the portfolio. friend-query.js powers relationship intelligence with live HubSpot data for any person (human or AI). organization-query.js provides cross-system client views. The methodology queries ensure Sage's relationship briefs and session preparations reference canonical content, not stale copies.

Pax (Finance)

Pax uses company-health-query.js for engagement, investment, offering, and deliverable health across the revenue view. project-query.js provides visibility into project pipeline state with plan doc linkage. The canonical data model ensures Pax's revenue briefs and capacity assessments reference consistent entity definitions.

Dependencies

Dependency Status Notes
Sanity CMS Confirmed 43+ schema types, write token in apps/website/.env
Content Vault (SQLite) Confirmed /mnt/d/data/content-vault.db, 42 tables, 3,100+ records
HubSpot VF Team Portal Confirmed Portal 40810431, property index cached
Obsidian Vault Confirmed /mnt/d/Obsidian/value-first/, 87 notes
scripts/sanity/query.js Confirmed Read operations, auto-loads token
scripts/sanity/patch.js Confirmed Write operations via Canon
scripts/hubspot/api.js Confirmed Universal HubSpot CLI
Node.js 18+ Confirmed Required for all canonical query tools

Verification

  1. Methodology alignment: node scripts/canonical/methodology-query.js --drift returns zero discrepancies for the 24 in-scope entity types (traps, VP stages, unified views)
  2. Full census: node scripts/canonical/unified-audit.js returns 3,100+ records across 24 entity types
  3. Website build: pnpm build completes with zero methodology-related errors (all surfaces pull from Sanity)
  4. Obsidian graph: Open /mnt/d/Obsidian/value-first/ in Obsidian, verify 87 notes visible with connected graph
  5. Project query: node scripts/canonical/project-query.js "Unified Canonical" returns full cross-system view with 3 plan docs linked
  6. Visual verification: Open file:///D:/Leadership/assessments/2026-04-07-unified-canonical-data-model.html and confirm all 9 layers show "Complete"

Key Decisions Made During the Build

  1. Intentional data, not clean data. Every entity earns its place through a Unified View. Data that exists but doesn't serve a decision doesn't belong in the model.
  2. Friend replaces Person/Contact. One entity for anyone in the constellation -- human or AI.
  3. System-as-source-of-truth. No single source. Each system owns what it's best at. Agents coordinate writes through designated gateways.
  4. Learn, update, and certify by doing. Agent certification comes from constructive outcomes, not documentation. Audits are work orders, not deliverables.
  5. Canonical queries are READ intelligence. Pipeline scripts and gateway agents handle WRITES.
  6. Drift detection embedded in rhythm. Daily checks in /daily-ops, weekly comprehensive scans in /weekly-review, on-demand via --drift flags.

Session Evidence

Commit Description
68803953 UCA Phase 2: entity broadening + validation (52/52 at 5/5)
0af5eeff Change Order: Project as 24th entity type + project-query.js
e4a69544 Layer 7: 19 components refactored from hardcoded to canonical
ccab3c8a7 /certify extended to 5 artifact types

4 capability reports written: Content Vault, Canonical Query Layer, Rendered Surface Canonical Queries, Obsidian Knowledge Graph.

4 FR-11 audit reports: Visual QA (pass), Link Health (pass after fix), Director Show Setup (fail then fixed), Pixel Dedup (fail then fixed), Cross-system Drift (resolved to 52/52).