@deftai/directive-content 0.55.1 → 0.56.0

package/scripts/vbrief_migrate_conformance.py

@@ -0,0 +1,368 @@
+#!/usr/bin/env python3
+"""vbrief_migrate_conformance.py -- idempotent Category A vBRIEF 0.6 conformance
+migration (#1620).
+
+directive is the vBRIEF reference implementation, yet its own corpus emits a
+handful of bare, non-namespaced keys that are misused / misspelled CORE fields.
+0.6 *permits* unknown fields (they MUST be preserved), so these are not hard
+spec breaks -- but they violate directive's own discipline (consumer usage must
+be core-correct or ``x-directive/`` / ``x-vbrief/`` namespaced, never bare) and
+produced the statusreport #34 false-RED.
+
+This script migrates the **Category A** correctness bugs to their correct core
+home. Category B namespacing (``plan.policy`` -> ``plan["x-directive/policy"]``)
+is DEFERRED to a follow-up because it depends on upstream vBRIEF #12; it is NOT
+touched here.
+
+Migrations (Category A only)
+----------------------------
+
+1. ``plan.planRef`` (plan-LEVEL) that is a bare GitHub ISSUE ref ``"#1348"`` ->
+   append a deduped ``plan.references[]`` entry ``{ "uri":
+   "https://github.com/deftai/directive/issues/1348", "type":
+   "x-vbrief/github-issue", "title": "Issue #1348" }``, then delete ``planRef``.
+   This is the misused-as-issue-pointer pattern that produced the statusreport
+   #34 false-RED.
+
+   IMPORTANT -- what is LEFT UNTOUCHED:
+
+   - A PATH-style plan-level ``planRef`` (e.g. ``"completed/...vbrief.json"``)
+     is the directive epic<->story child->parent linkage that
+     ``scripts/vbrief_validate.py`` D4 validates bidirectionally. Migrating it
+     to ``references[]`` breaks D4 (which reads the back-pointer from
+     ``planRef``), so it is deliberately NOT migrated here. Reconciling that
+     linkage onto ``references[]`` (and reworking D4) is deferred to the
+     Category B follow-up (#1650).
+   - item-LEVEL ``planRef`` is a legitimate 0.6 core field
+     (``PlanItem.planRef``) and is LEFT UNTOUCHED.
+
+   A ``#``-prefixed plan-level ``planRef`` that is NOT a numeric issue ref
+   (e.g. a stale symbolic slug) carries no valid issue/path target and is
+   simply deleted -- the real references already live in ``references[]``.
+
+2. item-level ``description`` (prose) -> item-level ``narrative`` (the core
+   field). ``narrative`` is an object in 0.6, so a string ``description`` is
+   wrapped as ``{ "Description": <prose> }``. When the item already has a
+   ``narrative`` the existing keys win and ``description`` is folded in
+   non-destructively.
+
+3. item-level ``narratives`` (PLURAL -- a copy-paste typo at item level) ->
+   item-level ``narrative`` (SINGULAR). The plan-LEVEL ``narratives`` (plural)
+   is the correct/expected key and is LEFT UNTOUCHED -- only the item-level
+   typo is migrated.
+
+Formatting
+----------
+Files are read / written via ``pathlib.Path.read_text(encoding="utf-8")`` /
+``write_text(..., encoding="utf-8")`` per the #798 PowerShell/encoding rule.
+The output preserves key order (``json.load`` / ``json.dump`` are
+order-preserving) and matches each file's existing formatting -- 2-space
+indent, a trailing newline, and the file's original ``ensure_ascii`` style
+(detected per file) -- so an unchanged file is never rewritten and a changed
+file produces a minimal diff.
+
+Modes
+-----
+- default (write): apply every needed change, print a per-file summary, exit 0.
+- ``--check`` (dry-run): mutate nothing; exit 0 when the corpus is already
+  conformant (a no-op second run), else print the per-file summary and exit 1.
+
+Exit codes
+----------
+- ``0`` -- write mode succeeded, OR ``--check`` found no needed changes.
+- ``1`` -- ``--check`` found needed changes (drift).
+- ``2`` -- config error (``--project-root`` has no ``vbrief/`` directory).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+#: A plan-level ``planRef`` that is a bare GitHub issue ref, e.g. ``"#1348"``.
+_ISSUE_REF = re.compile(r"^#(\d+)$")
+
+#: Canonical issue-URL base for directive. The corpus is single-repo, so a
+#: bare ``#N`` always resolves to deftai/directive (mirrors the existing
+#: ``x-vbrief/github-issue`` references already present across the corpus).
+_ISSUE_URL_BASE = "https://github.com/deftai/directive/issues"
+
+
+def _rename_key_inplace(d: dict, old: str, new: str, new_value: object) -> None:
+    """Replace ``old`` key with ``new`` (value ``new_value``) preserving order.
+
+    Rebuilds the dict so ``new`` occupies ``old``'s position. Caller guarantees
+    ``new`` is not already present (else the existing ``new`` would be dropped).
+    """
+    rebuilt = {}
+    for key, value in d.items():
+        if key == old:
+            rebuilt[new] = new_value
+        else:
+            rebuilt[key] = value
+    d.clear()
+    d.update(rebuilt)
+
+
+def _issue_reference(number: str) -> tuple[dict, str]:
+    """Build the ``x-vbrief/github-issue`` ``references[]`` entry + dedupe-uri."""
+    uri = f"{_ISSUE_URL_BASE}/{number}"
+    return (
+        {"uri": uri, "type": "x-vbrief/github-issue", "title": f"Issue #{number}"},
+        uri,
+    )
+
+
+def _migrate_plan_ref(plan: dict, changes: list[str]) -> None:
+    """Migrate / clean a plan-level ``planRef`` per its value shape.
+
+    - ``"#1348"`` (numeric issue ref) -> deduped ``references[]`` entry, delete.
+    - ``"#some-slug"`` (``#``-prefixed, non-numeric junk) -> delete (the real
+      references already live in ``references[]``).
+    - anything else (a PATH-style child->parent link) -> LEFT UNTOUCHED: it is
+      the D4 epic<->story linkage read by ``scripts/vbrief_validate.py``;
+      migrating it would break that bidirectional check (deferred to #1650).
+    """
+    if "planRef" not in plan:
+        return
+    value = plan["planRef"]
+    sval = value.strip() if isinstance(value, str) else ""
+    match = _ISSUE_REF.match(sval)
+
+    if match is not None:
+        entry, dedupe_uri = _issue_reference(match.group(1))
+        refs = plan.get("references")
+        if isinstance(refs, list):
+            existing = {
+                r.get("uri") for r in refs if isinstance(r, dict) and "uri" in r
+            }
+            if dedupe_uri in existing:
+                del plan["planRef"]
+                changes.append(
+                    f"planRef {value!r} dropped (references[] already has {dedupe_uri})"
+                )
+            else:
+                refs.append(entry)
+                del plan["planRef"]
+                changes.append(f"planRef {value!r} -> references[] (x-vbrief/github-issue)")
+        else:
+            # No references[] yet: put it where planRef was for a minimal diff.
+            _rename_key_inplace(plan, "planRef", "references", [entry])
+            changes.append(
+                f"planRef {value!r} -> new references[] (x-vbrief/github-issue)"
+            )
+        return
+
+    if sval.startswith("#"):
+        del plan["planRef"]
+        changes.append(f"planRef {value!r} removed (non-issue, non-path bare ref)")
+        return
+
+    # Path-style child->parent link: leave it for the D4 validator (see #1650).
+
+
+def _fold_into_narrative(item: dict, source_key: str, changes: list[str]) -> None:
+    """Migrate item-level ``description`` / ``narratives`` -> ``narrative``.
+
+    ``narrative`` is a 0.6 object field. A string source is wrapped under a
+    sensible key; an object source is renamed / merged. An existing
+    ``narrative`` wins on key conflicts (the source is folded in
+    non-destructively).
+    """
+    if source_key not in item:
+        return
+    source = item[source_key]
+    # The wrapper key used when the source is a bare string.
+    wrap_key = "Description" if source_key == "description" else "Narrative"
+
+    if "narrative" not in item:
+        if isinstance(source, dict):
+            new_value: object = dict(source)
+        else:
+            new_value = {wrap_key: source}
+        _rename_key_inplace(item, source_key, "narrative", new_value)
+        changes.append(f"item {source_key} -> narrative")
+        return
+
+    # narrative already present: fold the source in, prefer existing keys.
+    narrative = item["narrative"]
+    if isinstance(narrative, dict):
+        if isinstance(source, dict):
+            for key, value in source.items():
+                narrative.setdefault(key, value)
+        else:
+            narrative.setdefault(wrap_key, source)
+    del item[source_key]
+    changes.append(f"item {source_key} folded into existing narrative")
+
+
+def _walk_items(items: list, changes: list[str]) -> None:
+    """Recurse item / subItem trees applying the item-level migrations."""
+    for item in items:
+        if not isinstance(item, dict):
+            continue
+        _fold_into_narrative(item, "description", changes)
+        _fold_into_narrative(item, "narratives", changes)
+        for nested_key in ("items", "subItems"):
+            nested = item.get(nested_key)
+            if isinstance(nested, list):
+                _walk_items(nested, changes)
+
+
+def migrate_data(data: dict) -> list[str]:
+    """Apply all Category A migrations to ``data`` in place; return change log."""
+    changes: list[str] = []
+    plan = data.get("plan")
+    if not isinstance(plan, dict):
+        return changes
+    _migrate_plan_ref(plan, changes)
+    items = plan.get("items")
+    if isinstance(items, list):
+        _walk_items(items, changes)
+    return changes
+
+
+def _detect_indent_ensure_ascii(original: str, data: dict) -> bool:
+    """Return the ``ensure_ascii`` value that reproduces ``original``.
+
+    617/618 corpus files use ``ensure_ascii=False``; one historical file uses
+    ASCII-escaped unicode. Detecting per file keeps a changed file's diff
+    minimal (it is never re-escaped / un-escaped as a side effect).
+    """
+    if json.dumps(data, indent=2, ensure_ascii=False) + "\n" == original:
+        return False
+    # Default to ensure_ascii=False (canonical) unless the ASCII-escaped form
+    # is the exact reproduction of the original.
+    return json.dumps(data, indent=2, ensure_ascii=True) + "\n" == original
+
+
+def _serialize(data: dict, ensure_ascii: bool) -> str:
+    return json.dumps(data, indent=2, ensure_ascii=ensure_ascii) + "\n"
+
+
+def iter_vbrief_files(project_root: Path) -> list[Path]:
+    """Return sorted ``vbrief/**/*.vbrief.json`` paths under ``project_root``."""
+    vbrief_dir = project_root / "vbrief"
+    if not vbrief_dir.is_dir():
+        return []
+    return sorted(vbrief_dir.rglob("*.vbrief.json"))
+
+
+def evaluate(
+    project_root: Path,
+    *,
+    check: bool = False,
+) -> tuple[int, list[tuple[str, list[str]]], str]:
+    """Pure driver returning ``(exit_code, per_file_changes, human_message)``.
+
+    Separated from :func:`main` so tests can drive every state without CLI
+    plumbing. In write mode (``check=False``) changed files are persisted.
+    """
+    vbrief_dir = project_root / "vbrief"
+    if not vbrief_dir.is_dir():
+        return (
+            2,
+            [],
+            (
+                f"\u274c vbrief_migrate_conformance: no vbrief/ directory under "
+                f"{project_root}.\n"
+                "  Recovery: run from a project root that contains vbrief/."
+            ),
+        )
+
+    per_file: list[tuple[str, list[str]]] = []
+    for path in iter_vbrief_files(project_root):
+        original = path.read_text(encoding="utf-8")
+        try:
+            data = json.loads(original)
+        except json.JSONDecodeError:
+            # Leave unparseable files alone; the conformance gate / encoding
+            # gate own malformed-file reporting.
+            continue
+        changes = migrate_data(data)
+        if not changes:
+            continue
+        rel = path.relative_to(project_root).as_posix()
+        per_file.append((rel, changes))
+        if not check:
+            ensure_ascii = _detect_indent_ensure_ascii(original, json.loads(original))
+            path.write_text(_serialize(data, ensure_ascii), encoding="utf-8")
+
+    if not per_file:
+        msg = (
+            "\u2713 vbrief_migrate_conformance: corpus already conformant "
+            "(no Category A migrations needed) (#1620)."
+        )
+        return 0, per_file, msg
+
+    verb = "would change" if check else "changed"
+    marker = "\u26a0" if check else "\u2713"
+    lines = [
+        f"{marker} vbrief_migrate_conformance: "
+        f"{verb} {len(per_file)} file(s) (Category A, #1620)."
+    ]
+    for rel, changes in per_file:
+        lines.append(f"  {rel}")
+        for change in changes:
+            lines.append(f"    - {change}")
+    message = "\n".join(lines)
+    # --check signals drift with exit 1; write mode reports success with exit 0.
+    return (1 if check else 0), per_file, message
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="vbrief_migrate_conformance.py",
+        description=(
+            "Idempotent Category A vBRIEF 0.6 conformance migration (#1620): "
+            "plan.planRef -> plan.references[], item description/narratives -> "
+            "item narrative."
+        ),
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help=(
+            "Dry-run: mutate nothing. Exit 0 when no changes are needed, "
+            "else print a per-file summary and exit 1."
+        ),
+    )
+    parser.add_argument(
+        "--project-root",
+        default=".",
+        help="Project root containing vbrief/ (default: current directory).",
+    )
+    parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Suppress the success message (drift/errors still print).",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    # Force UTF-8 stdout/stderr so the non-ASCII status glyphs survive a
+    # Windows cp1252/cp437 console (mirrors scripts/verify_encoding.py #814).
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    if hasattr(sys.stderr, "reconfigure"):
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    project_root = Path(args.project_root).resolve()
+
+    code, _per_file, message = evaluate(project_root, check=args.check)
+    if code == 0:
+        if not args.quiet:
+            print(message)
+    else:
+        print(message, file=sys.stderr)
+    return code
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/vbrief_reconcile_graph.py

@@ -0,0 +1,306 @@
+#!/usr/bin/env python3
+"""vbrief_reconcile_graph.py -- cascade-unblock walker (#1287).
+
+A pure-vBRIEF, forge-agnostic verb (``task vbrief:reconcile:graph``) that
+walks ``vbrief/proposed/``, resolves each candidate's
+``plan.metadata.swarm.depends_on[]`` against current lifecycle state, and
+promotes (``proposed/ -> pending/`` via the existing
+``scope_lifecycle.run_transition`` path) every candidate whose
+dependencies ALL resolve to a brief living in ``vbrief/completed/`` or
+``vbrief/cancelled/``.
+
+Design contract:
+
+* **Cascade-unblock only.** A candidate with an empty ``depends_on`` is
+  left in ``proposed/`` -- the backlog is the operator's, not the
+  walker's. Only candidates that WERE blocked on dependencies and are now
+  unblocked get promoted.
+* **WIP-cap aware.** Promotions stop once ``pending/ + active/`` reaches
+  the configured cap (``plan.policy.wipCap``, default 10). ``--force``
+  overrides the cap (each forced promote is logged by the underlying
+  scope-lifecycle audit path).
+* **Cycle-safe.** Dependency cycles among proposed candidates are detected
+  via the ``swarm_readiness`` dep-graph machinery and never promoted; a
+  cycle is reported and yields exit 1.
+* **Idempotent.** A second run is a no-op: promoted candidates have left
+  ``proposed/``, so nothing further resolves.
+
+Reuses the dependency-graph resolution machinery in
+``scripts/swarm_readiness.py`` (``_candidate``, ``_all_scope_ids``,
+``_candidate_dep_graph``, ``_mark_cycles``) and the promote surface in
+``scripts/scope_lifecycle.py`` (``run_transition``) rather than
+reinventing either.
+
+Exit codes (three-state):
+    0 -- ran successfully (promoted >= 0 candidates; WIP-cap deferral and
+         not-yet-resolved candidates are normal, idempotent outcomes).
+    1 -- a dependency cycle was detected among proposed candidates.
+    2 -- usage / config error (no ``vbrief/proposed/`` directory, etc.).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from _stdio_utf8 import reconfigure_stdio  # noqa: E402
+from scope_lifecycle import run_transition  # noqa: E402
+from swarm_readiness import (  # noqa: E402
+    Candidate,
+    _all_scope_ids,
+    _as_str_list,
+    _candidate,
+    _candidate_dep_graph,
+    _mark_cycles,
+)
+
+reconfigure_stdio()
+
+# A dependency "resolves" (no longer blocks its dependent) when the brief
+# it names lives in one of these terminal lifecycle folders.
+RESOLVED_FOLDERS = ("completed", "cancelled")
+_CYCLE_MARKER = "dependency cycle:"
+
+
+@dataclass
+class ReconcileOutcome:
+    """Result of a single reconcile walk."""
+
+    promoted: list[str] = field(default_factory=list)
+    deferred_wip: list[str] = field(default_factory=list)
+    waiting: list[tuple[str, list[str]]] = field(default_factory=list)
+    cycles: list[str] = field(default_factory=list)
+    errors: list[tuple[str, str]] = field(default_factory=list)
+    cap: int = 0
+    count: int = 0
+    dry_run: bool = False
+    forced: bool = False
+
+    def to_json(self) -> dict[str, object]:
+        return {
+            "promoted": list(self.promoted),
+            "deferred_wip": list(self.deferred_wip),
+            "waiting": [{"story_id": sid, "unresolved": deps} for sid, deps in self.waiting],
+            "cycles": list(self.cycles),
+            "errors": [{"story_id": sid, "message": msg} for sid, msg in self.errors],
+            "cap": self.cap,
+            "count": self.count,
+            "dry_run": self.dry_run,
+            "forced": self.forced,
+        }
+
+
+def _resolve_wip_state(project_root: Path) -> tuple[int, int]:
+    """Return ``(cap, current_count)`` for the WIP cap.
+
+    Deferred-import of ``scripts.policy`` so a tree that pre-dates the D4
+    WIP-cap schema (#1124) degrades to "no cap" (a very large cap) rather
+    than raising.
+    """
+    try:
+        from policy import count_vbrief_wip, resolve_wip_cap
+    except ImportError:  # pragma: no cover -- D4 not present
+        return sys.maxsize, 0
+    cap = resolve_wip_cap(project_root).cap
+    count = count_vbrief_wip(project_root)
+    return cap, count
+
+
+def _dep_resolved(dep: str, known_ids: dict[str, tuple[Path, str]]) -> bool:
+    """True when *dep* names a brief in a terminal (completed/cancelled) folder."""
+    known = known_ids.get(dep)
+    if known is None:
+        return False
+    path, _status = known
+    return path.parent.name in RESOLVED_FOLDERS
+
+
+def _unresolved_deps(
+    candidate: Candidate,
+    known_ids: dict[str, tuple[Path, str]],
+) -> list[str]:
+    """Return the dependency ids that have NOT resolved to a terminal folder."""
+    return [
+        dep
+        for dep in _as_str_list(candidate.swarm.get("depends_on"))
+        if not _dep_resolved(dep, known_ids)
+    ]
+
+
+def _candidate_in_cycle(candidate: Candidate) -> bool:
+    return any(reason.startswith(_CYCLE_MARKER) for reason in candidate.blocked)
+
+
+def reconcile_graph(
+    project_root: Path,
+    *,
+    force: bool = False,
+    dry_run: bool = False,
+) -> tuple[int, ReconcileOutcome]:
+    """Walk proposed/, promote cascade-unblocked candidates, return (exit, outcome).
+
+    The promote order is deterministic (sorted by story id) so the WIP-cap
+    cut-off is stable across runs.
+    """
+    proposed_dir = project_root / "vbrief" / "proposed"
+    if not proposed_dir.is_dir():
+        return 2, ReconcileOutcome()
+
+    candidate_paths = sorted(proposed_dir.glob("*.vbrief.json"))
+    candidates = [c for path in candidate_paths if (c := _candidate(path, project_root))]
+
+    known_ids = _all_scope_ids(project_root)
+    for candidate in candidates:
+        known_ids.setdefault(candidate.story_id, (candidate.path, candidate.status))
+
+    # Reuse the swarm_readiness dep-graph + cycle machinery. ``_candidate_dep_graph``
+    # builds edges only between proposed candidates; ``_mark_cycles`` then appends a
+    # ``dependency cycle: ...`` marker to every candidate that participates in one.
+    graph = _candidate_dep_graph(candidates, known_ids)
+    _mark_cycles(candidates, graph)
+
+    cap, count = _resolve_wip_state(project_root)
+    outcome = ReconcileOutcome(cap=cap, count=count, dry_run=dry_run, forced=force)
+
+    eligible: list[Candidate] = []
+    for candidate in sorted(candidates, key=lambda c: c.story_id):
+        if _candidate_in_cycle(candidate):
+            cycle_reason = next(
+                reason for reason in candidate.blocked if reason.startswith(_CYCLE_MARKER)
+            )
+            outcome.cycles.append(f"{candidate.story_id}: {cycle_reason}")
+            continue
+        deps = _as_str_list(candidate.swarm.get("depends_on"))
+        if not deps:
+            # Cascade-unblock only: a dependency-free brief is operator backlog,
+            # not the walker's to promote.
+            continue
+        unresolved = _unresolved_deps(candidate, known_ids)
+        if unresolved:
+            outcome.waiting.append((candidate.story_id, unresolved))
+            continue
+        eligible.append(candidate)
+
+    running_count = count
+    for candidate in eligible:
+        if running_count >= cap and not force:
+            outcome.deferred_wip.append(candidate.story_id)
+            continue
+        if dry_run:
+            outcome.promoted.append(candidate.story_id)
+            running_count += 1
+            continue
+        ok, message = run_transition("promote", candidate.path)
+        if not ok:
+            outcome.errors.append((candidate.story_id, message))
+            continue
+        outcome.promoted.append(candidate.story_id)
+        running_count += 1
+
+    outcome.count = running_count
+    exit_code = 1 if outcome.cycles else 0
+    return exit_code, outcome
+
+
+def _render_report(outcome: ReconcileOutcome) -> str:
+    lines: list[str] = ["vBRIEF reconcile graph", ""]
+    suffix = " (dry-run)" if outcome.dry_run else ""
+
+    lines.append(f"Promoted{suffix}:")
+    if outcome.promoted:
+        lines.extend(f"- {story_id}" for story_id in outcome.promoted)
+    else:
+        lines.append("- none")
+    lines.append("")
+
+    lines.append(f"Deferred (WIP cap {outcome.count}/{outcome.cap}):")
+    if outcome.deferred_wip:
+        lines.extend(f"- {story_id}" for story_id in outcome.deferred_wip)
+    else:
+        lines.append("- none")
+    lines.append("")
+
+    lines.append("Waiting (deps unresolved):")
+    if outcome.waiting:
+        lines.extend(
+            f"- {story_id}: needs {', '.join(deps)}" for story_id, deps in outcome.waiting
+        )
+    else:
+        lines.append("- none")
+    lines.append("")
+
+    lines.append("Cycles:")
+    if outcome.cycles:
+        lines.extend(f"- {entry}" for entry in outcome.cycles)
+    else:
+        lines.append("- none")
+
+    if outcome.errors:
+        lines.append("")
+        lines.append("Errors:")
+        lines.extend(f"- {story_id}: {message}" for story_id, message in outcome.errors)
+
+    return "\n".join(lines)
+
+
+def _parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Cascade-unblock walker: promote proposed/ vBRIEFs whose "
+            "swarm.depends_on[] all resolve to completed/ or cancelled/."
+        )
+    )
+    parser.add_argument(
+        "--project-root",
+        default=".",
+        help="Project root containing vbrief/ (default: current directory).",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Override the WIP cap when promoting (each forced promote is audited).",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Report which candidates WOULD be promoted without moving any files.",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Emit a machine-readable JSON summary instead of the text report.",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parse_args(sys.argv[1:] if argv is None else argv)
+    project_root = Path(args.project_root).resolve()
+    exit_code, outcome = reconcile_graph(
+        project_root,
+        force=args.force,
+        dry_run=args.dry_run,
+    )
+    if exit_code == 2:
+        if args.json:
+            print(json.dumps({"error": "no vbrief/proposed/ directory found"}))
+        else:
+            print(
+                f"Error: no vbrief/proposed/ directory found under {project_root}",
+                file=sys.stderr,
+            )
+        return 2
+    if args.json:
+        print(json.dumps(outcome.to_json(), indent=2))
+    else:
+        print(_render_report(outcome))
+    return exit_code
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())