cadence-skill-installer 0.2.10 → 0.2.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cadence-skill-installer",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "description": "Install the Cadence skill into supported AI tool skill directories.",
   "repository": "https://github.com/snowdamiz/cadence",
   "private": false,

package/skill/scripts/query-ideation-research.py

@@ -4,13 +4,28 @@
 from __future__ import annotations
 
 import argparse
+from difflib import SequenceMatcher
 import json
+import re
 import sys
 from pathlib import Path
 from typing import Any
 
 from ideation_research import ResearchAgendaValidationError, normalize_ideation_research, slugify
 
+FUZZY_TEXT_FIELDS: tuple[str, ...] = (
+    "block.title",
+    "block.rationale",
+    "block.tags",
+    "topic.title",
+    "topic.category",
+    "topic.why_it_matters",
+    "topic.research_questions",
+    "topic.keywords",
+    "topic.tags",
+)
+TOKEN_PATTERN = re.compile(r"[a-z0-9]+")
+
 
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(
@@ -28,6 +43,25 @@ def parse_args() -> argparse.Namespace:
     parser.add_argument("--tag", help="Filter by topic or block tag")
     parser.add_argument("--priority", choices=["high", "medium", "low"], help="Filter by priority")
     parser.add_argument("--text", help="Case-insensitive text search across topic and block fields")
+    parser.add_argument(
+        "--fuzzy-text",
+        action="store_true",
+        help="Enable fuzzy matching for --text instead of strict substring matching",
+    )
+    parser.add_argument(
+        "--fuzzy-threshold",
+        type=float,
+        default=0.72,
+        help="Fuzzy score threshold between 0.0 and 1.0 (default: 0.72)",
+    )
+    parser.add_argument(
+        "--fuzzy-fields",
+        help=(
+            "Comma-separated fuzzy field paths. "
+            f"Supported: {', '.join(FUZZY_TEXT_FIELDS)}. "
+            "If omitted, all supported fields are searched."
+        ),
+    )
     parser.add_argument(
         "--include-related",
         action="store_true",
@@ -56,6 +90,111 @@ def _lower(value: Any) -> str:
     return str(value).strip().lower()
 
 
+def _field_text(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value.strip()
+    if isinstance(value, (list, tuple, set)):
+        return " ".join(part for part in (_field_text(item) for item in value) if part)
+    return str(value).strip()
+
+
+def _entry_field_map(entry: dict[str, Any]) -> dict[str, str]:
+    topic = entry.get("topic", {})
+    return {
+        "block.title": _field_text(entry.get("block_title", "")),
+        "block.rationale": _field_text(entry.get("block_rationale", "")),
+        "block.tags": _field_text(entry.get("block_tags", [])),
+        "topic.title": _field_text(topic.get("title", "")),
+        "topic.category": _field_text(topic.get("category", "")),
+        "topic.why_it_matters": _field_text(topic.get("why_it_matters", "")),
+        "topic.research_questions": _field_text(topic.get("research_questions", [])),
+        "topic.keywords": _field_text(topic.get("keywords", [])),
+        "topic.tags": _field_text(topic.get("tags", [])),
+    }
+
+
+def _parse_fuzzy_fields(raw_fields: str | None) -> list[str]:
+    if not raw_fields:
+        return []
+    fields = [value.strip() for value in raw_fields.split(",") if value.strip()]
+    if not fields:
+        raise ValueError("FUZZY_FIELDS_EMPTY")
+
+    invalid_fields = sorted({field for field in fields if field not in FUZZY_TEXT_FIELDS})
+    if invalid_fields:
+        supported = ", ".join(FUZZY_TEXT_FIELDS)
+        invalid = ", ".join(invalid_fields)
+        raise ValueError(f"UNKNOWN_FUZZY_FIELDS: {invalid}. Supported fields: {supported}")
+
+    unique_fields: list[str] = []
+    for field in fields:
+        if field not in unique_fields:
+            unique_fields.append(field)
+    return unique_fields
+
+
+def _tokenize(value: str) -> list[str]:
+    return TOKEN_PATTERN.findall(_lower(value))
+
+
+def _token_overlap_ratio(query: str, candidate: str) -> float:
+    query_tokens = set(_tokenize(query))
+    candidate_tokens = set(_tokenize(candidate))
+    if not query_tokens or not candidate_tokens:
+        return 0.0
+    return len(query_tokens & candidate_tokens) / float(len(query_tokens))
+
+
+def _fuzzy_score(query: str, candidate: str) -> float:
+    query_norm = _lower(query)
+    candidate_norm = _lower(candidate)
+    if not query_norm or not candidate_norm:
+        return 0.0
+    if query_norm in candidate_norm:
+        return 1.0
+
+    best = max(
+        SequenceMatcher(None, query_norm, candidate_norm).ratio(),
+        _token_overlap_ratio(query_norm, candidate_norm),
+    )
+
+    candidate_tokens = _tokenize(candidate_norm)
+    query_token_count = max(1, len(_tokenize(query_norm)))
+    max_span = min(len(candidate_tokens), max(query_token_count + 1, 3))
+    for span in range(1, max_span + 1):
+        for start in range(0, len(candidate_tokens) - span + 1):
+            phrase = " ".join(candidate_tokens[start : start + span])
+            score = SequenceMatcher(None, query_norm, phrase).ratio()
+            if score > best:
+                best = score
+    return best
+
+
+def _fuzzy_text_match(
+    query: str,
+    entry: dict[str, Any],
+    *,
+    threshold: float,
+    fields: list[str],
+) -> tuple[bool, float, list[str]]:
+    field_map = _entry_field_map(entry)
+    target_fields = fields or list(FUZZY_TEXT_FIELDS)
+
+    best_score = 0.0
+    matched_fields: list[str] = []
+    for field in target_fields:
+        candidate = field_map.get(field, "")
+        score = _fuzzy_score(query, candidate)
+        if score > best_score:
+            best_score = score
+        if score >= threshold:
+            matched_fields.append(field)
+
+    return best_score >= threshold, best_score, sorted(set(matched_fields))
+
+
 def _searchable_text(block: dict[str, Any], topic: dict[str, Any]) -> str:
     fields = [
         topic.get("title", ""),
@@ -99,6 +238,21 @@ def main() -> int:
     args = parse_args()
     payload_path = Path(args.file)
 
+    if not 0.0 <= args.fuzzy_threshold <= 1.0:
+        print("INVALID_FUZZY_THRESHOLD: must be between 0.0 and 1.0", file=sys.stderr)
+        return 2
+    if args.fuzzy_text and not args.text:
+        print("FUZZY_TEXT_REQUIRES_TEXT_FILTER: provide --text when using --fuzzy-text", file=sys.stderr)
+        return 2
+    if args.fuzzy_fields and not args.fuzzy_text:
+        print("FUZZY_FIELDS_REQUIRES_FUZZY_TEXT: use --fuzzy-text with --fuzzy-fields", file=sys.stderr)
+        return 2
+    try:
+        fuzzy_fields = _parse_fuzzy_fields(args.fuzzy_fields)
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+
     try:
         ideation_payload, source_type = read_payload(payload_path)
     except ValueError as exc:
@@ -168,6 +322,7 @@ def main() -> int:
             )
 
     matched_topics: list[dict[str, Any]] = []
+    fuzzy_match_meta: dict[str, dict[str, Any]] = {}
     for entry in flat_topics:
         topic = entry["topic"]
         topic_id = str(topic.get("topic_id", "")).strip()
@@ -189,15 +344,29 @@ def main() -> int:
             if tag_value not in topic_tags and tag_value not in block_tags:
                 continue
         if args.text:
-            if _lower(args.text) not in _searchable_text(
-                {
-                    "title": entry["block_title"],
-                    "rationale": entry["block_rationale"],
-                    "tags": entry["block_tags"],
-                },
-                topic,
-            ):
-                continue
+            if args.fuzzy_text:
+                is_match, score, matched_fields = _fuzzy_text_match(
+                    args.text,
+                    entry,
+                    threshold=args.fuzzy_threshold,
+                    fields=fuzzy_fields,
+                )
+                if not is_match:
+                    continue
+                fuzzy_match_meta[topic_id] = {
+                    "score": round(score, 4),
+                    "matched_fields": matched_fields,
+                }
+            else:
+                if _lower(args.text) not in _searchable_text(
+                    {
+                        "title": entry["block_title"],
+                        "rationale": entry["block_rationale"],
+                        "tags": entry["block_tags"],
+                    },
+                    topic,
+                ):
+                    continue
 
         matched_topics.append(entry)
 
@@ -284,6 +453,11 @@ def main() -> int:
                     related_entities.append(entity)
             topic_payload["related_entity_details"] = related_entities
 
+        if args.fuzzy_text and args.text:
+            fuzzy_metadata = fuzzy_match_meta.get(str(topic_payload.get("topic_id", "")).strip())
+            if fuzzy_metadata is not None:
+                topic_payload["fuzzy_match"] = fuzzy_metadata
+
         topics_result.append(topic_payload)
 
     related_payload: dict[str, Any] = {}
@@ -319,6 +493,9 @@ def main() -> int:
             "tag": args.tag or None,
             "priority": args.priority or None,
             "text": args.text or None,
+            "fuzzy_text": bool(args.fuzzy_text),
+            "fuzzy_threshold": args.fuzzy_threshold if args.fuzzy_text else None,
+            "fuzzy_fields": (fuzzy_fields or list(FUZZY_TEXT_FIELDS)) if args.fuzzy_text else None,
             "include_related": bool(args.include_related),
         },
         "summary": {
@@ -333,6 +510,9 @@ def main() -> int:
         },
     }
 
+    if args.fuzzy_text and fuzzy_match_meta:
+        response["summary"]["best_fuzzy_score"] = max(meta["score"] for meta in fuzzy_match_meta.values())
+
     if related_payload:
         response["related"] = related_payload
 

package/skill/scripts/query-json-fuzzy.py

@@ -0,0 +1,294 @@
+#!/usr/bin/env python3
+"""General-purpose fuzzy search over JSON scalar fields.
+
+This script is intentionally standalone and not wired into any existing Cadence flow.
+It searches recursively across arbitrary JSON structures and can target specific fields
+using key/path patterns. Identifier-like keys are excluded by default.
+"""
+
+from __future__ import annotations
+
+import argparse
+from difflib import SequenceMatcher
+from fnmatch import fnmatchcase
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+TOKEN_PATTERN = re.compile(r"[a-z0-9]+")
+IDENTIFIER_KEY_PATTERN = re.compile(
+    r"(?:^|[_-])(id|ids|uuid|guid|slug|slugs|identifier|identifiers|key|keys|token|tokens|hash|checksum|fingerprint|ref|refs|code|codes|path|paths|url|urls|uri|uris|file|files|filepath|filepaths)$",
+    re.IGNORECASE,
+)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Fuzzy-search JSON scalar fields (all current/future fields by default)."
+    )
+    parser.add_argument(
+        "--file",
+        default=str(Path(".cadence") / "cadence.json"),
+        help="Path to any JSON file (default: .cadence/cadence.json)",
+    )
+    parser.add_argument("--text", required=True, help="Query text to fuzzy-match")
+    parser.add_argument(
+        "--threshold",
+        type=float,
+        default=0.72,
+        help="Minimum fuzzy score between 0.0 and 1.0 (default: 0.72)",
+    )
+    parser.add_argument(
+        "--limit",
+        type=int,
+        default=25,
+        help="Maximum matches returned, sorted by score descending (default: 25)",
+    )
+    parser.add_argument(
+        "--field",
+        action="append",
+        default=[],
+        help=(
+            "Include only matching fields (repeatable, supports * wildcard). "
+            "Matches against full path and terminal key. Example: --field 'ideation.*.title' --field title"
+        ),
+    )
+    parser.add_argument(
+        "--exclude-field",
+        action="append",
+        default=[],
+        help=(
+            "Exclude matching fields (repeatable, supports * wildcard). "
+            "Matches against full path and terminal key."
+        ),
+    )
+    parser.add_argument(
+        "--include-identifiers",
+        action="store_true",
+        help="Include normally excluded technical keys (ids, uuid, slug, key, path, url, file, etc.)",
+    )
+    parser.add_argument(
+        "--include-non-string",
+        action="store_true",
+        help="Also search numbers/booleans (strings are always searched)",
+    )
+    parser.add_argument(
+        "--min-length",
+        type=int,
+        default=2,
+        help="Skip string values shorter than this length (default: 2)",
+    )
+    return parser.parse_args()
+
+
+def _lower(value: Any) -> str:
+    return str(value).strip().lower()
+
+
+def _normalize_key(key: str) -> str:
+    # Convert camelCase to snake-like form before identifier checks.
+    snakeish = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", str(key))
+    return _lower(snakeish)
+
+
+def _is_identifier_key(key: str) -> bool:
+    normalized = _normalize_key(key)
+    return bool(IDENTIFIER_KEY_PATTERN.search(normalized))
+
+
+def _normalize_patterns(values: list[str]) -> list[str]:
+    patterns: list[str] = []
+    for raw_value in values:
+        for part in str(raw_value).split(","):
+            candidate = _lower(part)
+            if candidate and candidate not in patterns:
+                patterns.append(candidate)
+    return patterns
+
+
+def _path_or_key_matches(patterns: list[str], path: str, key: str) -> bool:
+    path_norm = _lower(path)
+    key_norm = _normalize_key(key)
+    return any(fnmatchcase(path_norm, pattern) or fnmatchcase(key_norm, pattern) for pattern in patterns)
+
+
+def _tokenize(value: str) -> list[str]:
+    return TOKEN_PATTERN.findall(_lower(value))
+
+
+def _token_overlap_ratio(query: str, candidate: str) -> float:
+    query_tokens = set(_tokenize(query))
+    candidate_tokens = set(_tokenize(candidate))
+    if not query_tokens or not candidate_tokens:
+        return 0.0
+    return len(query_tokens & candidate_tokens) / float(len(query_tokens))
+
+
+def _fuzzy_score(query: str, candidate: str) -> float:
+    query_norm = _lower(query)
+    candidate_norm = _lower(candidate)
+    if not query_norm or not candidate_norm:
+        return 0.0
+    if query_norm in candidate_norm:
+        return 1.0
+
+    best = max(
+        SequenceMatcher(None, query_norm, candidate_norm).ratio(),
+        _token_overlap_ratio(query_norm, candidate_norm),
+    )
+
+    candidate_tokens = _tokenize(candidate_norm)
+    query_token_count = max(1, len(_tokenize(query_norm)))
+    max_span = min(len(candidate_tokens), max(query_token_count + 1, 3))
+    for span in range(1, max_span + 1):
+        for start in range(0, len(candidate_tokens) - span + 1):
+            phrase = " ".join(candidate_tokens[start : start + span])
+            score = SequenceMatcher(None, query_norm, phrase).ratio()
+            if score > best:
+                best = score
+    return best
+
+
+def _preview(value: str, limit: int = 220) -> str:
+    text = value.strip()
+    if len(text) <= limit:
+        return text
+    return text[: limit - 3] + "..."
+
+
+def _iter_scalar_candidates(node: Any, *, path: str = "", key: str = ""):
+    if isinstance(node, dict):
+        for child_key, child_value in node.items():
+            child_key_text = str(child_key)
+            child_path = f"{path}.{child_key_text}" if path else child_key_text
+            yield from _iter_scalar_candidates(child_value, path=child_path, key=child_key_text)
+        return
+
+    if isinstance(node, list):
+        for index, item in enumerate(node):
+            child_path = f"{path}[{index}]"
+            yield from _iter_scalar_candidates(item, path=child_path, key=key)
+        return
+
+    yield {
+        "path": path,
+        "key": key,
+        "value": node,
+    }
+
+
+def _load_json(path: Path) -> Any:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except OSError as exc:
+        raise ValueError(f"PAYLOAD_READ_FAILED: {exc}") from exc
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"INVALID_PAYLOAD_JSON: {exc}") from exc
+
+
+def main() -> int:
+    args = parse_args()
+    payload_path = Path(args.file)
+
+    if not 0.0 <= args.threshold <= 1.0:
+        print("INVALID_THRESHOLD: must be between 0.0 and 1.0", file=sys.stderr)
+        return 2
+    if args.limit < 1:
+        print("INVALID_LIMIT: must be >= 1", file=sys.stderr)
+        return 2
+    if args.min_length < 0:
+        print("INVALID_MIN_LENGTH: must be >= 0", file=sys.stderr)
+        return 2
+
+    include_patterns = _normalize_patterns(args.field)
+    exclude_patterns = _normalize_patterns(args.exclude_field)
+
+    try:
+        payload = _load_json(payload_path)
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+
+    candidates_scanned = 0
+    candidates_considered = 0
+    matches: list[dict[str, Any]] = []
+
+    for candidate in _iter_scalar_candidates(payload):
+        candidates_scanned += 1
+        field_path = str(candidate["path"])
+        field_key = str(candidate["key"])
+
+        if not args.include_identifiers and _is_identifier_key(field_key):
+            continue
+        if include_patterns and not _path_or_key_matches(include_patterns, field_path, field_key):
+            continue
+        if exclude_patterns and _path_or_key_matches(exclude_patterns, field_path, field_key):
+            continue
+
+        raw_value = candidate["value"]
+        if isinstance(raw_value, str):
+            text_value = raw_value.strip()
+            value_type = "string"
+        elif args.include_non_string and isinstance(raw_value, (int, float, bool)):
+            text_value = str(raw_value)
+            value_type = type(raw_value).__name__
+        else:
+            continue
+
+        if len(text_value) < args.min_length:
+            continue
+
+        candidates_considered += 1
+        score = _fuzzy_score(args.text, text_value)
+        if score < args.threshold:
+            continue
+
+        matches.append(
+            {
+                "path": field_path,
+                "field": field_key,
+                "value_type": value_type,
+                "score": round(score, 4),
+                "value_preview": _preview(text_value),
+            }
+        )
+
+    matches_sorted = sorted(
+        matches,
+        key=lambda item: (-item["score"], item["path"]),
+    )
+    results = matches_sorted[: args.limit]
+
+    response: dict[str, Any] = {
+        "status": "ok",
+        "path": str(payload_path),
+        "query": {
+            "text": args.text,
+            "threshold": args.threshold,
+            "limit": args.limit,
+            "field": include_patterns or None,
+            "exclude_field": exclude_patterns or None,
+            "include_identifiers": bool(args.include_identifiers),
+            "include_non_string": bool(args.include_non_string),
+            "min_length": args.min_length,
+        },
+        "summary": {
+            "candidates_scanned": candidates_scanned,
+            "candidates_considered": candidates_considered,
+            "matches_before_limit": len(matches_sorted),
+            "matches_returned": len(results),
+        },
+        "results": results,
+    }
+
+    if results:
+        response["summary"]["best_score"] = max(item["score"] for item in results)
+
+    print(json.dumps(response, indent=4))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skill/skills/ideation-updater/SKILL.md

