@unified-product-graph/core 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,699 @@
+# Changelog
+
+All notable changes to `@unified-product-graph/core` are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+---
+
+## [0.6.0] — 2026-05-22
+
+**Minor.** v1 editorial cut: the public framework surface is narrowed to the 34 canonical, famous frameworks (Wardley Map, BMC, OST, RICE, JTBD, North Star, OKR, AARRR, Porter Five Forces, RACI, C4, etc.) — one entry per famous-author archetype, balanced across the six lifecycle bands. The broader research catalog of 182 additional definitions is retained internally for tier-1 wiring tests and future promotion but is no longer re-exported from the package entry point or shipped in mirrors. Also lands the status-migrations axis prepared during the unreleased window.
+
+### Changed — breaking for set-iterating consumers (framework cut)
+
+- `UPG_FRAMEWORKS`, `UPG_FRAMEWORKS_BY_ID`, `UPG_FRAMEWORKS_BY_CATEGORY` now reflect the 34 canonical frameworks only. Previously 216.
+- `UPG_TYPE_LABELS[].framework_labels` keys are now scoped to the canonical 34. Label vocabulary for research-library frameworks moves to the internal-only `@unified-product-graph/frameworks` workspace.
+- `presentation/labels.ts` now sources frameworks from `canonical.js` to keep the published bundle aligned with the public surface.
+
+### Added — canonical framework infrastructure
+
+- New `packages/upg-spec/src/frameworks/canonical.ts` — generated single file holding the 34 canonical `UPGFramework` records. Public surface for `@unified-product-graph/core`.
+- New `scripts/regen-canonical-frameworks.mjs` — regen script driven by a `CANONICAL_IDS` allowlist. Future promotions are one allowlist edit + one rerun.
+- `scripts/sync-oss-repos.sh` per-pkg-excludes `src/frameworks/definitions` from the public `core` mirror so the internal research library never lands in the GitHub repo.
+
+### Added — `UPG_STATUS_MIGRATIONS` axis
+
+- **`UPG_STATUS_MIGRATIONS` map + `migrateStatusValue` / `hasStatusMigration` / `listStatusMigrations` / `findInvalidStatusMigrationTargets` helpers** (`grammar/status-migrations.ts`) — a new migration axis parallel to `UPG_MIGRATIONS` (type renames) and `UPG_PROPERTY_MIGRATIONS` (property-shape evolution): per-entity-type maps of legacy status values to canonical lifecycle phases. Initial coverage spans the highest-volume drift observed across `entopo.upg`, `sanity.upg`, and `inkling.upg` (UPG-527): `service`, `feature`, `feature_area`, `hypothesis`, `opportunity`, `initiative`, `decision`, `deployment`, `monitor`, `incident`. The companion `migrate_status` MCP tool in `@unified-product-graph/mcp-server` consumes this map; `validate_graph` lifecycle_drift entries now carry `suggested_migration` when the map resolves.
+
+---
+
+## [0.5.8] — 2026-05-21
+
+**Patch.** Three additive contributions: (1) 22 edges that close the slot-connectivity gaps in five Tier-1 strategy, research, and feedback canvas frameworks surfaced by the UPG-528 Part 1 audit (UPG-528 Part 2d); (2) five skeleton canonical playbooks promoted to rich multi-phase playbooks (UPG-523); (3) a Tier-1 connectivity regression gate that pins the v0.5.8 canonical-edge slot-pair floors for all 20 Tier-1 famous frameworks (UPG-528 Part 2e). No removals, no renames, no breaking shape changes.
+
+### Added — Tier-1 strategy / research / feedback canvas wiring (22 edges, UPG-528 Part 2d)
+
+**McKinsey 7S (4 edges)**
+
+The 7S canvas — Strategy, Structure, Systems, Shared Values, Style, Staff, Skills — forms a network of mutual influence. The catalog already had `strategic_pillar` and `capability` but no 7S-specific wiring. The central "Shared Values" node (shared_value entity, team_org domain) acts as the hub.
+
+- **`strategic_pillar_guided_by_shared_value`** (strategy ↔ team_org · cross-domain) — verbs `guided_by` / `guides`. 7S: Strategy aligns to Shared Values.
+- **`team_influences_shared_value`** (team_org · causal) — verbs `influences` / `influenced_by`. 7S: Staff shapes the Shared Values over time.
+- **`capability_expressed_through_skill`** (strategy ↔ team_org · cross-domain) — verbs `expressed_through` / `expresses`. 7S: Skills are the executable form of a capability. `skill` gains a hierarchy relationship from `capability`.
+- **`shared_value_aligns_team`** (team_org · causal) — verbs `aligns` / `aligned_by`. 7S: Shared Values bind team behaviour. Reverse of `team_influences_shared_value` but at the organisational level — teams are the object of alignment.
+
+**Jobs-to-be-Done / Four Forces (4 edges)**
+
+Christensen/Klement/Moesta four-forces canvas: Push (pain), Pull (attraction), Inertia (habit), Anxiety (fear). The catalog already had `persona_experiences_need`, `persona_pursues_job`, `job_motivates_desired_outcome`, and `switching_cost`. Missing: the force-attribution edges that map the canvas slots to entities.
+
+- **`need_creates_push_toward_solution`** (user ↔ discovery · cross-domain) — verbs `creates_push_toward` / `pulled_by`. Four Forces: a pain or frustration (need with `valence='pain'`) creates the push force toward a solution.
+- **`desired_outcome_creates_pull_toward_solution`** (user ↔ discovery · cross-domain) — verbs `creates_pull_toward` / `pulled_by`. Four Forces: the desired outcome is the magnet — what the user is pulled toward.
+- **`switching_cost_creates_inertia`** (user · causal) — verbs `creates_inertia` / `inertia_from`. Four Forces: switching costs are the concrete mechanism of inertia. Causal because the cost literally prevents switching.
+- **`assumption_creates_anxiety_about_solution`** (validation ↔ discovery · cross-domain) — verbs `creates_anxiety_about` / `anxiety_resolved_by`. Four Forces: the Anxiety force maps to unvalidated assumptions about the new solution.
+
+**North Star Framework (3 edges)**
+
+Amplitude's North Star framework: north_star_metric → input_metric → feature. The catalog had `metric` but no north-star-specific hierarchy. `north_star_metric` and `input_metric` are specialised metric subtypes defined in `MetricProperties.designation`.
+
+- **`north_star_metric_composed_of_input_metric`** (strategy · hierarchy) — verbs `composed_of` / `component_of`. The North Star is defined as a function of 3-5 input metrics. `north_star_metric` gains `input_metric` as a valid child.
+- **`input_metric_driven_by_feature`** (product ↔ strategy · cross-domain) — verbs `driven_by` / `drives`. Features move the needle on the input metrics. Causal in the North Star sense — the feature is what the team ships to shift the input metric.
+- **`initiative_moves_north_star_metric`** (strategy · causal) — verbs `moves` / `moved_by`. Initiatives are the strategic bets that move the north star metric. Cross-level: an initiative aggregates multiple features each of which drives input metrics.
+
+**OKR Canvas (3 edges)**
+
+Doerr/Wodtke's OKR canvas slots: company-level → team OKR → key result → initiative. The catalog already had the basic OKR spine (`product_targets_objective`, `objective_achieved_through_key_result`). Missing: the team-OKR alignment wiring and the initiative link from key result.
+
+- **`team_okr_aligned_with_key_result`** (team_org ↔ strategy · cross-domain) — verbs `aligned_with` / `aligns`. OKR canvas: team OKRs align with (but are not hierarchically contained by) company-level key results.
+- **`key_result_driven_by_initiative`** (strategy · causal) — verbs `driven_by` / `drives`. Key results are moved by the initiatives that fund the work.
+- **`team_okr_contributes_to_objective`** (team_org ↔ strategy · cross-domain) — verbs `contributes_to` / `has_contributing_team_okr`. Team-level OKRs roll up to product-level objectives; `contributes_to` is softer than `rolls_up_to` (team OKRs partially contribute; they are not the same objective re-stated).
+
+**Voice-of-Customer Program (4 edges)**
+
+The VoC canvas wires feedback_session → survey_response → nps_campaign → churn_reason → customer_health_score. The catalog already had `nps_campaign`, `survey_response`, `churn_reason`, and `customer_health_score` but no lateral connections.
+
+- **`feedback_session_surfaces_churn_reason`** (customer_success ↔ feedback · cross-domain) — verbs `surfaces` / `surfaced_in`. VoC: exit interviews and feedback sessions are the primary source for churn reasons.
+- **`nps_campaign_reveals_churn_reason`** (feedback · causal) — verbs `reveals` / `revealed_by`. Detractor NPS responses are strong predictors of churn; the survey makes the risk visible.
+- **`churn_reason_degrades_customer_health_score`** (customer_success · causal) — verbs `degrades` / `degraded_by`. Customer health scoring models incorporate churn-risk signals; a documented churn reason is an input that lowers the score.
+- **`survey_response_informs_nps_campaign`** (feedback · causal) — verbs `informs` / `informed_by`. Individual survey responses are the raw data that the NPS campaign aggregates into its score. Causal direction: responses → campaign score (not vice versa).
+
+**Wardley + McKinsey strategic context (4 edges)**
+
+Two Wardley-style edges and two McKinsey-ecosystem links missed by the earlier passes.
+
+- **`capability_shapes_strategic_pillar`** (strategy · causal) — verbs `shapes` / `shaped_by`. A canonical capability is the organizational foundation for a strategic pillar. In 7S terms, Skills/Capabilities anchor Strategy.
+- **`value_stream_delivers_outcome`** (strategy · causal) — verbs `delivers` / `delivered_by`. Value streams are the end-to-end flow that produces a business outcome. Closes the gap between operational flows (value_stream) and strategic results (outcome).
+- **`initiative_funded_by_revenue_stream`** (strategy ↔ business_model · cross-domain) — verbs `funded_by` / `funds`. Strategic initiatives are funded by the revenue streams they ultimately grow or protect. Connects the business model layer (revenue_stream) to the strategy layer (initiative).
+- **`strategic_pillar_operationalised_by_value_stream`** (strategy · causal) — verbs `operationalised_by` / `operationalises`. A strategic pillar is made real through the value streams that deliver it. Closes the strategy-to-execution chain: `strategic_pillar → value_stream → outcome`.
+
+### Hierarchy grammar (Part 2d)
+
+- `north_star_metric` gains `input_metric` as a valid child (North Star Framework: the NSM is defined as a function of input metrics).
+- `capability` gains `skill` as a valid child (7S Framework: skills are the executable expression of a capability).
+
+### Pairs NOT added (LOW-confidence — explicit decisions, Part 2d)
+
+The Part 1 audit surfaced 240+ missing pairs across the five canvases; 22 are added above. Patterns excluded: reverse-already-covered (e.g. `shared_value → strategic_pillar`, `solution → need`), slot-pair artifacts with no canonical relationship (e.g. `shared_value → capability`, `key_result → team_okr`), and already-mediated paths (e.g. `initiative → key_result` mediated via `key_result_driven_by_initiative` reverse).
+
+### Connectivity (post-fix, Part 2d)
+
+- mckinsey-7s: 0 → 4 new edges
+- four-forces: 0 → 4 new edges
+- north-star-framework: 0 → 3 new edges
+- okr-canvas: baseline → +3 new edges
+- voice-of-customer-program: 0 → 4 new edges (+ 3 Wardley/strategic-context edges)
+
+### Catalog size (Part 2d)
+
+- Edges: 916 → 938 (+22)
+- `UPG_VERSION`: `0.5.7` → `0.5.8`
+
+---
+
+### Added — Rich playbooks for the 5 former skeletons (UPG-523)
+
+**Patch.** Five of ten canonical playbooks were skeletons — single-phase `domain_guide` records that just deferred to a domain creation sequence. They are now rich multi-phase `entity_sequence` playbooks with per-phase `prompt_hint`s, matching the voice and shape of the existing five rich playbooks (`users-needs`, `discovery-research-validation`, `experience-design-brand`, `engineering-platform`, `business-gtm-growth`). Surfaced by the 2026-05-21 higher-order constructs audit (Pass 7).
+
+Each playbook bumps `version` 0.1.0 → 0.2.0 and grows from one step to 6–7:
+
+- **`playbook:strategy-outcomes`** — 7 phases: Vision & Mission → Themes → Outcomes → Objectives → Key Results → Initiatives & Capabilities → Assumptions & Decisions. Preserves the chain into `playbook:discovery-validation-hypothesis-cycle` via the final step's `next_sequence_on_gap`.
+- **`playbook:market-competitive`** — 6 phases: Market → Competitors → Their offerings → Trends → Analysis → Moves.
+- **`playbook:product-delivery`** — 6 phases: Features → Epics → Stories → Tasks & Dependencies → Releases & Milestones → Themes & Changelog.
+- **`playbook:analytics-data`** — 6 phases: Data Sources → Event Schemas → Pipelines & Models → Metrics → Dashboards → Data Quality. No longer marked "skeleton playbook; content depth is in progress".
+- **`playbook:operations-quality`** — 7 phases: DevOps Backbone → Monitoring & SLOs → Incident Response → Security → Quality Gates → Compliance & Accessibility → Customer Support. No longer marked "skeleton playbook; content depth is in progress".
+
+### Helper update (UPG-523)
+
+`seqStep()` helper in `playbooks/definitions/index.ts` now accepts an optional `{ next_sequence_on_gap }` parameter to support chaining between rich playbooks (mirroring `domainGuideStep`).
+
+### Audit coverage (UPG-523)
+
+- Rich canonical playbooks: 5 → 10 (every canonical playbook is now multi-phase).
+- Skeleton playbooks remaining: 0 of 10 canonical.
+
+---
+
+### Tests — Tier-1 connectivity regression gate (UPG-528 Part 2e)
+
+**Additive only.** New vitest file `src/__tests__/tier-1-connectivity-regression-gate.test.ts` pins the v0.5.8 (post-Tier-1-sweep) canonical-edge slot-pair connectivity for the 20 Tier-1 famous frameworks as a strict integer floor (`min_connected / total`). If any framework's connected-pair count drops below its pinned floor — e.g. via accidental edge consolidation in UPG-510, a refactor, or a silent deprecation — CI fails with an actionable message that lists both remediation paths (restore the edge, or update the floor + document in `CHANGELOG.md`). No catalog changes, no edges added or removed, no framework definitions touched, no version bump. Locks in the 77 canonical Tier-1 edges shipped across UPG-528 Batches 1-4. Test count: 781 → 803 (+22 = 20 framework floors + 2 sanity meta-tests).
+
+---
+
+## [0.5.7] — 2026-05-21
+
+**Patch.** 11 high-confidence edges that close the slot-connectivity gaps in four Tier-1 engineering + AI canvas frameworks surfaced by the UPG-528 Part 1 audit: Bounded Context Canvas (Nick Tune / DDD Crew), LLM Evaluation Framework (NLP community), API Design First (OpenAPI Initiative), and Multi-Agent Orchestration (AutoGen / CrewAI / LangGraph). Additive only — no removals, no renames, no breaking shape changes.
+
+### Context
+
+The Part 1 audit (Agent O2) re-run on Agent V's v0.5.6 base showed 94 missing ordered slot-pair edges across the four canvases. Many were already closed by Agent S (v0.5.3 — DDD/CQRS event chain) and Agent K (v0.5.2 — Wardley capability properties). Of the remaining gaps, most are reverse-traversals already covered by an existing forward edge, slot-pair artifacts with no canonical relationship in source literature, or paths already mediated through a third entity. This patch adds the 11 edges that map to explicitly-named relationships in the canonical engineering / AI literature. Continues the Part 2a/2b discipline: quality of the catalog over score on the audit.
+
+### Added — Bounded Context Canvas (2 edges)
+
+DDD canon: Nick Tune's canvas captures purpose, ubiquitous language, inbound/outbound communication, and key domain roles. The catalog already had the Agent S v0.5.3 chain (`bounded_context_modelled_as_aggregate`, `bounded_context_emits_domain_event`, `aggregate_contains_domain_entity`, `aggregate_emits_domain_event`, `aggregate_handles_command`, `command_produces_domain_event`). Missing: the BC-level published-language link and the saga / process-manager reaction loop.
+
+- **`bounded_context_publishes_api_contract`** (engineering · hierarchy) — verbs `publishes` / `published_by`. DDD's "published language" at the BC level. `api_contract` gains a second valid hierarchy parent (service AND bounded_context); both paths coexist intentionally — services expose per-service contracts, the BC publishes their union as its public surface.
+- **`domain_event_triggers_command`** (engineering · causal) — verbs `triggers` / `triggered_by`. CQRS saga / process-manager pattern (Vernon, Young): an event handler issues a new command in response to an event. Closes the reactive loop that the existing `command_produces_domain_event` only covers in one direction.
+
+### Added — LLM Evaluation Framework (2 edges)
+
+The canvas presents Accuracy (eval_benchmark), Coherence (eval_run), Safety (ai_guardrail), Latency (metric), and Cost (ai_cost_tracker) as evaluation dimensions of an ai_model. The catalog already had `ai_model_benchmarked_by_eval_benchmark`, `ai_model_constrained_by_ai_guardrail`, `ai_model_costed_by_ai_cost_tracker`, and `eval_benchmark_executed_as_eval_run`. Missing: the metric-output edges from benchmark and run.
+
+- **`eval_run_produces_metric`** (ai_ml · causal) — verbs `produces` / `produced_by`. Every benchmark execution writes a result row of (metric, value, timestamp). Causal because the run is what creates the metric reading.
+- **`eval_benchmark_defines_metric`** (ai_ml · hierarchy) — verbs `defines` / `defined_by`. HELM, MLPerf, BIG-bench all specify their metric set. Mirrors `data_source_defines_metric` (same verb, same classification). `metric` gains another hierarchy parent (already has outcome / objective / key_result / solution / data_source as parents).
+
+### Added — API Design First (4 edges)
+
+The OpenAPI / Swagger workflow threads contract → endpoint → review (decision) → mock (domain_entity) → implementation (data_flow). Agent S's v0.5.1 work landed `api_contract_contains_api_endpoint`. Missing: the typed-payload edges and the design-decision attachment that the canvas slots imply.
+
+- **`api_endpoint_references_domain_entity`** (engineering · semantic) — verbs `references` / `referenced_by`. Endpoints bind to entity types by name in request/response payloads — semantic, not hierarchy, because the entity is not contained.
+- **`api_contract_records_decision`** (engineering ↔ strategy · cross-domain) — verbs `records` / `recorded_in`. API design decisions (auth scheme, versioning policy, REST vs gRPC, pagination) are recorded against the contract during the OpenAPI review step. Parallel to `bounded_context_decided_via_decision` but at the contract grain.
+- **`data_flow_transports_domain_entity`** (engineering · causal) — verbs `transports` / `transported_by`. DFD canonical: the arrow on a data-flow diagram carries a named payload.
+- **`api_endpoint_participates_in_data_flow`** (engineering · semantic) — verbs `participates_in` / `involves`. Endpoints are DFD nodes that emit / consume flows. Semantic because participation is associational membership, not containment.
+
+### Added — Multi-Agent Orchestration (3 edges)
+
+The AutoGen / CrewAI / LangGraph canvas wires agent_definition → workflow_template → workflow_run → workflow_artifact with agent_hook and review_gate as cross-cutting concerns. The existing catalog covers the template-level structure (`agent_definition_orchestrates_workflow_template`, `workflow_template_executed_as_workflow_run`, `workflow_template_gated_by_review_gate`, `workflow_run_produces_workflow_artifact`, `agent_definition_triggered_via_agent_hook`). Missing: the runtime / execution facts the canvas surfaces under "Handoff Rules", "Conflict Resolution", and "Aggregation".
+
+- **`agent_definition_produces_workflow_artifact`** (agentic · causal) — verbs `produces` / `produced_by`. Agents are the logical authors of artifacts; runs are their structural carrier. Polysemic with `workflow_run_produces_workflow_artifact` (already in catalog) by design — same pattern as the v0.5.3 `aggregate_emits_domain_event` + `command_produces_domain_event` polysemy.
+- **`agent_hook_fires_during_workflow_run`** (agentic · causal) — verbs `fires_during` / `fires_via`. The runtime attribution for hook firing. The existing `agent_definition_triggered_via_agent_hook` covers the hook→agent registration; this adds the hook→run execution context.
+- **`workflow_run_passes_through_review_gate`** (agentic · causal) — verbs `passes_through` / `gates_run`. Run-level gate traversal — distinct from the existing template-level `workflow_template_gated_by_review_gate`. Required for queries asking "which runs blocked on this gate?".
+
+### Hierarchy grammar
+
+Two `UPG_VALID_CHILDREN` updates:
+
+- `bounded_context` gains `api_contract` as a child (BCs publish their union of contracts as published language; service-level exposure remains).
+- `eval_benchmark` gains `metric` as a child (benchmarks define their metric set).
+
+### Pairs NOT added (LOW-confidence — explicit decisions)
+
+Across the four canvases, 83 ordered slot pairs are LOW-confidence and explicitly NOT added. Five patterns:
+
+1. **Reverse-already-covered.** `domain_entity → aggregate`, `command → aggregate`, `metric → eval_run`, `decision → api_contract`, `workflow_artifact → workflow_run`, `review_gate → workflow_run` — reverses of edges added here or already in catalog.
+2. **Slot-pair artifacts with no canonical relationship.** `domain_entity → domain_event`, `ai_guardrail → metric` (Coherence ↔ Safety), `api_contract → domain_entity` (mediated through endpoint), `agent_hook → workflow_artifact`, `review_gate → workflow_artifact` — both on the canvas but no named relationship in source literature.
+3. **Already-mediated paths.** `bounded_context → command` (mediated through aggregate), `bounded_context → domain_entity` (mediated through aggregate), `ai_model → eval_run` (mediated through eval_benchmark), `agent_definition → workflow_run` (mediated through workflow_template), `workflow_template → workflow_artifact` (mediated through workflow_run), `bounded_context → api_endpoint` (mediated through api_contract).
+4. **Wrong-direction abstractions.** `domain_event → bounded_context`, `aggregate → bounded_context`, `api_contract → bounded_context` — children don't structurally reach up to their parent; reverse traversal of the existing forward edge handles "what BC does this belong to".
+5. **Conceptually loose canvas mappings.** Bounded Context Canvas labels `api_contract` as "Business Decisions" and `command` as "Outbound Communication" — both stretch the entity types. Adding edges that honour the stretch (e.g., `api_contract → command`) would import the looseness into the catalog.
+
+### Connectivity (post-fix vs Part 1 baseline, re-run on Agent V's v0.5.6 base)
+
+- bounded-context-canvas: 6→8 of 30 (0.200→0.267 · +2)
+- llm-evaluation-framework: 4→6 of 30 (0.133→0.200 · +2)
+- api-design-first: 1→5 of 20 (0.050→0.250 · +4)
+- multi-agent-orchestration: 5→8 of 30 (0.167→0.267 · +3)
+
+Strictly higher than baseline for all four frameworks. Per Part 2a/2b discipline: the audit's "every directional pair must resolve" metric overstates how connected canvases actually are (most slot pairs are not canonical relationships in source literature); the relevant test is strictly-higher-than-baseline, not a magic ratio target.
+
+### Tests
+
+- `src/__tests__/tier-1-engineering-ai-wiring.test.ts` — guards each edge's shape, PAIR_MAP indexing, no self-loops, catalog growth, and post-fix connectivity per framework.
+- All 694 v0.5.6 tests continue to pass.
+
+### Catalog size
+
+- Edges: 905 → 916 (+11)
+- Hierarchy grammar entries: +2 (bounded_context → api_contract, eval_benchmark → metric)
+- SATURATED fixture: +11 synthetic `e_synthetic_upg528_2c_*` instances
+
+### Migration notes
+
+None. All 11 edges are additive. Existing graphs and adapters are unaffected. Two `UPG_VALID_CHILDREN` extensions widen the legal parent set for `api_contract` (gains `bounded_context`) and `metric` (gains `eval_benchmark`); no existing parent-child relationship is removed or invalidated.
+
+---
+
+## [0.5.6] — 2026-05-21
+
+**Patch.** 15 edges (13 high-confidence + 2 medium-confidence) that close the slot-connectivity gaps in three Tier-1 design/UX canvas frameworks surfaced by the UPG-528 Part 1 audit: Lean UX Canvas (Gothelf), Persona Canvas (Cooper/Pichler), and Design Sprint (Knapp/GV). Additive only — no removals, no renames, no breaking shape changes.
+
+### Context
+
+The Part 1 audit (Agent O2) enumerated 75 missing ordered slot-pair edges across the three canvases. Most are slot-pair artifacts (no canonical relationship in the source literature) or hierarchy-reverses already covered by reverse traversal of an existing edge. This patch adds the 15 edges that map to explicitly-named relationships in the canonical source literature and explicitly does NOT add the artifact-only pairs. Continues the Part 2a discipline: quality of the catalog over score on the audit.
+
+### Added — Lean UX Canvas (7 edges)
+
+Closes Gothelf's hypothesis template, which binds hypothesis → feature → persona → outcome in one sentence: "We believe [feature] for [persona] will result in [outcome]." The catalog already had `feature_tests_hypothesis` (reverse), `experiment_run_validates_hypothesis`, `outcome_delivered_by_feature` (reverse), `persona_experiences_need`, and the Part 2a `assumption_concerns_*` family. Missing: the forward subject arrows of the hypothesis template, the outcome-side measurement loop, and pattern completion for `assumption_concerns_*`.
+
+- **`hypothesis_targets_outcome`** (validation · causal) — verbs `targets` / `targeted_by`. The "will result in [outcome]" clause of Gothelf's template.
+- **`hypothesis_concerns_persona`** (validation · semantic) — verbs `concerns` / `has_hypothesis`. The "for [persona]" clause. Mirrors `assumption_concerns_persona` shape.
+- **`feature_addresses_need`** (product · cross-domain) — verbs `addresses` / `addressed_by`. Parallel to `feature_addresses_job` — features address both jobs and needs (Lean UX block 5 ↔ block 1).
+- **`experiment_run_measures_outcome`** (validation · cross-domain) — verbs `measures` / `measured_by`. Parallel to `experiment_run_measures_metric` — outcomes are the higher-level business measure (Lean UX block 8 ↔ block 2).
+- **`persona_pursues_outcome`** (user · semantic) — verbs `pursues` / `pursued_by`. Lean UX block 4 (User Outcomes & Benefits) ties persona to outcome. Same verb as `persona_pursues_job` — lateral within the user domain.
+- **`assumption_concerns_outcome`** (validation · semantic) — verbs `concerns` / `has_assumption`. MEDIUM-confidence: pattern-completion of UPG-528 Part 2a's `assumption_concerns_*` family. Flagged for review.
+- **`assumption_concerns_feature`** (validation · semantic) — verbs `concerns` / `has_assumption`. MEDIUM-confidence: same family, same review flag.
+
+### Added — Persona Canvas (3 edges)
+
+Pichler/Cooper canvas slots: `{persona, desired_outcome, need, observation, job, quote}`. The catalog already had `persona_pursues_job`, `persona_experiences_need`, `persona_aspires_to_desired_outcome`, `job_motivates_desired_outcome`, `observation_characterises_persona`, `observation_evidenced_by_quote`, `quote_evidences_need`, and `observation_reveals_need`. Missing: the verbal-evidence direction from persona's mouth, the Ulwick need ↔ desired_outcome link, and the parallel observation-reveals edge for jobs.
+
+- **`quote_voices_persona`** (research · cross-domain) — verbs `voices` / `voiced_by`. Persona Canvas's Quotes slot is explicitly "what the persona says". Parallel to `observation_characterises_persona` but for verbal evidence.
+- **`need_measured_by_desired_outcome`** (user · causal) — verbs `measured_by` / `measures`. Ulwick's outcome-driven innovation: a need is measured by the desired outcomes that quantify its satisfaction. Reverse traversal closes `desired_outcome → need` from this one edge.
+- **`observation_reveals_job`** (research · cross-domain) — verbs `reveals` / `revealed_by`. Parallel to `observation_reveals_need`. Persona Canvas Behaviours slot surfaces jobs the persona performs.
+
+### Added — Design Sprint (5 edges, 1 medium-confidence)
+
+Knapp/GV's five-day flow: design_question (Map) → design_concept (Sketch) → decision (Decide) → user_flow (Prototype) → observation (Test). The catalog already had `design_question_answered_by_design_concept` (Day 1 → Day 2), `design_concept_realised_as_prototype`, `design_concept_sketched_in_wireframe`, and `learning_informs_decision`. Missing: the Day 3-5 closures.
+
+- **`design_question_resolved_by_decision`** (design · causal) — verbs `resolved_by` / `resolves`. Day 3 Decide — the HMW question gets a commitment-level resolution. Parallel to but stronger than `_answered_by_design_concept`.
+- **`decision_selects_design_concept`** (design · causal) — verbs `selects` / `selected_by`. Day 3 picks the winning sketch. The sprint's canonical "Decide" action.
+- **`user_flow_validated_by_observation`** (design · causal) — verbs `validated_by` / `validates`. Day 5 Test — observations validate (or invalidate) the prototype's flow. Parallel to `experiment_run_validates_hypothesis`.
+- **`design_concept_realised_as_user_flow`** (design · causal) — verbs `realised_as` / `realises`. MEDIUM-confidence (polysemy): widens grammar so concepts can be prototypes OR flows depending on sprint fidelity. Could be argued as redundant with the existing prototype edge. Flagged for review.
+- **`observation_informs_decision`** (research · cross-domain) — verbs `informs` / `informed_by`. MEDIUM-confidence (subsumed by learning?): `learning_informs_decision` already covers the synthesised-insight path. This adds the direct observation → decision link for cases where a sprint observation immediately changes commitment without intermediate synthesis. Flagged for review.
+
+### Hierarchy grammar
+
+No changes. All 15 edges are causal / semantic / cross-domain — none are hierarchy classification, so `UPG_VALID_CHILDREN` is unchanged.
+
+### Pairs NOT added (LOW-confidence — explicit decisions)
+
+The Part 1 audit surfaced 75 missing pairs across the three canvases; 15 are added above. The remaining 60 are LOW-confidence and explicitly NOT added. Three patterns:
+
+1. **Reverse-already-covered.** E.g., `decision → design_concept` is the reverse of the new `decision_selects_design_concept`; `desired_outcome → need` is the reverse of `need_measured_by_desired_outcome`; `assumption → need/persona/solution` are reverses of existing `assumption_concerns_*` (forward already exists). Adding both directions pollutes the catalog.
+2. **Slot-pair artifacts with no canonical relationship.** E.g., `outcome → persona`, `quote → desired_outcome`, `experiment_run → assumption`, `design_question → user_flow`, `design_question → observation` — both on the same canvas but no named relationship in source literature.
+3. **Already-mediated paths.** E.g., `decision → user_flow` (mediated via decision → design_concept → user_flow), `feature → outcome` (mediated via outcome_delivered_by_feature reverse), `hypothesis → need` (mediated via hypothesis → feature → need).
+
+The Part 2b report enumerates the full list and reason per pair.
+
+### Connectivity-ratio movement (post-fix vs Part 1 audit baseline)
+
+Measured against the Part 1 audit baseline (pre-Part-2a). The Part 2a `assumption_concerns_need` and `assumption_concerns_persona` edges also incidentally close two lean-ux-canvas pairs, so its gain looks larger than the +7 directly attributable to Part 2b.
+
+- `lean-ux-canvas` — connected 6→15 of 42 pairs · ratio 0.143 → 0.357 (+9 pairs total, of which +7 from Part 2b)
+- `persona-canvas` — connected 10→13 of 30 pairs · ratio 0.333 → 0.433 (+3 pairs)
+- `design-sprint` — connected 1→6 of 20 pairs · ratio 0.050 → 0.300 (+5 pairs, 6× absolute)
+
+These are the achievable upper bounds for these canvases given the discipline of adding only canonical edges. The remaining null pairs are deliberate non-additions, not gaps.
+
+### Catalog growth
+
+- `UPG_EDGE_CATALOG`: 881 → 896 keys (+15)
+- `UPG_VERSION`: `0.5.5` → `0.5.6` (patch)
+- `UPG_FORMAT_VERSION`: unchanged (`0.4.0`)
+
+### Migration impact
+
+None. Additive only. Existing edge keys, classifications, and verbs are unchanged.
+
+---
+
+## [0.5.5] — 2026-05-21
+
+**Patch.** Two additive contributions: (1) 29 edges (24 high-confidence + 5 medium-confidence) that close the slot-connectivity gaps in five Tier-1 business/GTM canvas frameworks surfaced by the UPG-528 Part 1 audit (UPG-528 Part 2a); (2) 3 causal edges that complete the DDD/CQRS event-flow spine (UPG-517 C1). No removals, no renames, no breaking shape changes.
+
+### Added — Business/GTM canvas wiring (29 edges, UPG-528 Part 2a)
+
+The Part 1 audit (Agent O2) enumerated 240 missing ordered slot-pair edges across five canvases: Business Model Canvas, Lean Canvas, GTM Playbook, Opportunity Canvas, and Test Card + Learning Card. Most are artifacts of the canvas declaring too many slot types — but ~29 represent real, named relationships from the canonical source literature (Osterwalder, Maurya, Patton, Strategyzer, GTM practice). This patch adds the canonical ones and explicitly does NOT add the artifact-only pairs.
+
+#### Business Model Canvas (15 edges, all causal/cross-domain)
+
+Closes the structural spine of Osterwalder's 9-block canvas — the named flows between value proposition, segments, channels, relationships, key activities, key resources, partnerships, costs, and revenues.
+
+- **`key_activity_delivers_value_proposition`** (business_model · causal) — verbs `delivers` / `delivered_by`. Activities are what the business *does* to produce its VP.
+- **`key_activity_uses_key_resource`** (business_model · cross-domain) — verbs `uses` / `used_by`.
+- **`key_resource_enables_key_activity`** (business_model · cross-domain) — verbs `enables` / `enabled_by`.
+- **`partnership_performs_key_activity`** (business_model · cross-domain) — verbs `performs` / `performed_by`. Outsourced activities; canonical BMC partnership rationale.
+- **`partnership_provides_key_resource`** (business_model · cross-domain) — verbs `provides` / `provided_by`. Resource-providing partnerships.
+- **`customer_relationship_with_market_segment`** (business_model · cross-domain) — verbs `with` / `maintained_by`. Each relationship targets specific segments.
+- **`distribution_channel_reaches_market_segment`** (business_model · cross-domain) — verbs `reaches` / `reached_by`.
+- **`distribution_channel_delivers_value_proposition`** (business_model · cross-domain) — verbs `delivers` / `delivered_by`. Channels are the delivery mechanism for the VP.
+- **`value_proposition_addresses_market_segment`** (business_model · cross-domain) — verbs `addresses` / `addressed_by`. Each VP targets specific segments.
+- **`revenue_stream_captured_from_market_segment`** (business_model · cross-domain) — verbs `captured_from` / `yields_revenue_via`. Different segments yield different streams.
+- **`cost_structure_driven_by_key_activity`** (business_model · causal) — verbs `driven_by` / `drives_cost_via`. Activities are the operational cost drivers.
+- **`cost_structure_driven_by_key_resource`** (business_model · causal) — verbs `driven_by` / `drives_cost_via`. Resources are the asset cost drivers.
+- **`value_proposition_yields_revenue_stream`** (business_model · causal) — verbs `yields` / `yielded_by`. Revenue is captured value.
+- **`customer_relationship_supports_value_proposition`** (business_model · cross-domain) — verbs `supports` / `supported_by`. MEDIUM-confidence (verb-naming): `supports` is one of several plausible choices. Flagged for review.
+- **`partnership_supports_value_proposition`** (business_model · cross-domain) — verbs `supports` / `supported_by`. MEDIUM-confidence (verb-naming): same note. Flagged for review.
+
+#### Lean Canvas (3 edges)
+
+- **`solution_addresses_need`** (discovery · causal) — verbs `addresses` / `addressed_by`. The direct problem-solution-fit link (complements pre-existing `opportunity_drives_solution` and `value_proposition_solves_need`).
+- **`capability_enables_value_proposition`** (strategy · causal) — verbs `enables` / `enabled_by`. The lean-canvas "unfair advantage" — a capability that uniquely enables the VP.
+- **`competitor_addresses_need`** (market · cross-domain) — verbs `addresses` / `addressed_by`. Closes the Lean Canvas "Existing Alternatives" slot — a competitor exists *because* it addresses the same underlying need.
+
+#### GTM Playbook (5 edges)
+
+The catalog already had `gtm_strategy` fanning out to all six children. Missing was the lateral flow ICP → positioning → messaging → launch/sales.
+
+- **`ideal_customer_profile_informs_positioning`** (gtm · causal) — verbs `informs` / `informed_by`.
+- **`ideal_customer_profile_shapes_messaging`** (gtm · causal) — verbs `shapes` / `shaped_by`.
+- **`ideal_customer_profile_shapes_sales_motion`** (gtm · causal) — verbs `shapes` / `shaped_by`.
+- **`messaging_used_in_launch`** (gtm · cross-domain) — verbs `used_in` / `uses`. Messaging is the artifact that launches use.
+- **`messaging_enables_sales_motion`** (gtm · cross-domain) — verbs `enables` / `enabled_by`. Messaging arms the sales motion.
+
+#### Test Card + Learning Card (3 edges)
+
+The Strategyzer validation flow: hypothesis → test_plan → experiment_run → evidence → learning → decision.
+
+- **`test_plan_ran_as_experiment_run`** (validation · hierarchy) — verbs `ran_as` / `ran_for`. Mirrors `experiment_plan_ran_as_experiment_run` for the Test Card pair. **Hierarchy update:** `test_plan` gains `experiment_run` as a valid child.
+- **`evidence_interpreted_as_learning`** (validation · causal) — verbs `interpreted_as` / `interpreted_from`. The interpretation step on the Learning Card.
+- **`learning_informs_decision`** (validation · causal) — verbs `informs` / `informed_by`. The commit step on the Learning Card.
+
+#### Opportunity Canvas (3 edges, all MEDIUM-confidence)
+
+Patton's Opportunity Canvas Assumptions slot is meant to capture the riskiest beliefs about each of the other slots. The catalog already had `assumption_becomes_hypothesis` (the test flow) and `initiative_assumes_assumption` (the owner side). Missing: the *subject* of the assumption.
+
+- **`assumption_concerns_need`** (validation · semantic) — verbs `concerns` / `has_assumption`. MEDIUM-confidence (verb-naming): `concerns` is one of several plausible verbs. Flagged for review.
+- **`assumption_concerns_persona`** (validation · semantic) — verbs `concerns` / `has_assumption`. MEDIUM-confidence: same note.
+- **`assumption_concerns_solution`** (validation · semantic) — verbs `concerns` / `has_assumption`. MEDIUM-confidence: same note.
+
+#### Hierarchy grammar (Part 2a)
+
+- `test_plan` gains `experiment_run` as a valid child — the Test Card maps to one or more experiment runs (mirrors `experiment_plan: ['experiment_run']`).
+
+#### Pairs NOT added (Part 2a)
+
+The Part 1 audit surfaced 240 missing pairs; 29 are added above. The remaining ~211 are LOW-confidence and explicitly NOT added. Three patterns:
+
+1. **Hierarchy-reverse pairs already reachable via reverse traversal.** E.g., `revenue_stream → value_proposition` is the reverse of the new `value_proposition_yields_revenue_stream`. Adding both directions would pollute the catalog with duplicates.
+2. **Canvas-only slot artifacts with no real semantic link.** E.g., `cost_structure → persona`, `metric → cost_structure`, `revenue_stream → competitor` — both on the same canvas but no canonical relationship.
+3. **Already-mediated paths.** E.g., `solution → capability` (mediated via `solution → feature ← capability`), `gtm_strategy → messaging` (mediated via `gtm_strategy → positioning → messaging`).
+
+#### Audit coverage (Part 2a)
+
+- Edge count: 861 → 890 (+29).
+- Slot-connectivity ratios (pre → post) for the 5 target frameworks:
+  - business-model-canvas: 0.014 → 0.222 (+15 pairs closed; **16× improvement**)
+  - lean-canvas: 0.127 → 0.164 (+4 pairs closed)
+  - gtm-playbook: 0.167 → 0.333 (+5 pairs closed; **2× improvement**)
+  - opportunity-canvas: 0.167 → 0.300 (+4 pairs closed; **1.8× improvement**)
+  - test-card-learning-card: 0.233 → 0.333 (+3 pairs closed)
+
+---
+
+### Added — DDD/CQRS event-flow spine (3 edges, UPG-517 C1)
+
+Three causal edges that complete the DDD/CQRS event-flow spine. The pre-existing structural edges (`aggregate_contains_domain_entity`, `aggregate_contains_value_object`, `aggregate_handles_command`, `bounded_context_modelled_as_aggregate`, `bounded_context_emits_domain_event`) cover who owns what; these three carry the temporal cause-and-effect that makes event-driven and CQRS architectures expressible.
+
+- **`command_produces_domain_event`** (engineering · causal) — verbs `produces` / `produced_by`. A command handle emits exactly one domain event per successful invocation; the command is the trigger.
+- **`aggregate_emits_domain_event`** (engineering · causal) — verbs `emits` / `emitted_by`. The aggregate is the source of the event — same event as `command_produces_domain_event`, viewed from its emitter rather than its trigger. Coexists with `bounded_context_emits_domain_event` (the bounded-context-level rollup, structural hierarchy).
+- **`domain_event_projected_to_read_model`** (engineering · causal) — verbs `projected_to` / `projected_from`. The CQRS read-side projection: domain events drive read-model updates. Composes with `aggregate_emits_domain_event` to express the full command-side → event → read-side path.
+
+#### Composes into the canonical CQRS chain
+
+```
+command
+  ─ command_produces_domain_event ─→ domain_event
+                                       ↑
+                                       │ aggregate_emits_domain_event
+                                       │
+                                    aggregate
+                                       │
+                                       │ aggregate_handles_command (existing, hierarchy)
+                                       ↓
+                                    command
+
+domain_event
+  ─ domain_event_projected_to_read_model ─→ read_model
+```
+
+#### Self-loop note (DDD/CQRS)
+
+None of the three are same-type edges. They compose cleanly with the UPG-520 self-loop refusal (`A → A` refused by default) — every relation is between distinct types.
+
+#### Polysemy on `domain_event`
+
+A single `domain_event` instance is simultaneously `produced_by` a command and `emitted_by` an aggregate. This is the intended shape in DDD/CQRS: commands are *triggers*, aggregates are *sources*. Both views are addressable in the catalog without duplicating the event.
+
+#### Scope discipline (UPG-517 C1)
+
+The UPG-517 C1 brief proposed eight edges. Five of those collided with edges already in the catalog at v0.5.1 / pre-existing:
+
+- `aggregate_contains_domain_entity`, `aggregate_contains_value_object`, `aggregate_handles_command` — shipped at v0.5.1.
+- `bounded_context_contains_aggregate` — overlaps with the canonical `bounded_context_modelled_as_aggregate`.
+- `bounded_context_contains_service` — overlaps with the canonical `bounded_context_deploys_service`.
+
+The remaining three (causal event-flow) had no prior canonical edges and are the actual gap.
+
+#### Audit coverage (UPG-517 C1)
+
+- Edge count: 857 → 861 (merged total with Part 2a: 857 → 890, but these three are the UPG-517 C1 contribution adding to the 0.5.4 base of 857).
+- `command` outgoing-edge count: 0 → 1 (no longer a pure terminal — `aggregate_handles_command` was incoming only).
+- `domain_event` outgoing-edge count: 0 → 1.
+- `aggregate` outgoing-edge count: 3 → 4.
+
+---
+
+## [0.5.4] — 2026-05-21
+
+**Patch.** Four edges across two tickets: three strategic_theme wiring edges (UPG-511) that lift `strategic_theme` from structural isolation to a conceptually central strategy node, and one solution-to-feature graduation edge (UPG-513) that closes the Teresa Torres Solution Tree chain. Additive only — no removals, no renames, no breaking shape changes.
+
+### Added
+
+**UPG-511 — strategic_theme wiring (3 causal / hierarchy edges)**
+
+- **`strategic_theme_delivers_outcome`** (strategy · causal) — verbs `delivers` / `delivered_by`. A strategic theme produces a business outcome; this causal link makes the delivery intent explicit.
+- **`strategic_theme_measured_by_key_result`** (strategy · causal) — verbs `measured_by` / `measures`. Themes are broad; key results make them measurable. Direct link means a dashboard can surface KRs next to the theme without traversing objective.
+- **`objective_rolls_up_to_strategic_theme`** (strategy · hierarchy) — verbs `rolls_up_to` / `contains_objective`. OKR containment direction — an objective is the specific quarterly bet *within* a theme. `strategic_theme` is the broader multi-quarter focus area; `objective` is subordinate. Mirrors the real-world usage and completes the strategic cascade: `strategic_pillar → strategic_theme → objective → key_result`.
+
+**UPG-513 — solution graduation (1 causal edge)**
+
+- **`solution_becomes_feature`** (discovery · causal) — verbs `becomes` / `evolved_from`. The explicit graduation moment in Teresa Torres' Solution Tree — a solution that has been validated and committed to delivery becomes a feature. Closes the chain: `opportunity → solution → feature`. Distinct from `capability_implemented_by_feature` (structural realisation) — this captures the *transition* from exploration to delivery commitment.
+
+### Hierarchy grammar
+
+- `strategic_theme` gains `objective` as a valid child — objectives are structurally subordinate to themes in the OKR cascade.
+
+### Semantic overlap check
+
+No duplicates introduced:
+- `strategic_theme_pursues_initiative` (pre-existing) — outgoing to `initiative`. New edges target `outcome`, `key_result`, and (incoming from) `objective`. No overlap.
+- `capability_implemented_by_feature` — structural realisation edge. `solution_becomes_feature` is a causal graduation edge. Different semantics, different source types.
+- `outcome_delivered_by_feature` (pre-existing) — `outcome → feature` reverse direction. `solution_becomes_feature` is `solution → feature`. No overlap.
+
+### Audit coverage
+
+- Edge count: 857 → 861.
+- `strategic_theme` outgoing-edge count: 1 → 3 (adds `delivers_outcome`, `measured_by_key_result`; gains 1 incoming from `objective_rolls_up_to`).
+- `solution` outgoing-edge count: +1 (adds `solution_becomes_feature`).
+
+---
+
+## [0.5.3] — 2026-05-21
+
+**Patch.** Framework-layer integrity sweep (UPG-521): framework shape linter + four canonical-example fixes, 66 SLOT_DATA_DRIFT warnings resolved, 212 framework column-drift corrections. No public-API or schema changes, no edge additions.
+
+### Added — Framework Shape Audit (UPG-521)
+
+- **Framework Shape Audit** (`src/frameworks/audit-shape.ts` + `scripts/audit-framework-shape.ts`) — linter that walks `UPG_FRAMEWORKS` and reports five issue kinds:
+  - `PRESENTATION_COLUMN_REFERENCES_ENTITY_TYPE` (blocker) — table column references an entity-type name instead of a declared property.
+  - `PRESENTATION_COLUMN_UNKNOWN_PROPERTY` (warning) — column references an undeclared identifier.
+  - `COMPUTED_EXPRESSION_UNDEFINED_VARIABLE` (blocker) — `computed_properties[*].expression` references an identifier that resolves to nothing.
+  - `SLOT_DATA_DRIFT` (blocker / warning) — `slots[*].entityTypeId` missing from `data.entity_types` (blocker), or vice-versa (warning).
+  - `WHEN_TO_USE_BOILERPLATE` (warning) — `education.when_to_use` bullets >50% identical to other frameworks in the same category.
+- **CI gate** (`src/__tests__/framework-shape-audit.test.ts`) — vitest suite that fails on blocker-class issues for the four showcase frameworks (rice-scoring · kano-model · wardley-map · business-model-canvas) and reports the wider-catalog blocker count as a warn-only signal. Includes negative-test fixtures proving each detector fires.
+
+### Fixed — Framework canonical examples (UPG-521)
+
+- **`rice-scoring`** — `presentation.layout.columns` rewritten to reference the four declared scoring properties (`reach`, `impact`, `confidence`, `effort`) and the `rice_score` computed property, instead of unrelated entity-type names (`metric`, `outcome`, `assumption`, `epic`). Default sort moved to `rice_score desc` so the showcase actually surfaces priorities.
+- **`kano-model`** — (1) `functional_response` / `dysfunctional_response` now declare the standard Kano enum (`i_like_it | i_expect_it | i_am_neutral | i_can_tolerate_it | i_dislike_it`). (2) `delighter_count` / `performance_count` / `must_be_count` / `indifferent_count` declared as `number` so the `satisfaction_coefficient` and `dissatisfaction_coefficient` expressions resolve. (3) Layout changed from generic value/effort `quadrant` to Kano `matrix` (5x5 response classification). (4) `when_to_use` rewritten in Kano-specific terms.
+- **`wardley-map`** — `evolution_stage` (enum: `genesis | custom | product | commodity`) and `visibility` (number 0-1) declared on each entity type that the framework slots over (`capability`, `feature`, `competitor`, `need`). Layout changed from `flow LR` to `quadrant` with `x_axis: evolution_stage` and `y_axis: visibility`. `structure.pattern` and `tags` updated to match.
+- **`business-model-canvas`** — removed the orphan `persona` entry from `data.entity_types` (it had no corresponding slot). The framework now satisfies the slot/data consistency check.
+
+### Fixed — Slot ↔ data.entity_types alignment (UPG-521)
+
+- **65 removals** — incidental entity types removed from `data.entity_types` in frameworks where the type appeared in data but had no corresponding slot and was not referenced in `required_properties` or `computed_properties`. Affected frameworks: `story-map`, `value-proposition-canvas`, `assumption-canvas`, `four-forces-of-progress`, `channel-model-fit`, `validation-board`, `experiment-card`, `empathy-map`, `opportunity-canvas`, `goal-oriented-roadmap`, `story-map-release-slicing`, `competitive-battlecard`, `competitor-profile`, `competitive-response-matrix`, `blue-ocean-strategy`, `jobs-to-be-done-canvas`, `balanced-scorecard`, `business-model-environment`, `raci-matrix`, `retrospective`, `blameless-postmortem`, `model-card`, `agent-evaluation-matrix`, `usability-test-plan`, `mixed-methods-matrix`, `user-needs-matrix`, `jobs-atlas`, `mental-model-diagram`, `user-segmentation-matrix`, `customer-forces-canvas`, `value-proposition-fit`, `voice-of-customer-program`, `nps-analysis-framework`, `customer-advisory-board-framework`, `icp-canvas`, `account-planning`, `monetisation-strategy`, `ge-mckinsey-matrix`.
+- **1 addition** — `opportunity-scoring`: added `Scored Outcomes` slot (`entityTypeId: outcome`) to match the existing `outcome` entry in `data.entity_types` (required because `computed_properties[0].entity_type` references `outcome`).
+- **Post-fix linter baseline**: `SLOT_DATA_DRIFT` → 0 (was 66). All other category counts unchanged.
+
+### Fixed — Column drift bulk repair (UPG-521)
+
+- **212 frameworks across 21 definition files** — `presentation.layout.columns` entries that referenced an entity-type name (e.g. `metric`, `outcome`, `epic`, `feature`, `competitor`, `hypothesis`) instead of a declared property have been corrected. Every column now references either a universal node field (`title`, `description`, `status`), a `data.required_properties` key, or a `data.computed_properties` name. The renderer will no longer receive entity instances in the wrong column slot.
+  - Files touched: `accessibility.ts`, `agentic.ts`, `ai-ml.ts`, `competitive.ts`, `customer-success.ts`, `design.ts`, `devops.ts`, `discovery.ts`, `engineering.ts`, `feedback-voc.ts`, `go-to-market.ts`, `growth.ts`, `metrics.ts`, `planning.ts`, `pricing.ts`, `prioritization.ts`, `program-mgmt.ts`, `strategy.ts`, `team-process.ts`, `user-understanding.ts`, `validation.ts`.
+- **CI gate strengthened** — added a hard-fail assertion that `PRESENTATION_COLUMN_REFERENCES_ENTITY_TYPE` is zero across all 216 frameworks (previously warn-only for non-showcase frameworks). Any regression will fail the build immediately.
+- **`prioritization.ts`** — fixed a smart-quote syntax error (`Won't Have`) that caused the TypeScript transform to fail at compile time.
+
+---
+
+## [0.5.2] — 2026-05-21
+
+**Patch.** Four canonical Wardley edges + two `CapabilityProperties` fields that complete Wardley-style value-chain decomposition. Additive only — no removals, no renames, no breaking shape changes.
+
+### Added
+
+Four edges that complete the `need → capability → capability → feature` Wardley spine and let competitors share that spine:
+
+- **`need_fulfilled_by_capability`** (cross-domain · hierarchy) — verbs `fulfilled_by` / `fulfils`. Anchors a value chain to a user need.
+- **`capability_depends_on_capability`** (strategy · hierarchy) — verbs `depends_on` / `depended_on_by`. The intra-capability value-chain spine. Same-type edge — see "Self-loop note" below.
+- **`capability_implemented_by_feature`** (cross-domain · hierarchy) — verbs `implemented_by` / `implements`. The chain terminates at user-facing features.
+- **`competitor_offers_capability`** (market_intelligence → strategy · cross-domain) — verbs `offers` / `offered_by`. Competitors map onto the same capability vocabulary the team uses, so a Wardley map can compare positions across the same chain.
+
+Two optional `CapabilityProperties` fields driven by the `wardley-map` framework (`packages/upg-spec/src/frameworks/definitions/strategy.ts`):
+
+- **`evolution_stage`** — `'genesis' | 'custom' | 'product' | 'commodity'`. Position on the Wardley evolution axis. Orthogonal to `maturity_level` (which measures the team's internal practice).
+- **`visibility`** — `number` in `[0.0, 1.0]`. Position on the visibility axis from deepest dependency to user-visible anchor. Drives the y-axis of a Wardley map.
+
+### Hierarchy grammar
+
+- `need` gains `capability` as a valid child (cross-domain hierarchy: Wardley starts from a need).
+- `capability` enters `UPG_VALID_CHILDREN` for the first time with `['capability', 'feature']` (self-nesting + implementation).
+
+### Self-loop note
+
+`capability_depends_on_capability` is a same-type edge. The v0.5.0 self-loop guard (UPG-520) refuses `A → A` by default — a value chain by definition has no node depending on itself. `A → B` between distinct capabilities is the supported and intended shape. If a future caller needs a same-node self-loop, that would require a separate opt-in.
+
+### Audit coverage
+
+- Edge count: 850 → 854.
+- `capability` outgoing-edge count: 1 → 3 (`capability_enables_value_stream` + `capability_depends_on_capability` + `capability_implemented_by_feature`).
+- `need` outgoing canonical edges: gains the hierarchy anchor for Wardley chains.
+- `competitor` outgoing-edge count: gains a third typed-vocabulary destination alongside `competitor_feature` and `learning`.
+- `CapabilityProperties`: 3 → 5 declared fields.
+
+---
+
+## [0.5.1] — 2026-05-21
+
+**Patch.** Three single-edge additions that fix documented domain-guide patterns which were unwireable at one hop. Surfaced by the 2026-05-20 systematic domain-wiring audit (Batch C sections C2 + C3). Additive only — no removals, no renames, no breaking shape changes.
+
+### Added
+
+- **`api_contract_contains_api_endpoint`** (engineering · hierarchy) — verbs `contains` / `belongs_to`. API contracts group endpoints by version/protocol; endpoints belong to specific contracts. `api_contract` and `api_endpoint` were both anchored on `service` as siblings — a contract had no path to its endpoints. This adds the natural parent-child wiring.
+- **`postmortem_identifies_root_cause`** (devops · causal) — verbs `identifies` / `identified_by`. The devops "Incident Response Chain" pattern routes through `postmortem → root_cause`, but the existing chain only had `incident → root_cause` and `investigation → root_cause`. `postmortem` had zero outgoing edges. This restores the documented chain.
+- **`postmortem_produces_runbook`** (devops · causal) — verbs `produces` / `produced_by`. Real ops practice: postmortems generate runbook updates as action items. Previously no path between the two existed in the catalog.
+
+### Changed
+
+- **`API Contract Chain` pattern (engineering domain guide)** — middle hop swapped from `service_serves_api_endpoint` to `api_contract_contains_api_endpoint` so the chain reads `service → contract → endpoint → feature` (cleaner narrative; `service_serves_api_endpoint` remains in the catalog for non-contract endpoints).
+- **`Incident Response Chain` pattern (devops domain guide)** — hop 4 swapped from `investigation_revealed_root_cause` (wrong anchor) to `postmortem_identifies_root_cause`; hop 5 added (`postmortem_produces_runbook`) so the chain ends at the action-item layer.
+
+### Audit coverage
+
+- Edge count: 847 → 850.
+- `postmortem` outgoing-edge count: 0 → 2 (no longer a pure terminal).
+- `api_contract` outgoing-edge count: 0 → 1.
+
+---
+
+## [0.5.0] — 2026-05-19
+
+**Co-version anchor.** This release establishes the `0.5.0` line that every `@unified-product-graph/*` sibling package (`mcp-server`, `mcp` (CLI), `cloud-server`, `adapters`, `markdown`, `notion-sync`) co-versions against.
+
+Minor bump: additive surface-area expansion (new entity type, new polymorphic edges, new grammar category). Consumers narrowing on `UPGEntityType` or `UPGEdgeType` unions will see new members.
+
+### Added
+
+- **`person` entity type** — a named, accountable individual. Distinct from `stakeholder` (an interested party: internal, external, investor, regulator) and from `role` (a responsibility slot filled by one or more people). `ent_349` · `team_org` domain · lifecycle-free · containment-free.
+- **`PersonProperties` interface** — `email`, `role_title`, `time_zone`. Identity, addressability, and coordination only. HR-shaped fields (`seniority`, `employment_type`, `start_date`) sit outside the spec — UPG is not an HRIS.
+- **`node_owned_by_person` polymorphic edge** — verbs `owned_by` / `owns`. Fifth member of the universal-ownership family alongside `_team`, `_role`, `_stakeholder`, `_department`.
+- **`node_belongs_to_bounded_context` polymorphic edge** — verbs `belongs_to` / `contains`. Covers DDD building blocks (service, domain_event, domain_entity, aggregate, read_model, api_contract, value_object, command, data_model). Polymorphic count: 10 → 12.
+- **`UPG_CONTAINMENT_FREE_TYPES` set + `isContainmentFreeType()` helper** (`grammar/hierarchy.ts`) — a new grammar category parallel to `UPG_LIFECYCLE_FREE_TYPES`. Containment-free types are referenced by other nodes via edges rather than contained by structural parents. First member: `person`. The G2b hierarchy audit treats absence from `UPG_VALID_CHILDREN` as a defect unless the type is in this set.
+
+### Removed (UPG-509 spec-hygiene pass)
+
+Spec-hygiene pass surfaced by the 2026-05-20 v2 spec-as-observed analysis (Finding 11 — *legacy data + tools drift*) and the systematic domain-wiring audit (Failure Mode 2 — *creation_sequence drift*).
+
+**UPG-509 — Deprecation hygiene.** Every property tagged `@deprecated since="0.4.0" removeIn="0.5.0"` has been removed from `UPG_PROPERTY_SCHEMA`.
+
+Status fields lifted to `UPGBaseNode.status` per `status-convention.md` Rule 1 (12): `strategic_theme.theme_status`, `assumption.validation_status`, `service.service_status`, `api_contract.contract_status`, `technical_debt_item.debt_status`, `investigation.investigation_status`, `fix.fix_status`, `contract.contract_status`, `threat_model.threat_model_status`, `role.role_status`, `team_okr.okr_status`, `partnership.partnership_status`.
+
+Free-text properties replaced by canonical edges (5): `model_comparison.winner`, `service_level_agreement.customer`, `data_product.consumers`, `report.recipients`, `learning.metric`.
+
+Renamed-to-sibling properties (5): `root_cause.confidence → cause_confidence`, `metric.frequency → cadence` (Cadence enum), `key_activity.frequency` / `symptom.frequency` / `churn_reason.frequency` → 4-way frequency split. `MetricFrequency` type alias removed.
+
+### Added (UPG-509 + UPG-516)
+
+- **`UPG_PROPERTY_MIGRATIONS['0.5.0']` block** — 22 migration rules: 12 `lift_property_to_top_level` + 5 `drop_props` (edge-replaced) + 5 `drop_props` (renamed-sibling).
+- **`migrateProductStage` helper + `LEGACY_PRODUCT_STAGES` map** (`catalog/legacy-product-stages.ts`) — authoritative `idea → concept` mapping, append-only, exposed from package root.
+- **`creation_sequence` ↔ registry invariant** (`creation-sequence-matches-registry.test.ts`) — asserts domain sequences cover all registered entities. `scripts/audit-creation-sequence.ts` as CI drift report.
+
+### Fixed (UPG-516 — creation_sequence drift)
+
+11 domains reconciled: 22 missing entities added, 6 foreign entries removed — `strategy`, `engineering`, `devops`, `validation`, `market_intelligence`, `user_research`, `ux_design`, `product_spec`, `growth`, `content`, `customer_success`.
+
+---
+
+## [0.4.3] — 2026-05-18
+
+### Added
+
+- **`constraint` entity (Strategy domain)** — a first-class entity for the structural constraints that Theory of Constraints, Wardley Mapping, and risk frameworks operate on. `ConstraintProperties` carries optional `constraint_kind` (`resource | technical | regulatory | temporal | compliance | other`), `constraint_status` (`binding | advisory | lifted`), `rule_strength`, `source`, `review_date`. Lifecycle-free — `constraint_status` is the state signal.
+- **Five canonical Constraint edges:**
+  - `product_bounded_by_constraint` (hierarchy)
+  - `constraint_constrains_feature` (cross-domain)
+  - `constraint_constrains_initiative` (semantic)
+  - `constraint_constrains_metric` (semantic)
+  - `constraint_owned_by_team` (cross-domain)
+
+The polymorphic `node_constrains_node` edge is unchanged for arbitrary constrain relationships. The new typed edges are the canonical choice when the source is a named `constraint` node.
+
+---
+
+## [0.4.2] — 2026-05-18
+
+### Added
+
+- **`MetricHealth` type and `MetricProperties.metric_health` property** — a universal health signal that applies to every metric regardless of `designation`. Values: `'healthy' | 'at_risk' | 'unhealthy' | 'unknown'`. Orthogonal to lifecycle and to `guardrail_status`. Renderers should read `metric_health` for the universal lifecycle-dot signal across all metrics, with `guardrail_status` as a breach-specific overlay for guardrails.
+
+---
+
+## [0.4.1] — 2026-05-16
+
+### Fixed
+
+- **Resolver pair collisions resolved deterministically.** `UPG_EDGE_PAIR_MAP` was previously a `Record<string, UPGEdgeType>`, which silently dropped every edge but the last on the 35 `(source, target)` pairs where multiple edges share endpoints. `resolveContainmentEdge` therefore returned a non-deterministic last-wins answer.
+  - `UPG_EDGE_PAIR_MAP` is now `Record<string, UPGEdgeType[]>` — every catalogued edge for a pair is preserved.
+  - New `pickCanonicalEdge(source, target, hint?)` applies a deterministic classification-ranked policy: hierarchy ≻ causal ≻ semantic ≻ cross-domain. Declaration order breaks ties inside a classification.
+  - New `resolveAllEdges(source, target): UPGEdgeType[]` returns the full candidate set.
+  - `resolveContainmentEdge` now delegates to `pickCanonicalEdge(source, target, 'hierarchy')`.
+
+### Added
+
+Nine cross-domain edges:
+
+- **Testing → Bug:** `regression_test_addresses_bug`.
+- **DevOps:** `incident_affects_feature`, `release_strategy_used_by_deployment`.
+- **User Research linkage:** `participant_voiced_quote`, `research_question_addressed_by_insight`, `survey_response_evidences_insight`.
+- **Engineering:** `feature_flag_gates_feature`, `data_model_persisted_in_database_schema`, `read_model_projects_aggregate`.
+
+### Audit coverage
+
+- Edge count: 831 → 840.
+- All 35 pair collisions now resolve non-null and deterministically via `pickCanonicalEdge`.
+
+---
+
+## [0.4.0] — 2026-05-12
+
+First public release of `@unified-product-graph/core`.
+
+### Removed
+
+**Narrative-string properties superseded by canonical edges.** Four properties whose canonical edges already shipped are removed in v0.4.0 — carrying the string twin into the first public version would cement a documented inconsistency.
+
+- `ValueProposition.jobs_addressed: string` — use `value_proposition_addresses_job`.
+- `ValueProposition.pain_reliefs: string` — use `value_proposition_solves_need` (a pain is a `need` with `valence='pain'`).
+- `ValueProposition.gain_creators: string` — use `value_proposition_delivers_outcome`.
+- `MetricProperties.guardrail_for: string` — use `metric_guards_metric`.
+
+**`MetricProperties` cleanup (14 properties total).** Six quality signals migrate to the `metric_quality_assessment` entity. Three proxy fields migrate to `metric_quality_assessment.proxy_*`. Five external-sync fields move to tool-extension namespaces (e.g. `extensions.<tool>.metric_sync.*`) — these were always tool runtime state, never portable spec data.
+
+- Quality: `quality_correlated`, `quality_actionable`, `quality_sensitive`, `quality_comparative`, `quality_related`, `quality_score`.
+- Proxy: `proxy_reason`, `proxy_confidence`, `proxy_alternatives`.
+- External sync: `external_metric_id`, `external_query`, `last_synced_at`, `sync_status`, `sync_error`.
+
+The runtime migrator (`grammar/migrations.ts`) retains the legacy drop rule, so older graphs round-trip cleanly — `metric` nodes carrying any of these 14 fields have them stripped on load.
+
+### Added
+
+- **Classification taxonomy.** Two new entity types — `classification_axis` and `classification_value` — for 2-axis paradigm matrices and competitive-landscape comparisons. Six new edge types wire them to `competitive_analysis`, `competitor`, and `persona`. Three new property shapes: `ClassificationCommitment`, `ClassificationCapability`, `EmptyCell` (with `rationale_kind: 'structural' | 'ideological' | 'opportunity'`). `validate_graph` enforces referential integrity on `empty_cells`. Proof-of-spec fixture at `spec/examples/cms-field-guide.upg`.
+- **`Cadence` primitive** — canonical recurrence enum `'continuous' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'yearly' | 'on_demand' | 'other'`. Replaces ad-hoc free-form `frequency: string` and `*cadence: string` properties.
+- **Four-way frequency split** on entities whose recurrence is an axis of analysis: `frequency_count?: number`, `frequency_period?: Duration`, `frequency_rating?: 'rare' | 'occasional' | 'regular' | 'constant' | 'other'`, `cadence?: Cadence`.
+- **`RootCauseProperties.cause_confidence`** — renamed replacement for `confidence` (3-tier: `'hypothesised' | 'likely' | 'confirmed'`). Disambiguates from the spec-wide `UPGAssessment`-typed `confidence` axis.
+- **Canonical edges replacing narrative-string properties:** `learning_observed_on_metric`, `model_comparison_winner_is_ai_model`, `data_product_consumed_by_service`, `report_distributed_to_team`, `service_level_agreement_covers_account`.
+- **`*_status` convention doc** at `src/properties/status-convention.md` — codifies the three axes that `*_status` properties span (lifecycle / runtime state / event outcome) and the rules for choosing the right canonical slot.
+- **`property-schema-coverage` regression test** — walks every `*Properties` interface via the TypeScript Compiler API and asserts each declared property appears in `UPG_PROPERTY_SCHEMA`, including full union-member coverage for string-literal-union properties.
+- **`UPG_VERSION` vs `UPG_FORMAT_VERSION`** — `UPG_VERSION` (currently `'0.5.0'`) is the catalogue version (entities, edges, properties). `UPG_FORMAT_VERSION` (currently `'0.4.0'`) is the on-disk `.upg` document format version. The format evolves more slowly than the catalogue.
+
+### Changed
+
+- **Property-registry generator migrated to the TypeScript Compiler API.** Closes a silent-drop bug class in the previous regex-based generator: union-typed properties, type-alias references, and JSDoc tag text now extract correctly.
+
+---
+
+## Pre-0.4 history
+
+The schema iterated through internal 0.1.x–0.3.x phases before public 0.4.0 release. Those entries are preserved in the source repository for archival purposes but are not part of the public changelog — every breaking change they introduced is reflected in the 0.4.0 baseline above.