agentic-project-kit 1.0.1__py3-none-any.whl

agentic_project_kit/mutation_lock_audit.py

@@ -0,0 +1,421 @@
+from __future__ import annotations
+
+import re
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any, Mapping
+
+LOCK_MARKER = "workspace_mutation_lock"
+
+@dataclass(frozen=True)
+class MutationLockFindingClassification:
+    """Human-facing classification for mutation-lock audit findings."""
+
+    kind: str
+    counts_as_blocking: bool
+    rationale: str
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "kind": self.kind,
+            "counts_as_blocking": self.counts_as_blocking,
+            "rationale": self.rationale,
+        }
+
+
+MODULE_LEVEL_STRING_TABLE_PATHS = frozenset(
+    {
+        "src/agentic_project_kit/command_manifest.py",
+        "src/agentic_project_kit/work_order_validator.py",
+        "src/agentic_project_kit/command_inbox_check.py",
+        "src/agentic_project_kit/composite_short_circuit.py",
+        "src/agentic_project_kit/llm_execution_context.py",
+    }
+)
+
+METADATA_LITERAL_SYMBOLS = frozenset(
+    {
+        "_category_for",
+        "_composition_level_for",
+        "_task_tags",
+        "_button",
+        "_actions",
+    }
+)
+
+GENERATED_REFERENCE_SYMBOLS = frozenset(
+    {
+        "write_reference",
+        "render_markdown",
+        "commands_render_md_command",
+        "direction_render_command",
+    }
+)
+
+REPORT_WRITER_SYMBOL_HINTS = (
+    "write_",
+    "_write_",
+    "report",
+    "evidence",
+    "summary",
+    "log",
+    "finalize",
+)
+
+RUNTIME_MUTATION_SYMBOL_HINTS = (
+    "branch",
+    "commit",
+    "push",
+    "merge",
+    "restore",
+    "sync",
+    "pr_",
+    "release",
+)
+
+CORE_RUNTIME_MUTATOR_SYMBOLS = frozenset(
+    {
+        "admin_refresh_pr",
+        "_admin_refresh_pr_unlocked",
+        "branch_create",
+        "branch_delete",
+        "branch_switch",
+        "commit_paths",
+        "_commit_paths_unlocked",
+        "pr_create",
+        "_pr_create_unlocked",
+        "pr_merge_safe",
+        "_pr_merge_safe_unlocked",
+        "pull_current",
+        "push_current",
+        "_push_current_unlocked",
+    }
+)
+
+
+def _finding_value(finding: object, key: str) -> str:
+    if isinstance(finding, Mapping):
+        return str(finding.get(key) or "")
+    return str(getattr(finding, key, "") or "")
+
+
+def _is_enforced_core_runtime_path(path: str) -> bool:
+    return path == "src/agentic_project_kit/transfer_repo_actions.py"
+
+
+def classify_mutation_lock_finding(finding: object) -> MutationLockFindingClassification:
+    """Classify a mutation-lock audit finding without changing audit behavior."""
+
+    path = _finding_value(finding, "path")
+    symbol = _finding_value(finding, "symbol")
+    category = _finding_value(finding, "category")
+    reason = _finding_value(finding, "reason")
+
+    symbol_l = symbol.lower()
+
+    if symbol == "<module>" and path in MODULE_LEVEL_STRING_TABLE_PATHS:
+        return MutationLockFindingClassification(
+            kind="metadata_literal",
+            counts_as_blocking=False,
+            rationale="module-level command metadata is audit vocabulary, not executed mutation",
+        )
+
+    if symbol in METADATA_LITERAL_SYMBOLS:
+        return MutationLockFindingClassification(
+            kind="metadata_literal",
+            counts_as_blocking=False,
+            rationale="symbol describes command/category metadata rather than executing a mutation",
+        )
+
+    if symbol in GENERATED_REFERENCE_SYMBOLS:
+        return MutationLockFindingClassification(
+            kind="generated_reference",
+            counts_as_blocking=False,
+            rationale="symbol writes generated command/reference material, not a workspace mutation target",
+        )
+
+    if category == "C" or "filesystem_" in reason:
+        if any(hint in symbol_l for hint in REPORT_WRITER_SYMBOL_HINTS):
+            return MutationLockFindingClassification(
+                kind="report_writer",
+                counts_as_blocking=False,
+                rationale="filesystem mutation writes report, evidence, summary, or log output",
+            )
+        return MutationLockFindingClassification(
+            kind="filesystem_side_effect",
+            counts_as_blocking=False,
+            rationale="filesystem side-effect remains visible for review; LC3 hard blocking is limited to runtime git/github mutators",
+        )
+
+    if category in {"A", "B"} or "git_" in reason or "github_" in reason:
+        if _is_enforced_core_runtime_path(path) and symbol in CORE_RUNTIME_MUTATOR_SYMBOLS:
+            return MutationLockFindingClassification(
+                kind="runtime_mutation",
+                counts_as_blocking=True,
+                rationale="finding is in a runtime git/github mutation path",
+            )
+        if any(hint in symbol_l for hint in RUNTIME_MUTATION_SYMBOL_HINTS):
+            return MutationLockFindingClassification(
+                kind="delegated_runtime_reference",
+                counts_as_blocking=False,
+                rationale="runtime-like command text is outside the LC3 enforced core mutator body or delegates to locked core mutators",
+            )
+
+    return MutationLockFindingClassification(
+        kind="review_visible_reference",
+        counts_as_blocking=False,
+        rationale="finding remains visible for review but does not match an enforced LC3 runtime mutator",
+    )
+
+ENFORCED_CORE_MUTATION_LOCK_PATHS = (
+    "transfer_repo_actions.py",
+    "transfer_pr_create_flow.py",
+    "transfer_pr_merge_flow.py",
+)
+
+
+@dataclass(frozen=True)
+class MutationLockFinding:
+    category: str
+    symbol: str
+    path: str
+    line: int
+    reason: str
+    required_lock: str = "workspace_mutation_lock"
+
+
+@dataclass(frozen=True)
+class MutationLockCoverageAuditResult:
+    kind: str
+    findings: list[MutationLockFinding]
+
+    @property
+    def blocking_findings(self) -> list[MutationLockFinding]:
+        return [
+            finding
+            for finding in self.findings
+            if classify_mutation_lock_finding(finding).counts_as_blocking
+        ]
+
+    @property
+    def non_blocking_findings(self) -> list[MutationLockFinding]:
+        return [
+            finding
+            for finding in self.findings
+            if not classify_mutation_lock_finding(finding).counts_as_blocking
+        ]
+
+    @property
+    def result_status(self) -> str:
+        return "BLOCK" if self.blocking_findings else "PASS"
+
+    @property
+    def returncode(self) -> int:
+        return 0 if self.result_status == "PASS" else 1
+
+    def to_dict(self) -> dict[str, Any]:
+        findings = [_finding_to_dict(finding) for finding in self.findings]
+        blocking_findings = [
+            finding
+            for finding in findings
+            if finding["classification"]["counts_as_blocking"]
+        ]
+        non_blocking_findings = [
+            finding
+            for finding in findings
+            if not finding["classification"]["counts_as_blocking"]
+        ]
+        return {
+            "kind": self.kind,
+            "result_status": self.result_status,
+            "finding_count": len(findings),
+            "blocking_finding_count": len(blocking_findings),
+            "non_blocking_finding_count": len(non_blocking_findings),
+            "classification_summary": _classification_summary(self.findings),
+            "findings": findings,
+            "blocking_findings": blocking_findings,
+            "non_blocking_findings": non_blocking_findings,
+        }
+
+
+def _finding_to_dict(finding: MutationLockFinding) -> dict[str, Any]:
+    classification = classify_mutation_lock_finding(finding)
+    data = asdict(finding)
+    data["classification"] = classification.to_dict()
+    return data
+
+
+def _classification_summary(findings: list[MutationLockFinding]) -> dict[str, dict[str, object]]:
+    summary: dict[str, dict[str, object]] = {}
+    for finding in findings:
+        classification = classify_mutation_lock_finding(finding)
+        entry = summary.setdefault(
+            classification.kind,
+            {
+                "count": 0,
+                "counts_as_blocking": classification.counts_as_blocking,
+            },
+        )
+        entry["count"] = int(entry["count"]) + 1
+    return dict(sorted(summary.items()))
+
+
+_MUTATION_PATTERNS: tuple[tuple[str, re.Pattern[str]], ...] = (
+    ("git_branch_mutation", re.compile(r"\bgit\s+(?:switch|checkout|branch)\b|[\"']git[\"']\s*,\s*[\"'](?:switch|checkout|branch)[\"']|branch_create|branch-switch")),
+    ("git_history_mutation", re.compile(r"\bgit\s+(?:commit|merge|reset|restore|push)\b|[\"']git[\"']\s*,\s*[\"'](?:commit|merge|reset|restore|push)[\"']|pr-create-complete|pr-complete")),
+    ("filesystem_mutation", re.compile(r"\.(?:write_text|unlink|replace|rename)\(|(?:mkdir|rmtree)\(")),
+    ("github_mutation", re.compile(r"\bgh\s+pr\s+(?:create|merge|close|edit)\b")),
+)
+
+_LOCK_MARKERS = (
+    "workspace_lock",
+    "acquire_workspace_lock",
+    "WorkspaceLock",
+    "mutation_lock",
+    "with_workspace_lock",
+)
+
+
+def _nearest_symbol(lines: list[str], index: int) -> str:
+    for line_no in range(index, -1, -1):
+        line = lines[line_no].strip()
+        match = re.match(r"def\s+([a-zA-Z_][a-zA-Z0-9_]*)\(", line)
+        if match:
+            return match.group(1)
+        match = re.match(r"class\s+([a-zA-Z_][a-zA-Z0-9_]*)\b", line)
+        if match:
+            return match.group(1)
+    return "<module>"
+
+
+def _function_body(lines: list[str], symbol: str) -> str:
+    start: int | None = None
+    for line_no, line in enumerate(lines):
+        if re.match(rf"def\s+{re.escape(symbol)}\(", line):
+            start = line_no
+            break
+    if start is None:
+        return ""
+    end = len(lines)
+    for line_no in range(start + 1, len(lines)):
+        if re.match(r"def\s+[a-zA-Z_][a-zA-Z0-9_]*\(", lines[line_no]):
+            end = line_no
+            break
+    return "\n".join(lines[start:end])
+
+
+def _symbol_has_lock_marker(lines: list[str], symbol: str) -> bool:
+    body = _function_body(lines, symbol)
+    if any(marker in body for marker in _LOCK_MARKERS):
+        return True
+    if symbol.startswith("_") and symbol.endswith("_unlocked"):
+        wrapper_symbol = symbol.removeprefix("_").removesuffix("_unlocked")
+        wrapper_body = _function_body(lines, wrapper_symbol)
+        return any(marker in wrapper_body for marker in _LOCK_MARKERS)
+    return False
+
+
+def _has_lock_marker_nearby(lines: list[str], index: int) -> bool:
+    start = max(0, index - 12)
+    end = min(len(lines), index + 8)
+    window = "\n".join(lines[start:end])
+    return any(marker in window for marker in _LOCK_MARKERS)
+
+
+def audit_mutation_lock_coverage(root: Path | str = ".") -> MutationLockCoverageAuditResult:
+    repo_root = Path(root)
+    src_root = repo_root / "src" / "agentic_project_kit"
+    findings: list[MutationLockFinding] = []
+
+    if not src_root.exists():
+        return MutationLockCoverageAuditResult(
+            kind="mutation_lock_coverage_audit",
+            findings=[
+                MutationLockFinding(
+                    category="A",
+                    symbol="src_root_missing",
+                    path=str(src_root),
+                    line=0,
+                    reason="agentic_project_kit source root is missing",
+                )
+            ],
+        )
+
+    for path in sorted(src_root.rglob("*.py")):
+        rel = path.relative_to(repo_root).as_posix()
+        if path.name == "mutation_lock_audit.py":
+            continue
+
+        lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
+        for index, line in enumerate(lines):
+            stripped = line.strip()
+            if stripped.startswith("#"):
+                continue
+
+            for category_name, pattern in _MUTATION_PATTERNS:
+                if not pattern.search(line):
+                    continue
+
+                if _has_lock_marker_nearby(lines, index):
+                    continue
+
+                symbol = _nearest_symbol(lines, index)
+                if _symbol_has_lock_marker(lines, symbol):
+                    continue
+                category = {
+                    "git_branch_mutation": "A",
+                    "git_history_mutation": "A",
+                    "github_mutation": "B",
+                    "filesystem_mutation": "C",
+                }[category_name]
+
+                findings.append(
+                    MutationLockFinding(
+                        category=category,
+                        symbol=symbol,
+                        path=rel,
+                        line=index + 1,
+                        reason=f"{category_name} without nearby workspace mutation lock marker",
+                    )
+                )
+
+    return MutationLockCoverageAuditResult(
+        kind="mutation_lock_coverage_audit",
+        findings=findings,
+    )
+
+
+def render_mutation_lock_coverage_audit(result: MutationLockCoverageAuditResult) -> str:
+    lines = [
+        "MUTATION_LOCK_COVERAGE_AUDIT",
+        f"RESULT: {result.result_status}",
+        f"FINDINGS: {len(result.findings)}",
+        f"BLOCKING_FINDINGS: {len(result.blocking_findings)}",
+        f"NON_BLOCKING_FINDINGS: {len(result.non_blocking_findings)}",
+    ]
+    if result.findings:
+        lines.append("CLASSIFICATION_SUMMARY:")
+        for kind, summary in _classification_summary(result.findings).items():
+            disposition = "BLOCK" if summary["counts_as_blocking"] else "non-blocking"
+            lines.append(f"- {kind}: {summary['count']} ({disposition})")
+
+    if result.blocking_findings:
+        lines.append("BLOCKING:")
+    for finding in result.blocking_findings:
+        classification = classify_mutation_lock_finding(finding)
+        lines.append(
+            f"- [{finding.category}] {finding.symbol} {finding.path}:{finding.line} "
+            f"— classification={classification.kind} disposition=BLOCK "
+            f"— {finding.reason} — {classification.rationale}"
+        )
+
+    if result.non_blocking_findings:
+        lines.append("NON_BLOCKING:")
+    for finding in result.non_blocking_findings:
+        classification = classify_mutation_lock_finding(finding)
+        lines.append(
+            f"- [{finding.category}] {finding.symbol} {finding.path}:{finding.line} "
+            f"— classification={classification.kind} disposition=non-blocking "
+            f"— {finding.reason} — {classification.rationale}"
+        )
+    return "\n".join(lines) + "\n"