@@ -36,12 +36,28 @@ description: Discuss, audit, and update existing project ideation in .cadence/ca
    - Fields unchanged
    - Research blocks/entities/topics affected
 12. Persist only after user confirmation.
-13. For any persistence mode (add, modify, or remove):
-   - Write the complete updated ideation object to `"$PROJECT_ROOT/.cadence/ideation_payload.json"`.
+13. Use this canonical ideation payload contract and do not inspect Cadence scripts to infer shape during normal operation:
+   - Payload root must be a JSON object representing the full updated `ideation` object.
+   - Preserve unchanged fields and update only confirmed changes; avoid dropping existing keys unless user asked to remove them.
+   - Keep core ideation fields explicit where relevant, including:
+     - `objective`, `core_outcome`, `target_audience`, `core_experience`
+     - `in_scope`, `out_of_scope`, `implementation_approach`
+     - `milestones`, `constraints`, `risks`, `success_signals`, `assumptions`
+   - `research_agenda` should include:
+     - `blocks` (array)
+     - `entity_registry` (array)
+     - `topic_index` (object, set to `{}` in payload; it is rebuilt during normalization)
+   - Each block should include `block_id`, `title`, `rationale`, `tags`, and `topics`.
+   - Each topic should include `topic_id`, `title`, `category`, `priority` (`low|medium|high`), `why_it_matters`, `research_questions`, `keywords`, `tags`, and `related_entities`.
+   - Each entity should include `entity_id`, `label`, `kind`, `aliases`, and `owner_block_id`.
+   - If `state.ideation-completed` is currently true, keep at least one research topic in `blocks` because injection with `--completion-state keep` still enforces non-empty topics.
+   - Relationship rule: every id listed in topic `related_entities` must exist in `entity_registry`, and that entity's `owner_block_id` must match the topic's block.
+14. For any persistence mode (add, modify, or remove):
+   - Write the complete updated ideation object to `"$PROJECT_ROOT/.cadence/ideation_payload.json"` using the contract above.
    - Run `python3 "$CADENCE_SCRIPTS_DIR/prepare-ideation-research.py" --file "$PROJECT_ROOT/.cadence/ideation_payload.json" --allow-empty`.
    - Run `cd "$PROJECT_ROOT" && python3 "$CADENCE_SCRIPTS_DIR/inject-ideation.py" --file "$PROJECT_ROOT/.cadence/ideation_payload.json" --completion-state keep`.
