@deftai/directive-content 0.55.1 → 0.56.0

package/scripts/ts_check_lane.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""Node-toolchain-aware TypeScript lane for `task check` (#1530, #1790).
+
+`task check` -> `check:framework-source` historically ran only the Python
+suite + gates; the TypeScript engine (biome lint, tsc build, vitest) ran only
+in the dedicated CI job. That split let a TS lint/format/test failure pass a
+contributor's local `task check` and redden CI after push (PR #1780: a worker's
+local gate was green while CI biome failed on unformatted files).
+
+This helper closes the gap WITHOUT regressing the documented invariant that
+`check:framework-source` must not hard-require a Node toolchain in Node-less
+environments (the vendored-consumer guard pattern from #1474). When `pnpm` is on
+PATH it runs `pnpm run lint`, `pnpm run build`, and `pnpm run test` in order,
+failing fast on the first non-zero exit. When `pnpm` is absent it prints a clear
+notice and exits 0 -- the TS lane stays validated by the CI job in that case.
+"""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess  # noqa: S404 -- fixed, non-shell pnpm invocations only
+import sys
+from collections.abc import Callable, Sequence
+from pathlib import Path
+from typing import Any
+
+# Run order is deliberate: lint (cheapest, catches the PR #1780 biome class
+# first), then build, then the test suite.
+LANE_COMMANDS: tuple[tuple[str, ...], ...] = (
+    ("run", "lint"),
+    ("run", "build"),
+    ("run", "test"),
+)
+
+SKIP_NOTICE = (
+    "[ts:check-lane] pnpm not found on PATH -- skipping the TypeScript lane "
+    "(build/lint/test). The TS engine stays validated by the dedicated CI job. "
+    "Install the Node toolchain (pnpm) to run the TS lane locally."
+)
+
+
+def _resolve_pnpm() -> str | None:
+    """Return the pnpm executable path, or None when it is not installed."""
+    return shutil.which("pnpm")
+
+
+def run_ts_lane(
+    project_root: Path,
+    *,
+    pnpm: str | None,
+    runner: Callable[..., Any] = subprocess.run,
+    out: Callable[[str], Any] = print,
+) -> int:
+    """Run the TS lane when pnpm is available; skip (exit 0) when it is not.
+
+    `pnpm`, `runner`, and `out` are injected so the guard logic is unit-testable
+    without a real Node toolchain or real subprocess execution.
+    """
+    if not pnpm:
+        out(SKIP_NOTICE)
+        return 0
+
+    for command in LANE_COMMANDS:
+        argv: Sequence[str] = (pnpm, *command)
+        result = runner(argv, cwd=str(project_root))
+        code = getattr(result, "returncode", 0)
+        if code != 0:
+            out(f"[ts:check-lane] `pnpm {' '.join(command)}` failed (exit {code}).")
+            return code
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--project-root",
+        default=".",
+        help="Repo root that owns the pnpm workspace (default: cwd).",
+    )
+    args = parser.parse_args(argv)
+    return run_ts_lane(Path(args.project_root), pnpm=_resolve_pnpm())
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/validate-links.py

@@ -0,0 +1,64 @@
+"""Validate internal links in markdown files."""
+
+import os
+import re
+import sys
+from pathlib import Path
+
+EXCLUDE_DIRS = {
+    ".git", "backup", "node_modules", ".venv", "__pycache__", "dist",
+    ".planning", "specs",  # planning docs and test fixtures
+}
+LINK_RE = re.compile(r"\[([^\]]*)\]\(([^)]+)\)")
+
+# Skip template variables, reference markers, and example-only links
+SKIP_PATTERNS = re.compile(r"[{}@]|^\[|^\./relative-|^path$")
+
+
+def main() -> int:
+    broken = []
+
+    for md in sorted(Path(".").rglob("*.md")):
+        if any(p in md.parts for p in EXCLUDE_DIRS):
+            continue
+        # Skip history/archive/ files
+        if "history" in md.parts and "archive" in md.parts:
+            continue
+        try:
+            text = md.read_text("utf-8", errors="replace")
+            for i, line in enumerate(text.splitlines(), 1):
+                for m in LINK_RE.finditer(line):
+                    target = m.group(2)
+                    # Skip external URLs, anchors, and mailto
+                    if target.startswith(("http://", "https://", "mailto:", "#")):
+                        continue
+                    # Skip template variables and example links
+                    if SKIP_PATTERNS.search(target):
+                        continue
+                    # Strip anchor and query params
+                    clean = target.split("#")[0].split("?")[0]
+                    if not clean:
+                        continue
+                    resolved = (md.parent / clean).resolve()
+                    if not resolved.exists():
+                        broken.append((str(md), i, target))
+        except Exception:
+            pass
+
+    strict = os.environ.get("LINK_CHECK_STRICT", "") == "1" or "--strict" in sys.argv
+
+    if broken:
+        mode = "errors" if strict else "warnings"
+        print(f"Found {len(broken)} broken internal link(s) ({mode}):")
+        for fp, ln, target in broken[:50]:
+            print(f"  {fp}:{ln} -> {target}")
+        if len(broken) > 50:
+            print(f"  ... and {len(broken) - 50} more")
+        return 1 if strict else 0
+
+    print("All internal markdown links valid")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/validate_strategy_output.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""
+validate_strategy_output.py -- Deterministic validation gate for
+strategy output shape (v0.20 contract per #1166 s2).
+
+Enforces that any vbrief/ tree produced by a spec-generating strategy (yolo, interview,
+speckit, rapid, enterprise, ...) conforms to the canonical v0.20 output contract.
+
+See: strategies/v0-20-contract.md (when present) and the parent epic #1166.
+
+Rules enforced (hard fail):
+- All scope vBRIEFs under vbrief/proposed/ (and other lifecycle dirs if present) MUST
+  use the date-prefixed filename convention: YYYY-MM-DD-<slug>.vbrief.json
+  (catches interview-style bare names like "scaffold.vbrief.json").
+- vbrief/PROJECT-DEFINITION.vbrief.json MUST exist (full project identity).
+- vbrief/specification.vbrief.json MUST NOT be present as a strategy-produced artifact
+  (legacy dual-write). The framework's own canonical source-of-truth copy is tolerated,
+  as is a post-cutover full-spec consumer tree where specification.vbrief.json is the
+  canonical source rendered to SPECIFICATION.md and all lifecycle folders exist.
+- If vbrief/ exists, the five standard lifecycle subfolders should be present or the
+  strategy must have created them (proposed/ at minimum for emission).
+
+Exit codes:
+  0 -- conformant (or framework self with tolerated legacy spec.vbrief)
+  1 -- non-conformant output shape (prints actionable errors citing the contract)
+  2 -- usage / invocation error
+
+Usage:
+    uv run python scripts/validate_strategy_output.py [--project-root <path>] [--strict]
+
+Wired into:
+- `task check` (via root Taskfile.yml)
+- skills/deft-directive-build/SKILL.md Pre-Cutover Detection Guard (generalized)
+- CI matrix (via task check)
+
+Story: s2-deterministic-gate under #1166
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+# Filename pattern for v0.20-conformant scope vBRIEFs (date-prefixed).
+# Matches the convention in vbrief/vbrief.md and conventions/vbrief-filenames.md
+DATE_PREFIXED_RE = re.compile(r"^\d{4}-\d{2}-\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*\.vbrief\.json$")
+GENERATED_SPEC_PURPOSE = "<!-- Purpose: rendered specification -->"
+GENERATED_SPEC_SOURCE = "<!-- Source of truth: vbrief/specification.vbrief.json -->"
+LIFECYCLE_DIRS = ("proposed", "pending", "active", "completed", "cancelled")
+
+
+def _is_deft_framework_root(project_root: Path) -> bool:
+    """Heuristic: is this the deft framework source itself?
+    (tolerate its specification.vbrief.json as canonical source, not strategy output)
+    """
+    return (
+        (project_root / "AGENTS.md").exists()
+        and (project_root / "Taskfile.yml").exists()
+        and (project_root / "strategies").is_dir()
+    )
+
+
+def _read_text_safe(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return ""
+
+
+def _has_complete_lifecycle(vbrief_dir: Path) -> bool:
+    return all((vbrief_dir / folder).is_dir() for folder in LIFECYCLE_DIRS)
+
+
+def _is_post_cutover_full_spec_state(project_root: Path) -> bool:
+    """Return True for canonical consumer full-spec state.
+
+    This is deliberately stricter than "specification.vbrief.json exists" so
+    the gate still catches strategy-generated legacy dual-writes. A consumer
+    may keep ``vbrief/specification.vbrief.json`` as the source of truth only
+    after the vBRIEF-centric shape is complete and the root SPECIFICATION.md is
+    a rendered export from that source.
+    """
+    vbrief_dir = project_root / "vbrief"
+    spec_md = _read_text_safe(project_root / "SPECIFICATION.md")
+    return (
+        # Caller already confirmed specification.vbrief.json exists; the
+        # remaining conditions separate canonical state from a legacy dual-write.
+        (vbrief_dir / "PROJECT-DEFINITION.vbrief.json").is_file()
+        and _has_complete_lifecycle(vbrief_dir)
+        and GENERATED_SPEC_PURPOSE in spec_md
+        and GENERATED_SPEC_SOURCE in spec_md
+    )
+
+
+def validate_strategy_output(project_root: Path, strict: bool = False) -> list[str]:
+    """
+    Return list of error strings (empty == pass).
+    """
+    errors: list[str] = []
+    vbrief_dir = project_root / "vbrief"
+
+    if not vbrief_dir.exists():
+        # No vbrief/ produced at all -- some legacy strategies may still do this,
+        # but v0.20 contract requires the lifecycle layout. Flag only in strict mode
+        # or when other signals present; for now soft (strategies are converging).
+        if strict:
+            errors.append(
+                "vbrief/ directory missing entirely. v0.20 strategies must emit at least "
+                "vbrief/proposed/ (with date-prefixed files) + PROJECT-DEFINITION.vbrief.json."
+            )
+        return errors
+
+    # 1. PROJECT-DEFINITION.vbrief.json must exist at vbrief/ root.
+    proj_def = vbrief_dir / "PROJECT-DEFINITION.vbrief.json"
+    if not proj_def.exists():
+        errors.append(
+            "Missing vbrief/PROJECT-DEFINITION.vbrief.json. "
+            "All v0.20-conformant strategy output must include a complete project definition "
+            "(see v0-20-contract.md and task project:render)."
+        )
+
+    # 2. Forbid legacy specification.vbrief.json in generated user projects.
+    #    Tolerate canonical source copies only in the framework tree or in
+    #    complete post-cutover consumer full-spec state.
+    spec_legacy = vbrief_dir / "specification.vbrief.json"
+    if (
+        spec_legacy.exists()
+        and not _is_deft_framework_root(project_root)
+        and not _is_post_cutover_full_spec_state(project_root)
+    ):
+        errors.append(
+            "Legacy artifact vbrief/specification.vbrief.json present. "
+            "v0.20 strategies MUST NOT dual-write the old specification.vbrief.json "
+            "alongside scope vBRIEFs in the lifecycle folders. "
+            "See strategies/v0-20-contract.md (contract) and issue #1166."
+        )
+    # Framework source / post-cutover full-spec state tolerated (canonical spec,
+    # not strategy output).
+
+    # 3. Every .vbrief.json under the lifecycle folders (proposed/ primarily, but all)
+    #    must be date-prefixed. This is the key shape invariant for s2.
+    for dname in LIFECYCLE_DIRS:
+        dpath = vbrief_dir / dname
+        if dpath.exists() and dpath.is_dir():
+            for f in sorted(dpath.glob("*.vbrief.json")):
+                if not DATE_PREFIXED_RE.match(f.name):
+                    errors.append(
+                        f"Non-conformant filename in vbrief/{dname}/: {f.name}. "
+                        "v0.20 requires strict YYYY-MM-DD-<slug>.vbrief.json "
+                        "(date prefix from creation). Bare names (e.g. scaffold.vbrief.json) "
+                        "are pre-v0.20. See strategies/v0-20-contract.md and "
+                        "vbrief/vbrief.md filename convention."
+                    )
+
+    # 4. If proposed/ exists it must not be empty for a strategy that claims to have emitted scope.
+    #    (light check; real emptiness is often valid for trivial specs)
+    #    We rely primarily on the filename rule above.
+
+    return errors
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Deterministic validation gate for v0.20 strategy output shape."
+    )
+    parser.add_argument(
+        "--project-root",
+        type=Path,
+        default=Path("."),
+        help="Root of the project whose vbrief/ tree to validate (default: cwd)",
+    )
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="Treat missing vbrief/ as error (useful in CI for generated projects)",
+    )
+    parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Suppress success message on clean exit",
+    )
+    args = parser.parse_args(argv)
+
+    project_root = args.project_root.resolve()
+    errors = validate_strategy_output(project_root, strict=args.strict)
+
+    if errors:
+        print("❌ Strategy output shape validation FAILED (v0.20 contract gate)", file=sys.stderr)
+        for err in errors:
+            print(f"  • {err}", file=sys.stderr)
+        print(
+            "\nReference: strategies/v0-20-contract.md (once landed) + "
+            "https://github.com/deftai/directive/issues/1166 (s2-deterministic-gate)",
+            file=sys.stderr,
+        )
+        print(
+            "Fix: re-run the emitting strategy after the contract migration "
+            "stories land, or run `task migrate:vbrief` + `task project:render` "
+            "+ `task scope:promote` as appropriate.",
+            file=sys.stderr,
+        )
+        return 1
+
+    if not args.quiet:
+        print("✓ Strategy output shape conforms to v0.20 contract")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/vbrief_activate.py

@@ -0,0 +1,228 @@
+#!/usr/bin/env python3
+"""vbrief_activate.py -- structural lifecycle move pending/ -> active/ (#810).
+
+Companion to ``scripts/preflight_implementation.py``. The preflight gate
+asserts a vBRIEF is eligible for implementation; this helper is the
+ONLY supported way to satisfy it. Behavior:
+
+- Already-active vBRIEFs (folder == ``active`` AND status ==
+  ``running``): print a no-op message and exit 0. Idempotent.
+- Pending vBRIEFs (folder == ``pending``): flip ``plan.status`` from
+  ``pending`` / ``approved`` to ``running``, stamp ``vBRIEFInfo.updated``
+  to current ISO 8601 UTC, atomically move to ``vbrief/active/``.
+- Any other source folder (``proposed``, ``completed``, ``cancelled``,
+  ``active`` with non-running status, foreign folder): reject with an
+  actionable message. Exit 1.
+- Malformed JSON, missing ``plan``, unreadable file: reject. Exit 1.
+
+The atomic move uses :func:`pathlib.Path.replace` (POSIX rename
+semantics on Linux/macOS, MoveFileEx on Windows) so concurrent reads
+never see a half-written destination.
+
+Mirrors the shape of ``scripts/scope_lifecycle.py`` (the existing
+lifecycle tooling) and ``scripts/preflight_implementation.py`` (the
+preflight companion). Pure stdlib.
+"""
+
+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
+
+#: Folders the lifecycle move flows BETWEEN. Source-folder allow-list
+#: defends against silent data loss from accidentally activating a
+#: ``completed/`` or ``cancelled/`` vBRIEF.
+SOURCE_FOLDERS = frozenset({"pending"})
+ACTIVE_FOLDER = "active"
+ELIGIBLE_STATUSES_FOR_FLIP = frozenset({"pending", "approved"})
+TARGET_STATUS = "running"
+
+
+def _utc_now_iso() -> str:
+    """Return an ISO 8601 UTC timestamp with ``Z`` suffix.
+
+    Matches the existing ``vBRIEFInfo.updated`` format used elsewhere
+    in the framework (see ``vbrief/schemas/vbrief-core.schema.json``
+    examples and ``scripts/scope_lifecycle.py``).
+    """
+    return datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _load_vbrief(path: Path) -> tuple[dict[str, Any] | None, str | None]:
+    """Load and validate the vBRIEF payload.
+
+    Returns ``(payload, None)`` on success or ``(None, error_msg)`` on
+    failure. Never raises -- malformed input is reported via the
+    structured error message.
+    """
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        return None, f"Could not read vBRIEF at {path}: {exc}."
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        return None, f"vBRIEF at {path} is not valid JSON: {exc.msg} (line {exc.lineno})."
+    if not isinstance(payload, dict):
+        return None, f"vBRIEF at {path} top-level value is not a JSON object."
+    return payload, None
+
+
+def activate(vbrief_path: Path) -> tuple[int, str]:
+    """Pure activator -- returns ``(exit_code, human_message)``.
+
+    Performs the lifecycle move + status flip + timestamp stamp
+    atomically (load -> validate -> mutate in memory -> write to
+    target -> remove source). Idempotent on already-active inputs.
+    """
+    if not vbrief_path.exists():
+        return 1, f"vBRIEF not found at {vbrief_path}."
+    if not vbrief_path.is_file():
+        return 1, f"vBRIEF path {vbrief_path} is not a regular file."
+
+    payload, err = _load_vbrief(vbrief_path)
+    if err is not None or payload is None:
+        return 1, err or "vBRIEF could not be loaded."
+
+    plan = payload.get("plan")
+    if not isinstance(plan, dict):
+        return 1, f"vBRIEF at {vbrief_path} lacks a `plan` object -- malformed."
+
+    status = plan.get("status")
+    if not isinstance(status, str) or not status:
+        return (
+            1,
+            f"vBRIEF at {vbrief_path} lacks `plan.status` -- malformed.",
+        )
+
+    folder = vbrief_path.parent.name
+
+    # Idempotent no-op: already in the eligible state.
+    if folder == ACTIVE_FOLDER and status == TARGET_STATUS:
+        return 0, f"No-op: {vbrief_path} already active."
+
+    # Reject any other ``active/`` state -- e.g. status ``blocked`` or
+    # ``completed``. These are NOT activations; the operator should use
+    # ``task scope:unblock`` / ``task scope:complete`` etc.
+    if folder == ACTIVE_FOLDER:
+        return (
+            1,
+            f"vBRIEF is already in active/ but plan.status is '{status}', "
+            f"not '{TARGET_STATUS}'. Use the appropriate task (e.g. "
+            f"`task scope:unblock`) instead of `task vbrief:activate`.",
+        )
+
+    # Reject sources outside the allow-list. ``proposed/`` must promote
+    # to ``pending/`` first via ``task scope:promote``; ``completed/``
+    # and ``cancelled/`` are terminal.
+    if folder not in SOURCE_FOLDERS:
+        return (
+            1,
+            f"vBRIEF is in {folder}/ -- only pending/ vBRIEFs can be activated. "
+            f"Use the lifecycle tasks (`task scope:promote`, etc.) to move it "
+            f"into pending/ first.",
+        )
+
+    # Status sanity-check on the source. The schema's enum allows
+    # several pre-implementation states; only those documented as
+    # eligible for the flip are honored here.
+    if status not in ELIGIBLE_STATUSES_FOR_FLIP:
+        return (
+            1,
+            f"plan.status is '{status}' -- only "
+            f"{sorted(ELIGIBLE_STATUSES_FOR_FLIP)} can be flipped to "
+            f"'{TARGET_STATUS}'.",
+        )
+
+    # --- Mutate in memory --------------------------------------------------
+    plan["status"] = TARGET_STATUS
+    info = payload.setdefault("vBRIEFInfo", {})
+    if not isinstance(info, dict):
+        return (
+            1,
+            f"vBRIEF at {vbrief_path} has a non-object `vBRIEFInfo` -- malformed.",
+        )
+    info["updated"] = _utc_now_iso()
+
+    # --- Resolve destination ----------------------------------------------
+    # Walk up two levels from <root>/vbrief/pending/<file>.json to find
+    # the ``vbrief/`` parent, then descend into ``active/``.
+    vbrief_dir = vbrief_path.parent.parent
+    active_dir = vbrief_dir / ACTIVE_FOLDER
+    try:
+        active_dir.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        return 1, f"Could not create {active_dir}: {exc}."
+
+    dest = active_dir / vbrief_path.name
+    if dest.exists():
+        return (
+            1,
+            f"Refusing to overwrite existing destination {dest}. Resolve the "
+            f"collision manually before re-running `task vbrief:activate`.",
+        )
+
+    # --- Atomic write + source removal ------------------------------------
+    # Write to a sibling temp file in the destination directory so
+    # ``Path.replace`` is a same-filesystem rename (atomic on POSIX +
+    # Windows). The source file is removed only after the destination
+    # is durable, so a mid-flight crash leaves the original in place.
+    tmp = dest.with_suffix(dest.suffix + ".tmp")
+    try:
+        tmp.write_text(
+            json.dumps(payload, indent=2, ensure_ascii=False) + "\n",
+            encoding="utf-8",
+        )
+        tmp.replace(dest)
+    except OSError as exc:
+        # Best-effort cleanup of the partial temp file.
+        with contextlib.suppress(OSError):
+            tmp.unlink(missing_ok=True)
+        return 1, f"Could not write {dest}: {exc}."
+
+    try:
+        vbrief_path.unlink()
+    except OSError as exc:
+        return (
+            1,
+            f"Wrote {dest} but could not remove source {vbrief_path}: {exc}. "
+            f"Manual cleanup required.",
+        )
+
+    return 0, f"Activated {vbrief_path.name}: pending/ -> active/ (status: {TARGET_STATUS})."
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="vbrief_activate.py",
+        description=(
+            "Activate a pending vBRIEF: flip plan.status to 'running', "
+            "stamp vBRIEFInfo.updated, atomically move to vbrief/active/. "
+            "Idempotent on already-active inputs (#810)."
+        ),
+    )
+    parser.add_argument(
+        "vbrief_path",
+        help="Path to the candidate vBRIEF JSON file (in vbrief/pending/).",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    code, message = activate(Path(args.vbrief_path))
+    if code == 0:
+        print(message)
+    else:
+        print(message, file=sys.stderr)
+    return code
+
+
+if __name__ == "__main__":
+    sys.exit(main())