cadence-skill-installer 0.2.21 → 0.2.23

package/README.md

@@ -34,6 +34,20 @@ npx cadence-skill-installer --tools codex,claude,gemini --yes
 - `windsurf`
 - `opencode`
 
+## Release guardrails
+
+This repo enforces release preflight checks through npm lifecycle scripts:
+
+- `preversion`: cleans generated Python artifacts and requires a clean git working tree.
+- `prepack`: removes generated Python artifacts before packaging.
+
+Manual checks:
+
+```bash
+npm run release:preflight
+npm pack --dry-run
+```
+
 ## CI/CD Trusted Publishing (recommended)
 
 This repo includes `/Users/sn0w/Documents/dev/cadence/.github/workflows/publish.yml` for npm trusted publishing (OIDC).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cadence-skill-installer",
-  "version": "0.2.21",
+  "version": "0.2.23",
   "description": "Install the Cadence skill into supported AI tool skill directories.",
   "repository": "https://github.com/snowdamiz/cadence",
   "private": false,
@@ -12,6 +12,12 @@
   "engines": {
     "node": ">=18.0.0"
   },
+  "scripts": {
+    "clean:artifacts": "node scripts/clean-python-artifacts.mjs",
+    "release:preflight": "node scripts/release-preflight.mjs",
+    "prepack": "node scripts/clean-python-artifacts.mjs",
+    "preversion": "node scripts/release-preflight.mjs"
+  },
   "publishConfig": {
     "access": "public"
   },

package/skill/scripts/ideation_research.py

