arkaos 4.0.2 → 4.1.1

package/core/governance/evidence_checks.py

@@ -0,0 +1,421 @@
+"""Evidence check engine — executable checks behind the Quality Gate (PR-4).
+
+Gate 4 verdicts DERIVE from tool output, not persona narrative. This
+module runs real, read-only checks over a project (lint, typecheck,
+tests, coverage, security grep, spellcheck) and returns a structured
+``EvidenceReport``. Reviewers INTERPRET the report; they cannot
+override it — ``overall == "fail"`` forces REJECTED.
+
+Safety contract:
+  - subprocesses run with ``cwd=project_dir``, ``capture_output=True``,
+    argument lists only (never ``shell=True`` with interpolated input)
+  - 300s cap per check; on expiry the process is killed and the check
+    reports ``ran=True, passed=None, summary="timeout"``
+  - nothing that mutates: no installs, no git, no writes to the project
+
+CLI (for hooks/skills)::
+
+    python -m core.governance.evidence_checks <project_dir> \
+        [--checks lint,tests] [--test-command '...'] \
+        [--changed-files f1,f2] [--json]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import shlex
+import shutil
+import subprocess
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+from core.shared.test_evidence import coverage_percent_from_xml
+
+TIMEOUT_SECONDS = 300
+COVERAGE_THRESHOLD = 80.0
+ALL_CHECKS: tuple[str, ...] = (
+    "lint", "typecheck", "tests", "coverage", "security-grep", "spellcheck",
+)
+
+_MAX_SUMMARY_CHARS = 800
+_MAX_GREP_HITS = 20
+
+# Obvious-classes security sweep. Line-level, over caller-supplied files.
+_SECURITY_PATTERNS: tuple[tuple[str, re.Pattern[str]], ...] = (
+    ("aws-access-key", re.compile(r"AKIA[0-9A-Z]{16}")),
+    ("api-secret-key", re.compile(r"\bsk-[A-Za-z0-9_-]{20,}")),
+    ("github-token", re.compile(r"\bghp_[A-Za-z0-9]{20,}")),
+    (
+        "hardcoded-password",
+        re.compile(r"password\s*=\s*['\"][^'\"]{4,}['\"]", re.IGNORECASE),
+    ),
+    (
+        "eval-exec-on-input",
+        re.compile(
+            r"\b(?:eval|exec)\s*\(.*(?:input|request|argv|params|body)",
+            re.IGNORECASE,
+        ),
+    ),
+    ("sql-percent-interpolation", re.compile(r"execute\s*\([^)]*['\"]\s*%")),
+    ("sql-fstring-interpolation", re.compile(r"execute\s*\(\s*f['\"]")),
+    ("curl-pipe-shell", re.compile(r"curl[^|\n]*\|\s*(?:ba|z)?sh\b")),
+)
+
+
+@dataclass
+class CheckResult:
+    """Outcome of one executable check."""
+
+    check: str
+    ran: bool
+    passed: bool | None
+    command: str
+    exit_code: int | None
+    summary: str
+    details_path: str | None = None
+
+
+@dataclass
+class EvidenceReport:
+    """All check results plus the derived overall evidence status."""
+
+    project_dir: str
+    overall: str  # "pass" | "fail" | "insufficient-evidence"
+    results: list[CheckResult] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "project_dir": self.project_dir,
+            "overall": self.overall,
+            "results": [asdict(r) for r in self.results],
+        }
+
+
+# ─── Subprocess plumbing ────────────────────────────────────────────────
+
+
+def _tail(text: str, limit: int = _MAX_SUMMARY_CHARS) -> str:
+    text = (text or "").strip()
+    return text[-limit:] if len(text) > limit else text
+
+
+def _skip(check: str, reason: str) -> CheckResult:
+    return CheckResult(
+        check=check, ran=False, passed=None, command="",
+        exit_code=None, summary=reason,
+    )
+
+
+def _run(
+    check: str, cmd: list[str], project_dir: Path, timeout: int,
+) -> CheckResult:
+    """Run one read-only project command; capture exit code + tail."""
+    command_str = " ".join(cmd)
+    try:
+        proc = subprocess.run(
+            cmd, cwd=project_dir, capture_output=True, text=True,
+            timeout=timeout,
+        )
+    except FileNotFoundError:
+        return _skip(check, f"tool not found: {cmd[0]}")
+    except subprocess.TimeoutExpired:
+        # subprocess.run kills the child on expiry before raising.
+        return CheckResult(
+            check=check, ran=True, passed=None, command=command_str,
+            exit_code=None, summary="timeout",
+        )
+    output = _tail(proc.stdout.strip() or proc.stderr.strip())
+    return CheckResult(
+        check=check, ran=True, passed=proc.returncode == 0,
+        command=command_str, exit_code=proc.returncode, summary=output,
+    )
+
+
+# ─── Applicability detection ────────────────────────────────────────────
+
+
+def _suffixes(changed_files: list[str] | None) -> set[str]:
+    return {Path(f).suffix for f in changed_files or []}
+
+
+def _has_python(project_dir: Path, changed_files: list[str] | None) -> bool:
+    if ".py" in _suffixes(changed_files):
+        return True
+    if (project_dir / "pyproject.toml").is_file():
+        return True
+    return any(project_dir.glob("*.py")) or any(project_dir.glob("*/*.py"))
+
+
+def _package_json_script(project_dir: Path, script: str) -> bool:
+    pkg = project_dir / "package.json"
+    if not pkg.is_file():
+        return False
+    try:
+        scripts = json.loads(pkg.read_text(encoding="utf-8")).get("scripts", {})
+    except (json.JSONDecodeError, OSError):
+        return False
+    value = str(scripts.get(script, ""))
+    return bool(value) and "no test specified" not in value
+
+
+def _mypy_configured(project_dir: Path) -> bool:
+    if (project_dir / "mypy.ini").is_file():
+        return True
+    for name in ("pyproject.toml", "setup.cfg"):
+        path = project_dir / name
+        try:
+            text = path.read_text(encoding="utf-8") if path.is_file() else ""
+        except OSError:
+            text = ""
+        if "[tool.mypy]" in text or "[mypy]" in text:
+            return True
+    return False
+
+
+# ─── Individual checks ──────────────────────────────────────────────────
+
+
+def _check_lint(
+    project_dir: Path, changed: list[str] | None,
+    test_command: str | None, timeout: int,
+) -> CheckResult:
+    if _has_python(project_dir, changed) and shutil.which("ruff"):
+        return _run("lint", ["ruff", "check", "."], project_dir, timeout)
+    if _package_json_script(project_dir, "lint"):
+        return _run(
+            "lint", ["npm", "run", "--silent", "lint"], project_dir, timeout,
+        )
+    pint = project_dir / "vendor" / "bin" / "pint"
+    if pint.is_file():
+        return _run("lint", [str(pint), "--test"], project_dir, timeout)
+    return _skip("lint", "no lint tooling detected (ruff/eslint/pint)")
+
+
+def _check_typecheck(
+    project_dir: Path, changed: list[str] | None,
+    test_command: str | None, timeout: int,
+) -> CheckResult:
+    if _mypy_configured(project_dir) and shutil.which("mypy"):
+        return _run("typecheck", ["mypy", "."], project_dir, timeout)
+    if (project_dir / "tsconfig.json").is_file():
+        local_tsc = project_dir / "node_modules" / ".bin" / "tsc"
+        if local_tsc.is_file():
+            return _run(
+                "typecheck", [str(local_tsc), "--noEmit"], project_dir, timeout,
+            )
+        if shutil.which("tsc"):
+            return _run("typecheck", ["tsc", "--noEmit"], project_dir, timeout)
+        return _skip("typecheck", "tsconfig.json present but tsc not installed")
+    return _skip("typecheck", "no typecheck configuration detected")
+
+
+def _check_tests(
+    project_dir: Path, changed: list[str] | None,
+    test_command: str | None, timeout: int,
+) -> CheckResult:
+    if test_command:
+        return _run("tests", shlex.split(test_command), project_dir, timeout)
+    if _has_python(project_dir, changed) and shutil.which("pytest"):
+        return _run("tests", ["pytest", "-q"], project_dir, timeout)
+    if _package_json_script(project_dir, "test"):
+        return _run(
+            "tests", ["npm", "test", "--silent"], project_dir, timeout,
+        )
+    return _skip("tests", "no test runner detected (pytest/npm test)")
+
+
+def _junit_result(junit: Path) -> CheckResult:
+    try:
+        text = junit.read_text(encoding="utf-8")
+    except OSError:
+        text = ""
+    failures = re.search(r'failures="(\d+)"', text)
+    errors = re.search(r'errors="(\d+)"', text)
+    if failures is None and errors is None:
+        return CheckResult(
+            check="coverage", ran=True, passed=None,
+            command=f"parse:{junit.name}", exit_code=None,
+            summary="junit.xml present but unparseable",
+            details_path=str(junit),
+        )
+    failed = sum(int(m.group(1)) for m in (failures, errors) if m)
+    return CheckResult(
+        check="coverage", ran=True, passed=failed == 0,
+        command=f"parse:{junit.name}", exit_code=None,
+        summary=f"junit: {failed} failures/errors", details_path=str(junit),
+    )
+
+
+def _check_coverage(
+    project_dir: Path, changed: list[str] | None,
+    test_command: str | None, timeout: int,
+) -> CheckResult:
+    coverage_xml = project_dir / "coverage.xml"
+    if coverage_xml.is_file():
+        percent = coverage_percent_from_xml(coverage_xml)
+        if percent is None:
+            return CheckResult(
+                check="coverage", ran=True, passed=None,
+                command="parse:coverage.xml", exit_code=None,
+                summary="coverage.xml present but unparseable",
+                details_path=str(coverage_xml),
+            )
+        return CheckResult(
+            check="coverage", ran=True,
+            passed=percent >= COVERAGE_THRESHOLD,
+            command="parse:coverage.xml", exit_code=None,
+            summary=(
+                f"coverage {percent:.1f}% "
+                f"(threshold {COVERAGE_THRESHOLD:.0f}%)"
+            ),
+            details_path=str(coverage_xml),
+        )
+    junit = project_dir / "junit.xml"
+    if junit.is_file():
+        return _junit_result(junit)
+    return _skip("coverage", "no coverage.xml or junit.xml on disk")
+
+
+def _grep_file(path: Path) -> list[str]:
+    try:
+        lines = path.read_text(encoding="utf-8", errors="ignore").splitlines()
+    except OSError:
+        return []
+    hits = []
+    for lineno, line in enumerate(lines, start=1):
+        for name, pattern in _SECURITY_PATTERNS:
+            if pattern.search(line):
+                hits.append(f"{path}:{lineno} [{name}]")
+    return hits
+
+
+def _check_security_grep(
+    project_dir: Path, changed: list[str] | None,
+    test_command: str | None, timeout: int,
+) -> CheckResult:
+    if not changed:
+        return _skip("security-grep", "no changed files provided")
+    hits: list[str] = []
+    for name in changed:
+        path = Path(name)
+        if not path.is_absolute():
+            path = project_dir / name
+        if path.is_file():
+            hits.extend(_grep_file(path))
+    summary = (
+        "no security patterns matched"
+        if not hits
+        else "; ".join(hits[:_MAX_GREP_HITS])
+    )
+    return CheckResult(
+        check="security-grep", ran=True, passed=not hits,
+        command=f"security-grep over {len(changed)} changed file(s)",
+        exit_code=None, summary=_tail(summary),
+    )
+
+
+def _check_spellcheck(
+    project_dir: Path, changed: list[str] | None,
+    test_command: str | None, timeout: int,
+) -> CheckResult:
+    if not shutil.which("codespell"):
+        return _skip("spellcheck", "codespell not installed")
+    md_files = [f for f in changed or [] if f.endswith(".md")]
+    if not md_files:
+        return _skip("spellcheck", "no changed .md files")
+    return _run("spellcheck", ["codespell", *md_files], project_dir, timeout)
+
+
+_CHECK_DISPATCH = {
+    "lint": _check_lint,
+    "typecheck": _check_typecheck,
+    "tests": _check_tests,
+    "coverage": _check_coverage,
+    "security-grep": _check_security_grep,
+    "spellcheck": _check_spellcheck,
+}
+
+
+# ─── Public API ─────────────────────────────────────────────────────────
+
+
+def _derive_overall(results: list[CheckResult]) -> str:
+    """fail if any ran check failed; insufficient if nothing concluded."""
+    if any(r.ran and r.passed is False for r in results):
+        return "fail"
+    if any(r.ran and r.passed is True for r in results):
+        return "pass"
+    return "insufficient-evidence"
+
+
+def run_evidence_checks(
+    project_dir: Path,
+    changed_files: list[str] | None = None,
+    checks: list[str] | None = None,
+    test_command: str | None = None,
+    timeout: int = TIMEOUT_SECONDS,
+) -> EvidenceReport:
+    """Run the selected checks and derive the overall evidence status."""
+    project_dir = Path(project_dir)
+    selected = list(checks) if checks else list(ALL_CHECKS)
+    results: list[CheckResult] = []
+    for name in selected:
+        check_fn = _CHECK_DISPATCH.get(name)
+        if check_fn is None:
+            results.append(_skip(name, f"unknown check: {name}"))
+            continue
+        results.append(check_fn(project_dir, changed_files, test_command, timeout))
+    return EvidenceReport(
+        project_dir=str(project_dir),
+        overall=_derive_overall(results),
+        results=results,
+    )
+
+
+# ─── CLI ────────────────────────────────────────────────────────────────
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="python -m core.governance.evidence_checks",
+        description="Run executable evidence checks for the Quality Gate.",
+    )
+    parser.add_argument("project_dir", type=Path)
+    parser.add_argument("--checks", help="comma-separated subset of checks")
+    parser.add_argument("--test-command", help="override for the tests check")
+    parser.add_argument("--changed-files", help="comma-separated changed files")
+    parser.add_argument("--json", action="store_true", help="emit JSON report")
+    return parser
+
+
+def _csv(value: str | None) -> list[str] | None:
+    if not value:
+        return None
+    return [item.strip() for item in value.split(",") if item.strip()]
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+    report = run_evidence_checks(
+        project_dir=args.project_dir,
+        changed_files=_csv(args.changed_files),
+        checks=_csv(args.checks),
+        test_command=args.test_command,
+    )
+    if args.json:
+        print(json.dumps(report.to_dict(), indent=2))
+    else:
+        for result in report.results:
+            state = (
+                "SKIP" if not result.ran
+                else {True: "PASS", False: "FAIL", None: "N/A"}[result.passed]
+            )
+            print(f"[{state}] {result.check}: {result.summary}")
+        print(f"overall: {report.overall}")
+    return {"pass": 0, "fail": 1}.get(report.overall, 2)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/core/governance/meta_tag_check.py

@@ -61,3 +61,39 @@ def _has_bypass_marker(text: str, markers: tuple[str, ...]) -> bool:
 
 def _is_trivial_length(text: str) -> bool:
     return len(text.split()) < _TRIVIAL_WORD_THRESHOLD
+
+
+# ─── kb=N reconciliation (structural honesty PR-2) ──────────────────────
+
+_KB_REPORTED_RE: re.Pattern[str] = re.compile(
+    r"\[arka:meta\][^\n]*?\bkb=(\d+)", re.IGNORECASE
+)
+
+
+def parse_reported_kb(response_text: str) -> int | None:
+    """Extract the self-reported kb=N from a closing [arka:meta] line.
+
+    Returns None when the tag or the kb field is absent.
+    """
+    match = _KB_REPORTED_RE.search(response_text or "")
+    return int(match.group(1)) if match else None
+
+
+def reconcile_kb_count(
+    reported: int | None, injected: int | None
+) -> dict[str, int | bool | None]:
+    """Reconcile the self-reported kb=N against the Synapse-injected count.
+
+    ``injected`` is ground truth (written by synapse-bridge from the L2.5
+    layer result); ``reported`` is the model's claim. Warn-only contract:
+    ``kb_inflated`` is True only when BOTH values are known and the claim
+    exceeds reality. Unknown on either side never flags inflation.
+    """
+    inflated = (
+        reported is not None and injected is not None and reported > injected
+    )
+    return {
+        "kb_reported": reported,
+        "kb_injected": injected,
+        "kb_inflated": inflated,
+    }

package/core/governance/qg_verdict.py

@@ -0,0 +1,78 @@
+"""Structured Quality Gate verdict schema (PR-4 evidence Quality Gate).
+
+``QGVerdict`` is the contract every QG reviewer subagent must return.
+The verdict is INTERPRETATION of an ``EvidenceReport`` from
+``core.governance.evidence_checks`` — never narrative alone:
+
+  - ``evidence_report.overall == "fail"`` forces ``verdict=REJECTED``;
+    a persona cannot override failing evidence with prose.
+  - ``APPROVED`` requires ``overall == "pass"``, or
+    ``insufficient-evidence`` with an explicit justification in notes.
+
+``QG_VERDICT_JSON_SCHEMA`` is the dict to pass as the structured-output
+schema when dispatching reviewers via the Agent tool.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class QGBlocker(BaseModel):
+    """One concrete issue that blocks approval."""
+
+    check: str = Field(description="Evidence check or rubric area that failed")
+    detail: str = Field(description="What exactly is wrong, with evidence")
+    file: str | None = Field(
+        default=None, description="File (and line if known) of the issue"
+    )
+
+
+class QGEvidenceSummary(BaseModel):
+    """Embedded summary of the EvidenceReport the reviewer interpreted."""
+
+    overall: Literal["pass", "fail", "insufficient-evidence"]
+    checks_ran: list[str] = Field(default_factory=list)
+    checks_failed: list[str] = Field(default_factory=list)
+    checks_skipped: list[str] = Field(default_factory=list)
+
+
+class QGVerdict(BaseModel):
+    """Binary Quality Gate verdict derived from executable evidence."""
+
+    verdict: Literal["APPROVED", "REJECTED"]
+    evidence_report: QGEvidenceSummary
+    blockers: list[QGBlocker] = Field(default_factory=list)
+    reviewer: str = Field(description="Reviewer id, e.g. tech-director-francisca")
+    model_used: str = Field(description="Model tier the review ran on")
+    notes: str = Field(
+        default="",
+        description=(
+            "Interpretation notes; MUST justify approval explicitly when "
+            "evidence is insufficient"
+        ),
+    )
+
+    @model_validator(mode="after")
+    def enforce_evidence_floor(self) -> "QGVerdict":
+        """APPROVED cannot coexist with failing evidence (evidence floor)."""
+        if self.verdict == "APPROVED" and self.evidence_report.overall == "fail":
+            raise ValueError(
+                "APPROVED verdict with evidence overall='fail' — a persona "
+                "cannot override failing evidence with narrative"
+            )
+        if (
+            self.verdict == "APPROVED"
+            and self.evidence_report.overall == "insufficient-evidence"
+            and not self.notes.strip()
+        ):
+            raise ValueError(
+                "APPROVED on insufficient-evidence requires explicit "
+                "justification in notes"
+            )
+        return self
+
+
+QG_VERDICT_JSON_SCHEMA: dict = QGVerdict.model_json_schema()

