@deftai/directive-content 0.59.0 → 0.61.0

package/scripts/migrate_vbrief.py

@@ -1,2677 +0,0 @@
-#!/usr/bin/env python3
-"""
-migrate_vbrief.py -- Migrate a Deft project to the vBRIEF-centric document model.
-
-Converts existing SPECIFICATION.md + specification.vbrief.json + PROJECT.md +
-ROADMAP.md into the new lifecycle folder structure defined by RFC #309.
-
-Usage:
-    uv run python scripts/migrate_vbrief.py [project_root]
-
-    project_root -- path to the project root (default: current working directory)
-
-Exit codes:
-    0 -- migration completed successfully
-    1 -- migration failed (errors printed to stderr)
-
-Story: #312 (Phase 2 vBRIEF Architecture Cutover)
-"""
-
-from __future__ import annotations
-
-import contextlib
-import json
-import re
-import subprocess
-import sys
-from datetime import UTC, datetime
-from pathlib import Path
-from typing import Any
-from urllib.parse import urlparse
-
-# Ensure the ``scripts/`` directory is on sys.path so sibling module
-# ``_vbrief_build`` is importable whether this file is run as __main__ or
-# imported from a test harness that appends the ``scripts/`` path.
-sys.path.insert(0, str(Path(__file__).resolve().parent))
-
-
-# #635: Detection-bound emit helper -- lazy-imported so an import-time
-# failure in ``scripts/_event_detect.py`` (e.g. syntax error in a future
-# change) cannot break the migrator'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 the migrator 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)
-
-
-from _vbrief_build import (  # noqa: E402 -- after sys.path mutate + lazy emit helper
-    EMITTED_VBRIEF_VERSION,  # canonical emitted version per #533
-    create_scope_vbrief as _create_scope_vbrief_shared,
-    reference_with_default_trust as _reference_with_default_trust,
-    slugify as _slugify_shared,
-)
-from _vbrief_speckit import (  # noqa: E402
-    create_speckit_scope_vbrief as _create_speckit_scope_vbrief_shared,
-    dependencies_for_item as _dependencies_for_item_shared,
-    edge_nodes as _edge_nodes_shared,
-    migrate_speckit_plan as _migrate_speckit_plan_shared,
-    speckit_ip_index as _speckit_ip_index_shared,
-    speckit_ip_slug as _speckit_ip_slug_shared,
-)
-from _vbrief_validation import (  # noqa: E402
-    finalize_migration,
-    slug_fallback_id,
-    slugify_id,
-)
-
-# Re-export slug-safe sanitiser under the migrator's underscore-prefixed
-# convention so test harnesses and other migrator-adjacent tooling can import
-# it from ``migrate_vbrief`` alongside the existing ``_slugify`` shim (#498).
-_slugify_id = slugify_id
-_slug_fallback_id = slug_fallback_id
-
-# --- safety (Agent C, #497) ---
-# Safety affordances for `task migrate:vbrief` live in `_vbrief_safety`:
-# .premigrate.* backups, --dry-run preview, dirty-tree guard, --rollback.
-# See `scripts/_vbrief_safety.py` and tracking issue #506 (D7) for the
-# authoritative decisions this code implements.
-# --- end safety ---
-# --- reconciliation (Agent B, #496) ---
-# Role-based SPEC/ROADMAP reconciliation per #506 D3 + overrides loader +
-# RECONCILIATION.md emitter live in ``_vbrief_reconciliation``.
-# --- end lifecycle-routing ---
-# --- fidelity (Agent A, #495) ---
-# Per-task body / FR-NFR definition parsing, Requirements narrative, plan.edges[]
-# extraction, and the disambiguated ROUTE migration log live in
-# ``_vbrief_fidelity``.  Per #506 D2 #14 body routing is reconciled by Agent B;
-# this module FEEDS reconciliation by enriching spec_vbrief.plan.items with
-# the narratives parsed from raw SPECIFICATION.md content.
-# --- legacy-artifacts (Agent A, #505) ---
-# LegacyArtifacts narrative emission + 6KB sidecar overflow + LEGACY-REPORT.md
-# + stdout summary live in ``_vbrief_legacy``.  The known-mappings list is
-# shared with #495's canonical extraction path so both agree on what is
-# canonical vs non-canonical (#506 D5).
-# --- behavioral events (#635 events behavioral wiring) ---
-# Structural ``legacy:detected`` event emission. Each captured legacy
-# section produces one framework event alongside the existing
-# ``vbrief/migration/LEGACY-REPORT.md`` write (existing report behaviour
-# preserved). Handlers are deferred to follow-up work per the vBRIEF.
-#
-# Imported under the distinct ``_emit_behavioral_event`` name so it
-# does NOT shadow the detection-bound ``_emit_event`` lazy-import wrapper
-# defined above. The two helpers consume the same unified
-# ``events/registry.json`` post-#706 unification but enforce different
-# category boundaries: ``_emit_event`` (detection-bound) accepts any
-# registered event name; ``_emit_behavioral_event`` (this alias) only
-# accepts events whose registry entry carries ``category: "behavioral"``.
-from _events import (  # noqa: E402
-    DEFAULT_EVENT_LOG as _DEFAULT_EVENT_LOG,
-    emit as _emit_behavioral_event,
-)
-from _vbrief_fidelity import (  # noqa: E402
-    build_edges_from_tasks as _build_edges_from_tasks,
-    build_requirements_narrative as _build_requirements_narrative,
-    format_migration_log_entry as _format_migration_log_entry,
-    ingest_spec_narratives as _ingest_spec_narratives,
-    parse_requirement_definitions as _parse_requirement_definitions,
-    parse_spec_tasks as _parse_spec_tasks,
-    task_scope_narratives as _task_scope_narratives,
-)
-
-# --- end behavioral events ---
-from _vbrief_legacy import (  # noqa: E402
-    CANONICAL_SPEC_KEYS as _CANONICAL_SPEC_KEYS,
-    PRD_HAND_EDIT_WARNING as _PRD_HAND_EDIT_WARNING,
-    PROJECT_KNOWN_MAPPINGS as _PROJECT_KNOWN_MAPPINGS,
-    detect_prd_legacy as _detect_prd_legacy,
-    emit_legacy_artifacts as _emit_legacy_artifacts,
-    emit_legacy_report as _emit_legacy_report,
-    parse_top_level_sections as _parse_top_level_sections,
-    partition_sections as _partition_sections,
-    summarize_captures as _summarize_captures,
-)
-from _vbrief_reconciliation import (  # noqa: E402
-    load_overrides as _load_overrides,
-    reconcile_scope_items as _reconcile_scope_items,
-    write_reconciliation_report as _write_reconciliation_report,
-)
-
-# --- end reconciliation ---
-# --- lifecycle-routing (Agent B, #499) ---
-# Lifecycle folder <-> status mapping + scope vBRIEF builder per #506 shared
-# conventions. Schema vocabulary only -- ``active/`` uses ``running``, NEVER
-# ``in_progress`` (the critical #499 correction comment).
-from _vbrief_routing import (  # noqa: E402
-    build_scope_vbrief_from_reconciled as _build_reconciled_scope_vbrief,
-)
-from _vbrief_safety import (  # noqa: E402
-    FileModification,
-    SafetyManifest,
-    dirty_tree_refusal_message,
-    is_tree_dirty,
-    load_safety_manifest,
-    now_utc_iso,
-    plan_backups,
-    rollback as safety_rollback,  # noqa: E402
-    sha256_of,
-    write_backups,
-    write_safety_manifest,
-)
-from slug_normalize import (  # noqa: E402
-    DEFAULT_MAX_LEN as _SLUG_MAX_LEN,
-    disambiguate_slug as _disambiguate_slug,
-    normalize_slug as _normalize_slug,
-)
-
-MIGRATOR_VERSION = "0.20.0"
-
-# --- vbrief version (#533) ---
-# ``EMITTED_VBRIEF_VERSION`` is the canonical ``vBRIEFInfo.version`` string
-# emitted on every file the migrator writes. Imported above from
-# ``_vbrief_build`` so the migrator, ingestion helpers, and speckit all share
-# a single source of truth. Bumped from ``"0.5"`` to ``"0.6"`` as part of the
-# Agent 2 schema vendor transition (#533). During the transition the
-# validator accepts both values; the migrator only emits the newer string.
-# --- end vbrief version ---
-
-# --- gitignore (#530) ---
-# Canonical comment block + patterns appended to a consumer project's
-# ``.gitignore`` by the migrator on its first run so ``.premigrate.*`` backup
-# files do not leak into commits. Idempotent -- the migrator only appends
-# patterns that are not already matched by an existing .gitignore rule.
-_GITIGNORE_MARKER_LINE = (
-    "# Migration backups (created by `task migrate:vbrief`) -- do NOT commit."
-)
-_GITIGNORE_COMMENT_BLOCK: tuple[str, ...] = (
-    _GITIGNORE_MARKER_LINE,
-    "# Post-commit, pre-migration state is recoverable via git history; see",
-    "# deft/main.md \u00a7 Safety flags for the post-commit recovery path.",
-)
-_GITIGNORE_PATTERNS: tuple[str, ...] = (
-    "*.premigrate.md",
-    "*.premigrate.vbrief.json",
-)
-# --- end gitignore ---
-
-# --- traces strip (#529) ---
-# Regex matching a ``**Traces**: ...`` line inside a LegacyArtifacts task block.
-# ``items[].subItems[].narrative.Traces`` is the single source of truth; the
-# duplicated line inside ``LegacyArtifacts`` is stripped during migration to
-# prevent downstream drift between the two copies. Applied with ``.match()``
-# against each individual line in ``_strip_traces_from_narrative`` so the
-# ``re.MULTILINE`` flag is not needed (Greptile #561 P2).
-_TRACES_LINE_RE = re.compile(r"^\s*\*\*Traces\*\*\s*:.*$")
-# Regex matching a LegacyArtifacts task header: e.g. ``### t2.1.2: ...`` or
-# ``### t2.1.2 -- ...``. Used to attribute the stripped line to a task id for
-# the RECONCILIATION.md audit trail. Applied with ``.match()`` against each
-# individual line so ``re.MULTILINE`` is likewise unnecessary.
-_TASK_HEADER_RE = re.compile(
-    r"^###\s+(?P<task_id>[A-Za-z]?\d+(?:\.\d+)+)\b",
-)
-# Marker used to guard RECONCILIATION.md against duplicate Traces-stripped
-# sections on migrator re-runs (Greptile #561 P2). Must match the section
-# header emitted by :func:`_write_traces_stripped_note` exactly.
-_TRACES_SECTION_HEADER = "## Traces lines stripped from LegacyArtifacts (#529)"
-# --- end traces strip ---
-
-# --- end fidelity + legacy-artifacts ---
-
-# Lifecycle folders per RFC #309 D13
-LIFECYCLE_FOLDERS = ("proposed", "pending", "active", "completed", "cancelled")
-
-# Migrator-managed subdirectories under ``vbrief/`` that are created lazily by
-# sidecar emission (``vbrief/legacy/``, #505) and reporting (``vbrief/migration/``)
-# paths. Tracked in the safety manifest's ``created_dirs`` when the migrator
-# creates them for the first time so ``--rollback`` can RMDIR them consistently
-# with the lifecycle folders (issues #527, #528).
-_MANAGED_SUBDIRS: tuple[str, ...] = ("legacy", "migration")
-
-# Deprecation redirect sentinel per Story S (#334). Retained for one
-# release cycle alongside the canonical banner (#572) so consumers
-# that migrated under rc.1 / rc.2 are not incorrectly re-flagged as
-# pre-cutover on rc.3 and later.
-DEPRECATION_SENTINEL = "<!-- deft:deprecated-redirect -->"
-
-# Canonical machine-generated banner markers per #572 /
-# ``conventions/machine-generated-banner.md``. The migrator and the
-# three render scripts all emit the ``AUTO-GENERATED by`` +
-# ``<!-- Purpose:`` pair as the first two banner lines, so the
-# user-customisation detector below only needs to look for either
-# token (plus the legacy deprecation sentinel for one release cycle).
-# ``_is_user_customized()`` treats any file carrying one of these
-# markers as machine-managed and therefore safe to replace.
-#
-# Greptile P2 on the review of this PR: the marker is the FULL
-# ``<!-- Purpose:`` HTML-comment prefix, not the bare ``Purpose:``
-# string, so a hand-authored spec containing ``Purpose: deliver a
-# self-service flow`` in ordinary prose is not misclassified as
-# machine-managed and silently overwritten.
-_SPEC_AUTO_MARKERS = (
-    "AUTO-GENERATED by",
-    "<!-- Purpose:",
-    DEPRECATION_SENTINEL,
-    # Legacy markers kept for one release cycle so a previously-
-    # generated file that used the old banner shape is still
-    # recognised as machine-managed.
-    "Generated by",
-    "deft-setup skill",
-    "spec_render.py",
-)
-_PROJECT_AUTO_MARKERS = (
-    "AUTO-GENERATED by",
-    "<!-- Purpose:",
-    DEPRECATION_SENTINEL,
-    # Legacy markers -- see _SPEC_AUTO_MARKERS for rationale.
-    "Generated by",
-    "deft-setup skill",
-)
-
-# Date for migration-created vBRIEF filenames (D7: creation date)
-_TODAY = datetime.now(UTC).strftime("%Y-%m-%d")
-
-# ISO-8601 UTC timestamp stamped onto ``vBRIEFInfo.updated`` when the
-# migrator routes a scope to ``completed/`` (#593). Module-level so the
-# golden-file test can monkeypatch for deterministic byte-for-byte output
-# (mirrors ``_TODAY``).
-_MIGRATION_TIMESTAMP = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
-
-# Mapping of markdown heading text (lowercased) to canonical narrative key names.
-# Covers both CamelCase keys (from prd_render.py output) and space-separated
-# forms (from hand-written PRDs/specs).  Keys must match prd_render.py.
-_HEADING_TO_NARRATIVE_KEY: dict[str, str] = {
-    "overview": "Overview",
-    "problemstatement": "ProblemStatement",
-    "problem statement": "ProblemStatement",
-    "goals": "Goals",
-    "userstories": "UserStories",
-    "user stories": "UserStories",
-    "requirements": "Requirements",
-    "successmetrics": "SuccessMetrics",
-    "success metrics": "SuccessMetrics",
-    "architecture": "Architecture",
-    "nonfunctionalrequirements": "NonFunctionalRequirements",
-    "non-functional requirements": "NonFunctionalRequirements",
-    "non functional requirements": "NonFunctionalRequirements",
-    "openquestions": "OpenQuestions",
-    "open questions": "OpenQuestions",
-}
-
-
-def _is_user_customized(content: str, auto_markers: tuple[str, ...]) -> bool:
-    """Check if file content has been customized beyond auto-generated content.
-
-    Returns True if the content does NOT contain any of the known auto-generation
-    markers, suggesting the user has substantially rewritten the file.
-    """
-    return not any(marker in content for marker in auto_markers)
-
-
-# Legacy underscore-prefixed alias -- extraction of the shared helper into
-# ``_vbrief_build`` (#454) preserves the public surface tests import today.
-_slugify = _slugify_shared
-
-
-def _parse_prd_narratives(content: str) -> dict[str, str]:
-    """Parse structured ## sections from PRD/SPECIFICATION markdown into narrative keys.
-
-    Recognizes known PRD headings (both CamelCase and space-separated forms)
-    and maps them to canonical narrative key names matching prd_render.py
-    NARRATIVE_KEY_ORDER.
-
-    Returns a dict of narrative_key -> section_body for recognized sections.
-    """
-    narratives: dict[str, str] = {}
-    parts = re.split(r"^##\s+", content, flags=re.MULTILINE)
-
-    for part in parts[1:]:  # skip preamble before first ##
-        heading, _, body = part.partition("\n")
-        heading = heading.strip()
-        # Strip trailing auto-generated footer (--- followed by italicized note)
-        body = re.sub(r"\n---\s*\n\*{1,2}[^*]+\*{1,2}\s*$", "", body)
-        body = body.strip()
-
-        if not body:
-            continue
-
-        key = _HEADING_TO_NARRATIVE_KEY.get(heading.lower())
-        if key:
-            narratives[key] = body
-
-    return narratives
-
-
-def _parse_roadmap_items(roadmap_path: Path) -> tuple[list[dict], dict[str, str], list[dict]]:
-    """Parse ROADMAP.md and extract items as structured data.
-
-    Returns a tuple of:
-      - active items: list of dicts with keys: number, title, phase, tier.
-      - phase_descriptions: dict mapping phase heading -> description text.
-      - completed items: list of dicts with keys: number, title (from Completed section).
-    """
-    if not roadmap_path.exists():
-        return [], {}, []
-
-    content = roadmap_path.read_text(encoding="utf-8")
-    items: list[dict] = []
-    completed_items: list[dict] = []
-    phase_descriptions: dict[str, str] = {}
-    current_phase = ""
-    current_tier = ""
-    in_completed = False
-    # Accumulate description lines between heading and first list item
-    desc_lines: list[str] = []
-    capturing_desc = False
-    _synthetic_counter = 0
-
-    for line in content.splitlines():
-        # Detect phase headings (## Level)
-        phase_match = re.match(r"^##\s+(.+)", line)
-        if phase_match:
-            # Save previous phase description
-            if current_phase and desc_lines:
-                phase_descriptions[current_phase] = "\n".join(desc_lines).strip()
-            desc_lines = []
-
-            current_phase = phase_match.group(1).strip()
-            current_tier = ""
-            if "completed" in current_phase.lower():
-                in_completed = True
-                capturing_desc = False
-            else:
-                in_completed = False
-                capturing_desc = True
-            continue
-
-        # Detect tier subheadings (### Level)
-        tier_match = re.match(r"^###\s+(.+)", line)
-        if tier_match:
-            if current_phase and desc_lines and capturing_desc:
-                phase_descriptions[current_phase] = "\n".join(desc_lines).strip()
-                desc_lines = []
-                capturing_desc = False
-            current_tier = tier_match.group(1).strip()
-            continue
-
-        # Accumulate phase description text (non-empty, non-list lines)
-        if capturing_desc and not in_completed:
-            stripped = line.strip()
-            if stripped and not stripped.startswith("-"):
-                desc_lines.append(stripped)
-                continue
-            if stripped.startswith("-"):
-                # First list item ends description capture
-                if desc_lines:
-                    phase_descriptions[current_phase] = "\n".join(desc_lines).strip()
-                    desc_lines = []
-                capturing_desc = False
-                # Fall through to item parsing below
-            else:
-                # Empty line during desc capture
-                if desc_lines:
-                    desc_lines.append("")
-                continue
-
-        if not current_phase:
-            continue
-
-        # --- Completed section items ---
-        if in_completed:
-            # Match: - ~~#NNN -- Title~~ or - ~~Title~~
-            comp_match = re.match(r"^-\s+~~(?:#?(\d+)\s*--?\s*)?(.+?)~~", line)
-            if comp_match:
-                comp_number = comp_match.group(1) or ""
-                comp_title = comp_match.group(2).strip()
-                completed_items.append({
-                    "number": comp_number,
-                    "title": comp_title,
-                    "phase": current_phase,
-                })
-            continue
-
-        # --- Active section items ---
-        # Match GitHub issue format: - **#NNN** -- Title
-        item_match = re.match(r"^-\s+\*\*#(\d+)\*\*\s+--\s+(.+)", line)
-        if item_match:
-            items.append({
-                "number": item_match.group(1),
-                "title": item_match.group(2).strip(),
-                "phase": current_phase,
-                "tier": current_tier,
-            })
-            continue
-
-        # Match task-based format: - **`X.Y.Z`** Title  or  - `X.Y.Z` Title
-        task_match = re.match(
-            r"^-\s+(?:\*\*)?`([^`]+)`(?:\*\*)?\s+(.+)", line
-        )
-        if task_match:
-            task_id = task_match.group(1).strip()
-            title = task_match.group(2).strip()
-            items.append({
-                "number": "",
-                "title": title,
-                "phase": current_phase,
-                "tier": current_tier,
-                "task_id": task_id,
-            })
-            continue
-
-        # Generic fallback: - Title (any list item under a ## heading)
-        generic_match = re.match(r"^-\s+(.+)", line)
-        if generic_match:
-            title = generic_match.group(1).strip()
-            # Skip items that look like sub-bullets or empty
-            if not title:
-                continue
-            _synthetic_counter += 1
-            items.append({
-                "number": "",
-                "title": title,
-                "phase": current_phase,
-                "tier": current_tier,
-                "synthetic_id": f"roadmap-{_synthetic_counter}",
-            })
-            continue
-
-    # Save final phase description
-    if current_phase and desc_lines and not in_completed:
-        phase_descriptions[current_phase] = "\n".join(desc_lines).strip()
-
-    return items, phase_descriptions, completed_items
-
-
-# --- repo detection (#613) ---
-# Regex mirroring ``reconcile_issues.detect_repo`` + ``issue_ingest._resolve_
-# repo_url``: accept both ``git@github.com:owner/repo.git`` and
-# ``https://github.com/owner/repo.git`` origin URLs and tolerate a trailing
-# ``.git`` suffix. Exposed at module level so tests can monkeypatch
-# ``_GIT_REMOTE_RE`` if they need to stub edge-case remotes without fighting
-# subprocess.
-_GIT_REMOTE_RE = re.compile(
-    r"github\.com[:/]([^/\s]+)/([^/\s]+?)(?:\.git)?(?:\s|$)",
-)
-
-
-def _detect_repo_from_git_remote(project_root: Path | None) -> str:
-    """Return ``https://github.com/owner/repo`` from ``git remote get-url origin``.
-
-    Matches the detection approach used by ``scripts/issue_ingest.py`` /
-    ``scripts/reconcile_issues.detect_repo`` -- shells out to ``git remote
-    get-url origin`` inside ``project_root`` (not the migrator's own CWD,
-    which would pick up deft's own remote on consumer projects, #538) and
-    returns the matching ``https://github.com/{owner}/{repo}`` URL. Returns
-    the empty string on any failure (git missing, remote missing, parse
-    failure) so callers can fall back cleanly without surfacing subprocess
-    errors to the migration log.
-    """
-    cwd = str(project_root) if project_root is not None else None
-    try:
-        result = subprocess.run(
-            ["git", "remote", "get-url", "origin"],
-            capture_output=True,
-            text=True,
-            timeout=10,
-            cwd=cwd,
-        )
-    except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
-        return ""
-    if result.returncode != 0:
-        return ""
-    url = (result.stdout or "").strip()
-    if not url:
-        return ""
-    match = _GIT_REMOTE_RE.search(url)
-    if not match:
-        return ""
-    return f"https://github.com/{match.group(1)}/{match.group(2)}"
-
-
-def _resolve_repo_url(
-    spec_vbrief: dict | None,
-    project_root: Path | None = None,
-) -> str:
-    """Resolve ``https://github.com/{owner}/{repo}`` for scope vBRIEF references.
-
-    Resolution order (highest precedence first):
-
-    1. ``spec_vbrief.vBRIEFInfo.repository`` (OWNER/REPO string).
-    2. Any ``github.com/{owner}/{repo}`` URI inside ``spec_vbrief.plan.
-       references[]`` (matches canonical v0.6 and legacy shapes).
-    3. ``git remote get-url origin`` rooted at ``project_root`` when
-       provided -- mirrors ``scripts/issue_ingest.py`` so consumer-project
-       migrations resolve to the consumer's GitHub repo, not deft's own
-       remote (#538, #613).
-
-    Returns the empty string when none resolve. Callers that receive the
-    empty string MUST NOT emit a ``references[]`` entry for GitHub issues
-    (the canonical v0.6 shape requires ``uri`` -- see #613 and
-    ``conventions/references.md``).
-    """
-    # Try spec_vbrief metadata first
-    if spec_vbrief:
-        repo = spec_vbrief.get("vBRIEFInfo", {}).get("repository", "")
-        if repo:
-            return f"https://github.com/{repo}"
-        # Check references for a GitHub URL pattern
-        refs = spec_vbrief.get("plan", {}).get("references", [])
-        for ref in refs:
-            uri = ref.get("uri", "")
-            if urlparse(uri).netloc in ("github.com", "www.github.com"):
-                # Extract owner/repo from URL
-                parts = uri.split("github.com/")[-1].split("/")
-                if len(parts) >= 2:
-                    return f"https://github.com/{parts[0]}/{parts[1]}"
-    # #613: fall back to the project's git origin so consumer migrations
-    # get canonical URIs even when spec_vbrief is absent or carries no
-    # repository hint.
-    if project_root is not None:
-        return _detect_repo_from_git_remote(project_root)
-    return ""
-
-
-def _extract_tech_stack(project_content: str) -> str:
-    """Extract tech stack information from PROJECT.md content.
-
-    Looks for common patterns:
-      - **Tech Stack**: value
-      - ## Tech Stack\n content
-      - Tech Stack: value
-    Returns extracted tech stack string, or empty string if not found.
-    """
-    # Pattern 1: **Tech Stack**: value (bold label on a single line)
-    match = re.search(
-        r"\*\*Tech\s+Stack\*\*\s*:\s*(.+)", project_content, re.IGNORECASE
-    )
-    if match:
-        return match.group(1).strip()
-
-    # Pattern 2: ## Tech Stack section (grab lines until next ## or EOF)
-    section_match = re.search(
-        r"##\s+Tech\s+Stack\s*\n(.*?)(?=\n##\s|\Z)",
-        project_content,
-        re.IGNORECASE | re.DOTALL,
-    )
-    if section_match:
-        section = section_match.group(1).strip()
-        if section:
-            return section
-
-    # Pattern 3: plain Tech Stack: value
-    plain_match = re.search(
-        r"Tech\s+Stack\s*:\s*(.+)", project_content, re.IGNORECASE
-    )
-    if plain_match:
-        return plain_match.group(1).strip()
-
-    return ""
-
-
-def _first_prose_paragraph(content: str) -> str:
-    """Return the first non-empty prose paragraph from markdown content.
-
-    Skips fenced code blocks, blank lines, markdown heading lines, and list
-    items; returns the first plain paragraph it finds.  Falls back to the
-    first H1 (`# Title`) heading text if no prose paragraph exists.  Returns
-    the empty string if nothing usable is found.
-    """
-    if not content:
-        return ""
-    first_h1 = ""
-    in_code_block = False
-    paragraph_lines: list[str] = []
-
-    def _flush() -> str:
-        if paragraph_lines:
-            return " ".join(paragraph_lines).strip()
-        return ""
-
-    for line in content.splitlines():
-        stripped = line.strip()
-        if stripped.startswith("```"):
-            in_code_block = not in_code_block
-            continue
-        if in_code_block:
-            continue
-        # First H1 title (# Title). Ignore H2/H3 etc.
-        if re.match(r"^#\s+", stripped) and not first_h1:
-            first_h1 = re.sub(r"^#\s+", "", stripped).strip()
-            continue
-        # Skip other headings -- also flush any accumulated paragraph first
-        if stripped.startswith("#"):
-            para = _flush()
-            if para:
-                return para
-            paragraph_lines.clear()
-            continue
-        # List items (unordered and ordered), blockquotes, and tables are not
-        # prose paragraphs for Overview purposes.  Ordered list detection uses
-        # the standard markdown pattern "N.\s" at the line start.
-        if stripped.startswith(("-", "*", ">", "|")) or re.match(r"^\d+\.\s", stripped):
-            para = _flush()
-            if para:
-                return para
-            paragraph_lines.clear()
-            continue
-        # Empty line ends paragraph
-        if not stripped:
-            para = _flush()
-            if para:
-                return para
-            paragraph_lines.clear()
-            continue
-        paragraph_lines.append(stripped)
-
-    # Final paragraph at EOF
-    para = _flush()
-    if para:
-        return para
-    # Fallback to H1 title text
-    return first_h1
-
-
-def _derive_overview_narrative(
-    spec_vbrief: dict | None,
-    spec_md_content: str | None,
-    project_content: str | None,
-    scope_item_count: int,
-) -> str:
-    """Derive an Overview narrative for PROJECT-DEFINITION.vbrief.json (#417).
-
-    D3 requires the `Overview` narrative key (after case-folding) to be
-    present on `vbrief/PROJECT-DEFINITION.vbrief.json`.  Resolution order:
-
-    1. `spec_vbrief.plan.narratives['Overview']` if present and non-empty.
-    2. First prose paragraph / H1 title of `SPECIFICATION.md` (pre-sentinel).
-    3. First prose paragraph / H1 title of `PROJECT.md` (pre-sentinel).
-    4. Synthesized placeholder naming the scope count, telling the user how
-       to fill it in.  Always non-empty so `vbrief:validate` passes D3.
-    """
-    # 1. spec_vbrief narratives (set by step 2b PRD/SPEC ingestion, or by the
-    # caller if there was a pre-existing specification.vbrief.json).
-    if spec_vbrief:
-        narratives = spec_vbrief.get("plan", {}).get("narratives", {})
-        if isinstance(narratives, dict):
-            ov = narratives.get("Overview")
-            if isinstance(ov, str) and ov.strip():
-                return ov.strip()
-
-    # 2. SPECIFICATION.md prose / title -- but only if not already a sentinel
-    # stub (would happen on re-run after migration).
-    if spec_md_content and DEPRECATION_SENTINEL not in spec_md_content:
-        derived = _first_prose_paragraph(spec_md_content)
-        if derived:
-            return derived
-
-    # 3. PROJECT.md prose / title -- same sentinel guard.
-    if project_content and DEPRECATION_SENTINEL not in project_content:
-        derived = _first_prose_paragraph(project_content)
-        if derived:
-            return derived
-
-    # 4. Synthesized fallback.  Always non-empty so the D3 validator passes.
-    if scope_item_count > 0:
-        return (
-            f"Project overview was not auto-derived during migration. "
-            f"{scope_item_count} scope item(s) were created in vbrief/pending/. "
-            f"Update vbrief/PROJECT-DEFINITION.vbrief.json narratives['Overview'] "
-            f"manually to describe your project."
-        )
-    return (
-        "Project overview was not auto-derived during migration. "
-        "Update vbrief/PROJECT-DEFINITION.vbrief.json narratives['Overview'] "
-        "manually to describe your project."
-    )
-
-
-def _build_project_definition(
-    spec_vbrief: dict | None,
-    project_content: str | None,
-    scope_items: list[dict],
-    repo_url: str = "",
-    spec_md_content: str | None = None,
-) -> dict:
-    """Build PROJECT-DEFINITION.vbrief.json from existing sources.
-
-    Per RFC #309 D3:
-    - narratives holds project identity (overview, tech stack, architecture, risks, config)
-    - items acts as a scope registry referencing individual vBRIEF files
-
-    ``spec_md_content`` is the raw SPECIFICATION.md text (pre-sentinel) for
-    Overview-narrative derivation on canonical v0.19 consumer projects that
-    have no pre-existing ``specification.vbrief.json`` (#417).
-
-    Per #498: every ``plan.items[*].id`` is routed through
-    :func:`_vbrief_validation.slugify_id` so the scope-registry id conforms
-    to the schema-locked ID regex ``^[a-zA-Z0-9_-]+(\\.[a-zA-Z0-9_-]+)*$``
-    and matches the slug used for the scope vBRIEF filename.
-    """
-    narratives: dict[str, str] = {}
-
-    # Extract from specification.vbrief.json
-    if spec_vbrief:
-        plan = spec_vbrief.get("plan", {})
-        if isinstance(plan, dict):
-            spec_narratives = plan.get("narratives", {})
-            if isinstance(spec_narratives, dict):
-                for key, value in spec_narratives.items():
-                    if isinstance(value, str):
-                        narratives[key] = value
-
-    # Extract from PROJECT.md
-    if project_content:
-        narratives["ProjectConfig"] = project_content
-        # Extract tech stack into its own narrative key (D3 requirement)
-        tech_stack = _extract_tech_stack(project_content)
-        if tech_stack:
-            narratives["tech stack"] = tech_stack
-
-    # Ensure Overview narrative is present AND non-empty so the generated
-    # PROJECT-DEFINITION passes `scripts/vbrief_validate.py::
-    # validate_project_definition` D3 out of the box (#417).  Case-insensitive
-    # check because D3 lowers() keys before comparing to
-    # PROJECT_DEF_EXPECTED_NARRATIVES = {"overview", "tech stack"}.  The
-    # value-awareness matters because a pre-existing specification.vbrief.json
-    # may carry an empty / whitespace-only `Overview` -- without this check,
-    # that blank value would round-trip into PROJECT-DEFINITION unchanged
-    # (D3 only asserts key presence, so we surface a useful narrative instead).
-    overview_key = next(
-        (k for k in narratives if k.lower() == "overview"), None
-    )
-    overview_value = narratives.get(overview_key, "") if overview_key else ""
-    if not isinstance(overview_value, str) or not overview_value.strip():
-        derived = _derive_overview_narrative(
-            spec_vbrief, spec_md_content, project_content, len(scope_items)
-        )
-        if derived:
-            # Keep the existing key spelling (e.g. "overview" vs "Overview")
-            # if one is present so we do not create a second key that differs
-            # only in case.  Default to CamelCase "Overview" for new entries.
-            narratives[overview_key or "Overview"] = derived
-
-    # Per #498 D8 / validator D3: PROJECT_DEF_EXPECTED_NARRATIVES requires
-    # `tech stack` (lowercase, space-separated) alongside `overview`. When
-    # no PROJECT.md was present we never populated it above, which the
-    # self-validation hook surfaces as a hard-block schema error. Synthesize
-    # a placeholder -- the same pattern #417 established for Overview -- so
-    # minimal fixtures round-trip cleanly and operators see a visible
-    # "fill-me-in" hint rather than a silent regression.
-    tech_stack_key = next((k for k in narratives if k.lower() == "tech stack"), None)
-    tech_stack_value = narratives.get(tech_stack_key, "") if tech_stack_key else ""
-    if not isinstance(tech_stack_value, str) or not tech_stack_value.strip():
-        narratives[tech_stack_key or "tech stack"] = (
-            "Tech stack was not auto-derived during migration. "
-            "Update vbrief/PROJECT-DEFINITION.vbrief.json narratives['tech stack'] "
-            "with your language, framework, and runtime versions."
-        )
-
-    items: list[dict] = []
-    # Per #498: use slug-safe ids, disambiguating collisions within a single
-    # registry build so every emitted id is unique and passes the schema's
-    # ID regex out of the box.
-    emitted_scope_ids: set[str] = set()
-    for scope in scope_items:
-        number = scope.get("number", "")
-        id_source = slug_fallback_id(scope)
-        scope_id = f"scope-{slugify_id(id_source, emitted_scope_ids)}"
-        # #499-registry: registry status mirrors the scope's reconciled
-        # status when the caller provides it (the migrator passes
-        # reconciled items whose status already reflects the #506
-        # lifecycle<->status mapping). Falls back to the phase-based
-        # heuristic for unstructured callers (e.g. direct test callers
-        # that pass raw ROADMAP items without reconciliation).
-        scope_status = scope.get("status")
-        if not isinstance(scope_status, str) or not scope_status:
-            phase = str(scope.get("phase", "") or "")
-            scope_status = (
-                "completed" if "completed" in phase.lower() else "pending"
-            )
-        item_title = scope.get("title", "Untitled")
-        item: dict = {
-            "id": scope_id,
-            "title": item_title,
-            "status": scope_status,
-        }
-        # #613: emit canonical v0.6 references on PROJECT-DEFINITION.plan.
-        # items[*].references so every scope registry row links back to
-        # its origin GitHub issue in the same shape the scope vBRIEF file
-        # carries. The VBriefReference schema requires ``uri`` and a
-        # ``^x-vbrief/`` type -- without a resolvable ``repo_url`` we
-        # cannot honestly construct ``uri`` so we drop the reference
-        # rather than emit a malformed stub.
-        if number and repo_url:
-            ref_title = (
-                f"Issue #{number}: {item_title}"
-                if item_title and item_title != "Untitled"
-                else f"Issue #{number}"
-            )
-            item["references"] = [
-                _reference_with_default_trust(
-                    {
-                        "uri": f"{repo_url}/issues/{number}",
-                        "type": "x-vbrief/github-issue",
-                        "title": ref_title,
-                    }
-                )
-            ]
-        items.append(item)
-
-    return {
-        "vBRIEFInfo": {
-            "version": EMITTED_VBRIEF_VERSION,
-            "description": "Project definition -- synthesized gestalt of the project.",
-        },
-        "plan": {
-            "title": "PROJECT-DEFINITION",
-            "status": "running",
-            "narratives": narratives,
-            "items": items,
-        },
-    }
-
-
-# Legacy underscore-prefixed alias -- the shared helper lives in
-# ``_vbrief_build`` (#454). Tests and callers continue to import
-# ``_create_scope_vbrief`` from this module.
-_create_scope_vbrief = _create_scope_vbrief_shared
-
-
-def _deprecation_redirect(
-    original_name: str,
-    pointer_target: str,
-    scope_note: str,
-) -> str:
-    """Generate deprecation redirect content for a replaced file.
-
-    Opens with the canonical 4-line banner documented in
-    ``conventions/machine-generated-banner.md`` (#572) so downstream
-    detectors (pre-cutover guards, user-customisation heuristics)
-    have a stable token to match on. The legacy ``DEPRECATION_SENTINEL``
-    comment is preserved on the fifth line for one release cycle so
-    tools that still search for it continue to work.
-    """
-    return (
-        "<!-- AUTO-GENERATED by task migrate:vbrief -- DO NOT EDIT MANUALLY -->\n"
-        "<!-- Purpose: deprecation redirect -->\n"
-        "<!-- Source of truth: n/a -->\n"
-        "<!-- Regenerate with: task migrate:vbrief -->\n"
-        f"{DEPRECATION_SENTINEL}\n"
-        f"# {original_name} -- DEPRECATED\n"
-        f"\n"
-        f"This file has been replaced by the vBRIEF-centric document model.\n"
-        f"\n"
-        f"**See instead:**\n"
-        f"- `{pointer_target}` -- project definition and scope registry\n"
-        f"- `vbrief/pending/` -- individual scope vBRIEFs (backlog)\n"
-        f"- `vbrief/active/` -- in-progress scope vBRIEFs\n"
-        f"\n"
-        f"{scope_note}\n"
-        f"\n"
-        f"Migrated on {_TODAY} by `task migrate:vbrief` (RFC #309, Story #312).\n"
-    )
-
-
-# --- gitignore helper (#530 + #567) ---
-def _ensure_gitignore_patterns(
-    project_root: Path, *, dry_run: bool
-) -> tuple[str | None, FileModification | None]:
-    """Append migration-backup gitignore patterns to ``.gitignore`` idempotently.
-
-    Per issue #530 Option A: the migrator writes the two ``.premigrate.*``
-    glob patterns under a comment block so the backups do not leak into
-    commits on greenfield consumer projects. Idempotent -- checks whether
-    each pattern is already present as a standalone rule before appending.
-    If ``.gitignore`` is absent, it is created.
-
-    Per issue #567: when a non-dry-run write actually lands, also return
-    a ``FileModification`` record (pre_hash / post_hash / appended bytes /
-    operation = ``append`` or ``create``) so rollback can symmetrically
-    reverse the forward-pass edit.
-
-    Returns ``(log_line, file_modification)``. ``log_line`` is ``None``
-    when the append is a no-op (patterns already present); ``file_
-    modification`` is ``None`` under ``dry_run`` or when no write landed.
-    """
-    gitignore = project_root / ".gitignore"
-    existing: list[str]
-    pre_existed = gitignore.is_file()
-    if pre_existed:
-        try:
-            existing_text = gitignore.read_text(encoding="utf-8")
-        except OSError:
-            return None, None
-        existing = existing_text.splitlines()
-    else:
-        existing_text = ""
-        existing = []
-
-    # A pattern is considered "present" if it appears verbatim on any
-    # non-comment line. This matches git's own loose interpretation: a
-    # project-level override that negates the pattern (``!*.premigrate.md``)
-    # still counts as "gitignore is aware of it" for our purposes.
-    existing_patterns = {
-        line.strip()
-        for line in existing
-        if line.strip() and not line.strip().startswith("#")
-    }
-    missing = [p for p in _GITIGNORE_PATTERNS if p not in existing_patterns]
-    if not missing:
-        return None, None
-
-    # Build the new block. When any patterns are missing we always include
-    # the full comment block for the first append so operators see the
-    # rationale. If the marker line is already present (partial prior
-    # append), skip re-emitting the comment block and just append the
-    # missing patterns under a short note.
-    block_lines: list[str] = []
-    if _GITIGNORE_MARKER_LINE in existing:
-        block_lines.append(
-            "# Additional migration backup patterns appended by "
-            "`task migrate:vbrief`."
-        )
-    else:
-        block_lines.extend(_GITIGNORE_COMMENT_BLOCK)
-    block_lines.extend(missing)
-    # Ensure the file ends with a newline before appending so we do not
-    # merge our comment onto a previous pattern line.
-    separator = ""
-    if existing_text and not existing_text.endswith("\n"):
-        separator = "\n"
-    # ``appended_content`` captures the EXACT bytes we add to the file
-    # (including the leading separator / blank-line spacer) so the #567
-    # rollback path can strip them verbatim.
-    appended_content = (
-        separator
-        + ("\n" if existing_text else "")
-        + "\n".join(block_lines)
-        + "\n"
-    )
-    if pre_existed:
-        new_text = existing_text + appended_content
-        operation = "append"
-    else:
-        # Greenfield: the full file body IS the appended content and
-        # rollback deletes the file rather than stripping a suffix.
-        new_text = "\n".join(block_lines) + "\n"
-        appended_content = new_text
-        operation = "create"
-
-    rel = ".gitignore"
-    verb = "CREATE" if not pre_existed else "UPDATE"
-    if dry_run:
-        return (
-            f"DRYRUN {verb} {rel} (append {len(missing)} migration-backup "
-            f"pattern(s): {', '.join(missing)})"
-        ), None
-    pre_hash = sha256_of(gitignore) if pre_existed else ""
-    gitignore.write_text(new_text, encoding="utf-8")
-    post_hash = sha256_of(gitignore)
-    modification = FileModification(
-        path=rel,
-        operation=operation,
-        pre_hash=pre_hash,
-        post_hash=post_hash,
-        appended_content=appended_content,
-    )
-    return (
-        f"{verb} {rel} (append {len(missing)} migration-backup "
-        f"pattern(s): {', '.join(missing)})"
-    ), modification
-# --- end gitignore helper ---
-
-
-# --- traces strip helpers (#529) ---
-def _strip_traces_from_narrative(narrative: str) -> tuple[str, list[str]]:
-    """Strip ``**Traces**: ...`` lines from a LegacyArtifacts narrative.
-
-    ``plan.items[].subItems[].narrative.Traces`` is the single source of
-    truth (see issue #529 for the 25/36 drift inventory). The duplicated
-    ``**Traces**: ...`` line inside each LegacyArtifacts task block is
-    stripped during migration so downstream tooling cannot pick a stale
-    second copy.
-
-    Returns ``(cleaned_narrative, stripped_task_ids)``. The cleaned
-    narrative preserves every other line verbatim; stripped task ids are
-    attributed to the preceding ``### tX.Y.Z`` header when available, or
-    recorded as ``<unattributed>`` when a ``**Traces**:`` line appears
-    outside any recognised task block.
-    """
-    if not narrative or "**Traces**" not in narrative:
-        return narrative, []
-
-    stripped_ids: list[str] = []
-    lines = narrative.splitlines()
-    current_task_id = ""
-    cleaned: list[str] = []
-    for line in lines:
-        header_match = _TASK_HEADER_RE.match(line)
-        if header_match:
-            current_task_id = header_match.group("task_id")
-        if _TRACES_LINE_RE.match(line):
-            attribution = current_task_id or "<unattributed>"
-            if attribution not in stripped_ids:
-                stripped_ids.append(attribution)
-            continue
-        cleaned.append(line)
-    # Preserve the trailing newline shape of the input (emit_legacy_artifacts
-    # emits narratives terminated with ``\n``).
-    trailing_newline = "\n" if narrative.endswith("\n") else ""
-    return "\n".join(cleaned) + trailing_newline, stripped_ids
-
-
-def _write_traces_stripped_note(
-    project_root: Path,
-    stripped_audit: list[dict],
-    *,
-    dry_run: bool,
-) -> tuple[Path | None, str | None]:
-    """Append a Traces-stripped section to ``vbrief/migration/RECONCILIATION.md``.
-
-    Creates the file if it doesn't exist. Returns ``(path, log_line)``.
-    ``log_line`` is ``None`` when ``stripped_audit`` is empty (nothing to
-    emit). Called after :func:`_vbrief_reconciliation.write_reconciliation_report`
-    so the Traces-stripped section follows any reconciliation conflicts
-    already recorded in the same file.
-    """
-    if not stripped_audit:
-        return None, None
-    report_dir = project_root / "vbrief" / "migration"
-    target = report_dir / "RECONCILIATION.md"
-    total = sum(len(entry.get("task_ids", [])) for entry in stripped_audit)
-
-    section_lines: list[str] = [
-        "## Traces lines stripped from LegacyArtifacts (#529)",
-        "",
-        (
-            "Per issue #529 the migrator strips duplicated ``**Traces**: ...`` "
-            "lines from LegacyArtifacts task blocks so downstream tooling reads "
-            "a single source of truth from ``plan.items[].subItems[].narrative.Traces``."
-        ),
-        "",
-    ]
-    for entry in stripped_audit:
-        source = entry.get("source", "?")
-        task_ids = entry.get("task_ids", []) or ["<none>"]
-        section_lines.append(f"- `{source}`: {', '.join(task_ids)}")
-    section_lines.append("")
-
-    section = "\n".join(section_lines)
-    rel = "vbrief/migration/RECONCILIATION.md"
-
-    if dry_run:
-        return None, (
-            f"DRYRUN APPEND {rel} (Traces-stripped audit: {total} task(s))"
-        )
-
-    report_dir.mkdir(parents=True, exist_ok=True)
-    if target.is_file():
-        existing = target.read_text(encoding="utf-8")
-        # Idempotency guard (Greptile #561 P2): re-running the migrator on
-        # a project whose PROJECT.md / PRD.md still carries **Traces**:
-        # lines would otherwise append a duplicate section on every pass.
-        # Skip when the canonical section header is already present.
-        if _TRACES_SECTION_HEADER in existing:
-            return target, (
-                f"SKIP   {rel} (Traces-stripped section already recorded)"
-            )
-        if not existing.endswith("\n"):
-            existing += "\n"
-        separator = "" if existing.endswith("\n\n") else "\n"
-        target.write_text(existing + separator + section, encoding="utf-8")
-        verb = "APPEND"
-    else:
-        header = (
-            "# Migration reconciliation report\n"
-            "\n"
-            f"Generated: {now_utc_iso()}\n"
-            "\n"
-            "Per #496 / #529 this file records SPEC/ROADMAP reconciliation "
-            "decisions and LegacyArtifacts traces-line stripping performed "
-            "during `task migrate:vbrief`.\n"
-            "\n"
-        )
-        target.write_text(header + section, encoding="utf-8")
-        verb = "CREATE"
-    return target, f"{verb} {rel} (Traces-stripped audit: {total} task(s))"
-# --- end traces strip helpers ---
-
-
-def _track_managed_subdir(
-    project_root: Path,
-    subdir_name: str,
-    pre_existed: dict[str, bool],
-    created_dirs: list[str],
-) -> None:
-    """Add ``vbrief/{subdir_name}`` to ``created_dirs`` if we created it (#527/#528).
-
-    Uses ``pre_existed`` (captured at migration start) so the decision is
-    derived from safety-manifest state, not from scanning the filesystem.
-    A repeat call is a no-op, preserving idempotency for callers that may
-    invoke this at multiple points in the migration flow.
-    """
-    rel = f"vbrief/{subdir_name}"
-    if pre_existed.get(subdir_name):
-        return
-    if rel in created_dirs:
-        return
-    folder = project_root / "vbrief" / subdir_name
-    if folder.is_dir():
-        created_dirs.append(rel)
-
-
-# --- prettier remediation breadcrumb (#670) ---
-# The migrator's generated artifacts (Markdown stubs + JSON vBRIEFs) are not
-# guaranteed to be byte-identical to what ``prettier --write`` would produce
-# (Python ``json.dumps`` always expands single-element arrays prettier would
-# collapse; trivial Markdown spacing around HTML-comment blocks). Migration is
-# a rare one-shot pre-v0.20 legacy path, so byte-matching prettier in the
-# generator (#670 option 1) or auto-running it (option 2) is intentionally out
-# of scope. Instead we emit a remediation breadcrumb so a consumer whose
-# ``task check`` runs ``prettier --check`` (or ``task fmt:check``) turns a
-# surprise baseline failure into a known one-command fix.
-_PRETTIER_BREADCRUMB_MARKER = "Prettier remediation (#670)"
-
-# Canonical generated paths the breadcrumb enumerates. These are the migration
-# outputs most likely to trip ``prettier --check``.
-_PRETTIER_BREADCRUMB_PATHS: tuple[str, ...] = (
-    "SPECIFICATION.md",
-    "PROJECT.md",
-    "ROADMAP.md",
-    "vbrief/specification.vbrief.json",
-    "vbrief/PROJECT-DEFINITION.vbrief.json",
-    "vbrief/migration/LEGACY-REPORT.md",
-)
-
-
-def _prettier_breadcrumb_body() -> list[str]:
-    """Return the remediation note body as plain-text lines (no Markdown heading).
-
-    Shared verbatim between the stdout action log and the
-    ``vbrief/migration/LEGACY-REPORT.md`` section (the latter under a ``##``
-    heading) so the two surfaces never drift.
-    """
-    lines = [
-        f"{_PRETTIER_BREADCRUMB_MARKER}: migration output is NOT guaranteed to "
-        "be prettier-clean. If your `task check` runs `prettier --check` (or "
-        "`task fmt:check`), these generated files may fail the gate on a fresh "
-        "post-migration checkout:",
-    ]
-    for path in _PRETTIER_BREADCRUMB_PATHS:
-        lines.append(f"  - {path}")
-    lines.append(
-        "Fix before `task check`: run `prettier --write` on the files above, "
-        "or add them to `.prettierignore`."
-    )
-    return lines
-
-
-def _append_prettier_breadcrumb(report_path: Path) -> bool:
-    """Append the prettier remediation section to an existing LEGACY-REPORT.md.
-
-    Idempotent: returns ``False`` without writing when the breadcrumb marker
-    is already present (a migrator re-run), and ``True`` after appending
-    otherwise. The caller only invokes this when ``report_path`` exists --
-    i.e. ``scripts/_vbrief_legacy.emit_legacy_report`` captured legacy
-    sections (the typical pre-v0.20 migration) -- so the breadcrumb augments
-    the legacy report rather than creating a misleadingly-titled report with
-    no legacy content captured.
-    """
-    existing = report_path.read_text(encoding="utf-8")
-    if _PRETTIER_BREADCRUMB_MARKER in existing:
-        return False
-    section = "\n".join(
-        [f"## {_PRETTIER_BREADCRUMB_MARKER}", ""] + _prettier_breadcrumb_body()
-    )
-    report_path.write_text(
-        existing.rstrip("\n") + "\n\n" + section + "\n", encoding="utf-8"
-    )
-    return True
-# --- end prettier remediation breadcrumb ---
-
-
-def migrate(
-    project_root: Path,
-    *,
-    dry_run: bool = False,
-    force: bool = False,
-    strict: bool = False,
-) -> tuple[bool, list[str]]:
-    """Run the full migration on the given project root.
-
-    ``dry_run`` -- when True, produce the full action log without writing any
-    file to disk (#497-2).  All backup, manifest, and lifecycle-folder lines
-    are prefixed ``DRYRUN`` so the operator can distinguish a plan from a
-    real run.
-
-    ``force`` -- when True, bypass the dirty-tree guard (#497-3).  The guard
-    refuses to run on a dirty working tree by default to keep migration
-    output separable from in-progress edits.
-
-    ``strict`` -- when True (``task migrate:vbrief -- --strict`` per #496),
-    exit non-zero if SPEC and ROADMAP disagreed on any dimension or any
-    override from ``vbrief/migration-overrides.yaml`` triggered. Scope
-    vBRIEFs and ``vbrief/migration/RECONCILIATION.md`` are still written so
-    the operator can inspect before re-running without ``--strict``.
-
-    Returns:
-        (True, actions) on success -- actions is a list of human-readable lines.
-        (False, errors) on failure.
-    """
-    actions: list[str] = []
-    warnings: list[str] = []
-    vbrief_dir = project_root / "vbrief"
-    created_files: list[str] = []
-    created_dirs: list[str] = []
-
-    # #527 / #528: snapshot which migrator-managed subdirs pre-existed so we
-    # can record any we create in the safety manifest's ``created_dirs``.
-    # Tracking is derived from this captured state -- NOT from post-hoc
-    # filesystem scans -- so rollback's RMDIR decision comes straight from
-    # the manifest and never clobbers a directory that was already present.
-    managed_subdir_pre_existed: dict[str, bool] = {
-        name: (vbrief_dir / name).is_dir() for name in _MANAGED_SUBDIRS
-    }
-
-    # --- safety (Agent C, #497) ---
-    # Dirty-tree guard (#497-3): refuse on a non-clean git status unless the
-    # operator passes --force.  Runs BEFORE any filesystem mutation so a
-    # dirty-tree refusal leaves the project in its exact pre-run state.
-    # --dry-run is explicitly exempt (Greptile #509 P1): dry-run is read-only,
-    # cannot corrupt state, and operators are encouraged to preview BEFORE
-    # committing any pending edits. Pairing --force with --dry-run to preview
-    # on an unfamiliar project would defeat the purpose of dry-run.
-    if not force and not dry_run and is_tree_dirty(project_root):
-        # #635: emit dirty-tree event before returning the refusal so any
-        # consumer (skill, task, CI runner) can react uniformly. Existing
-        # CLI output (the canonical refusal message) is preserved. The
-        # events surface MUST NOT break the migrator, so registry/IO
-        # failures are silently suppressed.
-        with contextlib.suppress(Exception):
-            _emit_event(
-                "dirty-tree:detected",
-                {"project_root": str(project_root.resolve())},
-            )
-        return False, [dirty_tree_refusal_message()]
-
-    # Always-on backups (#497-1): copy every pre-cutover input to its
-    # .premigrate.* sibling BEFORE we touch anything else (the lifecycle
-    # folder creation below is technically the first filesystem write, but
-    # backups come first so we can surface an actionable error if a backup
-    # itself fails before any write lands).
-    backup_pairs = plan_backups(project_root)
-    backup_records, backup_actions = write_backups(
-        project_root, backup_pairs, dry_run=dry_run
-    )
-    actions.extend(backup_actions)
-    # --- end safety ---
-
-    # --- gitignore (#530 + #567) ---
-    # Append the ``.premigrate.*`` glob patterns to the consumer project's
-    # ``.gitignore`` on first migration so backups never leak into commits.
-    # Idempotent on subsequent runs. The helper also returns a
-    # ``FileModification`` record (pre_hash / post_hash /
-    # appended_content) that we stash for the safety manifest so
-    # ``--rollback`` can reverse this edit symmetrically with
-    # ``post_migration_stub_hashes`` (#567).
-    gitignore_action, gitignore_modification = _ensure_gitignore_patterns(
-        project_root, dry_run=dry_run
-    )
-    if gitignore_action:
-        actions.append(gitignore_action)
-    file_modifications: list[FileModification] = []
-    if gitignore_modification is not None:
-        file_modifications.append(gitignore_modification)
-    # --- end gitignore ---
-
-    # ---- Step 1: Create lifecycle folders ----
-    for folder_name in LIFECYCLE_FOLDERS:
-        folder = vbrief_dir / folder_name
-        rel = folder.relative_to(project_root).as_posix()
-        if folder.exists():
-            actions.append(f"SKIP  lifecycle folder already exists: vbrief/{folder_name}/")
-        elif dry_run:
-            actions.append(f"DRYRUN CREATE lifecycle folder: vbrief/{folder_name}/")
-        else:
-            folder.mkdir(parents=True, exist_ok=True)
-            created_dirs.append(rel)
-            actions.append(f"CREATE lifecycle folder: vbrief/{folder_name}/")
-
-    # ---- Step 2: Read existing sources ----
-    spec_vbrief_path = vbrief_dir / "specification.vbrief.json"
-    spec_vbrief: dict | None = None
-    if spec_vbrief_path.exists():
-        try:
-            spec_vbrief = json.loads(spec_vbrief_path.read_text(encoding="utf-8"))
-            actions.append("READ  vbrief/specification.vbrief.json")
-        except json.JSONDecodeError as exc:
-            return False, [f"ERROR: invalid JSON in specification.vbrief.json: {exc}"]
-
-        # #571: the migrator now guarantees that every ingested
-        # ``specification.vbrief.json`` is stamped with the current
-        # ``EMITTED_VBRIEF_VERSION`` before being written back to disk.
-        # Previously the ``_ingest_spec_narratives`` path only merged new
-        # keys under ``plan.narratives`` and left ``vBRIEFInfo.version``
-        # at its pre-migration value, so consumers that started at v0.5
-        # stayed at v0.5 after a "successful" migration and then hit a
-        # hard-fail on the next ``task spec:validate`` with a misleading
-        # "Migrate legacy v0.5 vBRIEFs via the migrator sweep" error --
-        # pointing at a sweep that did not exist for these files.
-        if isinstance(spec_vbrief, dict):
-            envelope = spec_vbrief.setdefault("vBRIEFInfo", {})
-            if isinstance(envelope, dict) and envelope.get(
-                "version"
-            ) != EMITTED_VBRIEF_VERSION:
-                prior_version = envelope.get("version")
-                envelope["version"] = EMITTED_VBRIEF_VERSION
-                # Greptile P1 on this PR: persist-or-log split mirrors
-                # the plan.vbrief.json branch below so ``--dry-run``
-                # surfaces the bump as ``DRYRUN BUMP ...`` rather than
-                # a bare ``BUMP ...`` that would mislead operators
-                # previewing a run into thinking the change landed.
-                if dry_run:
-                    actions.append(
-                        "DRYRUN BUMP specification.vbrief.json "
-                        "vBRIEFInfo.version "
-                        f"{prior_version!r} -> "
-                        f"{EMITTED_VBRIEF_VERSION!r} (#571)"
-                    )
-                else:
-                    # Persist the bump immediately so even a no-
-                    # narrative-ingest migration lands v0.6 on disk.
-                    # Subsequent ingest writes may re-serialize the
-                    # same (already-bumped) in-memory copy; that is
-                    # harmless because the envelope has already been
-                    # mutated.
-                    spec_vbrief_path.write_text(
-                        json.dumps(spec_vbrief, indent=2, ensure_ascii=False)
-                        + "\n",
-                        encoding="utf-8",
-                    )
-                    actions.append(
-                        "BUMP  specification.vbrief.json "
-                        "vBRIEFInfo.version "
-                        f"{prior_version!r} -> "
-                        f"{EMITTED_VBRIEF_VERSION!r} (#571)"
-                    )
-    else:
-        actions.append("SKIP  vbrief/specification.vbrief.json not found")
-
-    # #571: mirror the spec_vbrief version bump on any pre-existing
-    # ``vbrief/plan.vbrief.json``. ``migrate_speckit_plan()`` already
-    # force-bumps the envelope on its speckit-shaped conversion path
-    # (L2053-L2056 below), but a non-speckit session-scoped
-    # plan.vbrief.json never reaches that function during the normal
-    # ``task migrate:vbrief`` flow -- so it used to stay at v0.5
-    # indefinitely and later fail ``spec:validate``. Here we read it,
-    # bump the envelope in-place, and rewrite it with no other shape
-    # changes so the operator gets a clean v0.5 -> v0.6 flip without
-    # surprises.
-    plan_vbrief_path = vbrief_dir / "plan.vbrief.json"
-    if plan_vbrief_path.is_file():
-        try:
-            plan_vbrief_data = json.loads(
-                plan_vbrief_path.read_text(encoding="utf-8")
-            )
-        except json.JSONDecodeError as exc:
-            return False, [
-                f"ERROR: invalid JSON in plan.vbrief.json: {exc}"
-            ]
-        if isinstance(plan_vbrief_data, dict):
-            plan_envelope = plan_vbrief_data.setdefault("vBRIEFInfo", {})
-            if isinstance(plan_envelope, dict) and plan_envelope.get(
-                "version"
-            ) != EMITTED_VBRIEF_VERSION:
-                prior_plan_version = plan_envelope.get("version")
-                plan_envelope["version"] = EMITTED_VBRIEF_VERSION
-                if dry_run:
-                    actions.append(
-                        "DRYRUN BUMP plan.vbrief.json vBRIEFInfo.version "
-                        f"{prior_plan_version!r} -> "
-                        f"{EMITTED_VBRIEF_VERSION!r} (#571)"
-                    )
-                else:
-                    plan_vbrief_path.write_text(
-                        json.dumps(
-                            plan_vbrief_data, indent=2, ensure_ascii=False
-                        )
-                        + "\n",
-                        encoding="utf-8",
-                    )
-                    actions.append(
-                        "BUMP  plan.vbrief.json vBRIEFInfo.version "
-                        f"{prior_plan_version!r} -> "
-                        f"{EMITTED_VBRIEF_VERSION!r} (#571)"
-                    )
-
-    spec_md_path = project_root / "SPECIFICATION.md"
-    spec_md_content: str | None = None
-    if spec_md_path.exists():
-        spec_md_content = spec_md_path.read_text(encoding="utf-8")
-        actions.append("READ  SPECIFICATION.md")
-
-    project_md_path = project_root / "PROJECT.md"
-    project_content: str | None = None
-    if project_md_path.exists():
-        project_content = project_md_path.read_text(encoding="utf-8")
-        actions.append("READ  PROJECT.md")
-
-    roadmap_path = project_root / "ROADMAP.md"
-    roadmap_items, phase_descriptions, completed_items = _parse_roadmap_items(roadmap_path)
-    total_items = len(roadmap_items) + len(completed_items)
-    if total_items:
-        actions.append(
-            f"READ  ROADMAP.md ({len(roadmap_items)} active, "
-            f"{len(completed_items)} completed items parsed)"
-        )
-    else:
-        actions.append("SKIP  ROADMAP.md not found or no items parsed")
-
-    # Resolve repository URL for provenance references. The ``project_root``
-    # arg enables the ``git remote get-url origin`` fallback added in #613 so
-    # scope vBRIEFs built without a pre-existing ``specification.vbrief.json``
-    # repository hint still get canonical ``{uri, type, title}`` references.
-    repo_url = _resolve_repo_url(spec_vbrief, project_root=project_root)
-
-    # ---- Step 2b: Ingest PRD/SPECIFICATION structured narratives (#397) ----
-    prd_path = project_root / "PRD.md"
-    ingested_narratives: dict[str, str] = {}
-
-    if prd_path.exists():
-        prd_content = prd_path.read_text(encoding="utf-8")
-        actions.append("READ  PRD.md")
-        ingested_narratives.update(_parse_prd_narratives(prd_content))
-
-    if spec_md_content and DEPRECATION_SENTINEL not in spec_md_content:
-        spec_parsed = _parse_prd_narratives(spec_md_content)
-        # SPECIFICATION.md sections take priority over PRD.md for overlaps
-        ingested_narratives.update(spec_parsed)
-
-    if ingested_narratives:
-        # Ensure spec_vbrief structure exists
-        if spec_vbrief is None:
-            spec_vbrief = {
-                "vBRIEFInfo": {
-                    "version": EMITTED_VBRIEF_VERSION,
-                    "description": "Specification",
-                },
-                "plan": {
-                    "title": "Specification",
-                    "status": "approved",
-                    "narratives": {},
-                    "items": [],
-                },
-            }
-
-        existing = spec_vbrief.setdefault("plan", {}).setdefault("narratives", {})
-        ingested_keys: list[str] = []
-        for key, value in ingested_narratives.items():
-            if key not in existing:
-                existing[key] = value
-                ingested_keys.append(key)
-
-        if ingested_keys:
-            rel = spec_vbrief_path.relative_to(project_root).as_posix()
-            created_new_spec_vbrief = not spec_vbrief_path.exists()
-            if dry_run:
-                actions.append(
-                    f"DRYRUN INGEST narratives into specification.vbrief.json: "
-                    f"{', '.join(sorted(ingested_keys))}"
-                )
-            else:
-                spec_vbrief_path.parent.mkdir(parents=True, exist_ok=True)
-                spec_vbrief_path.write_text(
-                    json.dumps(spec_vbrief, indent=2, ensure_ascii=False) + "\n",
-                    encoding="utf-8",
-                )
-                if created_new_spec_vbrief:
-                    created_files.append(rel)
-                actions.append(
-                    f"INGEST narratives into specification.vbrief.json: "
-                    f"{', '.join(sorted(ingested_keys))}"
-                )
-
-    # --- fidelity (Agent A, #495) ---
-    # Parse the raw SPECIFICATION.md for per-task bodies (Description /
-    # DependsOn / AcceptanceCriteria / Traces) + FR-N / NFR-N definitions
-    # + non-canonical ## sections.  Enrich spec_vbrief.plan.items so Agent
-    # B's reconciliation picks up the bodies through its "spec owns body"
-    # path (#506 D2 #14).  Emit the Requirements narrative (#495-4) and
-    # plan.edges[] (#495-6, #506 D4) on the spec vBRIEF.  Collect legacy
-    # SPEC sections for #505 capture at the end of the run.
-    spec_tasks: list[dict] = []
-    requirement_defs: dict[str, str] = {}
-    spec_legacy_sections: list[tuple[str, str, int, int]] = []
-    fidelity_log: list[dict] = []
-    if spec_md_content and DEPRECATION_SENTINEL not in spec_md_content:
-        spec_tasks = _parse_spec_tasks(spec_md_content)
-        requirement_defs = _parse_requirement_definitions(spec_md_content)
-        _canon, fidelity_log, spec_legacy_sections = _ingest_spec_narratives(
-            spec_md_content, source_file="SPECIFICATION.md"
-        )
-        if spec_vbrief is None:
-            spec_vbrief = {
-                "vBRIEFInfo": {
-                    "version": EMITTED_VBRIEF_VERSION,
-                    "description": "Specification",
-                },
-                "plan": {
-                    "title": "Specification",
-                    "status": "approved",
-                    "narratives": {},
-                    "items": [],
-                },
-            }
-        spec_plan = spec_vbrief.setdefault("plan", {})
-        spec_narratives = spec_plan.setdefault("narratives", {})
-
-        # Requirements narrative (#495-4): FR/NFR defs emitted as a single
-        # string. Preserve any pre-existing narrative.
-        req_narrative = _build_requirements_narrative(requirement_defs)
-        if req_narrative and not spec_narratives.get("Requirements"):
-            spec_narratives["Requirements"] = req_narrative
-            actions.append(
-                "FIDELITY specification.vbrief.json Requirements: "
-                f"{len(requirement_defs)} FR/NFR definition(s)"
-            )
-
-        # plan.edges[] from per-task Depends-on (#495-6, D4).
-        edges = _build_edges_from_tasks(spec_tasks)
-        if edges:
-            existing_edges = spec_plan.get("edges", [])
-            if not isinstance(existing_edges, list):
-                existing_edges = []
-            seen_keys = {
-                (str(e.get("from", "")), str(e.get("to", "")),
-                 str(e.get("type", "")))
-                for e in existing_edges if isinstance(e, dict)
-            }
-            new_count = 0
-            for edge in edges:
-                key = (edge["from"], edge["to"], edge["type"])
-                if key not in seen_keys:
-                    existing_edges.append(edge)
-                    seen_keys.add(key)
-                    new_count += 1
-            if new_count:
-                spec_plan["edges"] = existing_edges
-                actions.append(
-                    f"FIDELITY specification.vbrief.json plan.edges[]: "
-                    f"{new_count} Depends-on edge(s) emitted (#506 D4)"
-                )
-
-        # Enrich spec_vbrief.plan.items with per-task narratives so B's
-        # reconciliation picks up Description / DependsOn / AcceptanceCriteria
-        # / Traces from SPEC.md bodies (#495-1). Match by task_id; when no
-        # matching item exists, synthesize a new item so the body is not lost.
-        spec_items = spec_plan.setdefault("items", [])
-        if not isinstance(spec_items, list):
-            spec_items = []
-            spec_plan["items"] = spec_items
-
-        def _find_spec_item(task_id: str) -> dict | None:
-            for item in spec_items:
-                if isinstance(item, dict) and str(item.get("id", "")) == task_id:
-                    return item
-            return None
-
-        enriched_count = 0
-        for task in spec_tasks:
-            task_id = task.get("task_id", "")
-            if not task_id:
-                continue
-            task_narr = _task_scope_narratives(task)
-            if not task_narr:
-                continue
-            item = _find_spec_item(task_id)
-            if item is None:
-                item = {
-                    "id": task_id,
-                    "title": task.get("title", task_id),
-                    "status": task.get("status", "pending"),
-                    "narrative": {},
-                }
-                spec_items.append(item)
-            narrative = item.setdefault("narrative", {})
-            if not isinstance(narrative, dict):
-                narrative = {}
-                item["narrative"] = narrative
-            for key, value in task_narr.items():
-                if not narrative.get(key):
-                    narrative[key] = value
-                    enriched_count += 1
-
-        if enriched_count:
-            actions.append(
-                f"FIDELITY specification.vbrief.json items enriched: "
-                f"{enriched_count} per-task narrative field(s) (#495-1)"
-            )
-
-        # Persist the enriched spec vBRIEF so Agent B's reconciliation
-        # reads the enriched state.  Skipped under --dry-run.
-        if not dry_run and (req_narrative or edges or enriched_count):
-            rel_spec = spec_vbrief_path.relative_to(project_root).as_posix()
-            created_new = not spec_vbrief_path.exists()
-            spec_vbrief_path.parent.mkdir(parents=True, exist_ok=True)
-            spec_vbrief_path.write_text(
-                json.dumps(spec_vbrief, indent=2, ensure_ascii=False) + "\n",
-                encoding="utf-8",
-            )
-            if created_new and rel_spec not in created_files:
-                created_files.append(rel_spec)
-
-    # Disambiguated migration log (#495-15): every section routing decision
-    # gets a ROUTE line recording source : line-range -> target-key -> target-file.
-    for entry in fidelity_log:
-        actions.append(_format_migration_log_entry(entry))
-    # --- end fidelity ---
-
-    # --- reconciliation (Agent B, #496) ---
-    # Load overrides BEFORE defaults apply, then reconcile SPEC + ROADMAP
-    # into a single list of routed scope items. The report captures every
-    # resolved disagreement for downstream emission to
-    # vbrief/migration/RECONCILIATION.md and for --strict exit-code gating.
-    overrides = _load_overrides(vbrief_dir)
-    if overrides:
-        actions.append(
-            f"READ  vbrief/migration-overrides.yaml ({len(overrides)} override(s))"
-        )
-    reconciled_items, reconciliation_report = _reconcile_scope_items(
-        roadmap_active=roadmap_items,
-        roadmap_completed=completed_items,
-        spec_vbrief=spec_vbrief,
-        phase_descriptions=phase_descriptions,
-        overrides=overrides,
-    )
-    # --- end reconciliation ---
-
-    # ---- Step 3: Generate PROJECT-DEFINITION.vbrief.json ----
-    proj_def_path = vbrief_dir / "PROJECT-DEFINITION.vbrief.json"
-    if proj_def_path.exists():
-        actions.append("SKIP  PROJECT-DEFINITION.vbrief.json already exists (idempotent)")
-    else:
-        # #499-registry: pass reconciled items so PROJECT-DEFINITION
-        # plan.items[*].status mirrors each scope's reconciled status. Falls
-        # back to raw roadmap_items + completed_items for the degenerate
-        # case where no ROADMAP existed (reconciled_items is empty and the
-        # registry was historically empty too).
-        if reconciled_items:
-            registry_items = [
-                {
-                    "number": r.get("number", ""),
-                    "title": r.get("title", "Untitled"),
-                    "status": r.get("status", "pending"),
-                    "phase": r.get("phase", ""),
-                    "task_id": r.get("original_task_id", ""),
-                    "synthetic_id": r.get("synthetic_id", ""),
-                }
-                for r in reconciled_items
-            ]
-        else:
-            registry_items = roadmap_items + completed_items
-        proj_def = _build_project_definition(
-            spec_vbrief,
-            project_content,
-            registry_items,
-            repo_url=repo_url,
-            spec_md_content=spec_md_content,
-        )
-        if dry_run:
-            actions.append("DRYRUN CREATE vbrief/PROJECT-DEFINITION.vbrief.json")
-        else:
-            proj_def_path.write_text(
-                json.dumps(proj_def, indent=2, ensure_ascii=False) + "\n",
-                encoding="utf-8",
-            )
-            created_files.append(
-                proj_def_path.relative_to(project_root).as_posix()
-            )
-            actions.append("CREATE vbrief/PROJECT-DEFINITION.vbrief.json")
-
-    # --- lifecycle-routing (Agent B, #499) ---
-    # Write each reconciled scope vBRIEF to the lifecycle folder chosen by
-    # the reconciler (proposed / pending / active / completed / cancelled
-    # per #506). Replaces the old Steps 4 + 4b that dumped everything into
-    # pending/ or completed/. Orphan ROADMAP items route to proposed/ with
-    # narrative.SourceConflict = "missing-from-spec".
-    #
-    # #532: filename stem uses ``slug_normalize.normalize_slug`` (Unicode
-    # NFKD, checkbox markers stripped, word-boundary truncation at 60 chars,
-    # Windows-reserved fallback). The id prefix is still emitted via
-    # ``slugify_id`` (#498) because it is ALSO used as an in-JSON
-    # ``plan.items[*].id`` value that must match the schema ID regex.
-    emitted_stems: set[str] = set()
-    for reconciled in reconciled_items:
-        folder = reconciled.get("folder", "pending")
-        number = reconciled.get("number", "")
-        id_source = slug_fallback_id({
-            "number": number,
-            "task_id": reconciled.get("original_task_id", ""),
-            "synthetic_id": reconciled.get("synthetic_id", ""),
-            "title": reconciled.get("title", "untitled"),
-        })
-        id_part = slugify_id(id_source)
-        # Compose id + raw title then normalize as a single unit so the
-        # word-boundary truncation rule considers the full composed stem.
-        raw_title = reconciled.get("title", "untitled") or "untitled"
-        composed_raw = f"{id_part}-{raw_title}" if id_part else raw_title
-        normalized_stem = _normalize_slug(composed_raw, max_len=_SLUG_MAX_LEN)
-        stem = _disambiguate_slug(
-            normalized_stem, emitted_stems, max_len=_SLUG_MAX_LEN
-        )
-        emitted_stems.add(stem)
-        # Kept for the human-readable ``label`` fallback below.
-        title_slug = _normalize_slug(
-            reconciled.get("title", "untitled") or "untitled",
-            max_len=_SLUG_MAX_LEN,
-        )
-        filename = f"{_TODAY}-{stem}.vbrief.json"
-        target_folder = vbrief_dir / folder
-        if not target_folder.exists() and not dry_run:
-            target_folder.mkdir(parents=True, exist_ok=True)
-        target_path = target_folder / filename
-
-        if target_path.exists():
-            actions.append(
-                f"SKIP  {folder}/{filename} already exists (idempotent)"
-            )
-            continue
-
-        # Check if any existing file references this issue number
-        if number:
-            existing = _find_existing_scope_vbrief(vbrief_dir, number)
-            if existing:
-                actions.append(
-                    f"SKIP  #{number} already has scope vBRIEF: "
-                    f"{existing.relative_to(vbrief_dir)}"
-                )
-                continue
-
-        scope_vbrief = _build_reconciled_scope_vbrief(
-            reconciled,
-            repo_url=repo_url,
-            migration_timestamp=_MIGRATION_TIMESTAMP,
-        )
-        label = (
-            f"#{number}" if number
-            else reconciled.get("task_id") or title_slug
-        )
-        # #593: annotate the CREATE log line with the source section so
-        # operators can audit routing decisions post-migration without
-        # re-running the migrator. ``source_section`` is populated by the
-        # reconciler for every ROADMAP-sourced row; SPEC-only items (no
-        # ROADMAP counterpart) fall back to the short label.
-        source_section = reconciled.get("source_section", "")
-        log_suffix = (
-            f"({label}, from {source_section})"
-            if source_section
-            else f"({label})"
-        )
-        if dry_run:
-            actions.append(f"DRYRUN CREATE {folder}/{filename} {log_suffix}")
-        else:
-            target_path.write_text(
-                json.dumps(scope_vbrief, indent=2, ensure_ascii=False) + "\n",
-                encoding="utf-8",
-            )
-            created_files.append(
-                target_path.relative_to(project_root).as_posix()
-            )
-            actions.append(f"CREATE {folder}/{filename} {log_suffix}")
-    # --- end lifecycle-routing ---
-
-    # ---- Step 5: Deprecation redirects ----
-    # Hashes captured after write (or proposed-write in dry-run) so --rollback
-    # can detect whether the operator has edited the stub since migration.
-    stub_hashes: dict[str, str] = {}
-    if spec_md_path.exists():
-        if spec_md_content and DEPRECATION_SENTINEL in spec_md_content:
-            actions.append("SKIP  SPECIFICATION.md already has deprecation redirect")
-        else:
-            # Check for user customization
-            if spec_md_content and _is_user_customized(spec_md_content, _SPEC_AUTO_MARKERS):
-                # In dry-run the fold target (PROJECT-DEFINITION) may not yet
-                # exist -- _fold_custom_content short-circuits gracefully and
-                # returns False, which would otherwise abort.  Skip the abort
-                # path in dry-run and record the fold as proposed.
-                if dry_run:
-                    warnings.append(
-                        "WARNING: SPECIFICATION.md appears user-customized. "
-                        "Original content would be preserved in "
-                        "PROJECT-DEFINITION.vbrief.json narratives (dry-run)."
-                    )
-                else:
-                    preserved = _fold_custom_content(
-                        proj_def_path, "SpecificationContent", spec_md_content or ""
-                    )
-                    if preserved:
-                        warnings.append(
-                            "WARNING: SPECIFICATION.md appears user-customized. "
-                            "Original content preserved in "
-                            "PROJECT-DEFINITION.vbrief.json narratives."
-                        )
-                    else:
-                        return False, [
-                            "ERROR: SPECIFICATION.md appears user-customized but content could not "
-                            "be preserved in PROJECT-DEFINITION.vbrief.json. Fix the project "
-                            "definition file structure and re-run to prevent data loss."
-                        ]
-
-            redirect = _deprecation_redirect(
-                "SPECIFICATION.md",
-                "vbrief/PROJECT-DEFINITION.vbrief.json",
-                "For scope details, see individual vBRIEF files in the lifecycle folders.",
-            )
-            if dry_run:
-                actions.append("DRYRUN REPLACE SPECIFICATION.md with deprecation redirect")
-            else:
-                spec_md_path.write_text(redirect, encoding="utf-8")
-                stub_hashes["SPECIFICATION.md"] = sha256_of(spec_md_path)
-                actions.append("REPLACE SPECIFICATION.md with deprecation redirect")
-
-    if project_md_path.exists():
-        if project_content and DEPRECATION_SENTINEL in project_content:
-            actions.append("SKIP  PROJECT.md already has deprecation redirect")
-        else:
-            # Check for user customization -- note: PROJECT.md content is already
-            # captured in narratives["ProjectConfig"] by _build_project_definition (step 3),
-            # so the fold here is a safety net only.
-            if project_content and _is_user_customized(project_content, _PROJECT_AUTO_MARKERS):
-                warnings.append(
-                    "WARNING: PROJECT.md appears user-customized. "
-                    "Original content preserved in PROJECT-DEFINITION.vbrief.json narratives."
-                )
-
-            redirect = _deprecation_redirect(
-                "PROJECT.md",
-                "vbrief/PROJECT-DEFINITION.vbrief.json",
-                "For project configuration, see the narratives section.",
-            )
-            if dry_run:
-                actions.append("DRYRUN REPLACE PROJECT.md with deprecation redirect")
-            else:
-                project_md_path.write_text(redirect, encoding="utf-8")
-                stub_hashes["PROJECT.md"] = sha256_of(project_md_path)
-                actions.append("REPLACE PROJECT.md with deprecation redirect")
-
-    # --- legacy-artifacts (Agent A, #505) ---
-    # Capture non-canonical ## sections from SPECIFICATION.md, PROJECT.md,
-    # and PRD.md into a ``LegacyArtifacts`` narrative on the matching
-    # vBRIEF file (per #506 D5 / #505 Section 1).  Sections >6 KB overflow
-    # to ``vbrief/legacy/{stem}-{slug}.md`` sidecars (Section 4).  PRD.md
-    # hand-edited sections get the RFC-defined warning prefix (Section 5).
-    # Emit ``vbrief/migration/LEGACY-REPORT.md`` when any capture occurs
-    # (Section 6) and append a stdout summary (Section 8).
-    #
-    # Skipped under --dry-run so operators can preview the plan without
-    # synthesising sidecar files. The .premigrate.* backups (Agent C)
-    # cover rollback; LegacyArtifacts is an additive preservation mechanism.
-    captures: dict[str, list[dict]] = {
-        "specification.vbrief.json -> LegacyArtifacts": [],
-        "PROJECT-DEFINITION.vbrief.json -> LegacyArtifacts": [],
-        "PRD.md content (flagged: hand-edited)": [],
-    }
-
-    # Pin the event log to ``<project_root>/<DEFAULT_EVENT_LOG>`` so the
-    # migrator's emissions stay scoped to the project being migrated --
-    # without this, ``_resolve_log_path`` would fall back to the agent's
-    # CWD and a test running ``migrate(tmp_path)`` from the repo root
-    # would write events into the deft repo's own log directory. The
-    # default path lives under the already-gitignored ``.deft-cache/``
-    # (relocated from ``.deft/`` in #1465) so the log never leaks as an
-    # untracked file in the migrated consumer.
-    _legacy_event_log = project_root / _DEFAULT_EVENT_LOG
-
-    def _legacy_event_emitter(event_name: str, payload: dict) -> None:
-        """Emit a ``legacy:detected`` framework event per captured section.
-
-        Wraps the shared :func:`scripts._events.emit` helper (aliased here
-        as ``_emit_behavioral_event`` to avoid shadowing the
-        detection-bound ``_emit_event`` wrapper) so the migrator's
-        emission stays out of the inner loop in
-        ``_vbrief_legacy.emit_legacy_artifacts``. Failures are swallowed
-        in the caller (#635 behavioral events wiring; post-#706
-        unification per #709 / #710).
-        """
-        _emit_behavioral_event(event_name, payload, log_path=_legacy_event_log)
-    # #529: collect per-source Traces-stripping audit entries. Each entry
-    # records the source file name and the list of task ids whose
-    # ``**Traces**: ...`` line was stripped from the emitted LegacyArtifacts
-    # narrative. The audit is emitted to ``vbrief/migration/RECONCILIATION.md``
-    # after reconciliation writes its own conflicts.
-    traces_stripped_audit: list[dict] = []
-    if not dry_run:
-        # SPEC.md legacy sections were collected by the fidelity hook above.
-        if spec_legacy_sections:
-            narrative, sidecars, stats = _emit_legacy_artifacts(
-                spec_legacy_sections,
-                "SPECIFICATION.md",
-                project_root,
-                slugify_fn=_slugify_shared,
-                event_emitter=_legacy_event_emitter,
-            )
-            if narrative:
-                narrative, stripped_ids = _strip_traces_from_narrative(narrative)
-                if stripped_ids:
-                    traces_stripped_audit.append({
-                        "source": "SPECIFICATION.md",
-                        "task_ids": stripped_ids,
-                    })
-                if not spec_vbrief_path.exists():
-                    # Nothing has written spec.vbrief.json yet (e.g. SPEC is
-                    # 100% non-canonical) -- synthesize a minimal skeleton
-                    # so LegacyArtifacts has a target file.
-                    spec_vbrief_path.parent.mkdir(parents=True, exist_ok=True)
-                    spec_vbrief_path.write_text(
-                        json.dumps(
-                            {
-                                "vBRIEFInfo": {
-                                    "version": EMITTED_VBRIEF_VERSION,
-                                    "description": "Specification",
-                                },
-                                "plan": {
-                                    "title": "Specification",
-                                    "status": "approved",
-                                    "narratives": {},
-                                    "items": [],
-                                },
-                            },
-                            indent=2,
-                            ensure_ascii=False,
-                        )
-                        + "\n",
-                        encoding="utf-8",
-                    )
-                    created_files.append(
-                        spec_vbrief_path.relative_to(project_root).as_posix()
-                    )
-                _attach_legacy_narrative(spec_vbrief_path, narrative)
-                for sidecar in sidecars:
-                    try:
-                        rel = sidecar.relative_to(project_root).as_posix()
-                    except ValueError:
-                        rel = str(sidecar)
-                    if rel not in created_files:
-                        created_files.append(rel)
-                captures[
-                    "specification.vbrief.json -> LegacyArtifacts"
-                ].extend(stats)
-                actions.append(
-                    "LEGACY specification.vbrief.json LegacyArtifacts: "
-                    f"{len(stats)} section(s)"
-                )
-
-        # PROJECT.md non-canonical sections -> PROJECT-DEFINITION.vbrief.json.
-        if project_content and DEPRECATION_SENTINEL not in project_content:
-            project_sections = _parse_top_level_sections(project_content)
-            _project_canonical, project_legacy = _partition_sections(
-                project_sections, _PROJECT_KNOWN_MAPPINGS
-            )
-            if project_legacy:
-                narrative, sidecars, stats = _emit_legacy_artifacts(
-                    project_legacy,
-                    "PROJECT.md",
-                    project_root,
-                    slugify_fn=_slugify_shared,
-                    event_emitter=_legacy_event_emitter,
-                )
-                if narrative and proj_def_path.exists():
-                    narrative, stripped_ids = _strip_traces_from_narrative(
-                        narrative
-                    )
-                    if stripped_ids:
-                        traces_stripped_audit.append({
-                            "source": "PROJECT.md",
-                            "task_ids": stripped_ids,
-                        })
-                    _attach_legacy_narrative(proj_def_path, narrative)
-                    for sidecar in sidecars:
-                        try:
-                            rel = sidecar.relative_to(project_root).as_posix()
-                        except ValueError:
-                            rel = str(sidecar)
-                        if rel not in created_files:
-                            created_files.append(rel)
-                    captures[
-                        "PROJECT-DEFINITION.vbrief.json -> LegacyArtifacts"
-                    ].extend(stats)
-                    actions.append(
-                        "LEGACY PROJECT-DEFINITION.vbrief.json LegacyArtifacts: "
-                        f"{len(stats)} section(s)"
-                    )
-
-        # PRD.md section-name diff (OQ3-b, #505 Section 5). Hand-edited
-        # sections whose normalised title is NOT a canonical spec narrative
-        # key on the post-migration spec vBRIEF get captured with the
-        # warning prefix.
-        if prd_path.exists():
-            prd_content = prd_path.read_text(encoding="utf-8")
-            canonical_present = _canonical_spec_keys_in(spec_vbrief_path)
-            prd_legacy = _detect_prd_legacy(
-                prd_content, canonical_present, source_name="PRD.md"
-            )
-            if prd_legacy:
-                # Greptile #706 P1: pass ``flagged=True`` so the
-                # ``legacy:detected`` event payload carries
-                # ``flagged: true`` BEFORE emission, matching the
-                # ``events/registry.json`` (``category: "behavioral"``)
-                # contract for PRD.md hand-edit captures (post-#706
-                # unification per #709 / #710). The legacy stat-dict
-                # patch loop below is preserved as a defensive belt-
-                # and-suspenders for any downstream consumer that
-                # still inspects the returned stats list directly.
-                narrative, sidecars, stats = _emit_legacy_artifacts(
-                    prd_legacy,
-                    "PRD.md",
-                    project_root,
-                    slugify_fn=_slugify_shared,
-                    warning_prefix=_PRD_HAND_EDIT_WARNING,
-                    event_emitter=_legacy_event_emitter,
-                    flagged=True,
-                )
-                for stat in stats:
-                    stat["flagged"] = True
-                if narrative and spec_vbrief_path.exists():
-                    narrative, stripped_ids = _strip_traces_from_narrative(
-                        narrative
-                    )
-                    if stripped_ids:
-                        traces_stripped_audit.append({
-                            "source": "PRD.md",
-                            "task_ids": stripped_ids,
-                        })
-                    _attach_legacy_narrative(spec_vbrief_path, narrative)
-                    for sidecar in sidecars:
-                        try:
-                            rel = sidecar.relative_to(project_root).as_posix()
-                        except ValueError:
-                            rel = str(sidecar)
-                        if rel not in created_files:
-                            created_files.append(rel)
-                    captures[
-                        "PRD.md content (flagged: hand-edited)"
-                    ].extend(stats)
-                    actions.append(
-                        "LEGACY PRD.md hand-edit captures: "
-                        f"{len(stats)} section(s)"
-                    )
-
-        # Emit vbrief/migration/LEGACY-REPORT.md + stdout summary.
-        sources_read = [p for p in (
-            "SPECIFICATION.md" if spec_md_content else None,
-            "PROJECT.md" if project_content else None,
-            "ROADMAP.md" if total_items else None,
-            "PRD.md" if prd_path.exists() else None,
-        ) if p]
-        report_path = _emit_legacy_report(
-            project_root,
-            captures,
-            migrator_version=MIGRATOR_VERSION,
-            sources=sources_read,
-        )
-        if report_path is not None:
-            try:
-                rel_report = report_path.relative_to(project_root).as_posix()
-            except ValueError:
-                rel_report = str(report_path)
-            if rel_report not in created_files:
-                created_files.append(rel_report)
-            total_captured = sum(len(v) for v in captures.values())
-            actions.append(
-                f"CREATE {rel_report} ({total_captured} section(s) captured)"
-            )
-            for line in _summarize_captures(captures):
-                actions.append(line)
-    elif spec_legacy_sections or project_content:
-        actions.append("DRYRUN LEGACY capture (skipped under --dry-run)")
-    # --- end legacy-artifacts ---
-
-    # --- reconciliation-report (Agent B, #496) ---
-    # Emit vbrief/migration/RECONCILIATION.md when SPEC and ROADMAP
-    # disagreed or any override triggered. Runs AFTER scope vBRIEFs are
-    # written but BEFORE Agent C's safety manifest so the report is
-    # recorded in created_files and removed on --rollback.
-    if not dry_run and reconciliation_report.has_disagreement():
-        report_path = _write_reconciliation_report(
-            reconciliation_report, vbrief_dir
-        )
-        if report_path is not None:
-            try:
-                rel = report_path.relative_to(project_root).as_posix()
-            except ValueError:
-                rel = str(report_path)
-            created_files.append(rel)
-            actions.append(f"CREATE {rel}")
-    elif dry_run and reconciliation_report.has_disagreement():
-        actions.append(
-            "DRYRUN CREATE vbrief/migration/RECONCILIATION.md"
-        )
-    # --- end reconciliation-report ---
-
-    # #529: Append the Traces-stripped audit section to RECONCILIATION.md.
-    # Runs AFTER the reconciliation report so both live in the same file --
-    # the report writer overwrites, so appending last keeps both surfaces.
-    # In --dry-run the call short-circuits to a log line.
-    traces_report_path, traces_action = _write_traces_stripped_note(
-        project_root, traces_stripped_audit, dry_run=dry_run
-    )
-    if traces_action:
-        actions.append(traces_action)
-    if traces_report_path is not None:
-        try:
-            rel = traces_report_path.relative_to(project_root).as_posix()
-        except ValueError:
-            rel = str(traces_report_path)
-        if rel not in created_files:
-            created_files.append(rel)
-
-    # --- prettier remediation breadcrumb (#670) ---
-    # Emit the prettier remediation note on stdout (via the action log) on
-    # every successful migration, and append it to vbrief/migration/
-    # LEGACY-REPORT.md when that report was generated (legacy sections were
-    # captured -- the typical pre-v0.20 migration; the report is already in
-    # created_files for --rollback). The note turns a surprise baseline
-    # ``task check`` prettier failure into a known one-command fix. Skipped
-    # under --dry-run (no files are written).
-    if not dry_run:
-        report_path = (
-            project_root / "vbrief" / "migration" / "LEGACY-REPORT.md"
-        )
-        if report_path.exists():
-            _append_prettier_breadcrumb(report_path)
-        for line in _prettier_breadcrumb_body():
-            actions.append(line)
-    # --- end prettier remediation breadcrumb ---
-
-    # #527 / #528: record any migrator-managed subdirs we created (legacy,
-    # migration) in the safety manifest's created_dirs so --rollback RMDIRs
-    # them consistently with the lifecycle folders. Uses the pre-existed
-    # snapshot captured at the top of this function so the decision is
-    # driven by manifest state rather than filesystem scan.
-    #
-    # Pre-create vbrief/migration/ here because the safety manifest is about
-    # to be written into it below (via write_safety_manifest) -- by mkdir'ing
-    # now we surface its creation to the tracking helper in the same call
-    # site as all other managed-subdir tracking.
-    migration_dir = vbrief_dir / "migration"
-    if not dry_run and not migration_dir.is_dir():
-        migration_dir.mkdir(parents=True, exist_ok=True)
-    for subdir_name in _MANAGED_SUBDIRS:
-        _track_managed_subdir(
-            project_root,
-            subdir_name,
-            managed_subdir_pre_existed,
-            created_dirs,
-        )
-
-    # --- safety (Agent C, #497) ---
-    # Persist a safety manifest for --rollback.  The manifest lives under
-    # vbrief/migration/ (#506 shared path convention) and records:
-    #   * every .premigrate.* backup we wrote (for restore);
-    #   * every file/directory this run created (for removal on rollback);
-    #   * post-migration stub hashes (so rollback can detect later edits).
-    #
-    # Re-run protection (Greptile #509 P1 cascade-3): when the migrator is
-    # re-invoked on an already-migrated project, plan_backups correctly
-    # returns zero pairs (sources are all stubs), so ``backup_records`` is
-    # empty.  Writing a fresh manifest with ``backups=[]`` would overwrite
-    # the first run's record, leaving ``--rollback`` unable to restore any
-    # originals.  Load any prior manifest and carry its backup records
-    # forward so subsequent rollback still works end-to-end.  Stub hashes
-    # and created_files are merged the same way so rollback still knows
-    # which artefacts to remove.
-    prior = load_safety_manifest(project_root) if not dry_run else None
-    merged_backups = list(backup_records)
-    merged_stub_hashes = dict(stub_hashes)
-    merged_created_files = list(created_files)
-    merged_created_dirs = list(created_dirs)
-    merged_file_modifications = list(file_modifications)
-    if prior is not None:
-        # Re-run on already-migrated project: union the prior manifest's
-        # records with this run's so nothing recorded before is dropped.
-        # Current-run records take precedence for overlapping sources
-        # (fresh digest wins), and prior-run records for sources we did
-        # not touch this time (e.g. SPECIFICATION.md / PROJECT.md are
-        # stubs on the second pass and get skipped by plan_backups).
-        current_sources = {b.source for b in backup_records}
-        for prior_record in prior.backups:
-            if prior_record.source not in current_sources:
-                merged_backups.append(prior_record)
-        for rel, digest in prior.post_migration_stub_hashes.items():
-            merged_stub_hashes.setdefault(rel, digest)
-        for rel in prior.created_files:
-            if rel not in merged_created_files:
-                merged_created_files.append(rel)
-        for rel in prior.created_dirs:
-            if rel not in merged_created_dirs:
-                merged_created_dirs.append(rel)
-        # #567: carry prior file_modifications forward when the current
-        # run did not re-record the same path (e.g. a re-run on an
-        # already-migrated project whose .gitignore already has the
-        # patterns -- the helper returns ``None`` as a no-op). Without
-        # this, rollback would lose the original modification record
-        # and be unable to reverse the first run's append.
-        current_modification_paths = {m.path for m in file_modifications}
-        for prior_mod in prior.file_modifications:
-            if prior_mod.path not in current_modification_paths:
-                merged_file_modifications.append(prior_mod)
-    manifest = SafetyManifest(
-        version="1",
-        migration_timestamp=now_utc_iso(),
-        backups=merged_backups,
-        created_files=merged_created_files,
-        created_dirs=merged_created_dirs,
-        post_migration_stub_hashes=merged_stub_hashes,
-        file_modifications=merged_file_modifications,
-    )
-    manifest_action = write_safety_manifest(
-        project_root, manifest, dry_run=dry_run
-    )
-    actions.append(manifest_action)
-    # --- end safety ---
-
-    # ---- Report ----
-    for w in warnings:
-        actions.append(w)
-
-    # --- strict gate (Agent B, #496) ---
-    # ``task migrate:vbrief -- --strict`` must exit non-zero when any
-    # SPEC/ROADMAP disagreement was recorded so CI can gate cutover until
-    # the operator has reviewed RECONCILIATION.md. Runs BEFORE Agent D's
-    # validation gate because a reconciliation conflict is a workflow
-    # decision surface -- the scope vBRIEFs themselves are still
-    # schema-valid, so the operator would otherwise see a success exit
-    # from the validator. Agent C's .premigrate.* backups remain in place
-    # for ``task migrate:vbrief -- --rollback`` recovery either way.
-    if strict and reconciliation_report.has_disagreement() and not dry_run:
-        actions.append(
-            "STRICT: reconciliation conflicts detected; see "
-            "vbrief/migration/RECONCILIATION.md"
-        )
-        return False, actions
-    # --- end strict gate ---
-
-    # --- validation (Agent D, #498) ---
-    # Hard-block on schema-invalid migration output per #506 D8. Runs AFTER
-    # Agent C's safety path (#497) so .premigrate.* backups and the safety
-    # manifest remain in place on failure for ``task migrate:vbrief --
-    # --rollback`` recovery. Skipped under --dry-run so operators can preview
-    # the plan without invoking the validator on a non-existent tree. Full
-    # implementation lives in scripts/_vbrief_validation.py::
-    # finalize_migration to keep migrate_vbrief.py under the 1000-line cap.
-    if dry_run:
-        return True, actions
-    return finalize_migration(project_root, vbrief_dir, actions)
-
-
-def _edge_nodes(edge: dict) -> tuple[str, str]:
-    """Compatibility shim for the shared Speckit translator."""
-    return _edge_nodes_shared(edge)
-
-
-def _dependencies_for_item(item_id: str, edges: list[dict]) -> list[str]:
-    """Compatibility shim for the shared Speckit translator."""
-    return _dependencies_for_item_shared(item_id, edges)
-
-
-def _speckit_ip_slug(title: str, item_id: str) -> str:
-    """Compatibility shim for the shared Speckit translator."""
-    return _speckit_ip_slug_shared(title, item_id)
-
-
-def _speckit_ip_index(item: dict, fallback_index: int) -> int:
-    """Compatibility shim for the shared Speckit translator."""
-    return _speckit_ip_index_shared(item, fallback_index)
-
-
-def _create_speckit_scope_vbrief(
-    item: dict,
-    *,
-    ip_index: int,
-    dependencies: list[str],
-    spec_ref: str,
-) -> dict:
-    """Compatibility shim for the shared Speckit translator."""
-    return _create_speckit_scope_vbrief_shared(
-        item,
-        ip_index=ip_index,
-        dependencies=dependencies,
-        spec_ref=spec_ref,
-    )
-
-
-def migrate_speckit_plan(
-    plan_path: Path,
-    *,
-    pending_dir: Path | None = None,
-    date: str | None = None,
-    spec_ref: str = "specification.vbrief.json",
-) -> tuple[bool, list[str]]:
-    """Compatibility shim for the shared Speckit translator."""
-    return _migrate_speckit_plan_shared(
-        plan_path,
-        pending_dir=pending_dir,
-        date=date,
-        spec_ref=spec_ref,
-        today=_TODAY,
-    )
-
-
-# Pattern shared with ``reconcile_issues.ISSUE_URL_PATTERN``: matches the
-# canonical v0.6 ``https://github.com/{owner}/{repo}/issues/{N}`` URI that
-# the migrator now emits on scope vBRIEF references (#613). Kept at module
-# scope so the regex compiles once per interpreter.
-_CANONICAL_ISSUE_URI_RE = re.compile(
-    r"https://github\.com/[^/]+/[^/]+/issues/(?P<number>\d+)"
-)
-
-# Filename-stem fallback pattern. When ``repo_url`` is unresolvable at
-# migration time (no git remote, no ``spec_vbrief.repository`` hint), the
-# migrator's scope vBRIEFs carry an empty ``plan.references`` -- the
-# canonical shape requires ``uri`` which we can't synthesize without
-# ``{owner}/{repo}``. Cross-day re-migrations must still deduplicate
-# those files, so we pattern-match the leading issue number out of the
-# filename stem (``YYYY-MM-DD-<N>-<slug>.vbrief.json`` per
-# ``conventions/vbrief-filenames.md``). Addresses Greptile P1 finding:
-# without this fallback, ``_find_existing_scope_vbrief`` returns None
-# for every reference-less file and duplicate scope vBRIEFs accumulate
-# on each re-run.
-_FILENAME_ISSUE_RE = re.compile(
-    r"^\d{4}-\d{2}-\d{2}-(?P<number>\d+)-"
-)
-
-
-def _reference_matches_issue(ref: dict, issue_number: str) -> bool:
-    """Return True if ``ref`` points at GitHub issue ``#{issue_number}``.
-
-    Accepts both the canonical v0.6 shape ``{uri, type: x-vbrief/github-
-    issue, title}`` and the legacy shape ``{type: github-issue, id}`` so
-    the migrator's duplicate-suppression path stays idempotent during the
-    transition (#613). ``issue_number`` is the bare digit string.
-    """
-    if not isinstance(ref, dict) or not issue_number:
-        return False
-    legacy_id = ref.get("id")
-    if isinstance(legacy_id, str) and legacy_id == f"#{issue_number}":
-        return True
-    uri = ref.get("uri")
-    if isinstance(uri, str) and uri:
-        match = _CANONICAL_ISSUE_URI_RE.search(uri)
-        if match and match.group("number") == issue_number:
-            return True
-    return False
-
-
-def _find_existing_scope_vbrief(vbrief_dir: Path, issue_number: str) -> Path | None:
-    """Check if any existing vBRIEF in lifecycle folders matches the issue.
-
-    Three-tier match (most-reliable first):
-
-    1. Canonical v0.6 reference shape -- ``plan.references[*].uri``
-       contains the canonical ``.../issues/{N}`` URI (#613 primary path).
-    2. Legacy reference shape -- ``plan.references[*].id == "#{N}"`` (kept
-       for mixed-shape worktrees during the transition).
-    3. Filename-stem fallback -- ``YYYY-MM-DD-{N}-`` prefix. Covers the
-       edge case where ``repo_url`` was unresolvable at migration time
-       (no git remote, no ``spec_vbrief.repository`` hint); those files
-       ship with empty ``plan.references`` because the canonical
-       ``VBriefReference`` schema requires ``uri`` which we cannot
-       synthesize. Without this fallback, cross-day re-migrations on
-       such projects silently produce duplicate scope vBRIEFs because
-       tier 1 and tier 2 both miss.
-
-    Returns the first matching path found, or ``None``.
-    """
-    # Pass 1: reference-based match (canonical + legacy, same scan).
-    for folder_name in LIFECYCLE_FOLDERS:
-        folder = vbrief_dir / folder_name
-        if not folder.exists():
-            continue
-        for fpath in folder.glob("*.vbrief.json"):
-            try:
-                data = json.loads(fpath.read_text(encoding="utf-8"))
-                refs = data.get("plan", {}).get("references", [])
-                if not isinstance(refs, list):
-                    continue
-                for ref in refs:
-                    if _reference_matches_issue(ref, issue_number):
-                        return fpath
-            except (json.JSONDecodeError, AttributeError):
-                continue
-
-    # Pass 2: filename-stem fallback for reference-less files.
-    if not issue_number:
-        return None
-    for folder_name in LIFECYCLE_FOLDERS:
-        folder = vbrief_dir / folder_name
-        if not folder.exists():
-            continue
-        for fpath in folder.glob("*.vbrief.json"):
-            stem = fpath.name.removesuffix(".vbrief.json")
-            match = _FILENAME_ISSUE_RE.match(stem)
-            if match and match.group("number") == issue_number:
-                return fpath
-    return None
-
-
-def _fold_custom_content(proj_def_path: Path, key: str, content: str) -> bool:
-    """Fold custom content into PROJECT-DEFINITION.vbrief.json narratives.
-
-    Returns True if content was successfully preserved, False otherwise.
-
-    Legacy fallback preserved for backward compatibility; the new
-    ``LegacyArtifacts`` mechanism (#505) captures non-canonical ## sections
-    with full provenance headers and is the preferred preservation surface
-    going forward.
-    """
-    if not proj_def_path.exists():
-        return False
-    try:
-        data = json.loads(proj_def_path.read_text(encoding="utf-8"))
-        data.setdefault("plan", {}).setdefault("narratives", {})[key] = content
-        proj_def_path.write_text(
-            json.dumps(data, indent=2, ensure_ascii=False) + "\n",
-            encoding="utf-8",
-        )
-        return True
-    except (json.JSONDecodeError, AttributeError):
-        return False
-
-
-# --- legacy-artifacts (Agent A, #505) ---
-def _attach_legacy_narrative(vbrief_path: Path, narrative: str) -> None:
-    """Append a ``LegacyArtifacts`` narrative onto an existing vBRIEF file.
-
-    If the file already carries a ``LegacyArtifacts`` narrative, the new
-    content is concatenated (blank-line separator) so multiple capture
-    passes on one run do not silently overwrite one another.
-    """
-    if not vbrief_path.exists():
-        return
-    try:
-        data = json.loads(vbrief_path.read_text(encoding="utf-8"))
-    except (json.JSONDecodeError, OSError):
-        return
-    plan = data.setdefault("plan", {})
-    narratives = plan.setdefault("narratives", {})
-    existing = narratives.get("LegacyArtifacts", "")
-    if isinstance(existing, str) and existing.strip():
-        narratives["LegacyArtifacts"] = (
-            existing.rstrip() + "\n\n" + narrative.strip() + "\n"
-        )
-    else:
-        narratives["LegacyArtifacts"] = narrative
-    vbrief_path.write_text(
-        json.dumps(data, indent=2, ensure_ascii=False) + "\n",
-        encoding="utf-8",
-    )
-
-
-def _canonical_spec_keys_in(spec_vbrief_path: Path) -> set[str]:
-    """Return the canonical spec narrative keys present on disk.
-
-    Used by the PRD.md section-name diff (OQ3-b, #505 Section 5) to decide
-    whether a PRD ## section is expected render output (skip capture) or a
-    hand-edited section that should be captured with the warning prefix.
-    """
-    if not spec_vbrief_path.exists():
-        return set()
-    try:
-        data = json.loads(spec_vbrief_path.read_text(encoding="utf-8"))
-    except (json.JSONDecodeError, OSError):
-        return set()
-    narratives = data.get("plan", {}).get("narratives", {}) or {}
-    if not isinstance(narratives, dict):
-        return set()
-    return {
-        k for k, v in narratives.items()
-        if k in _CANONICAL_SPEC_KEYS and isinstance(v, str) and v.strip()
-    }
-# --- end legacy-artifacts ---
-
-
-def main() -> int:
-    """Entry point for the migration script."""
-    import argparse
-
-    args = list(sys.argv[1:])
-
-    # --speckit-plan <path> subcommand: convert a speckit-shaped plan.vbrief.json
-    # into per-IP scope vBRIEFs in ``<plan dir>/pending/`` (#436, #458).
-    # Handled ahead of the main argparse so we keep its positional-path calling
-    # convention stable for the test harness that already exercises it.
-    if args and args[0] == "--speckit-plan":
-        if len(args) < 2:
-            print(
-                "ERROR: --speckit-plan requires a path argument",
-                file=sys.stderr,
-            )
-            return 2
-        plan_path = Path(args[1]).resolve()
-        print(f"Migrating speckit plan at: {plan_path}")
-        print("=" * 60)
-        ok, messages = migrate_speckit_plan(plan_path)
-        for msg in messages:
-            print(f"  {msg}")
-        print("=" * 60)
-        if ok:
-            print("speckit plan migration completed successfully.")
-            return 0
-        print("speckit plan migration FAILED.", file=sys.stderr)
-        return 1
-
-    # --- safety (Agent C, #497) ---
-    # Primary CLI for `task migrate:vbrief` -- positional project_root +
-    # --dry-run / --force / --rollback flags per #506 D7.
-    parser = argparse.ArgumentParser(
-        prog="migrate_vbrief.py",
-        description=(
-            "Migrate a Deft project to the vBRIEF-centric document model. "
-            "Destructive by default; use --dry-run to preview or --rollback "
-            "to undo a previous migration."
-        ),
-    )
-    parser.add_argument(
-        "project_root",
-        nargs="?",
-        default=None,
-        help="Path to the project root (default: current working directory).",
-    )
-    parser.add_argument(
-        "--dry-run",
-        action="store_true",
-        help=(
-            "Print the migration plan without writing any files. Exits 0 on "
-            "success with every planned action prefixed DRYRUN."
-        ),
-    )
-    parser.add_argument(
-        "--force",
-        action="store_true",
-        help=(
-            "Bypass the dirty-tree guard (and the rollback confirmation / "
-            "edited-stub guard). Not recommended."
-        ),
-    )
-    parser.add_argument(
-        "--rollback",
-        action="store_true",
-        help=(
-            "Restore from .premigrate.* backups and remove the scope "
-            "vBRIEFs and migration artefacts a prior run created. Reads "
-            "vbrief/migration/safety-manifest.json written by the migrator."
-        ),
-    )
-    # --- strict flag (Agent B, #496) ---
-    parser.add_argument(
-        "--strict",
-        action="store_true",
-        help=(
-            "Fail the run non-zero if SPEC and ROADMAP disagreed on any "
-            "dimension or any override from vbrief/migration-overrides.yaml "
-            "triggered. Scope vBRIEFs and vbrief/migration/RECONCILIATION.md "
-            "are still written so the operator can inspect and re-run."
-        ),
-    )
-    # --- end strict flag ---
-    ns = parser.parse_args(args)
-
-    project_root = (
-        Path(ns.project_root).resolve() if ns.project_root else Path.cwd()
-    )
-
-    if not project_root.is_dir():
-        print(f"ERROR: {project_root} is not a directory", file=sys.stderr)
-        return 1
-
-    if ns.rollback:
-        print(f"Rolling back migration at: {project_root}")
-        print("=" * 60)
-        ok, messages = safety_rollback(project_root, force=ns.force)
-        for msg in messages:
-            print(f"  {msg}")
-        print("=" * 60)
-        if ok:
-            print("Rollback completed successfully.")
-            return 0
-        print("Rollback FAILED.", file=sys.stderr)
-        return 1
-
-    if ns.dry_run:
-        print(f"Dry-run migration at: {project_root}")
-    else:
-        print(f"Migrating project at: {project_root}")
-    if ns.strict:
-        print("Strict mode enabled: reconciliation conflicts will fail the run.")
-    print("=" * 60)
-
-    ok, messages = migrate(
-        project_root,
-        dry_run=ns.dry_run,
-        force=ns.force,
-        strict=ns.strict,
-    )
-
-    for msg in messages:
-        print(f"  {msg}")
-
-    print("=" * 60)
-    if ok:
-        if ns.dry_run:
-            print("Dry-run completed successfully. No files were modified.")
-        else:
-            print("Migration completed successfully.")
-        return 0
-    # --- end safety ---
-    print("Migration FAILED.", file=sys.stderr)
-    return 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())