@deftai/directive-content 0.59.0 → 0.61.0

package/scripts/ts_check_lane.py

@@ -1,86 +0,0 @@
-#!/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

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

@@ -1,212 +0,0 @@
-#!/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

@@ -1,228 +0,0 @@
-#!/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())