core-runtime 0.1.1__py3-none-any.whl

cli/logic/utils_migration.py

@@ -0,0 +1,43 @@
+# src/cli/logic/utils_migration.py
+"""
+Shared utilities for constitutional migration and domain rationalization.
+This is the canonical location for logic used by migration-related tools.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from ruamel.yaml import YAML
+
+
+yaml_handler = YAML()
+yaml_handler.preserve_quotes = True
+yaml_handler.indent(mapping=2, sequence=4, offset=2)
+
+
+# ID: 64bb309f-1cf9-4480-afc4-78130e8357e2
+def parse_migration_plan(plan_path: Path) -> dict[str, str]:
+    """Parses the markdown migration plan into a mapping dictionary."""
+    if not plan_path.exists():
+        raise FileNotFoundError(f"Migration plan not found at: {plan_path}")
+    content = plan_path.read_text(encoding="utf-8")
+    pattern = re.compile(r"\|\s*`([^`]+)`\s*\|\s*`([^`]+)`\s*\|")
+    matches = pattern.findall(content)
+    if not matches:
+        raise ValueError("No valid domain mappings found in the migration plan.")
+    return {old.strip(): new.strip() for old, new in matches}
+
+
+# ID: 80131c72-c024-4823-8226-f63c5d8c4704
+def replacer(match: re.Match, domain_map: dict, py_file: Path, repo_root: Path) -> str:
+    """Replacement function for re.subn to update capability tags."""
+    old_cap = match.group(1)
+    for old_domain, new_domain in domain_map.items():
+        if old_cap.startswith(old_domain):
+            new_cap = old_cap.replace(old_domain, new_domain, 1)
+            if old_cap != new_cap:
+                # FUTURE: Add logging if needed
+                pass
+    return match.group(0)

cli/logic/validate.py

@@ -0,0 +1,107 @@
+# src/cli/logic/validate.py
+"""
+CLI commands for validating constitutional and governance integrity.
+
+CONSTITUTIONAL ALIGNMENT:
+- Single Responsibility: CLI presentation and user interaction
+- Delegates validation logic to services
+- Thin adapter layer
+
+Extracted responsibilities:
+- Schema validation → IntentSchemaValidator
+- Expression evaluation → PolicyExpressionEvaluator
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from body.services.intent_schema_validator import IntentSchemaValidator
+from body.services.policy_expression_evaluator import (
+    PolicyExpressionEvaluator,
+    ReviewContext,
+)
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+validate_app = typer.Typer(help="Commands for validating constitutional integrity.")
+
+
+# ---------------------------------------------------------------------------
+# CLI command: validate .intent against JSON Schemas
+# ---------------------------------------------------------------------------
+
+
+@validate_app.command("intent-schema")
+# ID: 3c97e5c8-ad67-4865-b636-0860ab74775b
+def validate_intent_schema(
+    intent_path: Path = typer.Option(
+        Path(".intent"),
+        "--intent-path",
+        help="Path to the .intent directory (Mind root).",
+    ),
+) -> None:
+    """
+    Validate .intent YAML documents that declare `$schema` against their JSON Schemas.
+
+    Current behaviour (A2 migration-friendly):
+    - Walks `.intent/**` (excluding runtime/state folders).
+    - For each YAML/YML file:
+        * If it has a `$schema` field → validate against that JSON Schema.
+        * If it has no `$schema` field → report as [SKIP], but do NOT fail.
+
+    This allows gradual rollout of schema governance across the Mind.
+    """
+    logger.info("Running .intent JSON-schema validation via core-admin.")
+
+    # Use service for validation logic
+    validator = IntentSchemaValidator(intent_path.resolve())
+    results, skipped = validator.validate_all()
+
+    # CLI presentation logic
+    if not results:
+        typer.echo("No .intent YAML files with $schema found. Nothing to validate.")
+        if skipped:
+            _print_skipped(skipped)
+        return
+
+    # Print results
+    errors = []
+    for result in results:
+        if result.is_valid:
+            typer.echo(f"[OK] {result.yaml_path} ✓")
+        else:
+            errors.append(f"[FAIL] {result.yaml_path}: {result.error_message}")
+
+    # Handle failures
+    if errors:
+        typer.echo("\nSchema validation errors:", err=True)
+        typer.echo("\n".join(errors), err=True)
+        raise typer.Exit(code=1)
+
+    typer.echo("\nAll .intent documents with $schema validated successfully.")
+
+    if skipped:
+        _print_skipped(skipped)
+
+
+def _print_skipped(skipped: list[str]) -> None:
+    """Print skipped files message."""
+    typer.echo("\nSkipped files (no $schema yet):")
+    for msg in skipped:
+        typer.echo(f"  {msg}")
+
+
+# ---------------------------------------------------------------------------
+# Re-export for backward compatibility
+# ---------------------------------------------------------------------------
+
+# Export ReviewContext and evaluator for any code that imports from here
+__all__ = [
+    "PolicyExpressionEvaluator",
+    "ReviewContext",
+    "validate_app",
+]

