@deftai/directive-content 0.55.1 → 0.56.0

package/scripts/_policy_show_cli.py

@@ -0,0 +1,266 @@
+#!/usr/bin/env python3
+"""``task policy:show`` argparse shim (#1148 / N8 of #1119 Wave-2d-1).
+
+Extracted from :mod:`scripts.policy` so the parent module stays well
+under the 1000-line MUST cap from ``coding/coding.md``. The CLI delegates
+to :func:`policy.inspect_all_policies` / :func:`policy.inspect_one_policy`
+for every read; the render layer here is purely cosmetic.
+
+Flags (mirror the #1148 issue body):
+
+* ``--format=text|json`` -- ``text`` is the default human form (one block
+  per field); ``json`` emits the stable schema
+  ``{generated_at, fields: [{name, current, default, source}, ...]}``.
+* ``--changed-only`` -- drop rows whose source is ``default`` so the
+  output focuses on what the operator actually configured. Combines
+  cleanly with ``--format=json`` for ``jq`` consumption.
+* ``--field=<canonical-dotted-path>`` -- show exactly one registered
+  field; exit 2 with the recognised-names list when ``<name>`` is not
+  a registered field. Mutually compatible with ``--format=json``.
+* ``--project-root <path>`` -- override the project root (defaults to
+  ``Path.cwd()``); useful for tests + tools dispatching from outside
+  the consumer working directory.
+
+Exit codes:
+
+* ``0`` -- success (including the "all defaults" + "missing
+  PROJECT-DEFINITION" cases; the verb is informational).
+* ``2`` -- argparse usage error OR unknown ``--field=<name>``.
+
+Pure-stdlib; runs anywhere :mod:`scripts.policy` does.
+"""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import json
+import sys
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+# Make sibling scripts importable when invoked as
+# ``python scripts/_policy_show_cli.py`` (the dispatch shape go-task uses).
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+# UTF-8 self-reconfigure -- the rendered values for ``triageScope`` etc.
+# can include non-ASCII characters that crash cp1252 on Windows.
+for _stream in (sys.stdout, sys.stderr):
+    if hasattr(_stream, "reconfigure"):
+        with contextlib.suppress(AttributeError, ValueError):
+            _stream.reconfigure(encoding="utf-8", errors="replace")
+
+import policy  # noqa: E402  (sibling import after sys.path tweak)
+
+# ---------------------------------------------------------------------------
+# Public helpers (test-injectable)
+# ---------------------------------------------------------------------------
+
+
+def _utc_iso(dt: datetime | None = None) -> str:
+    """ISO-8601 UTC timestamp with seconds precision and ``Z`` suffix."""
+    return (dt or datetime.now(UTC)).astimezone(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def field_to_dict(field: policy.PolicyField) -> dict[str, Any]:
+    """Render one :class:`policy.PolicyField` as a JSON-stable dict.
+
+    Stable key order: ``name``, ``current``, ``default``, ``source``.
+    Stable across releases -- the JSON schema is the scripting contract.
+    """
+    return {
+        "name": field.name,
+        "current": field.current,
+        "default": field.default,
+        "source": field.source,
+    }
+
+
+def render_json(
+    fields: list[policy.PolicyField],
+    *,
+    now: datetime | None = None,
+) -> str:
+    """Render the JSON envelope ``{generated_at, fields: [...]}``.
+
+    ``ensure_ascii=False`` so non-ASCII operator values (rare but
+    possible -- e.g. milestone names with em dashes) survive the
+    serialisation round-trip without ``\\uXXXX`` escaping.
+    """
+    envelope = {
+        "generated_at": _utc_iso(now),
+        "fields": [field_to_dict(f) for f in fields],
+    }
+    return json.dumps(envelope, ensure_ascii=False, indent=2, sort_keys=False)
+
+
+def _format_value(value: Any) -> str:
+    """Render a value for the text format.
+
+    Booleans render as ``true`` / ``false`` (the issue-body example output
+    used lowercase JSON-style booleans). Lists and dicts round-trip
+    through ``json.dumps`` for a stable, copy-pasteable shape. Strings
+    render verbatim; numbers via ``repr`` so floats keep precision.
+    """
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (list, dict)):
+        return json.dumps(value, ensure_ascii=False, sort_keys=False)
+    if isinstance(value, str):
+        return value
+    return repr(value)
+
+
+def render_text(fields: list[policy.PolicyField]) -> str:
+    """Render the human-readable text format from the issue body.
+
+    Each field renders as a four-line block:
+
+    .. code-block:: text
+
+        [policy] <name>
+          current: <value>
+          default: <value>
+          source:  <typed|default|legacy>
+
+    Blocks are separated by a blank line. An empty ``fields`` list
+    (``--changed-only`` against an all-defaults config) renders a single
+    informational line so the operator does not see a blank screen.
+    """
+    if not fields:
+        return (
+            "[policy] (no fields changed)\n"
+            "  All registered policies are at their framework defaults. "
+            "Re-run without `--changed-only` to inspect them."
+        )
+    blocks: list[str] = []
+    for field in fields:
+        block = (
+            f"[policy] {field.name}\n"
+            f"  current: {_format_value(field.current)}\n"
+            f"  default: {_format_value(field.default)}\n"
+            f"  source:  {field.source}"
+        )
+        blocks.append(block)
+    return "\n\n".join(blocks)
+
+
+# ---------------------------------------------------------------------------
+# argparse setup
+# ---------------------------------------------------------------------------
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="task policy:show",
+        description=(
+            "Inspect every registered typed-policy field on "
+            "vbrief/PROJECT-DEFINITION.vbrief.json (#1148 / N8 of #1119)."
+        ),
+    )
+    parser.add_argument(
+        "--format",
+        choices=("text", "json"),
+        default="text",
+        help="Output format (default: text). Use json for stable scripting schema.",
+    )
+    parser.add_argument(
+        "--changed-only",
+        action="store_true",
+        help=(
+            "Filter out fields whose source is 'default'. "
+            "Keeps 'typed' and 'legacy' rows only."
+        ),
+    )
+    parser.add_argument(
+        "--field",
+        dest="field",
+        metavar="<name>",
+        default=None,
+        help=(
+            "Show exactly one registered field by canonical dotted path "
+            "(e.g. plan.policy.wipCap). Exits 2 on unknown name."
+        ),
+    )
+    parser.add_argument(
+        "--project-root",
+        dest="project_root",
+        metavar="<path>",
+        default=None,
+        help="Project root (default: current working directory).",
+    )
+    return parser
+
+
+def run_cli(argv: list[str] | None = None) -> int:
+    """Argparse + dispatch for ``task policy:show``.
+
+    Exit 0 in every success path (including all-defaults and missing
+    PROJECT-DEFINITION). Exit 2 for argparse usage errors and for
+    ``--field=<name>`` where ``<name>`` is not a registered field.
+    """
+    parser = _build_parser()
+    try:
+        args = parser.parse_args(argv)
+    except SystemExit as exc:
+        # argparse already emitted its error to stderr; preserve its code.
+        return int(exc.code) if isinstance(exc.code, int) else 2
+
+    project_root = (
+        Path(args.project_root).resolve() if args.project_root else Path.cwd()
+    )
+
+    # Surface a friendly informational line on missing PROJECT-DEFINITION so
+    # the operator understands why every row will be at default. Exit 0;
+    # show is informational by contract.
+    pd_path = project_root / policy.PROJECT_DEFINITION_REL_PATH
+    if not pd_path.is_file():
+        sys.stderr.write(
+            f"[policy:show] PROJECT-DEFINITION not found at {pd_path}; "
+            "rendering framework defaults.\n"
+        )
+
+    if args.field is not None:
+        return _dispatch_single_field(args, project_root)
+    return _dispatch_all_fields(args, project_root)
+
+
+def _dispatch_single_field(args: argparse.Namespace, project_root: Path) -> int:
+    field = policy.inspect_one_policy(args.field, project_root)
+    if field is None:
+        known = policy.registered_policy_names()
+        sys.stderr.write(
+            f"[policy:show] unknown --field={args.field!r}; "
+            f"registered fields: {known}\n"
+        )
+        return 2
+    # ``--changed-only`` against a single-field default is a no-op render --
+    # operators asking for a single field by name almost always want to see
+    # it regardless of source. The default branch keeps the row; the
+    # ``--changed-only`` filter only fires across the all-fields surface.
+    if args.format == "json":
+        sys.stdout.write(render_json([field]) + "\n")
+    else:
+        sys.stdout.write(render_text([field]) + "\n")
+    return 0
+
+
+def _dispatch_all_fields(args: argparse.Namespace, project_root: Path) -> int:
+    fields = policy.inspect_all_policies(project_root)
+    if args.changed_only:
+        fields = [f for f in fields if f.source != "default"]
+    if args.format == "json":
+        sys.stdout.write(render_json(fields) + "\n")
+    else:
+        sys.stdout.write(render_text(fields) + "\n")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entry point. Alias for :func:`run_cli` so tests can patch it."""
+    return run_cli(argv)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/_precutover.py

@@ -0,0 +1,92 @@
+"""Shared pre-v0.20 document-model detection helpers.
+
+The session-start guard, CLI gate, validator, and migration preflight all need
+the same distinction:
+
+* deprecation redirect stubs are migrated/current enough;
+* generated ``SPECIFICATION.md`` exports from ``task spec:render`` are not
+  hand-authored legacy docs when their source JSON exists, and are fully
+  current vBRIEF artifacts when their lifecycle folders also exist;
+* hand-authored root docs are legacy pre-cutover inputs.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+LIFECYCLE_FOLDERS: tuple[str, ...] = (
+    "proposed",
+    "pending",
+    "active",
+    "completed",
+    "cancelled",
+)
+
+DEPRECATED_REDIRECT_SENTINEL = "<!-- deft:deprecated-redirect -->"
+DEPRECATION_REDIRECT_PURPOSE = "<!-- Purpose: deprecation redirect -->"
+
+GENERATED_SPEC_PURPOSE = "<!-- Purpose: rendered specification -->"
+GENERATED_SPEC_SOURCE = "<!-- Source of truth: vbrief/specification.vbrief.json -->"
+SPEC_SOURCE_RELPATH = Path("vbrief") / "specification.vbrief.json"
+
+
+def missing_lifecycle_folders(project_root: Path) -> list[str]:
+    """Return missing vBRIEF lifecycle folder names for ``project_root``."""
+    vbrief_root = project_root / "vbrief"
+    return [folder for folder in LIFECYCLE_FOLDERS if not (vbrief_root / folder).is_dir()]
+
+
+def has_complete_lifecycle(project_root: Path) -> bool:
+    """Return True when every canonical lifecycle folder exists."""
+    return not missing_lifecycle_folders(project_root)
+
+
+def is_deprecation_redirect(content: str) -> bool:
+    """Return True when markdown content is a migration redirect stub."""
+    return DEPRECATED_REDIRECT_SENTINEL in content or DEPRECATION_REDIRECT_PURPOSE in content
+
+
+def is_generated_specification_export(project_root: Path, content: str) -> bool:
+    """Return True for a generated ``task spec:render`` root export.
+
+    The banner alone is not enough: the declared vBRIEF source must also
+    exist. Lifecycle completeness is checked separately by
+    ``is_current_generated_specification``.
+    """
+    return (
+        GENERATED_SPEC_PURPOSE in content
+        and GENERATED_SPEC_SOURCE in content
+        and (project_root / SPEC_SOURCE_RELPATH).is_file()
+    )
+
+
+def is_current_generated_specification(project_root: Path, content: str) -> bool:
+    """Return True for a fully current ``task spec:render`` root export."""
+    return is_generated_specification_export(project_root, content) and has_complete_lifecycle(
+        project_root
+    )
+
+
+def root_markdown_is_legacy(project_root: Path, filename: str, content: str) -> bool:
+    """Return True if a root markdown artifact should trigger migration."""
+    if is_deprecation_redirect(content):
+        return False
+    if filename == "SPECIFICATION.md" and is_generated_specification_export(project_root, content):
+        return False
+    return filename in {"SPECIFICATION.md", "PROJECT.md"}
+
+
+def detect_pre_cutover_legacy(project_root: Path) -> list[str]:
+    """Return root artifact filenames that are legacy pre-v0.20 inputs."""
+    legacy: list[str] = []
+    for filename in ("SPECIFICATION.md", "PROJECT.md"):
+        candidate = project_root / filename
+        if not candidate.is_file():
+            continue
+        try:
+            content = candidate.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        if root_markdown_is_legacy(project_root, filename, content):
+            legacy.append(filename)
+    return legacy