-14. After persistence, confirm result by running `cd "$PROJECT_ROOT" && python3 "$CADENCE_SCRIPTS_DIR/render-ideation-summary.py"`.
-15. Mention that granular research queries are available via `cd "$PROJECT_ROOT" && python3 "$CADENCE_SCRIPTS_DIR/query-ideation-research.py"`.
-16. At end of this successful skill conversation, run `cd "$PROJECT_ROOT" && python3 "$CADENCE_SCRIPTS_DIR/finalize-skill-checkpoint.py" --scope ideation-updater --checkpoint ideation-updated --paths .`.
-17. If `finalize-skill-checkpoint.py` returns `status=no_changes`, continue without failure.
-18. Ask whether to continue refining another aspect or stop.
+15. After persistence, confirm result by running `cd "$PROJECT_ROOT" && python3 "$CADENCE_SCRIPTS_DIR/render-ideation-summary.py"`.
+16. Mention that granular research queries are available via `cd "$PROJECT_ROOT" && python3 "$CADENCE_SCRIPTS_DIR/query-ideation-research.py"`.
+17. At end of this successful skill conversation, run `cd "$PROJECT_ROOT" && python3 "$CADENCE_SCRIPTS_DIR/finalize-skill-checkpoint.py" --scope ideation-updater --checkpoint ideation-updated --paths .`.
+18. If `finalize-skill-checkpoint.py` returns `status=no_changes`, continue without failure.
+19. Ask whether to continue refining another aspect or stop.

