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

agentic_project_kit/gui_window_guard.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import importlib
+import os
+
+
+@dataclass(frozen=True)
+class WindowGuardResult:
+    ok: bool
+    tkinter_importable: bool
+    native_tkinter_importable: bool
+    message: str
+
+
+def check_window_launch_ready() -> WindowGuardResult:
+    try:
+        importlib.import_module("tkinter")
+        tkinter_importable = True
+    except Exception as exc:
+        return WindowGuardResult(False, False, False, f"tkinter import failed: {exc}")
+    try:
+        importlib.import_module("_tkinter")
+        native_importable = True
+    except Exception as exc:
+        return WindowGuardResult(False, tkinter_importable, False, f"native _tkinter import failed: {exc}")
+    if os.environ.get("AGENTIC_KIT_ALLOW_TK_WINDOW_SMOKE") != "1":
+        return WindowGuardResult(
+            False,
+            tkinter_importable,
+            native_importable,
+            "real Tk window smoke requires AGENTIC_KIT_ALLOW_TK_WINDOW_SMOKE=1",
+        )
+    return WindowGuardResult(True, tkinter_importable, native_importable, "window launch guard passed")
+
+
+def render_window_guard_result(result: WindowGuardResult) -> str:
+    status = "READY" if result.ok else "BLOCKED"
+    return "\n".join((
+        "GUI WINDOW GUARD",
+        f"window_launch_ready={str(result.ok).lower()}",
+        f"tkinter_importable={str(result.tkinter_importable).lower()}",
+        f"native_tkinter_importable={str(result.native_tkinter_importable).lower()}",
+        f"message={result.message}",
+        f"window_guard_status={status}",
+    ))

agentic_project_kit/handoff_freshness.py

