cortex-loop 0.1.0a1__py3-none-any.whl

cortex/foundation.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+import subprocess
+from collections import Counter
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path, PurePosixPath
+from typing import Iterable
+
+from .genome import FoundationConfig
+
+
+@dataclass(slots=True)
+class FoundationFinding:
+    path: str
+    churn_count: int
+    level: str
+
+    def to_dict(self) -> dict[str, object]:
+        return {"path": self.path, "churn_count": self.churn_count, "level": self.level}
+
+
+@dataclass(slots=True)
+class FoundationReport:
+    generated_at: str
+    enabled: bool
+    git_available: bool
+    watch_paths: list[str]
+    warnings: list[str] = field(default_factory=list)
+    findings: list[FoundationFinding] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "generated_at": self.generated_at,
+            "enabled": self.enabled,
+            "git_available": self.git_available,
+            "watch_paths": self.watch_paths,
+            "warnings": self.warnings,
+            "findings": [f.to_dict() for f in self.findings],
+        }
+
+    def by_path(self) -> dict[str, FoundationFinding]:
+        return {finding.path: finding for finding in self.findings}
+
+
+class FoundationAnalyzer:
+    def __init__(self, repo_root: Path, config: FoundationConfig) -> None:
+        self.repo_root = repo_root
+        self.config = config
+
+    def analyze(self) -> FoundationReport:
+        now = datetime.now(timezone.utc).isoformat()
+        if not self.config.enabled:
+            return FoundationReport(
+                generated_at=now,
+                enabled=False,
+                git_available=False,
+                watch_paths=list(self.config.watch_paths),
+                warnings=["Foundation analysis disabled in cortex.toml."],
+            )
+
+        git_repo, repo_warning = self._is_git_repo()
+        if not git_repo:
+            return FoundationReport(
+                generated_at=now,
+                enabled=True,
+                git_available=False,
+                watch_paths=list(self.config.watch_paths),
+                warnings=[repo_warning or "Git repository not detected; skipping churn analysis."],
+            )
+
+        counts, git_available, churn_warning = self._collect_churn_counts()
+        findings: list[FoundationFinding] = []
+        warnings: list[str] = [churn_warning] if churn_warning else []
+        for path, count in counts.most_common():
+            level = ""
+            if count >= self.config.stability_thresholds.high_churn_count:
+                level = "high"
+            elif count >= self.config.stability_thresholds.warn_churn_count:
+                level = "warn"
+            else:
+                continue
+            findings.append(FoundationFinding(path=path, churn_count=count, level=level))
+
+        if findings:
+            warnings.append(
+                f"Foundation analysis found {len(findings)} churn-heavy files in watched paths."
+            )
+
+        return FoundationReport(
+            generated_at=now,
+            enabled=True,
+            git_available=git_available,
+            watch_paths=list(self.config.watch_paths),
+            warnings=warnings,
+            findings=findings,
+        )
+
+    def warnings_for_target_files(self, target_files: Iterable[str]) -> list[str]:
+        report = self.analyze()
+        if not report.findings:
+            return report.warnings
+
+        target_set = {self._norm_path(path) for path in target_files if path}
+        if not target_set:
+            return report.warnings
+
+        findings = report.by_path()
+        matched: list[str] = []
+        for path in sorted(target_set):
+            finding = findings.get(path)
+            if finding is None:
+                continue
+            matched.append(
+                f"Target file {path} is {finding.level}-churn ({finding.churn_count} touches in recent window)."
+            )
+        return report.warnings + matched
+
+    def _is_git_repo(self) -> tuple[bool, str | None]:
+        timeout_ms = self._git_timeout_millis()
+        try:
+            result = subprocess.run(
+                ["git", "rev-parse", "--is-inside-work-tree"],
+                cwd=self.repo_root,
+                capture_output=True,
+                text=True,
+                check=False,
+                timeout=timeout_ms / 1000.0,
+            )
+        except FileNotFoundError:
+            return False, "Git binary not found; skipping churn analysis."
+        except subprocess.TimeoutExpired:
+            return (
+                False,
+                f"Git repository detection timed out after {timeout_ms}ms; skipping churn analysis.",
+            )
+        if result.returncode == 0 and result.stdout.strip() == "true":
+            return True, None
+        return False, "Git repository not detected; skipping churn analysis."
+
+    def _collect_churn_counts(self) -> tuple[Counter[str], bool, str | None]:
+        timeout_ms = self._git_timeout_millis()
+        cmd = ["git", "log", "--name-only", "--pretty=format:", f"-n{self.config.churn_window_commits}"]
+        cmd.extend(["--", *self.config.watch_paths])
+        try:
+            result = subprocess.run(
+                cmd,
+                cwd=self.repo_root,
+                capture_output=True,
+                text=True,
+                check=False,
+                timeout=timeout_ms / 1000.0,
+            )
+        except FileNotFoundError:
+            return Counter(), False, "Git binary not found; skipping churn analysis."
+        except subprocess.TimeoutExpired:
+            return (
+                Counter(),
+                False,
+                f"Git churn scan timed out after {timeout_ms}ms; skipping churn analysis.",
+            )
+        if result.returncode != 0:
+            return Counter(), True, "Git churn scan failed; skipping churn analysis."
+
+        counts: Counter[str] = Counter()
+        for raw in result.stdout.splitlines():
+            path = raw.strip()
+            if not path:
+                continue
+            norm = self._norm_path(path)
+            if self._ignored(norm):
+                continue
+            counts[norm] += 1
+        return counts, True, None
+
+    def _ignored(self, path: str) -> bool:
+        parts = set(PurePosixPath(path).parts)
+        return any(ignored in parts for ignored in self.config.ignored_dirs)
+
+    @staticmethod
+    def _norm_path(path: str) -> str:
+        return str(PurePosixPath(path))
+
+    def _git_timeout_millis(self) -> int:
+        return max(1, int(self.config.git_timeout_ms))