cli/logic/vector_drift.py

@@ -0,0 +1,109 @@
+# src/cli/logic/vector_drift.py
+
+"""Provides functionality for the vector_drift module."""
+
+from __future__ import annotations
+
+import asyncio
+
+from sqlalchemy import text
+
+from shared.context import CoreContext
+from shared.infrastructure.clients.qdrant_client import QdrantService
+from shared.infrastructure.database.session_manager import get_session
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+
+async def _fetch_postgres_vector_ids() -> set[str]:
+    """
+    Authoritative source of vector IDs is the link table:
+      core.symbol_vector_links(symbol_id UUID, vector_id TEXT, ...)
+    """
+    async with get_session() as session:
+        rows = await session.execute(
+            text("SELECT vector_id::text FROM core.symbol_vector_links")
+        )
+        return {r[0] for r in rows}
+
+
+async def _fetch_qdrant_point_ids(qdrant_service: QdrantService) -> set[str]:
+    """
+    Fetch all point IDs from Qdrant without payloads/vectors.
+
+    PHASE 1 FIX: Uses scroll_all_points() service method instead of direct client access.
+    """
+    points = await qdrant_service.scroll_all_points(
+        with_payload=False, with_vectors=False
+    )
+    all_ids = {str(p.id) for p in points}
+    return all_ids
+
+
+# ID: fc322479-d062-486a-b2cc-636cd2eb7a86
+async def inspect_vector_drift(context: CoreContext) -> dict:
+    """
+    Verifies synchronization between PostgreSQL and Qdrant using the
+    context's QdrantService.
+
+    Returns:
+        dict: Contains synchronization results with keys:
+            - postgres_count: Number of vector IDs in PostgreSQL
+            - qdrant_count: Number of point IDs in Qdrant
+            - missing_in_qdrant: List of IDs missing in Qdrant
+            - orphans_in_qdrant: List of orphaned IDs in Qdrant
+            - status: "synchronized" or "drift_detected"
+            - error: Error message if any
+    """
+    logger.info("Verifying synchronization between PostgreSQL and Qdrant...")
+    if context.qdrant_service is None and context.registry:
+        try:
+            context.qdrant_service = await context.registry.get_qdrant_service()
+        except Exception as e:
+            error_msg = f"Failed to initialize QdrantService: {e}"
+            logger.error(error_msg)
+            return {"error": error_msg, "status": "error"}
+    if not context.qdrant_service:
+        error_msg = "QdrantService not available in context."
+        logger.error(error_msg)
+        return {"error": error_msg, "status": "error"}
+    try:
+        postgres_ids, qdrant_ids = await asyncio.gather(
+            _fetch_postgres_vector_ids(),
+            _fetch_qdrant_point_ids(context.qdrant_service),
+        )
+    except Exception as e:
+        error_msg = f"Error connecting to a database: {e}"
+        logger.error(error_msg)
+        return {"error": error_msg, "status": "error"}
+    logger.info("Found %s linked vector IDs in PostgreSQL.", len(postgres_ids))
+    logger.info("Found %s point IDs in Qdrant.", len(qdrant_ids))
+    missing_in_qdrant = sorted(postgres_ids - qdrant_ids)
+    orphans_in_qdrant = sorted(qdrant_ids - postgres_ids)
+    result = {
+        "postgres_count": len(postgres_ids),
+        "qdrant_count": len(qdrant_ids),
+        "missing_in_qdrant": missing_in_qdrant,
+        "orphans_in_qdrant": orphans_in_qdrant,
+        "status": (
+            "synchronized"
+            if not missing_in_qdrant and (not orphans_in_qdrant)
+            else "drift_detected"
+        ),
+    }
+    if not missing_in_qdrant and (not orphans_in_qdrant):
+        logger.info(
+            "Perfect synchronization. PostgreSQL and Qdrant are perfectly aligned."
+        )
+    else:
+        if missing_in_qdrant:
+            logger.warning(
+                "Found %s vector IDs missing in Qdrant", len(missing_in_qdrant)
+            )
+        if orphans_in_qdrant:
+            logger.warning(
+                "Found %s orphaned point IDs in Qdrant", len(orphans_in_qdrant)
+            )
+    return result