@@ -0,0 +1,390 @@
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from agentic_project_kit.handoff_state import is_administrative_evidence_subject
+
+FRESHNESS_GUARD_FILES = [
+    "docs/STATUS.md",
+    ".agentic/handoff_state.yaml",
+    "docs/handoff/CURRENT_HANDOFF.md",
+]
+OPERATIONAL_FRESHNESS_FILES = [
+    "docs/STATUS.md",
+    "docs/handoff/CURRENT_HANDOFF.md",
+    "docs/handoff/START_NEW_CHAT_PROMPT.md",
+    "docs/handoff/NEXT_CHAT_BOOTSTRAP.md",
+]
+SUCCESSOR_HANDOFF_GLOBS = [
+    "*successor*handoff*.md",
+    "*successor*handoff*.yaml",
+    "*successor*handoff*.yml",
+]
+
+
+def assess_handoff_prompt_freshness(
+    data: dict[str, Any],
+    handoff_path: str | Path = ".agentic/handoff_state.yaml",
+    *,
+    current_head: str | None = None,
+    current_subject: str | None = None,
+    successor_prompt_text: str | None = None,
+    intended_successor_prompt_path: str | Path | None = None,
+) -> list[str]:
+    """Return warnings when a successor handoff prompt may be stale.
+
+    The guard is intentionally warning-based. A stale repository still needs to
+    render a repairable prompt; it must not silently present that prompt as
+    authoritative.
+    """
+
+    state_path = Path(handoff_path)
+    project_root = _project_root_for_handoff_path(state_path)
+    warnings: list[str] = []
+
+    for relative_path in FRESHNESS_GUARD_FILES:
+        if not (project_root / relative_path).exists():
+            warnings.append(f"required handoff freshness file missing: {relative_path}")
+
+    detected_head = _short_commit(current_head) if current_head else _git_short_head(project_root)
+    detected_subject = current_subject if current_subject is not None else _git_head_subject(project_root)
+    detected_message = (
+        current_subject
+        if current_subject is not None
+        else _git_head_message(project_root)
+    )
+    expected_commits = _expected_handoff_commits(data)
+    admin_refresh_head = bool(
+        detected_head
+        and expected_commits
+        and not _commit_matches(detected_head, expected_commits)
+        and (
+            is_administrative_evidence_subject(detected_subject)
+            or _is_administrative_merge_commit(
+                project_root,
+                detected_head,
+                detected_message,
+                expected_commits,
+            )
+        )
+    )
+    if (
+        detected_head
+        and expected_commits
+        and not _commit_matches(detected_head, expected_commits)
+        and not admin_refresh_head
+    ):
+        joined = ", ".join(expected_commits)
+        warnings.append(
+            "current git HEAD "
+            f"{detected_head} is not represented by handoff safe/admin state ({joined})"
+        )
+
+    successor_prompt_path = _latest_successor_prompt_path(data, project_root)
+    if successor_prompt_path is None:
+        warnings.append("no successor handoff prompt was found under docs/reports/terminal")
+        return warnings
+
+    if not successor_prompt_path.exists():
+        intended_path = _resolve_project_path(project_root, intended_successor_prompt_path)
+        if successor_prompt_text is None or intended_path != successor_prompt_path:
+            relative_prompt = _relative_to_project(successor_prompt_path, project_root)
+            warnings.append(f"latest successor handoff prompt is missing: {relative_prompt}")
+            return warnings
+
+    marker_commits = expected_commits if admin_refresh_head else ([detected_head] if detected_head else expected_commits)
+    if successor_prompt_text is None:
+        prompt_text = successor_prompt_path.read_text(encoding="utf-8")
+    else:
+        prompt_text = successor_prompt_text
+    if marker_commits and not any(commit and commit in prompt_text for commit in marker_commits):
+        relative_prompt = _relative_to_project(successor_prompt_path, project_root)
+        joined = ", ".join(marker_commits)
+        warnings.append(
+            "latest successor handoff prompt "
+            f"{relative_prompt} does not mention current handoff commit marker(s): {joined}"
+        )
+
+    warnings.extend(
+        _assess_operational_document_freshness(
+            project_root,
+            expected_commits,
+        )
+    )
+
+    return warnings
+
+
+
+def _assess_operational_document_freshness(
+    project_root: Path,
+    marker_commits: list[str],
+) -> list[str]:
+    """Return warnings when live operational docs do not mention current markers.
+
+    This intentionally reuses the existing handoff-freshness mechanism. It does
+    not introduce a new rule layer: STATUS, CURRENT_HANDOFF, chat bootstrap
+    prompts, and the active roadmap are human-facing projections of the
+    machine-readable handoff state and must mention at least one current
+    safe/admin commit marker when they exist. Stable authority sources such as
+    PROJECT_DIRECTION.yaml are intentionally excluded; they are required
+    context, not per-PR refresh projections.
+    """
+
+    markers = [marker for marker in marker_commits if marker]
+    if not markers:
+        return []
+
+    warnings: list[str] = []
+    for relative_path in OPERATIONAL_FRESHNESS_FILES:
+        path = project_root / relative_path
+        if not path.exists():
+            continue
+        content = path.read_text(encoding="utf-8", errors="replace")
+        if any(marker in content for marker in markers):
+            continue
+        joined = ", ".join(markers)
+        warnings.append(
+            f"operational handoff document {relative_path} does not mention "
+            f"current handoff commit marker(s): {joined}"
+        )
+    return warnings
+
+def render_freshness_guard(warnings: list[str]) -> str:
+    if not warnings:
+        return ""
+    lines = [
+        "## Handoff Freshness Guard",
+        "",
+        "WARNING: this successor handoff prompt may be stale.",
+        "Refresh `docs/STATUS.md`, `.agentic/handoff_state.yaml`, "
+        "`docs/handoff/CURRENT_HANDOFF.md`, and the successor prompt before treating "
+        "this prompt as authoritative.",
+        "",
+    ]
+    lines.extend(f"- {warning}" for warning in warnings)
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _short_commit(value: Any) -> str:
+    return str(value or "").strip()[:7]
+
+
+def _project_root_for_handoff_path(path: Path) -> Path:
+    if path.name == "handoff_state.yaml" and path.parent.name == ".agentic":
+        return path.parent.parent
+    return Path.cwd()
+
+
+def _resolve_project_path(project_root: Path, path: str | Path | None) -> Path | None:
+    if path is None:
+        return None
+    candidate = Path(path)
+    if candidate.is_absolute():
+        return candidate
+    return project_root / candidate
+
+
+def _git_short_head(project_root: Path) -> str:
+    try:
+        return subprocess.check_output(
+            ["git", "rev-parse", "--short", "HEAD"],
+            cwd=project_root,
+            stderr=subprocess.DEVNULL,
+            text=True,
+        ).strip()
+    except (OSError, subprocess.CalledProcessError):
+        return ""
+
+
+def _git_head_subject(project_root: Path) -> str:
+    try:
+        return subprocess.check_output(
+            ["git", "log", "-1", "--pretty=%s"],
+            cwd=project_root,
+            stderr=subprocess.DEVNULL,
+            text=True,
+        ).strip()
+    except (OSError, subprocess.CalledProcessError):
+        return ""
+
+
+def _git_head_message(project_root: Path) -> str:
+    try:
+        return subprocess.check_output(
+            ["git", "log", "-1", "--pretty=%B"],
+            cwd=project_root,
+            stderr=subprocess.DEVNULL,
+            text=True,
+        ).strip()
+    except (OSError, subprocess.CalledProcessError):
+        return ""
+
+
+def _git_commit_subject(project_root: Path, commit: str) -> str:
+    try:
+        return subprocess.check_output(
+            ["git", "log", "-1", "--pretty=%s", commit],
+            cwd=project_root,
+            stderr=subprocess.DEVNULL,
+            text=True,
+        ).strip()
+    except (OSError, subprocess.CalledProcessError):
+        return ""
+
+
+def _git_commit_message(project_root: Path, commit: str) -> str:
+    try:
+        return subprocess.check_output(
+            ["git", "log", "-1", "--pretty=%B", commit],
+            cwd=project_root,
+            stderr=subprocess.DEVNULL,
+            text=True,
+        ).strip()
+    except (OSError, subprocess.CalledProcessError):
+        return ""
+
+
+def _is_administrative_merge_message(message: str) -> bool:
+    lowered = message.lower()
+    if not lowered.startswith("merge pull request #"):
+        return False
+    administrative_terms = (
+        "handoff",
+        "successor",
+        "closeout",
+        "evidence",
+        "refresh",
+        "freshness",
+    )
+    return any(term in lowered for term in administrative_terms)
+
+
+def _git_parent_commits(project_root: Path, commit: str) -> list[str]:
+    try:
+        parents = subprocess.check_output(
+            ["git", "show", "-s", "--pretty=%P", commit],
+            cwd=project_root,
+            stderr=subprocess.DEVNULL,
+            text=True,
+        ).strip()
+    except (OSError, subprocess.CalledProcessError):
+        return []
+    return [_short_commit(parent) for parent in parents.split() if parent.strip()]
+
+
+def _is_administrative_merge_commit(
+    project_root: Path,
+    detected_head: str,
+    detected_message: str,
+    expected_commits: list[str],
+) -> bool:
+    """Return true for GitHub merge commits that only merge administrative handoff/evidence work.
+
+    A normal product merge must still trigger the freshness guard. Therefore the
+    check requires both a GitHub-style merge message and administrative wording
+    in the full merge message, plus a parent already represented by handoff
+    safe/admin state.
+    """
+
+    message = detected_message.lower()
+    if not _is_administrative_merge_message(message):
+        return False
+    parents = _git_parent_commits(project_root, detected_head)
+    if any(_commit_matches(parent, expected_commits) for parent in parents):
+        return True
+    return _has_expected_commit_in_first_parent_admin_chain(
+        project_root,
+        detected_head,
+        expected_commits,
+    )
+
+
+def _has_expected_commit_in_first_parent_admin_chain(
+    project_root: Path,
+    start_commit: str,
+    expected_commits: list[str],
+    *,
+    max_depth: int = 20,
+) -> bool:
+    """Accept bounded chains of administrative GitHub merge commits.
+
+    This prevents a loop where every administrative merge commit requires a new
+    handoff-state refresh. The walk is deliberately first-parent and bounded:
+    product merges still warn unless every merge on the path is itself
+    administrative and the chain reaches an already represented commit.
+    """
+
+    current = start_commit
+    for _ in range(max_depth):
+        parents = _git_parent_commits(project_root, current)
+        if not parents:
+            return False
+        first_parent = parents[0]
+        if _commit_matches(first_parent, expected_commits):
+            return True
+        subject = _git_commit_subject(project_root, first_parent)
+        message = _git_commit_message(project_root, first_parent)
+        if not _is_administrative_merge_message(message or subject):
+            return False
+        current = first_parent
+    return False
+
+
+def _expected_handoff_commits(data: dict[str, Any]) -> list[str]:
+    commits: list[str] = []
+    safe_state = data.get("safe_state", {})
+    if isinstance(safe_state, dict):
+        safe_commit = _short_commit(safe_state.get("commit"))
+        if safe_commit:
+            commits.append(safe_commit)
+    admin_state = data.get("administrative_evidence_state", {})
+    if isinstance(admin_state, dict):
+        admin_commit = _short_commit(admin_state.get("current_head"))
+        if admin_commit and admin_commit not in commits:
+            commits.append(admin_commit)
+    return commits
+
+
+def _commit_matches(candidate: str, expected: list[str]) -> bool:
+    candidate = _short_commit(candidate)
+    return any(
+        candidate.startswith(commit) or commit.startswith(candidate)
+        for commit in expected
+        if commit
+    )
+
+
+def _configured_successor_prompt_path(data: dict[str, Any], project_root: Path) -> Path | None:
+    handoff_maintenance = data.get("handoff_maintenance", {})
+    if isinstance(handoff_maintenance, dict):
+        configured = handoff_maintenance.get("latest_successor_prompt")
+        if configured:
+            return project_root / str(configured)
+    return None
+
+
+def _latest_successor_prompt_path(data: dict[str, Any], project_root: Path) -> Path | None:
+    configured = _configured_successor_prompt_path(data, project_root)
+    if configured is not None:
+        return configured
+    terminal_dir = project_root / "docs" / "reports" / "terminal"
+    if not terminal_dir.exists():
+        return None
+    candidates = sorted(
+        candidate
+        for pattern in SUCCESSOR_HANDOFF_GLOBS
+        for candidate in terminal_dir.glob(pattern)
+    )
+    if not candidates:
+        return None
+    return candidates[-1]
+
+
+def _relative_to_project(path: Path, project_root: Path) -> Path:
+    try:
+        return path.relative_to(project_root)
+    except ValueError:
+        return path

