@unified-product-graph/mcp-server 0.8.1 → 0.8.4

package/dist/tools-manifest.json

@@ -1,8 +1,8 @@
 {
   "schema_version": "2",
   "package": "@unified-product-graph/mcp-server",
-  "package_version": "0.8.1",
-  "tool_count": 94,
+  "package_version": "0.8.4",
+  "tool_count": 96,
   "domains": [
     "context",
     "nodes",
@@ -153,11 +153,11 @@
         "properties": {
           "skill_invoked": {
             "type": "string",
-            "description": "Register that this skill was just invoked (e.g. \"upg-status\")"
+            "description": "Register that this skill was just invoked (e.g. \"upg-show-status\")"
           },
           "recommendation": {
             "type": "string",
-            "description": "Record a recommendation given to the user (e.g. \"Run /upg-strategy to fill strategy gap\")"
+            "description": "Record a recommendation given to the user (e.g. \"Run /upg-new-strategy to fill strategy gap\")"
           },
           "focus_area": {
             "type": "string",
@@ -167,11 +167,15 @@
             "type": "string",
             "enum": [
               "product",
+              "ux_design",
               "engineering",
-              "design",
-              "growth"
+              "growth",
+              "business",
+              "research",
+              "marketing",
+              "full"
             ],
-            "description": "Switch the active lens. Changes what context, skills, and gaps are surfaced first."
+            "description": "Switch the active lens. Changes what context, skills, and gaps are surfaced first. Canonical lens ids (derived from core): product, ux_design, engineering, growth, business, research, marketing, full."
           },
           "persist_lens": {
             "type": "boolean",
@@ -304,7 +308,7 @@
         "create_node",
         "batch_create_edges"
       ],
-      "source": "src/tools/nodes.ts:991",
+      "source": "src/tools/nodes.ts:1013",
       "symbol": "batchCreateNodes",
       "returns": "JSON: `{ created, edges_created, count, edges_count, warnings? }`.",
       "return_shape": "{ created, edges_created, count, edges_count, warnings? }",
@@ -343,7 +347,7 @@
       "see": [
         "delete_node"
       ],
-      "source": "src/tools/nodes.ts:1095",
+      "source": "src/tools/nodes.ts:1117",
       "symbol": "batchDeleteNodes",
       "returns": "JSON: `{ deleted, edges_removed, count }`.",
       "return_shape": "{ deleted, edges_removed, count }",
@@ -404,7 +408,7 @@
       "see": [
         "update_node"
       ],
-      "source": "src/tools/nodes.ts:1019",
+      "source": "src/tools/nodes.ts:1041",
       "symbol": "batchUpdateNodes",
       "returns": "JSON: `{ updated, count, warnings? }`. `warnings` carries\nlifecycle-phase hints aggregated across the batch.",
       "return_shape": "{ updated, count, warnings? }",
@@ -528,7 +532,7 @@
         "batch_delete_nodes",
         "validate_graph"
       ],
-      "source": "src/tools/nodes.ts:1340",
+      "source": "src/tools/nodes.ts:1362",
       "symbol": "deduplicateNodes",
       "returns": "JSON: with `dry_run: true`, `{ duplicates, total_groups,\ntotal_duplicate_nodes, dry_run, message }`. With `dry_run: false`,\n`{ merged: true, groups_merged, nodes_removed, edges_redirected,\nstrategy }`.",
       "return_notes": [
@@ -567,7 +571,7 @@
       "see": [
         "batch_delete_nodes"
       ],
-      "source": "src/tools/nodes.ts:965",
+      "source": "src/tools/nodes.ts:987",
       "symbol": "deleteNode",
       "returns": "JSON: `{ node, removed_edge_ids }`.",
       "return_shape": "{ node, removed_edge_ids }",
@@ -769,7 +773,7 @@
         "validate_graph",
         "list_type_migrations"
       ],
-      "source": "src/tools/nodes.ts:1286",
+      "source": "src/tools/nodes.ts:1308",
       "symbol": "migrateProperties",
       "returns": "JSON: `{ top_level_renames, lifted_properties, dropped_props,\ndropped_self_referential, dry_run }`.",
       "return_shape": "{ top_level_renames, lifted_properties, dropped_props, dropped_self_referential, dry_run }",
@@ -868,7 +872,7 @@
         "export_edges",
         "update_node"
       ],
-      "source": "src/tools/nodes.ts:1149",
+      "source": "src/tools/nodes.ts:1171",
       "symbol": "migrateType",
       "returns": "JSON: `{ migrated_nodes, migrated_edges, edge_renames,\ndropped_edges, unmapped_legacy_edges, defaults_applied, dry_run }`.\n`edge_renames` is `[{ id, from, to, flipped }]`; `dropped_edges` is\n`[{ id, from }]`; `unmapped_legacy_edges` is `[{ type, count }]`.\n`migrated_edges` is the total mutated count (renames + drops).",
       "return_shape": "{ migrated_nodes, migrated_edges, edge_renames, dropped_edges, unmapped_legacy_edges, defaults_applied, dry_run }",
@@ -1046,6 +1050,13 @@
           "properties": {
             "type": "object",
             "description": "Merged with existing properties"
+          },
+          "unset_properties": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Property keys to DELETE. Applied after the `properties` merge, so one call can set some keys and drop others. Writing `{ key: null }` only stores a literal null; use this to actually remove a key. Unknown keys are ignored."
           }
         },
         "required": [
@@ -1053,7 +1064,7 @@
         ]
       },
       "throws": [
-        "Returns a textError when `node_id` is missing, the type migration\nfails, when `strict: true` and unknown properties are present, or when\nthe underlying store rejects the patch."
+        "Returns a textError when `node_id` is missing, the type migration\nfails, the `status` is not a valid lifecycle phase for the type, when\n`strict: true` and unknown properties are present, or when the underlying\nstore rejects the patch."
       ],
       "examples": [
         {
@@ -1067,13 +1078,14 @@
         "migrate_type",
         "batch_update_nodes"
       ],
-      "source": "src/tools/nodes.ts:874",
+      "source": "src/tools/nodes.ts:880",
       "symbol": "updateNode",
-      "returns": "JSON: `{ node, warning?, unknown_properties? }`. `warning`\naggregates lifecycle-status hints, migration warnings, and any\nunknown-property notice. `unknown_properties` lists property\nkeys not in the entity's schema. Pass `strict: true` to reject unknown\nproperties instead of warning.",
-      "return_shape": "{ node, warning?, unknown_properties? }",
+      "returns": "JSON: `{ node, warning?, unknown_properties?, unset? }`. `warning`\naggregates migration warnings and any unknown-property notice.\n`unknown_properties` lists property keys not in the entity's schema.\n`unset` lists the keys actually removed. Pass `strict: true` to reject\nunknown properties instead of warning.",
+      "return_shape": "{ node, warning?, unknown_properties?, unset? }",
       "return_notes": [
-        "`warning` aggregates lifecycle-status hints, migration warnings, and any unknown-property notice.",
+        "`warning` aggregates migration warnings and any unknown-property notice.",
         "`unknown_properties` lists property keys not in the entity's schema.",
+        "`unset` lists the keys actually removed.",
         "Pass `strict: true` to reject unknown properties instead of warning."
       ],
       "atomicity": "atomic-with-rollback (when `type` is changed); atomic for\nshallow-merge patches."
@@ -1123,7 +1135,7 @@
       "see": [
         "create_edge"
       ],
-      "source": "src/tools/edges.ts:209",
+      "source": "src/tools/edges.ts:210",
       "symbol": "batchCreateEdges",
       "returns": "JSON: `{ created, count }`.",
       "return_shape": "{ created, count }",
@@ -1162,7 +1174,7 @@
       "see": [
         "delete_edge"
       ],
-      "source": "src/tools/edges.ts:293",
+      "source": "src/tools/edges.ts:298",
       "symbol": "batchDeleteEdges",
       "returns": "JSON: `{ deleted, count }`.",
       "return_shape": "{ deleted, count }",
@@ -1213,7 +1225,7 @@
       "see": [
         "move_node"
       ],
-      "source": "src/tools/edges.ts:177",
+      "source": "src/tools/edges.ts:178",
       "symbol": "batchMoveNodes",
       "returns": "JSON: `{ moves, warnings? }` mirroring the per-move result of\n`move_node`.",
       "return_shape": "{ moves, warnings? }",
@@ -1248,6 +1260,10 @@
           "type": {
             "type": "string",
             "description": "Edge type. Auto-inferred if omitted."
+          },
+          "properties": {
+            "type": "object",
+            "description": "Edge-scoped properties. Only permitted on edge types that opt in (currently framework_exercise_includes_node); rejected on plain semantic edges."
           }
         },
         "required": [
@@ -1301,7 +1317,7 @@
         "export_edges",
         "repair_dangling_edges"
       ],
