@deftai/directive-content 0.59.0 → 0.61.0

package/scripts/preflight_wip_cap.py

@@ -1,149 +0,0 @@
-#!/usr/bin/env python3
-"""preflight_wip_cap.py -- ``task verify:wip-cap`` re-validation gate (#1124 / D4 of #1119).
-
-CI-level re-validation that the consumer's ``pending/ + active/`` count
-is within the typed ``plan.policy.wipCap`` (default 10 per umbrella
-#1119 Current Shape v3). Catches three drift scenarios that
-``task scope:promote``'s own cap check cannot:
-
-1. **Stale-branch merge** -- a PR was within cap at PR-open but master
-   advanced past the cap before merge. ``scope:promote`` ran on the PR
-   branch (within cap); the merged combination is over cap.
-2. **Force-merge bypass** -- an operator opened a PR with ``scope:promote
-   --force`` (audit-logged, but still merged); the merge surfaces the
-   override on the base branch.
-3. **Out-of-band edits** -- a vBRIEF was moved into ``pending/`` via
-   filesystem operations (``git mv``, IDE drag) without going through
-   ``scope:promote``; the cap was never enforced.
-
-Behaviour contract:
-
-* Three-state exit (mirrors ``scripts/preflight_branch.py`` / #747):
-  ``0`` -- count within cap; ``1`` -- count >= cap (over cap); ``2`` --
-  config error (PROJECT-DEFINITION malformed). All paths print
-  diagnostic to stderr with the canonical relief verbs.
-* ``--allow-over-cap`` -- escape hatch for the framework's own
-  ``task check`` so deft's own landing-day overage (currently
-  ``pending/+active/`` >> 10 -- see umbrella v3 "Landing-day overage
-  handled via D1 ``scope:demote --batch``") does not break framework
-  self-check. Consumer projects MUST NOT pass this; their ``task check``
-  fails loudly when over cap. Mirrors ``verify:cache-fresh``'s
-  ``--allow-missing-bootstrap`` shape.
-* ``--project-root`` -- consumer project root; defaults to CWD. Mirrors
-  the existing preflight scripts.
-
-Pure stdlib so the gate runs from a fresh git hook or minimal CI runner
-without ``uv sync``.
-"""
-
-from __future__ import annotations
-
-import argparse
-import sys
-from pathlib import Path
-
-# Make sibling ``policy`` importable when run as ``__main__``.
-sys.path.insert(0, str(Path(__file__).resolve().parent))
-
-from _stdio_utf8 import reconfigure_stdio  # noqa: E402
-
-reconfigure_stdio()
-
-
-def _format_refusal(count: int, cap: int, project_root: Path) -> str:
-    return (
-        f"\u274c verify:wip-cap: {count}/{cap} in pending/+active/ "
-        f"(over cap; project_root={project_root}).\n"
-        "   Drain the WIP set before merging:\n"
-        "     task scope:demote <existing>                       # return one to proposed/\n"
-        "     task scope:demote --batch --older-than-days 30     # bulk relief\n"
-        "   Or open a follow-up PR with --force-merge intent (audit-logged).\n"
-        "   (#1124 / D4 of #1119; see plan.policy.wipCap in "
-        "vbrief/PROJECT-DEFINITION.vbrief.json.)"
-    )
-
-
-def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(
-        prog="preflight_wip_cap.py",
-        description=(
-            "Re-validate plan.policy.wipCap on the base branch (#1124 / D4 of #1119). "
-            "Catches stale-branch merges, --force overrides, and out-of-band edits."
-        ),
-    )
-    parser.add_argument(
-        "--project-root",
-        default=".",
-        help="Consumer project root (default: CWD).",
-    )
-    parser.add_argument(
-        "--allow-over-cap",
-        action="store_true",
-        help=(
-            "Print an INFO line + exit 0 even when over cap. Reserved for "
-            "the framework's own task check during landing-day overage; "
-            "consumer projects MUST NOT pass this."
-        ),
-    )
-    parser.add_argument(
-        "--quiet",
-        action="store_true",
-        help="Suppress the success / over-cap-allowed banner; refusal stays loud.",
-    )
-    args = parser.parse_args(argv)
-
-    project_root = Path(args.project_root).resolve()
-
-    # Lazy import so a partial install can still produce a sensible
-    # error (mirrors the scope_lifecycle.py pattern).
-    try:
-        from policy import count_vbrief_wip, resolve_wip_cap  # noqa: I001
-    except ImportError as exc:  # pragma: no cover -- D4 not present
-        print(
-            f"\u274c verify:wip-cap: scripts.policy not importable: {exc}",
-            file=sys.stderr,
-        )
-        return 2
-
-    cap_result = resolve_wip_cap(project_root)
-    if cap_result.source == "default-on-error" and cap_result.error:
-        print(
-            f"\u274c verify:wip-cap: PROJECT-DEFINITION malformed: {cap_result.error}",
-            file=sys.stderr,
-        )
-        return 2
-
-    cap = cap_result.cap
-    count = count_vbrief_wip(project_root)
-
-    if count < cap:
-        if not args.quiet:
-            print(
-                f"\u2713 verify:wip-cap: {count}/{cap} in pending/+active/ "
-                f"(within cap; source={cap_result.source})."
-            )
-        return 0
-
-    # Over cap (count >= cap).
-    if args.allow_over_cap:
-        if not args.quiet:
-            # Stderr so it surfaces alongside other warnings in CI logs;
-            # banner is informational, not a failure.
-            print(
-                (
-                    f"\u26a0 verify:wip-cap: {count}/{cap} in pending/+active/ "
-                    "is OVER cap, but --allow-over-cap was passed (framework "
-                    "landing-day grace; consumers MUST NOT use this flag).\n"
-                    "  Drain via task scope:demote / task scope:demote --batch "
-                    "--older-than-days 30 (#1119 umbrella v3)."
-                ),
-                file=sys.stderr,
-            )
-        return 0
-
-    print(_format_refusal(count, cap, project_root), file=sys.stderr)
-    return 1
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

