core-runtime 0.1.1__py3-none-any.whl

cli/resources/workers/remediate.py

@@ -0,0 +1,337 @@
+# src/cli/resources/workers/remediate.py
+"""
+Remediation pipeline command.
+
+Chains AuditViolationSensor → ViolationRemediator for a given audit rule.
+
+Usage:
+    # Dry-run (default) — sense violations, run LLM + Canary, post proposed
+    # fixes to blackboard for review. Nothing written to src/.
+    core-admin workers remediate purity.no_ast_duplication
+
+    # Write mode — apply fixes, commit
+    core-admin workers remediate purity.no_ast_duplication --write
+
+    # Sense only — just post findings to blackboard, no LLM
+    core-admin workers remediate purity.no_ast_duplication --sense-only
+
+    # File mode — audit a single file across all rules, then remediate
+    core-admin workers remediate --file src/body/workers/violation_remediator.py
+    core-admin workers remediate --file src/body/workers/violation_remediator.py --write
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from pathlib import Path
+from typing import Any
+
+import typer
+from rich.console import Console
+
+from cli.utils.decorators import core_command
+from shared.context import CoreContext
+from shared.infrastructure.database.session_manager import get_session
+
+from .run import workers_app
+
+
+logger = logging.getLogger(__name__)
+console = Console()
+
+
+@workers_app.command("remediate")
+@core_command(dangerous=True)
+# ID: 75e79945-f796-49d5-ba87-783cae6233d0
+async def remediate_cmd(
+    ctx: typer.Context,
+    rule: str = typer.Argument(
+        None, help="Audit rule ID to remediate (e.g. 'purity.no_ast_duplication')."
+    ),
+    write: bool = typer.Option(
+        False,
+        "--write",
+        help="Apply fixes to src/ and commit. Default is dry-run: LLM + Canary run but nothing is written.",
+    ),
+    sense_only: bool = typer.Option(
+        False,
+        "--sense-only",
+        help="Only run the sensor — post findings to blackboard, skip LLM.",
+    ),
+    file: str | None = typer.Option(
+        None,
+        "--file",
+        help=(
+            "Audit a single file across all rules, then remediate. "
+            "Mutually exclusive with rule and --sense-only. "
+            "Path must be relative to repo root."
+        ),
+    ),
+) -> None:
+    """
+    Run the autonomous remediation pipeline for a constitutional audit rule.
+
+    Default (dry-run): sensor finds violations → LLM proposes fix →
+    Canary validates → proposed fix posted to blackboard for review.
+
+    With --write: same pipeline but fix is applied to src/ and committed.
+
+    With --sense-only: only the sensor runs — violations are posted to
+    the blackboard but no LLM is invoked.
+
+    With --file: run a full audit scoped to a single file across all rules,
+    then feed findings directly into ViolationRemediator (bypasses sensor
+    and blackboard). Mutually exclusive with rule and --sense-only.
+
+    Examples:
+        # Dry-run — review proposed fixes on the blackboard first
+        core-admin workers remediate purity.no_ast_duplication
+
+        # Apply fixes
+        core-admin workers remediate purity.no_ast_duplication --write
+
+        # Just sense — populate blackboard, no LLM
+        core-admin workers remediate purity.no_ast_duplication --sense-only
+
+        # File mode — audit one file, remediate all violations found
+        core-admin workers remediate --file src/body/workers/violation_remediator.py
+    """
+    # --- mutual exclusion checks ---
+    if file and rule:
+        logger.info(
+            "--file and rule are mutually exclusive. "
+            "Use --file to audit a single file across all rules, "
+            "or provide a rule argument to use the sensor pipeline."
+        )
+        raise typer.Exit(code=1)
+
+    if file and sense_only:
+        logger.info(
+            "--file and --sense-only are incompatible. "
+            "--file already runs the audit; there is nothing to sense."
+        )
+        raise typer.Exit(code=1)
+
+    if not file and not rule:
+        logger.info("Either a rule argument or --file option is required.")
+        raise typer.Exit(code=1)
+
+    core_context: CoreContext = ctx.obj
+    async with get_session() as session:
+        await core_context.cognitive_service.initialize(session)
+
+    if file:
+        await _run_file_pipeline(core_context, file, write)
+    else:
+        await _run_rule_pipeline(core_context, rule, write, sense_only)
+
+
+async def _run_file_pipeline(
+    core_context: CoreContext,
+    file_path: str,
+    write: bool,
+) -> None:
+    """Audit a single file across all rules, then feed findings into ViolationRemediator."""
+    from mind.governance.audit_context import AuditorContext
+    from mind.governance.auditor import ConstitutionalAuditor
+    from will.workers.violation_remediator_body import ViolationRemediator
+
+    repo_root: Path = core_context.git_service.repo_path
+    abs_path = repo_root / file_path
+
+    if not abs_path.is_file():
+        logger.info("File not found: %s (resolved to %s)", file_path, abs_path)
+        raise typer.Exit(code=1)
+
+    mode = "WRITE" if write else "DRY-RUN"
+    logger.info(
+        "Remediation pipeline (file mode) file=%s mode=%s",
+        file_path,
+        mode,
+    )
+
+    # Step 1 — File-scoped full audit
+    logger.info("Step 1/2 - Full audit scoped to %s", file_path)
+
+    auditor_context: AuditorContext = core_context.auditor_context
+    async with get_session() as session:
+        auditor_context.db_session = session
+        await auditor_context.load_knowledge_graph()
+        auditor = ConstitutionalAuditor(auditor_context)
+        result = await auditor.run_full_audit_async()
+        auditor_context.db_session = None
+
+    all_findings = result.get("findings", [])
+    file_findings = _filter_findings_for_file(all_findings, file_path)
+
+    if not file_findings:
+        logger.info("No violations found in %s", file_path)
+        return
+
+    logger.info(
+        "Found %d violation(s) in %s across %d rule(s)",
+        len(file_findings),
+        file_path,
+        len({f["rule"] for f in file_findings}),
+    )
+
+    # Step 2 — Feed findings into ViolationRemediator directly
+    logger.info("Step 2/2 - ViolationRemediator (file mode)")
+
+    # Build synthetic blackboard-style finding dicts that ViolationRemediator expects.
+    synthetic_findings = _build_synthetic_findings(file_findings, file_path)
+
+    # Determine a combined target_rule label for the remediator.
+    unique_rules = sorted({f["rule"] for f in file_findings})
+    target_rule = unique_rules[0] if len(unique_rules) == 1 else "file-audit"
+
+    remediator = ViolationRemediator(
+        core_context=core_context, target_rule=target_rule, write=write
+    )
+
+    # Bypass blackboard: override _claim_open_findings to return our findings,
+    # and _mark_finding / _mark_findings to no-op (no blackboard entries exist).
+    async def _injected_claim() -> list[dict[str, Any]]:
+        return synthetic_findings
+
+    async def _noop_mark_findings(findings: list[dict[str, Any]], status: str) -> None:
+        pass
+
+    async def _noop_mark_finding(finding_id: str, status: str) -> None:
+        pass
+
+    remediator._claim_open_findings = _injected_claim  # type: ignore[assignment]
+    remediator._mark_findings = _noop_mark_findings  # type: ignore[assignment]
+    remediator._mark_finding = _noop_mark_finding  # type: ignore[assignment]
+
+    await remediator.start()
+    logger.info("Remediator complete.")
+
+    console.print()
+    if write:
+        logger.info(
+            "Pipeline complete in WRITE mode. "
+            "Fixes applied and committed. Run audit to verify:"
+        )
+        logger.info("  core-admin code audit")
+    else:
+        logger.info(
+            "Pipeline complete in DRY-RUN mode. "
+            "Proposed fixes are on the blackboard. Review them:"
+        )
+        logger.info(
+            "  core-admin workers blackboard --filter 'audit.remediation.dry_run'"
+        )
+        logger.info("\nWhen satisfied, apply with:")
+        logger.info("  core-admin workers remediate --file %s --write", file_path)
+
+
+def _filter_findings_for_file(
+    findings: list[Any], target_file: str
+) -> list[dict[str, Any]]:
+    """Filter audit findings to only those matching the target file path."""
+    result = []
+    for f in findings:
+        if isinstance(f, dict):
+            fp = f.get("file_path") or ""
+            check_id = f.get("check_id", "unknown")
+            message = f.get("message", "")
+            severity = str(f.get("severity", "warning"))
+            line_number = f.get("line_number")
+        else:
+            fp = getattr(f, "file_path", None) or ""
+            check_id = getattr(f, "check_id", "unknown")
+            message = getattr(f, "message", "")
+            severity = str(getattr(f, "severity", "warning"))
+            line_number = getattr(f, "line_number", None)
+
+        if fp == target_file:
+            result.append(
+                {
+                    "file_path": fp,
+                    "rule": check_id,
+                    "message": message,
+                    "severity": severity,
+                    "line_number": line_number,
+                }
+            )
+    return result
+
+
+def _build_synthetic_findings(
+    file_findings: list[dict[str, Any]], file_path: str
+) -> list[dict[str, Any]]:
+    """Convert filtered audit findings into the blackboard-entry format ViolationRemediator expects."""
+    synthetic = []
+    for f in file_findings:
+        synthetic.append(
+            {
+                "id": str(uuid.uuid4()),
+                "payload": {
+                    "file_path": file_path,
+                    "rule": f["rule"],
+                    "message": f["message"],
+                    "severity": f["severity"],
+                    "line_number": f.get("line_number"),
+                    "status": "unprocessed",
+                },
+            }
+        )
+    return synthetic
+
+
+async def _run_rule_pipeline(
+    core_context: CoreContext,
+    rule: str,
+    write: bool,
+    sense_only: bool,
+) -> None:
+    """Original rule-based pipeline: AuditViolationSensor → ViolationRemediator."""
+    from will.workers.audit_violation_sensor import AuditViolationSensor
+    from will.workers.violation_remediator_body import ViolationRemediator
+
+    mode = "SENSE-ONLY" if sense_only else "WRITE" if write else "DRY-RUN"
+    logger.info(
+        "Remediation pipeline rule=%s mode=%s",
+        rule,
+        mode,
+    )
+    logger.info("Step 1/2 - AuditViolationSensor")
+    sensor = AuditViolationSensor(
+        core_context=core_context,
+        declaration_name=f"audit_sensor_{rule.split('.')[0]}",
+        rule_namespace=rule,
+        dry_run=not write,
+    )
+    await sensor.start()
+    logger.info("Sensor complete.")
+    if sense_only:
+        logger.info("--sense-only: skipping remediator. Check blackboard for findings:")
+        logger.info(
+            "  core-admin workers blackboard --filter 'audit.violation::%s'", rule
+        )
+        return
+    logger.info("Step 2/2 - ViolationRemediator")
+    remediator = ViolationRemediator(
+        core_context=core_context, target_rule=rule, write=write
+    )
+    await remediator.start()
+    logger.info("Remediator complete.")
+    console.print()
+    if write:
+        logger.info(
+            "Pipeline complete in WRITE mode. "
+            "Fixes applied and committed. Run audit to verify:"
+        )
+        logger.info("  core-admin code audit")
+    else:
+        logger.info(
+            "Pipeline complete in DRY-RUN mode. "
+            "Proposed fixes are on the blackboard. Review them:"
+        )
+        logger.info(
+            "  core-admin workers blackboard --filter 'audit.remediation.dry_run'"
+        )
+        logger.info("\nWhen satisfied, apply with:")
+        logger.info("  core-admin workers remediate %s --write", rule)

cli/resources/workers/run.py

@@ -0,0 +1,140 @@
+# src/cli/resources/workers/run.py
+"""Worker run command — starts a constitutional worker by declaration name."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+import typer
+import yaml
+from rich.console import Console
+
+from cli.utils.decorators import core_command
+from shared.config import settings
+from shared.context import CoreContext
+from shared.infrastructure.database.session_manager import get_session
+
+
+logger = logging.getLogger(__name__)
+console = Console()
+workers_app = typer.Typer(
+    help="Constitutional worker management.", no_args_is_help=True
+)
+
+
+def _load_worker_declarations() -> dict[str, dict]:
+    """
+    Discover all active worker declarations from .intent/workers/.
+
+    Returns a dict keyed by declaration name (YAML stem), value is the
+    parsed declaration dict. Only active workers are included.
+
+    This is the constitutional alternative to a hardcoded Python registry —
+    adding a new worker requires only a YAML declaration, not a code change.
+    """
+    workers_dir: Path = settings.MIND / "workers"
+    if not workers_dir.exists():
+        return {}
+    declarations = {}
+    for yaml_path in sorted(workers_dir.glob("*.yaml")):
+        try:
+            data = yaml.safe_load(yaml_path.read_text(encoding="utf-8"))
+            if data.get("metadata", {}).get("status") != "active":
+                continue
+            impl = data.get("implementation")
+            if not impl or not impl.get("module") or (not impl.get("class")):
+                logger.warning(
+                    "Worker declaration '%s' is missing implementation block — skipped.",
+                    yaml_path.stem,
+                )
+                continue
+            declarations[yaml_path.stem] = data
+        except Exception as e:
+            logger.warning("Could not load worker declaration %s: %s", yaml_path, e)
+    return declarations
+
+
+@workers_app.command("run")
+@core_command(dangerous=False)
+# ID: ed6afc60-992e-4695-9a64-59844ec6be65
+async def workers_run_cmd(
+    ctx: typer.Context,
+    worker_name: str = typer.Argument(
+        ..., help="Worker declaration name (e.g. doc_worker)."
+    ),
+) -> None:
+    """Start a constitutional worker by its declaration name."""
+    import importlib
+
+    declarations = _load_worker_declarations()
+    if worker_name not in declarations:
+        available = ", ".join(sorted(declarations.keys())) or "(none declared)"
+        console.print(f"[red]Unknown worker: {worker_name}[/red]")
+        console.print(f"Available: {available}")
+        raise typer.Exit(code=1)
+    declaration = declarations[worker_name]
+    impl = declaration["implementation"]
+    module_path: str = impl["module"]
+    class_name: str = impl["class"]
+    needs_context: bool = impl.get("requires_core_context", False)
+    core_context: CoreContext = ctx.obj
+    async with get_session() as session:
+        await core_context.cognitive_service.initialize(session)
+    module = importlib.import_module(module_path)
+    worker_class = getattr(module, class_name)
+
+    # Replicate the daemon's constructor-kwargs build (see _run_daemon in
+    # cli/commands/daemon.py) so parameterised workers — those declaring
+    # mandate.scope.rule_namespace or implementation.params — receive the
+    # same arguments they get under the daemon. Without this, sensors like
+    # AuditViolationSensor TypeError on missing rule_namespace (#262).
+    kwargs: dict[str, Any] = {"declaration_name": worker_name}
+    rule_namespace = (
+        declaration.get("mandate", {}).get("scope", {}).get("rule_namespace", "")
+    )
+    if rule_namespace:
+        kwargs["rule_namespace"] = rule_namespace
+
+    extra_params = impl.get("params") or {}
+    if extra_params:
+        protected = {
+            "declaration_name",
+            "rule_namespace",
+            "core_context",
+            "cognitive_service",
+        }
+        clashes = set(extra_params) & protected
+        if clashes:
+            logger.warning(
+                "Worker '%s' implementation.params contains protected keys "
+                "%s — they will be ignored.",
+                worker_name,
+                clashes,
+            )
+            extra_params = {k: v for k, v in extra_params.items() if k not in protected}
+        kwargs.update(extra_params)
+
+    cog_svc = core_context.cognitive_service
+
+    # Single fallback to bare instantiation handles workers whose
+    # __init__ takes no args and rely on a class-level declaration_name
+    # (e.g. ObserverWorker). Anything more elaborate belongs in the daemon's
+    # _instantiate_worker, not the CLI run path.
+    if needs_context:
+        try:
+            worker = worker_class(core_context=core_context, **kwargs)
+        except TypeError:
+            worker = worker_class(core_context=core_context)
+    else:
+        try:
+            worker = worker_class(cognitive_service=cog_svc, **kwargs)
+        except TypeError:
+            worker = worker_class()
+
+    if not worker.declaration_name:
+        worker.declaration_name = worker_name
+    console.print(f"[bold green]Starting worker: {worker_name}[/bold green]")
+    await worker.start()
+    console.print(f"[bold green]Worker {worker_name} completed.[/bold green]")

