@unified-product-graph/core 0.6.2 → 0.7.0

package/dist/index.js

@@ -96,7 +96,7 @@ var UPG_DOMAINS = [
       "feature",
       "feature_area",
       "epic",
-      "story_statement",
+      "user_story",
       "acceptance_criterion",
       "release",
       "task",
@@ -618,20 +618,19 @@ var UPG_ENTITY_META = [
   { name: "feature_area", type_id: "ent_314", maturity: "stable", since: "0.1.0" },
   { name: "feature", type_id: "ent_071", maturity: "stable", since: "0.1.0" },
   { name: "epic", type_id: "ent_072", maturity: "stable", since: "0.1.0" },
-  // split 2 (v0.2.7): `user_story` decomposes into `story_statement`
-  // (P5 templated-statement, lifecycle-free design artefact) +
-  // `story_task` (P4 work-unit, the engineering work to implement). The
-  // statement is the "As X, I want Y so Z" stable promise; the task carries
-  // the lifecycle (backlog → in_progress → done). Replacement points to
-  // `story_task` because legacy user_story rows almost always carried task
-  // properties (assignee, status, priority); the statement is additive
-  // structural surface. Narrows to `never` in v0.2.9.
-  // user_story → story_task was the v0.2.7 migration. story_task is now
-  // deprecated at v0.4.0 and collapsed into canonical `task`. story_task carried
-  // no unique properties or lifecycle that task doesn't already carry, so the
-  // additive-vocabulary rule keeps one.
-  { name: "user_story", type_id: "ent_073", maturity: "deprecated", since: "0.1.0", deprecated_in: "0.2.7", replacement: "task" },
-  { name: "story_statement", type_id: "ent_342", maturity: "proposed", since: "0.2.7" },
+  // `user_story` is the templated "As X, I want Y so Z" promise — a stable,
+  // lifecycle-free design artefact (UCS pattern P5). The v0.2.7 split EXTRACTED
+  // the engineering work into a separate `task` (the lifecycle-bearing work-unit,
+  // linked via `task_implements_user_story`); the split was right. But the
+  // surviving statement half was renamed to the coined `story_statement`, which
+  // raised the adoption barrier — "user story" is the universally-recognised
+  // industry term for exactly this artefact. v0.7.0 (UPG-571) re-canonicalises
+  // the statement under `user_story`; `story_statement` becomes a deprecated
+  // alias. `story_task` (the original work half) was already collapsed into
+  // canonical `task` at v0.4.0. So the canonical shape is: user_story (statement)
+  // + task (work), linked by `task_implements_user_story`.
+  { name: "user_story", type_id: "ent_073", maturity: "proposed", since: "0.1.0" },
+  { name: "story_statement", type_id: "ent_342", maturity: "deprecated", since: "0.2.7", deprecated_in: "0.7.0", replacement: "user_story" },
   { name: "story_task", type_id: "ent_343", maturity: "deprecated", since: "0.2.7", deprecated_in: "0.4.0", replacement: "task" },
   { name: "acceptance_criterion", type_id: "ent_074", maturity: "stable", since: "0.1.0" },
   { name: "release", type_id: "ent_075", maturity: "stable", since: "0.1.0" },
@@ -1215,16 +1214,15 @@ var UPG_EDGE_CATALOG = {
   outcome_delivered_by_feature: { forward_verb: "delivered_by", reverse_verb: "delivers", classification: "cross-domain", source_type: "outcome", target_type: "feature" },
   outcome_delivered_via_feature_area: { forward_verb: "delivered_via", reverse_verb: "delivers_for", classification: "cross-domain", source_type: "outcome", target_type: "feature_area" },
   feature_decomposed_into_epic: { forward_verb: "decomposed_into", reverse_verb: "implements", classification: "hierarchy", source_type: "feature", target_type: "epic" },
-  // user_story → story_statement (P5 templated-statement,
-  // lifecycle-free design artefact) + story_task (P4 work-unit, the engineering
-  // work). Statement carries the "As X, I want Y so Z" stable promise + verifies
-  // through acceptance criteria + is covered by test cases + is targeted by
-  // epics; task carries the lifecycle and the implementation work.
-  epic_specified_by_story_statement: { forward_verb: "specified_by", reverse_verb: "specifies", classification: "hierarchy", source_type: "epic", target_type: "story_statement" },
-  story_statement_verified_by_acceptance_criterion: { forward_verb: "verified_by", reverse_verb: "verifies", classification: "hierarchy", source_type: "story_statement", target_type: "acceptance_criterion" },
-  // story_task collapsed into task. Edge renamed accordingly.
-  // UPG_EDGE_MIGRATIONS['0.4.0'] carries the rename rule for old graphs.
-  task_implements_story_statement: { forward_verb: "implements", reverse_verb: "implemented_by", classification: "cross-domain", source_type: "task", target_type: "story_statement" },
+  // user_story (P5 templated-statement, the "As X, I want Y so Z" lifecycle-free
+  // promise) verifies through acceptance criteria, is covered by test cases, and
+  // is specified by epics; the paired `task` carries the lifecycle and the
+  // implementation work, and implements the statement. (v0.2.7 split extracted
+  // the work into `task`; v0.7.0/UPG-571 re-canonicalised the statement
+  // story_statement → user_story — see UPG_EDGE_MIGRATIONS['0.7.0'].)
+  epic_specified_by_user_story: { forward_verb: "specified_by", reverse_verb: "specifies", classification: "hierarchy", source_type: "epic", target_type: "user_story" },
+  user_story_verified_by_acceptance_criterion: { forward_verb: "verified_by", reverse_verb: "verifies", classification: "hierarchy", source_type: "user_story", target_type: "acceptance_criterion" },
+  task_implements_user_story: { forward_verb: "implements", reverse_verb: "implemented_by", classification: "cross-domain", source_type: "task", target_type: "user_story" },
   feature_affected_by_bug: { forward_verb: "affected_by", reverse_verb: "affects", classification: "hierarchy", source_type: "feature", target_type: "bug" },
   // release containment edges — used by the GitHub adapter when
   // importing milestone→issue relationships. resolveContainmentEdge('release',
@@ -1240,10 +1238,10 @@ var UPG_EDGE_CATALOG = {
   // feature_area is not contained by theme — themes span multiple
   // areas cross-cuttingly. Containment path: product → feature_area.
   theme_spans_feature_area: { forward_verb: "spans", reverse_verb: "spanned_by", classification: "semantic", source_type: "theme", target_type: "feature_area" },
-  // `task_implements_user_story` consolidated into the
-  // canonical `story_task_implements_story_statement` above. The legacy
-  // task→user_story edge is no longer registered — story_task IS the task,
-  // and statements carry the implements relationship directly.
+  // The legacy `story_task` collapsed into `task` (v0.4.0), so the implements
+  // relationship is the canonical `task_implements_user_story` above — there is
+  // no separate story_task edge. (v0.2.7 introduced the Statement/Implementation
+  // split; v0.7.0/UPG-571 re-canonicalised the statement to user_story.)
   bug_affects_feature: { forward_verb: "affects", reverse_verb: "affected_by", classification: "cross-domain", source_type: "bug", target_type: "feature" },
   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" },
@@ -1493,7 +1491,7 @@ var UPG_EDGE_CATALOG = {
   test_suite_covers_feature: { forward_verb: "covers", reverse_verb: "covered_by", classification: "cross-domain", source_type: "test_suite", target_type: "feature" },
   test_environment_mirrors_deployment: { forward_verb: "mirrors", reverse_verb: "mirrored_by", classification: "cross-domain", source_type: "test_environment", target_type: "deployment" },
   regression_test_guards_release: { forward_verb: "guards", reverse_verb: "guarded_by", classification: "cross-domain", source_type: "regression_test", target_type: "release" },
-  test_case_covers_story_statement: { forward_verb: "covers", reverse_verb: "covered_by", classification: "cross-domain", source_type: "test_case", target_type: "story_statement" },
+  test_case_covers_user_story: { forward_verb: "covers", reverse_verb: "covered_by", classification: "cross-domain", source_type: "test_case", target_type: "user_story" },
   qa_session_targets_feature: { forward_verb: "targets", reverse_verb: "targeted_by", classification: "cross-domain", source_type: "qa_session", target_type: "feature" },
   test_coverage_report_covers_service: { forward_verb: "covers", reverse_verb: "covered_by", classification: "cross-domain", source_type: "test_coverage_report", target_type: "service" },
   test_suite_produces_test_result: { forward_verb: "produces", reverse_verb: "produced_by", classification: "causal", source_type: "test_suite", target_type: "test_result" },
@@ -3038,12 +3036,12 @@ var UPG_VALID_CHILDREN = {
   ],
   // ── Product Specification hierarchy ─────────────────────────────────────────
   // story_task collapsed into canonical task. feature now owns
-  // task directly; story-derived tasks implement story_statement via
-  // task_implements_story_statement edge.
+  // task directly; story-derived tasks implement user_story via
+  // task_implements_user_story edge.
   feature: ["epic", "bug", "task"],
   feature_area: ["feature", "feature_area"],
-  epic: ["story_statement"],
-  story_statement: ["acceptance_criterion"],
+  epic: ["user_story"],
+  user_story: ["acceptance_criterion"],
   task: ["task"],
   // ── Engineering hierarchy ───────────────────────────────────────────────────
   bounded_context: [
@@ -4172,37 +4170,6 @@ var EPIC_LIFECYCLE = {
     }
   ]
 };
-var USER_STORY_LIFECYCLE = {
-  entity_type: "user_story",
-  initial_phase: "draft",
-  terminal_phases: ["done"],
-  phases: [
-    {
-      id: "draft",
-      label: "Draft",
-      description: "The story has been written but has not been reviewed or refined. It may not yet have acceptance criteria.",
-      transitions_to: ["ready"]
-    },
-    {
-      id: "ready",
-      label: "Ready",
-      description: "The story has been refined. Acceptance criteria are defined. It is ready to be pulled into a sprint.",
-      transitions_to: ["in_progress"]
-    },
-    {
-      id: "in_progress",
-      label: "In Progress",
-      description: "A developer is actively working on this story.",
-      transitions_to: ["done"]
-    },
-    {
-      id: "done",
-      label: "Done",
-      description: "The story meets all acceptance criteria and has been merged and verified.",
-      transitions_to: []
-    }
-  ]
-};
 var RELEASE_LIFECYCLE = {
   entity_type: "release",
   initial_phase: "planned",
@@ -5703,9 +5670,9 @@ var UPG_LIFECYCLES = [
   FEATURE_AREA_LIFECYCLE,
   FEATURE_LIFECYCLE,
   EPIC_LIFECYCLE,
-  USER_STORY_LIFECYCLE,
-  // story_task lifecycle removed v0.4.0 collapsed story_task into task.
-  // task uses TASK_LIFECYCLE (WORK_ITEM_TEMPLATE) which is equivalent.
+  // user_story is lifecycle-free (declared in UPG_LIFECYCLE_FREE_TYPES below).
+  // story_task lifecycle removed v0.4.0 — collapsed into task (TASK_LIFECYCLE,
+  // WORK_ITEM_TEMPLATE).
   RELEASE_LIFECYCLE,
   TASK_LIFECYCLE,
   BUG_LIFECYCLE,
@@ -5812,12 +5779,13 @@ var UPG_LIFECYCLE_FREE_TYPES = /* @__PURE__ */ new Set([
   "brand_typography",
   "brand_imagery",
   // ── Product Specification (4 of 5) — criteria, grouping, historical, +
-  //    story_statement (v0.2.7 split: the templated promise is a stable
-  //    design artefact; the paired story_task carries the lifecycle) ─
+  //    user_story (the templated promise is a stable design artefact; the paired
+  //    task carries the lifecycle). Re-canon story_statement → user_story at
+  //    v0.7.0/UPG-571. ─
   "acceptance_criterion",
   "changelog",
   "theme",
-  "story_statement",
+  "user_story",
   // ── Strategy — metric is a measurement definition; metric_quality_assessment
   //    is a point-in-time snapshot; value_stream is a mapped flow;
   //    constraint carries its own `constraint_status` enum (binding/advisory/
@@ -6303,6 +6271,23 @@ function getEnumValueMeta(scaleName, value) {
 
 // src/grammar/migrations.ts
 var UPG_MIGRATIONS = {
+  "0.7.0": [
+    // (since v0.7.0, UPG-571) story_statement → user_story. The v0.2.7 split
+    // correctly separated the templated promise from the engineering work
+    // (task), but renamed the surviving statement half to the coined
+    // `story_statement`. "User story" is the universally-recognised industry
+    // term for exactly that artefact, and UPG's value is being the recognisable
+    // canonical vocabulary — so the statement is re-canonicalised under
+    // `user_story`. Lifecycle-free, same property surface (as_a / i_want_to /
+    // so_that / text); no property migration required. The paired `task` and
+    // the `task_implements_*` / `epic_specified_by_*` / `*_verified_by_*` /
+    // `test_case_covers_*` edges are renamed in UPG_EDGE_MIGRATIONS['0.7.0'].
+    {
+      from: "story_statement",
+      to: "user_story",
+      reason: 'story_statement re-canonicalised to user_story (UPG-571). The v0.2.7 Statement/Implementation split was sound \u2014 it extracted the lifecycle-bearing work into `task` \u2014 but the coined `story_statement` name raised the adoption barrier; "user story" is the industry-standard term for the templated promise. Lifecycle-free, identical property surface (as_a / i_want_to / so_that / text); no property migration needed.'
+    }
+  ],
   "0.4.0": [
     // (since v0.4.0) hypothesis_claim reverts to hypothesis (the simpler
     // canonical name — "claim" is implied). hypothesis_evidence deprecated
@@ -7293,6 +7278,18 @@ function getSplitMigrations(fromVersion, toVersion) {
   return result;
 }
 var UPG_EDGE_MIGRATIONS = {
+  "0.7.0": [
+    // (since v0.7.0, UPG-571) story_statement → user_story re-canon. The four
+    // canonical edges that touch the statement are renamed to the user_story
+    // form. Endpoint guards reference the POST-migration (user_story) types —
+    // edge migration runs after node migration, so by the time these rules
+    // apply the statement node has already been renamed story_statement →
+    // user_story (UPG_MIGRATIONS['0.7.0']).
+    { kind: "rename", from: "task_implements_story_statement", to: "task_implements_user_story", requires_source_type: "task", requires_target_type: "user_story", reason: "story_statement \u2192 user_story (UPG-571). Task still implements the statement; edge key updated to the re-canonicalised target type." },
+    { kind: "rename", from: "epic_specified_by_story_statement", to: "epic_specified_by_user_story", requires_source_type: "epic", requires_target_type: "user_story", reason: "story_statement \u2192 user_story (UPG-571). Epics specify the statement; edge key updated to the re-canonicalised target type." },
+    { kind: "rename", from: "story_statement_verified_by_acceptance_criterion", to: "user_story_verified_by_acceptance_criterion", requires_source_type: "user_story", requires_target_type: "acceptance_criterion", reason: "story_statement \u2192 user_story (UPG-571). Acceptance criteria verify the statement; edge key updated to the re-canonicalised source type." },
+    { kind: "rename", from: "test_case_covers_story_statement", to: "test_case_covers_user_story", requires_source_type: "test_case", requires_target_type: "user_story", reason: "story_statement \u2192 user_story (UPG-571). Test cases cover the statement; edge key updated to the re-canonicalised target type." }
+  ],
   "0.4.0": [
     // ── hypothesis_claim → hypothesis reverse rename ───────────────
     // Every edge that was renamed FROM hypothesis_* TO hypothesis_claim_* in
@@ -7773,18 +7770,19 @@ var UPG_EDGE_MIGRATIONS = {
       requires_target_type: "story_statement",
       reason: "Test cases cover the spec, not the work; retargets target to story_statement."
     },
-    // Two user_story-edges drop (consolidated into the new canonical
-    // story_task_implements_story_statement edge).
+    // user_story_broken_into_task drops — consolidated into the implements edge.
     {
       kind: "drop",
       from: "user_story_broken_into_task",
-      reason: 'Consolidated into the canonical story_task_implements_story_statement (the implements relationship now flows from task to statement directly). CHANGELOG v0.2.7: "user_story_broken_into_task \u2192 dropped; consolidated into story_task_implements_story_statement."'
-    },
-    {
-      kind: "drop",
-      from: "task_implements_user_story",
-      reason: 'Consolidated as above \u2014 story_task IS the task, statements carry the implements relationship directly. CHANGELOG v0.2.7: "task_implements_user_story \u2192 dropped; consolidated as above."'
+      reason: 'Consolidated into the canonical implements edge (the relationship now flows from task to statement directly). CHANGELOG v0.2.7: "user_story_broken_into_task \u2192 dropped."'
     }
+    // NOTE: the v0.2.7 drop of `task_implements_user_story` was REMOVED at v0.7.0
+    // (UPG-571). Re-canonicalising story_statement → user_story makes
+    // `task_implements_user_story` the canonical implements edge again, so the
+    // name is no longer retired (a drop rule must never name a canonical edge).
+    // Legacy pre-0.2.7 instances are reconnected by the v0.2.7 split's emitted
+    // implements edge; any residual dangling edge is handled by
+    // repair_dangling_edges.
   ],
   "0.2.8": [
     // ── split 3: 12 hypothesis-edge retargets + 1 drop ─────────────
@@ -10952,8 +10950,8 @@ var UPG_PROPERTY_SCHEMA = {
     risks_flagged: { type: "number", description: "Number of risks flagged in this report" },
     blockers: { type: "string", description: "Description of current blockers" }
   },
-  // StoryStatementProperties — "As X, I want Y so Z" templated promise on a user story (UCS pattern P5).
-  story_statement: {
+  // UserStoryProperties — "As X, I want Y so Z" templated promise — a user story (UCS pattern P5).
+  user_story: {
     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." },
@@ -11515,7 +11513,7 @@ var UPG_FRAMEWORKS = [
       },
       {
         "label": "User Stories",
-        "entityTypeId": "story_statement",
+        "entityTypeId": "user_story",
         "description": "Detailed stories prioritised vertically"
       },
       {
@@ -11535,7 +11533,7 @@ var UPG_FRAMEWORKS = [
           "role": "bucket"
         },
         {
-          "type": "story_statement",
+          "type": "user_story",
           "role": "bucket"
         },
         {
@@ -16276,7 +16274,7 @@ var PRODUCT_DELIVERY_PLAYBOOK = {
     seqStep(
       3,
       "Stories",
-      ["story_statement", "acceptance_criterion"],
+      ["user_story", "acceptance_criterion"],
       'Write each feature from the user perspective. "As [persona], I want [job], so that [outcome]." Define acceptance criteria.'
     ),
     seqStep(
@@ -17717,19 +17715,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", "story_statement", "acceptance_criterion", "task", "bug", "release", "roadmap", "roadmap_item", "theme", "changelog"],
+  creation_sequence: ["feature_area", "feature", "epic", "user_story", "acceptance_criterion", "task", "bug", "release", "roadmap", "roadmap_item", "theme", "changelog"],
   patterns: [
     {
       name: "Feature Decomposition",
-      description: "Features group into areas, decompose into epics, epics specify story_statements (the templated promise), and tasks implement statements as the engineering work",
-      entity_types: ["feature_area", "feature", "epic", "story_statement", "task"],
-      edge_chain: ["feature_area_contains_feature", "feature_decomposed_into_epic", "epic_specified_by_story_statement", "task_implements_story_statement"]
+      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"]
     }
   ],
   required_bridges: [
     { edge_type: "feature_tests_hypothesis", target_domain: "validation", when: "Features should trace back to validated hypotheses" },
     { edge_type: "outcome_delivered_by_feature", target_domain: "strategy", when: "Every feature should connect to a strategic outcome" },
-    { edge_type: "test_case_covers_story_statement", target_domain: "testing", when: "Story statements should have acceptance tests" }
+    { edge_type: "test_case_covers_user_story", target_domain: "testing", when: "User stories should have acceptance tests" }
   ],
   anti_patterns: [
     { description: "Features without outcomes. Features serve strategic outcomes; the rest is waste." },
@@ -17910,7 +17908,7 @@ var TESTING_GUIDE = {
     }
   ],
   required_bridges: [
-    { edge_type: "test_case_covers_story_statement", target_domain: "product_spec", when: "Test cases should trace back to story statements (which in turn trace to features via epics)" },
+    { edge_type: "test_case_covers_user_story", target_domain: "product_spec", when: "Test cases should trace back to user stories (which in turn trace to features via epics)" },
     { edge_type: "test_case_validates_acceptance_criterion", target_domain: "product_spec", when: 'Acceptance criteria define what "done" means and must be validated by tests' }
   ],
   anti_patterns: [
@@ -19555,7 +19553,7 @@ var UPG_COUNT_BENCHMARKS = [
     "rationale": "Epics group related stories. Not needed at idea stage."
   },
   {
-    "type": "story_statement",
+    "type": "user_story",
     "domain": "product_spec",
     "concept": null,
     "validation": {
@@ -20470,7 +20468,7 @@ var UPG_RATIO_BENCHMARKS = [
   },
   {
     "name": "Story coverage",
-    "numerator_type": "story_statement",
+    "numerator_type": "user_story",
     "denominator_type": "feature",
     "expected_min": 2,
     "stages": [
@@ -22253,7 +22251,7 @@ var UPG_REGIONS = [
       "feature_affected_by_bug",
       "epic_specified_by_user_story",
       "user_story_verified_by_acceptance_criterion",
-      "user_story_broken_into_task",
+      "task_implements_user_story",
       "roadmap_contains_roadmap_item",
       "roadmap_categorised_by_theme",
       "roadmap_schedules_release",