-      "source": "src/tools/edges.ts:122",
+      "source": "src/tools/edges.ts:123",
       "symbol": "deleteEdge",
       "returns": "JSON: the removed edge object.",
       "return_notes": [
@@ -1352,7 +1368,7 @@
         "query",
         "list_nodes"
       ],
-      "source": "src/tools/edges.ts:403",
+      "source": "src/tools/edges.ts:408",
       "symbol": "exportEdges",
       "returns": "JSON: `{ edges, total, offset, limit, types?, _hash }`. Each edge\ncarries `{ id, source, target, type, mapping_confidence? }`.",
       "return_shape": "{ edges, total, offset, limit, types?, _hash }",
@@ -1398,7 +1414,7 @@
       "see": [
         "batch_move_nodes"
       ],
-      "source": "src/tools/edges.ts:149",
+      "source": "src/tools/edges.ts:150",
       "symbol": "moveNode",
       "returns": "JSON: `{ moved: true, node_id, new_parent_id, new_edge,\nold_edge_id?, warning? }`. The internal `removed_edge` field is stripped\nfrom the wire payload.",
       "return_shape": "{ moved: true, node_id, new_parent_id, new_edge, old_edge_id?, warning? }",
@@ -1445,7 +1461,7 @@
         "migrate_type",
         "export_edges"
       ],