package/skill/skills/ideation-updater/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Ideation Updater"
   short_description: "Discuss and update existing project ideation"
-  default_prompt: "Review current project ideation, discuss changes, and persist approved updates. Resolve PROJECT_ROOT first with scripts/resolve-project-root.py --require-cadence, then resolve CADENCE_SCRIPTS_DIR with scripts/resolve-project-scripts-dir.py --project-root \"$PROJECT_ROOT\". Execute state-changing ideation persistence commands from PROJECT_ROOT so .cadence writes and checkpoint commits target the correct repository. Keep research_agenda synchronized with ideation changes by rebuilding the full updated ideation object, running scripts/prepare-ideation-research.py, and then persisting with scripts/inject-ideation.py. Keep user-facing responses focused on ideation outcomes and do not expose internal skill-routing or command traces unless the user explicitly asks. If the user is starting ideation from scratch, route them to a fresh chat with: Start a new chat and either say \"help me define my project\" or share your project brief."
+  default_prompt: "Review current project ideation, discuss changes, and persist approved updates. Resolve PROJECT_ROOT first with scripts/resolve-project-root.py --require-cadence, then resolve CADENCE_SCRIPTS_DIR with scripts/resolve-project-scripts-dir.py --project-root \"$PROJECT_ROOT\". Execute state-changing ideation persistence commands from PROJECT_ROOT so .cadence writes and checkpoint commits target the correct repository. Keep research_agenda synchronized with ideation changes by rebuilding the full updated ideation object. Use the canonical ideation payload contract documented in this skill and do not read script sources just to infer payload shape. Then run scripts/prepare-ideation-research.py and persist with scripts/inject-ideation.py. Keep user-facing responses focused on ideation outcomes and do not expose internal skill-routing or command traces unless the user explicitly asks. If the user is starting ideation from scratch, route them to a fresh chat with: Start a new chat and either say \"help me define my project\" or share your project brief."

