@deftai/directive-content 0.55.2 → 0.56.0

package/scripts/_session_start_hook.py

@@ -0,0 +1,205 @@
+"""_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

@@ -0,0 +1,365 @@
+"""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

@@ -0,0 +1,59 @@
+"""_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