-      "source": "src/tools/edges.ts:490",
+      "source": "src/tools/edges.ts:495",
       "symbol": "renameEdgeType",
       "returns": "JSON: with `dry_run: true`, `{ dry_run, from, to, flip, would_rename, sample }`.\nWith `dry_run: false`, `{ dry_run, from, to, flip, renamed, ids }`.",
       "return_notes": [
@@ -1493,7 +1509,7 @@
         "Dropping `corrupt` edges is irreversible. The integrity stamp is\nre-computed on next save; a subsequent reload won't bring them back."
       ],
       "see": [],
-      "source": "src/tools/edges.ts:337",
+      "source": "src/tools/edges.ts:342",
       "symbol": "repairDanglingEdges",
       "returns": "JSON: `{ dry_run, report, dropped?, remaining? }`. `report` is\nthe pre-action classification. With `dry_run: false`, `dropped` is the\ncount of edges removed and `remaining` is the post-action report.",
       "return_shape": "{ dry_run, report, dropped?, remaining? }",
@@ -1742,7 +1758,7 @@
         "list_portfolio_cross_edges",
         "migrate_cross_edges"
       ],
-      "source": "src/tools/workspace.ts:395",
+      "source": "src/tools/workspace.ts:403",
       "symbol": "createCrossProductEdge",
       "returns": "JSON: `{ edge, portfolio_file }`.",
       "return_shape": "{ edge, portfolio_file }",
@@ -1794,7 +1810,7 @@
       "see": [
         "init_workspace"
       ],
-      "source": "src/tools/workspace.ts:275",
+      "source": "src/tools/workspace.ts:283",
       "symbol": "createProductTool",
       "returns": "JSON: `{ message, ...result }`. `result` carries `id`, `title`,\n`slug`, `file_path`, and the optional portfolio edge.",
       "return_shape": "{ message,...result }",
@@ -1823,7 +1839,7 @@
       "see": [
         "list_portfolios"
       ],
-      "source": "src/tools/workspace.ts:344",
+      "source": "src/tools/workspace.ts:352",
       "symbol": "getOrganization",
       "returns": "JSON: `{ organization: UPGOrganization | null, portfolio_file? }`.\nReturns `{ organization: null }` when no portfolio document exists yet.",
       "return_shape": "{ organization: UPGOrganization | null, portfolio_file? }",
@@ -1852,7 +1868,7 @@
       "see": [
         "init_workspace"
       ],
-      "source": "src/tools/workspace.ts:163",
+      "source": "src/tools/workspace.ts:171",
       "symbol": "getWorkspaceInfo",
       "returns": "JSON: `{ mode, workspace_path?, current_product?, current_file?,\nproducts }`. The shape depends on whether `.upg/workspace.json` exists.",
       "return_shape": "{ mode, workspace_path?, current_product?, current_file?, products }",
@@ -1892,7 +1908,7 @@
         "switch_product",
         "get_workspace_info"
       ],
-      "source": "src/tools/workspace.ts:239",
+      "source": "src/tools/workspace.ts:247",
       "symbol": "initWorkspaceTool",
       "returns": "JSON: `{ message, ...result }`. `result` carries the workspace\npath and the moved file's new location.",
       "return_shape": "{ message,...result }",
@@ -1922,10 +1938,13 @@
         "switch_product",
         "get_workspace_info"
       ],
-      "source": "src/tools/workspace.ts:40",
+      "source": "src/tools/workspace.ts:44",
       "symbol": "listLocalProducts",
-      "returns": "JSON: `{ products: Array<{ file, title, stage, nodes, edges }> }`.",
+      "returns": "JSON: `{ products: Array<{ file, title, stage, nodes, edges }> }`.\n`stage` is the CANONICAL UPGProductStage (legacy values like `idea` are\ncoerced to `concept`), or `null` when unset — matching what\n`get_product_context` reports for the same product (UPG-611 / DT-MCP-3).",
       "return_shape": "{ products: Array<{ file, title, stage, nodes, edges }> }",
+      "return_notes": [
+        "`stage` is the CANONICAL UPGProductStage (legacy values like `idea` are coerced to `concept`), or `null` when unset — matching what `get_product_context` reports for the same product (UPG-611 / DT-MCP-3)."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1942,7 +1961,7 @@
       "see": [
         "create_cross_product_edge"
       ],
-      "source": "src/tools/workspace.ts:534",
+      "source": "src/tools/workspace.ts:542",
       "symbol": "listPortfolioCrossEdges",
       "returns": "JSON: `{ cross_edges: UPGCrossEdge[], total, portfolio_file? }`.",
       "return_shape": "{ cross_edges: UPGCrossEdge[], total, portfolio_file? }",
@@ -1969,7 +1988,7 @@
         "create_cross_product_edge",
         "get_organization"
       ],
-      "source": "src/tools/workspace.ts:317",
+      "source": "src/tools/workspace.ts:325",
       "symbol": "listPortfolios",
       "returns": "JSON: `{ portfolios: Array<{ id, title, description?,\nparent_portfolio_id?, hierarchy_model?, products? }>, total }`.",
       "return_shape": "{ portfolios: Array<{ id, title, description?, parent_portfolio_id?, hierarchy_model?, products? }>, total }",