cli/utils/__init__.py

@@ -0,0 +1,32 @@
+# src/cli/utils/__init__.py
+
+"""
+Modularized Package Entry Point (V2.3).
+"""
+
+from __future__ import annotations
+
+from .decorators import COMMAND_REGISTRY, async_command, core_command
+from .display import (
+    console,
+    display_error,
+    display_info,
+    display_success,
+    display_warning,
+)
+from .helpers import deprecated_command
+from .prompts import confirm_action
+
+
+__all__ = [
+    "COMMAND_REGISTRY",
+    "async_command",
+    "confirm_action",
+    "console",
+    "core_command",
+    "deprecated_command",
+    "display_error",
+    "display_info",
+    "display_success",
+    "display_warning",
+]

cli/utils/annotation_formatter.py

@@ -0,0 +1,154 @@
+# src/cli/utils/annotation_formatter.py
+
+"""F-10.2 — GitHub Actions workflow-command annotation formatter.
+
+Renders the F-10.1a stateless-audit payload as GitHub Actions
+workflow-command lines so findings surface inline in PR diff view
+(next to the offending line) rather than only in the workflow log.
+
+Format per GitHub Actions documentation:
+
+    ::error file=PATH,line=N,col=N::MESSAGE
+    ::warning file=PATH,line=N,col=N::MESSAGE
+    ::notice file=PATH,line=N,col=N::MESSAGE
+
+ADR-085 §D5 lists "PR annotations + merge-blocking demonstrated
+against a real external repo" as the F-10 exit criterion. The
+annotation channel is the user-visible surface of the gate — findings
+only in the workflow log are effectively invisible in a developer's
+PR review flow.
+
+Severity-to-channel mapping (constitutional contract):
+
+| CORE severity | GH channel | Merge-block? | Why                              |
+|---------------|------------|--------------|----------------------------------|
+| blocking      | error      | yes          | gate's whole point               |
+| high          | error      | yes          | parse_min_severity default       |
+| medium        | warning    | no           | visible in PR, doesn't block     |
+| low           | notice     | no           | informational                    |
+| info          | notice     | no           | informational                    |
+
+Skipped rules (from F-10.1a's `skipped_rules` field) are emitted as
+notices so the operator sees them in the workflow log, but they do not
+appear inline in the diff (no file/line). This preserves the honesty
+commitment from F-10.1a — degraded coverage is surfaced, not silent.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+_SEVERITY_TO_CHANNEL: dict[str, str] = {
+    "blocking": "error",
+    "block": "error",
+    "high": "error",
+    "medium": "warning",
+    "low": "notice",
+    "info": "notice",
+}
+
+# The 'error' channel is what GitHub uses to fail required status
+# checks; merge-blocking is keyed off this. Documented here so a future
+# maintainer can audit the merge-block surface in one place.
+_MERGE_BLOCKING_CHANNELS: frozenset[str] = frozenset({"error"})
+
+
+# ID: 496df0ee-c556-41ba-b894-05e5979b2f64
+def severity_to_channel(severity: str) -> str:
+    """Map a CORE severity string to a GH annotation channel.
+
+    Unknown severities fall back to ``notice`` (visible but non-blocking).
+    This is the safer default: a misclassified finding still surfaces
+    rather than getting silently swallowed.
+    """
+    return _SEVERITY_TO_CHANNEL.get(severity.lower(), "notice")
+
+
+# ID: 9922cc55-939c-435d-94a3-74af7e048f04
+def format_finding(finding: dict[str, Any]) -> str:
+    """Format a single finding as one GH workflow-command line.
+
+    Newlines and ``%``/``\\r`` characters in the message are URL-encoded
+    per GitHub's escaping rules; otherwise a multi-line message breaks
+    the workflow-command parser and the annotation never renders.
+    """
+    severity = str(finding.get("severity", "info"))
+    channel = severity_to_channel(severity)
+
+    file_path = finding.get("file", "")
+    line_no = finding.get("line", 1) or 1
+    raw_message = str(finding.get("message", "") or finding.get("rule_id", ""))
+    rule_id = finding.get("rule_id", "")
+    title = f"{rule_id} [{severity}]" if rule_id else severity
+
+    # GH's workflow-command parser breaks on raw newlines and on the
+    # literal characters % \r \n inside the message. Encode per the GH
+    # documentation: %25 %0D %0A.
+    safe_message = (
+        raw_message.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")
+    )
+    safe_title = title.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")
+
+    parts = [f"file={file_path}", f"line={line_no}", f"title={safe_title}"]
+    return f"::{channel} {','.join(parts)}::{safe_message}"
+
+
+# ID: 319d626b-b926-4ab0-abf0-9df4cb07419a
+def format_skipped_rule(skipped: dict[str, str]) -> str:
+    """Format one skipped-rule entry as a GH notice (no file/line).
+
+    Skipped rules surface as workflow-log notices so the operator sees
+    the F-10.1a honesty signal (which rules ran vs. were skipped) but
+    they do not appear in the PR diff. CI users learn about reduced
+    coverage from the workflow output, not from the absence of
+    annotations.
+    """
+    rule_id = skipped.get("rule_id", "")
+    reason = skipped.get("reason", "skipped").replace("%", "%25")
+    return f"::notice title=Rule skipped: {rule_id}::{reason}"
+
+
+# ID: 2bc4a2c5-b119-40d1-88b4-27ee32978c5d
+def format_payload(payload: dict[str, Any]) -> str:
+    """Render the full F-10.1a payload as GH workflow-command lines.
+
+    Returns a newline-joined string; trailing newline included so the
+    last annotation parses correctly. Suitable for direct write to
+    stdout from the CLI's --format=github-annotations path.
+
+    Output order:
+    1. One line per finding (file/line/severity/message)
+    2. One line per skipped rule (workflow-log notice, no file/line)
+    3. One summary line on stderr-style notice (verdict + counts)
+
+    The summary appears last so a downstream consumer that truncates at
+    the first annotation still sees per-finding lines first.
+    """
+    lines: list[str] = []
+    findings = payload.get("findings", []) or []
+    for finding in findings:
+        lines.append(format_finding(finding))
+
+    skipped = payload.get("skipped_rules", []) or []
+    for entry in skipped:
+        lines.append(format_skipped_rule(entry))
+
+    verdict = payload.get("verdict", "UNKNOWN")
+    finding_count = len(findings)
+    skipped_count = len(skipped)
+    summary = (
+        f"CORE audit (stateless): verdict={verdict} "
+        f"findings={finding_count} skipped_rules={skipped_count}"
+    )
+    lines.append(f"::notice title=CORE audit summary::{summary}")
+
+    return "\n".join(lines) + "\n"
+
+
+__all__ = [
+    "format_finding",
+    "format_payload",
+    "format_skipped_rule",
+    "severity_to_channel",
+]