icdev 0.0.3__py3-none-any.whl

tools/writing/style_guide_manager.py

@@ -0,0 +1,438 @@
+"""WriteGuard Style Guide Manager — 5-layer cascade with ISSO locks (D-WG-3).
+
+Manages style guides at Platform→Tenant→Program→Project→User levels.
+Each layer can override or merge parent rules. ISSO-lockable dimensions
+prevent lower layers from changing critical rules (e.g., CUI marking).
+
+Pattern: dev_profile_manager.py (D183-D188).
+"""
+
+import json
+import sqlite3
+import uuid
+from datetime import UTC, datetime
+from pathlib import Path
+
+import yaml
+
+
+DB_PATH = Path(__file__).resolve().parent.parent.parent / "data" / "icdev.db"
+STYLE_GUIDES_DIR = Path(__file__).resolve().parent.parent.parent / "context" / "writing" / "style_guides"
+CASCADE_ORDER = ("platform", "tenant", "program", "project", "user")
+
+
+def _get_db(db_path=None):
+    """Get database connection."""
+    path = db_path or DB_PATH
+    return sqlite3.connect(str(path))
+
+
+def _now():
+    """Current timestamp."""
+    return datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def create_guide(scope, scope_id, guide_name, guide_yaml, created_by,
+                 inherits_from=None, classification="CUI", db_path=None):
+    """Create a new style guide.
+
+    Args:
+        scope: One of 'platform', 'tenant', 'program', 'project', 'user'.
+        scope_id: Identifier for the scope (e.g., tenant ID).
+        guide_name: Human-readable name.
+        guide_yaml: YAML string of style guide rules.
+        created_by: User/system creating the guide.
+        inherits_from: Parent guide ID to inherit from.
+        classification: Data classification marking.
+        db_path: Optional database path override.
+
+    Returns:
+        dict with guide details.
+    """
+    if scope not in CASCADE_ORDER:
+        return {"error": f"Invalid scope: {scope}. Must be one of {CASCADE_ORDER}"}
+
+    guide_id = f"wg-sg-{uuid.uuid4().hex[:12]}"
+    conn = _get_db(db_path)
+    try:
+        conn.execute(
+            """INSERT INTO wg_style_guides
+               (id, scope, scope_id, version, guide_name, guide_yaml,
+                inherits_from, created_by, created_at, is_active, classification)
+               VALUES (?, ?, ?, 1, ?, ?, ?, ?, ?, 1, ?)""",
+            (guide_id, scope, scope_id, guide_name, guide_yaml,
+             inherits_from, created_by, _now(), classification),
+        )
+        conn.commit()
+        return {"id": guide_id, "scope": scope, "scope_id": scope_id,
+                "version": 1, "guide_name": guide_name, "status": "created"}
+    except Exception as e:
+        return {"error": str(e)}
+    finally:
+        conn.close()
+
+
+def get_guide(guide_id, version=None, db_path=None):
+    """Get a style guide by ID, optionally at a specific version.
+
+    Returns:
+        dict with full guide data, or error.
+    """
+    conn = _get_db(db_path)
+    try:
+        if version:
+            row = conn.execute(
+                "SELECT * FROM wg_style_guides WHERE id=? AND version=?",
+                (guide_id, version),
+            ).fetchone()
+        else:
+            row = conn.execute(
+                "SELECT * FROM wg_style_guides WHERE id=? AND is_active=1 ORDER BY version DESC LIMIT 1",
+                (guide_id,),
+            ).fetchone()
+
+        if not row:
+            return {"error": f"Guide not found: {guide_id}"}
+
+        cols = [d[0] for d in conn.execute("SELECT * FROM wg_style_guides LIMIT 0").description]
+        return dict(zip(cols, row))
+    finally:
+        conn.close()
+
+
+def list_guides(scope=None, scope_id=None, db_path=None):
+    """List style guides, optionally filtered by scope.
+
+    Returns:
+        list of guide summary dicts.
+    """
+    conn = _get_db(db_path)
+    try:
+        query = "SELECT id, scope, scope_id, version, guide_name, is_active, created_at FROM wg_style_guides"
+        params = []
+
+        conditions = []
+        if scope:
+            conditions.append("scope=?")
+            params.append(scope)
+        if scope_id:
+            conditions.append("scope_id=?")
+            params.append(scope_id)
+
+        if conditions:
+            query += " WHERE " + " AND ".join(conditions)
+
+        query += " ORDER BY created_at DESC"
+
+        rows = conn.execute(query, params).fetchall()
+        cols = ["id", "scope", "scope_id", "version", "guide_name", "is_active", "created_at"]
+        return [dict(zip(cols, row)) for row in rows]
+    finally:
+        conn.close()
+
+
+def update_guide(guide_id, guide_yaml, updated_by, change_summary="", db_path=None):
+    """Update a style guide by creating a new version (D183 — version immutability).
+
+    The old version is deactivated; a new row is inserted with incremented version.
+
+    Returns:
+        dict with new version info.
+    """
+    conn = _get_db(db_path)
+    try:
+        # Get current active version
+        current = conn.execute(
+            "SELECT * FROM wg_style_guides WHERE id=? AND is_active=1 ORDER BY version DESC LIMIT 1",
+            (guide_id,),
+        ).fetchone()
+
+        if not current:
+            return {"error": f"Guide not found: {guide_id}"}
+
+        cols = [d[0] for d in conn.execute("SELECT * FROM wg_style_guides LIMIT 0").description]
+        current_dict = dict(zip(cols, current))
+        new_version = current_dict["version"] + 1
+
+        # Deactivate current version
+        conn.execute(
+            "UPDATE wg_style_guides SET is_active=0 WHERE id=? AND version=?",
+            (guide_id, current_dict["version"]),
+        )
+
+        # Insert new version
+        conn.execute(
+            """INSERT INTO wg_style_guides
+               (id, scope, scope_id, version, guide_name, guide_yaml,
+                inherits_from, created_by, created_at, is_active, change_summary, classification)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 1, ?, ?)""",
+            (guide_id, current_dict["scope"], current_dict["scope_id"],
+             new_version, current_dict["guide_name"], guide_yaml,
+             current_dict["inherits_from"], updated_by, _now(),
+             change_summary, current_dict.get("classification", "CUI")),
+        )
+        conn.commit()
+        return {"id": guide_id, "version": new_version, "status": "updated"}
+    except Exception as e:
+        return {"error": str(e)}
+    finally:
+        conn.close()
+
+
+def resolve_cascade(scope_id, scope="project", db_path=None):
+    """Resolve the effective style guide by merging the 5-layer cascade.
+
+    Resolution order: platform → tenant → program → project → user.
+    Each layer overrides parent values unless dimension is locked.
+
+    Args:
+        scope_id: The target scope identifier.
+        scope: The target scope level.
+        db_path: Optional database path.
+
+    Returns:
+        dict with resolved guide YAML and metadata.
+    """
+    conn = _get_db(db_path)
+    try:
+        # Collect guides from all levels up to the target scope
+        target_idx = CASCADE_ORDER.index(scope) if scope in CASCADE_ORDER else 4
+        resolved = {}
+        applied_layers = []
+
+        for level in CASCADE_ORDER[: target_idx + 1]:
+            guide_row = conn.execute(
+                """SELECT id, guide_yaml, version FROM wg_style_guides
+                   WHERE scope=? AND is_active=1
+                   ORDER BY version DESC LIMIT 1""",
+                (level,),
+            ).fetchone()
+
+            if not guide_row:
+                # Try loading from default YAML files for platform scope
+                if level == "platform":
+                    default = _load_default_guide("government")
+                    if default:
+                        resolved = _deep_merge(resolved, default)
+                        applied_layers.append({"scope": level, "source": "default_file"})
+                continue
+
+            guide_id, yaml_str, version = guide_row
+
+            try:
+                guide_data = yaml.safe_load(yaml_str) or {}
+            except yaml.YAMLError:
+                guide_data = {}
+
+            # Check locks — locked dimensions cannot be overridden by lower layers
+            locks = _get_active_locks(guide_id, conn)
+            locked_paths = {lock["dimension_path"] for lock in locks}
+
+            # Merge, skipping locked paths from parent layers
+            if locked_paths and applied_layers:
+                guide_data = _filter_locked_paths(guide_data, locked_paths)
+
+            resolved = _deep_merge(resolved, guide_data)
+            applied_layers.append({
+                "scope": level,
+                "guide_id": guide_id,
+                "version": version,
+                "locked_paths": list(locked_paths),
+            })
+
+        return {
+            "resolved_guide": resolved,
+            "applied_layers": applied_layers,
+            "target_scope": scope,
+            "target_scope_id": scope_id,
+        }
+    finally:
+        conn.close()
+
+
+def lock_dimension(guide_id, dimension_path, lock_role, locked_by, reason="", db_path=None):
+    """Lock a style guide dimension so lower-scope guides cannot override it.
+
+    Args:
+        guide_id: The guide to lock a dimension on.
+        dimension_path: Dot-separated path (e.g., 'cui.marking_required').
+        lock_role: Role performing the lock ('isso', 'architect', 'pm', 'admin').
+        locked_by: User performing the lock.
+        reason: Justification for the lock.
+
+    Returns:
+        dict with lock details.
+    """
+    valid_roles = ("isso", "architect", "pm", "admin")
+    if lock_role not in valid_roles:
+        return {"error": f"Invalid lock role: {lock_role}. Must be one of {valid_roles}"}
+
+    lock_id = f"wg-lk-{uuid.uuid4().hex[:12]}"
+    conn = _get_db(db_path)
+    try:
+        conn.execute(
+            """INSERT INTO wg_style_guide_locks
+               (id, guide_id, dimension_path, lock_owner_role, locked_by, locked_at, reason, is_active)
+               VALUES (?, ?, ?, ?, ?, ?, ?, 1)""",
+            (lock_id, guide_id, dimension_path, lock_role, locked_by, _now(), reason),
+        )
+        conn.commit()
+        return {"lock_id": lock_id, "guide_id": guide_id,
+                "dimension_path": dimension_path, "status": "locked"}
+    except Exception as e:
+        return {"error": str(e)}
+    finally:
+        conn.close()
+
+
+def unlock_dimension(guide_id, dimension_path, unlocked_by, role, db_path=None):
+    """Unlock a style guide dimension.
+
+    Only the same role level or higher can unlock.
+
+    Returns:
+        dict with unlock status.
+    """
+    conn = _get_db(db_path)
+    try:
+        lock = conn.execute(
+            """SELECT id, lock_owner_role FROM wg_style_guide_locks
+               WHERE guide_id=? AND dimension_path=? AND is_active=1""",
+            (guide_id, dimension_path),
+        ).fetchone()
+
+        if not lock:
+            return {"error": f"No active lock on {dimension_path} for guide {guide_id}"}
+
+        lock_id, lock_role = lock
+        role_order = {"admin": 4, "isso": 3, "architect": 2, "pm": 1}
+        if role_order.get(role, 0) < role_order.get(lock_role, 0):
+            return {"error": f"Insufficient role. Lock held by {lock_role}, your role: {role}"}
+
+        conn.execute(
+            "UPDATE wg_style_guide_locks SET is_active=0 WHERE id=?",
+            (lock_id,),
+        )
+        conn.commit()
+        return {"lock_id": lock_id, "dimension_path": dimension_path,
+                "status": "unlocked", "unlocked_by": unlocked_by}
+    except Exception as e:
+        return {"error": str(e)}
+    finally:
+        conn.close()
+
+
+def history(guide_id, db_path=None):
+    """Get version history of a style guide.
+
+    Returns:
+        list of version summaries.
+    """
+    conn = _get_db(db_path)
+    try:
+        rows = conn.execute(
+            """SELECT version, is_active, created_by, created_at, change_summary
+               FROM wg_style_guides WHERE id=? ORDER BY version DESC""",
+            (guide_id,),
+        ).fetchall()
+
+        cols = ["version", "is_active", "created_by", "created_at", "change_summary"]
+        return [dict(zip(cols, row)) for row in rows]
+    finally:
+        conn.close()
+
+
+def diff_versions(guide_id, v1, v2, db_path=None):
+    """Compare two versions of a style guide.
+
+    Returns:
+        dict with added, removed, and changed keys.
+    """
+    g1 = get_guide(guide_id, version=v1, db_path=db_path)
+    g2 = get_guide(guide_id, version=v2, db_path=db_path)
+
+    if "error" in g1 or "error" in g2:
+        return {"error": g1.get("error") or g2.get("error")}
+
+    try:
+        d1 = yaml.safe_load(g1.get("guide_yaml", "{}")) or {}
+        d2 = yaml.safe_load(g2.get("guide_yaml", "{}")) or {}
+    except yaml.YAMLError:
+        return {"error": "Failed to parse guide YAML"}
+
+    added = {k: v for k, v in d2.items() if k not in d1}
+    removed = {k: v for k, v in d1.items() if k not in d2}
+    changed = {k: {"old": d1[k], "new": d2[k]} for k in d1 if k in d2 and d1[k] != d2[k]}
+
+    return {"v1": v1, "v2": v2, "added": added, "removed": removed, "changed": changed}
+
+
+def load_default_guides():
+    """Load all default style guides from context/writing/style_guides/.
+
+    Returns:
+        dict mapping guide name to parsed YAML content.
+    """
+    guides = {}
+    if not STYLE_GUIDES_DIR.exists():
+        return guides
+
+    for f in STYLE_GUIDES_DIR.glob("*.yaml"):
+        try:
+            with open(f, "r", encoding="utf-8") as fh:
+                guides[f.stem] = yaml.safe_load(fh) or {}
+        except (yaml.YAMLError, IOError):
+            continue
+
+    return guides
+
+
+def _load_default_guide(name):
+    """Load a single default guide by name."""
+    path = STYLE_GUIDES_DIR / f"{name}.yaml"
+    if not path.exists():
+        return {}
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            return yaml.safe_load(f) or {}
+    except (yaml.YAMLError, IOError):
+        return {}
+
+
+def _get_active_locks(guide_id, conn):
+    """Get active locks for a guide."""
+    rows = conn.execute(
+        "SELECT dimension_path, lock_owner_role, locked_by FROM wg_style_guide_locks WHERE guide_id=? AND is_active=1",
+        (guide_id,),
+    ).fetchall()
+    return [{"dimension_path": r[0], "lock_owner_role": r[1], "locked_by": r[2]} for r in rows]
+
+
+def _deep_merge(base, override):
+    """Deep merge two dicts. Override wins on conflicts."""
+    result = dict(base)
+    for k, v in override.items():
+        if k in result and isinstance(result[k], dict) and isinstance(v, dict):
+            result[k] = _deep_merge(result[k], v)
+        else:
+            result[k] = v
+    return result
+
+
+def _filter_locked_paths(data, locked_paths):
+    """Remove locked dimension paths from data so they can't override."""
+    filtered = dict(data)
+    for path in locked_paths:
+        parts = path.split(".")
+        _remove_path(filtered, parts)
+    return filtered
+
+
+def _remove_path(data, parts):
+    """Remove a nested key path from dict."""
+    if not parts or not isinstance(data, dict):
+        return
+    if len(parts) == 1:
+        data.pop(parts[0], None)
+    elif parts[0] in data and isinstance(data[parts[0]], dict):
+        _remove_path(data[parts[0]], parts[1:])