package/skill/skills/ideator/SKILL.md

@@ -43,13 +43,36 @@ description: Guide users from a rough concept to a fully defined project idea th
    - Ensure entity relationships are block-consistent: if a topic references an entity, that topic must be in the entity's owner block.
 14. Do not hard-code assumptions. If you infer something, label it explicitly and ask for confirmation.
 15. When coverage is deep enough, present a final ideation summary and ask for confirmation.
-16. After confirmation, persist ideation programmatically:
+16. Use this canonical ideation payload contract and do not inspect Cadence scripts to infer shape during normal operation:
+   - Payload root must be a JSON object representing the full `ideation` object.
+   - Include execution-ready core fields from discovery. Preferred keys:
+     - `objective` (string)
+     - `core_outcome` (string)
+     - `target_audience` (string or array)
+     - `core_experience` (string, array, or object)
+     - `in_scope` (array)
+     - `out_of_scope` (array)
+     - `implementation_approach` (object or array)
+     - `milestones` (array)
+     - `constraints` (array)
+     - `risks` (array)
+     - `success_signals` (array)
+     - `assumptions` (array, optional)
+   - `research_agenda` is required and must include:
+     - `blocks` (array with at least one topic total for ideator completion)
+     - `entity_registry` (array)
+     - `topic_index` (object, set to `{}` in payload; it is rebuilt during normalization)
+   - Each `research_agenda.blocks[]` item should include `block_id`, `title`, `rationale`, `tags`, and `topics`.
+   - Each `topics[]` item should include `topic_id`, `title`, `category`, `priority` (`low|medium|high`), `why_it_matters`, `research_questions`, `keywords`, `tags`, and `related_entities`.
+   - Each `entity_registry[]` item should include `entity_id`, `label`, `kind`, `aliases`, and `owner_block_id`.
+   - Relationship rule: every id listed in topic `related_entities` must exist in `entity_registry`, and that entity's `owner_block_id` must match the topic's block.
+17. After confirmation, persist ideation programmatically:
    - Create a JSON payload file at `"$PROJECT_ROOT/.cadence/ideation_payload.json"`.
