@deftai/directive-content 0.55.1 → 0.56.0

package/scripts/slug_normalize.py

@@ -0,0 +1,178 @@
+"""slug_normalize.py -- canonical slug normalization for scope vBRIEF filenames (#532).
+
+Single source of truth for the rules laid out in issue #532. Used by
+``scripts/migrate_vbrief.py`` when generating scope vBRIEF filenames so the
+migrator and any future skill / helper that creates scope vBRIEFs all agree
+on how ``YYYY-MM-DD-<slug>.vbrief.json`` slugs are derived.
+
+Rules (per #532 Suggested normalization rules):
+
+1. Normalize Unicode to NFKD; strip combining marks; drop non-ASCII.
+2. Lowercase the entire result.
+3. Strip common Markdown checkbox markers (``[x]``, ``[ ]``) before the
+   punctuation pass so they do not leak into the slug as a literal ``x``.
+4. Replace any run of ``[^a-z0-9]+`` with a single hyphen.
+5. Strip leading and trailing hyphens.
+6. Truncate at word boundaries at or before ``max_len`` (default 60). If the
+   next character after the cut is inside a word, backtrack to the most
+   recent hyphen provided that hyphen is past ``max_len // 2``.
+7. Empty-slug fallback: return ``"untitled"`` when normalization produces
+   an empty string.
+8. Reserved names: if the slug equals a Windows reserved name (``con``,
+   ``prn``, ``aux``, ``nul``, ``com1``-``com9``, ``lpt1``-``lpt9``), append
+   ``-scope``.
+
+Collision handling: :func:`disambiguate_slug` appends ``-2``, ``-3``, ... to
+the normalized slug until the candidate is not in the supplied ``existing``
+set. Callers typically pass a set pre-populated with stems from existing
+lifecycle-folder files.
+
+This module intentionally has no dependency on the rest of the migrator so
+future skills (refinement, setup) can import it without dragging the full
+migration surface.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+
+__all__ = [
+    "WINDOWS_RESERVED",
+    "DEFAULT_MAX_LEN",
+    "normalize_slug",
+    "disambiguate_slug",
+]
+
+# Windows-reserved filename stems (case-insensitive). Matching is performed on
+# the fully normalized slug so ``CON`` -> ``con`` is rejected just like ``con``.
+WINDOWS_RESERVED: frozenset[str] = frozenset(
+    {"con", "prn", "aux", "nul"}
+    | {f"com{i}" for i in range(1, 10)}
+    | {f"lpt{i}" for i in range(1, 10)}
+)
+
+# Default body length per #532. Shorter than the historic ~80 char ceiling so
+# the final ``YYYY-MM-DD-<slug>.vbrief.json`` filename stays well within
+# Windows path limits for deeply nested worktrees.
+DEFAULT_MAX_LEN: int = 60
+
+# Match a leading checkbox marker at a word boundary: ``[x]``, ``[X]``, ``[ ]``.
+# We deliberately only strip leading markers (or those preceded by whitespace)
+# rather than anywhere in the string, so a legitimate ``[x]`` inside a sentence
+# like ``add [x]-axis scaling`` is not mangled.
+_CHECKBOX_RE = re.compile(r"(?:(?<=^)|(?<=\s))\[[ xX]\]")
+
+
+def normalize_slug(text: str, max_len: int = DEFAULT_MAX_LEN) -> str:
+    """Return a filesystem-safe, deterministic slug for ``text``.
+
+    See module docstring for the full rule list.
+
+    Parameters
+    ----------
+    text:
+        Free-form input -- typically a GitHub issue title, ROADMAP line, or
+        spec task body.  ``None`` and empty strings return ``"untitled"``.
+    max_len:
+        Hard ceiling on the returned body length. Default 60. Values less
+        than 1 fall back to ``DEFAULT_MAX_LEN`` so callers cannot accidentally
+        truncate the slug away entirely.
+
+    Returns
+    -------
+    str
+        A slug matching ``^[a-z0-9]+(-[a-z0-9]+)*$`` with length <= ``max_len``.
+    """
+    if not text:
+        return "untitled"
+    if max_len < 1:
+        max_len = DEFAULT_MAX_LEN
+
+    # 1. Unicode NFKD, drop combining marks, drop non-ASCII.
+    decomposed = unicodedata.normalize("NFKD", text)
+    ascii_only = "".join(
+        ch for ch in decomposed if not unicodedata.combining(ch)
+    )
+    ascii_only = ascii_only.encode("ascii", "ignore").decode("ascii")
+
+    # 2. Lowercase.
+    lowered = ascii_only.lower()
+
+    # 3. Strip checkbox markers before the punctuation pass so ``[x]`` does
+    # not leak into the slug as a literal ``x``.
+    stripped = _CHECKBOX_RE.sub(" ", lowered)
+
+    # 4. Collapse non-alphanumeric runs to a single hyphen.
+    hyphenated = re.sub(r"[^a-z0-9]+", "-", stripped)
+
+    # 5. Strip leading/trailing hyphens.
+    trimmed = hyphenated.strip("-")
+
+    # 6. Truncate at word boundaries at or before max_len.
+    if len(trimmed) > max_len:
+        truncated = trimmed[:max_len]
+        # If we cut mid-word, backtrack to the most recent hyphen provided
+        # that hyphen is past max_len // 2 -- otherwise the slug collapses
+        # too aggressively for short limits.
+        if trimmed[max_len] not in "-":
+            last_hyphen = truncated.rfind("-")
+            if last_hyphen > max_len // 2:
+                truncated = truncated[:last_hyphen]
+        trimmed = truncated.rstrip("-")
+
+    # 7. Empty-after-normalization fallback.
+    if not trimmed:
+        return "untitled"
+
+    # 8. Windows reserved names.
+    if trimmed in WINDOWS_RESERVED:
+        return f"{trimmed}-scope"
+
+    return trimmed
+
+
+def disambiguate_slug(
+    slug: str,
+    existing: set[str] | frozenset[str],
+    *,
+    max_len: int = DEFAULT_MAX_LEN,
+) -> str:
+    """Return a collision-free variant of ``slug`` relative to ``existing``.
+
+    Appends ``-2``, ``-3``, ... to ``slug`` until the candidate is not in
+    ``existing``. The suffix always respects ``max_len`` by truncating the
+    body portion when necessary so the final slug remains within the ceiling.
+
+    The function does NOT mutate ``existing``; callers record the returned
+    value themselves once it is adopted.
+    """
+    if slug not in existing:
+        return slug
+
+    base = slug
+    n = 2
+    while True:
+        suffix = f"-{n}"
+        candidate = base + suffix
+        if len(candidate) > max_len:
+            # Trim the base to make room for the suffix; rstrip hyphens so we
+            # do not produce e.g. ``foo--2``.
+            body_budget = max_len - len(suffix)
+            if body_budget < 1:
+                # Pathological short max_len -- just return the base + suffix;
+                # caller's filesystem handling will still reject if absurd.
+                body_budget = 1
+            trimmed = base[:body_budget].rstrip("-") or base[:body_budget]
+            candidate = trimmed + suffix
+        if candidate not in existing:
+            return candidate
+        n += 1
+        # Guard against runaway loops on pathological inputs (e.g. ``existing``
+        # that contains every integer suffix). 10_000 is well above any
+        # reasonable real-world collision depth.
+        if n > 10_000:
+            raise RuntimeError(
+                f"disambiguate_slug: unable to resolve collision for {slug!r} "
+                f"after {n} attempts"
+            )

package/scripts/spec_render.py

@@ -0,0 +1,477 @@
+#!/usr/bin/env python3
+"""
+spec_render.py — Render a vbrief specification JSON file to SPECIFICATION.md.
+
+Usage:
+    uv run python scripts/spec_render.py <spec_file> [out_file] [--include-scopes=on|off]
+
+    spec_file — path to vbrief/specification.vbrief.json
+    out_file  — output path (default: <spec_file's grandparent>/SPECIFICATION.md)
+    --include-scopes=on|off
+              — include (default) or exclude the Implementation Plan section
+                aggregated from vbrief/{pending,active,completed} scope vBRIEFs (#435)
+
+Exit codes:
+    0 — rendered successfully
+    1 — validation failed or status not in ('approved', 'running', 'completed')
+    2 — usage error (no argument provided)
+
+Implementation: IMPLEMENTATION.md Phase 5.2; lifecycle aggregator per #435.
+"""
+
+import json
+import sys
+from pathlib import Path
+
+# Allow co-located import of spec_validate when run as a script
+sys.path.insert(0, str(Path(__file__).parent))
+from _stdio_utf8 import reconfigure_stdio  # noqa: E402
+from spec_validate import validate_spec  # noqa: E402
+
+# UTF-8 stdout guard (#540).
+reconfigure_stdio()
+
+# Declared narrative ordering for SPECIFICATION.md. Covers both the
+# interview/light key set (Overview, ProblemStatement, Goals, UserStories,
+# Requirements, SuccessMetrics, Architecture) and the speckit Phase 2/3 key
+# set (EdgeCases, TechDecisions, ImplementationPhases, PreImplementationGates).
+# Narratives present on the spec render in this declared order; any other
+# narrative keys render after these, sorted alphabetically. See #434.
+SPECIFICATION_NARRATIVE_KEY_ORDER = [
+    "Overview",
+    "ProblemStatement",
+    "Goals",
+    "UserStories",
+    "Requirements",
+    "SuccessMetrics",
+    "EdgeCases",
+    "Architecture",
+    "TechDecisions",
+    "ImplementationPhases",
+    "PreImplementationGates",
+]
+
+# Lifecycle folders walked by the scope aggregator, in render order (#435).
+LIFECYCLE_BUCKETS: tuple[tuple[str, str], ...] = (
+    ("pending", "Pending"),
+    ("active", "Active"),
+    ("completed", "Completed"),
+)
+
+# Canonical 4-line machine-generated banner per
+# ``conventions/machine-generated-banner.md`` (#572). spec:render
+# previously emitted no banner, so downstream heuristics could not
+# distinguish a rendered specification from a hand-authored one -- a
+# correctness gap. Now every rendered SPECIFICATION.md opens with the
+# same four lines as prd:render / roadmap:render.
+_BANNER = (
+    "<!-- AUTO-GENERATED by task spec:render -- DO NOT EDIT MANUALLY -->\n"
+    "<!-- Purpose: rendered specification -->\n"
+    "<!-- Source of truth: vbrief/specification.vbrief.json -->\n"
+    "<!-- Regenerate with: task spec:render -->\n"
+)
+
+# Narrative key resolution order used when rendering a scope's summary line.
+_SCOPE_SUMMARY_NARRATIVES = (
+    "Overview",
+    "Summary",
+    "Description",
+    "ProblemStatement",
+    "Problem",
+    "Outcome",
+)
+
+
+def _read_edge_endpoints(edge: dict) -> tuple[str, str]:
+    """Bilingual edge reader: prefer ``{from, to}``, fall back to ``{source, target}``.
+
+    Mirrors the reader in ``roadmap_render._read_edge_endpoints`` per #458 --
+    when both conventions are present on a single edge, canonical ``from``/``to``
+    wins. Replicated here rather than imported to keep the lifecycle aggregator
+    decoupled from roadmap rendering.
+    """
+    if not isinstance(edge, dict):
+        return "", ""
+    frm = edge.get("from") or edge.get("source", "") or ""
+    to = edge.get("to") or edge.get("target", "") or ""
+    return frm, to
+
+
+def _load_scope_vbriefs(folder: Path) -> list[tuple[str, dict]]:
+    """Load ``*.vbrief.json`` files from a lifecycle folder.
+
+    Returns a list of ``(filename_stem, vbrief_data)`` tuples, sorted by
+    filename. Missing / non-directory / malformed files are skipped silently
+    so the aggregator never prevents a successful render.
+    """
+    if not folder.is_dir():
+        return []
+    out: list[tuple[str, dict]] = []
+    for path in sorted(folder.glob("*.vbrief.json")):
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            continue
+        stem = path.name
+        if stem.endswith(".vbrief.json"):
+            stem = stem[: -len(".vbrief.json")]
+        out.append((stem, data))
+    return out
+
+
+def _scope_id(stem: str, vbrief: dict) -> str:
+    """Resolve a stable identifier for a scope used in cross-scope edge lookup."""
+    plan = vbrief.get("plan", {})
+    if isinstance(plan, dict):
+        plan_id = plan.get("id", "")
+        if isinstance(plan_id, str) and plan_id:
+            return plan_id
+    return stem
+
+
+def _cross_scope_dep_map(scopes: list[tuple[str, dict]]) -> dict[str, list[str]]:
+    """Build a cross-scope dep map using the bilingual edge reader (#458).
+
+    Only edges whose endpoints match scope IDs present in ``scopes`` contribute
+    to ordering; out-of-scope endpoints are ignored silently so a scope cannot
+    silently pin the whole render to an unresolved id.
+    """
+    scope_ids = {_scope_id(stem, vb) for stem, vb in scopes}
+    dep_map: dict[str, list[str]] = {}
+    for _stem, vbrief in scopes:
+        plan = vbrief.get("plan", {})
+        if not isinstance(plan, dict):
+            continue
+        edges = plan.get("edges", [])
+        if not isinstance(edges, list):
+            continue
+        for edge in edges:
+            frm, to = _read_edge_endpoints(edge)
+            if frm in scope_ids and to in scope_ids and frm and to:
+                dep_map.setdefault(to, []).append(frm)
+    return dep_map
+
+
+def _topo_sort_scopes(
+    scopes: list[tuple[str, dict]],
+    dep_map: dict[str, list[str]],
+) -> list[tuple[str, dict]]:
+    """Order scopes by longest dependency chain depth; fall back to filename order."""
+    if not scopes:
+        return []
+    id_by_index = [_scope_id(stem, vb) for stem, vb in scopes]
+    id_to_index = {sid: i for i, sid in enumerate(id_by_index)}
+    depths: dict[str, int] = {}
+
+    def _depth(sid: str, visited: set[str] | None = None) -> int:
+        if sid in depths:
+            return depths[sid]
+        if visited is None:
+            visited = set()
+        if sid in visited:
+            return 0
+        visited.add(sid)
+        deps = [d for d in dep_map.get(sid, []) if d in id_to_index]
+        if not deps:
+            depths[sid] = 0
+            return 0
+        result = max(_depth(d, visited) for d in deps) + 1
+        depths[sid] = result
+        return result
+
+    for sid in id_by_index:
+        _depth(sid)
+
+    ordered_indices = sorted(
+        range(len(scopes)),
+        key=lambda i: (depths.get(id_by_index[i], 0), i),
+    )
+    return [scopes[i] for i in ordered_indices]
+
+
+def _scope_summary_narrative(plan: dict) -> str:
+    """Pick the most informative narrative string for a scope summary line."""
+    if not isinstance(plan, dict):
+        return ""
+    narratives = plan.get("narratives", {})
+    if not isinstance(narratives, dict):
+        return ""
+    for key in _SCOPE_SUMMARY_NARRATIVES:
+        val = narratives.get(key)
+        if isinstance(val, str) and val.strip():
+            return val.strip()
+    # Fallback: first non-empty string narrative in insertion order.
+    for val in narratives.values():
+        if isinstance(val, str) and val.strip():
+            return val.strip()
+    return ""
+
+
+def _split_acceptance(value: object) -> list[str]:
+    """Normalize acceptance text/list values into visible markdown bullets."""
+    if isinstance(value, list):
+        return [str(item).strip() for item in value if str(item).strip()]
+    if not isinstance(value, str):
+        return []
+    parts: list[str] = []
+    for line in value.splitlines():
+        cleaned = line.strip()
+        if not cleaned:
+            continue
+        if cleaned.startswith(("- ", "* ")):
+            cleaned = cleaned[2:].strip()
+        if cleaned:
+            parts.append(cleaned)
+    return parts
+
+
+def _item_acceptance(item: dict) -> list[str]:
+    narrative = item.get("narrative")
+    if not isinstance(narrative, dict):
+        return []
+    return _split_acceptance(narrative.get("Acceptance"))
+
+
+def _render_scope_block(stem: str, vbrief: dict) -> list[str]:
+    """Render a single scope vBRIEF as a markdown block inside Implementation Plan."""
+    plan = vbrief.get("plan", {})
+    if not isinstance(plan, dict):
+        return []
+    title = plan.get("title", stem)
+    status = plan.get("status", "")
+    heading_parts = [f"### {stem}: {title}"]
+    if status:
+        heading_parts[0] += f"  `[{status}]`"
+    lines: list[str] = [heading_parts[0] + "\n"]
+
+    summary = _scope_summary_narrative(plan)
+    if summary:
+        lines.append(f"{summary}\n")
+
+    narratives = plan.get("narratives", {})
+    if isinstance(narratives, dict):
+        scope_acceptance = _split_acceptance(narratives.get("Acceptance"))
+        if scope_acceptance:
+            lines.append("**Scope Acceptance**:\n")
+            for criterion in scope_acceptance:
+                lines.append(f"- {criterion}")
+            lines.append("")
+
+    # Acceptance items -- each plan.items entry rendered as a bullet with status.
+    items = plan.get("items", [])
+    if isinstance(items, list) and items:
+        lines.append("**Acceptance**:\n")
+        for item in items:
+            if not isinstance(item, dict):
+                continue
+            item_title = item.get("title", "Untitled")
+            item_status = item.get("status", "")
+            bullet = f"- {item_title}"
+            if item_status:
+                bullet += f" `[{item_status}]`"
+            lines.append(bullet)
+            for criterion in _item_acceptance(item):
+                if criterion != item_title:
+                    lines.append(f"  - Acceptance: {criterion}")
+        lines.append("")
+    return lines
+
+
+def _aggregate_scope_section(vbrief_dir: Path) -> list[str]:
+    """Build the Implementation Plan section from vbrief/{pending,active,completed}.
+
+    Returns an empty list if no scope vBRIEFs exist in any lifecycle folder.
+    """
+    buckets: list[tuple[str, str, list[tuple[str, dict]]]] = []
+    for folder_name, heading in LIFECYCLE_BUCKETS:
+        scopes = _load_scope_vbriefs(vbrief_dir / folder_name)
+        if folder_name == "completed":
+            # Status pin: only completed scopes rendered under Completed.
+            scopes = [
+                (stem, vb)
+                for stem, vb in scopes
+                if isinstance(vb.get("plan"), dict)
+                and vb["plan"].get("status") == "completed"
+            ]
+        if scopes:
+            buckets.append((folder_name, heading, scopes))
+
+    if not buckets:
+        return []
+
+    lines: list[str] = ["## Implementation Plan\n"]
+    for _folder, heading, scopes in buckets:
+        dep_map = _cross_scope_dep_map(scopes)
+        ordered = _topo_sort_scopes(scopes, dep_map)
+        lines.append(f"### {heading}\n")
+        for stem, vbrief in ordered:
+            lines.extend(_render_scope_block(stem, vbrief))
+    return lines
+
+
+def render_spec(
+    spec_path: str,
+    out_path: str,
+    include_scopes: bool = True,
+) -> tuple[bool, str]:
+    """
+    Render the approved spec at *spec_path* to markdown at *out_path*.
+
+    Returns:
+        (True, success_message) on success.
+        (False, error_message)  on failure.
+    """
+    # Validate first
+    ok, msg = validate_spec(spec_path)
+    if not ok:
+        return False, msg
+
+    with open(spec_path, encoding="utf-8") as fh:
+        spec = json.load(fh)
+
+    # Support vBRIEF v0.5 envelope structure
+    plan = spec.get("plan", {})
+    status = plan.get("status", "") if isinstance(plan, dict) else spec.get("status", "")
+
+    renderable_statuses = ("approved", "running", "completed")
+    if status not in renderable_statuses:
+        return (
+            False,
+            f"⚠ specification.vbrief.json status is '{status}' "
+            f"(expected one of {renderable_statuses})\n"
+            "  Have the user review and set status to one of the"
+            " renderable statuses before rendering.",
+        )
+
+    # Canonical 4-line banner prepended to every rendered SPECIFICATION.md
+    # so operators (and downstream detectors) can recognise the file as
+    # machine-managed and re-run `task spec:render` to regenerate it
+    # (#572).
+    lines: list[str] = [_BANNER]
+
+    if isinstance(plan, dict):
+        title = plan.get("title", "Specification")
+    else:
+        title = plan or spec.get("title", "Specification")
+    lines.append(f"# {title}\n")
+
+    # Render narratives in declared order, then remaining keys alphabetically.
+    # Mirrors prd_render.py behavior -- speckit-shaped specs (ProblemStatement,
+    # Goals, Requirements, etc.) must not be silently dropped (#434).
+    if isinstance(plan, dict):
+        narratives = plan.get("narratives", {})
+        if not isinstance(narratives, dict):
+            narratives = {}
+    else:
+        # Legacy flat-format specs may carry overview/description at top level.
+        legacy_overview = spec.get("overview") or spec.get("description") or ""
+        narratives = {"Overview": legacy_overview} if legacy_overview else {}
+
+    rendered_keys: set[str] = set()
+    for key in SPECIFICATION_NARRATIVE_KEY_ORDER:
+        if key in narratives and narratives[key]:
+            lines.append(f"## {key}\n")
+            lines.append(f"{narratives[key]}\n")
+            rendered_keys.add(key)
+
+    for key in sorted(narratives.keys()):
+        if key in rendered_keys or not narratives.get(key):
+            continue
+        lines.append(f"## {key}\n")
+        lines.append(f"{narratives[key]}\n")
+
+    # Extract items from plan.items (v0.5) or spec.tasks (legacy). Items render
+    # after narratives so hybrid/legacy specs (items + narratives) still produce
+    # complete output.
+    items = plan.get("items", []) if isinstance(plan, dict) else spec.get("tasks", [])
+    for item in items:
+        item_id = item.get("id", "")
+        title_text = item.get("title", "")
+        item_status = item.get("status", "")
+        lines.append(f"## {item_id}: {title_text}  `[{item_status}]`\n")
+
+        # Dependencies from metadata (v0.5) or inline (legacy)
+        deps = None
+        if metadata := item.get("metadata"):
+            deps = metadata.get("dependencies")
+        if not deps:
+            deps = item.get("dependencies")
+        if deps:
+            dep_list = ", ".join(deps)
+            lines.append(f"**Depends on**: {dep_list}\n")
+
+        # Narrative is an object in v0.5, string/list in legacy
+        narrative = item.get("narrative")
+        if isinstance(narrative, dict):
+            for key, val in narrative.items():
+                if key == "Traces":
+                    lines.append(f"**Traces**: {val}\n")
+                elif key == "Acceptance":
+                    for acceptance_line in _split_acceptance(val):
+                        lines.append(f"- {acceptance_line}")
+                    lines.append("")
+                else:
+                    lines.append(f"{val}\n")
+        elif isinstance(narrative, list):
+            for entry in narrative:
+                lines.append(f"- {entry}")
+            lines.append("")
+        elif narrative:
+            lines.append(f"{narrative}\n")
+
+    # Aggregator: append Implementation Plan from lifecycle folders (#435).
+    if include_scopes:
+        vbrief_dir = Path(spec_path).resolve().parent
+        scope_lines = _aggregate_scope_section(vbrief_dir)
+        if scope_lines:
+            lines.extend(scope_lines)
+
+    Path(out_path).write_text("\n".join(lines), encoding="utf-8")
+    return True, f"✓ Rendered to {out_path}"
+
+
+def _parse_include_scopes_flag(argv: list[str]) -> tuple[bool, list[str]]:
+    """Extract ``--include-scopes[=on|off]`` from argv.
+
+    Returns ``(include_scopes, remaining_argv)``. Defaults to True (#435).
+    Accepts ``--include-scopes``, ``--include-scopes=on``, ``--include-scopes=off``,
+    ``--include-scopes=true``, ``--include-scopes=false`` (case-insensitive on value).
+    """
+    include = True
+    remaining: list[str] = []
+    for arg in argv:
+        if arg == "--include-scopes":
+            include = True
+            continue
+        if arg.startswith("--include-scopes="):
+            value = arg.split("=", 1)[1].lower()
+            include = value in ("on", "true", "1", "yes")
+            continue
+        remaining.append(arg)
+    return include, remaining
+
+
+def main() -> int:
+    include_scopes, positional = _parse_include_scopes_flag(sys.argv[1:])
+    if not positional:
+        print(
+            "Usage: spec_render.py <spec_file> [out_file] [--include-scopes=on|off]",
+            file=sys.stderr,
+        )
+        return 2
+
+    spec_path = positional[0]
+    if len(positional) >= 2:
+        out_path = positional[1]
+    else:
+        # Default: place SPECIFICATION.md at the grandparent of the spec file
+        # e.g. vbrief/specification.vbrief.json → SPECIFICATION.md
+        out_path = str(Path(spec_path).resolve().parent.parent / "SPECIFICATION.md")
+
+    ok, message = render_spec(spec_path, out_path, include_scopes=include_scopes)
+    print(message)
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())