@@ -653,8 +653,20 @@ def normalize_ideation_research(
                 continue
             alias_lookup.setdefault(normalized_alias, set()).add(entity["entity_id"])
 
+    # Track block usage from explicit topic references before alias inference.
+    entity_blocks: dict[str, set[str]] = {}
+    entity_topic_refs: dict[str, list[tuple[str, str]]] = {}
+    for topic_ref in flat_topics:
+        block_id = topic_ref["block_id"]
+        topic_id = _string(topic_ref["topic"].get("topic_id"))
+        for entity_id in topic_ref["topic"]["related_entities"]:
+            entity_blocks.setdefault(entity_id, set()).add(block_id)
+            entity_topic_refs.setdefault(entity_id, []).append((block_id, topic_id))
+
     for topic_ref in flat_topics:
         topic = topic_ref["topic"]
+        topic_block_id = topic_ref["block_id"]
+        topic_id = _string(topic.get("topic_id"))
         haystack = " ".join(
             [
                 _string(topic.get("title")),
@@ -675,14 +687,24 @@ def normalize_ideation_research(
                 detected_ids.append(entity_id)
 
         for entity_id in detected_ids:
-            if entity_id not in topic["related_entities"]:
-                topic["related_entities"].append(entity_id)
+            if entity_id in topic["related_entities"]:
+                continue
 
-    entity_blocks: dict[str, set[str]] = {}
-    for topic_ref in flat_topics:
-        block_id = topic_ref["block_id"]
-        for entity_id in topic_ref["topic"]["related_entities"]:
-            entity_blocks.setdefault(entity_id, set()).add(block_id)
+            entity = entity_index.get(entity_id)
+            if entity is None:
+                continue
+
+            owner_block_id = _string(entity.get("owner_block_id"))
+            referenced_blocks = entity_blocks.get(entity_id, set())
+            # Alias inference is advisory only and must never introduce cross-block links.
+            if owner_block_id and owner_block_id != topic_block_id:
+                continue
+            if referenced_blocks and topic_block_id not in referenced_blocks:
+                continue
+
+            topic["related_entities"].append(entity_id)
+            entity_blocks.setdefault(entity_id, set()).add(topic_block_id)
+            entity_topic_refs.setdefault(entity_id, []).append((topic_block_id, topic_id))
 
     for entity in normalized_entities:
         entity_id = entity["entity_id"]
@@ -690,9 +712,17 @@ def normalize_ideation_research(
         owner_block_id = _string(entity.get("owner_block_id"))
 
         if len(referenced_blocks) > 1:
-            blocks = ", ".join(sorted(referenced_blocks))
+            refs = ", ".join(
+                sorted(
+                    f"{topic_id}@{block_id}"
+                    for block_id, topic_id in entity_topic_refs.get(entity_id, [])
+                    if block_id and topic_id
+                )
+            )
             raise ResearchAgendaValidationError(
-                f"ENTITY_BLOCK_CONFLICT: entity '{entity_id}' is referenced across multiple blocks ({blocks})."
+                f"ENTITY_BLOCK_CONFLICT: entity '{entity_id}' is referenced across multiple blocks "
+                f"({', '.join(sorted(referenced_blocks))})."
+                f"{f' References: {refs}.' if refs else ''}"
             )
 
         if owner_block_id:
@@ -702,9 +732,17 @@ def normalize_ideation_research(
                 )
             if referenced_blocks and owner_block_id not in referenced_blocks:
                 block_label = _ordered_block_choice(referenced_blocks, block_order)
+                refs = ", ".join(
+                    sorted(
+                        f"{topic_id}@{block_id}"
+                        for block_id, topic_id in entity_topic_refs.get(entity_id, [])
+                        if block_id and topic_id
+                    )
+                )
                 raise ResearchAgendaValidationError(
                     f"ENTITY_OWNER_MISMATCH: entity '{entity_id}' owner block '{owner_block_id}' "
                     f"does not match referenced block '{block_label}'."
+                    f"{f' References: {refs}.' if refs else ''}"
                 )
         elif referenced_blocks:
             entity["owner_block_id"] = _ordered_block_choice(referenced_blocks, block_order)

package/skill/tests/test_ideation_research.py

@@ -0,0 +1,146 @@
+import copy
+import sys
+import unittest
+from pathlib import Path
+
+SCRIPTS_DIR = Path(__file__).resolve().parents[1] / "scripts"
+if str(SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIR))
+
+from ideation_research import ResearchAgendaValidationError, normalize_ideation_research
+
+
+def base_payload() -> dict:
+    return {
+        "objective": "test",
+        "research_agenda": {
+            "blocks": [
+                {
+                    "block_id": "block-a",
+                    "title": "Block A",
+                    "rationale": "",
+                    "tags": [],
+                    "topics": [
+                        {
+                            "topic_id": "topic-a1",
+                            "title": "Topic A1",
+                            "category": "general",
+                            "priority": "high",
+                            "why_it_matters": "",
+                            "research_questions": ["q"],
+                            "keywords": [],
+                            "tags": [],
+                            "related_entities": [],
+                        }
+                    ],
+                },
+                {
+                    "block_id": "block-b",
+                    "title": "Block B",
+                    "rationale": "",
+                    "tags": [],
+                    "topics": [
+                        {
+                            "topic_id": "topic-b1",
+                            "title": "Topic B1",
+                            "category": "general",
+                            "priority": "high",
+                            "why_it_matters": "",
+                            "research_questions": ["q"],
+                            "keywords": [],
+                            "tags": [],
+                            "related_entities": [],
+                        }
+                    ],
+                },
+            ],
+            "entity_registry": [],
+            "topic_index": {},
+        },
+    }
+
+
+class IdeationResearchNormalizationTests(unittest.TestCase):
+    def test_alias_inference_does_not_cross_owner_block(self) -> None:
+        payload = base_payload()
+        payload["research_agenda"]["blocks"][0]["topics"][0]["related_entities"] = ["entity-marketplace-fees"]
+        payload["research_agenda"]["blocks"][1]["topics"][0]["keywords"] = ["royalties"]
+        payload["research_agenda"]["entity_registry"] = [
+            {
+                "entity_id": "entity-marketplace-fees",
+                "label": "Marketplace fee system",
+                "kind": "economy-system",
+                "aliases": ["royalties", "platform fees"],
+                "owner_block_id": "block-a",
+            }
+        ]
+
+        normalized = normalize_ideation_research(copy.deepcopy(payload), require_topics=True)
+        topics = normalized["research_agenda"]["blocks"]
+
+        self.assertEqual(
+            topics[0]["topics"][0]["related_entities"],
+            ["entity-marketplace-fees"],
+        )
+        self.assertEqual(topics[1]["topics"][0]["related_entities"], [])
+
+    def test_alias_inference_does_not_cross_existing_ownerless_block_reference(self) -> None:
+        payload = base_payload()
+        payload["research_agenda"]["blocks"][0]["topics"][0]["related_entities"] = ["entity-royalties"]
+        payload["research_agenda"]["blocks"][1]["topics"][0]["keywords"] = ["royalties"]
+        payload["research_agenda"]["entity_registry"] = [
+            {
+                "entity_id": "entity-royalties",
+                "label": "Royalties",
+                "kind": "economy-system",
+                "aliases": ["royalties"],
+                "owner_block_id": "",
+            }
+        ]
+
+        normalized = normalize_ideation_research(copy.deepcopy(payload), require_topics=True)
+        topics = normalized["research_agenda"]["blocks"]
+        entity = normalized["research_agenda"]["entity_registry"][0]
+
+        self.assertEqual(topics[1]["topics"][0]["related_entities"], [])
+        self.assertEqual(entity["owner_block_id"], "block-a")
+
+    def test_explicit_cross_block_reference_still_fails(self) -> None:
+        payload = base_payload()
+        payload["research_agenda"]["blocks"][1]["topics"][0]["related_entities"] = ["entity-marketplace-fees"]
+        payload["research_agenda"]["entity_registry"] = [
+            {
+                "entity_id": "entity-marketplace-fees",
+                "label": "Marketplace fee system",
+                "kind": "economy-system",
+                "aliases": ["royalties"],
+                "owner_block_id": "block-a",
+            }
+        ]
+
+        with self.assertRaises(ResearchAgendaValidationError) as ctx:
+            normalize_ideation_research(copy.deepcopy(payload), require_topics=True)
+
+        self.assertIn("ENTITY_OWNER_MISMATCH", str(ctx.exception))
+
+    def test_same_block_alias_inference_still_links_entity(self) -> None:
+        payload = base_payload()
+        payload["research_agenda"]["blocks"][1]["topics"][0]["keywords"] = ["royalties"]
+        payload["research_agenda"]["entity_registry"] = [
+            {
+                "entity_id": "entity-marketplace-fees",
+                "label": "Marketplace fee system",
+                "kind": "economy-system",
+                "aliases": ["royalties"],
+                "owner_block_id": "block-b",
+            }
+        ]
+
+        normalized = normalize_ideation_research(copy.deepcopy(payload), require_topics=True)
+        block_b_topic = normalized["research_agenda"]["blocks"][1]["topics"][0]
+
+        self.assertEqual(block_b_topic["related_entities"], ["entity-marketplace-fees"])
+
+
+if __name__ == "__main__":
+    unittest.main()