@deftai/directive-content 0.59.0 → 0.60.0

package/scripts/_session_start_hook.py

@@ -1,205 +0,0 @@
-"""_session_start_hook.py -- session-start ritual sentinel writer (#1269).
-
-Thin wrapper around :func:`scripts.ritual_sentinel.write`. The
-session-start ritual orchestration calls this module at exit to persist
-the sentinel; the module is intentionally minimal so the orchestrator
-side can shell out without re-implementing the on-disk shape.
-
-Today no canonical session-start orchestrator script exists in
-``deft``; this CLI is the entry point a future orchestrator will wire
-into, and meanwhile operators can invoke it manually::
-
-    python scripts/_session_start_hook.py --write
-
-The ``--write`` flag derives the sentinel payload from the current
-``git`` state:
-
-* ``deftVersion`` -- resolved via :mod:`resolve_version` (the same
-  priority chain ``task build`` consumes; #723).
-* ``lastBranch`` -- ``git symbolic-ref --short HEAD`` (with
-  ``git rev-parse --short HEAD`` as the detached-HEAD fallback,
-  recorded as ``"detached:<short-sha>"`` when HEAD is detached).
-* ``lastActiveVbrief`` -- the most-recently-modified
-  ``vbrief/active/*.vbrief.json`` file, recorded as a POSIX-style
-  relative path. If no candidate file exists, the hook exits ``2``
-  with a one-line diagnostic to stderr instead of writing an
-  incomplete sentinel.
-
-Exit codes
-----------
-
-* ``0`` -- sentinel written.
-* ``2`` -- precondition not satisfied (no active vBRIEF, no git repo,
-  etc.). The ritual treats this as fail-open: ritual continues silently.
-* ``1`` -- unexpected error (re-raised :class:`Exception` from the
-  writer's ``except`` branch). Surfaces the underlying error to stderr.
-
-The hook is intentionally side-effect-free beyond the sentinel write;
-it does NOT mutate git state, the cache, or the vBRIEF lifecycle.
-
-Refs #1269.
-"""
-
-from __future__ import annotations
-
-import argparse
-import os
-import subprocess
-import sys
-from pathlib import Path
-
-# Sibling-script import (mirrors the pattern used by
-# ``scripts/resume_conditions.py`` and the other scripts/ modules).
-_SCRIPTS_DIR = Path(__file__).resolve().parent
-if str(_SCRIPTS_DIR) not in sys.path:
-    sys.path.insert(0, str(_SCRIPTS_DIR))
-
-import resolve_version  # type: ignore[import-not-found]  # noqa: E402
-import ritual_sentinel  # type: ignore[import-not-found]  # noqa: E402
-
-
-def _detect_branch(project_root: Path) -> str | None:
-    """Return the current git branch (or short SHA on detached HEAD)."""
-    try:
-        result = subprocess.run(
-            ["git", "symbolic-ref", "--short", "HEAD"],
-            cwd=str(project_root),
-            capture_output=True,
-            text=True,
-            timeout=10,
-            check=False,
-        )
-    except (FileNotFoundError, subprocess.TimeoutExpired):
-        return None
-    if result.returncode == 0:
-        branch = (result.stdout or "").strip()
-        if branch:
-            return branch
-    # Detached HEAD -- fall back to the short SHA so the sentinel still
-    # records *something* the operator can correlate with their checkout.
-    try:
-        rev_result = subprocess.run(
-            ["git", "rev-parse", "--short", "HEAD"],
-            cwd=str(project_root),
-            capture_output=True,
-            text=True,
-            timeout=10,
-            check=False,
-        )
-    except (FileNotFoundError, subprocess.TimeoutExpired):
-        return None
-    if rev_result.returncode == 0:
-        sha = (rev_result.stdout or "").strip()
-        if sha:
-            return f"detached:{sha}"
-    return None
-
-
-def _detect_latest_active_vbrief(project_root: Path) -> str | None:
-    """Return the most-recently-modified active vBRIEF as a POSIX relpath.
-
-    Fail-open across OSError -- a vBRIEF whose ``stat()`` raises
-    (TOCTOU delete between ``glob()`` and ``stat()``, permission
-    denied, broken symlink) is skipped rather than crashing the
-    ritual. Returns ``None`` when no readable candidate survives.
-    """
-    active_dir = project_root / "vbrief" / "active"
-    try:
-        if not active_dir.is_dir():
-            return None
-    except OSError:
-        return None
-    candidates: list[tuple[float, Path]] = []
-    try:
-        children = list(active_dir.glob("*.vbrief.json"))
-    except OSError:
-        return None
-    for child in children:
-        try:
-            if not child.is_file():
-                continue
-            mtime = child.stat().st_mtime
-        except OSError:
-            # Race with another process deleting the file between glob
-            # and stat, or permission denied on a specific entry. Skip.
-            continue
-        candidates.append((mtime, child))
-    if not candidates:
-        return None
-    candidates.sort(key=lambda pair: pair[0], reverse=True)
-    latest = candidates[0][1]
-    try:
-        return latest.relative_to(project_root).as_posix()
-    except ValueError:
-        return None
-
-
-def _build_arg_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(
-        prog="_session_start_hook",
-        description="Write the session-start ritual sentinel (#1269).",
-    )
-    parser.add_argument(
-        "--write",
-        action="store_true",
-        help="Write .deft/last-session.json from the current git state.",
-    )
-    parser.add_argument(
-        "--project-root",
-        type=Path,
-        default=None,
-        help="Project root directory (default: current working directory).",
-    )
-    return parser
-
-
-def main(argv: list[str] | None = None) -> int:
-    args = _build_arg_parser().parse_args(argv)
-    if not args.write:
-        # No-op invocation; print the usage hint to stderr and return 0
-        # so the ritual orchestration is never broken by a missing flag.
-        sys.stderr.write(
-            "_session_start_hook.py: pass --write to persist the sentinel.\n"
-        )
-        return 0
-    project_root: Path = (args.project_root or Path(os.getcwd())).resolve()
-    branch = _detect_branch(project_root)
-    if not branch:
-        sys.stderr.write(
-            "_session_start_hook.py: could not determine current git branch; "
-            "skipping sentinel write.\n"
-        )
-        return 2
-    last_active = _detect_latest_active_vbrief(project_root)
-    if not last_active:
-        sys.stderr.write(
-            "_session_start_hook.py: no active vBRIEF found under "
-            "vbrief/active/; skipping sentinel write.\n"
-        )
-        return 2
-    try:
-        deft_version = resolve_version.resolve_version()
-    except Exception as exc:  # noqa: BLE001 -- best-effort
-        sys.stderr.write(
-            f"_session_start_hook.py: resolve_version failed: {exc}; "
-            "skipping sentinel write.\n"
-        )
-        return 2
-    try:
-        sentinel_path = ritual_sentinel.write(
-            project_root,
-            deft_version=deft_version,
-            last_active_vbrief=last_active,
-            last_branch=branch,
-        )
-    except Exception as exc:  # noqa: BLE001 -- surface to caller
-        sys.stderr.write(
-            f"_session_start_hook.py: sentinel write failed: {exc}\n"
-        )
-        return 1
-    sys.stdout.write(f"{sentinel_path}\n")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main(sys.argv[1:]))

