@unified-product-graph/core 0.19.0 → 0.20.1

package/CHANGELOG.md

@@ -7,6 +7,36 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [0.20.1] - 2026-07-04
+
+**Three edges close the alignment-sheet seam: an initiative can now reach directly into the OKR ladder and the roadmap, and a strategic pillar gets its own north-star metric.** Composed flat region surfaces spanning org/team/product altitudes surfaced two gaps in the strategic cascade: an initiative's only path to a key result or a roadmap theme ran through its parent `strategic_theme`, and `strategic_pillar` — durable, multi-year, org-wide — had no measuring metric of its own, unlike every other rung of the cascade (`objective_measured_by_metric`, `key_result_quantified_by_metric`). Additive; no breaking change.
+
+### Added
+- **`initiative_advances_key_result`** — `initiative` → `key_result`, causal (intra-strategy execution, not cross-domain), cross-product-eligible. Extends the curated OKR laddering DAG that `objective_measured_by_metric` / `key_result_quantified_by_metric` are already part of.
+- **`initiative_delivered_via_roadmap_theme`** — `initiative` → `roadmap_theme`, semantic, within-graph. Mirrors `strategic_theme_realised_by_roadmap_theme`: a cross-reference between the strategy spine and the roadmap spine, not containment, so initiatives can reach the roadmap without routing through their parent theme.
+- **`strategic_pillar_measured_by_metric`** — `strategic_pillar` → `metric`, hierarchy, cross-product-eligible. Mirrors `objective_measured_by_metric` one level up the cascade; `metric` joins `strategic_pillar`'s valid children.
+
+---
+
+## [0.20.0] - 2026-07-04
+
+**A cadence layer for the product-delivery region: one self-nesting `planning_cycle` entity models sprints, iterations, quarters, program increments, and cooldowns, so a Jira or Linear export round-trips its time-boxes losslessly.** The delivery region could describe what ships (feature → epic → story → task) and what governs it (release, roadmap, theme), but had no home for the interval work flows *through*. This release mints `planning_cycle` — a named, dated, self-nesting interval discriminated by `cadence_kind` (period / iteration / buffer) rather than a type per methodology — plus the edges that schedule work into it and scope objectives and themes to it. It also closes the smaller structural gaps a Jira ∪ Linear import hits: polymorphic issue links, a dual-band `workflow_state` that preserves an imported tool's raw states without displacing the canonical `status`, and the task-level planning fields lifted onto `user_story`. Additive; no breaking change.
+
+### Added
+- **`planning_cycle` entity** (`proposed`) — the cadence axis. A self-nesting container in the `product_spec` domain / `product_delivery` region, `portfolio_shared`, lifecycle `planned → active → closed`. Properties: `cadence_kind` (period / iteration / buffer), `cadence_label`, `starts_on`, `ends_on`, `sequence`, `goal`, `appetite`. One type with a `cadence_kind` discriminator spans sprint / iteration / quarter / program-increment / cooldown; self-nesting handles the granularity ladder (a PI contains iterations; a cycle contains its cooldown).
+- **Core cadence edges** — `planning_cycle_contains_planning_cycle` (self-nesting containment), `objective_scoped_to_planning_cycle` and `strategic_theme_scoped_to_planning_cycle` (OKR / theme cycle-scoping, provisional cross-scope), `planning_cycle_schedules_user_story` (deliberate-only work scheduling — a story keeps its feature/epic containment parent), and `product_runs_planning_cycle` (top-level attach).
+- **Polymorphic work-item issue links** — `work_item_blocks_work_item`, `work_item_relates_to_work_item`, `work_item_duplicates_work_item` over the work-item set {feature, epic, user_story, task, bug}, all deliberate-only.
+- **Dual-band `workflow_state`** — a freeform `workflow_state` plus an optional `workflow_state_category` on the work-item entities, so an imported custom workflow round-trips losslessly without displacing canonical `status` as the reasoning axis.
+- **`planning-cycle-without-scheduled-work`** anti-pattern (low severity) — a cadence box that neither schedules work nor nests a sub-cycle.
+
+### Changed
+- **`user_story` gains `priority`, `effort`, `assignee`, `due_date`** — the story is now a first-class plannable unit alongside `task`, matching the tools where the story / issue is the estimated-and-assigned atom.
+
+### Deprecated
+- **`strategic_theme.time_horizon`** — promote the bounded period to a `planning_cycle` node linked with `strategic_theme_scoped_to_planning_cycle`. The property is kept and readable; removal is a later major. `strategic_pillar.time_horizon` (a durable, open-ended pillar horizon, not a dated cycle) stays as-is.
+
+---
+
 ## [0.19.0] - 2026-07-04
 
 **The MCP surface consolidates from 139 tools to 93 (+ 5 prompts): the static-spec introspection cluster folds into four faceted reads, and five procedural routers become skills.** The spec catalogue had accreted 45 near-identical `list_*` / `get_*` reads plus five routers — a surface an agent had to scan linearly before it could choose. This release collapses the reads into four facets and retires the routers, leaving the 89 write and live-graph-read verbs untouched. A parity gate (`retired-tools.json` + a byte-equality test wired as a prepublish stage) proves every retired tool's data is still reachable and identical through the facets, on both the local and cloud servers — which licenses a clean break with no deprecation window. Both servers' instructions gain a methodology preamble (the SEE → THINK → ACT → LEARN working loop) so the surface conveys *how to work*, not only *what exists*. Breaking. Local 139 → 93; cloud 100 → 54.