@@ -2012,7 +2031,7 @@
         "list_cross_edge_types",
         "init_workspace"
       ],
-      "source": "src/tools/workspace.ts:603",
+      "source": "src/tools/workspace.ts:611",
       "symbol": "migrateCrossEdges",
       "returns": "JSON: `{ migrated, skipped, dry_run, portfolio_file? }`.",
       "return_shape": "{ migrated, skipped, dry_run, portfolio_file? }",
@@ -2046,7 +2065,7 @@
         "list_local_products",
         "init_workspace"
       ],
-      "source": "src/tools/workspace.ts:108",
+      "source": "src/tools/workspace.ts:116",
       "symbol": "switchProduct",
       "returns": "JSON: `{ message, file, product: { title, stage }, entities }`.",
       "return_shape": "{ message, file, product: { title, stage }, entities }",
@@ -2094,6 +2113,51 @@
       "return_shape": "{ type, alias_of?, domain, expected_properties, edges_out, edges_in, phases?, initial_phase?, terminal_phases?, domain_guide? }",
       "atomicity": "atomic (read-only)"
     },
+    {
+      "name": "apply_framework",
+      "description": "Apply a framework (MoSCoW, RICE, Kano, ...) to a set of entities: creates a framework_exercise node and an `includes` edge to each entity. The per-entity result is recorded on the edge via score_entity, never on the entity node, so the same entity can sit in many exercises and any entity type can be scored. Returns { exercise_id, exercise, included, warnings }.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "framework_id": {
+            "type": "string",
+            "description": "Required. UPGFramework.id (e.g. \"moscow\", \"rice-scoring\")."
+          },
+          "title": {
+            "type": "string",
+            "description": "Human label for the exercise (default \"<Framework> exercise\")."
+          },
+          "entity_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Entities to pull into the exercise (any type)."
+          },
+          "status": {
+            "type": "string",
+            "description": "Lifecycle phase: draft | active | archived (default draft)."
+          }
+        },
+        "required": [
+          "framework_id"
+        ]
+      },
+      "throws": [
+        "textError on a missing/unknown framework_id."
+      ],
+      "examples": [],
+      "warnings": [],
+      "see": [
+        "score_entity"
+      ],
+      "source": "src/tools/frameworks.ts:22",
+      "symbol": "applyFramework",
+      "returns": "JSON: `{ exercise_id, exercise, included: [{ edge_id, entity_id }], warnings }`.",
+      "return_shape": "{ exercise_id, exercise, included: [{ edge_id, entity_id }], warnings }",
+      "atomicity": "atomic."
+    },
     {
       "name": "get_anti_pattern",
       "description": "Return one curated anti-pattern by id (kebab-case slug, e.g. \"features-without-hypotheses\", \"personas-without-jobs\"). Includes structured condition, why-it-matters, remediation, applicable stages, severity, optional source citation. IDs are stable URL fragments.",
@@ -2127,7 +2191,7 @@
         "inspect",
         "validate_graph"
       ],
-      "source": "src/tools/spec.ts:1425",
+      "source": "src/tools/spec.ts:1440",
       "symbol": "getAntiPattern",
       "returns": "JSON: `UPGCuratedAntiPattern`",
       "return_notes": [
@@ -2218,7 +2282,7 @@
         "list_anti_patterns",
         "get_playbook"
       ],
-      "source": "src/tools/spec.ts:746",
+      "source": "src/tools/spec.ts:761",
       "symbol": "getDomainGuide",
       "returns": "JSON: the full `UPGDomainUsageGuide` record.",
       "return_notes": [
@@ -2256,7 +2320,7 @@
         "list_domains",
         "get_domain_guide"
       ],
-      "source": "src/tools/spec.ts:1881",
+      "source": "src/tools/spec.ts:1896",
       "symbol": "getDomainRing",
       "returns": "JSON: the full `UPGDomainRing` record.",
       "return_notes": [
@@ -2297,7 +2361,7 @@
         "list_edge_migrations",
         "rename_edge_type"
       ],
-      "source": "src/tools/spec.ts:877",
+      "source": "src/tools/spec.ts:892",
       "symbol": "getEdgeType",
       "returns": "JSON: `{ type, forward_verb, reverse_verb, classification, source_type, target_type }`",
       "return_shape": "{ type, forward_verb, reverse_verb, classification, source_type, target_type }",
@@ -2336,7 +2400,7 @@
         "get_entity_schema",
         "list_type_migrations"
       ],
-      "source": "src/tools/spec.ts:1340",
+      "source": "src/tools/spec.ts:1355",
       "symbol": "getEntityMeta",
       "returns": "JSON: `EntityTypeMeta & { domain_id: string | null }`",
       "return_notes": [
@@ -2377,7 +2441,7 @@
         "get_playbook",
         "get_approach"
       ],
