@deftai/directive-content 0.55.2 → 0.56.0

package/scripts/preflight_implementation.py

@@ -0,0 +1,272 @@
+#!/usr/bin/env python3
+"""preflight_implementation.py -- structural implementation-intent gate (#810).
+
+Asserts a vBRIEF is eligible to be implemented before any code-writing
+sub-agent spawns. The executable preflight gate is intentionally limited
+to two structural conditions:
+
+1. The vBRIEF's containing folder is ``vbrief/active/``.
+2. ``plan.status == "running"``.
+
+Both conditions together encode the explicit lifecycle handoff that
+``task vbrief:activate <path>`` performs (pending/ -> active/ AND
+status flip pending/approved -> running). The gate fails closed: any
+ambiguous, malformed, or pre-activation state exits non-zero with an
+actionable redirect to ``task vbrief:activate``.
+
+Story-workflow controls such as ``git status --short --branch``,
+dirty-work prompting, one-story/default batching approval, and checkpoint
+commits live in the Story Start Gate documentation. They must run before
+this helper is invoked, because this helper only receives a vBRIEF path
+and stays deterministic, side-effect-free, and path-prefix agnostic across
+consumer installs.
+
+Mirrors ``scripts/preflight_branch.py`` (#747) in shape: pure stdlib,
+``evaluate(path) -> (exit_code, message)`` separated from CLI plumbing
+for testability, three-state exit codes, structured JSON variant.
+
+Exit codes:
+
+- ``0`` -- ready: folder is ``active/`` AND ``plan.status == "running"``.
+- ``1`` -- not ready: pre-activation folder, wrong status, malformed
+  JSON, missing keys, unreadable file, or any other reject path. The
+  message always includes the actionable
+  ``task vbrief:activate <path>`` redirect.
+
+The gate intentionally collapses every reject path to exit 1 (rather
+than splitting "config error" into exit 2 like ``preflight_branch.py``)
+because the consumer surface -- a skill step that decides whether to
+spawn a code-writing sub-agent -- only cares about ready / not-ready.
+The actionable message disambiguates the underlying cause for the
+operator.
+
+Refs:
+- #810 (this gate)
+- #747 (precedent shape: ``scripts/preflight_branch.py``)
+- #1371 (Story Start Gate; this helper remains the structural lifecycle sub-gate)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from verify_session_ritual import verify  # noqa: E402
+
+#: Canonical eligibility folder. A vBRIEF MUST live here for an
+#: implementation agent to spawn; lifecycle moves are gated by
+#: ``task vbrief:activate`` (#810).
+ACTIVE_FOLDER = "active"
+
+#: Canonical eligibility status. ``running`` is the only ``plan.status``
+#: enum value that signals an active implementation handoff.
+ELIGIBLE_STATUS = "running"
+
+#: The actionable redirect that EVERY reject path surfaces. Operators
+#: copy-paste this verbatim. The placeholder ``<path>`` is substituted
+#: with the input path so the redirect is one-shot runnable.
+ACTIVATE_HINT = "Run `task vbrief:activate {path}` before spawning an implementation agent."
+
+
+def _build_reject(path: Path, reason: str) -> str:
+    """Compose a reject message with the canonical actionable redirect."""
+    return f"{reason}\n  {ACTIVATE_HINT.format(path=path)}"
+
+
+def evaluate(vbrief_path: Path) -> tuple[int, str]:
+    """Pure evaluator -- returns ``(exit_code, human_message)``.
+
+    Separated from :func:`main` so tests can drive every state without
+    capsys plumbing or argparse round-tripping. Never raises -- every
+    error path is collapsed to exit 1 with an actionable message.
+    """
+    # --- Path resolution + readability ------------------------------------
+    try:
+        path = Path(vbrief_path)
+    except TypeError as exc:  # extremely defensive
+        return 1, _build_reject(
+            Path(str(vbrief_path)),
+            f"Could not interpret vBRIEF path '{vbrief_path}': {exc}.",
+        )
+
+    if not path.exists():
+        return 1, _build_reject(
+            path,
+            f"vBRIEF not found at {path}.",
+        )
+
+    if not path.is_file():
+        return 1, _build_reject(
+            path,
+            f"vBRIEF path {path} is not a regular file.",
+        )
+
+    # --- JSON load (swallow malformed / unreadable) ------------------------
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        return 1, _build_reject(
+            path,
+            f"Could not read vBRIEF at {path}: {exc}.",
+        )
+
+    try:
+        payload: Any = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        return 1, _build_reject(
+            path,
+            f"vBRIEF at {path} is not valid JSON: {exc.msg} (line {exc.lineno}).",
+        )
+
+    if not isinstance(payload, dict):
+        return 1, _build_reject(
+            path,
+            f"vBRIEF at {path} top-level value is not a JSON object.",
+        )
+
+    # --- Folder gate -------------------------------------------------------
+    folder = path.parent.name
+    if folder != ACTIVE_FOLDER:
+        return 1, _build_reject(
+            path,
+            f"vBRIEF is in {folder}/ -- only vbrief/active/ is eligible "
+            f"for implementation.",
+        )
+
+    # --- plan + plan.status structure -------------------------------------
+    plan = payload.get("plan")
+    if not isinstance(plan, dict):
+        return 1, _build_reject(
+            path,
+            f"vBRIEF at {path} lacks a `plan` object -- malformed.",
+        )
+
+    status = plan.get("status")
+    if not isinstance(status, str) or not status:
+        return 1, _build_reject(
+            path,
+            f"vBRIEF at {path} lacks `plan.status` -- malformed.",
+        )
+
+    if status != ELIGIBLE_STATUS:
+        return 1, _build_reject(
+            path,
+            f"plan.status is '{status}' -- only '{ELIGIBLE_STATUS}' is eligible "
+            f"for implementation.",
+        )
+
+    return 0, f"OK {path} -- ready for implementation."
+
+
+def _emit_json(path: Path, code: int, message: str) -> str:
+    """Render the structured ``--json`` payload.
+
+    Schema (pinned by tests):
+    - ``ready`` (bool) -- True iff exit code is 0.
+    - ``exit_code`` (int) -- 0 ready, 1 not ready.
+    - ``vbrief_path`` (str) -- the input path as supplied.
+    - ``message`` (str) -- the same human-readable message printed in
+      non-JSON mode (multi-line, newlines preserved).
+    """
+    payload = {
+        "ready": code == 0,
+        "exit_code": code,
+        "vbrief_path": str(path),
+        "message": message,
+    }
+    return json.dumps(payload, sort_keys=True)
+
+
+def _discover_project_root(vbrief_path: Path) -> Path:
+    """Find the repo root that owns ``vbrief_path`` for the session gate."""
+    try:
+        resolved = vbrief_path.resolve(strict=False)
+    except OSError:
+        resolved = vbrief_path.absolute()
+    for candidate in (resolved.parent, *resolved.parents):
+        if (candidate / ".git").exists() or (
+            candidate / "vbrief" / "PROJECT-DEFINITION.vbrief.json"
+        ).exists():
+            return candidate
+    return Path.cwd()
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="preflight_implementation.py",
+        description=(
+            "Structural implementation-intent gate (#810). Asserts a "
+            "vBRIEF lives in vbrief/active/ AND plan.status == 'running' "
+            "before an implementation agent can spawn. Mirrors the shape "
+            "of scripts/preflight_branch.py (#747)."
+        ),
+    )
+    parser.add_argument(
+        "--vbrief-path",
+        required=True,
+        help="Path to the candidate vBRIEF JSON file.",
+    )
+    parser.add_argument(
+        "--project-root",
+        default=None,
+        help=(
+            "Project root containing .deft/ritual-state.json. Defaults to "
+            "the owner discovered from --vbrief-path."
+        ),
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        dest="emit_json",
+        help=(
+            "Emit a structured JSON payload to stdout instead of the "
+            "human-readable message. Exit code is unchanged."
+        ),
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    path = Path(args.vbrief_path)
+    project_root = (
+        Path(args.project_root).resolve(strict=False)
+        if args.project_root is not None
+        else _discover_project_root(path)
+    )
+
+    ritual = verify(project_root, tier="gated")
+    if ritual.code != 0:
+        message = (
+            "Session ritual gate failed before #810 lifecycle check: "
+            f"{ritual.message}"
+        )
+        if args.emit_json:
+            print(_emit_json(path, 1, message))
+        else:
+            print(message, file=sys.stderr)
+        return 1
+
+    code, message = evaluate(path)
+
+    if args.emit_json:
+        # JSON variant always lands on stdout -- consumers parse it.
+        print(_emit_json(path, code, message))
+    elif code == 0:
+        print(message)
+    else:
+        # Reject paths land on stderr so calling skills can pipe stdout
+        # cleanly when chaining; the actionable redirect is preserved.
+        print(message, file=sys.stderr)
+
+    return code
+
+
+if __name__ == "__main__":
+    sys.exit(main())