@deftai/directive-content 0.55.1 → 0.56.0

package/scripts/ip_risk.py

@@ -0,0 +1,531 @@
+#!/usr/bin/env python3
+"""ip_risk.py -- Permissive heuristic for detecting third-party intellectual
+property (IP) references in interview / research text (#738).
+
+The detector is intentionally permissive: it errs on the side of false
+positives so that downstream interview steps can ask the user the
+monetization-intent question rather than silently letting an IP-adjacent
+project sail through PRD / SPECIFICATION generation without legal-risk
+flagging.
+
+Usage::
+
+    from ip_risk import detect_ip_terms, ip_risk_scope_items, plain_risk_summary
+
+    hits = detect_ip_terms("A Magic: The Gathering deck-builder app")
+    if hits:
+        items = ip_risk_scope_items(monetization_intent="commercial")
+        summary = plain_risk_summary(hits, monetization_intent="commercial")
+
+The full guidance (heuristic categories, question script, minimum-protection
+checklist) lives in ``references/ip-risk.md``. Keep the term lists in this
+module synchronised with that document.
+
+Exit codes (CLI mode):
+
+    0 -- no IP terms detected
+    1 -- IP terms detected (one term per line on stdout)
+    2 -- usage error (no input provided)
+
+This module is *advisory*. It does NOT provide legal advice and MUST NOT be
+used as a substitute for lawyer consultation when the project is commercial
+and IP-adjacent.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+# ---------------------------------------------------------------------------
+# Heuristic term lists (#738)
+# ---------------------------------------------------------------------------
+# Curated permissive set keyed by category. All matching is case-insensitive
+# and word-boundary based -- substring matches inside a longer word
+# ("magicwand", "starcraft") do NOT trigger.
+#
+# The lists are intentionally short and well-known. The heuristic is meant to
+# catch the *most common* IP-adjacent project ideas that come up in interview
+# sessions (the #151 playtester case was a Magic: The Gathering deck builder),
+# not to be a comprehensive trademark database.
+
+_BRANDED_GAMES_AND_UNIVERSES: tuple[str, ...] = (
+    # Tabletop / collectable card games
+    "Magic: The Gathering",
+    "Magic the Gathering",
+    "MTG",
+    "Yu-Gi-Oh",
+    "Yugioh",
+    "Pokemon",
+    "Pokémon",
+    "Dungeons and Dragons",
+    "Dungeons & Dragons",
+    "D&D",
+    "Warhammer",
+    # Video game franchises
+    "Mario",
+    "Zelda",
+    "Final Fantasy",
+    "Halo",
+    "Call of Duty",
+    "Fortnite",
+    "Minecraft",
+    "Roblox",
+    "League of Legends",
+    "World of Warcraft",
+    "WoW",
+    "Overwatch",
+    "Counter-Strike",
+    "Valorant",
+    "Apex Legends",
+    # Fictional universes
+    "Star Wars",
+    "Star Trek",
+    "Marvel",
+    "DC Comics",
+    "Harry Potter",
+    "Lord of the Rings",
+    "Middle-earth",
+    "Game of Thrones",
+    "Westeros",
+    "Disney",
+    "Pixar",
+)
+
+_BRANDED_CHARACTERS: tuple[str, ...] = (
+    "Mickey Mouse",
+    "Spider-Man",
+    "Spiderman",
+    "Batman",
+    "Superman",
+    "Wonder Woman",
+    "Iron Man",
+    "Hulk",
+    "Captain America",
+    "Pikachu",
+    "Sonic the Hedgehog",
+    "Luigi",
+    "Princess Peach",
+    "Kirby",
+    "Master Chief",
+    "Lara Croft",
+    "Indiana Jones",
+    "James Bond",
+)
+
+_SPORTS_LEAGUES: tuple[str, ...] = (
+    "NFL",
+    "NBA",
+    "MLB",
+    "NHL",
+    "MLS",
+    "FIFA",
+    "UEFA",
+    "Premier League",
+    "La Liga",
+    "Bundesliga",
+    "Olympics",
+    "Olympic Games",
+    "Super Bowl",
+    "World Cup",
+)
+
+_BRANDED_PRODUCTS: tuple[str, ...] = (
+    "iPhone",
+    "iPad",
+    "MacBook",
+    "AirPods",
+    "PlayStation",
+    "Xbox",
+    "Nintendo Switch",
+    "Coca-Cola",
+    "Pepsi",
+    "Starbucks",
+    "McDonald's",
+    "Lego",
+    "Barbie",
+    "Hot Wheels",
+)
+
+_MUSIC_AND_FILM: tuple[str, ...] = (
+    "Taylor Swift",
+    "Beyonce",
+    "Beyoncé",
+    # NOTE: "BTS" and "Drake" were removed (Greptile P2 #775) -- both
+    # false-positive heavily on common technical / proper-noun uses
+    # (BTS = Build-Test-Ship / Behind-The-Scenes / bug-tracking;
+    # Drake = the duck, the surname, Drake University, Sir Francis Drake,
+    # the Drake equation). Re-add only with a music-specific surrounding
+    # context check.
+    "Spotify",
+    "Netflix",
+    "Hulu",
+    "HBO",
+)
+
+# Generic fictional-universe terms that often signal IP-adjacency even
+# without a specific brand name. Conservative list -- single common nouns
+# like "wizard" are NOT included to avoid pathological false positives.
+_FICTIONAL_UNIVERSE_TERMS: tuple[str, ...] = (
+    "Hogwarts",
+    "Jedi",
+    "Sith",
+    "Death Star",
+    "Hobbit",
+    "Vulcan",
+    "Klingon",
+    "Mandalorian",
+    "Force-sensitive",
+    "Muggle",
+    "Quidditch",
+    "Tatooine",
+)
+
+_CATEGORIES: dict[str, tuple[str, ...]] = {
+    "branded-game-or-universe": _BRANDED_GAMES_AND_UNIVERSES,
+    "branded-character": _BRANDED_CHARACTERS,
+    "sports-league": _SPORTS_LEAGUES,
+    "branded-product": _BRANDED_PRODUCTS,
+    "music-or-film": _MUSIC_AND_FILM,
+    "fictional-universe-term": _FICTIONAL_UNIVERSE_TERMS,
+}
+
+
+@dataclass(frozen=True)
+class IPHit:
+    """A single IP-term detection hit."""
+
+    term: str
+    category: str
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        return f"{self.term} ({self.category})"
+
+
+# Pre-compile a regex per category for fast scanning. Each term is escaped
+# and wrapped in word boundaries so substring matches inside a longer word
+# do not trigger ("magicwand" should NOT match "Magic").
+def _compile_category(terms: Iterable[str]) -> re.Pattern[str]:
+    # Use a non-word-char lookaround that also tolerates leading/trailing
+    # punctuation common in titles (e.g. "Magic: The Gathering" appearing
+    # mid-sentence). Word boundaries (\b) work for ASCII; we accept the
+    # ASCII-only behavior for the heuristic.
+    escaped = [re.escape(term) for term in terms]
+    pattern = r"(?i)(?<!\w)(?:" + "|".join(escaped) + r")(?!\w)"
+    return re.compile(pattern)
+
+
+_CATEGORY_PATTERNS: dict[str, re.Pattern[str]] = {
+    category: _compile_category(terms) for category, terms in _CATEGORIES.items()
+}
+
+
+def detect_ip_terms(text: str) -> list[IPHit]:
+    """Scan *text* for known IP terms; return a deduplicated list of hits.
+
+    The scan is permissive (case-insensitive, word-boundary based) and
+    intentionally err on the side of false positives. An empty list means
+    "no known IP terms detected" -- it does NOT mean "this project is
+    free of IP risk", since the heuristic only knows about the curated
+    term lists above.
+
+    Hits are deduplicated by ``(term, category)`` pair preserving first
+    appearance order. The original surface form from *text* is preserved
+    (e.g. ``"magic the gathering"`` keeps its lowercase form even though
+    the canonical term is ``"Magic the Gathering"``).
+    """
+    if not text:
+        return []
+    seen: set[tuple[str, str]] = set()
+    hits: list[IPHit] = []
+    for category, pattern in _CATEGORY_PATTERNS.items():
+        for match in pattern.finditer(text):
+            term = match.group(0)
+            key = (term.lower(), category)
+            if key in seen:
+                continue
+            seen.add(key)
+            hits.append(IPHit(term=term, category=category))
+    return hits
+
+
+def is_ip_adjacent(text: str) -> bool:
+    """Return True iff *text* contains at least one detected IP term."""
+    return bool(detect_ip_terms(text))
+
+
+# ---------------------------------------------------------------------------
+# Monetization-intent branching + scope-item generation (#738)
+# ---------------------------------------------------------------------------
+
+_VALID_INTENTS: frozenset[str] = frozenset({"personal", "commercial", "unknown"})
+
+
+def _validate_intent(intent: str) -> str:
+    """Normalise and validate a monetization-intent value.
+
+    Accepts ``"personal"``, ``"commercial"``, or ``"unknown"`` (case-
+    insensitive). Anything else raises ``ValueError`` -- the interview
+    flow MUST capture an explicit answer when IP is detected, so an
+    unrecognised intent here indicates a programming error in the caller.
+    """
+    if not isinstance(intent, str):
+        raise ValueError(f"monetization_intent must be a string, got {type(intent)!r}")
+    normalized = intent.strip().lower()
+    if normalized not in _VALID_INTENTS:
+        raise ValueError(
+            f"monetization_intent {intent!r} not in {sorted(_VALID_INTENTS)}"
+        )
+    return normalized
+
+
+def ip_risk_scope_items(monetization_intent: str) -> list[dict[str, str]]:
+    """Return the canonical IP-risk protection scope items for SPECIFICATION
+    injection.
+
+    The minimum-protection checklist (see ``references/ip-risk.md``) lands
+    three scope items in the spec:
+
+    - **Disclaimer stub** -- a "not affiliated with / not endorsed by"
+      front-of-app notice the implementation phase fills in once the
+      specific IP holder is named.
+    - **API-only-asset-access policy** -- never bundle assets (images,
+      audio, video, text) from the third-party IP; access only via
+      official APIs that grant a license to use them, and gate that
+      access behind the user's own credentials.
+    - **Hosting policy** -- self-hosted private use only, OR commercial
+      hosting only after legal review confirms the licensing terms allow
+      it.
+
+    All three items are emitted regardless of monetization intent because
+    even personal IP-adjacent projects can leak into commercial use over
+    time. The ``Acceptance`` narrative on each item is tightened to the
+    commercial-level checklist (lawyer-confirmed terms, written license,
+    etc.) for **any intent other than ``"personal"``** -- the
+    wrong-side-of-safe policy means that ``"unknown"`` (interview hasn't
+    captured an explicit answer yet) inherits the stricter commercial
+    checklist. Only the explicit ``"personal"`` answer relaxes the
+    acceptance language.
+
+    The returned items are plain dicts compatible with
+    ``vBRIEF v0.6 PlanItem`` shape (``title``, ``status``, ``narrative``).
+    Callers append them to ``plan.items`` on the
+    ``specification.vbrief.json`` draft so they flow naturally into the
+    rendered SPECIFICATION.md via the existing ``scripts/spec_render.py``
+    pipeline -- no spec_render.py modification is required.
+    """
+    intent = _validate_intent(monetization_intent)
+    # Wrong-side-of-safe policy (Greptile P1 #775): treat anything other than
+    # the explicit `personal` answer as commercial-level. `unknown` (the
+    # interview is still asking the question) MUST inherit the stricter
+    # checklist so the spec carries lawyer-confirmed acceptance criteria
+    # by default. The interview MUST still resolve `unknown` -> `personal` /
+    # `commercial` before the confirmation gate; this is just the safe
+    # fallback for the scope-item shape if the call lands first.
+    commercial = intent != "personal"
+
+    base_acceptance = (
+        "Lawyer-confirmed wording before public release"
+        if commercial
+        else "Reviewed by the project owner before any public release"
+    )
+    asset_acceptance = (
+        "All third-party assets reach the app via official APIs only with a "
+        "license that explicitly permits the planned use; no assets bundled "
+        "in the repository or build artifacts; lawyer-confirmed before public "
+        "release"
+        if commercial
+        else "All third-party assets reach the app via official APIs only; "
+        "no assets bundled in the repository or build artifacts"
+    )
+    hosting_acceptance = (
+        "Hosting plan reviewed by counsel; written license terms cover the "
+        "deployment region and audience; revenue model documented"
+        if commercial
+        else "Self-hosted private use only; do not deploy publicly until a "
+        "monetization decision is made and re-reviewed against this rule"
+    )
+
+    return [
+        {
+            "title": "IP-risk: disclaimer stub on the app's front surface",
+            "status": "pending",
+            "narrative": {
+                "Description": (
+                    "Add a 'not affiliated with / not endorsed by' notice on "
+                    "the app's first user-visible surface (splash screen, "
+                    "landing page, or CLI banner)."
+                ),
+                "Acceptance": base_acceptance,
+                "Traces": "IP-1",
+            },
+        },
+        {
+            "title": "IP-risk: API-only third-party asset access policy",
+            "status": "pending",
+            "narrative": {
+                "Description": (
+                    "Never bundle third-party IP assets (images, audio, "
+                    "video, text, card data, character likenesses) in the "
+                    "repository or build artifacts. Access only via official "
+                    "APIs that grant a license."
+                ),
+                "Acceptance": asset_acceptance,
+                "Traces": "IP-2",
+            },
+        },
+        {
+            "title": "IP-risk: hosting policy gated on monetization intent",
+            "status": "pending",
+            "narrative": {
+                "Description": (
+                    "Document the hosting plan and gate it on the captured "
+                    "monetization intent. Self-hosted private use is the "
+                    "default; commercial hosting requires lawyer review."
+                ),
+                "Acceptance": hosting_acceptance,
+                "Traces": "IP-3",
+            },
+        },
+    ]
+
+
+def plain_risk_summary(
+    hits: list[IPHit],
+    monetization_intent: str,
+) -> str:
+    """Build a plain-English risk summary suitable for interview output.
+
+    The summary is intentionally non-alarming and non-legal-advice: it
+    states what was detected, what the implication is at a high level,
+    and (for commercial intent) it carries a non-optional recommendation
+    to consult a lawyer. The summary is meant to be copied verbatim into
+    the interview output and into the ``IPRisk`` narrative on the
+    specification vBRIEF.
+
+    Returns an empty string when *hits* is empty (no IP detected); the
+    caller MUST NOT inject the summary in that case.
+
+    .. warning::
+
+        ``monetization_intent="unknown"`` produces a **transitional**
+        re-ask prompt -- a status message saying "the interview MUST
+        capture an explicit answer". It is NOT a terminal output and
+        does NOT carry the lawyer recommendation that
+        :func:`ip_risk_scope_items` injects under the wrong-side-of-safe
+        policy. Callers MUST loop back to the monetization-intent
+        question and re-call this function with ``personal`` or
+        ``commercial`` before treating the summary as final output --
+        otherwise the interview surface (no lawyer rec) and the
+        injected spec items (commercial-level acceptance language)
+        will mismatch (#775 P2).
+    """
+    if not hits:
+        return ""
+    intent = _validate_intent(monetization_intent)
+
+    grouped: dict[str, list[str]] = {}
+    for hit in hits:
+        grouped.setdefault(hit.category, []).append(hit.term)
+
+    bullets: list[str] = []
+    for category, terms in grouped.items():
+        unique_terms = sorted(set(terms), key=str.lower)
+        bullets.append(f"- {category}: {', '.join(unique_terms)}")
+
+    header = (
+        "Heads up: your project description references third-party "
+        "intellectual property (IP). This is a plain-English summary -- "
+        "not legal advice."
+    )
+    detection_block = "Detected IP-adjacent terms:\n" + "\n".join(bullets)
+
+    if intent == "commercial":
+        intent_block = (
+            "You said you intend to use this commercially (sell access, "
+            "earn revenue, distribute to paying users, or run ads). "
+            "Commercial use of someone else's IP without a written license "
+            "is the high-risk case. You MUST consult a lawyer before "
+            "shipping to paying users -- this is not optional output from "
+            "this interview."
+        )
+    elif intent == "personal":
+        intent_block = (
+            "You said this is a personal project (no monetization, private "
+            "use, learning). Personal use is lower risk but not zero risk: "
+            "if your project ever goes public, becomes monetized, or is "
+            "shared widely, the risk profile changes and a lawyer review "
+            "becomes worthwhile."
+        )
+    else:  # unknown
+        intent_block = (
+            "You did not choose between personal and commercial use. The "
+            "interview MUST capture an explicit answer before generating "
+            "the SPECIFICATION -- the legal-risk profile depends on the "
+            "answer."
+        )
+
+    next_steps = (
+        "Suggested next steps: (1) confirm whether your use is personal "
+        "or commercial; (2) keep the disclaimer / API-only-asset / "
+        "hosting scope items the SPECIFICATION will include; "
+        "(3) for commercial intent, consult a lawyer before public "
+        "release."
+    )
+
+    return "\n\n".join([header, detection_block, intent_block, next_steps])
+
+
+# ---------------------------------------------------------------------------
+# CLI entry point (for ad-hoc use; the canonical caller is the interview
+# skill which invokes the helpers directly).
+# ---------------------------------------------------------------------------
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = sys.argv[1:] if argv is None else argv
+    if not args:
+        print(
+            "Usage: ip_risk.py <text-to-scan> [--intent personal|commercial|unknown]",
+            file=sys.stderr,
+        )
+        return 2
+
+    intent = "unknown"
+    text_parts: list[str] = []
+    i = 0
+    while i < len(args):
+        arg = args[i]
+        if arg == "--intent" and i + 1 < len(args):
+            intent = args[i + 1]
+            i += 2
+            continue
+        text_parts.append(arg)
+        i += 1
+    text = " ".join(text_parts)
+    if not text:
+        print("Usage: ip_risk.py <text-to-scan>", file=sys.stderr)
+        return 2
+
+    hits = detect_ip_terms(text)
+    if not hits:
+        print("No IP terms detected.")
+        return 0
+
+    print("Detected IP terms:")
+    for hit in hits:
+        print(f"  - {hit}")
+    try:
+        summary = plain_risk_summary(hits, intent)
+    except ValueError as exc:
+        print(f"Invalid --intent value: {exc}", file=sys.stderr)
+        return 2
+    print()
+    print(summary)
+    return 1
+
+
+if __name__ == "__main__":  # pragma: no cover - CLI entry
+    sys.exit(main())