@deftai/directive-content 0.55.2 → 0.56.0

package/scripts/vbrief_validate.py

@@ -0,0 +1,1195 @@
+#!/usr/bin/env python3
+"""
+vbrief_validate.py -- Validate the vBRIEF-centric document model.
+
+Replaces and extends spec_validate.py for the vBRIEF lifecycle folder model.
+Validates individual scope vBRIEFs, PROJECT-DEFINITION.vbrief.json, and
+cross-file consistency.
+
+Usage:
+    uv run python scripts/vbrief_validate.py [--vbrief-dir <path>]
+                                             [--strict-origin-types]
+                                             [--warnings-as-errors]
+
+Exit codes:
+    0 -- valid (may have warnings); also valid with warnings unless
+         --warnings-as-errors is set
+    1 -- validation errors found (or warnings with --warnings-as-errors)
+    2 -- usage error
+
+Story: #333 (RFC #309), #536 (validator CLI flags, schema-trusting D11),
+       #533 (full v0.6 transition -- strict 0.6-only acceptance)
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+# Ensure sibling scripts (`_event_detect`) are importable when this file is
+# run directly. Mirrors the pattern in scripts/migrate_vbrief.py.
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+import _precutover as _precutover  # noqa: E402
+from _precutover import is_current_generated_specification, is_deprecation_redirect  # noqa: E402
+
+DEPRECATED_REDIRECT_SENTINEL = _precutover.DEPRECATED_REDIRECT_SENTINEL
+__all__ = ("DEPRECATED_REDIRECT_SENTINEL",)
+
+
+# #635: Detection-bound emit helper -- lazy-imported so an import-time
+# failure in ``scripts/_event_detect.py`` cannot break the validator's
+# ability to load. The events surface MUST NOT break the wrapped CLI;
+# importing at module level would let an import-time exception in the
+# helper take down ``task check``'s vbrief:validate gate before the
+# call-site ``contextlib.suppress`` could intervene (Greptile P1 on PR
+# #707 -- mirrors the lazy pattern in ``run::_emit_event_safe``).
+# Filename is intentionally distinct from the sibling vBRIEF's
+# ``scripts/_events.py`` (behavioral events) to avoid file-level merge
+# conflicts; post-merge consolidation may unify them under one name.
+def _emit_event(name: str, payload: dict[str, Any]) -> None:
+    """Lazy-import scripts/_event_detect.emit and forward the call."""
+    from _event_detect import emit  # noqa: I001 -- intentional lazy import
+
+    emit(name, payload)
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+# v0.6 Status enum from the canonical schema
+# (https://github.com/deftai/vBRIEF/blob/master/schemas/vbrief-core-0.6.schema.json).
+VALID_STATUSES = frozenset(
+    {
+        "draft",
+        "proposed",
+        "approved",
+        "pending",
+        "running",
+        "completed",
+        "blocked",
+        "failed",
+        "cancelled",
+    }
+)
+
+# Strict v0.6-only acceptance (#533). The canonical schema at
+# vbrief/schemas/vbrief-core.schema.json pins vBRIEFInfo.version to
+# const "0.6"; this validator rejects every other version. Pre-existing
+# v0.5 vBRIEFs are automatically bumped to v0.6 during ``task
+# migrate:vbrief`` (#571); operators who see the error should re-run
+# the migrator on the affected project.
+VALID_VBRIEF_VERSIONS = frozenset({"0.6"})
+
+# D13: status-to-folder mapping. v0.6 adds ``failed`` as a terminal status
+# (#533 / refinement skill Phase 4 ``task scope:fail``); it belongs in
+# ``completed/`` because the scope has reached a terminal state (#537).
+FOLDER_ALLOWED_STATUSES: dict[str, frozenset[str]] = {
+    "proposed": frozenset({"draft", "proposed"}),
+    "pending": frozenset({"approved", "pending"}),
+    "active": frozenset({"running", "blocked"}),
+    "completed": frozenset({"completed", "failed"}),
+    "cancelled": frozenset({"cancelled"}),
+}
+
+LIFECYCLE_FOLDERS = tuple(FOLDER_ALLOWED_STATUSES.keys())
+
+# D7: filename convention YYYY-MM-DD-descriptive-slug.vbrief.json
+FILENAME_PATTERN = re.compile(r"^\d{4}-\d{2}-\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*\.vbrief\.json$")
+
+# D3: expected narrative keys for PROJECT-DEFINITION (per #506 D3).
+# Values are normalized (lowercase, whitespace collapsed) so both the
+# historic lowercase-space ``tech stack`` and the #506 D3 PascalCase
+# ``TechStack`` shapes satisfy the validator.  Comparison normalizes the
+# candidate key the same way.
+PROJECT_DEF_EXPECTED_NARRATIVES = frozenset(
+    {
+        "overview",
+        "techstack",
+    }
+)
+
+
+def _normalize_narrative_key(key: str) -> str:
+    """Normalize a narrative key for D3 comparison.
+
+    Lowercases, strips whitespace, and collapses word separators so
+    ``TechStack`` / ``Tech Stack`` / ``tech stack`` / ``tech-stack`` all
+    compare equal to the canonical ``techstack`` key (#506 D3 / D5).
+    Uses the module-level ``re`` already imported at the top of the file
+    (PR #525 Greptile P2 review).
+    """
+    low = (key or "").lower()
+    return re.sub(r"[\s_\-]+", "", low)
+
+
+def _scope_ids_for_ref_uri(uri: str) -> set[str]:
+    """Return possible PROJECT-DEFINITION registry IDs for a local scope URI."""
+    rel = uri[len("file://") :] if uri.startswith("file://") else uri
+    name = Path(rel).name
+    full_id = name[: -len(".vbrief.json")] if name.endswith(".vbrief.json") else Path(name).stem
+    ids = {full_id}
+    parts = full_id.split("-", 3)
+    if (
+        len(parts) == 4
+        and len(parts[0]) == 4
+        and len(parts[1]) == 2
+        and len(parts[2]) == 2
+        and all(part.isdigit() for part in parts[:3])
+    ):
+        ids.add(parts[3])
+    return ids
+
+
+def _item_local_scope_uris(item: dict, plan: dict) -> list[str]:
+    """Collect local scope URIs that identify a PROJECT-DEFINITION registry item."""
+    uris: list[str] = []
+
+    metadata = item.get("metadata")
+    if isinstance(metadata, dict):
+        source_path = metadata.get("source_path")
+        if isinstance(source_path, str) and source_path:
+            uris.append(source_path)
+        metadata_refs = metadata.get("references")
+        if isinstance(metadata_refs, list):
+            for ref in metadata_refs:
+                if isinstance(ref, dict) and ref.get("type") == "x-vbrief/plan":
+                    uri = ref.get("uri")
+                    if isinstance(uri, str) and uri:
+                        uris.append(uri)
+
+    refs = item.get("references")
+    if isinstance(refs, list):
+        for ref in refs:
+            if isinstance(ref, dict) and ref.get("type") == "x-vbrief/plan":
+                uri = ref.get("uri")
+                if isinstance(uri, str) and uri:
+                    uris.append(uri)
+
+    item_id = item.get("id")
+    item_title = item.get("title")
+    plan_refs = plan.get("references")
+    if isinstance(plan_refs, list):
+        for ref in plan_refs:
+            if not isinstance(ref, dict) or ref.get("type") != "x-vbrief/plan":
+                continue
+            uri = ref.get("uri")
+            if not isinstance(uri, str) or not uri:
+                continue
+            title_matches = isinstance(item_title, str) and ref.get("title") == item_title
+            id_matches = isinstance(item_id, str) and item_id in _scope_ids_for_ref_uri(uri)
+            if title_matches or id_matches:
+                uris.append(uri)
+
+    # Preserve first-seen order while avoiding duplicate diagnostics.
+    return list(dict.fromkeys(uris))
+
+
+def _validate_project_registry_scope_status(
+    item: dict,
+    item_index: int,
+    plan: dict,
+    filepath: Path,
+    vbrief_dir: Path,
+) -> list[str]:
+    """Validate PROJECT-DEFINITION item status against referenced scope status."""
+    errors: list[str] = []
+    item_status = item.get("status")
+    if not isinstance(item_status, str):
+        return errors
+
+    resolved_root = vbrief_dir.resolve()
+    for uri in _item_local_scope_uris(item, plan):
+        if uri.startswith(("http://", "https://", "#")):
+            continue
+        scope_path = _resolve_ref_path(uri, vbrief_dir)
+        if scope_path is None:
+            continue
+        if not scope_path.is_relative_to(resolved_root) or not scope_path.exists():
+            continue
+        try:
+            scope_data = json.loads(scope_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            continue
+        scope_plan = scope_data.get("plan")
+        if not isinstance(scope_plan, dict):
+            continue
+        scope_status = scope_plan.get("status")
+        if isinstance(scope_status, str) and scope_status != item_status:
+            errors.append(
+                f"{filepath}: items[{item_index}] status is {item_status!r} "
+                f"but referenced scope '{uri}' has plan.status {scope_status!r} "
+                "(D3 registry-status)"
+            )
+    return errors
+
+
+# D11: origin reference type patterns.
+#
+# Default behavior (schema-trusting, Option A from #536): ANY reference whose
+# `type` matches `^x-vbrief/` counts as an origin. This matches the v0.6
+# schema pattern and aligns with the shape documented in
+# conventions/references.md and the refinement skill.
+#
+# Strict behavior (opt-in via --strict-origin-types): only the registered
+# allow-list below counts. Teams who want zero tolerance for ad-hoc
+# `x-vbrief/*` values pass --strict-origin-types in CI.
+ORIGIN_TYPE_PATTERN = re.compile(r"^x-vbrief/")
+
+STRICT_ORIGIN_ALLOWLIST = frozenset(
+    {
+        "x-vbrief/plan",
+        "x-vbrief/github-issue",
+        "x-vbrief/github-pr",
+        "x-vbrief/jira-ticket",
+        "x-vbrief/user-request",
+        "x-vbrief/spec-section",
+    }
+)
+
+# Legacy bare origin types accepted for backward compatibility with
+# pre-v0.20 vBRIEFs that pre-date the x-vbrief/* prefix convention.
+# These are accepted unconditionally (independent of --strict-origin-types)
+# so pre-migration vBRIEFs do not regress.
+LEGACY_ORIGIN_TYPES = frozenset(
+    {
+        "github-issue",
+        "jira-ticket",
+        "user-request",
+    }
+)
+
+# Files that should contain the redirect sentinel after migration
+DEPRECATED_FILES = ("SPECIFICATION.md", "PROJECT.md")
+
+
+# ---------------------------------------------------------------------------
+# Schema validation (reuses spec_validate.py logic, extended)
+# ---------------------------------------------------------------------------
+
+
+def validate_vbrief_schema(data: dict, filepath: str) -> list[str]:
+    """Validate vBRIEF structural requirements (v0.6). Returns errors.
+
+    Strictly requires ``vBRIEFInfo.version == "0.6"`` to match the canonical
+    v0.6 schema vendored at ``vbrief/schemas/vbrief-core.schema.json`` (#533).
+    Any v0.5 vBRIEF is auto-bumped to v0.6 during ``task migrate:vbrief``
+    (#571); operators who hit the error should re-run the migrator.
+    """
+    errors: list[str] = []
+
+    # Top-level envelope
+    if "vBRIEFInfo" not in data:
+        errors.append(f"{filepath}: missing required top-level key 'vBRIEFInfo'")
+    else:
+        info = data["vBRIEFInfo"]
+        if not isinstance(info, dict):
+            errors.append(f"{filepath}: 'vBRIEFInfo' must be an object")
+        elif info.get("version") not in VALID_VBRIEF_VERSIONS:
+            # #571: replaced the non-existent "migrator sweep" recovery
+            # pointer with the real command -- the migrator now auto-
+            # bumps v0.5 -> v0.6 on every pre-existing
+            # ``specification.vbrief.json`` / ``plan.vbrief.json`` it
+            # encounters.
+            errors.append(
+                f"{filepath}: 'vBRIEFInfo.version' must be '0.6' "
+                f"(canonical v0.6 schema, #533), got "
+                f"{info.get('version')!r}. Run `task migrate:vbrief` to "
+                f"upgrade pre-existing v0.5 vBRIEFs in-place."
+            )
+
+    if "plan" not in data:
+        errors.append(f"{filepath}: missing required top-level key 'plan'")
+    else:
+        plan = data["plan"]
+        if not isinstance(plan, dict):
+            errors.append(f"{filepath}: 'plan' must be an object")
+        else:
+            for field in ("title", "status", "items"):
+                if field not in plan:
+                    errors.append(f"{filepath}: 'plan' missing required field '{field}'")
+
+            if "title" in plan and (not isinstance(plan["title"], str) or not plan["title"]):
+                errors.append(f"{filepath}: 'plan.title' must be a non-empty string")
+
+            if "status" in plan and plan["status"] not in VALID_STATUSES:
+                errors.append(
+                    f"{filepath}: 'plan.status' invalid: {plan['status']!r} "
+                    f"(expected one of {sorted(VALID_STATUSES)})"
+                )
+
+            # Validate narratives values are strings
+            if "narratives" in plan:
+                _validate_narratives(plan["narratives"], f"{filepath}: plan.narratives", errors)
+
+            if "items" in plan:
+                if not isinstance(plan["items"], list):
+                    errors.append(f"{filepath}: 'plan.items' must be an array")
+                else:
+                    for i, item in enumerate(plan["items"]):
+                        if not isinstance(item, dict):
+                            errors.append(f"{filepath}: plan.items[{i}] must be an object")
+                            continue
+                        _validate_plan_item(item, f"{filepath}: plan.items", errors)
+
+    return errors
+
+
+def _validate_narratives(narratives: object, path: str, errors: list[str]) -> None:
+    """Validate that all values in a narratives object are strings."""
+    if not isinstance(narratives, dict):
+        errors.append(f"{path} must be an object")
+        return
+    for key, value in narratives.items():
+        if not isinstance(value, str):
+            errors.append(f"{path}.{key} must be a string, got {type(value).__name__}")
+
+
+def _validate_plan_item(item: dict, path: str, errors: list[str]) -> None:
+    """Recursively validate a PlanItem and its nested children.
+
+    Per the canonical v0.6 schema, ``PlanItem.items`` is the PREFERRED
+    nested field and ``PlanItem.subItems`` is the deprecated legacy alias
+    kept for backward compatibility (#533 / Greptile P1). Both are accepted
+    here and recursively validated; neither is treated as an error.
+    """
+    item_id = item.get("id", "<no-id>")
+    item_path = f"{path}[{item_id}]"
+
+    if "title" not in item:
+        errors.append(f"{item_path} missing 'title'")
+    if "status" not in item:
+        errors.append(f"{item_path} missing 'status'")
+    elif item["status"] not in VALID_STATUSES:
+        errors.append(f"{item_path} invalid status: {item['status']!r}")
+
+    if "narrative" in item:
+        _validate_narratives(item["narrative"], f"{item_path}.narrative", errors)
+
+    # v0.6 preferred nested field.
+    if "items" in item:
+        if not isinstance(item["items"], list):
+            errors.append(f"{item_path}.items must be an array")
+        else:
+            for j, sub in enumerate(item["items"]):
+                if not isinstance(sub, dict):
+                    errors.append(f"{item_path}.items[{j}] must be an object")
+                    continue
+                _validate_plan_item(sub, f"{item_path}.items", errors)
+
+    # Deprecated legacy alias -- still accepted for backward compatibility.
+    if "subItems" in item:
+        if not isinstance(item["subItems"], list):
+            errors.append(f"{item_path}.subItems must be an array")
+        else:
+            for j, sub in enumerate(item["subItems"]):
+                if not isinstance(sub, dict):
+                    errors.append(f"{item_path}.subItems[{j}] must be an object")
+                    continue
+                _validate_plan_item(sub, f"{item_path}.subItems", errors)
+
+
+# ---------------------------------------------------------------------------
+# D7: Filename convention
+# ---------------------------------------------------------------------------
+
+
+def validate_filename(filepath: Path) -> list[str]:
+    """Check filename matches YYYY-MM-DD-descriptive-slug.vbrief.json."""
+    name = filepath.name
+    if name == "PROJECT-DEFINITION.vbrief.json":
+        return []  # PROJECT-DEFINITION has its own convention
+    if not FILENAME_PATTERN.match(name):
+        return [
+            f"{filepath}: filename '{name}' does not match convention "
+            "YYYY-MM-DD-descriptive-slug.vbrief.json (D7)"
+        ]
+    return []
+
+
+# ---------------------------------------------------------------------------
+# D2: Folder/status consistency
+# ---------------------------------------------------------------------------
+
+
+def validate_folder_status(filepath: Path, data: dict, vbrief_dir: Path) -> list[str]:
+    """Verify plan.status matches the lifecycle folder the file is in."""
+    errors: list[str] = []
+    try:
+        rel = filepath.relative_to(vbrief_dir)
+    except ValueError:
+        return []
+
+    parts = rel.parts
+    if len(parts) < 2:
+        return []  # file is at vbrief/ root (e.g. PROJECT-DEFINITION)
+
+    folder = parts[0]
+    if folder not in FOLDER_ALLOWED_STATUSES:
+        return []  # not in a lifecycle folder
+
+    plan = data.get("plan", {})
+    status = plan.get("status")
+    if status is None:
+        return []  # schema validator already catches missing status
+
+    allowed = FOLDER_ALLOWED_STATUSES[folder]
+    if status not in allowed:
+        errors.append(
+            f"{filepath}: plan.status is '{status}' but file is in "
+            f"'{folder}/' (allowed statuses: {sorted(allowed)}) (D2)"
+        )
+
+    return errors
+
+
+# ---------------------------------------------------------------------------
+# D3: PROJECT-DEFINITION.vbrief.json validator
+# ---------------------------------------------------------------------------
+
+
+def validate_project_definition(filepath: Path, data: dict, vbrief_dir: Path) -> list[str]:
+    """Validate PROJECT-DEFINITION.vbrief.json specific requirements."""
+    errors: list[str] = []
+    resolved_root = vbrief_dir.resolve()
+
+    # Check narratives contains expected keys.  Normalization collapses
+    # word separators so both the historic ``tech stack`` spelling and the
+    # #506 D3 canonical ``TechStack`` shape satisfy the check.
+    plan = data.get("plan", {})
+    narratives = plan.get("narratives", {})
+    if isinstance(narratives, dict):
+        present = {_normalize_narrative_key(k) for k in narratives}
+        for expected in PROJECT_DEF_EXPECTED_NARRATIVES:
+            if expected not in present:
+                errors.append(f"{filepath}: narratives missing expected key '{expected}' (D3)")
+
+    # #1131 (D12): typed plan.policy.triageScope[] validation -- helper
+    # lives in scripts/triage_scope.py so this file does not grow.
+    with contextlib.suppress(Exception):
+        from triage_scope import validate_triage_scope_on_plan  # noqa: I001
+
+        errors.extend(validate_triage_scope_on_plan(plan, filepath))
+
+    # #1133 (D14): typed plan.policy.triageScopeIgnores[] validation --
+    # helper lives in scripts/_triage_scope_ignores.py and is re-exported
+    # from triage_scope so the lazy-import hook pattern mirrors D12.
+    with contextlib.suppress(Exception):
+        from triage_scope import validate_triage_scope_ignores_on_plan  # noqa: I001
+
+        errors.extend(validate_triage_scope_ignores_on_plan(plan, filepath))
+
+    # #1129 (D10): typed triageAutoClassify[] + triageHoldMarkers[] hooks.
+    with contextlib.suppress(Exception):
+        from triage_classify import (
+            validate_triage_auto_classify_on_plan as _ac,
+            validate_triage_hold_markers_on_plan as _hm,
+        )  # noqa: I001,E501
+
+        errors.extend(_ac(plan, filepath))
+        errors.extend(_hm(plan, filepath))
+
+    # #1128 (D11): typed plan.policy.triageRankingLabels[] validation --
+    # helper lives in scripts/triage_queue.py so this file does not grow.
+    with contextlib.suppress(Exception):
+        from triage_queue import validate_triage_ranking_labels_on_plan  # noqa: I001
+
+        errors.extend(validate_triage_ranking_labels_on_plan(plan, filepath))
+
+    # #1124 (D4): typed plan.policy.wipCap validation -- helper lives in
+    # scripts/policy.py so this file does not grow. Mirrors the D10 /
+    # D11 / D12 hook pattern above.
+    with contextlib.suppress(Exception):
+        from policy import validate_wip_cap_on_plan  # noqa: I001
+
+        errors.extend(validate_wip_cap_on_plan(plan, filepath))
+
+    # #1348: typed plan.policy.sessionRitualStalenessHours validation.
+    try:
+        from policy import validate_session_ritual_staleness_hours_on_plan  # noqa: I001
+    except ImportError:
+        pass
+    else:
+        errors.extend(validate_session_ritual_staleness_hours_on_plan(plan, filepath))
+
+    # Check items registry entries reference existing scope vBRIEF files
+    items = plan.get("items", [])
+    if isinstance(items, list):
+        for i, item in enumerate(items):
+            if not isinstance(item, dict):
+                continue
+            errors.extend(
+                _validate_project_registry_scope_status(item, i, plan, filepath, vbrief_dir)
+            )
+            refs = item.get("references", [])
+            if not isinstance(refs, list):
+                refs = []
+            for ref in refs:
+                if not isinstance(ref, dict):
+                    continue
+                uri = ref.get("uri", "")
+                if uri and uri.startswith("file://"):
+                    ref_path = uri.replace("file://", "")
+                    full_path = (vbrief_dir / ref_path).resolve()
+                    if not full_path.is_relative_to(resolved_root):
+                        errors.append(
+                            f"{filepath}: items[{i}] references "
+                            f"'{ref_path}' outside vbrief directory (D3)"
+                        )
+                        continue
+                    if not full_path.exists():
+                        errors.append(
+                            f"{filepath}: items[{i}] references "
+                            f"'{ref_path}' which does not exist (D3)"
+                        )
+                elif uri and not uri.startswith(("http://", "https://", "#")):
+                    # Treat as relative path
+                    full_path = (vbrief_dir / uri).resolve()
+                    if not full_path.is_relative_to(resolved_root):
+                        errors.append(
+                            f"{filepath}: items[{i}] references "
+                            f"'{uri}' outside vbrief directory (D3)"
+                        )
+                        continue
+                    if not full_path.exists():
+                        errors.append(
+                            f"{filepath}: items[{i}] references '{uri}' which does not exist (D3)"
+                        )
+
+    return errors
+
+
+# ---------------------------------------------------------------------------
+# D4: Epic-story bidirectional link validation
+# ---------------------------------------------------------------------------
+
+
+def validate_epic_story_links(
+    all_vbriefs: dict[Path, dict],
+    vbrief_dir: Path,
+    resolved_to_original: dict[Path, Path] | None = None,
+) -> list[str]:
+    """Validate bidirectional references between epic and story vBRIEFs."""
+    errors: list[str] = []
+    path_map = resolved_to_original or {}
+
+    def _display(p: Path) -> str:
+        """Return original path for display if available."""
+        return str(path_map.get(p, p))
+
+    for filepath, data in all_vbriefs.items():
+        plan = data.get("plan", {})
+        fp_display = _display(filepath)
+
+        # Check forward references (epic -> children)
+        refs = plan.get("references", [])
+        if isinstance(refs, list):
+            for ref in refs:
+                if not isinstance(ref, dict):
+                    continue
+                uri = ref.get("uri", "")
+                ref_type = ref.get("type", "")
+                if not uri or not ref_type:
+                    continue
+                # D4 only applies to child plan references
+                if ref_type != "x-vbrief/plan":
+                    continue
+                # Resolve the child path
+                child_path = _resolve_ref_path(uri, vbrief_dir)
+                if child_path is None:
+                    continue
+                if child_path not in all_vbriefs:
+                    if child_path.exists():
+                        continue  # file exists but wasn't loaded
+                    errors.append(
+                        f"{fp_display}: references child '{uri}' which does not exist (D4)"
+                    )
+                    continue
+                # Verify child has planRef back
+                child_data = all_vbriefs[child_path]
+                child_plan = child_data.get("plan", {})
+                if not _has_plan_ref_to(child_plan, filepath, vbrief_dir):
+                    errors.append(
+                        f"{_display(child_path)}: missing planRef back "
+                        f"to parent '{filepath.name}' (D4)"
+                    )
+
+        # Check backward references (story -> parent via planRef)
+        # Scan both plan-level and item-level planRef values
+        for plan_ref in _collect_plan_refs(plan):
+            parent_path = _resolve_ref_path(plan_ref, vbrief_dir)
+            if parent_path and parent_path in all_vbriefs:
+                parent_data = all_vbriefs[parent_path]
+                parent_plan = parent_data.get("plan", {})
+                parent_refs = parent_plan.get("references", [])
+                if isinstance(parent_refs, list):
+                    child_uris = set()
+                    for pref in parent_refs:
+                        if isinstance(pref, dict) and pref.get("type") == "x-vbrief/plan":
+                            child_uris.add(pref.get("uri", ""))
+                    if not _path_in_refs(filepath, child_uris, vbrief_dir):
+                        errors.append(
+                            f"{fp_display}: has planRef to "
+                            f"'{parent_path.name}' but parent "
+                            "does not list this file in "
+                            "references (D4)"
+                        )
+            elif parent_path and not parent_path.exists():
+                errors.append(
+                    f"{fp_display}: planRef references '{plan_ref}' which does not exist (D4)"
+                )
+
+    return errors
+
+
+def _collect_plan_refs(plan: dict) -> list[str]:
+    """Collect all planRef values from plan root and top-level items.
+
+    Note: subItems are intentionally not scanned -- planRef is only valid
+    at the plan root and top-level item levels per vBRIEF convention.
+    """
+    refs: list[str] = []
+    root_ref = plan.get("planRef")
+    if isinstance(root_ref, str) and root_ref:
+        refs.append(root_ref)
+    for item in plan.get("items", []):
+        if isinstance(item, dict):
+            item_ref = item.get("planRef")
+            if isinstance(item_ref, str) and item_ref:
+                refs.append(item_ref)
+    return refs
+
+
+def _resolve_ref_path(uri: str, vbrief_dir: Path) -> Path | None:
+    """Resolve a reference URI to a filesystem path."""
+    if not isinstance(uri, str):
+        return None
+    if uri.startswith("file://"):
+        rel = uri.replace("file://", "")
+        return (vbrief_dir / rel).resolve()
+    if uri.startswith(("http://", "https://", "#")):
+        return None
+    # Treat as relative path
+    return (vbrief_dir / uri).resolve()
+
+
+def _has_plan_ref_to(child_plan: dict, parent_path: Path, vbrief_dir: Path) -> bool:
+    """Check if a plan has a planRef pointing back to parent_path."""
+    plan_ref = child_plan.get("planRef")
+    if plan_ref:
+        resolved = _resolve_ref_path(plan_ref, vbrief_dir)
+        if resolved and resolved == parent_path.resolve():
+            return True
+    # Also check items for planRef
+    for item in child_plan.get("items", []):
+        if isinstance(item, dict):
+            item_ref = item.get("planRef")
+            if item_ref:
+                resolved = _resolve_ref_path(item_ref, vbrief_dir)
+                if resolved and resolved == parent_path.resolve():
+                    return True
+    return False
+
+
+def _path_in_refs(filepath: Path, uris: set[str], vbrief_dir: Path) -> bool:
+    """Check if filepath is referenced by any URI in the set."""
+    resolved_file = filepath.resolve()
+    for uri in uris:
+        resolved = _resolve_ref_path(uri, vbrief_dir)
+        if resolved and resolved == resolved_file:
+            return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# D11: Origin provenance check
+# ---------------------------------------------------------------------------
+
+
+def validate_origin_provenance(
+    filepath: Path,
+    data: dict,
+    vbrief_dir: Path,
+    strict_origin_types: bool = False,
+) -> list[str]:
+    """Warn if a scope vBRIEF in pending/ or active/ has no origin reference.
+
+    Default behavior (schema-trusting): ANY reference whose ``type`` matches
+    ``^x-vbrief/`` counts as an origin. Legacy bare origin types
+    (``github-issue``, ``jira-ticket``, ``user-request``) are also accepted
+    unconditionally for pre-migration vBRIEFs (#536).
+
+    Strict behavior (``strict_origin_types=True``): only values in
+    :data:`STRICT_ORIGIN_ALLOWLIST` count. Legacy bare types continue to be
+    accepted so pre-migration vBRIEFs do not regress.
+    """
+    warnings: list[str] = []
+
+    try:
+        rel = filepath.relative_to(vbrief_dir)
+    except ValueError:
+        return []
+
+    parts = rel.parts
+    if len(parts) < 2:
+        return []
+
+    folder = parts[0]
+    if folder not in ("pending", "active"):
+        return []
+
+    plan = data.get("plan", {})
+    refs = plan.get("references", [])
+    has_origin = False
+    if isinstance(refs, list):
+        for ref in refs:
+            if not isinstance(ref, dict):
+                continue
+            ref_type = ref.get("type", "")
+            if not isinstance(ref_type, str):
+                continue
+
+            # Legacy bare origin types always count (pre-migration vBRIEFs).
+            if ref_type in LEGACY_ORIGIN_TYPES:
+                has_origin = True
+                break
+            # Legacy extended types (e.g. "github-issue-v2") also count for
+            # backward compatibility with pre-v0.20 tooling.
+            if any(
+                ref_type.startswith((f"{legacy}-", f"{legacy}/")) for legacy in LEGACY_ORIGIN_TYPES
+            ):
+                has_origin = True
+                break
+
+            if strict_origin_types:
+                # Allow-list mode: only registered x-vbrief/* values count.
+                if ref_type in STRICT_ORIGIN_ALLOWLIST:
+                    has_origin = True
+                    break
+            else:
+                # Schema-trusting default: any x-vbrief/* value counts.
+                if ORIGIN_TYPE_PATTERN.match(ref_type):
+                    has_origin = True
+                    break
+
+    if not has_origin:
+        if strict_origin_types:
+            warnings.append(
+                f"{filepath}: scope vBRIEF in '{folder}/' has no references "
+                "with an allow-listed origin type (D11; "
+                "--strict-origin-types)"
+            )
+        else:
+            warnings.append(
+                f"{filepath}: scope vBRIEF in '{folder}/' has no references "
+                "with an origin type (D11)"
+            )
+
+    return warnings
+
+
+# ---------------------------------------------------------------------------
+# #398: Render staleness detection (PRD.md / SPECIFICATION.md)
+# ---------------------------------------------------------------------------
+
+
+def check_render_staleness(vbrief_dir: Path) -> list[str]:
+    """Warn if PRD.md or SPECIFICATION.md are stale relative to specification.vbrief.json.
+
+    Compares source narratives/items from specification.vbrief.json against
+    the rendered export files.  Returns warning strings for stale files.
+    Skips silently if export files don't exist (#398).
+    """
+    warnings: list[str] = []
+    project_root = vbrief_dir.parent
+    spec_path = vbrief_dir / "specification.vbrief.json"
+
+    if not spec_path.is_file():
+        return warnings
+
+    try:
+        with open(spec_path, encoding="utf-8") as fh:
+            data = json.load(fh)
+    except (json.JSONDecodeError, OSError):
+        return warnings
+
+    plan = data.get("plan", {})
+    if not isinstance(plan, dict):
+        return warnings
+
+    narratives = plan.get("narratives", {})
+    items = plan.get("items", [])
+    title = plan.get("title", "")
+
+    # --- PRD.md ---
+    prd_path = project_root / "PRD.md"
+    if prd_path.is_file():
+        warnings.extend(_check_prd_staleness(prd_path, narratives, title))
+
+    # --- SPECIFICATION.md ---
+    # Note: validate_deprecated_placeholders (called earlier in validate_all)
+    # may also warn about SPECIFICATION.md if it lacks the deprecation redirect
+    # sentinel.  The staleness check here is complementary -- it fires for
+    # rendered exports that have drifted, while the deprecated check fires for
+    # files missing the redirect sentinel.  Both can appear in the same run
+    # during transitional states (e.g. a user ran `task spec:render` after
+    # migration); this is intentional -- the deprecated warning takes priority
+    # for the user's attention.
+    spec_md_path = project_root / "SPECIFICATION.md"
+    if spec_md_path.is_file():
+        warnings.extend(_check_spec_staleness(spec_md_path, narratives, items, title))
+
+    return warnings
+
+
+def _check_prd_staleness(
+    prd_path: Path,
+    narratives: dict,
+    title: str,
+) -> list[str]:
+    """Return a warning if PRD.md does not reflect current source narratives."""
+    try:
+        content = prd_path.read_text(encoding="utf-8")
+    except OSError:
+        return []
+
+    if not isinstance(narratives, dict) or not narratives:
+        return []
+
+    for value in narratives.values():
+        if isinstance(value, str) and value.strip() and value.strip() not in content:
+            return [
+                "PRD.md may be stale relative to "
+                "vbrief/specification.vbrief.json -- "
+                "run `task prd:render` to refresh"
+            ]
+
+    if title and title not in content:
+        return [
+            "PRD.md may be stale relative to "
+            "vbrief/specification.vbrief.json -- "
+            "run `task prd:render` to refresh"
+        ]
+
+    return []
+
+
+def _check_spec_staleness(
+    spec_md_path: Path,
+    narratives: dict,
+    items: list,
+    title: str,
+) -> list[str]:
+    """Return a warning if SPECIFICATION.md does not reflect current source."""
+    try:
+        content = spec_md_path.read_text(encoding="utf-8")
+    except OSError:
+        return []
+
+    # Skip deprecation redirects and current generated specification exports.
+    project_root = spec_md_path.parent
+    if is_deprecation_redirect(content) or is_current_generated_specification(
+        project_root, content
+    ):
+        return []
+
+    msg = (
+        "SPECIFICATION.md may be stale relative to "
+        "vbrief/specification.vbrief.json -- "
+        "run `task spec:render` to refresh"
+    )
+
+    # Check item titles
+    if isinstance(items, list):
+        for item in items:
+            if not isinstance(item, dict):
+                continue
+            item_title = item.get("title", "")
+            if isinstance(item_title, str) and item_title and item_title not in content:
+                return [msg]
+
+    # Check all narrative values (mirrors _check_prd_staleness)
+    if isinstance(narratives, dict):
+        for value in narratives.values():
+            if isinstance(value, str) and value.strip() and value.strip() not in content:
+                return [msg]
+
+    # Check title
+    if title and title not in content:
+        return [msg]
+
+    return []
+
+
+# ---------------------------------------------------------------------------
+# Story S (#334): Post-migration placeholder integrity
+# ---------------------------------------------------------------------------
+
+
+def validate_deprecated_placeholders(
+    vbrief_dir: Path,
+) -> list[str]:
+    """Check that SPECIFICATION.md and PROJECT.md contain the deprecation
+    redirect sentinel if they exist.
+
+    After migration, these files are replaced with redirect stubs containing
+    ``<!-- deft:deprecated-redirect -->``.  If a user or agent replaces the
+    redirect with real content, flag it as a warning.
+
+    Returns a list of warning strings.
+    """
+    warnings: list[str] = []
+    project_root = vbrief_dir.parent
+
+    for filename in DEPRECATED_FILES:
+        filepath = project_root / filename
+        if not filepath.is_file():
+            continue
+        try:
+            content = filepath.read_text(encoding="utf-8")
+        except OSError:
+            continue
+
+        if is_deprecation_redirect(content):
+            continue
+        if filename == "SPECIFICATION.md" and is_current_generated_specification(
+            project_root, content
+        ):
+            continue
+        warnings.append(
+            f"{filename} contains non-redirect content -- "
+            "this file is deprecated; use scope vBRIEFs "
+            "in vbrief/ instead"
+        )
+
+    return warnings
+
+
+# ---------------------------------------------------------------------------
+# Main orchestrator
+# ---------------------------------------------------------------------------
+
+
+def load_vbrief(filepath: Path) -> tuple[dict | None, str | None]:
+    """Load and parse a .vbrief.json file. Returns (data, error)."""
+    try:
+        with open(filepath, encoding="utf-8") as fh:
+            data = json.load(fh)
+        return data, None
+    except json.JSONDecodeError as exc:
+        return None, f"{filepath}: invalid JSON: {exc}"
+    except OSError as exc:
+        return None, f"{filepath}: cannot read: {exc}"
+
+
+def discover_vbriefs(vbrief_dir: Path) -> list[Path]:
+    """Find all .vbrief.json files in lifecycle folders."""
+    files: list[Path] = []
+    for folder in LIFECYCLE_FOLDERS:
+        folder_path = vbrief_dir / folder
+        if folder_path.is_dir():
+            files.extend(sorted(folder_path.glob("*.vbrief.json")))
+    return files
+
+
+def _looks_like_decomposition_draft(data: object) -> bool:
+    """Return whether root JSON has the temporary decomposition-draft shape."""
+    if not isinstance(data, dict):
+        return False
+    stories = data.get("stories", data.get("children"))
+    return isinstance(stories, list | dict)
+
+
+def validate_no_root_decomposition_drafts(vbrief_dir: Path) -> list[str]:
+    """Reject decomposition draft proposals left at the workspace root."""
+    project_root = vbrief_dir.parent
+    errors: list[str] = []
+    for path in sorted(project_root.glob("*.json")):
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, UnicodeDecodeError, json.JSONDecodeError):
+            continue
+        if _looks_like_decomposition_draft(data):
+            errors.append(
+                f"{path}: decomposition draft JSON must not live at workspace root; "
+                "write temporary proposals under vbrief/.eval/decompositions/"
+            )
+    return errors
+
+
+def validate_all(
+    vbrief_dir: Path,
+    strict_origin_types: bool = False,
+) -> tuple[list[str], list[str], int]:
+    """Run all validators. Returns (errors, warnings, scope_count)."""
+    errors: list[str] = []
+    warnings: list[str] = []
+    all_vbriefs: dict[Path, dict] = {}
+    # Map resolved -> original path for consistent error messages
+    resolved_to_original: dict[Path, Path] = {}
+
+    # Discover scope vBRIEFs in lifecycle folders
+    scope_files = discover_vbriefs(vbrief_dir)
+    errors.extend(validate_no_root_decomposition_drafts(vbrief_dir))
+
+    # Validate each scope vBRIEF
+    for filepath in scope_files:
+        data, load_err = load_vbrief(filepath)
+        if load_err:
+            errors.append(load_err)
+            continue
+
+        if data is None:
+            continue
+
+        resolved = filepath.resolve()
+        all_vbriefs[resolved] = data
+        resolved_to_original[resolved] = filepath
+
+        # Schema validation
+        errors.extend(validate_vbrief_schema(data, str(filepath)))
+
+        # Filename convention (D7)
+        errors.extend(validate_filename(filepath))
+
+        # Folder/status consistency (D2)
+        errors.extend(validate_folder_status(filepath, data, vbrief_dir))
+
+        # Origin provenance (D11) -- warnings only
+        warnings.extend(
+            validate_origin_provenance(
+                filepath,
+                data,
+                vbrief_dir,
+                strict_origin_types=strict_origin_types,
+            )
+        )
+
+    # Validate PROJECT-DEFINITION.vbrief.json if it exists
+    project_def = vbrief_dir / "PROJECT-DEFINITION.vbrief.json"
+    if project_def.exists():
+        data, load_err = load_vbrief(project_def)
+        if load_err:
+            errors.append(load_err)
+        elif data is not None:
+            resolved_pd = project_def.resolve()
+            all_vbriefs[resolved_pd] = data
+            resolved_to_original[resolved_pd] = project_def
+            errors.extend(validate_vbrief_schema(data, str(project_def)))
+            errors.extend(validate_project_definition(project_def, data, vbrief_dir))
+
+    # Epic-story bidirectional link validation (D4)
+    if all_vbriefs:
+        errors.extend(validate_epic_story_links(all_vbriefs, vbrief_dir, resolved_to_original))
+
+    # Post-migration placeholder integrity (Story S #334)
+    warnings.extend(validate_deprecated_placeholders(vbrief_dir))
+
+    # Render staleness check (#398)
+    warnings.extend(check_render_staleness(vbrief_dir))
+
+    # #635: emit vbrief:invalid event when validation surfaced any issue.
+    # Existing CLI exit-code semantics are unchanged (handled by main()).
+    # Events surface MUST NOT break validation, so registry/IO failures
+    # are silently suppressed so existing CLIs remain stable.
+    if errors or warnings:
+        with contextlib.suppress(Exception):
+            _emit_event(
+                "vbrief:invalid",
+                {
+                    "vbrief_dir": str(vbrief_dir.resolve()),
+                    "error_count": len(errors),
+                    "warning_count": len(warnings),
+                    "errors": list(errors),
+                    "warnings": list(warnings),
+                },
+            )
+
+    return errors, warnings, len(scope_files)
+
+
+USAGE = (
+    "Usage: vbrief_validate.py [--vbrief-dir <path>] [--strict-origin-types] [--warnings-as-errors]"
+)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entry point.
+
+    Exit codes (#536):
+        0 -- no errors (warnings tolerated unless --warnings-as-errors is set)
+        1 -- errors, or warnings when --warnings-as-errors is set
+        2 -- usage error (unknown flag / missing argument)
+    """
+    vbrief_dir = Path("vbrief")
+    strict_origin_types = False
+    warnings_as_errors = False
+
+    # Parse args
+    args = list(sys.argv[1:] if argv is None else argv)
+    i = 0
+    while i < len(args):
+        arg = args[i]
+        if arg == "--vbrief-dir" and i + 1 < len(args):
+            vbrief_dir = Path(args[i + 1])
+            i += 2
+        elif arg == "--strict-origin-types":
+            strict_origin_types = True
+            i += 1
+        elif arg == "--warnings-as-errors":
+            warnings_as_errors = True
+            i += 1
+        elif arg in ("-h", "--help"):
+            print(USAGE)
+            return 0
+        else:
+            print(f"Unknown argument: {arg}", file=sys.stderr)
+            print(USAGE, file=sys.stderr)
+            return 2
+
+    if not vbrief_dir.is_dir():
+        # No vbrief directory -- nothing to validate, pass silently
+        print(f"OK: No vbrief directory at {vbrief_dir} -- skipping validation")
+        return 0
+
+    errors, warnings, scope_count = validate_all(
+        vbrief_dir, strict_origin_types=strict_origin_types
+    )
+
+    # Print warnings first, then errors
+    for w in warnings:
+        print(f"WARN: {w}")
+    for e in errors:
+        print(f"FAIL: {e}")
+
+    # Determine exit code up-front so the summary banner reflects it.
+    warnings_escalated = bool(warnings) and warnings_as_errors
+    exit_code = 1 if errors or warnings_escalated else 0
+
+    # Only emit the "OK" banner when we will actually exit 0 (#536 Defect 2).
+    if exit_code == 0:
+        project_def = vbrief_dir / "PROJECT-DEFINITION.vbrief.json"
+        parts = []
+        if scope_count:
+            parts.append(f"{scope_count} scope vBRIEF(s)")
+        if project_def.exists():
+            parts.append("PROJECT-DEFINITION")
+        summary = ", ".join(parts) if parts else "no vBRIEF files"
+        warning_note = f" ({len(warnings)} warning(s))" if warnings else ""
+        print(f"OK: vBRIEF validation passed: {summary}{warning_note}")
+    else:
+        if errors:
+            print(f"\nFAIL: {len(errors)} error(s) found")
+        if warnings_escalated and not errors:
+            print(f"\nFAIL: {len(warnings)} warning(s) treated as errors (--warnings-as-errors)")
+
+    return exit_code
+
+
+if __name__ == "__main__":
+    sys.exit(main())