-      "source": "src/tools/spec.ts:814",
+      "source": "src/tools/spec.ts:829",
       "symbol": "getFramework",
       "returns": "JSON: the full `UPGFramework` record.",
       "return_notes": [
@@ -2418,7 +2482,7 @@
         "get_framework",
         "list_entity_types"
       ],
-      "source": "src/tools/spec.ts:1134",
+      "source": "src/tools/spec.ts:1149",
       "symbol": "getLensTool",
       "returns": "JSON: `{ ...UPGLens, visible_types: string[] }`",
       "return_shape": "{...UPGLens, visible_types: string[] }",
@@ -2454,7 +2518,7 @@
         "get_entity_meta",
         "get_entity_schema"
       ],
-      "source": "src/tools/spec.ts:1751",
+      "source": "src/tools/spec.ts:1766",
       "symbol": "getLifecycle",
       "returns": "JSON: the full `UPGLifecycle` record, or a descriptive message.",
       "return_notes": [
@@ -2536,7 +2600,7 @@
         "get_playbook",
         "list_lenses"
       ],
-      "source": "src/tools/spec.ts:936",
+      "source": "src/tools/spec.ts:951",
       "symbol": "getRegion",
       "returns": "JSON: the full `UPGRegion` record.",
       "return_notes": [
@@ -2577,7 +2641,7 @@
         "get_entity_meta",
         "list_entity_types"
       ],
-      "source": "src/tools/spec.ts:958",
+      "source": "src/tools/spec.ts:973",
       "symbol": "getRegionForEntity",
       "returns": "JSON: the full `UPGRegion` record.",
       "return_notes": [
@@ -2608,7 +2672,7 @@
         "list_scales",
         "get_entity_schema"
       ],
-      "source": "src/tools/spec.ts:1797",
+      "source": "src/tools/spec.ts:1812",
       "symbol": "getScale",
       "returns": "JSON: the full `UPGScaleDefinition` record including all points.",
       "return_notes": [
@@ -2639,7 +2703,7 @@
         "list_edge_types",
         "list_regions"
       ],
-      "source": "src/tools/spec.ts:986",
+      "source": "src/tools/spec.ts:1001",
       "symbol": "getSpecVersion",
       "returns": "JSON: `{ upg_version, markdown_format_version, entity_count, edge_count, domain_count, region_count }`",
       "return_shape": "{ upg_version, markdown_format_version, entity_count, edge_count, domain_count, region_count }",
@@ -2685,7 +2749,7 @@
         "get_entity_meta",
         "list_frameworks"
       ],
-      "source": "src/tools/spec.ts:1202",
+      "source": "src/tools/spec.ts:1217",
       "symbol": "getTypeLabel",
       "returns": "JSON: `{ ...UPGTypeLabel, resolved_label: string }`",
       "return_shape": "{...UPGTypeLabel, resolved_label: string }",
@@ -2724,7 +2788,7 @@
         "get_entity_meta",
         "create_node"
       ],
-      "source": "src/tools/spec.ts:1232",
+      "source": "src/tools/spec.ts:1247",
       "symbol": "getValidChildrenTool",
       "returns": "JSON: `{ parent_type, valid_children: string[] }`",
       "return_shape": "{ parent_type, valid_children: string[] }",
@@ -2732,7 +2796,7 @@
     },
     {
       "name": "inspect",
-      "description": "[LLM-mediated] This tool returns a routing envelope, not computed results. For user-facing inspection, invoke the /upg-inspect skill instead of calling this tool directly. Inspect approach: path of arrival to \"what's broken?\". Returns the Inspect record + invocation params in the family-resemblance envelope. The LLM consumes `signature_hint` and emits `{ violations: [{ severity, kind, entity_id, description, fix_hint }] }` against `UPG_ANTI_PATTERNS` + the live graph. Optional `region` or `entities[]` scope the audit.",
+      "description": "[LLM-mediated] This tool returns a routing envelope, not computed results. For user-facing inspection, invoke the /upg-show-entity skill instead of calling this tool directly. Inspect approach: path of arrival to \"what's broken?\". Returns the Inspect record + invocation params in the family-resemblance envelope. The LLM consumes `signature_hint` and emits `{ violations: [{ severity, kind, entity_id, description, fix_hint }] }` against `UPG_ANTI_PATTERNS` + the live graph. Optional `region` or `entities[]` scope the audit.",
       "domain": "spec",
       "inputSchema": {
         "type": "object",
@@ -2762,7 +2826,7 @@
         "plan",
         "reflect"
       ],
-      "source": "src/tools/spec.ts:459",
+      "source": "src/tools/spec.ts:468",
       "symbol": "inspect",
       "returns": "JSON envelope: `{ approach_id, scope, generated_at, approach,\nparams, violations, summary, execution_mode: \"execution_v0_4_0\" }`",
       "return_notes": [
@@ -2827,7 +2891,7 @@
         "inspect",
         "get_domain_guide"
       ],
-      "source": "src/tools/spec.ts:1383",
+      "source": "src/tools/spec.ts:1398",
       "symbol": "listAntiPatterns",
       "returns": "JSON: `{ total, count, next_cursor?, anti_patterns: UPGCuratedAntiPattern[] }`",
       "return_shape": "{ total, count, next_cursor?, anti_patterns: UPGCuratedAntiPattern[] }",
@@ -2928,7 +2992,7 @@
         "list_domains",
         "list_anti_patterns"
       ],