package/core/governance/review_workflow.py

@@ -54,6 +54,7 @@ class ReviewerVote:
     comments: str = ""
     flagged_rules: list[str] = field(default_factory=list)
     voted_at: str = ""
+    evidence_overall: str | None = None  # "pass" | "fail" | "insufficient-evidence"
 
 
 @dataclass
@@ -209,6 +210,7 @@ class ReviewWorkflowEngine:
         opinion: ReviewerOpinion,
         comments: str = "",
         flagged_rules: list[str] | None = None,
+        evidence_overall: str | None = None,
     ) -> bool:
         """Record a reviewer's vote.
 
@@ -218,9 +220,15 @@ class ReviewWorkflowEngine:
             opinion: Their vote
             comments: Optional comments
             flagged_rules: Constitution rules that were violated
+            evidence_overall: EvidenceReport.overall the vote interprets
+                ("pass" | "fail" | "insufficient-evidence")
 
         Returns:
             True if vote recorded successfully
+
+        Raises:
+            ValueError: APPROVE vote against evidence_overall == "fail" —
+                a reviewer cannot approve over failing executable evidence.
         """
         workflow = self._workflows.get(workflow_id)
         if not workflow:
@@ -229,12 +237,19 @@ class ReviewWorkflowEngine:
         if workflow.phase not in (ReviewPhase.REVIEW, ReviewPhase.DELIBERATION):
             return False
 
