@deftai/directive-content 0.59.0 → 0.61.0

package/scripts/verify_hooks_installed.py

@@ -1,206 +0,0 @@
-#!/usr/bin/env python3
-"""verify_hooks_installed.py -- honest health check for the deft git hooks (#1463 / #747).
-
-Pure stdlib, cross-platform. Invoked from ``task verify:hooks-installed``.
-
-Before #1463 the ``verify:hooks-installed`` task only asserted
-``core.hooksPath == .githooks``. In a vendored consumer (framework at
-``.deft/core/``) that produced a FALSE GREEN: ``core.hooksPath`` was set but the
-hooks directory did not exist at the repo root and the gate scripts the hooks
-reference (``preflight_branch.py`` / ``verify_encoding.py`` / ``preflight_gh.py``)
-could not be resolved, so the branch / encoding / destructive-gh-verb gates were
-silently inert while the check reported success.
-
-This gate now asserts the hooks are not merely *configured* but *functional*:
-
-1. ``core.hooksPath`` is set (non-empty).
-2. The resolved hooks directory exists.
-3. The ``pre-commit`` and ``pre-push`` hooks are present in it.
-4. On POSIX, those hooks are EXECUTABLE -- git silently skips a non-executable
-   hook, so a present-but-mode-100644 hook is the #1477 inert-gate class (the
-   exec bit is meaningless on Windows, so the check is POSIX-only).
-5. The gate scripts the hooks reference resolve in THIS layout -- own-repo
-   ``scripts/``, canonical vendored ``.deft/core/scripts/``, or legacy
-   ``deft/scripts/``.
-
-Exit codes (three-state, mirrors ``scripts/preflight_branch.py`` and friends):
-
-- ``0`` -- hooks installed AND functional.
-- ``1`` -- hooks NOT installed, OR wired-but-non-functional (the #1463
-  false-green class). The message names the exact missing piece.
-- ``2`` -- config error: the project root does not exist, or ``git`` is not on
-  PATH so ``core.hooksPath`` cannot be read.
-"""
-
-from __future__ import annotations
-
-import argparse
-import os
-import subprocess
-import sys
-from pathlib import Path
-
-#: Hook scripts the framework ships and the installer wires (#1463). Both must
-#: be present in the resolved hooks directory for the gate to pass.
-REQUIRED_HOOKS = ("pre-commit", "pre-push")
-
-#: Gate scripts the hooks dispatch to. ``preflight_branch.py`` is the probe file
-#: used to LOCATE the scripts dir (it must exist in every layout); all three are
-#: then asserted present so a partial payload cannot pass the check.
-SCRIPTS_PROBE = "preflight_branch.py"
-GATE_SCRIPTS = ("preflight_branch.py", "verify_encoding.py", "preflight_gh.py")
-
-#: Candidate scripts directories, in the same priority order the layout-aware
-#: hooks (`.githooks/pre-commit`) probe: own-repo, canonical vendored, legacy
-#: vendored. Each is relative to the project root.
-SCRIPTS_DIR_CANDIDATES = ("scripts", ".deft/core/scripts", "deft/scripts")
-
-
-def _configured_hooks_path(project_root: Path) -> tuple[str | None, str | None]:
-    """Return ``(hooks_path, error)`` for the repo at ``project_root``.
-
-    ``hooks_path`` is ``None`` when ``core.hooksPath`` is unset (``git config
-    --get`` exits 1). ``error`` is set ONLY when git itself is unavailable, so
-    the caller can map that to the config-error exit (2) rather than the
-    not-installed exit (1).
-    """
-    try:
-        proc = subprocess.run(
-            ["git", "-C", str(project_root), "config", "--get", "core.hooksPath"],
-            capture_output=True,
-            text=True,
-            encoding="utf-8",
-            errors="replace",
-            check=False,
-        )
-    except FileNotFoundError:
-        return None, "git executable not found on PATH"
-    if proc.returncode != 0:
-        # `git config --get` exits 1 when the key is unset -- not an error here.
-        return None, None
-    value = proc.stdout.strip()
-    return (value or None), None
-
-
-def _resolve_scripts_dir(project_root: Path) -> Path | None:
-    """Return the first candidate scripts dir containing the probe script."""
-    for rel in SCRIPTS_DIR_CANDIDATES:
-        candidate = project_root / Path(rel)
-        if (candidate / SCRIPTS_PROBE).is_file():
-            return candidate
-    return None
-
-
-def evaluate(project_root: Path) -> tuple[int, str]:
-    """Pure function returning ``(exit_code, human_message)``.
-
-    Separated from :func:`main` so tests can drive every state directly.
-    """
-    if not project_root.is_dir():
-        return 2, (
-            f"❌ deft hooks: project root {project_root} does not exist "
-            "(config error)."
-        )
-
-    hooks_path, git_err = _configured_hooks_path(project_root)
-    if git_err:
-        return 2, (
-            f"❌ deft hooks: cannot read core.hooksPath -- {git_err}.\n"
-            "  Recovery: install git (https://git-scm.com/) so the check can run."
-        )
-    if not hooks_path:
-        return 1, (
-            "❌ deft hooks not installed: core.hooksPath is unset.\n"
-            "  Recovery: run `task setup` (or re-run the deft installer)."
-        )
-
-    hooks_dir = Path(hooks_path)
-    if not hooks_dir.is_absolute():
-        hooks_dir = project_root / hooks_path
-
-    if not hooks_dir.is_dir():
-        return 1, (
-            f"❌ deft hooks wired but NON-FUNCTIONAL: core.hooksPath={hooks_path} "
-            f"but the directory {hooks_dir} does not exist (#1463 false-green).\n"
-            "  Recovery: re-run the deft installer / `task setup` to deposit the "
-            "hooks."
-        )
-
-    missing_hooks = [h for h in REQUIRED_HOOKS if not (hooks_dir / h).is_file()]
-    if missing_hooks:
-        return 1, (
-            f"❌ deft hooks wired but NON-FUNCTIONAL: {hooks_dir} is missing "
-            f"{', '.join(missing_hooks)} (#1463 false-green).\n"
-            "  Recovery: re-run the deft installer / `task setup`."
-        )
-
-    # On POSIX the hooks MUST be executable or git silently skips them, leaving
-    # the branch / encoding / destructive-gh-verb gates inert (#1477). The exec
-    # bit does not exist on Windows, so this check is POSIX-only.
-    if os.name == "posix":
-        non_exec = [h for h in REQUIRED_HOOKS if not os.access(hooks_dir / h, os.X_OK)]
-        if non_exec:
-            return 1, (
-                f"❌ deft hooks wired but NON-FUNCTIONAL: {hooks_dir} hook(s) "
-                f"{', '.join(non_exec)} are not executable (git mode is not "
-                "100755); git silently skips non-executable hooks on Unix "
-                "(#1477).\n"
-                "  Recovery: re-run the deft installer / `task setup`, or "
-                "`chmod +x .githooks/pre-commit .githooks/pre-push`."
-            )
-
-    scripts_dir = _resolve_scripts_dir(project_root)
-    if scripts_dir is None:
-        return 1, (
-            "❌ deft hooks wired but NON-FUNCTIONAL: the gate scripts cannot be "
-            "resolved.\n"
-            f"  Looked for {SCRIPTS_PROBE} under: "
-            f"{', '.join(SCRIPTS_DIR_CANDIDATES)} (relative to {project_root}).\n"
-            "  Recovery: re-run the deft installer so the payload is present."
-        )
-
-    missing_scripts = [s for s in GATE_SCRIPTS if not (scripts_dir / s).is_file()]
-    if missing_scripts:
-        return 1, (
-            f"❌ deft hooks wired but NON-FUNCTIONAL: {scripts_dir} is missing "
-            f"gate script(s): {', '.join(missing_scripts)} (#1463 false-green).\n"
-            "  Recovery: re-run the deft installer to restore the payload."
-        )
-
-    return 0, (
-        f"✓ deft hooks installed and functional: core.hooksPath={hooks_path}, "
-        f"hooks {', '.join(REQUIRED_HOOKS)} present, gate scripts resolve under "
-        f"{scripts_dir}."
-    )
-
-
-def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(
-        description=(
-            "Assert the deft git hooks are installed AND functional (#1463). "
-            "Three-state exit: 0 ok / 1 not-installed-or-non-functional / 2 "
-            "config error."
-        )
-    )
-    parser.add_argument(
-        "--project-root",
-        default=".",
-        help="project root to inspect (default: current directory).",
-    )
-    parser.add_argument(
-        "--quiet",
-        action="store_true",
-        help="suppress the human-readable message (exit code only).",
-    )
-    args = parser.parse_args(argv)
-
-    project_root = Path(args.project_root).resolve()
-    code, message = evaluate(project_root)
-    if not args.quiet:
-        stream = sys.stdout if code == 0 else sys.stderr
-        print(message, file=stream)
-    return code
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/scripts/verify_investigation.py

