process: enforce session handover gate across sessions (#308)

scripts/session_handover_check.py

@@ -0,0 +1,138 @@
+#!/usr/bin/env python3
+"""Session handover preflight gate.
+
+This script enforces a minimal handover record per working branch so that
+new sessions cannot start implementation without reading the required docs
+and recording current intent.
+"""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from datetime import UTC, datetime
+from pathlib import Path
+
+REQUIRED_DOCS = (
+    Path("docs/workflow.md"),
+    Path("docs/commands.md"),
+    Path("docs/agent-constraints.md"),
+)
+HANDOVER_LOG = Path("workflow/session-handover.md")
+
+
+def _run_git(*args: str) -> str:
+    try:
+        return (
+            subprocess.check_output(["git", *args], stderr=subprocess.DEVNULL)
+            .decode("utf-8")
+            .strip()
+        )
+    except Exception:
+        return ""
+
+
+def _current_branch() -> str:
+    branch = _run_git("branch", "--show-current")
+    if branch:
+        return branch
+    return _run_git("rev-parse", "--abbrev-ref", "HEAD")
+
+
+def _latest_entry(text: str) -> str:
+    chunks = text.split("\n### ")
+    if not chunks:
+        return ""
+    if chunks[0].startswith("### "):
+        chunks[0] = chunks[0][4:]
+    latest = chunks[-1].strip()
+    if not latest:
+        return ""
+    if not latest.startswith("### "):
+        latest = f"### {latest}"
+    return latest
+
+
+def _check_required_files(errors: list[str]) -> None:
+    for path in REQUIRED_DOCS:
+        if not path.exists():
+            errors.append(f"missing required document: {path}")
+    if not HANDOVER_LOG.exists():
+        errors.append(f"missing handover log: {HANDOVER_LOG}")
+
+
+def _check_handover_entry(
+    *,
+    branch: str,
+    strict: bool,
+    errors: list[str],
+) -> None:
+    if not HANDOVER_LOG.exists():
+        return
+    text = HANDOVER_LOG.read_text(encoding="utf-8")
+    latest = _latest_entry(text)
+    if not latest:
+        errors.append("handover log has no session entry")
+        return
+
+    required_tokens = (
+        "- branch:",
+        "- docs_checked:",
+        "- open_issues_reviewed:",
+        "- next_ticket:",
+    )
+    for token in required_tokens:
+        if token not in latest:
+            errors.append(f"latest handover entry missing token: {token}")
+
+    if strict:
+        today_utc = datetime.now(UTC).date().isoformat()
+        if today_utc not in latest:
+            errors.append(
+                f"latest handover entry must contain today's UTC date ({today_utc})"
+            )
+        branch_token = f"- branch: {branch}"
+        if branch_token not in latest:
+            errors.append(
+                "latest handover entry must target current branch "
+                f"({branch_token})"
+            )
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Validate session handover gate requirements."
+    )
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="Enforce today-date and current-branch match on latest handover entry.",
+    )
+    args = parser.parse_args()
+
+    errors: list[str] = []
+    _check_required_files(errors)
+
+    branch = _current_branch()
+    if not branch:
+        errors.append("cannot resolve current git branch")
+    elif branch in {"main", "master"}:
+        errors.append(f"working branch must not be {branch}")
+
+    _check_handover_entry(branch=branch, strict=args.strict, errors=errors)
+
+    if errors:
+        print("[FAIL] session handover check failed")
+        for err in errors:
+            print(f"- {err}")
+        return 1
+
+    print("[OK] session handover check passed")
+    print(f"[OK] branch={branch}")
+    print(f"[OK] handover_log={HANDOVER_LOG}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/validate_governance_assets.py

@@ -22,6 +22,10 @@ def main() -> int:
 
     pr_template = Path(".gitea/PULL_REQUEST_TEMPLATE.md")
     issue_template = Path(".gitea/ISSUE_TEMPLATE/runtime_verification.md")
+    workflow_doc = Path("docs/workflow.md")
+    commands_doc = Path("docs/commands.md")
+    handover_script = Path("scripts/session_handover_check.py")
+    handover_log = Path("workflow/session-handover.md")
 
     must_contain(
         pr_template,
@@ -32,6 +36,8 @@ def main() -> int:
             "NOT_OBSERVED",
             "tea",
             "gh",
+            "Session Handover Gate",
+            "session_handover_check.py --strict",
         ],
         errors,
     )
@@ -45,6 +51,35 @@ def main() -> int:
         ],
         errors,
     )
+    must_contain(
+        workflow_doc,
+        [
+            "Session Handover Gate (Mandatory)",
+            "session_handover_check.py --strict",
+        ],
+        errors,
+    )
+    must_contain(
+        commands_doc,
+        [
+            "Session Handover Preflight (Mandatory)",
+            "session_handover_check.py --strict",
+        ],
+        errors,
+    )
+    must_contain(
+        handover_log,
+        [
+            "Session Handover Log",
+            "- branch:",
+            "- docs_checked:",
+            "- open_issues_reviewed:",
+            "- next_ticket:",
+        ],
+        errors,
+    )
+    if not handover_script.exists():
+        errors.append(f"missing file: {handover_script}")
 
     if errors:
         print("[FAIL] governance asset validation failed")
@@ -58,4 +93,3 @@ def main() -> int:
 
 if __name__ == "__main__":
     sys.exit(main())
-