+        if opinion == ReviewerOpinion.APPROVE and evidence_overall == "fail":
+            raise ValueError(
+                f"reviewer {reviewer} voted APPROVE with evidence "
+                "overall='fail' — evidence floor violated"
+            )
+
         vote = ReviewerVote(
             reviewer=reviewer,
             opinion=opinion,
             comments=comments,
             flagged_rules=flagged_rules or [],
             voted_at=datetime.now(timezone.utc).isoformat(),
+            evidence_overall=evidence_overall,
         )
         workflow.votes.append(vote)
         return True
@@ -276,17 +291,35 @@ class ReviewWorkflowEngine:
         self._announce_phase_complete(ReviewPhase.DELIBERATION, result)
         return result
 
-    def reach_verdict(self, workflow_id: str, verdict: Verdict, feedback: str = "") -> PhaseResult:
+    def reach_verdict(
+        self,
+        workflow_id: str,
+        verdict: Verdict,
+        feedback: str = "",
+        evidence_overall: str | None = None,
+    ) -> PhaseResult:
         """Record the final verdict.
 
         Args:
             workflow_id: ID of the workflow
             verdict: Final verdict
             feedback: Feedback for the submitter
+            evidence_overall: EvidenceReport.overall the verdict derives
+                from ("pass" | "fail" | "insufficient-evidence")
 
         Returns:
             PhaseResult with verdict outcome
+
+        Raises:
+            ValueError: APPROVED with evidence_overall == "fail" — the
+                bookkeeping enforces the evidence floor.
         """