package/README.md

@@ -7,7 +7,7 @@
 
 The TypeScript core for the **Unified Product Graph (UPG)**, an open specification that gives product tools a shared vocabulary for entities, edges, and frameworks.
 
-319 entity types across 37 domains. 1026 typed edges. 46 canonical framework definitions, with more added as each is reviewed.
+320 entity types across 37 domains. 1037 typed edges. 46 canonical framework definitions, with more added as each is reviewed.
 
 ## Install
 

package/dist/index.cjs

@@ -347,7 +347,7 @@ var UPG_DOMAINS = [
   {
     id: "product_spec",
     label: "Product Specification",
-    description: "What you are building and shipping. Feature areas group related capabilities. Features, epics, and user stories break work down. Acceptance criteria define done. Tasks and bugs track execution. Releases and changelogs mark what shipped. Roadmaps and roadmap items plan what comes next. Roadmap themes group roadmap work around the customer problem it solves, one level down from the strategic themes in Strategy. Translates Strategy into Engineering and tracks delivery through Program Management.",
+    description: "What you are building and shipping. Feature areas group related capabilities. Features, epics, and user stories break work down. Acceptance criteria define done. Tasks and bugs track execution. Releases and changelogs mark what shipped. Roadmaps and roadmap items plan what comes next. Roadmap themes group roadmap work around the customer problem it solves, one level down from the strategic themes in Strategy. Planning cycles are the cadence axis: the named, dated, self-nesting intervals (sprint, iteration, quarter, program increment, cooldown) that work is scheduled through. Translates Strategy into Engineering and tracks delivery through Program Management.",
     types: [
       "feature",
       "feature_area",
@@ -360,7 +360,8 @@ var UPG_DOMAINS = [
       "roadmap",
       "roadmap_item",
       "roadmap_theme",
-      "changelog"
+      "changelog",
+      "planning_cycle"
     ]
   },
   {
@@ -938,6 +939,14 @@ var UPG_ENTITY_META = [
   { name: "theme", type_id: "ent_080", maturity: "deprecated", since: "0.1.0", deprecated_in: "0.9.0", replacement: "roadmap_theme" },
   { name: "roadmap_theme", type_id: "ent_351", maturity: "stable", since: "0.1.0" },
   { name: "changelog", type_id: "ent_081", maturity: "stable", since: "0.1.0" },
+  // (0.20.0) The cadence axis: a named, dated interval that work flows through
+  // and which nests (a program-increment contains iterations; a cycle contains
+  // its cooldown). One self-nesting type with a `cadence_kind` discriminator
+  // spans sprint / iteration / quarter / PI / cooldown rather than minting a
+  // type per methodology. `portfolio_shared` because a coarse cycle is an
+  // org-shared interval an objective in a rollup graph and a story in a product
+  // graph both schedule into.
+  { name: "planning_cycle", type_id: "ent_358", maturity: "proposed", since: "0.20.0", portfolio_shared: true },
   // ── Engineering ──
   { name: "bounded_context", type_id: "ent_082", maturity: "stable", since: "0.1.0" },
   { name: "service", type_id: "ent_083", maturity: "stable", since: "0.1.0" },
@@ -1554,6 +1563,10 @@ var UPG_EDGE_CATALOG = {
   strategic_pillar_enables_capability: { forward_verb: "enables", reverse_verb: "enabled_by", classification: "hierarchy", source_type: "strategic_pillar", target_type: "capability" },
   strategic_pillar_delivers_value_stream: { forward_verb: "delivers", reverse_verb: "delivered_by", classification: "hierarchy", source_type: "strategic_pillar", target_type: "value_stream" },
   strategic_pillar_decided_via_decision: { forward_verb: "decided_via", reverse_verb: "decided_for", classification: "hierarchy", source_type: "strategic_pillar", target_type: "decision" },
+  // 0.20.1: the durable pillar's own north-star, mirroring objective_measured_by_metric
+  // one level up the cascade. A strategic_pillar is multi-year and org-wide, so its
+  // measuring metric is portfolio-shared just like the pillar itself.
+  strategic_pillar_measured_by_metric: { forward_verb: "measured_by", reverse_verb: "measures", classification: "hierarchy", source_type: "strategic_pillar", target_type: "metric", cross_product_eligible: true },
   strategic_theme_pursues_initiative: { forward_verb: "pursues", reverse_verb: "pursued_under", classification: "hierarchy", source_type: "strategic_theme", target_type: "initiative", cross_product_eligible: true },
   // v0.9.0 (UPG-660): the soft bridge from the annual strategy focus area to the
   // roadmap grouping that realises it. Semantic, NOT hierarchy: strategic_theme and
@@ -1586,6 +1599,17 @@ var UPG_EDGE_CATALOG = {
   strategic_theme_measured_by_key_result: { forward_verb: "measured_by", reverse_verb: "measures", classification: "causal", source_type: "strategic_theme", target_type: "key_result", cross_product_eligible: true },
   strategic_theme_contains_objective: { forward_verb: "contains", reverse_verb: "rolls_up_to", classification: "hierarchy", source_type: "strategic_theme", target_type: "objective", cross_product_eligible: true },
   initiative_assumes_assumption: { forward_verb: "assumes", reverse_verb: "assumed_by", classification: "hierarchy", source_type: "initiative", target_type: "assumption" },
+  // 0.20.1: the G6 alignment-sheet bridge edges — an initiative reaches directly
+  // into the OKR ladder and the roadmap, rather than only via its parent
+  // strategic_theme. `advances_key_result` is intra-strategy execution (both
+  // ends sit in the strategy domain), so causal not cross-domain; the KR is
+  // portfolio-shared like the initiative, so the pair is cross-product-eligible.
+  initiative_advances_key_result: { forward_verb: "advances", reverse_verb: "advanced_by", classification: "causal", source_type: "initiative", target_type: "key_result", cross_product_eligible: true },
+  // `delivered_via_roadmap_theme` mirrors strategic_theme_realised_by_roadmap_theme:
+  // a semantic cross-reference between the strategy spine and the roadmap spine,
+  // not containment. roadmap_theme is not portfolio-shared, so this stays
+  // within-graph (no cross_product_eligible flag).
+  initiative_delivered_via_roadmap_theme: { forward_verb: "delivered_via", reverse_verb: "delivers", classification: "semantic", source_type: "initiative", target_type: "roadmap_theme" },
   initiative_drives_outcome: { forward_verb: "drives", reverse_verb: "driven_by", classification: "cross-domain", source_type: "initiative", target_type: "outcome", cross_product_eligible: true },
   capability_enables_value_stream: { forward_verb: "enables", reverse_verb: "enabled_by", classification: "cross-domain", source_type: "capability", target_type: "value_stream" },
   // v0.5.2 (UPG-528): three capability-anchored edges that complete the
@@ -1621,6 +1645,8 @@ var UPG_EDGE_CATALOG = {
   product_builds_feature: { forward_verb: "builds", reverse_verb: "built_by", classification: "hierarchy", source_type: "product", target_type: "feature" },
   product_ships_via_release: { forward_verb: "ships_via", reverse_verb: "ships", classification: "hierarchy", source_type: "product", target_type: "release" },
   product_plans_via_roadmap: { forward_verb: "plans_via", reverse_verb: "plans_for", classification: "hierarchy", source_type: "product", target_type: "roadmap" },
+  // (0.20.0) top-level attach for the cadence axis, mirroring product_plans_via_roadmap.
+  product_runs_planning_cycle: { forward_verb: "runs", reverse_verb: "run_by", classification: "hierarchy", source_type: "product", target_type: "planning_cycle" },
   product_categorises_by_roadmap_theme: { forward_verb: "categorises_by", reverse_verb: "categorises", classification: "hierarchy", source_type: "product", target_type: "roadmap_theme" },
   feature_area_contains_feature: { forward_verb: "contains", reverse_verb: "belongs_to", classification: "hierarchy", source_type: "feature_area", target_type: "feature" },
   feature_area_contains_feature_area: { forward_verb: "contains", reverse_verb: "belongs_to", classification: "hierarchy", source_type: "feature_area", target_type: "feature_area" },
@@ -1659,6 +1685,33 @@ var UPG_EDGE_CATALOG = {
   roadmap_item_references_feature: { forward_verb: "references", reverse_verb: "referenced_by", classification: "cross-domain", source_type: "roadmap_item", target_type: "feature" },
   feature_decomposes_into_task: { forward_verb: "decomposes_into", reverse_verb: "implements", classification: "hierarchy", source_type: "feature", target_type: "task" },
   task_has_subtask: { forward_verb: "has_subtask", reverse_verb: "is_subtask_of", classification: "hierarchy", source_type: "task", target_type: "task" },
+  // ── Planning cadence (0.20.0) ────────────────────────────────────────────────
+  // The cadence axis. E1 self-nests the interval (a program-increment contains
+  // iterations; a cycle contains its cooldown), mirroring team_contains_team.
+  planning_cycle_contains_planning_cycle: { forward_verb: "contains", reverse_verb: "belongs_to", classification: "hierarchy", source_type: "planning_cycle", target_type: "planning_cycle" },
+  // E3: scheduling work into a cycle is a deliberate authoring act, not a
+  // containment nesting — user_story keeps its feature/epic parent and is merely
+  // referenced by the cycle. deliberate_only so the generic-inference chokepoints
+  // never auto-materialise it.
+  planning_cycle_schedules_user_story: { forward_verb: "schedules", reverse_verb: "scheduled_in", classification: "semantic", source_type: "planning_cycle", target_type: "user_story", deliberate_only: true },
+  // E2: the OKR cycle-scoping anchor. objective -> planning_cycle. planning_cycle
+  // is portfolio_shared, so this passes the cross-scope gate and ships as
+  // PROVISIONAL (allowed cross-product with a write-time warning, self-maintaining,
+  // never added to the curated set) rather than carrying a cross_product_eligible
+  // flag, which would make it curated. Eligibility is permission, not obligation.
+  objective_scoped_to_planning_cycle: { forward_verb: "scoped_to", reverse_verb: "scopes", classification: "semantic", source_type: "objective", target_type: "planning_cycle" },
+  // F: the promoted `strategic_theme.time_horizon`. Same shape as E2 — a theme's
+  // bounded period becomes a scoping edge onto a shared, dated, nestable interval.
+  // Provisional (planning_cycle portfolio_shared). The property stays @deprecated.
+  strategic_theme_scoped_to_planning_cycle: { forward_verb: "scoped_to", reverse_verb: "scopes", classification: "semantic", source_type: "strategic_theme", target_type: "planning_cycle" },
+  // Gap 2 — polymorphic issue links over the work-item set {feature, epic,
+  // user_story, task, bug}. Endpoint-polymorphic (node -> node, registered in
+  // UPG_POLYMORPHIC_EDGE_KEYS) so one edge covers every level teams link at; the
+  // `work_item_` key names the intended semantic domain. All deliberate_only: an
+  // issue link is authored, never inferred from hierarchy.
+  work_item_blocks_work_item: { forward_verb: "blocks", reverse_verb: "blocked_by", classification: "causal", source_type: "node", target_type: "node", deliberate_only: true },
+  work_item_relates_to_work_item: { forward_verb: "relates_to", reverse_verb: "relates_to", classification: "semantic", source_type: "node", target_type: "node", deliberate_only: true },
+  work_item_duplicates_work_item: { forward_verb: "duplicates", reverse_verb: "duplicated_by", classification: "semantic", source_type: "node", target_type: "node", deliberate_only: true },
   // 2.3 Legal Domain
   product_owned_by_legal_entity: { forward_verb: "owned_by", reverse_verb: "owns", classification: "hierarchy", source_type: "product", target_type: "legal_entity" },
   legal_entity_protects_ip_asset: { forward_verb: "protects", reverse_verb: "protected_by", classification: "hierarchy", source_type: "legal_entity", target_type: "ip_asset" },
@@ -3442,7 +3495,13 @@ var UPG_POLYMORPHIC_EDGE_KEYS = [
   // Framework exercises (an exercise can include any entity type)
   "framework_exercise_includes_node",
   // Universal classification (any node classified against a classification_value)
-  "node_classified_as_classification_value"
+  "node_classified_as_classification_value",
+  // Work-item issue links (0.20.0): endpoint-polymorphic over the work-item set
+  // {feature, epic, user_story, task, bug}. The `work_item_` key names the
+  // intended semantic domain; the endpoints are the `node` wildcard.
+  "work_item_blocks_work_item",
+  "work_item_relates_to_work_item",
+  "work_item_duplicates_work_item"
 ];
 var _POLY_KEY_SET = new Set(UPG_POLYMORPHIC_EDGE_KEYS);
 function isPolymorphicEdge(key) {
@@ -3632,6 +3691,7 @@ var UPG_VALID_CHILDREN = {
     "release",
     "roadmap",
     "roadmap_theme",
+    "planning_cycle",
     // Engineering
     "bounded_context",
     "code_repository",
@@ -3809,7 +3869,11 @@ var UPG_VALID_CHILDREN = {
   //     That success-measurement asymmetry is the load-bearing distinction.
   vision: ["mission"],
   mission: ["strategic_pillar"],
-  strategic_pillar: ["strategic_theme", "capability", "value_stream", "decision"],
+  // 0.20.1: metric added as a strategic_pillar child, backing
+  // strategic_pillar_measured_by_metric (hierarchy) — the pillar's own
+  // north-star, mirrored from objective: ['key_result', 'metric', ...] one
+  // level down the cascade.
+  strategic_pillar: ["strategic_theme", "capability", "value_stream", "decision", "metric"],
   // v0.5.4 (UPG-511): objectives are the specific quarterly bets *within* a
   // strategic theme. The theme is the multi-quarter focus area; objectives are
   // subordinate. Pairs with `strategic_theme_contains_objective` in the edge
@@ -3900,6 +3964,13 @@ var UPG_VALID_CHILDREN = {
   epic: ["user_story"],
   user_story: ["acceptance_criterion"],
   task: ["task"],
+  // planning_cycle (0.20.0): the cadence axis self-nests (a program-increment
+  // contains iterations; a cycle contains its cooldown) via
+  // planning_cycle_contains_planning_cycle. It does NOT contain user_story as a
+  // child: scheduling work into a cycle is the semantic, deliberate-only
+  // planning_cycle_schedules_user_story edge, so a story keeps its feature/epic
+  // containment parent and is merely referenced by the cycle.
+  planning_cycle: ["planning_cycle"],
   // ── Engineering hierarchy ───────────────────────────────────────────────────
   bounded_context: [
     "service",
@@ -6543,6 +6614,16 @@ var SPECIFICATION_LIFECYCLE = {
     }
   ]
 };
+var PLANNING_CYCLE_LIFECYCLE = {
+  entity_type: "planning_cycle",
+  initial_phase: "planned",
+  terminal_phases: ["closed"],
+  phases: [
+    { id: "planned", label: "Planned", description: "The cycle is being shaped: dates set, goal written, work scheduled into it. It has not started yet.", transitions_to: ["active"] },
+    { id: "active", label: "Active", description: "The team is inside the interval; work is flowing through it.", transitions_to: ["closed"] },
+    { id: "closed", label: "Closed", description: "The interval has ended. Scheduled work has shipped, carried over, or been dropped. May reopen if the team extends or reruns it.", transitions_to: ["active"] }
+  ]
+};
 var UPG_LIFECYCLES = [
   // Product (root)
   PRODUCT_LIFECYCLE,
@@ -6586,6 +6667,7 @@ var UPG_LIFECYCLES = [
   TASK_LIFECYCLE,
   BUG_LIFECYCLE,
   ROADMAP_ITEM_LIFECYCLE,
+  PLANNING_CYCLE_LIFECYCLE,
   IP_ASSET_LIFECYCLE,
   CONTRACT_LIFECYCLE,
   DESIGN_CONCEPT_LIFECYCLE,
@@ -10768,7 +10850,9 @@ var UPG_PROPERTY_SCHEMA = {
     priority: { type: "string", enum: ["urgent", "high", "medium", "low", "none"], description: "Urgency relative to other work. Independent of `bug_severity` (a critical bug can have low priority if rare)." },
     assignee: { type: "string", description: "Assigned person. Promote to a `node_owned_by_person` edge if ownership must be queryable." },
     due_date: { type: "string", description: "ISO date due. Often tied to a release gate or SLA." },
-    labels: { type: "string[]", description: "Free-form classification tags. Applied uniformly across work item types." }
+    labels: { type: "string[]", description: "Free-form classification tags. Applied uniformly across work item types." },
+    workflow_state: { type: "string", description: 'The source tool\'s raw custom workflow state, verbatim and opaque (e.g. "In Review", "QA", "Needs Triage"). Non-canonical and never reasoned over: it exists to round-trip an import losslessly. Map it onto a canonical bucket with `workflow_state_category`; canonical `status` stays the sole reasoning axis.' },
+    workflow_state_category: { type: "string", description: 'Canonical bucket the raw `workflow_state` maps onto for reasoning (a source "In Review" and "QA" might both map to a verification phase). Optional companion to `workflow_state`: it lets a graph reason over an imported custom workflow without promoting the raw label to `status`.' }
   },
   // BuildArtifactProperties: Build artifact.
   build_artifact: {
@@ -11422,7 +11506,9 @@ var UPG_PROPERTY_SCHEMA = {
     priority: { type: "string", enum: ["urgent", "high", "medium", "low", "none"], description: "Task-level priority" },
     owner: { type: "string", description: "Responsible person or team. Promote to a `node_owned_by_person` edge if ownership must be queryable." },
     start_date: { type: "string", description: "ISO date work begins" },
-    target_date: { type: "string", description: "ISO date work completes" }
+    target_date: { type: "string", description: "ISO date work completes" },
+    workflow_state: { type: "string", description: 'The source tool\'s raw custom workflow state, verbatim and opaque (e.g. "In Review", "QA", "Needs Triage"). Non-canonical and never reasoned over: it exists to round-trip an import losslessly. Map it onto a canonical bucket with `workflow_state_category`; canonical `status` stays the sole reasoning axis.' },
+    workflow_state_category: { type: "string", description: 'Canonical bucket the raw `workflow_state` maps onto for reasoning (a source "In Review" and "QA" might both map to a verification phase). Optional companion to `workflow_state`: it lets a graph reason over an imported custom workflow without promoting the raw label to `status`.' }
   },
   // ErrorBudgetProperties: Error budget.
   error_budget: {
@@ -11602,7 +11688,9 @@ var UPG_PROPERTY_SCHEMA = {
     owner: { type: "string", description: "Responsible person or team. Promote to a `node_owned_by_person` edge if ownership must be queryable." },
     start_date: { type: "string", description: "ISO date work begins" },
     target_date: { type: "string", description: "ISO date work completes" },
-    health: { type: "string", enum: ["on_track", "at_risk", "off_track"], description: "Delivery health" }
+    health: { type: "string", enum: ["on_track", "at_risk", "off_track"], description: "Delivery health" },
+    workflow_state: { type: "string", description: 'The source tool\'s raw custom workflow state, verbatim and opaque (e.g. "In Review", "QA", "Needs Triage"). Non-canonical and never reasoned over: it exists to round-trip an import losslessly. Map it onto a canonical bucket with `workflow_state_category`; canonical `status` stays the sole reasoning axis.' },
+    workflow_state_category: { type: "string", description: 'Canonical bucket the raw `workflow_state` maps onto for reasoning (a source "In Review" and "QA" might both map to a verification phase). Optional companion to `workflow_state`: it lets a graph reason over an imported custom workflow without promoting the raw label to `status`.' }
   },
   // FeatureAreaProperties: A structural grouping of related features within a product.
   feature_area: {
@@ -12522,6 +12610,16 @@ var UPG_PROPERTY_SCHEMA = {
     conversion_rate: { type: "number", description: "Percentage of deals that advance from this stage", modifier: "snapshot" },
     avg_days_in_stage: { type: "number", description: "Average number of days deals spend in this stage" }
   },
+  // PlanningCycleProperties: Planning cycle: a named, dated interval work flows through, which nests.
+  planning_cycle: {
+    cadence_kind: { type: "string", enum: ["period", "iteration", "buffer"], description: "Methodology-neutral granularity of this interval. `period` is a coarse container (quarter / PI / OKR-cycle scale); `iteration` is a fine execution box (sprint / cycle); `buffer` is between-box slack (cooldown). Required: it is the discriminator that lets one type stand in for every methodology." },
+    cadence_label: { type: "string", description: 'The source methodology term verbatim ("sprint", "cycle", "PI", "quarter", "cooldown"). The dual-band label: `cadence_kind` is the canonical granularity reasoned over; `cadence_label` preserves what the team actually calls it.' },
+    starts_on: { type: "string", description: "ISO date the interval opens. A cycle is concretely dated, unlike a coarse `time_horizon` label." },
+    ends_on: { type: "string", description: "ISO date the interval closes." },
+    sequence: { type: "number", description: "The cycle / iteration number (e.g. Sprint 47, PI 3)." },
+    goal: { type: "string", description: "The interval's goal or focus: what this cadence box is for." },
+    appetite: { type: "string", description: 'Shape Up appetite: the fixed time budget a cycle is willing to spend on a bet (e.g. "6 weeks", "2 weeks").' }
+  },
   // PlaybookProperties: Customer success playbook.
   playbook: {
     playbook_type: { type: "string", enum: ["onboarding", "expansion", "renewal", "rescue", "other"], description: "Scenario this playbook addresses" },
@@ -13073,7 +13171,7 @@ var UPG_PROPERTY_SCHEMA = {
   // StrategicThemeProperties: StrategicTheme entity.
   strategic_theme: {
     owner: { type: "string", description: "Owning person or team. Promote to a `node_owned_by_person` edge if ownership must be queryable." },
-    time_horizon: { type: "string", description: 'Bounded period this theme is active (a theme is time-bound, within a pillar). @example "Q1 2026", "FY26"' },
+    time_horizon: { type: "string", description: 'Bounded period this theme is active (a theme is time-bound, within a pillar). @deprecated since 0.20.0. Promote the period to a `planning_cycle` node and link it with the `strategic_theme_scoped_to_planning_cycle` edge, which points at a shared, dated, nestable interval instead of a drifting per-theme string. Kept (not removed) for back-compat; removal is a later major. `strategic_pillar.time_horizon` stays as-is (a durable pillar horizon is genuinely open-ended, not a dated cycle). @example "Q1 2026", "FY26"' },
     description: { type: "string", description: "Short narrative of this time-bound thrust within its pillar" },
     scope: { type: "string", description: "What the theme explicitly includes or excludes" }
   },
@@ -13169,7 +13267,9 @@ var UPG_PROPERTY_SCHEMA = {
     effort: { type: "string", description: 'Effort estimate (e.g. "2h", "1d", "3 points"). Use a consistent unit within your team.' },
     priority: { type: "string", enum: ["urgent", "high", "medium", "low", "none"], description: "Relative importance against other tasks" },
     due_date: { type: "string", description: "ISO date due. Typically bounded by the containing story's due date." },
-    labels: { type: "string[]", description: "Free-form classification tags. Applied uniformly across work item types." }
+    labels: { type: "string[]", description: "Free-form classification tags. Applied uniformly across work item types." },
+    workflow_state: { type: "string", description: 'The source tool\'s raw custom workflow state, verbatim and opaque (e.g. "In Review", "QA", "Needs Triage"). Non-canonical and never reasoned over: it exists to round-trip an import losslessly. Map it onto a canonical bucket with `workflow_state_category`; canonical `status` stays the sole reasoning axis.' },
+    workflow_state_category: { type: "string", description: 'Canonical bucket the raw `workflow_state` maps onto for reasoning (a source "In Review" and "QA" might both map to a verification phase). Optional companion to `workflow_state`: it lets a graph reason over an imported custom workflow without promoting the raw label to `status`.' }
   },
   // TeamProperties: Team entity.
   team: {
@@ -13384,7 +13484,13 @@ var UPG_PROPERTY_SCHEMA = {
     as_a: { type: "string", description: '"As a [persona], \u2026". Free-text persona name or slug ref.' },
     i_want_to: { type: "string", description: "Capability or action the persona wants." },
     so_that: { type: "string", description: "Benefit or outcome the persona expects." },
-    text: { type: "string", description: "Free-form story text. Used as a single-line rendered view." }
+    text: { type: "string", description: "Free-form story text. Used as a single-line rendered view." },
+    assignee: { type: "string", description: "Assigned person. Promote to a `node_owned_by_person` edge if ownership must be queryable." },
+    effort: { type: "string", description: 'Effort estimate (e.g. "2h", "1d", "3 points"). Use a consistent unit within your team.' },
+    priority: { type: "string", enum: ["urgent", "high", "medium", "low", "none"], description: "Relative importance against other stories. Lifted onto user_story (0.20.0) so the story is a first-class plannable unit alongside task, matching Jira/Linear where the story/issue is the estimated-and-assigned atom." },
+    due_date: { type: "string", description: "ISO date due. Typically bounded by the release or planning_cycle the story is scheduled into." },
+    workflow_state: { type: "string", description: 'The source tool\'s raw custom workflow state, verbatim and opaque (e.g. "In Review", "QA", "Needs Triage"). Non-canonical and never reasoned over: it exists to round-trip an import losslessly. Map it onto a canonical bucket with `workflow_state_category`; canonical `status` stays the sole reasoning axis.' },
+    workflow_state_category: { type: "string", description: 'Canonical bucket the raw `workflow_state` maps onto for reasoning (a source "In Review" and "QA" might both map to a verification phase). Optional companion to `workflow_state`: it lets a graph reason over an imported custom workflow without promoting the raw label to `status`.' }
   },
   // ValueObjectProperties: DDD value object.
   value_object: {
@@ -20030,6 +20136,7 @@ var ENTITY_EMOJI = {
   persona: "\u{1F3AD}",
   pipeline_sales: "\u{1FA88}",
   pipeline_stage: "\u{1F9FD}",
+  planning_cycle: "\u{1F5D3}\uFE0F",
   playbook: "\u{1F4D2}",
   portfolio: "\u{1F9F8}",
   positioning: "\u{1F3AA}",
@@ -20721,6 +20828,7 @@ var STANDARD_LABELS = {
   roadmap_item: { alt_labels: ["roadmap entry", "planned item"] },
   roadmap_theme: { alt_labels: ["product theme", "roadmap theme"] },
   // UPG-660: renamed from bare 'theme' (N6 lineage)
+  planning_cycle: { alt_labels: ["sprint", "iteration", "cycle", "program increment", "pi", "cadence", "time-box", "cooldown", "quarter"] },
   // Engineering layer
   bounded_context: { alt_labels: ["context", "domain boundary", "module boundary"] },
   service: { alt_labels: ["microservice", "backend service", "api service"] },
@@ -23242,13 +23350,19 @@ var PRODUCT_SPEC_GUIDE = {
   // registered to product_spec but missing from the navigation order).
   // `changelog` lives here because it is a structural product-shipping
   // artefact; content domain references it only via cross-domain bridges.
-  creation_sequence: ["feature_area", "feature", "epic", "user_story", "acceptance_criterion", "task", "bug", "release", "roadmap", "roadmap_item", "roadmap_theme", "changelog"],
+  creation_sequence: ["feature_area", "feature", "epic", "user_story", "acceptance_criterion", "task", "bug", "release", "roadmap", "roadmap_item", "roadmap_theme", "changelog", "planning_cycle"],
   patterns: [
     {
       name: "Feature Decomposition",
       description: "Features group into areas, decompose into epics, epics specify user stories (the templated promise), and tasks implement them as the engineering work",
       entity_types: ["feature_area", "feature", "epic", "user_story", "task"],
       edge_chain: ["feature_area_contains_feature", "feature_decomposed_into_epic", "epic_specified_by_user_story", "task_implements_user_story"]
+    },
+    {
+      name: "Planning Cadence",
+      description: "The cadence axis. Create a planning_cycle (a sprint, iteration, quarter, or PI), nest finer cycles inside a coarse one, schedule the stories that flow through it, and scope the objectives the cycle serves. Scheduling and scoping are deliberate links, not containment: a story keeps its feature/epic parent.",
+      entity_types: ["planning_cycle", "user_story", "objective"],
+      edge_chain: ["planning_cycle_contains_planning_cycle", "planning_cycle_schedules_user_story", "objective_scoped_to_planning_cycle"]
     }
   ],
   required_bridges: [
@@ -26517,6 +26631,40 @@ var UPG_ANTI_PATTERNS = [
     severity: "high",
     source: { kind: "practitioner", attribution: "John Cutler, Outcomes over Output" }
   },
+  {
+    id: "planning-cycle-without-scheduled-work",
+    name: "Planning cycle with no scheduled work",
+    description: "A planning_cycle exists but neither schedules any user_story nor contains a finer sub-cycle. An empty cadence box is a date range with nothing flowing through it: a sprint or iteration nobody planned work into, or a coarse period that was never broken down.",
+    structured_condition: {
+      operator: "and",
+      checks: [
+        { check: { type: "entity_count", entity_type: "planning_cycle", comparison: "nonzero" } },
+        {
+          check: {
+            type: "relationship",
+            source_type: "planning_cycle",
+            edge_type: "planning_cycle_schedules_user_story",
+            target_type: "user_story",
+            comparison: "not_exists"
+          }
+        },
+        {
+          check: {
+            type: "relationship",
+            source_type: "planning_cycle",
+            edge_type: "planning_cycle_contains_planning_cycle",
+            target_type: "planning_cycle",
+            comparison: "not_exists"
+          }
+        }
+      ]
+    },
+    why_it_matters: "A cadence layer only earns its keep when work is planned through it. An interval with no scheduled stories and no nested cycles adds ceremony without telling anyone what the period is for.",
+    remediation: "Schedule the stories the cycle will carry via `planning_cycle_schedules_user_story`, or break a coarse period into finer cycles via `planning_cycle_contains_planning_cycle`. If neither applies, the interval is not yet a real cadence box.",
+    stages: ["build", "beta", "launch", "growth", "mature"],
+    severity: "low",
+    since: "0.20.0"
+  },
   // ── Market intelligence layer ───────────────────────────────────────────
   {
     id: "competitors-missing-past-validation",
@@ -27345,6 +27493,16 @@ var UPG_REGIONS = [
         edge_id: "outcome_delivered_via_feature_area",
         crosses_into: "product_delivery"
       },
+      {
+        direction: "export",
+        edge_id: "objective_scoped_to_planning_cycle",
+        crosses_into: "product_delivery"
+      },
+      {
+        direction: "export",
+        edge_id: "strategic_theme_scoped_to_planning_cycle",
+        crosses_into: "product_delivery"
+      },
       {
         direction: "import",
         edge_id: "feature_drives_key_result",
@@ -28156,6 +28314,11 @@ var UPG_REGIONS = [
       {
         type: "status_report",
         role: "leaf"
+      },
+      {
+        type: "planning_cycle",
+        role: "container",
+        notes: "self-nesting cadence axis"
       }
     ],
     anchor: {
@@ -28179,7 +28342,9 @@ var UPG_REGIONS = [
       "roadmap_theme_spans_feature_area",
       "milestone_gates_release",
       "roadmap_item_references_feature",
-      "feature_request_voted_on_by_feedback_vote"
+      "feature_request_voted_on_by_feedback_vote",
+      "planning_cycle_contains_planning_cycle",
+      "planning_cycle_schedules_user_story"
     ],
     boundary_edges: [
       {
@@ -28187,6 +28352,16 @@ var UPG_REGIONS = [
         edge_id: "outcome_delivered_by_feature",
         crosses_into: "strategy_outcomes"
       },
+      {
+        direction: "import",
+        edge_id: "objective_scoped_to_planning_cycle",
+        crosses_into: "strategy_outcomes"
+      },
+      {
+        direction: "import",
+        edge_id: "strategic_theme_scoped_to_planning_cycle",
+        crosses_into: "strategy_outcomes"
+      },
       {
         direction: "import",
         edge_id: "outcome_delivered_via_feature_area",
@@ -29999,7 +30174,7 @@ function isCanonical(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.19.0";
+var UPG_VERSION = "0.20.1";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();