@@ -1,360 +0,0 @@
-#!/usr/bin/env python3
-"""verify_investigation.py -- deterministic validator for forensic investigation ledgers (#1621).
-
-Promotes the prose validator from the vendored ``forensic-research`` reference
-design (``docs/reference/forensic-research/references/investigation-profile.md``
-section "Validator pass") into a deterministic gate. An investigation ledger is
-the thin vBRIEF 0.6 profile (``forensic-research-v1``) written under
-``.tmp/investigations/<id>/investigation.vbrief.json``; this gate is the
-"before Wave 5 / before any causal chat" close check.
-
-Run it against a specific ledger -- it is intentionally NOT part of the
-``task check`` aggregate (like ``verify:story-ready``), because a generic
-``task check`` run has no investigation path to supply:
-
-    task verify:investigation -- --ledger .tmp/investigations/<id>/investigation.vbrief.json
-    uv run python scripts/verify_investigation.py --ledger <path> [--json]
-
-Hard failures (the close is refused -- exit 1):
-
-- ``HF-WAVES``   -- ``metadata.x-investigation.wavesCompleted`` is missing any of
-  waves 1-4 set to ``true`` (falsifier + red-team skipped -- the #1 forensic
-  discipline failure).
-- ``HF-STATUS``  -- ``plan.status`` is still ``running`` (cannot close an
-  investigation that is still in flight).
-- ``HF-FAILED-CLAIM`` -- a claim with ``status: failed`` is missing
-  ``ruledOutReason`` or ``evidenceRefs`` (proof-required disproval).
-- ``HF-COMPLETED-CLAIM`` -- a claim with ``status: completed`` is missing
-  ``evidenceRefs`` (evidence before narrative).
-- ``HF-DANGLING-EV`` -- a claim cites an ``EV-*`` ref that is absent from
-  ``plan.references``.
-- ``HF-BRANCH-NO-EDGE`` -- a branch with ``status: failed`` has no
-  ``invalidates`` edge targeting it (a branch is ruled out only by a falsified
-  child claim).
-
-Soft warnings (printed, do not fail -- the close proceeds):
-
-- ``SW-BLOCKED`` -- a live branch carries ``blocked`` (unknown) claims.
-- ``SW-MULTI-SURVIVOR`` -- more than one branch is ``completed`` (multiple
-  surviving theories).
-
-Exit codes (three-state, mirrors ``scripts/verify_encoding.py``):
-
-- ``0`` -- ledger passes the validator (close-ready / clean).
-- ``1`` -- one or more hard failures (close refused).
-- ``2`` -- config error: ledger path missing / unreadable, malformed JSON,
-  missing required keys, or not a ``forensic-research`` profile ledger.
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-import sys
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Any
-
-REQUIRED_WAVES = ("1", "2", "3", "4")
-
-
-@dataclass
-class Finding:
-    code: str
-    message: str
-
-
-@dataclass
-class ValidationResult:
-    hard_failures: list[Finding] = field(default_factory=list)
-    soft_warnings: list[Finding] = field(default_factory=list)
-
-    @property
-    def ok(self) -> bool:
-        return not self.hard_failures
-
-
-class LedgerConfigError(Exception):
-    """Raised when the ledger cannot be parsed into a validatable shape."""
-
-
-def _iter_claims(items: list[dict[str, Any]]) -> list[tuple[dict[str, Any], dict[str, Any] | None]]:
-    """Flatten branch -> claim items.
-
-    Returns a list of ``(claim, parent_branch)`` tuples for every nested item
-    (depth >= 1). Top-level items are treated as branches; their children are
-    claims. Deeper nesting is flattened with the nearest top-level branch as
-    parent.
-    """
-    out: list[tuple[dict[str, Any], dict[str, Any] | None]] = []
-
-    def walk(node: dict[str, Any], branch: dict[str, Any] | None) -> None:
-        for child in node.get("items", []) or []:
-            if not isinstance(child, dict):
-                continue
-            out.append((child, branch))
-            walk(child, branch)
-
-    for top in items:
-        if not isinstance(top, dict):
-            continue
-        walk(top, top)
-    return out
-
-
-def _claim_meta(claim: dict[str, Any]) -> dict[str, Any]:
-    meta = claim.get("metadata") or {}
-    xclaim = meta.get("x-claim") or {}
-    return xclaim if isinstance(xclaim, dict) else {}
-
-
-def _evidence_refs(xclaim: dict[str, Any]) -> list[str]:
-    refs = xclaim.get("evidenceRefs") or []
-    return [str(r) for r in refs] if isinstance(refs, list) else []
-
-
-def load_ledger(path: Path) -> dict[str, Any]:
-    """Load + structurally validate a ledger file. Raises LedgerConfigError."""
-    if not path.is_file():
-        raise LedgerConfigError(f"ledger not found: {path}")
-    try:
-        raw = path.read_text(encoding="utf-8")
-    except OSError as exc:  # pragma: no cover - unreadable file
-        raise LedgerConfigError(f"ledger unreadable: {path}: {exc}") from exc
-    try:
-        data = json.loads(raw)
-    except json.JSONDecodeError as exc:
-        raise LedgerConfigError(f"ledger is not valid JSON: {path}: {exc}") from exc
-    if not isinstance(data, dict):
-        raise LedgerConfigError(f"ledger root is not an object: {path}")
-    plan = data.get("plan")
-    if not isinstance(plan, dict):
-        raise LedgerConfigError(f"ledger missing 'plan' object: {path}")
-    if not isinstance(plan.get("items"), list):
-        raise LedgerConfigError(f"ledger missing 'plan.items' array: {path}")
-    meta = plan.get("metadata") or {}
-    xinv = meta.get("x-investigation") or {}
-    profile = xinv.get("profile") if isinstance(xinv, dict) else None
-    if profile != "forensic-research-v1":
-        raise LedgerConfigError(
-            f"ledger is not a forensic-research-v1 profile (got {profile!r}): {path}"
-        )
-    return data
-
-
-def validate_ledger(data: dict[str, Any]) -> ValidationResult:
-    """Apply the validator checklist to an already-loaded ledger dict."""
-    result = ValidationResult()
-    plan = data["plan"]
-    items = plan["items"]
-    meta = plan.get("metadata") or {}
-    xinv = meta.get("x-investigation") or {}
-
-    # HF-WAVES: falsifier + red-team must not be skipped.
-    waves = xinv.get("wavesCompleted") or {}
-    if not isinstance(waves, dict):
-        waves = {}
-    missing = [w for w in REQUIRED_WAVES if waves.get(w) is not True]
-    if missing:
-        result.hard_failures.append(
-            Finding(
-                "HF-WAVES",
-                f"wavesCompleted is missing {missing} -- falsifier (3) + "
-                "red-team (4) MUST run before close",
-            )
-        )
-
-    # HF-STATUS: cannot close a running investigation.
-    status = plan.get("status")
-    if status == "running":
-        result.hard_failures.append(
-            Finding(
-                "HF-STATUS",
-                "plan.status is still 'running' -- set it to completed/failed "
-                "before close",
-            )
-        )
-
-    # Build the reference id set for dangling-EV detection. Only the
-    # structured `id` counts -- admitting `title` would let a claim cite a
-    # reference's human-readable label and bypass HF-DANGLING-EV (Greptile P1).
-    ref_ids: set[str] = set()
-    for ref in plan.get("references", []) or []:
-        if isinstance(ref, dict):
-            val = ref.get("id")
-            if isinstance(val, str):
-                ref_ids.add(val)
-
-    claims = _iter_claims(items)
-    for claim, _branch in claims:
-        cid = claim.get("id", "<no-id>")
-        cstatus = claim.get("status")
-        # Only leaf claims (no children) carry evidence obligations.
-        is_branch = bool(claim.get("items"))
-        if is_branch:
-            continue
-        xclaim = _claim_meta(claim)
-        refs = _evidence_refs(xclaim)
-
-        if cstatus == "failed":
-            if not xclaim.get("ruledOutReason") or not refs:
-                result.hard_failures.append(
-                    Finding(
-                        "HF-FAILED-CLAIM",
-                        f"claim {cid} is 'failed' but missing ruledOutReason "
-                        "and/or evidenceRefs (proof-required disproval)",
-                    )
-                )
-        elif cstatus == "completed":
-            if not refs:
-                result.hard_failures.append(
-                    Finding(
-                        "HF-COMPLETED-CLAIM",
-                        f"claim {cid} is 'completed' but cites no evidenceRefs "
-                        "(evidence before narrative)",
-                    )
-                )
-        elif cstatus == "blocked":
-            result.soft_warnings.append(
-                Finding(
-                    "SW-BLOCKED",
-                    f"claim {cid} is 'blocked' (unknown) -- residual "
-                    "uncertainty on a live branch",
-                )
-            )
-
-        # HF-DANGLING-EV: every cited ref must exist in plan.references.
-        for ref in refs:
-            if ref not in ref_ids:
-                result.hard_failures.append(
-                    Finding(
-                        "HF-DANGLING-EV",
-                        f"claim {cid} cites evidence ref {ref!r} not present "
-                        "in plan.references",
-                    )
-                )
-
-    # HF-BRANCH-NO-EDGE: a failed branch needs an invalidates edge.
-    invalidates_targets: set[str] = set()
-    for edge in plan.get("edges", []) or []:
-        if isinstance(edge, dict) and edge.get("type") == "invalidates":
-            tgt = edge.get("to")
-            if isinstance(tgt, str):
-                invalidates_targets.add(tgt)
-
-    completed_branches = 0
-    for top in items:
-        if not isinstance(top, dict):
-            continue
-        bid = top.get("id", "<no-id>")
-        bstatus = top.get("status")
-        if bstatus == "failed" and bid not in invalidates_targets:
-            result.hard_failures.append(
-                Finding(
-                    "HF-BRANCH-NO-EDGE",
-                    f"branch {bid} is 'failed' but has no invalidates edge -- "
-                    "a branch is ruled out only by a falsified child claim",
-                )
-            )
-        if bstatus == "completed":
-            completed_branches += 1
-
-    if completed_branches > 1:
-        result.soft_warnings.append(
-            Finding(
-                "SW-MULTI-SURVIVOR",
-                f"{completed_branches} branches are 'completed' -- multiple "
-                "surviving theories; note in Outcome",
-            )
-        )
-
-    return result
-
-
-def _build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(
-        description="Validate a forensic investigation ledger (#1621).",
-    )
-    parser.add_argument(
-        "--ledger",
-        dest="ledger",
-        help="Path to investigation.vbrief.json (the forensic-research-v1 ledger).",
-    )
-    parser.add_argument(
-        "ledger_positional",
-        nargs="?",
-        help="Positional ledger path (alternative to --ledger).",
-    )
-    parser.add_argument(
-        "--project-root",
-        default=".",
-        help="Project root for resolving a relative --ledger path.",
-    )
-    parser.add_argument(
-        "--json",
-        action="store_true",
-        help="Emit a machine-readable JSON result.",
-    )
-    return parser
-
-
-def main(argv: list[str] | None = None) -> int:
-    parser = _build_parser()
-    args = parser.parse_args(argv)
-
-    ledger_arg = args.ledger or args.ledger_positional
-    if not ledger_arg:
-        print("config error: no ledger path given (--ledger <path>)", file=sys.stderr)
-        return 2
-
-    path = Path(ledger_arg)
-    if not path.is_absolute():
-        path = (Path(args.project_root) / path).resolve()
-
-    try:
-        data = load_ledger(path)
-    except LedgerConfigError as exc:
-        if args.json:
-            print(json.dumps({"exit": 2, "error": str(exc)}))
-        else:
-            print(f"config error: {exc}", file=sys.stderr)
-        return 2
-
-    result = validate_ledger(data)
-
-    if args.json:
-        print(
-            json.dumps(
-                {
-                    "exit": 0 if result.ok else 1,
-                    "hard_failures": [
-                        {"code": f.code, "message": f.message}
-                        for f in result.hard_failures
-                    ],
-                    "soft_warnings": [
-                        {"code": f.code, "message": f.message}
-                        for f in result.soft_warnings
-                    ],
-                }
-            )
-        )
-        return 0 if result.ok else 1
-
-    for warn in result.soft_warnings:
-        print(f"warning [{warn.code}]: {warn.message}")
-
-    if result.ok:
-        print(
-            f"OK investigation ledger passes the validator: {path} "
-            f"({len(result.soft_warnings)} soft warning(s))"
-        )
-        return 0
-
-    print(f"investigation ledger NOT close-ready: {path}", file=sys.stderr)
-    for fail in result.hard_failures:
-        print(f"  hard failure [{fail.code}]: {fail.message}", file=sys.stderr)
-    return 1
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())