package/scripts/_sor_gate_diff.py

@@ -1,365 +0,0 @@
-"""Diff scanner for the system-of-record architecture gate."""
-
-from __future__ import annotations
-
-import re
-import subprocess
-from pathlib import Path
-from typing import Any
-
-from preflight_architecture_sor import (
-    LOW_RISK_PATH_PREFIXES,
-    LOW_RISK_SUFFIXES,
-    SCANNER_EXEMPT_PATHS,
-    DetectedSignal,
-    GateFinding,
-    GateResult,
-    _format_failure,
-    _load_json_file,
-    _system_of_record,
-    validate_record,
-)
-
-
-def _is_low_risk_path(path: str) -> bool:
-    clean = path.lstrip("./")
-    if clean in SCANNER_EXEMPT_PATHS:
-        return True
-    if Path(clean).suffix.lower() in LOW_RISK_SUFFIXES:
-        return True
-    return clean.startswith(LOW_RISK_PATH_PREFIXES)
-
-
-def _storage_from_line(path: str, line: str) -> str:
-    text = f"{path} {line}".lower()
-    if re.search(r"\.ya?ml\b", text):
-        return "yaml_file"
-    if re.search(r"\.toml\b", text):
-        return "toml_file"
-    if re.search(r"\.(sqlite|sqlite3|db)\b", text):
-        return "sqlite_file"
-    if re.search(r"\.json\b", text):
-        return "json_file"
-    return "filesystem"
-
-
-def _path_name_signal(path: str) -> DetectedSignal | None:
-    if _is_low_risk_path(path):
-        return None
-    name = Path(path).name.lower()
-    if re.search(r"(registry|repository|store|manager|service)", name) and re.search(
-        r"\.(py|js|jsx|ts|tsx|go|rb|java|kt)$", name
-    ):
-        return DetectedSignal(
-            kind="state_module",
-            path=path,
-            line=None,
-            detail="stateful module name",
-        )
-    if re.search(r"migrations?/", path) or re.search(r"\bmigration", name):
-        return DetectedSignal(
-            kind="database_model",
-            path=path,
-            line=None,
-            detail="database migration path",
-            storage="database",
-        )
-    return None
-
-
-def _looks_like_workflow_state_change(stripped: str) -> bool:
-    term = (
-        r"(workflow|workflows|job|jobs|queue|queues|runtime|orchestration|job_queue|"
-        r"workflow_queue|runtime_state|orchestration_state|worker_state|run_state)"
-    )
-    action = (
-        r"(create|schedule|enqueue|dequeue|start|complete|fail|cancel|retry|update|delete|"
-        r"upsert|persist|save|load|restore|claim|lease|dispatch)"
-    )
-
-    if re.match(r"(#|//|/\*|\*)", stripped):
-        return False
-
-    patterns = (
-        rf"\b(def|function|func)\s+({action}_{term}|{term}_{action})\b",
-        r"\b(class|type)\s+\w*"
-        r"(Workflow|Job|Queue|Runtime|Orchestration|WorkerState|RunState)\w*",
-        rf"\b({term})\.(append|add|put|enqueue|dequeue|submit|dispatch|schedule|"
-        rf"start|complete|fail|cancel|retry|update|delete|save|persist)\s*\(",
-        rf"\b({term})\s*\[[^\]]+\]\s*=",
-        rf"\b({term})\s*=\s*(new\s+Map\(|\{{\}}|\[\])",
-        rf"\b({action}_{term}|{term}_{action})\s*\(",
-    )
-    return any(re.search(pattern, stripped, flags=re.IGNORECASE) for pattern in patterns)
-
-
-def _line_signals(path: str, line_no: int | None, line: str) -> list[DetectedSignal]:
-    if _is_low_risk_path(path):
-        return []
-
-    stripped = line.strip()
-    signals: list[DetectedSignal] = []
-
-    if re.search(
-        r"(write_text|write_bytes|fs\.(writeFile|writeFileSync|appendFile|createWriteStream)|"
-        r"Deno\.write(Text)?File|os\.WriteFile|ioutil\.WriteFile|Files\.write|"
-        r"open\([^)]*,\s*['\"][^'\"]*[wax])",
-        stripped,
-    ):
-        signals.append(
-            DetectedSignal(
-                kind="filesystem_write",
-                path=path,
-                line=line_no,
-                detail=stripped,
-                storage=_storage_from_line(path, stripped),
-            )
-        )
-
-    if re.search(r"\b(localStorage|sessionStorage|indexedDB|caches\.open)\b", stripped):
-        signals.append(
-            DetectedSignal(
-                kind="browser_storage",
-                path=path,
-                line=line_no,
-                detail=stripped,
-                storage="browser_storage",
-            )
-        )
-
-    path_name = Path(path).name.lower()
-    if re.search(r"(registry|repository|store|manager)", path_name) and re.search(
-        r"(new\s+Map\(|=\s*\{\}\s*(#|//|$)|:\s*dict\[)",
-        stripped,
-    ):
-        signals.append(
-            DetectedSignal(
-                kind="in_memory_state",
-                path=path,
-                line=line_no,
-                detail=stripped,
-                storage="in_memory",
-            )
-        )
-
-    if re.search(
-        r"(@\w+\.(post|put|patch|delete)\b|\b(router|app)\.(post|put|patch|delete)\s*\(|"
-        r"\b(def|function|func)\s+(create|select|update|delete|upsert)_?)",
-        stripped,
-        flags=re.IGNORECASE,
-    ):
-        signals.append(
-            DetectedSignal(
-                kind="mutation_endpoint",
-                path=path,
-                line=line_no,
-                detail=stripped,
-            )
-        )
-
-    if re.search(
-        r"(CREATE\s+TABLE|ALTER\s+TABLE|sqlalchemy|db\.Column|models\.Model|"
-        r"prisma|typeorm|sequelize|ActiveRecord)",
-        stripped,
-        flags=re.IGNORECASE,
-    ):
-        signals.append(
-            DetectedSignal(
-                kind="database_model",
-                path=path,
-                line=line_no,
-                detail=stripped,
-                storage="database",
-            )
-        )
-
-    if re.search(
-        r"\b(auth|session|permission|membership|role|grant|tenant|organization)\b",
-        stripped,
-        flags=re.IGNORECASE,
-    ):
-        signals.append(
-            DetectedSignal(
-                kind="auth_state",
-                path=path,
-                line=line_no,
-                detail=stripped,
-            )
-        )
-
-    if _looks_like_workflow_state_change(stripped):
-        signals.append(
-            DetectedSignal(
-                kind="workflow_state",
-                path=path,
-                line=line_no,
-                detail=stripped,
-            )
-        )
-
-    return signals
-
-
-def scan_diff(diff_text: str) -> tuple[list[DetectedSignal], list[str]]:
-    """Scan unified diff text for suspicious stateful patterns."""
-    signals: list[DetectedSignal] = []
-    changed_paths: list[str] = []
-    current_path: str | None = None
-    new_line_no: int | None = None
-
-    for raw_line in diff_text.splitlines():
-        if raw_line.startswith("diff --git "):
-            parts = raw_line.split()
-            if len(parts) >= 4:
-                candidate = parts[3]
-                current_path = candidate[2:] if candidate.startswith("b/") else candidate
-                if current_path not in changed_paths:
-                    changed_paths.append(current_path)
-                    path_signal = _path_name_signal(current_path)
-                    if path_signal is not None:
-                        signals.append(path_signal)
-            new_line_no = None
-            continue
-
-        if raw_line.startswith("+++ "):
-            target = raw_line[4:].strip()
-            if target == "/dev/null":
-                current_path = None
-                continue
-            current_path = target[2:] if target.startswith("b/") else target
-            if current_path not in changed_paths:
-                changed_paths.append(current_path)
-                path_signal = _path_name_signal(current_path)
-                if path_signal is not None:
-                    signals.append(path_signal)
-            continue
-
-        if raw_line.startswith("@@ "):
-            match = re.search(r"\+(\d+)", raw_line)
-            new_line_no = int(match.group(1)) if match else None
-            continue
-
-        if current_path is None:
-            continue
-
-        if raw_line.startswith("+") and not raw_line.startswith("+++"):
-            line = raw_line[1:]
-            signals.extend(_line_signals(current_path, new_line_no, line))
-            if new_line_no is not None:
-                new_line_no += 1
-        elif raw_line.startswith("-") and not raw_line.startswith("---"):
-            continue
-        elif new_line_no is not None:
-            new_line_no += 1
-
-    return signals, changed_paths
-
-
-def _git_diff(project_root: Path, base_ref: str) -> tuple[str | None, GateResult | None]:
-    try:
-        proc = subprocess.run(
-            ["git", "diff", "--unified=0", "--no-ext-diff", base_ref, "--"],
-            cwd=str(project_root),
-            capture_output=True,
-            text=True,
-            encoding="utf-8",
-            errors="replace",
-            check=False,
-            timeout=30,
-        )
-    except (OSError, subprocess.TimeoutExpired) as exc:
-        return None, GateResult(
-            2,
-            f"system-of-record gate misconfigured: could not run git diff: {exc}",
-        )
-    if proc.returncode != 0:
-        detail = proc.stderr.strip() or proc.stdout.strip() or f"git diff exited {proc.returncode}"
-        return None, GateResult(
-            2,
-            f"system-of-record gate misconfigured: could not diff against {base_ref}: {detail}",
-        )
-    return proc.stdout, None
-
-
-def _changed_story_records(
-    project_root: Path,
-    changed_paths: list[str],
-) -> tuple[list[tuple[Path, dict[str, Any], dict[str, Any]]], GateResult | None]:
-    records: list[tuple[Path, dict[str, Any], dict[str, Any]]] = []
-    for rel in changed_paths:
-        if not rel.endswith(".vbrief.json"):
-            continue
-        if not rel.startswith(("vbrief/active/", "vbrief/pending/", "vbrief/proposed/")):
-            continue
-        path = project_root / rel
-        payload, error = _load_json_file(path)
-        if error is not None:
-            return [], error
-        assert payload is not None
-        record = _system_of_record(payload)
-        if record is not None:
-            records.append((path, payload, record))
-    return records, None
-
-
-def evaluate_diff_text(
-    diff_text: str,
-    *,
-    project_root: Path,
-    story_path: Path | None = None,
-) -> GateResult:
-    signals, changed_paths = scan_diff(diff_text)
-    if not signals:
-        return GateResult(0, "OK system-of-record gate passed: no stateful diff signals detected.")
-
-    payload: dict[str, Any] | None = None
-    record: dict[str, Any] | None = None
-
-    if story_path is not None:
-        payload, error = _load_json_file(story_path)
-        if error is not None:
-            return error
-        assert payload is not None
-        record = _system_of_record(payload)
-    else:
-        records, error = _changed_story_records(project_root, changed_paths)
-        if error is not None:
-            return error
-        if len(records) == 1:
-            _, payload, record = records[0]
-        elif len(records) > 1:
-            return GateResult(
-                2,
-                "system-of-record gate misconfigured: multiple changed vBRIEFs "
-                "contain system-of-record records; pass --story-path.",
-            )
-
-    if record is None:
-        finding = GateFinding(
-            reason=(
-                "Diff contains stateful persistence signals, but no matching "
-                "architecture.systemOfRecord design record was supplied or changed."
-            ),
-            required_fix=(
-                "Run `task architecture:sor-preflight -- --story-path <path>` "
-                "after adding the design record, or pass --story-path to this diff gate."
-            ),
-            detected_storage=signals[0].storage,
-        )
-        return GateResult(1, _format_failure([finding]), (finding,))
-
-    result = validate_record(record, story_payload=payload, signals=signals)
-    if result.code == 0:
-        return GateResult(
-            0,
-            f"OK system-of-record gate passed: {len(signals)} stateful diff signal(s) matched.",
-        )
-    return result
-
-
-def evaluate_diff(project_root: Path, base_ref: str, story_path: Path | None = None) -> GateResult:
-    diff_text, error = _git_diff(project_root, base_ref)
-    if error is not None:
-        return error
-    assert diff_text is not None
-    return evaluate_diff_text(diff_text, project_root=project_root, story_path=story_path)