cli/logic/yaml_processor.py

@@ -0,0 +1,5 @@
+# src/cli/logic/yaml_processor.py
+
+"""Provides functionality for the yaml_processor module."""
+
+from __future__ import annotations

cli/renderers/audit_detail.py

@@ -0,0 +1,37 @@
+# src/cli/renderers/audit_detail.py
+"""Renderer for detailed audit findings."""
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from shared.models.audit_rendering import SeverityGroup, get_severity_style
+
+
+# ID: 5d19aa95-ce9e-49b4-b7eb-7f32c9bfd431
+def truncate(text: str, max_len: int) -> str:
+    """Truncate text with ellipsis if too long."""
+    return text[:max_len] + "..." if len(text) > max_len else text
+
+
+# ID: eb606556-5524-43c9-82b2-9706ba6c4930
+def render_details(console: Console, groups: list[SeverityGroup]) -> None:
+    """Render detailed tables for each severity group in panels."""
+    for group in groups:
+        count = len(group.findings)
+        if count == 0:
+            continue
+        inner_table = Table(show_header=True, header_style="bold white")
+        inner_table.add_column("ID", style="cyan", width=12, no_wrap=True)
+        inner_table.add_column("Title", style="bold white")
+        inner_table.add_column("Description", min_width=40)
+        inner_table.add_column("Recommendation", min_width=30)
+        for finding in group.findings:
+            desc = truncate(finding.description, 80)
+            rec = truncate(str(getattr(finding, "recommendation", "N/A")), 60)
+            inner_table.add_row(finding.id, finding.title, desc, rec)
+        title = f"{group.severity.name} ({count} findings)"
+        style = get_severity_style(group.severity)
+        panel = Panel(inner_table, title=title, border_style=style, expand=False)
+        console.print(panel)
+        console.print()

cli/renderers/audit_overview.py