package/scripts/_project_context.py

@@ -0,0 +1,224 @@
+"""_project_context.py -- resolve consumer project root + GitHub repo slug.
+
+Shared helpers used by ``scope_lifecycle``, ``issue_ingest``,
+``reconcile_issues`` and ``prd_render`` so every script follows the same
+precedence rules and fails loudly when no project context can be inferred.
+
+Precedence for ``resolve_project_root``:
+
+1. ``--project-root`` flag (explicit, highest precedence).
+2. ``$DEFT_PROJECT_ROOT`` environment variable.
+3. Walk upward from CWD looking for a ``vbrief/`` directory or a ``.git``
+   directory -- the first match is the project root.
+4. Fall back to the current working directory ONLY if it visibly looks
+   like a project root (contains either ``vbrief/`` or ``.git``).
+
+If none of those match, the caller gets ``None`` and is expected to emit
+a loud, actionable error -- silently falling back to ``deft/`` is exactly
+the bug that shipped #535 / #538.
+
+Precedence for ``resolve_project_repo``:
+
+1. ``--repo OWNER/NAME`` flag (explicit, highest precedence).
+2. ``$DEFT_PROJECT_REPO`` environment variable.
+3. ``git remote get-url origin`` run from the resolved project root --
+   this is the key anti-regression for #538: deft's own ``.git`` remote
+   (``deftai/directive``) is used only if the project root happens to be
+   deft itself.
+4. ``None`` -- caller must emit a loud error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import subprocess
+from collections.abc import Callable
+from pathlib import Path
+
+from framework_commands import CommandResult, run_framework_command
+
+# Sentinel directories that mark a deft project root.
+_PROJECT_ROOT_SENTINELS = ("vbrief", ".git")
+
+
+def _is_project_root(candidate: Path) -> bool:
+    """Return True if *candidate* contains any deft project-root sentinel."""
+    return any((candidate / sentinel).exists() for sentinel in _PROJECT_ROOT_SENTINELS)
+
+
+def resolve_project_root(
+    cli_project_root: str | None = None,
+    *,
+    start: Path | None = None,
+) -> Path | None:
+    """Resolve the consumer project root using the documented precedence.
+
+    Returns ``None`` when no candidate matches; callers MUST fail loudly
+    in that case (never silently fall back to deft's own directory).
+    """
+    if cli_project_root:
+        candidate = Path(cli_project_root).resolve()
+        if candidate.is_dir():
+            return candidate
+        return None
+
+    env_root = os.environ.get("DEFT_PROJECT_ROOT")
+    if env_root:
+        candidate = Path(env_root).resolve()
+        if candidate.is_dir():
+            return candidate
+        return None
+
+    cwd = (start or Path.cwd()).resolve()
+    # Walk upward from CWD looking for a sentinel.
+    for candidate in (cwd, *cwd.parents):
+        if _is_project_root(candidate):
+            return candidate
+    return None
+
+
+def resolve_project_repo(
+    cli_repo: str | None = None,
+    *,
+    project_root: Path | None = None,
+) -> str | None:
+    """Resolve the consumer GitHub repo (``OWNER/NAME``).
+
+    Returns ``None`` when detection fails so the caller can emit an
+    actionable error. ``project_root`` narrows ``git remote`` detection to
+    the consumer repo; without it we fall back to CWD, which may be wrong
+    under a ``task deft:*`` include (#538).
+    """
+    if cli_repo:
+        slug = _normalise_repo_slug(cli_repo)
+        if slug:
+            return slug
+        return None
+
+    env_repo = os.environ.get("DEFT_PROJECT_REPO")
+    if env_repo:
+        slug = _normalise_repo_slug(env_repo)
+        if slug:
+            return slug
+        # Greptile P2 on #562: fail loudly when the env var is set but
+        # unparseable, to match the explicit-flag path (which returns
+        # None on a malformed value rather than falling through to git
+        # auto-detection). Silent fallback to git is exactly the
+        # anti-pattern this helper was introduced to prevent.
+        return None
+
+    return _detect_repo_from_git(project_root)
+
+
+def _normalise_repo_slug(value: str) -> str | None:
+    r"""Accept ``OWNER/NAME`` or a full GitHub URL, return ``OWNER/NAME``.
+
+    Allows dots in the name component (``acme/dotnet.runtime``,
+    ``acme/my.project.git``) -- the previous ``[^/\.\s]+`` pattern stopped
+    at the first dot and silently truncated the repo name, routing ``gh``
+    calls to the wrong (or non-existent) repository (Greptile P1 on #562).
+    Strips a trailing ``.git`` suffix explicitly so SSH clone URLs still
+    normalise to the bare ``OWNER/NAME`` form.
+    """
+    value = value.strip()
+    if not value:
+        return None
+    match = re.search(
+        r"github\.com[:/]([^/\s]+)/([^/\s]+?)(?:\.git)?(?:\s|$)",
+        value,
+    )
+    if match:
+        return f"{match.group(1)}/{match.group(2)}"
+    if re.match(r"^[^/\s]+/[^/\s]+$", value):
+        return value
+    return None
+
+
+def _detect_repo_from_git(project_root: Path | None) -> str | None:
+    """Run ``git remote get-url origin`` in *project_root* (or CWD)."""
+    cwd = str(project_root) if project_root else None
+    try:
+        result = subprocess.run(
+            ["git", "remote", "get-url", "origin"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+            cwd=cwd,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return None
+    if result.returncode != 0:
+        return None
+    return _normalise_repo_slug(result.stdout.strip())
+
+
+def is_framework_source_context(framework_root: Path, project_root: Path) -> bool:
+    """Return True when a task is running from the framework checkout itself.
+
+    Vendored consumer installs execute framework tasks from ``.deft/core`` while
+    the user working directory remains the consumer repo.  Equality of the two
+    lexical absolute roots is the stable distinction: only the source checkout
+    should run source-repo self-tests by default.  Do not resolve symlinks here:
+    a consumer project may symlink ``.deft/core`` to a local framework checkout
+    and should still run the consumer-safe gate.
+    """
+    return Path(os.path.abspath(framework_root)) == Path(os.path.abspath(project_root))
+
+
+def dispatch_task_check(
+    framework_root: Path,
+    project_root: Path,
+    *,
+    runner: Callable[
+        [str, Path, Path],
+        CommandResult | subprocess.CompletedProcess[str],
+    ]
+    | None = None,
+) -> int:
+    """Dispatch ``check`` to the context-appropriate aggregate target."""
+    target = (
+        "check:framework-source"
+        if is_framework_source_context(framework_root, project_root)
+        else "check:consumer"
+    )
+    command_runner = runner or (
+        lambda command, root, framework: run_framework_command(
+            command,
+            project_root=root,
+            framework_root=framework,
+        )
+    )
+    result = command_runner(target, project_root, framework_root)
+    code = getattr(result, "code", None)
+    if code is None:
+        code = result.returncode
+    return int(code)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--dispatch-task-check",
+        action="store_true",
+        help="Dispatch the check aggregate for the current install context.",
+    )
+    parser.add_argument("--framework-root", type=Path)
+    parser.add_argument("--project-root", type=Path)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    if args.dispatch_task_check:
+        if args.framework_root is None or args.project_root is None:
+            raise SystemExit("--framework-root and --project-root are required")
+        return dispatch_task_check(args.framework_root, args.project_root)
+    parser.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())