147 lines
4.0 KiB
Python
Executable File
147 lines
4.0 KiB
Python
Executable File
#!/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:",
|
|
"- process_gate_checked:",
|
|
)
|
|
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})"
|
|
)
|
|
if "- next_ticket: #TBD" in latest:
|
|
errors.append("latest handover entry must not use placeholder next_ticket (#TBD)")
|
|
if "merged_to_feature_branch=no" in latest:
|
|
errors.append(
|
|
"process gate indicates not merged; implementation must stay blocked "
|
|
"(merged_to_feature_branch=no)"
|
|
)
|
|
|
|
|
|
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())
|