tools/writing/tone_profiler.py

@@ -0,0 +1,168 @@
+"""WriteGuard Tone Profiler — Keyword + LLM classification (D-WG-12, scanner tier).
+
+Deterministic keyword scoring first, then optional qwen3 scanner for nuanced
+classification. No Claude review needed — scanner functions only.
+"""
+
+import re
+
+
+# Tone keyword dictionaries (deterministic layer)
+_TONE_KEYWORDS = {
+    "formal": [
+        "therefore", "furthermore", "moreover", "consequently", "accordingly",
+        "pursuant", "whereas", "hereby", "notwithstanding", "aforementioned",
+        "hereunder", "therein", "shall", "henceforth", "pursuant to",
+    ],
+    "technical": [
+        "architecture", "implementation", "framework", "infrastructure", "deployment",
+        "configuration", "integration", "API", "protocol", "algorithm",
+        "encryption", "authentication", "latency", "throughput", "scalability",
+        "microservice", "containerized", "pipeline", "orchestration", "endpoint",
+    ],
+    "persuasive": [
+        "proven", "demonstrated", "innovative", "unique", "advantage",
+        "best-in-class", "exceptional", "outstanding", "superior", "significant",
+        "transformative", "cutting-edge", "industry-leading", "unmatched",
+        "track record", "capability", "expertise", "commitment", "dedicated",
+    ],
+    "authoritative": [
+        "mandates", "requires", "compliance", "regulation", "authority",
+        "directive", "policy", "standard", "certification", "accreditation",
+        "authorization", "enforcement", "oversight", "governance", "control",
+    ],
+    "plain_language": [
+        "use", "help", "start", "stop", "send", "need", "get", "put",
+        "make", "do", "show", "tell", "find", "give", "take", "keep",
+    ],
+    "academic": [
+        "research", "hypothesis", "methodology", "empirical", "theoretical",
+        "analysis", "synthesis", "literature", "findings", "evidence",
+        "correlation", "statistical", "peer-reviewed", "systematic",
+    ],
+}
+
+# Sentiment indicators
+_POSITIVE_WORDS = {
+    "excellent", "outstanding", "effective", "successful", "proven",
+    "innovative", "robust", "comprehensive", "reliable", "efficient",
+    "secure", "compliant", "certified", "validated", "verified",
+}
+
+_NEGATIVE_WORDS = {
+    "failure", "risk", "vulnerability", "weakness", "deficiency",
+    "inadequate", "insufficient", "non-compliant", "outdated", "deprecated",
+    "breach", "violation", "gap", "threat", "exposure",
+}
+
+
+def profile_tone(text, use_llm=False):
+    """Analyze text tone profile.
+
+    First pass: deterministic keyword scoring.
+    Second pass (optional): qwen3 scanner for nuanced classification.
+
+    Args:
+        text: Input text to analyze.
+        use_llm: Whether to use LLM for enhanced profiling.
+
+    Returns:
+        dict with 'profile' (tone scores), 'dominant_tone', 'sentiment'.
+    """
+    if not text or not text.strip():
+        return {"profile": {}, "dominant_tone": "unknown", "sentiment": "neutral", "findings": []}
+
+    words = text.lower().split()
+    word_count = len(words)
+
+    if word_count == 0:
+        return {"profile": {}, "dominant_tone": "unknown", "sentiment": "neutral", "findings": []}
+
+    # Deterministic keyword scoring
+    profile = {}
+    for tone, keywords in _TONE_KEYWORDS.items():
+        matches = 0
+        for kw in keywords:
+            if " " in kw:
+                # Multi-word keyword
+                matches += text.lower().count(kw)
+            else:
+                matches += sum(1 for w in words if w.strip(".,;:!?\"'()") == kw)
+
+        # Normalize by text length (per 100 words)
+        score = (matches / word_count) * 100 if word_count > 0 else 0
+        profile[tone] = round(min(1.0, score / 5.0), 2)  # Cap at 1.0
+
+    # Determine dominant tone
+    dominant = max(profile, key=profile.get) if profile else "unknown"
+
+    # Sentiment analysis (simple word counting)
+    pos_count = sum(1 for w in words if w.strip(".,;:!?\"'()") in _POSITIVE_WORDS)
+    neg_count = sum(1 for w in words if w.strip(".,;:!?\"'()") in _NEGATIVE_WORDS)
+
+    if pos_count > neg_count * 2:
+        sentiment = "positive"
+    elif neg_count > pos_count * 2:
+        sentiment = "negative"
+    elif pos_count > neg_count:
+        sentiment = "slightly_positive"
+    elif neg_count > pos_count:
+        sentiment = "slightly_negative"
+    else:
+        sentiment = "neutral"
+
+    findings = []
+
+    # Generate findings based on tone issues
+    if profile.get("formal", 0) > 0.7 and profile.get("plain_language", 0) < 0.1:
+        findings.append({
+            "category": "tone",
+            "severity": "info",
+            "message": "Text is heavily formal. Consider adding plain language for broader accessibility.",
+            "rule_id": "TONE-001",
+        })
+
+    if profile.get("persuasive", 0) > 0.5 and profile.get("technical", 0) < 0.2:
+        findings.append({
+            "category": "tone",
+            "severity": "info",
+            "message": "Text is persuasive but lacks technical substance. Balance claims with evidence.",
+            "rule_id": "TONE-002",
+        })
+
+    # Optional LLM enhancement (scanner tier — qwen3 only)
+    if use_llm:
+        try:
+            from tools.llm.router import LLMRouter
+            router = LLMRouter()
+            prompt = (
+                f"Classify the tone of this text into these categories with scores 0-1: "
+                f"formal, technical, persuasive, authoritative, plain_language, academic. "
+                f"Also identify the dominant tone and sentiment (positive/negative/neutral). "
+                f"Return JSON only.\n\nText:\n{text[:2000]}"
+            )
+            llm_result = router.invoke(
+                function_name="wg_tone_profile",
+                prompt=prompt,
+            )
+            if llm_result and isinstance(llm_result, dict):
+                # Merge LLM insights with deterministic scores
+                llm_profile = llm_result.get("profile", {})
+                for tone, score in llm_profile.items():
+                    if tone in profile:
+                        # Average deterministic and LLM scores
+                        profile[tone] = round((profile[tone] + score) / 2, 2)
+        except (ImportError, Exception):
+            pass  # LLM unavailable, use deterministic only
+
+    return {
+        "profile": profile,
+        "dominant_tone": dominant,
+        "sentiment": sentiment,
+        "findings": findings,
+        "stats": {
+            "positive_words": pos_count,
+            "negative_words": neg_count,
+            "word_count": word_count,
+        },
+    }