package/scripts/probe_session.py

@@ -1,545 +0,0 @@
-#!/usr/bin/env python3
-"""probe_session.py -- mechanical guard for probe artifact handoff (#1518c).
-
-Records whether a probe session is still interrogating or ready for artifact
-registration. Callers MUST invoke the guard helpers before writing probe output
-or updating ``completedStrategies`` for ``"probe"`` in ``plan.vbrief.json``.
-
-Session state lives at ``.deft/probe-session.json`` (gitignored, per-clone).
-
-Exit codes (CLI):
-  0 -- success
-  1 -- handoff blocked (interrogation still active)
-  2 -- usage / config error
-
-Usage:
-    uv run python scripts/probe_session.py start --target <scope> [--branch <decision-branch>]
-    uv run python scripts/probe_session.py record --question ... --answer ... --status locked
-    uv run python scripts/probe_session.py set-branch --branch <decision-branch>
-    uv run python scripts/probe_session.py complete
-    uv run python scripts/probe_session.py status [--json]
-    uv run python scripts/probe_session.py guard-artifact --path <artifact-path>
-    uv run python scripts/probe_session.py guard-plan-registration
-
-Refs #1518 recommendation C.
-"""
-
-from __future__ import annotations
-
-import argparse
-import contextlib
-import json
-import os
-import subprocess
-import sys
-import tempfile
-from dataclasses import dataclass
-from datetime import UTC, datetime
-from pathlib import Path
-from typing import Any, Literal
-
-SCHEMA_VERSION: int = 1
-SESSION_RELPATH: tuple[str, str] = (".deft", "probe-session.json")
-
-STATE_INTERROGATE: Literal["interrogate"] = "interrogate"
-STATE_COMPLETE: Literal["complete"] = "complete"
-ProbeState = Literal["interrogate", "complete"]
-
-VALID_DECISION_STATUSES = frozenset({"locked", "deferred", "risk-accepted"})
-
-
-class ProbeHandoffBlockedError(Exception):
-    """Raised when probe artifacts or plan registration are attempted too early."""
-
-    def __init__(self, message: str, *, session: ProbeSession | None = None) -> None:
-        super().__init__(message)
-        self.session = session
-
-
-@dataclass(frozen=True)
-class ResolvedDecision:
-    question: str
-    answer: str
-    status: str
-
-    def to_dict(self) -> dict[str, str]:
-        return {
-            "question": self.question,
-            "answer": self.answer,
-            "status": self.status,
-        }
-
-    @classmethod
-    def from_dict(cls, raw: object) -> ResolvedDecision | None:
-        if not isinstance(raw, dict):
-            return None
-        question = raw.get("question")
-        answer = raw.get("answer")
-        status = raw.get("status")
-        if not all(isinstance(v, str) and v.strip() for v in (question, answer, status)):
-            return None
-        if status not in VALID_DECISION_STATUSES:
-            return None
-        return cls(question=question.strip(), answer=answer.strip(), status=status.strip())
-
-
-@dataclass(frozen=True)
-class ProbeSession:
-    schema_version: int
-    state: ProbeState
-    target: str
-    current_branch: str
-    resolved_decisions: tuple[ResolvedDecision, ...]
-    started_at: datetime
-    completed_at: datetime | None
-
-    def to_dict(self) -> dict[str, Any]:
-        payload: dict[str, Any] = {
-            "schemaVersion": self.schema_version,
-            "state": self.state,
-            "target": self.target,
-            "currentBranch": self.current_branch,
-            "resolvedDecisions": [d.to_dict() for d in self.resolved_decisions],
-            "startedAt": _format_timestamp(self.started_at),
-        }
-        if self.completed_at is not None:
-            payload["completedAt"] = _format_timestamp(self.completed_at)
-        return payload
-
-
-def _session_path(project_root: Path) -> Path:
-    return project_root.joinpath(*SESSION_RELPATH)
-
-
-def _format_timestamp(value: datetime) -> str:
-    instant = value.replace(tzinfo=UTC) if value.tzinfo is None else value.astimezone(UTC)
-    return instant.strftime("%Y-%m-%dT%H:%M:%SZ")
-
-
-def _parse_timestamp(raw: object) -> datetime | None:
-    if not isinstance(raw, str) or not raw:
-        return None
-    normalised = raw[:-1] + "+00:00" if raw.endswith("Z") else raw
-    try:
-        parsed = datetime.fromisoformat(normalised)
-    except ValueError:
-        return None
-    if parsed.tzinfo is None:
-        parsed = parsed.replace(tzinfo=UTC)
-    return parsed
-
-
-def _detect_git_branch(project_root: Path) -> str:
-    try:
-        result = subprocess.run(
-            ["git", "symbolic-ref", "--short", "HEAD"],
-            cwd=str(project_root),
-            capture_output=True,
-            text=True,
-            encoding="utf-8",
-            errors="replace",
-            timeout=10,
-            check=False,
-        )
-    except (FileNotFoundError, subprocess.TimeoutExpired):
-        return ""
-    if result.returncode == 0:
-        branch = (result.stdout or "").strip()
-        if branch:
-            return branch
-    try:
-        rev_result = subprocess.run(
-            ["git", "rev-parse", "--short", "HEAD"],
-            cwd=str(project_root),
-            capture_output=True,
-            text=True,
-            encoding="utf-8",
-            errors="replace",
-            timeout=10,
-            check=False,
-        )
-    except (FileNotFoundError, subprocess.TimeoutExpired):
-        return ""
-    if rev_result.returncode == 0:
-        sha = (rev_result.stdout or "").strip()
-        if sha:
-            return f"detached:{sha}"
-    return ""
-
-
-def read(project_root: Path) -> ProbeSession | None:
-    """Read ``.deft/probe-session.json`` from ``project_root``."""
-    session_file = _session_path(project_root)
-    if not session_file.is_file():
-        return None
-    try:
-        payload = json.loads(session_file.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError, ValueError):
-        return None
-    if not isinstance(payload, dict):
-        return None
-    if payload.get("schemaVersion") != SCHEMA_VERSION:
-        return None
-    state = payload.get("state")
-    if state not in (STATE_INTERROGATE, STATE_COMPLETE):
-        return None
-    target = payload.get("target")
-    current_branch = payload.get("currentBranch")
-    if not isinstance(target, str) or not target.strip():
-        return None
-    if not isinstance(current_branch, str):
-        return None
-    started_at = _parse_timestamp(payload.get("startedAt"))
-    if started_at is None:
-        return None
-    completed_at = _parse_timestamp(payload.get("completedAt"))
-    if state == STATE_COMPLETE and completed_at is None:
-        return None
-    if state == STATE_INTERROGATE and completed_at is not None:
-        return None
-    raw_decisions = payload.get("resolvedDecisions")
-    if not isinstance(raw_decisions, list):
-        return None
-    decisions: list[ResolvedDecision] = []
-    for item in raw_decisions:
-        parsed = ResolvedDecision.from_dict(item)
-        if parsed is None:
-            return None
-        decisions.append(parsed)
-    return ProbeSession(
-        schema_version=SCHEMA_VERSION,
-        state=state,
-        target=target.strip(),
-        current_branch=current_branch.strip(),
-        resolved_decisions=tuple(decisions),
-        started_at=started_at,
-        completed_at=completed_at,
-    )
-
-
-def write(project_root: Path, session: ProbeSession) -> Path:
-    """Atomically persist ``session`` to ``.deft/probe-session.json``."""
-    session_file = _session_path(project_root)
-    session_file.parent.mkdir(parents=True, exist_ok=True)
-    tmp_fd, tmp_name = tempfile.mkstemp(
-        prefix=".probe-session.",
-        suffix=".json.tmp",
-        dir=str(session_file.parent),
-    )
-    fdopen_succeeded = False
-    try:
-        fh = os.fdopen(tmp_fd, "w", encoding="utf-8", newline="\n")
-        fdopen_succeeded = True
-        try:
-            json.dump(session.to_dict(), fh, indent=2, sort_keys=True)
-            fh.write("\n")
-            fh.flush()
-            with contextlib.suppress(OSError):
-                os.fsync(fh.fileno())
-        finally:
-            fh.close()
-        os.replace(tmp_name, session_file)
-    except Exception:
-        if not fdopen_succeeded:
-            with contextlib.suppress(OSError):
-                os.close(tmp_fd)
-        with contextlib.suppress(OSError):
-            os.unlink(tmp_name)
-        raise
-    return session_file
-
-
-def start_session(
-    project_root: Path,
-    *,
-    target: str,
-    current_branch: str = "",
-    now: datetime | None = None,
-) -> ProbeSession:
-    """Start (or replace) an interrogating probe session for ``target``."""
-    scope = target.strip()
-    if not scope:
-        raise ValueError("target must be a non-empty scope name")
-    branch = current_branch.strip() or _detect_git_branch(project_root)
-    instant = now if now is not None else datetime.now(UTC)
-    session = ProbeSession(
-        schema_version=SCHEMA_VERSION,
-        state=STATE_INTERROGATE,
-        target=scope,
-        current_branch=branch,
-        resolved_decisions=(),
-        started_at=instant,
-        completed_at=None,
-    )
-    write(project_root, session)
-    return session
-
-
-def record_decision(
-    project_root: Path,
-    *,
-    question: str,
-    answer: str,
-    status: str,
-) -> ProbeSession:
-    """Append a resolved decision while the session is interrogating."""
-    session = read(project_root)
-    if session is None:
-        raise ProbeHandoffBlockedError(
-            "No active probe session. Start one with "
-            "`uv run python scripts/probe_session.py start --target <scope>`."
-        )
-    if session.state != STATE_INTERROGATE:
-        raise ProbeHandoffBlockedError(
-            "Probe session is already complete; decisions cannot be appended.",
-            session=session,
-        )
-    if status not in VALID_DECISION_STATUSES:
-        raise ValueError(
-            f"status must be one of {sorted(VALID_DECISION_STATUSES)}, got {status!r}"
-        )
-    q = question.strip()
-    a = answer.strip()
-    if not q or not a:
-        raise ValueError("question and answer must be non-empty strings")
-    updated = ProbeSession(
-        schema_version=session.schema_version,
-        state=session.state,
-        target=session.target,
-        current_branch=session.current_branch,
-        resolved_decisions=session.resolved_decisions + (
-            ResolvedDecision(question=q, answer=a, status=status),
-        ),
-        started_at=session.started_at,
-        completed_at=session.completed_at,
-    )
-    write(project_root, updated)
-    return updated
-
-
-def set_current_branch(project_root: Path, branch: str) -> ProbeSession:
-    """Update the decision branch currently under interrogation."""
-    session = read(project_root)
-    if session is None:
-        raise ProbeHandoffBlockedError(
-            "No active probe session. Start one with "
-            "`uv run python scripts/probe_session.py start --target <scope>`."
-        )
-    if session.state != STATE_INTERROGATE:
-        raise ProbeHandoffBlockedError(
-            "Probe session is already complete; current branch cannot change.",
-            session=session,
-        )
-    updated = ProbeSession(
-        schema_version=session.schema_version,
-        state=session.state,
-        target=session.target,
-        current_branch=branch.strip(),
-        resolved_decisions=session.resolved_decisions,
-        started_at=session.started_at,
-        completed_at=session.completed_at,
-    )
-    write(project_root, updated)
-    return updated
-
-
-def mark_complete(project_root: Path, *, now: datetime | None = None) -> ProbeSession:
-    """Mark the active probe session complete so artifact handoff is allowed."""
-    session = read(project_root)
-    if session is None:
-        raise ProbeHandoffBlockedError(
-            "No active probe session. Start one with "
-            "`uv run python scripts/probe_session.py start --target <scope>`."
-        )
-    if session.state == STATE_COMPLETE:
-        return session
-    instant = now if now is not None else datetime.now(UTC)
-    updated = ProbeSession(
-        schema_version=session.schema_version,
-        state=STATE_COMPLETE,
-        target=session.target,
-        current_branch=session.current_branch,
-        resolved_decisions=session.resolved_decisions,
-        started_at=session.started_at,
-        completed_at=instant,
-    )
-    write(project_root, updated)
-    return updated
-
-
-def _blocked_message(session: ProbeSession | None, action: str) -> str:
-    if session is None:
-        return (
-            f"Probe handoff blocked for {action}: no active probe session. "
-            "Start interrogation with "
-            "`uv run python scripts/probe_session.py start --target <scope>` "
-            "and finish with `... complete` only after transition criteria are met."
-        )
-    return (
-        f"Probe handoff blocked for {action}: session state is "
-        f"'{session.state}' (target={session.target!r}, "
-        f"currentBranch={session.current_branch!r}, "
-        f"resolvedDecisions={len(session.resolved_decisions)}). "
-        "Continue interrogation until transition criteria are met, record decisions "
-        "with `uv run python scripts/probe_session.py record ...`, then run "
-        "`uv run python scripts/probe_session.py complete` before writing artifacts "
-        "or updating completedStrategies.probe in plan.vbrief.json."
-    )
-
-
-def require_handoff_allowed(project_root: Path, *, action: str) -> ProbeSession:
-    """Return the session when handoff is allowed; raise otherwise."""
-    session = read(project_root)
-    if session is None or session.state != STATE_COMPLETE:
-        raise ProbeHandoffBlockedError(_blocked_message(session, action), session=session)
-    return session
-
-
-def guard_probe_artifact(project_root: Path, artifact_path: str) -> ProbeSession:
-    """Guard writing a probe scope vBRIEF artifact."""
-    action = f"probe artifact write ({artifact_path})"
-    return require_handoff_allowed(project_root, action=action)
-
-
-def guard_plan_probe_registration(project_root: Path) -> ProbeSession:
-    """Guard updating completedStrategies.probe in plan.vbrief.json."""
-    return require_handoff_allowed(
-        project_root,
-        action="completedStrategies.probe registration in plan.vbrief.json",
-    )
-
-
-def session_summary(session: ProbeSession) -> dict[str, Any]:
-    """JSON-serialisable summary for CLI status output."""
-    return {
-        "state": session.state,
-        "target": session.target,
-        "currentBranch": session.current_branch,
-        "resolvedDecisions": [d.to_dict() for d in session.resolved_decisions],
-        "startedAt": _format_timestamp(session.started_at),
-        "completedAt": (
-            _format_timestamp(session.completed_at) if session.completed_at is not None else None
-        ),
-    }
-
-
-def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(
-        description="Mechanical guard for probe session state and artifact handoff."
-    )
-    parser.add_argument(
-        "--project-root",
-        type=Path,
-        default=Path("."),
-        help="Project root containing .deft/ (default: cwd)",
-    )
-    subparsers = parser.add_subparsers(dest="command", required=True)
-
-    start_parser = subparsers.add_parser("start", help="Start an interrogating probe session")
-    start_parser.add_argument("--target", required=True, help="Probe scope / feature slug")
-    start_parser.add_argument(
-        "--branch",
-        default="",
-        help="Decision branch under interrogation (defaults to git branch)",
-    )
-
-    record_parser = subparsers.add_parser("record", help="Record a resolved decision")
-    record_parser.add_argument("--question", required=True)
-    record_parser.add_argument("--answer", required=True)
-    record_parser.add_argument(
-        "--status",
-        required=True,
-        choices=sorted(VALID_DECISION_STATUSES),
-    )
-
-    branch_parser = subparsers.add_parser(
-        "set-branch",
-        help="Update the decision branch under interrogation",
-    )
-    branch_parser.add_argument("--branch", required=True)
-
-    subparsers.add_parser("complete", help="Mark the probe session complete")
-    status_parser = subparsers.add_parser("status", help="Show current probe session state")
-    status_parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
-
-    guard_artifact_parser = subparsers.add_parser(
-        "guard-artifact",
-        help="Fail unless probe artifact handoff is allowed",
-    )
-    guard_artifact_parser.add_argument(
-        "--path",
-        required=True,
-        help="Probe artifact path (e.g. vbrief/proposed/my-app-probe.vbrief.json)",
-    )
-
-    subparsers.add_parser(
-        "guard-plan-registration",
-        help="Fail unless completedStrategies.probe registration is allowed",
-    )
-
-    args = parser.parse_args(argv)
-    project_root = args.project_root.resolve()
-
-    try:
-        if args.command == "start":
-            session = start_session(project_root, target=args.target, current_branch=args.branch)
-            print(
-                f"Probe session started: state={session.state}, target={session.target!r}, "
-                f"currentBranch={session.current_branch!r}"
-            )
-            return 0
-        if args.command == "record":
-            session = record_decision(
-                project_root,
-                question=args.question,
-                answer=args.answer,
-                status=args.status,
-            )
-            print(
-                f"Recorded decision ({len(session.resolved_decisions)} total); "
-                f"state={session.state}"
-            )
-            return 0
-        if args.command == "set-branch":
-            session = set_current_branch(project_root, args.branch)
-            print(f"Current branch set to {session.current_branch!r}; state={session.state}")
-            return 0
-        if args.command == "complete":
-            session = mark_complete(project_root)
-            print(f"Probe session marked complete for target={session.target!r}")
-            return 0
-        if args.command == "status":
-            session = read(project_root)
-            if session is None:
-                print("No active probe session.")
-                return 0
-            if args.json:
-                print(json.dumps(session_summary(session), indent=2, sort_keys=True))
-            else:
-                summary = session_summary(session)
-                print(f"state: {summary['state']}")
-                print(f"target: {summary['target']}")
-                print(f"currentBranch: {summary['currentBranch']}")
-                print(f"resolvedDecisions: {len(summary['resolvedDecisions'])}")
-            return 0
-        if args.command == "guard-artifact":
-            guard_probe_artifact(project_root, args.path)
-            print(f"Probe artifact handoff allowed: {args.path}")
-            return 0
-        if args.command == "guard-plan-registration":
-            guard_plan_probe_registration(project_root)
-            print("completedStrategies.probe registration allowed")
-            return 0
-    except ProbeHandoffBlockedError as exc:
-        print(str(exc), file=sys.stderr)
-        return 1
-    except ValueError as exc:
-        print(str(exc), file=sys.stderr)
-        return 2
-
-    print(f"Unknown command: {args.command}", file=sys.stderr)
-    return 2
-
-
-if __name__ == "__main__":
-    sys.exit(main())