-   - Write the full finalized ideation object to that file, including `research_agenda` with `blocks`, `entity_registry`, and relationship-ready topic references.
+   - Write the full finalized ideation object to that file using the contract above.
    - Run `python3 "$CADENCE_SCRIPTS_DIR/prepare-ideation-research.py" --file "$PROJECT_ROOT/.cadence/ideation_payload.json"`.
    - Run `cd "$PROJECT_ROOT" && python3 "$CADENCE_SCRIPTS_DIR/inject-ideation.py" --file "$PROJECT_ROOT/.cadence/ideation_payload.json" --completion-state complete` (this injects ideation and deletes the payload file on success).
-17. Verify persistence by running `cd "$PROJECT_ROOT" && python3 "$CADENCE_SCRIPTS_DIR/get-ideation.py"`.
-18. Mention that granular research queries are available via `cd "$PROJECT_ROOT" && python3 "$CADENCE_SCRIPTS_DIR/query-ideation-research.py"`.
-19. At end of this successful skill conversation, run `cd "$PROJECT_ROOT" && python3 "$CADENCE_SCRIPTS_DIR/finalize-skill-checkpoint.py" --scope ideator --checkpoint ideation-completed --paths .`.
-20. If `finalize-skill-checkpoint.py` returns `status=no_changes`, continue without failure.
-21. If the user requests revisions later, regenerate the payload, rerun `prepare-ideation-research.py`, and rerun `inject-ideation.py` from `PROJECT_ROOT`.
+18. Verify persistence by running `cd "$PROJECT_ROOT" && python3 "$CADENCE_SCRIPTS_DIR/get-ideation.py"`.
+19. Mention that granular research queries are available via `cd "$PROJECT_ROOT" && python3 "$CADENCE_SCRIPTS_DIR/query-ideation-research.py"`.
+20. At end of this successful skill conversation, run `cd "$PROJECT_ROOT" && python3 "$CADENCE_SCRIPTS_DIR/finalize-skill-checkpoint.py" --scope ideator --checkpoint ideation-completed --paths .`.
+21. If `finalize-skill-checkpoint.py` returns `status=no_changes`, continue without failure.
+22. If the user requests revisions later, regenerate the payload, rerun `prepare-ideation-research.py`, and rerun `inject-ideation.py` from `PROJECT_ROOT`.

