cadence-skill-installer 0.2.11 → 0.2.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cadence-skill-installer",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "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/ideator/SKILL.md

@@ -35,6 +35,8 @@ description: Guide users from a rough concept to a fully defined project idea th
    - scope boundaries (in-scope vs out-of-scope)
    - implementation approach (for example tools, tech stack, process, platforms)
    - delivery shape (milestones, sequencing, constraints, risks, success signals)
+   - assume execution is AI-driven by default; if timeline expectations are discussed, calibrate estimates to roughly 10-100x faster than human-only delivery.
+   - do not force timeline-specific prompts just to apply this assumption.
 13. Build a complete later-phase research agenda from the ideation conversation:
    - Infer all relevant research topics that should be explored in later phases.
    - Keep the agenda domain-agnostic and driven by what the user discussed.