-      "source": "src/tools/spec.ts:1472",
+      "source": "src/tools/spec.ts:1487",
       "symbol": "listBenchmarks",
       "returns": "JSON: `{ kind, total, count, benchmarks: ... }`",
       "return_shape": "{ kind, total, count, benchmarks:... }",
@@ -2956,7 +3020,7 @@
         "list_portfolio_cross_edges",
         "migrate_cross_edges"
       ],
-      "source": "src/tools/spec.ts:1072",
+      "source": "src/tools/spec.ts:1087",
       "symbol": "listCrossEdgeTypes",
       "returns": "JSON: `{ count, types: readonly UPGCrossEdgeType[] }`",
       "return_shape": "{ count, types: readonly UPGCrossEdgeType[] }",
@@ -2984,7 +3048,7 @@
         "list_domains",
         "get_domain_guide"
       ],
-      "source": "src/tools/spec.ts:1860",
+      "source": "src/tools/spec.ts:1875",
       "symbol": "listDomainRings",
       "returns": "JSON: `{ rings: UPGDomainRing[], total: number }`",
       "return_shape": "{ rings: UPGDomainRing[], total: number }",
@@ -3019,7 +3083,7 @@
         "list_regions",
         "list_entity_types"
       ],
-      "source": "src/tools/spec.ts:711",
+      "source": "src/tools/spec.ts:726",
       "symbol": "listDomains",
       "returns": "JSON: `{ count, domains: Array<{ domain_id, anchor_entity, creation_sequence } | { domain_id, label, description, types, has_guide }> }`",
       "return_shape": "{ count, domains: Array<{ domain_id, anchor_entity, creation_sequence } | { domain_id, label, description, types, has_guide }> }",
@@ -3054,7 +3118,7 @@
         "list_edge_types",
         "validate_graph"
       ],
-      "source": "src/tools/spec.ts:1644",
+      "source": "src/tools/spec.ts:1659",
       "symbol": "listEdgeMigrations",
       "returns": "JSON: `{ migrations: [{ kind, from, to?, since }], total: number }`",
       "return_shape": "{ migrations: [{ kind, from, to?, since }], total: number }",
@@ -3093,7 +3157,7 @@
         "list_edge_migrations",
         "create_edge"
       ],
-      "source": "src/tools/spec.ts:858",
+      "source": "src/tools/spec.ts:873",
       "symbol": "listEdgeTypes",
       "returns": "JSON: `{ count, edges: Array<{ type, forward_verb, reverse_verb, classification, source_type, target_type }> }`",
       "return_shape": "{ count, edges: Array<{ type, forward_verb, reverse_verb, classification, source_type, target_type }> }",
@@ -3151,7 +3215,7 @@
         "list_type_migrations",
         "list_domains"
       ],
-      "source": "src/tools/spec.ts:1284",
+      "source": "src/tools/spec.ts:1299",
       "symbol": "listEntityTypes",
       "returns": "JSON: `{ total, count, next_cursor?, types: Array<EntityTypeMeta & { domain_id: string | null }> }`",
       "return_shape": "{ total, count, next_cursor?, types: Array<EntityTypeMeta & { domain_id: string | null }> }",
@@ -3178,7 +3242,7 @@
         "list_frameworks",
         "list_framework_structure_patterns"
       ],
-      "source": "src/tools/spec.ts:1816",
+      "source": "src/tools/spec.ts:1831",
       "symbol": "listFrameworkCategories",
       "returns": "JSON: `{ categories: string[], total: number }`",
       "return_shape": "{ categories: string[], total: number }",
@@ -3206,7 +3270,7 @@
         "list_framework_categories",
         "get_framework"
       ],
-      "source": "src/tools/spec.ts:1837",
+      "source": "src/tools/spec.ts:1852",
       "symbol": "listFrameworkStructurePatterns",
       "returns": "JSON: `{ patterns: string[], total: number }`",
       "return_shape": "{ patterns: string[], total: number }",
@@ -3249,7 +3313,7 @@
         "prioritise",
         "list_approaches"
       ],
-      "source": "src/tools/spec.ts:778",
+      "source": "src/tools/spec.ts:793",
       "symbol": "listFrameworks",
       "returns": "JSON: `{ total, count, next_cursor?, frameworks: UPGFramework[] }`",
       "return_shape": "{ total, count, next_cursor?, frameworks: UPGFramework[] }",
@@ -3278,7 +3342,7 @@
         "list_playbooks",
         "list_frameworks"
       ],
-      "source": "src/tools/spec.ts:1101",
+      "source": "src/tools/spec.ts:1116",
       "symbol": "listLenses",
       "returns": "JSON: `{ count, lenses: Array<{ id, name, description, icon, audience, perspective, framework_id?, playbook_id?, visible_domain_count, intelligence_prompt_count }> }`",
       "return_shape": "{ count, lenses: Array<{ id, name, description, icon, audience, perspective, framework_id?, playbook_id?, visible_domain_count, intelligence_prompt_count }> }",