@@ -0,0 +1,39 @@
+# src/cli/renderers/audit_overview.py
+"""Renderer for audit overview table."""
+
+from __future__ import annotations
+
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+from shared.logger import getLogger
+from shared.models.audit_rendering import SeverityGroup, get_severity_style
+
+
+logger = getLogger(__name__)
+
+
+# ID: a42afd0d-567d-4404-a401-aa26b2664246
+def render_overview(console: Console, groups: list[SeverityGroup]) -> None:
+    """Render overview table with severity counts and percentages."""
+    total = sum(len(g.findings) for g in groups)
+    if total == 0:
+        console.print("[bold green]No findings.[/]")
+        return
+    table = Table(
+        title="[bold magenta]Audit Overview[/bold magenta]",
+        show_header=True,
+        header_style="bold magenta",
+    )
+    table.add_column("Severity", style="dim")
+    table.add_column("Count", justify="right", style="cyan")
+    table.add_column("%", justify="right", style="magenta")
+    for group in groups:
+        count = len(group.findings)
+        if count == 0:
+            continue
+        pct = count / total * 100
+        sev_text = Text(group.severity.name, style=get_severity_style(group.severity))
+        table.add_row(sev_text, str(count), f"{pct:.1f}%")
+    console.print(table)

cli/resources/__init__.py

@@ -0,0 +1,27 @@
+# src/cli/resources/__init__.py
+"""
+Resource-first CLI command modules.
+
+Constitutional Alignment:
+- Commands organized by resource (database, vectors, code, etc.)
+- No exposure of internal architecture layers (mind/body/will)
+- Resource-action pattern enforced at registration
+
+Structure:
+    database/    - PostgreSQL operations
+    vectors/     - Qdrant vector operations
+    code/        - Codebase operations
+    symbols/     - Symbol registry operations
+    constitution/ - Governance operations
+    proposals/   - Autonomy workflow
+    project/     - Project lifecycle
+    dev/         - Developer workflows
+    admin/       - System administration
+
+Governed by: .intent/rules/cli/interface_design.json
+"""
+
+from __future__ import annotations
+
+
+__all__ = []

cli/resources/admin/__init__.py

@@ -0,0 +1,23 @@
+# src/cli/resources/admin/__init__.py
+"""Admin forensic resource hub."""
+
+from __future__ import annotations
+
+# Register Forensic Neurons
+from . import (
+    coverage,
+    debt_scan,
+    forensics,
+    health,
+    patterns,
+    refusals,
+    self_check,
+    status,
+    summary,
+    traces,
+    validate_env,
+)
+from .hub import app
+
+
+__all__ = ["app"]

cli/resources/admin/coverage.py

@@ -0,0 +1,63 @@
+# src/cli/resources/admin/coverage.py
+"""
+Admin Coverage Command - Constitutional Binding Audit.
+Analyzes the gap between declared laws and physical enforcement.
+"""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from cli.logic.governance.traceability_service import GovernanceTraceabilityService
+from cli.utils import core_command
+from shared.cli.command_meta import CommandBehavior, CommandLayer, command_meta
+
+from .hub import app
+
+
+console = Console()
+
+
+@app.command("coverage")
+@command_meta(
+    canonical_name="admin.coverage",
+    behavior=CommandBehavior.READ,
+    layer=CommandLayer.MIND,
+    summary="Audit the binding between constitutional rules and enforcement engines.",
+)
+@core_command(dangerous=False, requires_context=True)
+# ID: 7e425c3d-d707-4f5c-84e6-57c510cfd473
+async def admin_coverage_cmd(ctx: typer.Context) -> None:
+    """
+    Generate a Traceability Matrix.
+    Identifies 'Critical Gaps' where Blocking rules have no enforcement engine.
+    """
+    core_context = ctx.obj
+    service = GovernanceTraceabilityService(core_context.git_service.repo_path)
+    console.print(
+        "\n[bold cyan]⚖️  Audit: Constitutional Binding Analysis...[/bold cyan]\n"
+    )
+    report = service.generate_traceability_report()
+    summary = report["summary"]
+    stats = f"Total Rules: {summary['total_rules']}\nEnforced   : [green]{summary['enforced_count']}[/green]\nUnbound    : [yellow]{summary['unbound_count']}[/yellow]\nCoverage   : [bold]{summary['coverage_percent']}%[/bold]"
+    console.print(Panel(stats, title="Coverage Summary", expand=False))
+    if report["critical_gaps"]:
+        console.print(
+            "\n[bold red]🚨 CRITICAL GAPS: Blocking Rules without Enforcement[/bold red]"
+        )
+        gap_table = Table(show_header=True, header_style="bold red")
+        gap_table.add_column("Rule ID", style="cyan")
+        gap_table.add_column("Policy Source", style="dim")
+        for gap in report["critical_gaps"]:
+            gap_table.add_row(gap["id"], gap["policy"])
+        console.print(gap_table)
+    else:
+        console.print(
+            "\n[bold green]✅ No Critical Gaps: All 'Blocking' rules are bound to engines.[/bold green]"
+        )
+    console.print(
+        "\n[dim]Full Traceability Matrix saved to: reports/governance/traceability_matrix.json[/dim]\n"
+    )

