@deftai/directive-content 0.59.0 → 0.61.0

package/scripts/doctor.py

@@ -1,2552 +0,0 @@
-#!/usr/bin/env python3
-"""scripts/doctor.py -- canonical doctor implementation (Epic-1 #1335).
-
-This module now owns the core doctor logic previously in run::cmd_doctor
-and its helpers (parse flags, throttle via _doctor_state, install-integrity
-folding, AGENTS.md freshness, Taskfile include diagnostics, structure checks,
---fix repair, --json / --session / --quiet / --full / --project-root modes).
-
-Thin shims remain in:
-  * run::cmd_doctor  (delegates here after sys.path insert)
-  * Taskfile.yml "doctor:" target (already a shim to `run doctor`)
-
-All new/moved code follows project testing guidelines; tests updated
-in tests/cli/test_cmd_doctor.py and siblings.
-
-See also: scripts/_doctor_state.py (throttle). Install-integrity logic
-previously in framework_doctor.py (retired #1336) now lives here.
-
-Story: #1335 / #1336 (paired in agent1 worktree).
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-import re
-import shutil
-import subprocess
-import sys
-from dataclasses import dataclass, field
-from datetime import UTC, datetime
-from pathlib import Path
-
-# --- Duplicated minimal CLI / path helpers (avoid importing heavy run) ---
-# These are small, stable, and let doctor.py stay self-contained.
-# Rich is optional; fall back to plain prints. Mirrors run's top-level setup.
-
-HAS_RICH = False
-
-console = None
-Panel = None
-Markdown = None
-try:
-    from rich.console import Console
-    from rich.markdown import Markdown as _Markdown
-    from rich.panel import Panel as _Panel
-    console = Console()
-    Panel = _Panel
-    Markdown = _Markdown
-    HAS_RICH = True
-except Exception:  # noqa: BLE001 -- rich optional
-    HAS_RICH = False
-
-def print_header(text: str):
-    if HAS_RICH and console and Panel:
-        console.print(Panel(f"[bold cyan]{text}[/bold cyan]", border_style="cyan"))
-    else:
-        print(f"\n{'=' * 60}")
-        print(f"  {text}")
-        print('=' * 60)
-
-def print_section(text: str):
-    if HAS_RICH and console and Markdown:
-        console.print(Markdown(f"## {text}"))
-    else:
-        print(f"\n{'-' * 60}")
-        print(f"  {text}")
-        print('-' * 60)
-
-def print_info(msg: str):
-    if HAS_RICH and console:
-        console.print(f"[blue]ℹ[/blue] {msg}")
-    else:
-        print(f"ℹ {msg}")
-
-def print_success(msg: str):
-    if HAS_RICH and console:
-        console.print(f"[green]✓[/green] {msg}")
-    else:
-        print(f"✓ {msg}")
-
-def print_warn(msg: str):
-    if HAS_RICH and console:
-        console.print(f"[yellow]⚠[/yellow] {msg}")
-    else:
-        print(f"⚠ {msg}")
-
-def print_error(msg: str):
-    if HAS_RICH and console:
-        console.print(f"[red]✗[/red] {msg}")
-    else:
-        print(f"✗ {msg}")
-
-# Legacy aliases for the extracted code that calls info/success etc.
-info = print_info
-success = print_success
-warn = print_warn
-error = print_error
-
-def get_script_dir() -> Path:
-    """Get the directory where this script is located (works for import and direct)."""
-    return Path(__file__).parent.absolute()
-
-def resolve_path(path_str: str) -> Path:
-    """Resolve a user-supplied path string to an absolute Path.
-    Expands ~ and resolves relative paths against cwd.
-    """
-    if not path_str:
-        return Path.cwd()
-    p = Path(path_str).expanduser()
-    if not p.is_absolute():
-        p = (Path.cwd() / p).resolve()
-    return p
-
-def _resolve_version() -> str:
-    """Best-effort version (duplicated for doctor self-containment)."""
-    try:
-        for cand in [
-            Path(__file__).parent.parent / 'VERSION',
-            Path(__file__).parent / 'VERSION',
-            Path.cwd() / '.deft-version',
-        ]:
-            if cand.exists():
-                return cand.read_text(encoding='utf-8').strip()
-    except Exception:
-        pass
-    return 'dev'
-
-VERSION = _resolve_version()
-
-# UV url constant (the _check_uv_available helper remains in run for other callers)
-UV_INSTALL_URL = "https://docs.astral.sh/uv/"
-
-# Post-freeze npm canonical path (#1997 / #2003 / #1912).
-CANONICAL_UPGRADE_COMMAND = "npm i -g @deftai/directive@latest"
-NPM_PACKAGE_NAME = "@deftai/directive"
-UPGRADING_DOC_URL = "https://github.com/deftai/directive/blob/master/content/UPGRADING.md"
-GO_BRIDGE_RELEASES_URL = "https://github.com/deftai/directive/releases"
-NPM_MANAGED_SENTINEL_KEY = "managed_by"
-NPM_MANAGED_SENTINEL_VALUE = "npm"
-
-# --- Install-integrity checks (ported from retired framework_doctor.py #1336) ---
-# Symbols (EXIT_*, run_checks, main, CheckResult, DoctorResult + 4 checks + impl)
-# are inserted below in small batches. Once complete, _run_install_integrity_checks
-# will delegate locally (no more self-import hack or double-scripts path).
-# This satisfies the Greptile P0 (missing symbols for tests + runtime NameError/AttributeError).
-# --- END PORTED CHECKS HEADER ---
-
-# --- Ported from framework_doctor.py: constants, regexes, dataclasses, low-level helpers ---
-EXIT_CLEAN = 0
-EXIT_DRIFT = 1
-EXIT_CONFIG_ERROR = 2
-
-
-# Marker contract -- mirrors run::_AGENTS_MANAGED_OPEN_RE. Kept inline so
-# this script stays pure-stdlib + cross-platform without importing run
-# (which has heavy import-time side effects).
-_AGENTS_MANAGED_OPEN_RE = re.compile(r"<!--\s*deft:managed-section\s+v(2|3)(?:\s+([^>]*?))?\s*-->")
-_AGENTS_MANAGED_CLOSE = "<!-- /deft:managed-section -->"
-
-# The canonical install-root declaration AGENTS.md carries one of:
-#   "Deft is installed in <root>/."
-#   "Full guidelines: <root>/main.md"
-# We parse both. The first match wins.
-_INSTALLED_IN_RE = re.compile(r"Deft is installed in\s+(\S+?)/?\.")
-_FULL_GUIDELINES_RE = re.compile(r"Full guidelines:\s+(\S+)/main\.md")
-
-# Pattern for referenced skill paths. Matches both ``deft/skills/<name>/SKILL.md``
-# (legacy) and ``.deft/core/skills/<name>/SKILL.md`` (canonical).
-_SKILL_PATH_RE = re.compile(r"(?P<root>[\w./-]+?)/skills/(?P<name>[a-z][\w-]*)/SKILL\.md")
-
-# Deprecation-redirect sentinels embedded in stub SKILL.md files (#411).
-# A skill path that resolves but is a redirect stub is treated as still
-# a fail -- the operator needs to act, not be told everything is fine.
-#
-# Important: current real skills legitimately mention the markdown
-# ``deft:deprecated-redirect`` sentinel when describing migrated
-# SPECIFICATION.md / PROJECT.md state. Redirect detection therefore keys on
-# the stub header shape, not substring presence anywhere in a skill body.
-_DEPRECATED_REDIRECT_SENTINEL = "<!-- deft:deprecated-redirect -->"
-_DEPRECATED_SKILL_REDIRECT_SENTINEL = "<!-- deft:deprecated-skill-redirect -->"
-_REDIRECT_STUB_HEADER_LINES = 8
-
-
-@dataclass
-class CheckResult:
-    """Outcome of a single doctor check.
-
-    ``status`` is one of:
-      * ``"pass"`` -- check succeeded; no action required.
-      * ``"fail"`` -- check failed; drift detected and operator action
-        is required.
-      * ``"skip"`` -- check was skipped because its precondition was
-        not met (e.g. manifest-agreement skips when neither file exists).
-      * ``"error"`` -- check could not run because of a config-level
-        problem (e.g. project root does not exist). Propagates to
-        exit code 2.
-    """
-
-    name: str
-    status: str
-    detail: str
-    data: dict = field(default_factory=dict)
-
-
-@dataclass
-class DoctorResult:
-    """Aggregated doctor outcome consumed by the CLI + gate hook."""
-
-    project_root: str
-    install_root: str | None
-    exit_code: int
-    checks: list[CheckResult]
-    errors: list[str] = field(default_factory=list)
-
-    def to_dict(self) -> dict:
-        return {
-            "project_root": self.project_root,
-            "install_root": self.install_root,
-            "exit_code": self.exit_code,
-            "checks": [
-                {
-                    "name": c.name,
-                    "status": c.status,
-                    "detail": c.detail,
-                    "data": c.data,
-                }
-                for c in self.checks
-            ],
-            "errors": list(self.errors),
-        }
-
-
-# ---------------------------------------------------------------------------
-# Helpers (ported)
-# ---------------------------------------------------------------------------
-
-
-def _read_text_safe(path: Path) -> str | None:
-    """Best-effort UTF-8 read; returns None on OSError."""
-    if not path.is_file():
-        return None
-    try:
-        return path.read_text(encoding="utf-8", errors="replace")
-    except OSError:
-        return None
-
-
-def _parse_install_root_from_agents_md(text: str) -> str | None:
-    """Return the install root AGENTS.md claims (e.g. ``.deft/core``).
-
-    Tries the ``Deft is installed in <root>/.`` form first, then falls back
-    to ``Full guidelines: <root>/main.md``. Returns None when neither matches.
-    Pure -- no I/O.
-    """
-    match = _INSTALLED_IN_RE.search(text)
-    if match:
-        return match.group(1).strip()
-    match = _FULL_GUIDELINES_RE.search(text)
-    if match:
-        return match.group(1).strip()
-    return None
-
-
-def _extract_managed_section(text: str) -> str | None:
-    """Return the bracketed managed-section block, or None when markers are absent."""
-    normalised = text.replace("\r\n", "\n")
-    open_match = _AGENTS_MANAGED_OPEN_RE.search(normalised)
-    if open_match is None:
-        return None
-    open_idx = open_match.start()
-    close_idx = normalised.find(_AGENTS_MANAGED_CLOSE, open_match.end())
-    if close_idx < 0:
-        return None
-    end = close_idx + len(_AGENTS_MANAGED_CLOSE)
-    return normalised[open_idx:end]
-
-
-_MANIFEST_LINE_RE = re.compile(r"^\s*(?P<key>[A-Za-z_][A-Za-z0-9_]*)\s*:\s*(?P<value>.*?)\s*$")
-
-
-def _parse_manifest(text: str) -> dict:
-    """Minimal YAML-ish ``key: value`` parser (#1046 PR-B AC-4).
-
-    Mirrors ``run::_parse_install_manifest``. Pure -- no I/O.
-    """
-    parsed: dict = {}
-    for line in text.splitlines():
-        stripped = line.strip()
-        if not stripped or stripped.startswith("#"):
-            continue
-        match = _MANIFEST_LINE_RE.match(stripped)
-        if match is None:
-            continue
-        key = match.group("key").strip().lower()
-        value = match.group("value").strip().strip("'\"")
-        if key:
-            parsed[key] = value
-    return parsed
-
-
-def _manifest_tag_to_version(manifest: dict) -> str | None:
-    """Derive the bare ``.deft-version`` value from a manifest dict."""
-    for key in ("tag", "ref"):
-        raw = manifest.get(key)
-        if not isinstance(raw, str):
-            continue
-        candidate = raw.strip().lstrip("v")
-        if candidate:
-            return candidate
-    return None
-
-
-def _manifest_candidate_paths(
-    project_root: Path, install_root: str | None
-) -> list[Path]:
-    """Return the canonical-first VERSION-manifest probe order (#1427).
-
-    The install provenance manifest is written to divergent paths by two
-    install rails: the Go installer writes the documented canonical
-    ``<install_root>/VERSION`` (``.deft/core/VERSION`` per #1062), while the
-    webinstaller writes ``.deft/VERSION`` (a 5-field manifest that omits the
-    #1062 ``install_root`` field). The ordering below is **canonical-first**
-    so an existing ``.deft/core/VERSION`` always wins over a stale
-    ``.deft/VERSION``:
-
-      1. ``<install_root>/VERSION`` -- the AGENTS.md / manifest-declared
-         install root, when known (skipped when ``install_root`` is None).
-      2. ``.deft/core/VERSION``    -- the v0.27+ canonical install (#1062).
-      3. ``.deft/VERSION``         -- the webinstaller-vendored location
-         (#1427); restores detection for that population.
-      4. ``deft/VERSION``          -- the pre-v0.27 legacy install.
-
-    Duplicates are removed while preserving order so an ``install_root`` of
-    ``.deft/core`` does not probe the same path twice. Pure -- builds paths
-    only; no filesystem access.
-    """
-    raw: list[Path] = []
-    if install_root:
-        raw.append(project_root / install_root / "VERSION")
-    raw.append(project_root / ".deft" / "core" / "VERSION")
-    raw.append(project_root / ".deft" / "VERSION")
-    raw.append(project_root / "deft" / "VERSION")
-    seen: set[str] = set()
-    ordered: list[Path] = []
-    for candidate in raw:
-        key = str(candidate)
-        if key not in seen:
-            seen.add(key)
-            ordered.append(candidate)
-    return ordered
-
-
-def _locate_manifest(project_root: Path, install_root: str | None) -> Path | None:
-    """Return the first existing VERSION manifest, canonical-first (#1427).
-
-    Walks :func:`_manifest_candidate_paths` in canonical-first order and
-    returns the first candidate that exists on disk, or ``None`` when no
-    manifest is present. Centralises the manifest-location contract so
-    ``_check_manifest_agreement``, ``_check_install_path_consistency``, and
-    the #1339 payload-staleness read path all agree on where a manifest may
-    live -- including the webinstaller's ``.deft/VERSION`` location.
-    """
-    for candidate in _manifest_candidate_paths(project_root, install_root):
-        if candidate.is_file():
-            return candidate
-    return None
-
-
-def _is_deprecation_redirect_stub(text: str) -> bool:
-    """Return True when a resolved skill file is an actual redirect stub."""
-    lines = text.replace("\r\n", "\n").lstrip().splitlines()
-    sentinels = {
-        _DEPRECATED_REDIRECT_SENTINEL,
-        _DEPRECATED_SKILL_REDIRECT_SENTINEL,
-    }
-    return any(line.strip() in sentinels for line in lines[:_REDIRECT_STUB_HEADER_LINES])
-
-
-# ---------------------------------------------------------------------------
-# Checks (ported from framework_doctor.py)
-# ---------------------------------------------------------------------------
-
-
-def _check_quick_start_resolves(project_root: Path, install_root: str | None) -> CheckResult:
-    """Check #1: QUICK-START.md resolves from the install root AGENTS.md claims."""
-    if install_root is None:
-        return CheckResult(
-            name="quick-start-resolves",
-            status="skip",
-            detail=(
-                "AGENTS.md does not declare an install root; cannot check "
-                "QUICK-START.md resolution."
-            ),
-        )
-    qs_path = project_root / install_root / "QUICK-START.md"
-    if qs_path.is_file():
-        return CheckResult(
-            name="quick-start-resolves",
-            status="pass",
-            detail=f"Found QUICK-START.md at {qs_path}.",
-            data={"path": str(qs_path), "install_root": install_root},
-        )
-    return CheckResult(
-        name="quick-start-resolves",
-        status="fail",
-        detail=(
-            f"QUICK-START.md not found at {qs_path}. AGENTS.md claims the "
-            f"install root is {install_root!r} but the file is missing. "
-            "Run `.deft/core/run agents:refresh` (Unix) / "
-            "`.deft\\core\\run agents:refresh` (Windows) to align AGENTS.md "
-            "with the on-disk install root, OR run `task upgrade` to "
-            "re-pull the framework if the on-disk install is missing. "
-            "See UPGRADING.md for the canonical drift-repair walkthrough."
-        ),
-        data={
-            "path": str(qs_path),
-            "install_root": install_root,
-            # Dual repair-path contract: ``suggested_fix`` is the AGENTS.md
-            # realignment (preferred when the on-disk framework is correct);
-            # ``suggested_fix_alt`` re-pulls the framework when the on-disk
-            # install is missing entirely. Mirrors the prose's two-option
-            # phrasing so programmatic consumers (sync skill / CI) see the
-            # same dual surface as humans (SLizard P1 on PR #1067).
-            "suggested_fix": ".deft/core/run agents:refresh",
-            "suggested_fix_alt": "task upgrade",
-        },
-    )
-
-
-def _check_skill_paths_resolve(project_root: Path, agents_md_text: str) -> CheckResult:
-    """Check #2: every <install>/skills/<name>/SKILL.md AGENTS.md references resolves."""
-    referenced = sorted({m.group(0) for m in _SKILL_PATH_RE.finditer(agents_md_text)})
-    if not referenced:
-        return CheckResult(
-            name="skill-paths-resolve",
-            status="skip",
-            detail="AGENTS.md references no skill paths to verify.",
-            data={"referenced": []},
-        )
-    missing: list[str] = []
-    redirect_stubs: list[str] = []
-    for rel in referenced:
-        candidate = project_root / rel
-        if not candidate.is_file():
-            missing.append(rel)
-            continue
-        text = _read_text_safe(candidate)
-        if text is not None and _is_deprecation_redirect_stub(text):
-            redirect_stubs.append(rel)
-    if not missing and not redirect_stubs:
-        return CheckResult(
-            name="skill-paths-resolve",
-            status="pass",
-            detail=f"All {len(referenced)} skill path(s) resolve.",
-            data={"referenced": referenced},
-        )
-    parts: list[str] = []
-    if missing:
-        parts.append(f"missing: {missing}")
-    if redirect_stubs:
-        parts.append(f"deprecation-redirect stubs: {redirect_stubs}")
-    return CheckResult(
-        name="skill-paths-resolve",
-        status="fail",
-        detail=(
-            f"{len(missing)} skill path(s) do not resolve; "
-            f"{len(redirect_stubs)} stub redirect(s). " + "; ".join(parts)
-            + ". Run `.deft/core/run agents:refresh` (Unix) / "
-            "`.deft\\core\\run agents:refresh` (Windows) to rewrite the "
-            "managed AGENTS.md block so skill paths match the on-disk "
-            "framework, OR run `task upgrade` if the on-disk skills are "
-            "missing entirely. See UPGRADING.md for the drift-repair walkthrough."
-        ),
-        data={
-            "referenced": referenced,
-            "missing": missing,
-            "redirect_stubs": redirect_stubs,
-            # Dual repair-path contract -- see ``_check_quick_start_resolves``
-            # for the rationale (SLizard P1 on PR #1067).
-            "suggested_fix": ".deft/core/run agents:refresh",
-            "suggested_fix_alt": "task upgrade",
-        },
-    )
-
-
-def _check_manifest_agreement(project_root: Path, install_root: str | None) -> CheckResult:
-    """Check #3: <install>/VERSION YAML manifest agrees with <root>/.deft-version.
-
-    The manifest is located via :func:`_locate_manifest` (#1427) so a
-    webinstaller-vendored install whose manifest is at ``.deft/VERSION`` is
-    found, canonical-first. ``install_root`` may be None (the webinstaller
-    population whose manifest omits the #1062 ``install_root`` field and
-    whose AGENTS.md therefore yields no install-root claim) -- the helper
-    still probes the canonical/legacy locations, so detection no longer
-    depends on the AGENTS.md install-root parse.
-
-    #1325: before the canonical-vs-bare reconciliation, detect when BOTH the
-    canonical ``.deft/core/VERSION`` and the legacy parent-level
-    ``.deft/VERSION`` exist AND disagree. Two install manifests that name
-    different versions is a stale source-of-truth hazard -- ``task upgrade``
-    migrates the legacy file (backing it up as ``.deft/VERSION.premigrate``).
-    """
-    core_manifest = project_root / ".deft" / "core" / "VERSION"
-    legacy_manifest = project_root / ".deft" / "VERSION"
-    core_dual_text = _read_text_safe(core_manifest)
-    legacy_dual_text = _read_text_safe(legacy_manifest)
-    if core_dual_text is not None and legacy_dual_text is not None:
-        core_ver = _manifest_tag_to_version(_parse_manifest(core_dual_text))
-        legacy_ver = _manifest_tag_to_version(_parse_manifest(legacy_dual_text))
-        if core_ver != legacy_ver:
-            return CheckResult(
-                name="manifest-agreement",
-                status="fail",
-                detail=(
-                    f"Two install manifests disagree: .deft/core/VERSION "
-                    f"(tag={core_ver!r}) vs legacy .deft/VERSION "
-                    f"(tag={legacy_ver!r}). The canonical manifest is "
-                    ".deft/core/VERSION -- run `task upgrade` to migrate the "
-                    "stale .deft/VERSION (backed up as .deft/VERSION.premigrate). "
-                    "See UPGRADING.md for the canonical drift-repair walkthrough."
-                ),
-                data={
-                    "dual_manifest_drift": True,
-                    "core_manifest_path": str(core_manifest),
-                    "legacy_manifest_path": str(legacy_manifest),
-                    "core_version": core_ver,
-                    "legacy_version": legacy_ver,
-                    "authoritative": "manifest",
-                    "suggested_fix": "task upgrade",
-                },
-            )
-    manifest_path = _locate_manifest(project_root, install_root)
-    # Canonical-first expected location for diagnostics when no manifest is
-    # found on disk (``_manifest_candidate_paths`` always returns >= 1 entry).
-    expected_manifest_path = (
-        manifest_path
-        if manifest_path is not None
-        else _manifest_candidate_paths(project_root, install_root)[0]
-    )
-    bare_candidates = [
-        project_root / "vbrief" / ".deft-version",
-        project_root / ".deft-version",
-    ]
-    bare_path: Path | None = next((p for p in bare_candidates if p.is_file()), None)
-    manifest_text = _read_text_safe(manifest_path) if manifest_path else None
-    bare_text = _read_text_safe(bare_path) if bare_path else None
-    if manifest_text is None and bare_text is None:
-        return CheckResult(
-            name="manifest-agreement",
-            status="skip",
-            detail=(
-                "Neither YAML manifest nor bare .deft-version exists; "
-                "nothing to reconcile (greenfield install)."
-            ),
-            data={
-                "manifest_path": str(manifest_path) if manifest_path else None,
-                "bare_path": str(bare_path) if bare_path else None,
-            },
-        )
-    if manifest_text is None:
-        return CheckResult(
-            name="manifest-agreement",
-            status="fail",
-            detail=(
-                f"Bare .deft-version exists at {bare_path} but YAML manifest "
-                f"is missing at {expected_manifest_path}. Run `task upgrade` to write "
-                "the canonical manifest (#1046 PR-B AC-4). See UPGRADING.md "
-                "for the v0.27.x -> v0.28 transition walkthrough."
-            ),
-            data={
-                "manifest_path": str(manifest_path) if manifest_path else None,
-                "expected_manifest_path": str(expected_manifest_path),
-                "bare_path": str(bare_path) if bare_path else None,
-                "bare_value": (bare_text or "").strip() if bare_text else None,
-                "suggested_fix": "task upgrade",
-            },
-        )
-    if bare_text is None:
-        # YAML present, bare missing -- not a drift in itself; cmd_upgrade
-        # will derive the bare file on next run. Report as pass with a note.
-        manifest = _parse_manifest(manifest_text)
-        derived = _manifest_tag_to_version(manifest)
-        return CheckResult(
-            name="manifest-agreement",
-            status="pass",
-            detail=(
-                f"YAML manifest at {manifest_path} present; bare .deft-version "
-                f"absent (derived value: {derived!r} from manifest tag). "
-                "Run `task upgrade` to regenerate the derivative."
-            ),
-            data={
-                "manifest_path": str(manifest_path),
-                "manifest": manifest,
-                "derived_version": derived,
-            },
-        )
-    manifest = _parse_manifest(manifest_text)
-    derived = _manifest_tag_to_version(manifest)
-    bare_value = bare_text.strip()
-    if derived is None:
-        return CheckResult(
-            name="manifest-agreement",
-            status="fail",
-            detail=(
-                f"YAML manifest at {manifest_path} has no parseable tag/ref "
-                "field; cannot reconcile with bare .deft-version."
-            ),
-            data={
-                "manifest_path": str(manifest_path),
-                "bare_path": str(bare_path),
-                "manifest": manifest,
-                "bare_value": bare_value,
-            },
-        )
-    if derived == bare_value:
-        return CheckResult(
-            name="manifest-agreement",
-            status="pass",
-            detail=(
-                f"YAML manifest (tag={derived!r}) agrees with bare .deft-version ({bare_value!r})."
-            ),
-            data={
-                "manifest_path": str(manifest_path),
-                "bare_path": str(bare_path),
-                "derived_version": derived,
-                "bare_value": bare_value,
-            },
-        )
-    return CheckResult(
-        name="manifest-agreement",
-        status="fail",
-        detail=(
-            f"Drift detected: YAML manifest tag={derived!r} does NOT agree "
-            f"with bare .deft-version={bare_value!r}. Per #1046 PR-B AC-4 "
-            "the YAML manifest is the canonical source -- run `task upgrade` "
-            "to regenerate the bare derivative from the manifest, OR "
-            f"manually update {manifest_path} if the bare value is correct. "
-            "See UPGRADING.md for the canonical drift-repair walkthrough."
-        ),
-        data={
-            "manifest_path": str(manifest_path),
-            "bare_path": str(bare_path),
-            "derived_version": derived,
-            "bare_value": bare_value,
-            "authoritative": "manifest",
-            "suggested_fix": "task upgrade",
-        },
-    )
-
-
-def _check_install_path_consistency(project_root: Path, install_root: str | None) -> CheckResult:
-    """Check #4: AGENTS.md install-root claim resolves to an on-disk directory.
-
-    Narrow scope by design (#1046 PR-B Greptile review #1057): this check
-    only verifies that the install root AGENTS.md declares is a real
-    directory on disk. The cross-check that the YAML manifest is
-    **co-located** at that root is the responsibility of check #3
-    (``manifest-agreement``) -- when the manifest lives at a different
-    install root (e.g. legacy ``deft/VERSION`` while AGENTS.md claims
-    ``.deft/core``), check #3 reports the drift with the manifest as the
-    authoritative source. Splitting the responsibility keeps each check
-    independently actionable: this one says "reinstall or fix AGENTS.md",
-    check #3 says "reconcile the manifest with the bare derivative".
-    """
-    effective_install_root = install_root
-    fallback_info_note = ""
-    source = "AGENTS.md"
-    # #1062: prefer the manifest-side ``install_root`` field when present --
-    # it is the single source of truth for the install-layout contract.
-    # Fall back to the legacy AGENTS.md parse only when the manifest exists
-    # but predates the field (legacy v0.28 shape) or no manifest exists.
-    # The ``source`` flag stays sticky across the manifest-found-but-empty
-    # path so the diagnostic prose later accurately names where the
-    # effective install root came from (Greptile P1 on PR #1063 -- prior
-    # heuristic compared values, which mislabelled when manifest and
-    # AGENTS.md happened to agree).
-    # #1427: probe the manifest canonical-first via the shared candidate
-    # list so a webinstaller-vendored ``.deft/VERSION`` is considered too
-    # (the prior shape probed only ``.deft/core/VERSION`` and legacy
-    # ``deft/VERSION``). Iterate the candidate list rather than call
-    # ``_locate_manifest`` so an existing-but-unreadable manifest (OSError /
-    # permission denial -> ``_read_text_safe`` returns None) falls through
-    # to the next candidate, preserving the ``continue``-on-unreadable
-    # resilience of the original two-path loop (Greptile P2 on PR #1431).
-    # The first READABLE manifest wins, matching the prior
-    # break-on-first-found semantics.
-    for manifest_path in _manifest_candidate_paths(project_root, install_root):
-        manifest_text = _read_text_safe(manifest_path)
-        if manifest_text is None:
-            continue
-        manifest = _parse_manifest(manifest_text)
-        manifest_install_root = manifest.get("install_root")
-        if isinstance(manifest_install_root, str) and manifest_install_root.strip():
-            effective_install_root = manifest_install_root.strip()
-            fallback_info_note = ""
-            source = "manifest"
-            break
-        # Manifest found but missing the #1062 ``install_root`` field
-        # (legacy v0.28 shape, or a webinstaller ``.deft/VERSION`` that
-        # omits it). Fall back to the AGENTS.md parse and note it.
-        # ``source`` stays "AGENTS.md" -- the manifest was found but did not
-        # carry the install_root field, so the effective value still came
-        # from the AGENTS.md parse.
-        fallback_info_note = (
-            f" INFO: manifest at {manifest_path} is missing install_root; "
-            "fell back to the legacy AGENTS.md install-root parse."
-        )
-        break
-    if effective_install_root is None:
-        return CheckResult(
-            name="install-path-consistency",
-            status="skip",
-            detail=(
-                "AGENTS.md does not declare an install root."
-                + fallback_info_note
-            ),
-            data={
-                "claimed_install_root": install_root,
-                "effective_install_root": effective_install_root,
-                "fallback_info_note": fallback_info_note or None,
-            },
-        )
-    claimed_dir = project_root / effective_install_root
-    if not claimed_dir.is_dir():
-        return CheckResult(
-            name="install-path-consistency",
-            status="fail",
-            detail=(
-                f"Install root is recorded as {effective_install_root!r} "
-                f"(source: {source}) but {claimed_dir} is not a directory. "
-                "Pick one of two repair paths: "
-                "(a) run `.deft/core/run agents:refresh` (Unix) / "
-                "`.deft\\core\\run agents:refresh` (Windows) to rewrite "
-                "AGENTS.md to match the on-disk framework -- pick this if "
-                "the framework on disk is correct; OR "
-                "(b) run `npx @deftai/directive update` to (re)deposit the "
-                "framework at the path AGENTS.md / the manifest claims (the "
-                "npm CLI project deposit, #1912) -- "
-                "pick this if AGENTS.md is correct. The YAML manifest (if "
-                "present) is authoritative for the install-layout contract. "
-                "See UPGRADING.md for the canonical drift-repair walkthrough."
-            ),
-            data={
-                "claimed_install_root": install_root,
-                "effective_install_root": effective_install_root,
-                "effective_install_root_source": source,
-                "claimed_dir": str(claimed_dir),
-                "claimed_dir_exists": False,
-                "fallback_info_note": fallback_info_note or None,
-                "suggested_fix": ".deft/core/run agents:refresh",
-                "suggested_fix_alt": "npx @deftai/directive update",
-            },
-        )
-    # Note: this check intentionally does NOT verify the YAML manifest
-    # is co-located at ``<claimed_dir>/VERSION`` -- that cross-check is
-    # owned by check #3 (``manifest-agreement``). See docstring for the
-    # rationale and the per-check responsibility split.
-    return CheckResult(
-        name="install-path-consistency",
-        status="pass",
-        detail=(
-            f"Install root ({effective_install_root!r}, source: {source}) "
-            f"matches an existing directory at {claimed_dir}."
-            + fallback_info_note
-        ),
-        data={
-            "claimed_install_root": install_root,
-            "effective_install_root": effective_install_root,
-            "effective_install_root_source": source,
-            "claimed_dir": str(claimed_dir),
-            "fallback_info_note": fallback_info_note or None,
-        },
-    )
-
-
-# ---------------------------------------------------------------------------
-# Legacy-layout + canonical-vendored npm signpost (#1912 / #1997)
-# ---------------------------------------------------------------------------
-
-
-def _gitmodules_references_framework(text: str) -> bool:
-    normalized = text.replace("\r\n", "\n").lower()
-    if "deftai/directive" in normalized:
-        return True
-    return bool(re.search(r"(^|\n)\s*path\s*=\s*\.?deft(/|\s|$)", normalized))
-
-
-def _detect_legacy_layout(project_root: Path) -> tuple[bool, str | None, str, list[str]]:
-    """Mirror packages/core/src/init-deposit/legacy-detect.ts heuristics."""
-    if (project_root / ".deft" / "core").is_dir():
-        return False, None, "", []
-    orphan = project_root / ".deft" / "VERSION"
-    if orphan.is_file():
-        return (
-            True,
-            "orphan-deft-version",
-            "Found an orphan .deft/VERSION manifest with no .deft/core/ directory -- "
-            "this is a pre-.deft/core/ layout the npm CLI does not migrate.",
-            [".deft/VERSION"],
-        )
-    deft_dir = project_root / "deft"
-    deft_markers = [
-        deft_dir / "VERSION",
-        deft_dir / "main.md",
-        deft_dir / "Taskfile.yml",
-    ]
-    deft_is_framework = deft_dir.is_dir() and (
-        any(p.is_file() for p in deft_markers) or (deft_dir / "skills").is_dir()
-    )
-    if deft_is_framework:
-        if (deft_dir / ".git").exists():
-            return (
-                True,
-                "git-clone-or-submodule",
-                "Found a deft/ framework directory backed by its own .git (clone or "
-                "git submodule) -- the npm CLI does not migrate a clone/submodule deposit.",
-                ["deft/", "deft/.git"],
-            )
-        return (
-            True,
-            "legacy-deft-prefixed",
-            "Found a legacy deft/-prefixed framework install -- the canonical layout "
-            "is .deft/core/. The npm CLI does not migrate the deft/ -> .deft/core/ move.",
-            ["deft/"],
-        )
-    gitmodules = project_root / ".gitmodules"
-    if gitmodules.is_file():
-        text = _read_text_safe(gitmodules)
-        if text is not None and _gitmodules_references_framework(text):
-            return (
-                True,
-                "git-clone-or-submodule",
-                "Found a .gitmodules entry referencing the Deft framework -- a submodule "
-                "deposit the npm CLI does not migrate.",
-                [".gitmodules"],
-            )
-    agents_text = _read_text_safe(project_root / "AGENTS.md")
-    if agents_text is not None:
-        install_root = _parse_install_root_from_agents_md(agents_text)
-        if install_root == "deft":
-            return (
-                True,
-                "legacy-deft-prefixed",
-                "AGENTS.md declares the legacy deft/ install root -- the canonical layout "
-                "is .deft/core/. The npm CLI does not migrate the deft/ -> .deft/core/ move.",
-                ["AGENTS.md (install root: deft)"],
-            )
-        if (
-            "<!-- deft:managed-section" in agents_text
-            and _extract_managed_section(agents_text) is None
-        ):
-            return (
-                True,
-                "pre-v0.27-sentinel-agents-md",
-                "AGENTS.md carries a pre-v0.27 sentinel-only managed-section (no v2/v3 "
-                "managed-section markers) -- run the Go bridge to migrate before the npm CLI.",
-                ["AGENTS.md (sentinel-only managed-section)"],
-            )
-    return False, None, "", []
-
-
-def _legacy_layout_signpost_line(kind: str | None, detail: str) -> str:
-    return (
-        f"Legacy Deft layout detected ({kind or 'unknown'}): {detail} "
-        "Run the frozen Go bridge installer to migrate to .deft/core/, then use the npm "
-        f"CLI (`npx @deftai/directive update`). See {UPGRADING_DOC_URL} "
-        f"(frozen bridge: {GO_BRIDGE_RELEASES_URL})."
-    )
-
-
-def _check_legacy_layout(project_root: Path) -> CheckResult:
-    legacy, kind, detail, evidence = _detect_legacy_layout(project_root)
-    if not legacy:
-        return CheckResult(
-            name="legacy-layout",
-            status="skip",
-            detail="No legacy Deft layout detected (canonical .deft/core/ or greenfield).",
-            data={"legacy_layout": False},
-        )
-    signpost = _legacy_layout_signpost_line(kind, detail)
-    return CheckResult(
-        name="legacy-layout",
-        status="fail",
-        detail=signpost,
-        data={
-            "legacy_layout": True,
-            "legacy_layout_kind": kind,
-            "evidence": evidence,
-            "upgrading_doc_url": UPGRADING_DOC_URL,
-            "go_bridge_releases_url": GO_BRIDGE_RELEASES_URL,
-        },
-    )
-
-
-def _detect_canonical_vendored_manifest(project_root: Path) -> Path | None:
-    canonical = project_root / ".deft" / "core" / "VERSION"
-    located = _locate_manifest(project_root, ".deft/core")
-    return located if located == canonical else None
-
-
-def _is_npm_managed(manifest: dict) -> bool:
-    return manifest.get(NPM_MANAGED_SENTINEL_KEY) == NPM_MANAGED_SENTINEL_VALUE
-
-
-def _check_canonical_vendored_npm_signpost(project_root: Path) -> CheckResult:
-    manifest_path = _detect_canonical_vendored_manifest(project_root)
-    if manifest_path is None:
-        return CheckResult(
-            name="canonical-vendored-npm-signpost",
-            status="skip",
-            detail="No canonical-vendored .deft/core/ deposit (nothing to signpost).",
-            data={"canonical_vendored": False},
-        )
-    text = _read_text_safe(manifest_path)
-    if text is None:
-        return CheckResult(
-            name="canonical-vendored-npm-signpost",
-            status="skip",
-            detail="Canonical-vendored manifest unreadable.",
-            data={"canonical_vendored": True},
-        )
-    manifest = _parse_manifest(text)
-    if _is_npm_managed(manifest):
-        return CheckResult(
-            name="canonical-vendored-npm-signpost",
-            status="skip",
-            detail="Deposit is already npm-managed (hybrid).",
-            data={"canonical_vendored": True, "npm_managed": True},
-        )
-    detail = (
-        "Canonical-vendored install (.deft/core/) is not yet npm-managed. "
-        "Post-freeze upgrades run via npm: install the engine with "
-        f"`{CANONICAL_UPGRADE_COMMAND}`, then run `directive migrate` "
-        f"to stamp provenance. See {UPGRADING_DOC_URL}."
-    )
-    return CheckResult(
-        name="canonical-vendored-npm-signpost",
-        status="fail",
-        detail=detail,
-        data={
-            "canonical_vendored": True,
-            "npm_managed": False,
-            "manifest_path": str(manifest_path),
-            "sentinel_key": NPM_MANAGED_SENTINEL_KEY,
-            "sentinel_value": NPM_MANAGED_SENTINEL_VALUE,
-            "upgrading_doc_url": UPGRADING_DOC_URL,
-        },
-    )
-
-
-def _run_local_signpost_checks(
-    project_root: Path,
-    *,
-    emit_warn,
-    add_finding,
-) -> None:
-    """Lightweight local signposts on throttle-skip (#1997)."""
-    if _running_inside_deft_repo(project_root):
-        return
-    for check in (
-        _check_legacy_layout(project_root),
-        _check_canonical_vendored_npm_signpost(project_root),
-    ):
-        if check.status == "skip":
-            continue
-        if check.status == "fail":
-            emit_warn(check.detail)
-            add_finding(
-                "warning",
-                check.detail,
-                check=check.name,
-                status=check.status,
-                data=check.data,
-            )
-
-
-# ---------------------------------------------------------------------------
-# Top-level driver (ported) -- provides run_checks for tests + internal use
-# ---------------------------------------------------------------------------
-
-
-def run_checks(project_root: Path) -> dict:
-    """Run all four checks and return a structured payload.
-
-    Public API consumed by ``run::_maybe_run_framework_doctor`` (and tests).
-    Returns the DoctorResult dict shape directly. Best-effort -- any
-    individual check that fails to run converts to an ``error`` status and
-    propagates to exit code 2.
-    """
-    return _run_checks_impl(project_root).to_dict()
-
-
-def _run_checks_impl(project_root: Path) -> DoctorResult:
-    """Internal driver -- returns the dataclass form for richer testing."""
-    errors: list[str] = []
-    if not project_root.is_dir():
-        return DoctorResult(
-            project_root=str(project_root),
-            install_root=None,
-            exit_code=EXIT_CONFIG_ERROR,
-            checks=[],
-            errors=[f"project root does not exist: {project_root}"],
-        )
-
-    agents_md_path = project_root / "AGENTS.md"
-    agents_md_text = _read_text_safe(agents_md_path)
-    install_root: str | None = None
-    if agents_md_text is not None:
-        install_root = _parse_install_root_from_agents_md(agents_md_text)
-
-    checks: list[CheckResult] = []
-
-    # If AGENTS.md is missing entirely, the install-root-dependent checks
-    # all skip; surface this fact in a synthetic check so operators see
-    # the cause.
-    if agents_md_text is None:
-        checks.append(
-            CheckResult(
-                name="agents-md-present",
-                status="fail",
-                detail=(
-                    "AGENTS.md not found at project root -- run "
-                    "`.deft/core/run agents:refresh` to generate it from "
-                    "the canonical template."
-                ),
-                data={"agents_md_path": str(agents_md_path)},
-            )
-        )
-        # Still attempt the manifest agreement check (it can run without
-        # AGENTS.md for the greenfield case).
-        checks.append(_check_manifest_agreement(project_root, None))
-        checks.append(_check_legacy_layout(project_root))
-        checks.append(_check_canonical_vendored_npm_signpost(project_root))
-        return DoctorResult(
-            project_root=str(project_root),
-            install_root=None,
-            exit_code=_derive_exit_code(checks, errors),
-            checks=checks,
-            errors=errors,
-        )
-
-    checks.append(_check_quick_start_resolves(project_root, install_root))
-    checks.append(_check_skill_paths_resolve(project_root, agents_md_text))
-    checks.append(_check_manifest_agreement(project_root, install_root))
-    checks.append(_check_install_path_consistency(project_root, install_root))
-    checks.append(_check_legacy_layout(project_root))
-    checks.append(_check_canonical_vendored_npm_signpost(project_root))
-
-    return DoctorResult(
-        project_root=str(project_root),
-        install_root=install_root,
-        exit_code=_derive_exit_code(checks, errors),
-        checks=checks,
-        errors=errors,
-    )
-
-
-def _derive_exit_code(checks: list[CheckResult], errors: list[str]) -> int:
-    """Three-state exit code from check results + errors."""
-    if errors or any(c.status == "error" for c in checks):
-        return EXIT_CONFIG_ERROR
-    if any(
-        c.status == "fail" and c.name != "canonical-vendored-npm-signpost"
-        for c in checks
-    ):
-        return EXIT_DRIFT
-    return EXIT_CLEAN
-
-
-# --- Extracted doctor logic (from run, markers removed, now owned here) ---
-# (start of logic extracted from monolithic run per #1335)
-# The block from this marker through DOCTOR-EXTRACTION-END (the end of
-# cmd_doctor, just before def cmd_update) is extracted verbatim into
-# scripts/doctor.py . After extraction, this region is replaced by a
-# thin shim that does the path-insert + import + delegation.
-# The scripts/doctor.py now owns the core doctor logic.
-# ===
-
-# ── #1272 root Taskfile.yml include diagnostics ──────────────────────────
-#
-# A freshly installed directive project does not have a working `task X`
-# surface from the project root until the consumer wires their
-# root-level Taskfile.yml to include `.deft/core/Taskfile.yml`. The
-# install policy in `main.md` correctly prohibits silent mutation of
-# the consumer's existing Taskfile.yml, but the framework should still
-# *diagnose* the missing-include / missing-file shapes the moment the
-# operator runs doctor. Interactive `run doctor --fix` may offer to
-# create a Taskfile.yml when one is absent (explicit consent required);
-# the default and `--session` paths NEVER mutate filesystem state.
-#
-# The canonical snippet is mirrored verbatim from `.deft/core/main.md`
-# ("Publishing deft tasks in your project root") so doctor's output and
-# the prose documentation never drift.
-
-# Canonical YAML snippet emitted by doctor's diagnostic output and
-# written verbatim when the operator opts in to interactive repair.
-# Kept as a module-level constant so tests can compare against the
-# exact bytes a write would produce.
-_TASKFILE_INCLUDE_SNIPPET = (
-    "version: '3'\n"
-    "\n"
-    "includes:\n"
-    "  deft:\n"
-    "    taskfile: ./.deft/core/Taskfile.yml\n"
-    "    optional: true\n"
-)
-
-# Matches a top-level YAML ``includes:`` declaration. Used by the
-# indentation-aware state machine in :func:`_includes_block_has_deft_taskfile`
-# to anchor the scan: a ``taskfile:`` line that lives inside any other
-# block (e.g. ``vars:``, ``tasks:`` cmds, a YAML comment, a long string
-# scalar) MUST NOT count as a valid deft framework include, otherwise
-# the diagnostic mis-reports ``ok`` on a Taskfile that mentions the
-# string ``taskfile: ./.deft/core/Taskfile.yml`` in unrelated context
-# (a comment, an example block, an echo cmd). See #1303 review.
-_TASKFILE_INCLUDES_KEY_RE = re.compile(
-    r"^(?P<indent>[\t ]*)includes\s*:\s*(?:#.*)?$",
-    re.IGNORECASE,
-)
-
-# Matches ``taskfile: <path-to-deft-framework-Taskfile>`` value lines that
-# appear under the ``includes:`` mapping. Tolerates leading ``./``,
-# surrounding whitespace, optional single/double quotes around the value,
-# and an inline ``# ...`` comment trailing the value. Case-insensitive so
-# both ``Taskfile.yml`` and ``taskfile.yml`` match. Indent MUST be > 0
-# under a top-level ``includes:`` block.
-_TASKFILE_INCLUDE_VALUE_RE = re.compile(
-    r"^[\t ]+taskfile\s*:\s*[\"']?\.?/?(?:\.deft/core|deft)/Taskfile\.ya?ml[\"']?"
-    r"\s*(?:#.*)?$",
-    re.IGNORECASE,
-)
-
-
-def _includes_block_has_deft_taskfile(text: str) -> bool:
-    """Return True iff a top-level ``includes:`` mapping points at deft.
-
-    Walks ``text`` line-by-line with a small indentation-aware state
-    machine: anchors on a top-level (indent 0) ``includes:`` key, then
-    scans the strictly-greater-indent body for a ``taskfile:`` property
-    whose value resolves to either the canonical ``./.deft/core/Taskfile.yml``
-    or the pre-v0.27 legacy ``./deft/Taskfile.yml``. Lines whose indent
-    is less-than-or-equal-to the ``includes:`` indent end the block.
-
-    Stdlib-only: ``run`` is the bootstrap entry point and cannot assume
-    PyYAML is installed. A full YAML walk would be more robust but adds
-    a runtime dependency we deliberately avoid here.
-    """
-    includes_indent: int | None = None
-    in_includes = False
-    for raw_line in text.splitlines():
-        stripped = raw_line.strip()
-        if not stripped or stripped.startswith("#"):
-            continue
-        indent = len(raw_line) - len(raw_line.lstrip(" \t"))
-        if not in_includes:
-            match = _TASKFILE_INCLUDES_KEY_RE.match(raw_line)
-            if match is not None and indent == 0:
-                includes_indent = indent
-                in_includes = True
-            continue
-        if indent <= (includes_indent or 0):
-            in_includes = False
-            match = _TASKFILE_INCLUDES_KEY_RE.match(raw_line)
-            if match is not None and indent == 0:
-                includes_indent = indent
-                in_includes = True
-            continue
-        if _TASKFILE_INCLUDE_VALUE_RE.match(raw_line):
-            return True
-    return False
-
-
-def _resolve_consumer_taskfile(
-    project_root: Path | None = None,
-) -> Path | None:
-    """Return the consumer project's root Taskfile path, or None if absent.
-
-    Recognises both ``Taskfile.yml`` and ``Taskfile.yaml`` so the
-    diagnostic accepts whichever spelling the consumer chose. Returns
-    the first candidate that exists on disk; returns ``None`` when
-    neither file is present so callers can distinguish the
-    missing-file case from the missing-include case.
-
-    ``project_root`` defaults to ``Path.cwd()`` when omitted so existing
-    callers stay backward-compatible; the explicit-argument shape is the
-    canonical form so :func:`cmd_doctor` can honour a user-supplied
-    ``--project-root <path>`` (#1303 review).
-    """
-    if project_root is None:
-        project_root = Path.cwd()
-    for name in ("Taskfile.yml", "Taskfile.yaml"):
-        candidate = project_root / name
-        if candidate.is_file():
-            return candidate
-    return None
-
-
-def _classify_taskfile_include(project_root: Path) -> str:
-    """Classify the consumer's root Taskfile include health (#1272).
-
-    Returns one of:
-        ``ok``              -- root Taskfile.yml present and includes the
-                               deft framework Taskfile (``./.deft/core/Taskfile.yml``
-                               or the legacy ``./deft/Taskfile.yml``).
-        ``missing-file``    -- neither ``Taskfile.yml`` nor ``Taskfile.yaml``
-                               exists at the project root. Interactive
-                               ``run doctor --fix`` may create one with
-                               explicit consent.
-        ``missing-include`` -- a root Taskfile exists but contains no
-                               include pointing at the deft framework
-                               Taskfile. Doctor NEVER mutates an
-                               existing user-owned Taskfile -- diagnose
-                               only; the operator pastes the snippet.
-        ``unreadable``      -- a root Taskfile exists but could not be
-                               read (permission error, etc.). Diagnose;
-                               do not repair.
-
-    Pure -- read-only filesystem probe + indentation-aware string walk.
-    Never mutates state.
-    """
-    taskfile = _resolve_consumer_taskfile(project_root)
-    if taskfile is None:
-        return "missing-file"
-    try:
-        # ``utf-8-sig`` transparently strips a leading UTF-8 BOM if present.
-        # Windows editors (Notepad, some VS Code configurations) persist YAML
-        # with a BOM byte at the head; ``utf-8`` would keep the ``\ufeff``
-        # prefix in ``text`` and defeat the ``^[\t ]*includes`` anchor in
-        # :func:`_includes_block_has_deft_taskfile`, producing a spurious
-        # ``missing-include`` diagnostic on a legitimately wired Taskfile.
-        # See #1303 pass-2 review.
-        text = taskfile.read_text(encoding="utf-8-sig", errors="replace")
-    except OSError:
-        return "unreadable"
-    if _includes_block_has_deft_taskfile(text):
-        return "ok"
-    return "missing-include"
-
-
-def _format_missing_include_snippet() -> str:
-    """Return the paste-ready `includes:` fragment for an existing Taskfile.
-
-    Used by doctor's ``missing-include`` diagnostic so the operator
-    sees the exact YAML they need to paste under their existing
-    ``includes:`` block, without the ``version: '3'`` header (which
-    their existing file already supplies).
-    """
-    return (
-        "  deft:\n"
-        "    taskfile: ./.deft/core/Taskfile.yml\n"
-        "    optional: true\n"
-    )
-
-
-def _parse_doctor_flags(args: list[str]) -> dict:
-    """Parse the doctor-specific CLI flags (#1272, #1303 review).
-
-    Recognises (whitelist; unknown tokens surface as ``unknown``):
-        ``--session``                -- diagnose-only, session-safe mode.
-                                        NEVER prompts, NEVER mutates
-                                        filesystem state. Suitable for
-                                        invocation from session-start
-                                        rituals.
-        ``--fix`` / ``--repair`` /   -- offer interactive repair when
-        ``--repair-taskfile``           actionable (currently: create
-                                        missing root Taskfile.yml with
-                                        the canonical include). Requires
-                                        an interactive TTY AND explicit
-                                        operator approval at the prompt;
-                                        ignored when ``--session`` is
-                                        also passed.
-        ``--json``                   -- emit a single JSON object on
-                                        stdout describing the findings;
-                                        suppresses the human-readable
-                                        prose surface. Exit code is
-                                        still 0 (clean) / 1 (errors).
-        ``--quiet``                  -- suppress the per-check success
-                                        lines; errors and warnings still
-                                        surface.
-        ``--project-root <path>`` /  -- override the project root used
-        ``--project-root=<path>``       for the Taskfile diagnostic.
-                                        Defaults to :func:`Path.cwd`.
-        ``-h`` / ``--help``          -- accepted (caller decides how to
-                                        render help text); does not run
-                                        the diagnostics.
-
-    Unknown tokens are collected into ``flags["unknown"]`` so the caller
-    can exit non-zero with a useful error message rather than silently
-    swallowing a typo (e.g. ``--repare`` instead of ``--repair`` -- the
-    pre-review behaviour shipped diagnostics that ignored the typo,
-    masking the fact that the user never opted into repair).
-    """
-    flags = {
-        "session": False,
-        "fix": False,
-        "json": False,
-        "quiet": False,
-        "full": False,
-        "help": False,
-        "project_root": None,
-        "unknown": [],
-    }
-    i = 0
-    while i < len(args):
-        token = args[i]
-        if token == "--session":
-            flags["session"] = True
-        elif token in ("--fix", "--repair", "--repair-taskfile"):
-            flags["fix"] = True
-        elif token == "--json":
-            flags["json"] = True
-        elif token == "--quiet":
-            flags["quiet"] = True
-        elif token == "--full":
-            # #1308: bypass the 24h/4h throttle and always run the full
-            # check. Operators reach for this when the prior run was
-            # dirty (errors) and they want to re-probe after fixing,
-            # OR when they want to re-confirm a clean run before
-            # publishing a swarm.
-            flags["full"] = True
-        elif token in ("-h", "--help"):
-            flags["help"] = True
-        elif token == "--project-root":
-            if i + 1 >= len(args):
-                flags["unknown"].append("--project-root (missing value)")
-            else:
-                i += 1
-                flags["project_root"] = args[i]
-        elif token.startswith("--project-root="):
-            value = token.split("=", 1)[1]
-            if value:
-                flags["project_root"] = value
-            else:
-                flags["unknown"].append("--project-root= (empty value)")
-        else:
-            flags["unknown"].append(token)
-        i += 1
-    return flags
-
-
-# Allowed flag set for ``run doctor`` -- surfaced in the error message
-# emitted when ``_parse_doctor_flags`` collects an unknown token (#1303
-# review correctness #3). Keep in sync with the registered branches in
-# :func:`_parse_doctor_flags`.
-_DOCTOR_ALLOWED_FLAGS = (
-    "--session",
-    "--fix",
-    "--repair",
-    "--repair-taskfile",
-    "--json",
-    "--quiet",
-    "--full",
-    "--project-root",
-    "-h",
-    "--help",
-)
-
-
-def _load_doctor_state_module():
-    """Lazy-import ``scripts/_doctor_state`` (#1308)."""
-    try:
-        # Inside scripts/doctor.py, get_script_dir() already returns the
-        # scripts/ dir containing sibling _doctor_state.py. Do not append
-        # another "/scripts" (would resolve to scripts/scripts/ and break
-        # throttle state load when doctor.py is the entry point).
-        scripts_dir = get_script_dir()
-        if str(scripts_dir) not in sys.path:
-            sys.path.insert(0, str(scripts_dir))
-        import _doctor_state  # type: ignore[import-not-found]
-        return _doctor_state
-    except Exception:  # noqa: BLE001 -- state load MUST NOT break doctor
-        return None
-
-
-def _evaluate_doctor_throttle(project_root: Path):
-    """Read doctor state and compute the 24h/4h throttle decision (#1308)."""
-    mod = _load_doctor_state_module()
-    if mod is None:
-        return None
-    try:
-        state = mod.read_state(project_root)
-        return mod.decide_throttle(state)
-    except Exception:  # noqa: BLE001 -- state read MUST NOT break doctor
-        return None
-
-
-# --- Ported from run (required by cmd_doctor / freshness / throttle paths) ---
-# These were left behind during the initial extraction; without them every
-# `run doctor` (non-throttled path) hits NameError before any check runs.
-# Small batch ports; supporting constants/defs included where referenced.
-
-# Minimal local read_yn (used only in interactive --fix Taskfile repair path
-# under isatty + fix_mode). Closes the "undefined" gap Greptile summary
-# flagged on the post-7a0606c head. Full ask_confirm lives in run; this is
-# the smallest non-crashing implementation sufficient for doctor.
-def read_yn(prompt_text: str, default: bool = False) -> bool:
-    """Yes/No prompt (read_yn alias to run's ask_confirm)."""
-    try:
-        suffix = " (Y/n): " if default else " (y/N): "
-        resp = input(f"{prompt_text}{suffix}").strip().lower()
-        if not resp:
-            return default
-        return resp[0] in ("y", "yes")
-    except (EOFError, KeyboardInterrupt):
-        return default
-
-
-def _load_agents_md_module():
-    """Lazy-import the shared ``scripts/_agents_md`` helpers (#1389).
-
-    ``get_script_dir()`` already returns the ``scripts/`` directory holding
-    the sibling ``_agents_md.py``, so mirror ``_load_doctor_state_module``
-    and insert it on ``sys.path`` before importing. The freshness probe can
-    then share ``run``'s exact managed-section verdict logic instead of the
-    interim stub that always reported ``unreadable``.
-    """
-    scripts_dir = get_script_dir()
-    if str(scripts_dir) not in sys.path:
-        sys.path.insert(0, str(scripts_dir))
-    import _agents_md  # type: ignore[import-not-found]
-    return _agents_md
-
-
-def _agents_refresh_plan(project_root: Path) -> dict:
-    """Compute the real AGENTS.md managed-section freshness verdict (#1389).
-
-    Delegates to the shared, pure ``scripts/_agents_md._agents_refresh_plan``
-    -- the same implementation ``run`` uses -- so a consumer whose managed
-    section is present, readable and current reports ``state == "current"``
-    (no freshness warning) instead of the previous interim stub that
-    unconditionally returned ``{"state": "unreadable"}`` and produced a
-    spurious warning on every ``task doctor`` run. Genuinely stale sections
-    report ``stale`` (the freshness check then points the operator at
-    ``deft agents:refresh``); a genuinely unreadable / template-missing
-    state still surfaces a warning.
-    """
-    return _load_agents_md_module()._agents_refresh_plan(project_root)
-
-
-def _now_utc() -> datetime:
-    """Return UTC-aware ``datetime.now`` (split out for test monkeypatching)."""
-    return datetime.now(UTC)
-
-
-# Post-#1875 content/ move: these framework-internal markers now live under
-# content/ in the SOURCE repo. They identify a deft source checkout (a consumer
-# would never reproduce them); the C1 flatten means a consumer deposit has no
-# content/ dir, so the absence of content/ here is itself consistent with the
-# "not a source checkout" branch.
-_DEFT_REPO_POSITIVE_MARKERS = (
-    Path("content") / "templates" / "agents-entry.md",
-    Path("content") / "skills" / "deft-directive-build" / "SKILL.md",
-)
-
-
-def _running_inside_deft_repo(project_root: Path) -> bool:
-    """Heuristic: True when `run` is invoked from inside the deft repo itself.
-
-    Consumer projects embed deft as ``./deft/`` (legacy) or ``./.deft/core/``
-    (canonical) and consume the framework's published surface; the deft
-    source repo carries ``main.md`` at its root, has neither install
-    location materialised inside its own checkout, AND ships a set of
-    framework-internal artefacts (notably ``templates/agents-entry.md`` and
-    ``skills/deft-directive-build/SKILL.md``) a consumer would have no
-    reason to mirror.
-
-    The heuristic fires only when ALL of the following hold:
-      * ``main.md`` is present at ``project_root`` (the documented entry
-        point a consumer never reproduces verbatim).
-      * NEITHER ``./deft`` (legacy install) NOR ``./.deft/core`` (canonical
-        install) exists at the project root -- both indicate the deft
-        framework was installed INTO this directory rather than that this
-        directory IS the framework.
-      * ALL of the markers in ``_DEFT_REPO_POSITIVE_MARKERS`` resolve --
-        framework-internal paths a consumer would never reproduce.
-
-    The original heuristic (#1272 baseline) checked only ``main.md`` plus
-    the absence of ``./deft``; that mis-fired on a consumer who happened
-    to carry a root-level ``main.md`` for unrelated reasons OR who
-    installed canonically to ``./.deft/core`` and so genuinely had no
-    ``./deft`` subdirectory -- doctor would then silently skip the
-    Taskfile-include diagnostic in exactly the place it was meant to
-    surface (#1303 review SLizard P1, Greptile carryover).
-
-    Skipping the gate here avoids nagging deft maintainers on every
-    ``run`` invocation against the framework checkout itself.
-    """
-    if not (project_root / "main.md").is_file():
-        return False
-    if (project_root / "deft").is_dir():
-        return False
-    if (project_root / ".deft" / "core").is_dir():
-        return False
-    return all((project_root / marker).is_file() for marker in _DEFT_REPO_POSITIVE_MARKERS)
-
-
-# --- Extracted doctor logic (from run, markers removed, now owned here) ---
-
-def _format_iso_z(when) -> str:
-    """Render a UTC-aware datetime as YYYY-MM-DDTHH:MM:SSZ."""
-    if when is None:
-        return ""
-    if when.tzinfo is None:
-        when = when.replace(tzinfo=UTC)
-    return when.astimezone(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
-
-
-def _render_doctor_status_line(decision) -> str:
-    """Render the human-readable throttle-skip line (#1308)."""
-    age_h = max(int(decision.age_hours), 0)
-    if decision.dirty:
-        errs = decision.last_error_count
-        warns = max(decision.last_finding_count - decision.last_error_count, 0)
-        err_phrase = f"{errs} error{'s' if errs != 1 else ''}"
-        warn_phrase = f"{warns} warning{'s' if warns != 1 else ''}"
-        return (
-            f"[doctor] ran {age_h}h ago, {err_phrase} / {warn_phrase} "
-            "-- UNRESOLVED; run `deft doctor --full` to re-probe or "
-            "address findings."
-        )
-    remaining = decision.next_eligible_at - _now_utc()
-    remaining_h = max(int(remaining.total_seconds() // 3600), 0)
-    return (
-        f"[doctor] ran {age_h}h ago, clean; next eligible in "
-        f"{remaining_h}h; --full forces."
-    )
-
-
-def _emit_doctor_throttle_skip(decision, *, json_mode: bool, project_root: Path) -> int:
-    """Print the throttle-skip surface and return the gated exit code (#1308)."""
-    signpost_findings: list[dict] = []
-
-    def _add_signpost(severity: str, message: str, **extras: object) -> None:
-        entry: dict = {"severity": severity, "message": message}
-        entry.update(extras)
-        signpost_findings.append(entry)
-
-    _run_local_signpost_checks(
-        project_root,
-        emit_warn=warn if not json_mode else (lambda _m: None),
-        add_finding=_add_signpost,
-    )
-
-    hint = (
-        "run `deft doctor --full` to re-probe or address findings"
-        if decision.dirty
-        else "--full forces"
-    )
-    if json_mode:
-        payload = {
-            "status": "throttle-skipped",
-            "last_run_at": _format_iso_z(decision.last_run_at),
-            "last_exit_code": decision.last_exit_code,
-            "last_error_count": decision.last_error_count,
-            "last_finding_count": decision.last_finding_count,
-            "next_eligible_at": _format_iso_z(decision.next_eligible_at),
-            "hint": hint,
-        }
-        if signpost_findings:
-            payload["signpost_findings"] = signpost_findings
-        print(json.dumps(payload, sort_keys=True, ensure_ascii=False))
-    else:
-        print(_render_doctor_status_line(decision))
-        signpost_warnings = sum(1 for f in signpost_findings if f.get("severity") == "warning")
-        if signpost_warnings:
-            warn(
-                f"Signpost advisory: {signpost_warnings} local layout / npm-migration "
-                "note(s) above (throttle-skipped full probe)."
-            )
-    return 1 if decision.dirty else 0
-
-
-def _persist_doctor_state(
-    project_root: Path,
-    *,
-    exit_code: int,
-    findings: list[dict],
-) -> None:
-    """Best-effort write of doctor-state.json after a full check (#1308).
-
-    ``last_finding_count`` is persisted as the count of findings that
-    *mattered* -- ``severity == "skip"`` findings (e.g. the AGENTS.md
-    freshness check's "no managed-section markers (likely maintainer
-    repo)" skip) are EXCLUDED (#1316). Counting a skip would make
-    ``_render_doctor_status_line`` over-report warnings by one on a
-    dirty throttle-skip, because it derives the warning tally as
-    ``last_finding_count - last_error_count`` and a skip carries no
-    error/warning weight. See ``scripts/_doctor_state.py`` for the
-    persisted-schema contract.
-    """
-    mod = _load_doctor_state_module()
-    if mod is None:
-        return
-    try:
-        mod.write_state(
-            project_root,
-            exit_code=int(exit_code),
-            finding_count=sum(
-                1 for f in findings if f.get("severity") != "skip"
-            ),
-            error_count=sum(1 for f in findings if f.get("severity") == "error"),
-        )
-    except Exception:  # noqa: BLE001 -- state write MUST NOT break doctor
-        return
-
-
-def _run_install_integrity_checks(
-    project_root: Path,
-    *,
-    emit_success,
-    emit_warn,
-    emit_error,
-    emit_info,
-    add_finding,
-) -> None:
-    """Install-integrity checks (ex-framework_doctor.py) folded into
-    canonical doctor (#1308, #1336 retirement).
-    """
-    if _running_inside_deft_repo(project_root):
-        emit_info(
-            "Skipping install-integrity checks -- running inside the deft "
-            "framework repo (no install manifest in the source checkout)."
-        )
-        return
-    try:
-        # Direct call to the local (ported) implementation -- no self-import
-        # hack, no path munging. The four checks now run for real.
-        result = run_checks(project_root)
-    except Exception as exc:  # noqa: BLE001 -- probe failure is a warning
-        message = f"Install-integrity probe unavailable: {type(exc).__name__}: {exc}"
-        emit_warn(message)
-        add_finding("warning", message, check="install-integrity")
-        return
-    for entry in result.get("checks", []) or []:
-        name = entry.get("name", "install-integrity")
-        status = entry.get("status", "")
-        detail = entry.get("detail", "")
-        if status == "pass":
-            emit_success(f"{name}: pass")
-            continue
-        if status == "skip":
-            emit_info(f"{name}: skip -- {detail}")
-            continue
-        if name in ("legacy-layout", "canonical-vendored-npm-signpost") and status == "fail":
-            emit_warn(f"{name}: {detail}")
-            add_finding(
-                "warning",
-                detail or f"{name} {status}",
-                check=f"install-integrity:{name}",
-                install_check=name,
-                status=status,
-                data=entry.get("data", {}),
-            )
-            continue
-        if status == "error":
-            emit_error(f"{name}: error -- {detail}")
-        else:
-            emit_error(f"{name}: fail -- {detail}")
-        add_finding(
-            "error",
-            detail or f"{name} {status}",
-            check=f"install-integrity:{name}",
-            install_check=name,
-            status=status,
-            data=entry.get("data", {}),
-        )
-
-
-def _has_v3_managed_marker(project_root: Path) -> bool:
-    """True iff AGENTS.md carries a deft:managed-section v3 marker (#1308)."""
-    agents_md = project_root / "AGENTS.md"
-    if not agents_md.is_file():
-        return False
-    try:
-        text = agents_md.read_text(encoding="utf-8", errors="replace")
-    except OSError:
-        return False
-    return re.search(
-        r"<!--\s*deft:managed-section\s+v3(?:\s+[^>]*?)?\s*-->",
-        text,
-    ) is not None
-
-
-def _run_agents_md_freshness_check(
-    project_root: Path,
-    *,
-    emit_success,
-    emit_warn,
-    emit_info,
-    add_finding,
-) -> None:
-    """Probe AGENTS.md managed-section freshness via cmd_agents_refresh internals (#1308)."""
-    check_name = "agents-md-managed-section-fresh"
-    if _running_inside_deft_repo(project_root) or not _has_v3_managed_marker(
-        project_root
-    ):
-        skip_reason = "no managed-section markers (likely maintainer repo)"
-        emit_info(f"{check_name}: skip -- {skip_reason}")
-        add_finding(
-            "skip",
-            skip_reason,
-            check=check_name,
-            status="skip",
-        )
-        return
-    try:
-        plan = _agents_refresh_plan(project_root)
-    except Exception as exc:  # noqa: BLE001 -- never break doctor
-        message = f"{check_name}: probe failed -- {type(exc).__name__}: {exc}"
-        emit_warn(message)
-        add_finding("warning", message, check=check_name)
-        return
-    state = plan.get("state", "")
-    if state == "current":
-        emit_success(f"{check_name}: current")
-        return
-    if state in ("stale", "missing", "absent"):
-        message = (
-            f"AGENTS.md managed section is {state} -- "
-            "run `deft agents:refresh` to bring it to the current template."
-        )
-        emit_warn(message)
-        add_finding(
-            "warning",
-            message,
-            check=check_name,
-            status=state,
-            suggestion="deft agents:refresh",
-        )
-        return
-    message = (
-        f"AGENTS.md freshness check could not run (state={state!r}). "
-        "Inspect the framework template or AGENTS.md file permissions."
-    )
-    emit_warn(message)
-    add_finding("warning", message, check=check_name, status=state)
-
-
-def _parse_semver(version: str) -> tuple[int, ...]:
-    normalized = version.strip().lstrip("vV")
-    parts: list[int] = []
-    for segment in normalized.split("."):
-        try:
-            parts.append(int(segment.split("-")[0]))
-        except ValueError:
-            break
-    return tuple(parts) if parts else (0,)
-
-
-def _semver_less_than(left: str, right: str) -> bool:
-    return _parse_semver(left) < _parse_semver(right)
-
-
-def _npm_view_version() -> tuple[bool, str]:
-    try:
-        proc = subprocess.run(
-            ["npm", "view", NPM_PACKAGE_NAME, "version"],
-            capture_output=True,
-            text=True,
-            timeout=15,
-        )
-    except Exception:  # noqa: BLE001
-        return False, ""
-    version = (proc.stdout or "").strip().splitlines()[0].strip() if proc.stdout else ""
-    return proc.returncode == 0 and bool(version), version
-
-
-def _manifest_version(ref: str, tag: str) -> str:
-    candidate = (tag or ref).strip().replace("refs/tags/", "")
-    normalized = candidate.lstrip("vV")
-    if not re.match(r"^\d+(?:\.\d+)*", normalized):
-        return ""
-    return normalized
-
-
-def _run_payload_staleness_check(
-    project_root: Path,
-    *,
-    emit_warn,
-    emit_info,
-    add_finding,
-) -> None:
-    """#1339 / #2003 / #2004: payload staleness with npm canonical upgrade path."""
-    check_name = "payload-staleness"
-    try:
-        agents = project_root / "AGENTS.md"
-        is_deft = agents.exists() and (
-            "Deft — Development Framework (deft repo)" in
-            agents.read_text(encoding="utf-8", errors="ignore")
-        )
-        if is_deft:
-            emit_info(f"{check_name}: skip -- running inside deft framework repo")
-            add_finding(
-                "skip", "inside framework repo (no install manifest)",
-                check=check_name, status="skip", reason="not-applicable",
-            )
-            return
-    except Exception:
-        pass
-
-    manifest_path = None
-    try:
-        candidate = get_script_dir().parent / "VERSION"
-        if candidate.exists():
-            manifest_path = candidate
-    except Exception:
-        pass
-    if manifest_path is None:
-        manifest_path = _locate_manifest(project_root, None)
-    if manifest_path is None:
-        legacy_marker = project_root / ".deft-version"
-        if legacy_marker.exists():
-            manifest_path = legacy_marker
-    if manifest_path is None or not manifest_path.exists():
-        emit_info(f"{check_name}: skip -- no install manifest found (pre-v0.28 or legacy state)")
-        add_finding("skip", "no manifest", check=check_name, status="skip", reason="not-applicable")
-        return
-
-    try:
-        text = manifest_path.read_text(encoding="utf-8", errors="replace")
-        manifest = _parse_install_manifest(text)
-    except Exception as exc:  # noqa: BLE001
-        emit_info(f"{check_name}: skip -- could not read manifest: {exc}")
-        add_finding(
-            "skip",
-            f"manifest unreadable: {exc}",
-            check=check_name,
-            status="skip",
-            reason="not-applicable",
-        )
-        return
-
-    installed_sha = manifest.get("sha", "").strip()
-    ref = (manifest.get("ref") or manifest.get("tag") or "").strip()
-    tag = (manifest.get("tag") or "").strip()
-    if not installed_sha:
-        emit_info(f"{check_name}: skip -- manifest has no sha (incomplete provenance)")
-        add_finding(
-            "skip",
-            "no sha in manifest",
-            check=check_name,
-            status="skip",
-            reason="not-applicable",
-        )
-        return
-    if not ref:
-        emit_info(
-            f"{check_name}: skip -- manifest has no ref or tag (cannot resolve remote sha)"
-        )
-        add_finding(
-            "skip",
-            "no ref/tag in manifest",
-            check=check_name,
-            status="skip",
-            reason="not-applicable",
-        )
-        return
-
-    deft_dir = manifest_path.parent
-    ls_remote_ok = False
-    remote_sha = ""
-    try:
-        proc = subprocess.run(
-            ["git", "-C", str(deft_dir), "ls-remote", "origin", ref],
-            capture_output=True,
-            text=True,
-            timeout=15,
-        )
-        ls_remote_ok = proc.returncode == 0
-        if ls_remote_ok:
-            peeled_sha = ""
-            for line in proc.stdout.splitlines():
-                parts = line.strip().split()
-                if len(parts) >= 2:
-                    refname = parts[1]
-                    if refname.endswith("^{}"):
-                        peeled_sha = parts[0]
-                    elif not remote_sha:
-                        remote_sha = parts[0]
-            if peeled_sha:
-                remote_sha = peeled_sha
-            elif not remote_sha:
-                first_line = next((ln for ln in proc.stdout.splitlines() if ln.strip()), "")
-                parts = first_line.strip().split()
-                if parts:
-                    remote_sha = parts[0]
-    except Exception:  # noqa: BLE001
-        ls_remote_ok = False
-
-    if ls_remote_ok and remote_sha:
-        if installed_sha == remote_sha:
-            emit_info(f"{check_name}: current (sha matches remote)")
-            return
-        msg = (
-            f"Framework payload is stale (installed sha {installed_sha[:8]}... "
-            f"behind remote {remote_sha[:8]}... for ref '{ref}'). "
-            f"Recommendation: run `{CANONICAL_UPGRADE_COMMAND}` from any shell with Node ≥ 20."
-        )
-        emit_warn(msg)
-        add_finding(
-            "warning",
-            msg,
-            check=check_name,
-            status="stale",
-            installed_sha=installed_sha,
-            remote_sha=remote_sha,
-            ref=ref,
-            suggestion=CANONICAL_UPGRADE_COMMAND,
-            resolver="git-ls-remote",
-        )
-        return
-
-    npm_ok, npm_version = _npm_view_version()
-    installed_version = _manifest_version(ref, tag)
-    if npm_ok and installed_version:
-        if _semver_less_than(installed_version, npm_version):
-            msg = (
-                f"Framework payload is stale (installed v{installed_version} "
-                f"behind npm registry v{npm_version} for ref '{ref}'). "
-                f"Recommendation: run `{CANONICAL_UPGRADE_COMMAND}` from any shell with Node ≥ 20."
-            )
-            emit_warn(msg)
-            add_finding(
-                "warning",
-                msg,
-                check=check_name,
-                status="stale",
-                installed_version=installed_version,
-                remote_version=npm_version,
-                ref=ref,
-                suggestion=CANONICAL_UPGRADE_COMMAND,
-                resolver="npm-view",
-            )
-            return
-        emit_info(f"{check_name}: current (version matches npm registry)")
-        return
-
-    reason = (
-        "ls-remote produced no sha and npm registry fallback unavailable"
-        if ls_remote_ok
-        else "could not reach remote (git ls-remote / npm view both unavailable)"
-    )
-    emit_info(f"{check_name}: skip -- {reason}")
-    unverified_msg = f"payload currency UNVERIFIED — {reason}"
-    emit_warn(unverified_msg)
-    add_finding(
-        "warning",
-        unverified_msg,
-        check=check_name,
-        status="unverified",
-        reason=reason,
-    )
-
-
-def _parse_install_manifest(text: str) -> dict:
-    """Tiny tolerant parser for the single-key: 'value' YAML shape used by the
-    install manifest (#1062). Mirrors the shape expected by run::_parse_install_manifest
-    but kept local here so scripts/doctor.py stays self-contained for the handoff.
-    """
-    data: dict[str, str] = {}
-    for line in text.splitlines():
-        line = line.strip()
-        if not line or ":" not in line:
-            continue
-        k, v = [x.strip() for x in line.split(":", 1)]
-        v = v.strip().strip("'\"")
-        data[k] = v
-    return data
-
-def cmd_doctor(args: list[str]):
-    """Thin shim (#1335) -- core doctor logic now owned by scripts/doctor.py.
-
-    This entry point (and therefore `task doctor`) is a thin delegation layer.
-    The implementation, modes (--session, reporting, --json, --fix, --quiet,
-    --full, --project-root), throttle, and checks live in scripts/doctor.py
-    (the single owner per Epic-1). During the carve transition the bodies
-    remain in this file for stability; scripts/doctor.py is the documented
-    import surface and will receive the logic in follow-on increments.
-
-    See scripts/doctor.py header + vbrief/active/*1335*.vbrief.json .
-    """
-
-    # Real implementation body follows (transition). After full extraction
-    # this will be a 4-line import + call to scripts.doctor.cmd_doctor.
-    # The body below is the current home (being migrated).
-    """Canonical doctor surface for task-surface health (#1272, #1303 review).
-
-    Diagnoses (and optionally repairs, with explicit consent):
-
-    1. Required tools on PATH (uv, git) and optional tools (task,
-       python3, go, node) -- the existing #792 dependency probe.
-    2. Expected framework directory layout (#792).
-    3. Consumer root Taskfile.yml include health (#1272). When run
-       inside a consumer project, doctor detects:
-         * missing root Taskfile.yml          -> diagnose + print snippet;
-                                                 interactive ``--fix``
-                                                 may CREATE the file after
-                                                 explicit operator consent.
-         * root Taskfile.yml exists, no       -> diagnose + print snippet;
-           deft include                          NEVER mutates the existing
-                                                 user-owned Taskfile.
-         * include present                    -> OK.
-
-    Flags (parsed via :func:`_parse_doctor_flags`):
-        ``--session``       diagnose-only, session-safe; no prompt, no
-                            mutation.
-        ``--fix``           interactive repair offered when actionable
-                            (Taskfile creation only); ignored under
-                            ``--session``.
-        ``--json``          emit a single JSON object on stdout and
-                            suppress the human-readable prose; exit
-                            code unchanged.
-        ``--quiet``         suppress per-check success lines; errors
-                            and warnings still surface.
-        ``--project-root``  override the project root used for the
-                            Taskfile diagnostic. Defaults to
-                            :func:`Path.cwd`.
-
-    Returns:
-        ``0`` on a clean check OR a warning-only check (warnings are
-        informational and never exit-failing).
-        ``1`` on a hard error (missing required tool OR Taskfile drift
-        detected).
-        ``2`` on argument-parse failure (an unknown flag was passed --
-        the doctor refuses to run the diagnostics so the typo cannot
-        masquerade as a clean check).
-
-    Non-zero return is informational -- doctor's role is to surface
-    the failure, not to block the upgrade gate.
-
-    Throttle-state count semantics (#1316): when a full run completes,
-    ``_persist_doctor_state`` writes ``last_finding_count`` as the count
-    of findings that *mattered* -- ``severity == "skip"`` findings are
-    EXCLUDED. A skip (e.g. the AGENTS.md freshness check reporting "no
-    managed-section markers (likely maintainer repo)") is neither an
-    error nor a warning, so counting it would make the next throttle-skip
-    status line over-report warnings by one (the line derives warnings as
-    ``last_finding_count - last_error_count``). The in-run ``--json``
-    ``summary`` block already counts only ``error`` / ``warning``
-    findings, so this keeps the persisted tally consistent with it.
-    """
-    flags = _parse_doctor_flags(args)
-
-    # Reject unknown flags loudly. The previous shape silently swallowed
-    # typos (`--repare` instead of `--repair`), so an operator who
-    # mistyped never realised they had not opted into repair -- the
-    # diagnostic still ran in default mode and the prose suggested the
-    # repair was offered. Surface the unknown tokens, list the allowed
-    # set, and exit 2 so CI wrappers can distinguish a malformed
-    # invocation from a real diagnostic failure (#1303 review #3).
-    if flags.get("unknown"):
-        error(
-            "Unknown flag(s): "
-            + ", ".join(flags["unknown"])
-        )
-        info(
-            "Allowed: " + ", ".join(_DOCTOR_ALLOWED_FLAGS)
-        )
-        return 2
-
-    session_mode = flags["session"]
-    fix_mode = flags["fix"] and not session_mode
-    json_mode = flags["json"]
-    quiet_mode = flags["quiet"]
-    full_mode = flags["full"]
-
-    # ``--project-root`` lets operators invoke doctor against an
-    # arbitrary directory rather than ``Path.cwd``. Defaults to the
-    # current working directory so existing callers (``task doctor``,
-    # the ``run doctor`` CLI without overrides) are unaffected. The
-    # path is normalised through :func:`resolve_path` so ``~`` and
-    # relative paths work (#1303 review #5).
-    project_root_arg = flags.get("project_root")
-    project_root = (
-        resolve_path(project_root_arg) if project_root_arg else Path.cwd()
-    )
-
-    # #1308: throttle gate. Default = full check, but a recent run
-    # within the 24h-clean / 4h-dirty window short-circuits to a
-    # one-line status surface. ``--full`` bypasses the throttle. The
-    # ritual halts on a dirty-within-window state (exit 1) so a
-    # persistent-dirty install is never silently ignored.
-    if not full_mode:
-        decision = _evaluate_doctor_throttle(project_root)
-        if decision is not None and decision.skip:
-            return _emit_doctor_throttle_skip(
-                decision, json_mode=json_mode, project_root=project_root
-            )
-
-    # Findings are the single source of truth for the summary, the
-    # JSON payload, and the exit code (#1303 review #1 / #4). Replaces
-    # the prior ``errors += 1`` / ``errors -= 1`` accounting pair that
-    # was brittle when the interactive ``--fix`` path repaired a
-    # missing-file finding -- the decrement coupled two unrelated
-    # branches and made the summary easy to mis-read.
-    findings: list[dict] = []
-
-    def _add_finding(severity: str, message: str, **extras: object) -> None:
-        entry: dict = {"severity": severity, "message": message}
-        entry.update(extras)
-        findings.append(entry)
-
-    def _emit_info(msg: str) -> None:
-        if not json_mode:
-            info(msg)
-
-    def _emit_success(msg: str) -> None:
-        if json_mode or quiet_mode:
-            return
-        success(msg)
-
-    def _emit_warn(msg: str) -> None:
-        if not json_mode:
-            warn(msg)
-
-    def _emit_error(msg: str) -> None:
-        if not json_mode:
-            error(msg)
-
-    if not json_mode:
-        print_header(f"Deft CLI v{VERSION} - Doctor")
-        print()
-    _emit_info("Checking system dependencies...")
-    if not json_mode:
-        print()
-
-    # Check for required tools.  Errors and warnings are tracked
-    # separately (#792) so a missing required tool surfaces above
-    # optional-tool warnings in the summary and forces a non-zero
-    # return code.
-    def check_command(cmd: str, name: str, required: bool = False,
-                       install_url: str = ""):
-        if shutil.which(cmd):
-            _emit_success(f"{name} is installed")
-            return
-        url_hint = f" - install: {install_url}" if install_url else ""
-        if required:
-            message = f"{name} not found - required{url_hint}"
-            _emit_error(message)
-            _add_finding(
-                "error",
-                message,
-                check="dependency",
-                tool=cmd,
-                suggestion=install_url or None,
-            )
-            return
-        if cmd == "task":
-            message = f"{name} not found - install from https://taskfile.dev"
-        else:
-            message = f"{name} not found{url_hint}"
-        _emit_warn(message)
-        _add_finding(
-            "warning",
-            message,
-            check="dependency",
-            tool=cmd,
-            suggestion=install_url or None,
-        )
-
-    # uv is required: every deft task script invokes `uv run python ...`,
-    # so a green doctor on a machine without uv would mask an adoption
-    # blocker (#792).  Surface it before optional tools so the error is
-    # the first thing a fresh-machine user sees.
-    check_command(
-        "uv",
-        "uv (Astral Python runner)",
-        required=True,
-        install_url=UV_INSTALL_URL,
-    )
-    check_command("git", "git", required=True)
-    check_command("python3", "python3")
-    check_command("go", "go")
-    check_command("node", "node")
-
-    # #1308 / #1336: install-integrity checks now owned by scripts/doctor.py
-    # (the four checks formerly in framework_doctor.py). cmd_doctor folds
-    # them under ``install-integrity:<name>`` keys. Skipped in the deft
-    # maintainer repo (no install manifest in the source checkout).
-    if not json_mode:
-        print()
-    _emit_info("Checking install integrity...")
-    _run_install_integrity_checks(
-        project_root,
-        emit_success=_emit_success,
-        emit_warn=_emit_warn,
-        emit_error=_emit_error,
-        emit_info=_emit_info,
-        add_finding=_add_finding,
-    )
-
-    # #1308: AGENTS.md managed-section freshness. Reuses the
-    # cmd_agents_refresh --check byte-compare via _agents_refresh_plan;
-    # emits a skip finding with reason "no managed-section markers
-    # (likely maintainer repo)" when AGENTS.md carries no v3 markers.
-    # Stale templates surface as a warning (zero exit) -- the operator
-    # runs `deft agents:refresh` to bring them current.
-    if not json_mode:
-        print()
-    _emit_info("Checking AGENTS.md managed-section freshness...")
-    _run_agents_md_freshness_check(
-        project_root,
-        emit_success=_emit_success,
-        emit_warn=_emit_warn,
-        emit_info=_emit_info,
-        add_finding=_add_finding,
-    )
-
-    # #1339 (Epic-5): payload staleness from the install manifest. Runs after
-    # AGENTS freshness so the handoff from installer always surfaces a clear
-    # "re-run the installer" recommendation when the cloned payload sha lags
-    # the remote (deterministic, works in --session --json mode for agents).
-    if not json_mode:
-        print()
-    _emit_info("Checking payload staleness from install manifest...")
-    _run_payload_staleness_check(
-        project_root,
-        emit_warn=_emit_warn,
-        emit_info=_emit_info,
-        add_finding=_add_finding,
-    )
-
-    # Check directory structure.  Updated to the v0.20+ canonical
-    # layout (#792); pre-v0.20 entries (core, interfaces, tools, swarm,
-    # meta) were dropped because they no longer reflect the framework's
-    # current top-level layout and produced spurious 'Missing directory'
-    # warnings on every clean checkout.  Cross-referenced with
-    # `skills/deft-directive-setup/SKILL.md` § Environment Preflight
-    # (vbrief lifecycle requirement) and the project tree on master.
-    if not json_mode:
-        print()
-    _emit_info("Checking Deft structure...")
-
-    # Use .parent so the check anchors at the framework root (the directory
-    # containing scripts/doctor.py), restoring the pre-extraction semantics
-    # from run.get_script_dir() (which returned repo root in source layout).
-    # This eliminates the false-positive "Missing directory" warnings for all
-    # seven canonical framework subdirectories on every `run doctor` / `task doctor`
-    # invocation (Greptile framework-layout issue on 7a0606c).
-    framework_root = get_script_dir().parent
-    # Post-#1875 content/ move: shippable content dirs live under content/ in
-    # the SOURCE repo and are flattened back to the framework root in a CONSUMER
-    # deposit (C1). ``content_root`` resolves both contexts; engine/lifecycle
-    # dirs (tasks/, scripts/, vbrief/) always stay at the framework root.
-    scripts_dir = get_script_dir()
-    if str(scripts_dir) not in sys.path:
-        sys.path.insert(0, str(scripts_dir))
-    from _content_root import content_root  # noqa: PLC0415
-
-    content_base = content_root(framework_root)
-    expected_dirs = [
-        ("languages", content_base),
-        ("strategies", content_base),
-        ("skills", content_base),
-        ("templates", content_base),
-        ("tasks", framework_root),
-        ("scripts", framework_root),
-        ("vbrief", framework_root),
-    ]
-
-    for dir_name, base in expected_dirs:
-        dir_path = base / dir_name
-        if dir_path.is_dir():
-            _emit_success(f"Directory: {dir_name}/")
-        else:
-            message = f"Missing directory: {dir_name}/"
-            _emit_warn(message)
-            _add_finding(
-                "warning",
-                message,
-                check="framework-layout",
-                directory=dir_name,
-            )
-
-    # #1272 root Taskfile.yml include health. Skip when invoked from
-    # inside the deft framework repo itself -- the deft repo's own
-    # Taskfile.yml is the source of truth for its surface and does not
-    # need (and must not declare) a `deft:` include to itself.
-    if not json_mode:
-        print()
-    _emit_info("Checking optional root Taskfile.yml include...")
-    if _running_inside_deft_repo(project_root):
-        _emit_info(
-            "Skipping Taskfile include check -- running inside the deft "
-            "framework repo (the repo's own Taskfile.yml is the surface)."
-        )
-    else:
-        # ``include_missing`` is True until a successful interactive
-        # repair flips it off. Replaces the prior ``errors -= 1``
-        # gymnastic on the missing-file branch (#1303 review #1).
-        include_status = _classify_taskfile_include(project_root)
-        if include_status == "ok":
-            _emit_success("Root Taskfile.yml includes the deft framework")
-        elif include_status == "missing-file":
-            include_missing = True
-            target = project_root / "Taskfile.yml"
-            message = (
-                "Root Taskfile.yml missing. This is OK for package-manager "
-                "installs that use the `deft X` surface directly. To also "
-                f"enable the optional `task deft:X` surface, paste this into {target}:"
-            )
-            _emit_info(message)
-            if not json_mode:
-                print()
-                print(_TASKFILE_INCLUDE_SNIPPET)
-            # Interactive repair path. All gates MUST hold before any
-            # write: (1) --fix was requested AND we are not under
-            # --session (both folded into ``fix_mode`` -- see
-            # ``fix_mode = flags["fix"] and not session_mode`` above);
-            # (2) stdin is a TTY (so we can prompt); (3) we are not
-            # emitting JSON (JSON mode is diagnose-only). Even then,
-            # the operator must explicitly approve at the prompt.
-            # #1303 pass-3 review (Greptile run:4664-4669 -- redundant
-            # session_mode guard): the prior shape repeated
-            # ``and not session_mode`` here, but fix_mode already
-            # incorporates that condition; the duplicate gate could
-            # never change the outcome and invited confusion.
-            if (
-                fix_mode
-                and not json_mode
-                and sys.stdin.isatty()
-            ):
-                if read_yn(
-                    f"Create {target} with the canonical include now?",
-                    default=False,
-                ):
-                    try:
-                        # ``newline="\n"`` enforces LF line endings on
-                        # every host -- ``write_text`` otherwise honours
-                        # the platform default, which produces CRLF on
-                        # Windows and breaks the byte-equality contract
-                        # tests rely on (#1303 review #6).
-                        target.write_text(
-                            _TASKFILE_INCLUDE_SNIPPET,
-                            encoding="utf-8",
-                            newline="\n",
-                        )
-                        _emit_success(f"Wrote {target}")
-                        # The drift was just repaired -- flip the
-                        # boolean so the summary reflects the
-                        # post-repair state (replaces the prior
-                        # ``errors -= 1`` decrement pair).
-                        include_missing = False
-                    except OSError as exc:
-                        _emit_error(f"Failed to write {target}: {exc}")
-                else:
-                    _emit_info(
-                        "Skipped Taskfile.yml creation -- paste the "
-                        "snippet above when you are ready."
-                    )
-            if include_missing:
-                _add_finding(
-                    "warning",
-                    "Root Taskfile.yml missing; optional Taskfile include unavailable",
-                    check="taskfile-include",
-                    file=str(target),
-                    suggestion=_TASKFILE_INCLUDE_SNIPPET,
-                )
-        elif include_status == "missing-include":
-            message = (
-                "Root Taskfile.yml exists but does not include the deft "
-                "framework. The `deft X` surface still works; add this to "
-                "the Taskfile `includes:` block only if you want the optional "
-                "`task deft:X` surface (doctor NEVER mutates an existing "
-                "user-owned Taskfile):"
-            )
-            _emit_warn(message)
-            if not json_mode:
-                print()
-                print(_format_missing_include_snippet())
-            taskfile_path = _resolve_consumer_taskfile(project_root)
-            _add_finding(
-                "warning",
-                "Root Taskfile.yml does not include the deft framework",
-                check="taskfile-include",
-                file=str(taskfile_path) if taskfile_path else None,
-                suggestion=_format_missing_include_snippet(),
-            )
-        elif include_status == "unreadable":
-            # Resolve the actual Taskfile path so a consumer who chose the
-            # ``.yaml`` spelling sees the right file name in the error
-            # message and in the JSON `file` field (#1303 review,
-            # Greptile #2). Falls back to ``Taskfile.yml`` only if the
-            # resolver returns None -- which shouldn't happen here
-            # because the `unreadable` branch is only reached when a
-            # candidate file was found, but the fallback keeps the
-            # diagnostic informative under any future code drift.
-            taskfile_path = (
-                _resolve_consumer_taskfile(project_root)
-                or (project_root / "Taskfile.yml")
-            )
-            message = (
-                f"Root Taskfile.yml at {taskfile_path} "
-                "exists but could not be read -- check file permissions."
-            )
-            _emit_warn(message)
-            _add_finding(
-                "warning",
-                message,
-                check="taskfile-include",
-                file=str(taskfile_path),
-            )
-
-    error_count = sum(1 for f in findings if f["severity"] == "error")
-    warning_count = sum(1 for f in findings if f["severity"] == "warning")
-    exit_code = 1 if error_count else 0
-
-    # #1308: persist doctor-state.json so the next invocation can
-    # consult the throttle gate. Best-effort -- a write failure is
-    # silently swallowed by the state module so the doctor itself
-    # never breaks because of a state-file bug.
-    _persist_doctor_state(
-        project_root,
-        exit_code=exit_code,
-        findings=findings,
-    )
-
-    if json_mode:
-        payload = {
-            "status": "completed",
-            "ok": exit_code == 0,
-            "findings": findings,
-            "summary": {
-                "errors": error_count,
-                "warnings": warning_count,
-            },
-            "project_root": str(project_root),
-        }
-        print(json.dumps(payload, sort_keys=True, ensure_ascii=False))
-        return exit_code
-
-    print()
-    if error_count == 0 and warning_count == 0:
-        success("System check passed!")
-        return 0
-    if error_count:
-        # Errors first so missing-uv (or git) is not buried under
-        # optional-tool warnings.
-        error(
-            f"System check failed with {error_count} error(s)"
-            + (f" and {warning_count} warning(s)" if warning_count else "")
-            + "."
-        )
-        return 1
-    warn(f"System check completed with {warning_count} warning(s).")
-    return 0
-
-# (end of extracted region; now maintained in this file)
-# End of block extracted to scripts/doctor.py (see START marker above).
-# The thin shim below this point in the final state will replace the
-# extracted region.
-# ===
-# --- End of extracted doctor logic (Epic-1 #1335) ---
-
-# --- Ported CLI surface (main, _build_parser, _format_text_report) from
-# retired framework_doctor.py to satisfy test expectations for fd.main(),
-# UTF-8 reconfigure (#814), --json/--quiet/--project-root, and the 3-state
-# exit codes. The primary user surface remains cmd_doctor (new extraction).
-# ---
-
-
-def _build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(
-        prog="framework_doctor.py",
-        description=(
-            "Local install-integrity probe (#1046 PR-B AC-3). Four checks: "
-            "QUICK-START resolves, skill paths resolve, manifest agreement, "
-            "install-path consistency. Three-state exit: 0 clean / 1 drift "
-            "detected / 2 config error."
-        ),
-    )
-    parser.add_argument(
-        "--project-root",
-        default=".",
-        help="Project root path (default: current working directory).",
-    )
-    parser.add_argument(
-        "--json",
-        action="store_true",
-        help="Emit a single JSON object on stdout instead of human-readable text.",
-    )
-    parser.add_argument(
-        "--quiet",
-        action="store_true",
-        help="Suppress the success summary; failure detail still prints.",
-    )
-    return parser
-
-
-def _format_text_report(result: DoctorResult) -> str:
-    """Render a human-readable summary of the doctor result."""
-    lines: list[str] = []
-    if result.exit_code == EXIT_CLEAN:
-        lines.append(
-            "\u2713 deft framework:doctor -- all checks pass "
-            f"(install_root={result.install_root!r})."
-        )
-    elif result.exit_code == EXIT_DRIFT:
-        lines.append(
-            "\u26a0 deft framework:doctor -- drift detected "
-            f"(install_root={result.install_root!r})."
-        )
-    else:
-        lines.append("\u2717 deft framework:doctor -- config error.")
-    for c in result.checks:
-        if c.status == "pass":
-            sym = "\u2713"
-        elif c.status == "skip":
-            sym = "\u2022"
-        elif c.status == "fail":
-            sym = "\u2717"
-        else:  # error
-            sym = "!"
-        lines.append(f"  {sym} {c.name}: {c.detail}")
-    for err in result.errors:
-        lines.append(f"  ! {err}")
-    return "\n".join(lines)
-
-
-def main(argv: list[str] | None = None) -> int:
-    # #814: Force UTF-8 stdout/stderr at script entry. Windows Python
-    # defaults stdout/stderr to cp1252 when invoked under git hooks,
-    # which has no glyph for the U+2713 success marker. Without this
-    # reconfigure the doctor crashes with UnicodeEncodeError on the
-    # success summary. Guarded by hasattr because reconfigure only
-    # exists on TextIOWrapper streams. errors='replace' is a
-    # belt-and-suspenders fallback for the rare environment that still
-    # cannot render UTF-8.
-    if hasattr(sys.stdout, "reconfigure"):
-        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
-    if hasattr(sys.stderr, "reconfigure"):
-        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
-
-    parser = _build_parser()
-    args = parser.parse_args(argv)
-    project_root = Path(args.project_root).resolve()
-    result = _run_checks_impl(project_root)
-    if args.json:
-        print(json.dumps(result.to_dict(), sort_keys=True, ensure_ascii=False))
-    else:
-        if not (args.quiet and result.exit_code == EXIT_CLEAN):
-            print(_format_text_report(result))
-    return result.exit_code
-
-
-if __name__ == "__main__":
-    # python -m scripts.doctor [args] or direct python scripts/doctor.py [args]
-    args = sys.argv[1:]
-    if args and args[0].lower() == 'doctor':
-        args = args[1:]
-    sys.exit(cmd_doctor(args))