@@ -3315,7 +3379,7 @@
         "list_entity_types",
         "get_entity_meta"
       ],
-      "source": "src/tools/spec.ts:1709",
+      "source": "src/tools/spec.ts:1724",
       "symbol": "listLifecycles",
       "returns": "JSON: `{ lifecycles, total, free_types: string[], planned_types: string[] }`",
       "return_shape": "{ lifecycles, total, free_types: string[], planned_types: string[] }",
@@ -3386,7 +3450,7 @@
         "list_domain_rings",
         "create_product"
       ],
-      "source": "src/tools/spec.ts:1580",
+      "source": "src/tools/spec.ts:1595",
       "symbol": "listProductStages",
       "returns": "JSON: `{ count, stages: readonly UPGProductStage[] }`",
       "return_shape": "{ count, stages: readonly UPGProductStage[] }",
@@ -3415,7 +3479,7 @@
         "list_domains",
         "list_playbooks"
       ],
-      "source": "src/tools/spec.ts:904",
+      "source": "src/tools/spec.ts:919",
       "symbol": "listRegions",
       "returns": "JSON: `{ count, regions: Array<{ id, label, order, shape, mental_model, anchor_type, composes_atomic_domains, entity_count, intra_edge_count, boundary_edge_count }> }`",
       "return_shape": "{ count, regions: Array<{ id, label, order, shape, mental_model, anchor_type, composes_atomic_domains, entity_count, intra_edge_count, boundary_edge_count }> }",
@@ -3442,7 +3506,7 @@
         "get_scale",
         "get_entity_schema"
       ],
-      "source": "src/tools/spec.ts:1782",
+      "source": "src/tools/spec.ts:1797",
       "symbol": "listScales",
       "returns": "JSON: `{ scales: UPGScaleDefinition[], total: number }`",
       "return_shape": "{ scales: UPGScaleDefinition[], total: number }",
@@ -3471,7 +3535,7 @@
         "migrate_type",
         "validate_graph"
       ],
-      "source": "src/tools/spec.ts:1681",
+      "source": "src/tools/spec.ts:1696",
       "symbol": "listSplitMigrations",
       "returns": "JSON: `{ splits: [...], total: number }`",
       "return_shape": "{ splits: [...], total: number }",
@@ -3508,7 +3572,7 @@
         "list_entity_types",
         "get_entity_meta"
       ],
-      "source": "src/tools/spec.ts:1167",
+      "source": "src/tools/spec.ts:1182",
       "symbol": "listTypeLabels",
       "returns": "JSON: `{ total, count, next_cursor?, labels: UPGTypeLabel[] }`",
       "return_shape": "{ total, count, next_cursor?, labels: UPGTypeLabel[] }",
@@ -3544,7 +3608,7 @@
         "validate_graph",
         "list_entity_types"
       ],
-      "source": "src/tools/spec.ts:1613",
+      "source": "src/tools/spec.ts:1628",
       "symbol": "listTypeMigrations",
       "returns": "JSON: `{ migrations: [{ from, to, since }], total: number }`",
       "return_shape": "{ migrations: [{ from, to, since }], total: number }",
@@ -3552,14 +3616,18 @@
     },
     {
       "name": "plan",
-      "description": "Plan approach: path of arrival to \"what should I build next?\". Returns the Plan record + invocation params wrapped in `{ approach_id, scope, generated_at, approach, params }`. The LLM consumes `signature_hint` and synthesises `{ missing_entities, coverage_score }` against the live graph. Optional `region` narrows scope.",
+      "description": "Plan approach: path of arrival to \"what should I build next?\". Returns the Plan record + invocation params wrapped in `{ approach_id, scope, generated_at, approach, params }`. The LLM consumes `signature_hint` and synthesises `{ missing_entities, coverage_score }` against the live graph. Optional `region` narrows scope; omit `region` to scope to the product's ACTIVE regions; pass `exhaustive:true` to score the full type universe (UPG-601).",
       "domain": "spec",
       "inputSchema": {
         "type": "object",
         "properties": {
           "region": {
             "type": "string",
-            "description": "Optional UPGRegionId. Narrows planning scope to a single region (e.g. \"users_needs\", \"business_gtm_growth\"). Omit for whole-graph planning."
+            "description": "Optional UPGRegionId or atomic-domain id. Narrows planning scope to a single region (e.g. \"users_needs\", \"business_gtm_growth\"). Omit to scope to the product's active regions."
+          },
+          "exhaustive": {
+            "type": "boolean",
+            "description": "If true, score against the entire 312-type universe (every domain creation sequence). Off by default; whole-universe gap scoring is noisy for a focused product. Only applies when `region` is omitted."
           }
         }
       },
@@ -3599,15 +3667,18 @@
             "items": {
               "type": "string"
             },
-            "description": "Required. entity_id[] to rank."
+            "description": "entity_id[] to rank. Optional when exercise_id is given (the exercise supplies them)."
           },
           "framework_id": {
             "type": "string",
             "description": "Required. UPGFramework.id of the scoring lens (e.g. \"rice-scoring\", \"ice-scoring\", \"kano-model\", \"cost-of-delay\", \"wsjf\")."
+          },
+          "exercise_id": {
+            "type": "string",
+            "description": "Optional (0.8.4). A framework_exercise id: reads each candidate's scoring inputs from its includes-edge properties instead of node.properties, and bypasses the target-type guard so any entity type can be scored."
           }
         },
         "required": [
-          "candidates",
           "framework_id"
         ]
       },