package/scripts/_stdio_utf8.py

@@ -1,59 +0,0 @@
-"""_stdio_utf8.py -- Reconfigure sys.stdout / sys.stderr to UTF-8.
-
-Belt-and-suspenders guard for Python scripts under ``scripts/`` that emit
-non-ASCII characters (the ``-- / -> / x / !`` style symbols and unicode
-equivalents used for success / pending / error / warning markers).
-
-The PRIMARY mechanism for UTF-8 stdout in deft is ``PYTHONUTF8=1`` (set at
-the top level of ``Taskfile.yml`` and on every included task per #540). This
-module is the SECONDARY safeguard for three scenarios where the env var
-does not help:
-
-1. Scripts invoked directly (``python scripts/foo.py``) without going
-   through a ``task`` command.
-2. Subprocess invocations where the parent process strips or overrides
-   the environment.
-3. Child Python processes on Windows where the locale-dependent default
-   codec (cp1252 on US-English systems) would otherwise crash on the
-   unicode glyphs printed by several scripts (#540).
-
-Usage::
-
-    from _stdio_utf8 import reconfigure_stdio
-    reconfigure_stdio()
-
-Call once at module top, before any ``print()``. Idempotent: safe to call
-more than once and safe on streams that are already UTF-8.
-"""
-
-from __future__ import annotations
-
-import sys
-
-
-def reconfigure_stdio() -> None:
-    """Force ``sys.stdout`` / ``sys.stderr`` to UTF-8 without error on failure.
-
-    Python 3.7+ exposes ``reconfigure()`` on ``TextIOWrapper`` streams; for
-    redirected / closed / custom streams that lack it, we silently leave
-    encoding untouched. The PYTHONUTF8 env set in the task layer is the
-    primary fix; this function exists to defend against invocations that
-    bypass the task layer entirely.
-    """
-    for stream_name in ("stdout", "stderr"):
-        stream = getattr(sys, stream_name, None)
-        if stream is None:
-            continue
-        encoding = (getattr(stream, "encoding", "") or "").lower()
-        if encoding in ("utf-8", "utf8"):
-            continue
-        reconfigure = getattr(stream, "reconfigure", None)
-        if reconfigure is None:
-            continue
-        try:
-            reconfigure(encoding="utf-8")
-        except (AttributeError, OSError, ValueError):
-            # Reconfigure can fail on streams that aren't TextIOWrapper
-            # (e.g. pytest's capsys, subprocess-captured pipes). Silently
-            # continue -- the env var path remains the primary defence.
-            continue