agentic_project_kit/handoff_prompt.py

@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+from typing import Any
+
+from agentic_project_kit.chat_bootloader import MANDATORY_BOOT_SOURCES
+from agentic_project_kit.handoff_state import active_rules
+
+MANDATORY_SUCCESSOR_CHAT_SOURCES = list(MANDATORY_BOOT_SOURCES) + [
+    "docs/TEST_GATES.md",
+    "relevant source files and tests for the requested slice",
+]
+
+COMMUNICATION_SHORTCUTS = [
+    "d/D: local block appears finished; verify evidence before treating it as success",
+    "f/F: failure reported; inspect or upload evidence before asking for pasted output",
+    "w/W: continue within the current governance and evidence rules",
+    "paste-output: manual paste only when repo-backed or local evidence is unavailable or unusable",
+    "stop: no further mutation or terminal instructions",
+]
+
+FORBIDDEN_PATTERNS = [
+    "mutating before reading the mandatory successor-chat sources",
+    "treating d as proof of success",
+    "asking for pasted output while usable local or remote evidence exists",
+    "using shell-only snippets as canonical cross-platform execution",
+    "using POSIX tools as correctness dependencies for portable workflows",
+    "printing REMOTE_EVIDENCE: PENDING in a final summary",
+    "adding handwritten legacy summary footers after the summary renderer",
+    "continuing product work after unresolved contract or evidence drift",
+]
+
+SUMMARY_VOCABULARY = [
+    "WORK RESULT: PASS|FAIL|PENDING|HARD-FAIL|NO-COMMAND",
+    "EVIDENCE RESULT: PASS|FAIL|PARTIAL|CHAT_ONLY|NOT_REQUIRED",
+    "OVERALL RESULT: PASS|FAIL|PENDING|HARD-FAIL|NO-COMMAND",
+    "REMOTE_EVIDENCE: PASS|FAIL|PARTIAL|NOT_REQUIRED",
+    "NEXT_CHAT_REPLY: p|f|paste-output|continue|stop",
+]
+
+
+def _bullet_lines(items: list[Any]) -> list[str]:
+    return [f"- {item}" for item in items]
+
+
+def _rule_texts(data: dict[str, Any]) -> list[str]:
+    return [f"`{rule.get('id')}`: {rule.get('text')}" for rule in active_rules(data)]
+
+
+def render_handoff_prompt(data: dict[str, Any]) -> str:
+    repo = data.get("repo", {})
+    safe_state = data.get("safe_state", {})
+    release = data.get("release", {})
+    admin_state = data.get("administrative_evidence_state", {})
+    if isinstance(data.get("open_items"), dict):
+        open_prs = data.get("open_items", {}).get("prs", [])
+    else:
+        open_prs = []
+    lines: list[str] = []
+    lines.extend([
+        "# Übergabeprompt",
+        "",
+        "## 1. Arbeitsumgebung",
+        "",
+        f"Local path: `{repo.get('local_path', '')}`",
+        f"Remote: `{repo.get('remote', '')}`",
+        f"Default branch: `{repo.get('default_branch', 'main')}`",
+    ])
+    lines.extend([
+        "",
+        "## 2. Sicherer Stand",
+        "",
+        f"Branch: `{safe_state.get('branch', '')}`",
+        f"Commit: `{safe_state.get('commit', '')}`",
+        f"Subject: {safe_state.get('commit_subject', '')}",
+        f"Semantics: `{safe_state.get('semantics', 'last_substantive_work_state')}`",
+        f"Working tree expected clean: `{safe_state.get('working_tree_expected_clean', '')}`",
+    ])
+    if isinstance(admin_state, dict) and admin_state:
+        admin_current_head = admin_state.get("current_head", "")
+        admin_current_head_subject = admin_state.get("current_head_subject", "")
+        admin_allowed_after_safe_state = admin_state.get("allowed_after_safe_state", "")
+        admin_reason = admin_state.get("reason", "")
+        lines.extend([
+            "",
+            "## 2a. Administrative Evidence State",
+            "",
+            "Administrative Evidence Commits nach dem fachlichen Safe-State sind erlaubt, wenn sie nur Logs, Handoff, Summary oder Evidence aktualisieren. Sie ändern den fachlichen Safe-State nicht.",
+            "",
+            f"Current HEAD at generation time: `{admin_current_head}`",
+            f"HEAD subject: {admin_current_head_subject}",
+            f"Allowed after safe state: `{admin_allowed_after_safe_state}`",
+            f"Reason: {admin_reason}",
+        ])
+    lines.extend([
+        "",
+        "## 3. Release- und Produktstand",
+        "",
+        f"Current version: `{release.get('current_version', '')}`",
+        f"Previous version: `{release.get('previous_version', '')}`",
+        f"Tag: `{release.get('tag', '')}`",
+        f"Zenodo concept DOI: `{release.get('zenodo_concept_doi', '')}`",
+        f"Zenodo version DOI: `{release.get('zenodo_version_doi', '')}`",
+        f"Post-release check: `{release.get('post_release_check', '')}`",
+    ])
+    lines.extend([
+        "",
+        "## 4. Pflichtquellen vor jeder Mutation",
+        "",
+        "Lies diese Quellen zuerst. Wenn eine Quelle fehlt, widersprüchlich ist oder nicht gelesen werden kann, melde Drift und mutiere nicht außer zur Drift-Reparatur.",
+        "",
+    ])
+    lines.extend(_bullet_lines(MANDATORY_SUCCESSOR_CHAT_SOURCES))
+    lines.extend([
+        "",
+        "## 4a. Bootloader",
+        "",
+        "Beim Chatwechsel zuerst den Bootloader ausführen: `agentic-kit boot prompt` oder `./ns chat-bootloader`.",
+        "",
+        "## 5. Kommunikations- und Summary-Regeln",
+        "",
+        "User-Kürzel sind Kommunikationssignale, keine Evidence:",
+        "",
+    ])
+    lines.extend(_bullet_lines(COMMUNICATION_SHORTCUTS))
+    lines.extend(["", "Final-Summary-Vokabular:", ""])
+    lines.extend(_bullet_lines(SUMMARY_VOCABULARY))
+    lines.extend([
+        "",
+        "## 6. Aktive Regeln aus handoff_state",
+        "",
+    ])
+    lines.extend(_bullet_lines(_rule_texts(data)))
+    lines.extend(["", "## 7. Offene Punkte", ""])
+    if open_prs:
+        for pr in open_prs:
+            lines.append(f"- PR #{pr.get('number')}: {pr.get('title', '')}")
+    else:
+        lines.append("- Keine offenen PRs im handoff_state.")
+    lines.extend(["", "## 8. Abgeschlossen seit letzter Übergabe", ""])
+    completed = data.get("completed_since_previous_handoff", [])
+    if completed:
+        lines.extend(_bullet_lines(completed))
+    else:
+        lines.append("- Keine Einträge.")
+    lines.extend(["", "## 9. Letzte bekannte Fehler- und Driftmuster", ""])
+    for item in data.get("recent_failure_patterns", []):
+        if isinstance(item, dict):
+            lines.append(f"- `{item.get('id')}`: {item.get('prevention') or item.get('description', '')}")
+    lines.extend(["", "## 10. Verbotene Muster", ""])
+    lines.extend(_bullet_lines(FORBIDDEN_PATTERNS))
+    lines.extend(["", "## 11. Nächste erlaubte Aufgaben", ""])
+    tasks = data.get("next_allowed_tasks", [])
+    if tasks:
+        for task in tasks:
+            if isinstance(task, dict):
+                lines.append(f"- {task.get('priority', '?')}. `{task.get('id', '')}` — {task.get('title', '')}")
+    else:
+        lines.append("- Keine Aufgaben im handoff_state eingetragen.")
+    lines.extend(["", "## 12. Gesperrte Aufgaben", ""])
+    blocked = data.get("blocked_until_closeout", [])
+    if blocked:
+        lines.extend(_bullet_lines(blocked))
+    else:
+        lines.append("- Keine gesperrten Aufgaben im handoff_state eingetragen.")
+    lines.extend([
+        "",
+        "## 13. Erste Arbeitsanweisung",
+        "",
+        data.get("first_instruction", ""),
+        "",
+        "## 14. Arbeitsmodus für den Nachfolge-Chat",
+        "",
+        "1. Führe zuerst den Bootloader aus.",
+        "2. Lies danach alle Pflichtquellen aus Abschnitt 4.",
+        "3. Rekonstruiere den aktuellen Stand aus Repo, PR/CI, Logs und Summary, nicht aus Chat-Erinnerung.",
+        "4. Prüfe Drift zwischen Regeln, Tests, Summary-Renderer, Status und Handoff.",
+        "5. Bei Drift: warnen, keine Produktmutation, Handoff-Prompt oder Drift-Fix anbieten.",
+        "6. Arbeite nur in kleinen, testbaren Slices mit ehrlicher Evidence.",
+    ])
+    return "\n".join(lines).rstrip() + "\n"