@@ -3623,7 +3694,7 @@
         "plan",
         "trace"
       ],
-      "source": "src/tools/spec.ts:518",
+      "source": "src/tools/spec.ts:527",
       "symbol": "prioritise",
       "returns": "JSON envelope: `{ approach_id, scope, generated_at, approach,\nparams, framework_resolved, ranked?, required_properties?,\nhint?, execution_mode }`. Execution mode is `\"execution_v0_4_0\"` when\nthe framework has an expression, `\"definition_lookup_v0_4_0\"` otherwise.",
       "return_notes": [
@@ -3675,7 +3746,7 @@
         "plan",
         "get_anti_pattern"
       ],
-      "source": "src/tools/spec.ts:661",
+      "source": "src/tools/spec.ts:676",
       "symbol": "reflect",
       "returns": "JSON envelope: `{ approach_id, scope, generated_at, approach,\nparams, prompts, execution_mode: \"execution_v0_4_0\" }`",
       "return_notes": [
@@ -3723,12 +3794,56 @@
         "create_edge",
         "trace"
       ],
-      "source": "src/tools/spec.ts:1040",
+      "source": "src/tools/spec.ts:1055",
       "symbol": "resolveEdgeForPair",
       "returns": "JSON: `{ source_type, target_type, edge_type: string | null,\nanchor_hint?, alternate_anchors?, adjacent_edges? }`",
       "return_shape": "{ source_type, target_type, edge_type: string | null, anchor_hint?, alternate_anchors?, adjacent_edges? }",
       "atomicity": "atomic (read-only)"
     },
+    {
+      "name": "score_entity",
+      "description": "Record a framework's result for one entity on the exercise's includes edge (a MoSCoW bucket, a RICE score, a canvas slot). Auto-includes the entity if not already in scope. Merges into existing edge properties unless replace is set. Returns { edge, warnings }.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "exercise_id": {
+            "type": "string",
+            "description": "Required. The framework_exercise id."
+          },
+          "entity_id": {
+            "type": "string",
+            "description": "Required. The entity being scored."
+          },
+          "values": {
+            "type": "object",
+            "description": "Required. The result as { input: value }, e.g. { \"moscow\": \"must\" } or { \"reach\": 800, \"impact\": 3 }."
+          },
+          "replace": {
+            "type": "boolean",
+            "description": "Replace the edge properties instead of merging (default false)."
+          }
+        },
+        "required": [
+          "exercise_id",
+          "entity_id",
+          "values"
+        ]
+      },
+      "throws": [
+        "textError when the exercise/entity is missing or the node is not a\nframework_exercise."
+      ],
+      "examples": [],
+      "warnings": [],
+      "see": [
+        "apply_framework"
+      ],
+      "source": "src/tools/frameworks.ts:63",
+      "symbol": "scoreEntity",
+      "returns": "JSON: `{ edge, warnings }`.",
+      "return_shape": "{ edge, warnings }",
+      "atomicity": "atomic."
+    },
     {
       "name": "trace",
       "description": "[LLM-mediated] This tool returns a routing envelope, not computed results. For user-facing tracing, invoke the /upg-trace skill instead of calling this tool directly. Trace approach: path of arrival to \"walk a meaningful path through existing graph\". Returns the Trace record + invocation params in the family-resemblance envelope. The LLM uses `anchor` + `path` to compose `query()` calls and emits `{ trail: [{ depth, entity_id, edge_type_in }], reached: entity_id[] }`. `path` is type-shorthand: `[\"persona\",\"job\",\"feature\"]` walks persona→job→feature using the canonical edge per pair (via `resolve_edge_for_pair`). Optional `edges_override` selects non-canonical edges per hop; `null` per element means \"use canonical\".",
@@ -3782,7 +3897,7 @@
         "plan",
         "prioritise"
       ],
-      "source": "src/tools/spec.ts:598",
+      "source": "src/tools/spec.ts:613",
       "symbol": "trace",
       "returns": "JSON envelope: `{ approach_id, scope, generated_at, approach,\nparams, trail, reached, error?, halted_at_depth?,\nexecution_mode: \"execution_v0_4_0\" }`",
       "return_notes": [
@@ -3999,7 +4114,7 @@
       ],
       "warnings": [],
       "see": [],
-      "source": "src/tools/skills.ts:191",
+      "source": "src/tools/skills.ts:207",
       "symbol": "skillAudit",
       "returns": "`{ skills: SkillAuditRecord[] }`",
       "return_shape": "{ skills: SkillAuditRecord[] }",