package/skill/skills/ideator/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Ideator"
   short_description: "Step-by-step domain-agnostic ideation"
-  default_prompt: "Guide the user from a rough concept or provided project brief to a fully defined idea. Resolve PROJECT_ROOT first with scripts/resolve-project-root.py --require-cadence, then resolve CADENCE_SCRIPTS_DIR with scripts/resolve-project-scripts-dir.py --project-root \"$PROJECT_ROOT\". Before ideation steps, assert route with scripts/assert-workflow-route.py --skill-name ideator --project-root \"$PROJECT_ROOT\" and stop on mismatch. Execute state-changing ideation persistence commands from PROJECT_ROOT so .cadence writes and checkpoint commits target the correct project. Ask one follow-up question at a time for missing critical details, then produce a complete domain-agnostic research agenda inferred from the ideation discussion with blocks, topics, and entity relationships. Before persistence, run scripts/prepare-ideation-research.py to normalize and validate the research agenda, then inject via scripts/inject-ideation.py. Keep user-facing responses focused on ideation outcomes and do not expose internal skill-routing or command traces unless explicitly requested."
+  default_prompt: "Guide the user from a rough concept or provided project brief to a fully defined idea. Resolve PROJECT_ROOT first with scripts/resolve-project-root.py --require-cadence, then resolve CADENCE_SCRIPTS_DIR with scripts/resolve-project-scripts-dir.py --project-root \"$PROJECT_ROOT\". Before ideation steps, assert route with scripts/assert-workflow-route.py --skill-name ideator --project-root \"$PROJECT_ROOT\" and stop on mismatch. Execute state-changing ideation persistence commands from PROJECT_ROOT so .cadence writes and checkpoint commits target the correct project. Ask one follow-up question at a time for missing critical details, then produce a complete domain-agnostic research agenda inferred from the ideation discussion with blocks, topics, and entity relationships. Use the canonical ideation payload contract documented in this skill (including objective/core_outcome/in_scope/out_of_scope plus research_agenda blocks/entity_registry/topic_index) and do not read script sources just to infer payload shape. Before persistence, run scripts/prepare-ideation-research.py to normalize and validate the research agenda, then inject via scripts/inject-ideation.py. Keep user-facing responses focused on ideation outcomes and do not expose internal skill-routing or command traces unless explicitly requested."