cortex/genome.py

@@ -0,0 +1,348 @@
+from __future__ import annotations
+
+import tomllib
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Iterable
+
+from .packs import load_pack_overlay
+from .utils import _as_bool
+
+GENOME_SCHEMA_VERSION = "cortex_toml_v1"
+
+
+@dataclass(slots=True)
+class ProjectConfig:
+    name: str = "unknown-project"
+    type: str = "generic"
+    root: str = "."
+    trust_profile: str = "trusted"
+@dataclass(slots=True)
+class InvariantGraduationConfig:
+    enabled: bool = True
+    target_dir: str = "tests/invariants/graduated"
+@dataclass(slots=True)
+class InvariantsConfig:
+    suite_paths: list[str] = field(default_factory=list)
+    pytest_bin: str = "pytest"
+    run_on_stop: bool = True
+    execution_mode: str = "host"
+    container_engine: str = "docker"
+    container_image: str = "python:3.11-slim"
+    container_workdir: str = "/workspace"
+    graduation: InvariantGraduationConfig = field(default_factory=InvariantGraduationConfig)
+@dataclass(slots=True)
+class ChallengesConfig:
+    active_categories: list[str] = field(default_factory=lambda: ["null_inputs", "boundary_values", "error_handling", "graveyard_regression"])
+    custom_paths: list[str] = field(default_factory=list)
+    require_coverage: bool = True
+@dataclass(slots=True)
+class GraveyardConfig:
+    enabled: bool = True
+    max_matches: int = 5
+    similarity_threshold: float = 0.35
+    min_keyword_overlap: int = 1
+    context_max_matches: int = 2
+    context_summary_chars: int = 140
+    context_reason_chars: int = 200
+    context_max_tokens: int = 300
+@dataclass(slots=True)
+class StabilityThresholds:
+    warn_churn_count: int = 8
+    high_churn_count: int = 15
+@dataclass(slots=True)
+class FoundationConfig:
+    enabled: bool = True
+    watch_paths: list[str] = field(default_factory=lambda: ["src"])
+    ignored_dirs: list[str] = field(default_factory=lambda: ["node_modules", "dist", "build", ".git", "__pycache__"])
+    stability_thresholds: StabilityThresholds = field(default_factory=StabilityThresholds)
+    churn_window_commits: int = 200
+    git_timeout_ms: int = 1500
+@dataclass(slots=True)
+class RepomapConfig:
+    enabled: bool = False
+    run_on_session_start: bool = False
+    prefer_ast_graph: bool = True
+    parity_profile: bool = False
+    extended_language_profile: bool = False
+    watch_paths: list[str] = field(default_factory=lambda: ["src"])
+    ignored_dirs: list[str] = field(default_factory=lambda: ["node_modules", "dist", "build", ".git", ".cortex", "__pycache__"])
+    max_ranked_files: int = 20
+    max_text_bytes: int = 8192
+    artifact_path: str = ".cortex/artifacts/repomap/latest.json"
+    non_blocking: bool = True
+    session_start_timeout_ms: int = 2500
+@dataclass(slots=True)
+class RuntimeConfig:
+    adapter: str = ""
+@dataclass(slots=True)
+class ExecutiveConfig:
+    enabled: bool = True
+    inject_identity_preamble: bool = True
+    part_a_mode: str = "once_per_project"
+    halflife_sessions: int = 30
+    decay_threshold: float = 0.3
+    inject_threshold: float = 0.45
+    max_entries: int = 20
+    max_tokens: int = 1200
+    min_hold_sessions: int = 3
+@dataclass(slots=True)
+class HooksConfig:
+    mode: str = "advisory"
+    fail_on_missing_challenge_coverage: bool = False
+    recommend_revert_on_invariant_failure: bool = True
+    require_requirement_audit: bool = False
+    fail_on_requirement_audit_gap: bool = False
+    require_evidence_for_passed_requirement: bool = True
+    require_structured_stop_payload: bool = False
+    allow_message_stop_fallback: bool = False
+    minimal_response: bool = False
+@dataclass(slots=True)
+class RetryConfig:
+    enabled: bool = True
+    max_retries: int = 3
+@dataclass(slots=True)
+class BlocklistConfig:
+    enabled: bool = True
+    blocked_tools: list[str] = field(default_factory=list)
+    allowed_tools: list[str] = field(default_factory=list)
+    fail_closed: bool = False
+@dataclass(slots=True)
+class PacksConfig:
+    paths: list[str] = field(default_factory=list)
+@dataclass(slots=True)
+class MetricsConfig:
+    enabled: bool = True
+    track: list[str] = field(default_factory=lambda: ["human_oversight_minutes", "interrupt_count", "escaped_defects", "completion_minutes", "foundation_quality"])
+@dataclass(slots=True)
+class CortexGenome:
+    project: ProjectConfig = field(default_factory=ProjectConfig)
+    invariants: InvariantsConfig = field(default_factory=InvariantsConfig)
+    challenges: ChallengesConfig = field(default_factory=ChallengesConfig)
+    graveyard: GraveyardConfig = field(default_factory=GraveyardConfig)
+    foundation: FoundationConfig = field(default_factory=FoundationConfig)
+    repomap: RepomapConfig = field(default_factory=RepomapConfig)
+    runtime: RuntimeConfig = field(default_factory=RuntimeConfig)
+    executive: ExecutiveConfig = field(default_factory=ExecutiveConfig)
+    hooks: HooksConfig = field(default_factory=HooksConfig)
+    retry: RetryConfig = field(default_factory=RetryConfig)
+    blocklist: BlocklistConfig = field(default_factory=BlocklistConfig)
+    packs: PacksConfig = field(default_factory=PacksConfig)
+    metrics: MetricsConfig = field(default_factory=MetricsConfig)
+    source_path: str | None = None
+    parse_error: str | None = None
+    load_warnings: list[str] = field(default_factory=list)
+    def to_dict(self) -> dict[str, Any]: return asdict(self)
+
+
+def load_genome(path: str | Path | None = None) -> CortexGenome:
+    config_path = Path(path) if path is not None else Path("cortex.toml")
+    if not config_path.exists():
+        return CortexGenome(source_path=str(config_path))
+    try:
+        with config_path.open("rb") as fh:
+            raw = tomllib.load(fh)
+        if not isinstance(raw, dict):
+            raise ValueError("Top-level TOML must be a table")
+    except Exception as exc:  # noqa: BLE001
+        return CortexGenome(source_path=str(config_path), parse_error=str(exc))
+    invariants = _load_invariants(raw.get("invariants", {}))
+    challenges = _load_challenges(raw.get("challenges", {}))
+    blocklist = _load_blocklist(raw.get("blocklist", {}))
+    packs = _load_packs(raw.get("packs", {}))
+    overlay = load_pack_overlay(root=config_path.resolve().parent, pack_paths=packs.paths)
+    if overlay.challenge_categories:
+        challenges.active_categories = _merge_unique(challenges.active_categories, overlay.challenge_categories)
+    if overlay.invariant_paths:
+        invariants.suite_paths = _merge_unique(invariants.suite_paths, overlay.invariant_paths)
+    if overlay.blocked_tools:
+        blocklist.blocked_tools = _merge_unique(blocklist.blocked_tools, overlay.blocked_tools)
+    if overlay.allowed_tools:
+        blocklist.allowed_tools = _merge_unique(blocklist.allowed_tools, overlay.allowed_tools)
+    return CortexGenome(
+        project=_load_project(raw.get("project", {})),
+        invariants=invariants,
+        challenges=challenges,
+        graveyard=_load_graveyard(raw.get("graveyard", {})),
+        foundation=_load_foundation(raw.get("foundation", {})),
+        repomap=_load_repomap(raw.get("repomap", {})),
+        runtime=_load_runtime(raw.get("runtime", {})),
+        executive=_load_executive(raw.get("executive", {})),
+        hooks=_load_hooks(raw.get("hooks", {})),
+        retry=_load_retry(raw.get("retry", {})),
+        blocklist=blocklist,
+        packs=packs,
+        metrics=_load_metrics(raw.get("metrics", {})),
+        source_path=str(config_path),
+        load_warnings=overlay.warnings,
+    )
+
+
+def _load_project(data: Any) -> ProjectConfig:
+    d, x = _as_dict(data), ProjectConfig()
+    trust_profile = str(d.get("trust_profile", x.trust_profile)).strip().lower()
+    if not trust_profile:
+        trust_profile = x.trust_profile
+    return ProjectConfig(
+        name=str(d.get("name", x.name)),
+        type=str(d.get("type", x.type)),
+        root=str(d.get("root", x.root)),
+        trust_profile=trust_profile,
+    )
+def _load_invariants(data: Any) -> InvariantsConfig:
+    d, x, g = _as_dict(data), InvariantsConfig(), _as_dict(_as_dict(data).get("graduation", {}))
+    gd = InvariantGraduationConfig()
+    execution_mode = str(d.get("execution_mode", x.execution_mode)).strip().lower()
+    if execution_mode not in {"host", "container"}:
+        execution_mode = x.execution_mode
+    return InvariantsConfig(
+        suite_paths=[str(v) for v in _as_list(d.get("suite_paths"), x.suite_paths)],
+        pytest_bin=str(d.get("pytest_bin", x.pytest_bin)),
+        run_on_stop=_as_bool(d.get("run_on_stop"), x.run_on_stop),
+        execution_mode=execution_mode,
+        container_engine=str(d.get("container_engine", x.container_engine)),
+        container_image=str(d.get("container_image", x.container_image)),
+        container_workdir=str(d.get("container_workdir", x.container_workdir)),
+        graduation=InvariantGraduationConfig(
+            enabled=_as_bool(g.get("enabled"), gd.enabled),
+            target_dir=str(g.get("target_dir", gd.target_dir)),
+        ),
+    )
+def _load_challenges(data: Any) -> ChallengesConfig:
+    d, x = _as_dict(data), ChallengesConfig()
+    return ChallengesConfig(active_categories=[str(v) for v in _as_list(d.get("active_categories"), x.active_categories)] or list(x.active_categories), custom_paths=[str(v) for v in _as_list(d.get("custom_paths"), x.custom_paths)], require_coverage=_as_bool(d.get("require_coverage"), x.require_coverage))
+def _load_graveyard(data: Any) -> GraveyardConfig:
+    d, x = _as_dict(data), GraveyardConfig()
+    return GraveyardConfig(
+        enabled=_as_bool(d.get("enabled"), x.enabled),
+        max_matches=_as_int(d.get("max_matches"), x.max_matches),
+        similarity_threshold=_as_float(d.get("similarity_threshold"), x.similarity_threshold),
+        min_keyword_overlap=_as_int(d.get("min_keyword_overlap"), x.min_keyword_overlap),
+        context_max_matches=max(1, _as_int(d.get("context_max_matches"), x.context_max_matches)),
+        context_summary_chars=max(40, _as_int(d.get("context_summary_chars"), x.context_summary_chars)),
+        context_reason_chars=max(40, _as_int(d.get("context_reason_chars"), x.context_reason_chars)),
+        context_max_tokens=max(50, _as_int(d.get("context_max_tokens"), x.context_max_tokens)),
+    )
+def _load_foundation(data: Any) -> FoundationConfig:
+    d, x, td = _as_dict(data), FoundationConfig(), StabilityThresholds()
+    t = _as_dict(d.get("stability_thresholds", {}))
+    return FoundationConfig(
+        enabled=_as_bool(d.get("enabled"), x.enabled),
+        watch_paths=[str(v) for v in _as_list(d.get("watch_paths"), x.watch_paths)],
+        ignored_dirs=[str(v) for v in _as_list(d.get("ignored_dirs"), x.ignored_dirs)],
+        stability_thresholds=StabilityThresholds(
+            warn_churn_count=_as_int(t.get("warn_churn_count"), td.warn_churn_count),
+            high_churn_count=_as_int(t.get("high_churn_count"), td.high_churn_count),
+        ),
+        churn_window_commits=_as_int(d.get("churn_window_commits"), x.churn_window_commits),
+        git_timeout_ms=max(1, _as_int(d.get("git_timeout_ms"), x.git_timeout_ms)),
+    )
+def _load_repomap(data: Any) -> RepomapConfig:
+    d, x = _as_dict(data), RepomapConfig()
+    return RepomapConfig(
+        enabled=_as_bool(d.get("enabled"), x.enabled),
+        run_on_session_start=_as_bool(d.get("run_on_session_start"), x.run_on_session_start),
+        prefer_ast_graph=_as_bool(d.get("prefer_ast_graph"), x.prefer_ast_graph),
+        parity_profile=_as_bool(d.get("parity_profile"), x.parity_profile),
+        extended_language_profile=_as_bool(d.get("extended_language_profile"), x.extended_language_profile),
+        watch_paths=[str(v) for v in _as_list(d.get("watch_paths"), x.watch_paths)],
+        ignored_dirs=[str(v) for v in _as_list(d.get("ignored_dirs"), x.ignored_dirs)],
+        max_ranked_files=_as_int(d.get("max_ranked_files"), x.max_ranked_files),
+        max_text_bytes=_as_int(d.get("max_text_bytes"), x.max_text_bytes),
+        artifact_path=str(d.get("artifact_path", x.artifact_path)),
+        non_blocking=_as_bool(d.get("non_blocking"), x.non_blocking),
+        session_start_timeout_ms=_as_int(d.get("session_start_timeout_ms"), x.session_start_timeout_ms),
+    )
+def _load_runtime(data: Any) -> RuntimeConfig:
+    d, x = _as_dict(data), RuntimeConfig()
+    return RuntimeConfig(adapter=str(d.get("adapter", x.adapter)).strip())
+def _load_executive(data: Any) -> ExecutiveConfig:
+    d, x = _as_dict(data), ExecutiveConfig()
+    part_a_mode = str(d.get("part_a_mode", x.part_a_mode)).strip().lower()
+    if part_a_mode not in {"once_per_project", "always"}:
+        part_a_mode = x.part_a_mode
+    return ExecutiveConfig(
+        enabled=_as_bool(d.get("enabled"), x.enabled),
+        inject_identity_preamble=_as_bool(d.get("inject_identity_preamble"), x.inject_identity_preamble),
+        part_a_mode=part_a_mode,
+        halflife_sessions=max(1, _as_int(d.get("halflife_sessions"), x.halflife_sessions)),
+        decay_threshold=max(0.0, _as_float(d.get("decay_threshold"), x.decay_threshold)),
+        inject_threshold=max(0.0, _as_float(d.get("inject_threshold"), x.inject_threshold)),
+        max_entries=max(1, _as_int(d.get("max_entries"), x.max_entries)),
+        max_tokens=max(200, _as_int(d.get("max_tokens"), x.max_tokens)),
+        min_hold_sessions=max(0, _as_int(d.get("min_hold_sessions"), x.min_hold_sessions)),
+    )
+def _load_hooks(data: Any) -> HooksConfig:
+    d, x = _as_dict(data), HooksConfig()
+    return HooksConfig(
+        mode=str(d.get("mode", x.mode)),
+        fail_on_missing_challenge_coverage=_as_bool(
+            d.get("fail_on_missing_challenge_coverage"), x.fail_on_missing_challenge_coverage
+        ),
+        recommend_revert_on_invariant_failure=_as_bool(
+            d.get("recommend_revert_on_invariant_failure"), x.recommend_revert_on_invariant_failure
+        ),
+        require_requirement_audit=_as_bool(
+            d.get("require_requirement_audit"), x.require_requirement_audit
+        ),
+        fail_on_requirement_audit_gap=_as_bool(
+            d.get("fail_on_requirement_audit_gap"), x.fail_on_requirement_audit_gap
+        ),
+        require_evidence_for_passed_requirement=_as_bool(
+            d.get("require_evidence_for_passed_requirement"), x.require_evidence_for_passed_requirement
+        ),
+        require_structured_stop_payload=_as_bool(
+            d.get("require_structured_stop_payload"), x.require_structured_stop_payload
+        ),
+        allow_message_stop_fallback=_as_bool(
+            d.get("allow_message_stop_fallback"), x.allow_message_stop_fallback
+        ),
+        minimal_response=_as_bool(
+            d.get("minimal_response"), x.minimal_response
+        ),
+    )
+def _load_retry(data: Any) -> RetryConfig:
+    d, x = _as_dict(data), RetryConfig()
+    return RetryConfig(enabled=_as_bool(d.get("enabled"), x.enabled), max_retries=_as_int(d.get("max_retries"), x.max_retries))
+def _load_blocklist(data: Any) -> BlocklistConfig:
+    d, x = _as_dict(data), BlocklistConfig()
+    return BlocklistConfig(
+        enabled=_as_bool(d.get("enabled"), x.enabled),
+        blocked_tools=[str(v) for v in _as_list(d.get("blocked_tools"), x.blocked_tools)],
+        allowed_tools=[str(v) for v in _as_list(d.get("allowed_tools"), x.allowed_tools)],
+        fail_closed=_as_bool(d.get("fail_closed"), x.fail_closed),
+    )
+def _load_packs(data: Any) -> PacksConfig:
+    d = _as_dict(data)
+    return PacksConfig(paths=[str(v) for v in _as_list(d.get("paths"), [])])
+def _load_metrics(data: Any) -> MetricsConfig:
+    d, x = _as_dict(data), MetricsConfig()
+    return MetricsConfig(enabled=_as_bool(d.get("enabled"), x.enabled), track=[str(v) for v in _as_list(d.get("track"), x.track)])
+
+
+def _as_dict(value: Any) -> dict[str, Any]:
+    return value if isinstance(value, dict) else {}
+def _as_list(value: Any, default: list[Any]) -> list[Any]:
+    return value if isinstance(value, list) else list(default)
+def _as_int(value: Any, default: int) -> int:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+def _as_float(value: Any, default: float) -> float:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return default
+def _merge_unique(base: list[str], extra: list[str]) -> list[str]:
+    merged: list[str] = []
+    seen: set[str] = set()
+    for item in [*base, *extra]:
+        token = str(item).strip()
+        if not token or token in seen:
+            continue
+        seen.add(token)
+        merged.append(token)
+    return merged
+def collect_active_metric_names(genome: CortexGenome) -> Iterable[str]:
+    return genome.metrics.track if genome.metrics.enabled else []