cli/resources/admin/debt_scan.py

@@ -0,0 +1,195 @@
+# src/cli/resources/admin/debt_scan.py
+"""
+Admin Legacy Command - Technical Debt Map.
+
+Scans the codebase for markers that indicate workarounds, healed
+violations, circular import patches, and unresolved TODOs.
+
+Output tells you exactly where to focus cleanup work.
+
+Constitutional Alignment:
+- Behavior: READ (pure scan, no mutations)
+- Layer: MIND (governance visibility)
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from cli.logic.legacy_scan_logic import (
+    LEGACY_MARKERS,
+    LegacyScanResult,
+    get_top_debt_files,
+    scan_for_legacy_markers,
+)
+from cli.utils import core_command
+from shared.cli.command_meta import CommandBehavior, CommandLayer, command_meta
+
+from .hub import app
+
+
+console = Console()
+
+
+@app.command("legacy")
+@command_meta(
+    canonical_name="admin.legacy",
+    behavior=CommandBehavior.READ,
+    layer=CommandLayer.MIND,
+    summary="Scan codebase for legacy markers and technical debt.",
+)
+@core_command(dangerous=False, requires_context=False)
+# ID: 35659535-e2b1-4df5-8671-d3c485557100
+def admin_legacy_cmd(
+    ctx: typer.Context,
+    severity: str = typer.Option(
+        None, "--severity", "-s", help="Filter by severity: high, medium, low"
+    ),
+    top: int = typer.Option(
+        20, "--top", "-n", help="Show top N files by debt load (default: 20)"
+    ),
+    detail: bool = typer.Option(
+        False, "--detail", "-d", help="Show individual lines, not just file summary"
+    ),
+    marker: str = typer.Option(
+        None,
+        "--marker",
+        "-m",
+        help="Filter by marker type (e.g. HEALED, FUTURE, DEPRECATED)",
+    ),
+) -> None:
+    """
+    Find every HEALED, CONSTITUTIONAL FIX, CIRCULARITY FIX, DEPRECATED,
+    FUTURE, PENDING, HACK, WORKAROUND and LEGACY marker in the codebase.
+
+    This is your cleanup map. Start with high severity, highest count files.
+
+    Examples:
+        core-admin admin legacy
+        core-admin admin legacy --severity high
+        core-admin admin legacy --marker HEALED --detail
+        core-admin admin legacy --top 5 --detail
+    """
+    repo_root = Path.cwd()
+    if severity and severity not in ("high", "medium", "low"):
+        console.print("[red]Invalid severity. Choose: high, medium, low[/red]")
+        raise typer.Exit(1)
+    if marker:
+        marker = marker.upper()
+        if marker not in LEGACY_MARKERS:
+            valid = ", ".join(LEGACY_MARKERS.keys())
+            console.print(f"[red]Unknown marker '{marker}'. Valid: {valid}[/red]")
+            raise typer.Exit(1)
+    console.print(
+        f"\n[bold cyan]🔍 Scanning for technical debt in {repo_root}/src ...[/bold cyan]\n"
+    )
+    result = scan_for_legacy_markers(
+        repo_root=repo_root, scan_dirs=["src"], severity_filter=severity
+    )
+    if marker:
+        result = _filter_by_marker(result, marker)
+    if result.total_hits == 0:
+        console.print("[green]✅ No legacy markers found. Clean codebase![/green]\n")
+        return
+    _print_summary_panel(result)
+    _print_marker_breakdown(result)
+    _print_file_table(result, top=top, detail=detail)
+
+
+def _filter_by_marker(result: LegacyScanResult, marker: str) -> LegacyScanResult:
+    """Return a new result containing only hits for the given marker."""
+    from cli.logic.legacy_scan_logic import FileLegacySummary
+
+    filtered = []
+    for file_summary in result.files_with_hits:
+        matching = [h for h in file_summary.hits if h.marker == marker]
+        if matching:
+            fs = FileLegacySummary(file_path=file_summary.file_path)
+            fs.hits = matching
+            filtered.append(fs)
+    result.files_with_hits = filtered
+    return result
+
+
+def _print_summary_panel(result: LegacyScanResult) -> None:
+    """Print the top-level summary panel."""
+    high = result.total_high_severity
+    total = result.total_hits
+    files = len(result.files_with_hits)
+    high_color = "red" if high > 0 else "green"
+    summary = f"Files scanned : {result.files_scanned}\nFiles with debt: {files}\nTotal markers : {total}\n[{high_color}]High severity : {high}[/{high_color}]"
+    console.print(
+        Panel(summary, title="[bold]Technical Debt Summary[/bold]", expand=False)
+    )
+
+
+def _print_marker_breakdown(result: LegacyScanResult) -> None:
+    """Print per-marker count table."""
+    totals = result.marker_totals
+    if not totals:
+        return
+    table = Table(
+        title="Marker Breakdown",
+        header_style="bold magenta",
+        show_header=True,
+        show_lines=False,
+    )
+    table.add_column("Marker", style="cyan", min_width=20)
+    table.add_column("Count", justify="right", min_width=6)
+    table.add_column("Severity", min_width=8)
+    table.add_column("Meaning", style="dim")
+    for marker_key, count in totals.items():
+        info = LEGACY_MARKERS.get(marker_key, {})
+        severity = info.get("severity", "?")
+        color = info.get("color", "white")
+        label = info.get("description", "")
+        table.add_row(
+            f"[{color}]{marker_key}[/{color}]",
+            str(count),
+            f"[{color}]{severity}[/{color}]",
+            label,
+        )
+    console.print(table)
+    console.print()
+
+
+def _print_file_table(result: LegacyScanResult, top: int, detail: bool) -> None:
+    """Print per-file debt table, optionally with line detail."""
+    files = get_top_debt_files(result, limit=top)
+    if not files:
+        return
+    table = Table(
+        title=f"Top {top} Files by Debt Load",
+        header_style="bold magenta",
+        show_header=True,
+        show_lines=detail,
+    )
+    table.add_column("File", style="cyan")
+    table.add_column("Total", justify="right", min_width=6)
+    table.add_column("High", justify="right", min_width=6, style="red")
+    table.add_column("Markers")
+    for file_summary in files:
+        marker_str = ", ".join((f"{k}x{v}" for k, v in file_summary.by_marker.items()))
+        table.add_row(
+            file_summary.file_path,
+            str(file_summary.total),
+            str(file_summary.high_severity_count),
+            marker_str,
+        )
+        if detail:
+            for hit in file_summary.hits:
+                table.add_row(
+                    f"  [dim]L{hit.line_number}[/dim]",
+                    "",
+                    "",
+                    f"[{hit.color}]{hit.marker}[/{hit.color}]  [dim]{hit.line_content}[/dim]",
+                )
+    console.print(table)
+    console.print(
+        "\n[dim]Run with --detail to see individual lines. Run with --severity high to focus on critical debt.[/dim]\n"
+    )