agentic_project_kit/next_turn_evidence.py

@@ -0,0 +1,253 @@
+from __future__ import annotations
+
+import argparse
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from agentic_project_kit.safe_push import safe_push
+
+from agentic_project_kit.next_turn_result import publish_local_evidence, render_summary
+
+
+@dataclass(frozen=True)
+class EvidencePublishPlan:
+    run_id: str
+    local_terminal_log: str
+    work_result: str
+    files_to_stage: tuple[str, ...]
+    commit_message: str
+    branch: str
+    push_command: str
+
+
+def _run_git(args: list[str], *, root: Path, check: bool = True) -> subprocess.CompletedProcess[str]:
+    completed = subprocess.run(
+        ["git", *args],
+        cwd=root,
+        text=True,
+        capture_output=True,
+        check=False,
+    )
+    if check and completed.returncode != 0:
+        raise RuntimeError(completed.stderr.strip() or completed.stdout.strip())
+    return completed
+
+
+def _git_stdout(args: list[str], *, root: Path) -> str:
+    return _run_git(args, root=root).stdout.strip()
+
+
+def current_branch(root: Path | str = ".") -> str:
+    return _git_stdout(["branch", "--show-current"], root=Path(root))
+
+
+def build_evidence_publish_plan(
+    *,
+    run_id: str,
+    local_terminal_log: str,
+    work_result: str,
+    root: Path | str = ".",
+) -> EvidencePublishPlan:
+    root_path = Path(root)
+    branch = current_branch(root_path)
+    files = (
+        f"docs/reports/terminal/{run_id}.log",
+        f"docs/reports/command_runs/{run_id}.json",
+        "docs/reports/command_runs/next-turn-latest.json",
+    )
+    return EvidencePublishPlan(
+        run_id=run_id,
+        local_terminal_log=local_terminal_log,
+        work_result=work_result,
+        files_to_stage=files,
+        commit_message=f"Record {run_id} evidence",
+        branch=branch,
+        push_command=f"git push -u origin {branch}",
+    )
+
+
+def publish_and_stage_evidence(
+    *,
+    run_id: str,
+    local_terminal_log: str,
+    work_result: str,
+    root: Path | str = ".",
+) -> EvidencePublishPlan:
+    root_path = Path(root)
+    result = publish_local_evidence(
+        run_id=run_id,
+        local_terminal_log=local_terminal_log,
+        work_result=work_result,  # type: ignore[arg-type]
+        root=root_path,
+    )
+    plan = build_evidence_publish_plan(
+        run_id=run_id,
+        local_terminal_log=local_terminal_log,
+        work_result=work_result,
+        root=root_path,
+    )
+    _run_git(["add", *plan.files_to_stage], root=root_path)
+    print(render_summary(result))
+    return plan
+
+
+
+@dataclass(frozen=True)
+class EvidenceFinalizeResult:
+    plan: EvidencePublishPlan
+    committed: bool
+    pushed: bool
+    already_clean: bool
+    commit_sha: str
+    message: str
+
+
+def has_staged_changes(root: Path | str = ".") -> bool:
+    completed = _run_git(["diff", "--cached", "--quiet"], root=Path(root), check=False)
+    return completed.returncode == 1
+
+
+def commit_and_push_evidence(
+    *,
+    plan: EvidencePublishPlan,
+    root: Path | str = ".",
+    push: bool = True,
+    required_branch: str = "",
+    allow_main: bool = False,
+) -> EvidenceFinalizeResult:
+    root_path = Path(root)
+
+    if not has_staged_changes(root_path):
+        return EvidenceFinalizeResult(
+            plan=plan,
+            committed=False,
+            pushed=False,
+            already_clean=True,
+            commit_sha="",
+            message="PASS_ALREADY_DONE: no staged evidence changes",
+        )
+
+    branch = current_branch(root_path)
+    if required_branch and branch != required_branch:
+        raise RuntimeError(f"current branch {branch!r} does not match required branch {required_branch!r}")
+    if branch == "main" and not allow_main:
+        raise RuntimeError("next-turn evidence refuses to commit on main without allow_main=True")
+    if not branch:
+        raise RuntimeError("next-turn evidence refuses to commit without a current branch")
+    if push:
+        push_preflight = safe_push(
+            root_path,
+            target_branch=plan.branch,
+            purpose="next-turn evidence publish branch",
+            dry_run=True,
+        )
+        if not push_preflight.ok:
+            raise RuntimeError("push preflight blocked next-turn evidence: " + "; ".join(push_preflight.reasons))
+
+    commit = _run_git(["commit", "-m", plan.commit_message], root=root_path, check=False)
+    if commit.returncode != 0:
+        combined = (commit.stderr + commit.stdout).strip()
+        if "nothing to commit" in combined or "no changes added to commit" in combined:
+            return EvidenceFinalizeResult(
+                plan=plan,
+                committed=False,
+                pushed=False,
+                already_clean=True,
+                commit_sha="",
+                message="PASS_ALREADY_DONE: nothing to commit",
+            )
+        raise RuntimeError(combined)
+
+    sha = _git_stdout(["rev-parse", "HEAD"], root=root_path)
+
+    pushed = False
+    if push:
+        push_result = safe_push(
+            root_path,
+            target_branch=plan.branch,
+            purpose="next-turn evidence publish branch",
+            set_upstream=True,
+        )
+        if not push_result.ok:
+            raise RuntimeError((push_result.stderr + push_result.stdout).strip())
+        pushed = True
+
+    return EvidenceFinalizeResult(
+        plan=plan,
+        committed=True,
+        pushed=pushed,
+        already_clean=False,
+        commit_sha=sha,
+        message="PASS: evidence committed" + (" and pushed" if pushed else ""),
+    )
+
+
+def render_finalize_result(result: EvidenceFinalizeResult) -> str:
+    lines = [
+        "NEXT_TURN_EVIDENCE_FINALIZE_RESULT",
+        f"run_id={result.plan.run_id}",
+        f"committed={str(result.committed).lower()}",
+        f"pushed={str(result.pushed).lower()}",
+        f"already_clean={str(result.already_clean).lower()}",
+        f"commit_sha={result.commit_sha}",
+        f"message={result.message}",
+        f"branch={result.plan.branch}",
+        "subresult=PASS",
+    ]
+    return "\n".join(lines)
+
+def render_plan(plan: EvidencePublishPlan) -> str:
+    lines = [
+        "NEXT_TURN_EVIDENCE_PUBLISH_PLAN",
+        f"run_id={plan.run_id}",
+        f"local_terminal_log={plan.local_terminal_log}",
+        f"work_result={plan.work_result}",
+        f"branch={plan.branch}",
+        f"commit_message={plan.commit_message}",
+        f"push_command={plan.push_command}",
+        "files_to_stage:",
+    ]
+    lines.extend(f"- {item}" for item in plan.files_to_stage)
+    lines.append("subresult=PASS")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="next-turn-evidence")
+    parser.add_argument("--run-id", required=True)
+    parser.add_argument("--local-terminal-log", required=True)
+    parser.add_argument("--work-result", required=True, choices=["PASS", "FAIL", "PENDING", "HARD_FAIL", "PASS_ALREADY_DONE", "NOOP"])
+    parser.add_argument("--plan-only", action="store_true")
+    parser.add_argument("--commit", action="store_true")
+    parser.add_argument("--no-push", action="store_true")
+    args = parser.parse_args()
+
+    if args.plan_only:
+        plan = build_evidence_publish_plan(
+            run_id=args.run_id,
+            local_terminal_log=args.local_terminal_log,
+            work_result=args.work_result,
+        )
+        print(render_plan(plan))
+        return 0
+
+    plan = publish_and_stage_evidence(
+        run_id=args.run_id,
+        local_terminal_log=args.local_terminal_log,
+        work_result=args.work_result,
+    )
+
+    if args.commit:
+        finalize_result = commit_and_push_evidence(
+            plan=plan,
+            push=not args.no_push,
+        )
+        print(render_finalize_result(finalize_result))
+    else:
+        print(render_plan(plan))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())