+        if verdict == Verdict.APPROVED and evidence_overall == "fail":
+            raise ValueError(
+                "APPROVED verdict with evidence overall='fail' — evidence "
+                "floor violated; failing checks force REJECTED"
+            )
+
         workflow = self._workflows.get(workflow_id)
         if not workflow:
             return PhaseResult(

package/core/governance/skill_proposer.py

@@ -15,7 +15,8 @@ from datetime import datetime, timezone
 from pathlib import Path
 
 _COMPLETION_PATTERNS: tuple[re.Pattern[str], ...] = (
-    re.compile(r"\[arka:phase:13\]", re.IGNORECASE),
+    re.compile(r"\[arka:gate:4\]", re.IGNORECASE),
+    re.compile(r"\[arka:phase:13\]", re.IGNORECASE),  # legacy, v4.1 window
     re.compile(r"\barc complete\b", re.IGNORECASE),
 )
 

package/core/hooks/__init__.py

@@ -0,0 +1,12 @@
+"""Consolidated hook entrypoints (PR-6 v4.1.0 — hook hygiene).
+
+One python process per hook event. Each module exposes
+``main(stdin_json) -> int`` and is invoked by the thin bash wrappers in
+``config/hooks/*.sh`` as ``python3 -m core.hooks.<event>``.
+
+CRITICAL degradation contract: ambient python3 lacks PyYAML on some
+machines. This package and every entrypoint import ONLY stdlib at module
+level; anything that can pull yaml (core.workflow.*, core.governance.*,
+core.synapse engine, ...) is imported lazily inside try/except so
+stdlib-only paths (budget check, gotchas, nudges) still run.
+"""