@deftai/directive-content 0.59.0 → 0.61.0

package/tasks/project.yml

@@ -9,6 +9,12 @@ vars:
 # own repo root when invoked via ``includes:`` -- consumers got their data
 # scanned from ``deft/vbrief/``. Switched to ``{{.USER_WORKING_DIR}}`` to
 # match the convention used by roadmap:render / spec:render / migrate:vbrief.
+#
+# Staleness acknowledgement (#640): ``task project:ack-staleness`` records a
+# completed-scope watermark on PROJECT-DEFINITION ``plan.metadata.staleness_review``
+# so ``task project:render`` stops re-emitting the same narrative staleness flags
+# after review. This is distinct from ``task reconcile:issues``, which reconciles
+# origin freshness on scope vBRIEFs — not PROJECT-DEFINITION narrative heuristics.
 
 tasks:
   _ts-build:
@@ -25,3 +31,23 @@ tasks:
       - _ts-build
     cmds:
       - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" project-render "{{.USER_WORKING_DIR}}/vbrief"
+
+  ack-staleness:
+    desc: >-
+      Acknowledge reviewed PROJECT-DEFINITION narrative staleness (#640).
+      Distinct from task reconcile:issues (scope origin freshness).
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - _ts-build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" project-render --acknowledge-staleness "{{.USER_WORKING_DIR}}/vbrief"
+
+  export-spec:
+    desc: >-
+      Export SPECIFICATION.md from PROJECT-DEFINITION (+ lifecycle scopes).
+      Use --audience=internal to include proposed scopes (#2013 / #1502).
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - _ts-build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" export-spec {{.CLI_ARGS}}

package/tasks/toolchain.yml

@@ -5,9 +5,19 @@ vars:
 
 tasks:
   check:
-    desc: Verify required toolchain is installed (go, uv, git, gh, node, pnpm)
-    deps: [":ts:build"]
-    env:
-      PYTHONUTF8: "1"
+    desc: Verify required maintainer toolchain is installed (go, uv, git, gh, node, pnpm)
+    deps:
+      - task: :engine:_ts-build
     cmds:
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" toolchain:check
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'toolchain-check'
+
+  check-consumer:
+    desc: Verify required consumer toolchain is installed (git, gh, node, pnpm, task) without Python/go/uv (#2022 Phase 3).
+    deps:
+      - task: :engine:_ts-build
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'toolchain-check --consumer'

package/tasks/vbrief.yml

@@ -15,10 +15,11 @@ tasks:
     desc: Validate vBRIEF lifecycle folder structure and cross-file consistency
     dir: '{{.USER_WORKING_DIR}}'
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     cmds:
-      # Oracle/fallback (parity): scripts/vbrief_validate.py (#1828 Wave 8).
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" vbrief:validate --vbrief-dir "{{.USER_WORKING_DIR}}/vbrief"
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'vbrief:validate --vbrief-dir "{{.USER_WORKING_DIR}}/vbrief"'
 
   preflight:
     # Implementation-intent preflight wrapper (#810 / PR #812 fixup;

package/tasks/verify.yml

@@ -70,15 +70,11 @@ tasks:
     desc: "Detection-bound branch-protection gate (#747). Reads plan.policy.allowDirectCommitsToMaster from PROJECT-DEFINITION."
     dir: '{{.USER_WORKING_DIR}}'
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     cmds:
-      # Oracle/fallback (parity): scripts/preflight_branch.py (#1828 Wave 8).
-      # `--allow-missing-project-definition` keeps the framework's own check
-      # green for fresh checkouts that have not yet run `task setup` (the
-      # bootstrap fallback path documented in #746 acceptance criterion E).
-      # Production projects with PROJECT-DEFINITION present will still get
-      # the full enforcement -- the flag is a no-op when the file exists.
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" verify:branch --project-root "{{.USER_WORKING_DIR}}" --allow-missing-project-definition
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify:branch --project-root "{{.USER_WORKING_DIR}}" --allow-missing-project-definition'
 
   routing:
     desc: "Operator coding sub-agent model routing gate (#1739). Pre-dispatch (default): fails when a dispatched worker role has no decision in .deft/routing.local.json. Pass --advise for the non-blocking session-start disclosure; --roles a,b to widen the gated set; --provider to override the runtime."
@@ -145,7 +141,7 @@ tasks:
     desc: "Pre-`start_agent` cache-freshness gate (#1127). Refuses implementation dispatch when the triage cache is stale, missing, or the target issue's latest decision is not `accept`. Subscription-aware via plan.policy.triageScope[] (D12 / #1131). Flags: --for-issue N / --max-age-hours N / --allow-stale / --repo OWNER/NAME / --allow-missing-bootstrap (consumed by the framework's own `task check` so a fresh checkout passes -- consumers leave it OFF)."
     dir: '{{.USER_WORKING_DIR}}'
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     # Per `conventions/task-caching.md` (#574): NO `sources:` / `generates:`
     # because the gate forwards user-facing flags via {{.CLI_ARGS}}
     # (--for-issue / --max-age-hours / --allow-stale / --repo) that
@@ -155,8 +151,9 @@ tasks:
     # `task triage:bootstrap`; consumer projects leave it off so a
     # missing cache fails their `task check` loudly.
     cmds:
-      # Oracle/fallback (parity): scripts/preflight_cache.py --allow-missing-bootstrap (#1854 s5).
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" preflight-cache --project-root "{{.USER_WORKING_DIR}}" --allow-missing-bootstrap {{.CLI_ARGS}}
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'preflight-cache --project-root "{{.USER_WORKING_DIR}}" --allow-missing-bootstrap {{.CLI_ARGS}}'
 
   codebase-map-fresh:
     desc: "Drift gate for the generated .planning/codebase/MAP.md projection (#1595 PR4)."
@@ -276,7 +273,7 @@ tasks:
     desc: "Pre-merge re-validation that pending/+active/ count is within plan.policy.wipCap (#1124 / D4 of #1119). Catches stale-branch merges + --force overrides. Default cap is 10 per umbrella #1119 Current Shape v3. The framework's own task check passes --allow-over-cap during landing-day overage; consumer projects MUST NOT pass that flag."
     dir: '{{.USER_WORKING_DIR}}'
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     # Per `conventions/task-caching.md` (#574): NO `sources:` /
     # `generates:` because the gate forwards user-facing flags via
     # {{.CLI_ARGS}} (--allow-over-cap / --quiet) that go-task's
@@ -288,5 +285,6 @@ tasks:
     # OFF so a stale-branch / --force-merge over-cap state fails their
     # `task check` loudly.
     cmds:
-      # Oracle/fallback (parity): scripts/preflight_wip_cap.py (#1828 Wave 8).
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" verify:wip-cap --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify:wip-cap --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'

package/templates/agents-entry.md

@@ -134,7 +134,7 @@ Three consumer-facing surfaces enforce the branch-policy contract (#746 / #747):
 
 - `deft check` -- authoritative consumer pre-commit quality gate. In vendored `.deft/core` installs it runs consumer-safe Deft install/lifecycle gates and does NOT run framework source-repo self-tests. Run `deft check:framework-source` only when explicitly validating the vendored framework payload itself (#1519).
 - `deft verify:branch` -- branch gate wired into the `deft check` aggregate; refuses a commit on the default branch unless `plan.policy.allowDirectCommitsToMaster = true` (typed) or `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1` is set.
-- `.githooks/pre-commit` / `pre-push` -- local hooks installed via `deft setup`; verify via `deft verify:hooks-installed`.
+- `.githooks/pre-commit` / `pre-push` -- local hooks installed via `deft setup`; verify via `deft verify:hooks-installed`. After a framework upgrade, run `deft update` to refresh hook templates to the current TS-native `deft verify:*` / `deft preflight-gh` wiring (#2049).
 - `deft policy:show --field=allowDirectCommitsToMaster` -- inspect the resolved policy; `deft policy:allow-direct-commits -- --confirm` writes the typed override with an audit row.
 
 ## Branch Policy Disclosure (#746)

package/scripts/_agents_md.py

@@ -1,494 +0,0 @@
-#!/usr/bin/env python3
-"""scripts/_agents_md.py -- shared AGENTS.md managed-section helpers (#1389).
-
-Single source of truth for the AGENTS.md managed-section parse / render /
-freshness-plan logic. Extracted verbatim from the ``run`` module so BOTH
-``run`` (the CLI entry point) and ``scripts/doctor.py`` (the canonical
-doctor) can import the same implementation instead of duplicating it.
-
-Why this module exists
-----------------------
-After the Epic-1 doctor carve (#1335 / #1336) ``scripts/doctor.py`` became
-the owner of doctor core logic, but the AGENTS.md managed-section helpers it
-needs to compute a freshness verdict still lived in ``run``. The doctor
-module could not import them cleanly (``run`` has heavy import-time side
-effects -- rich / prompt_toolkit / textual probes), so
-``_agents_refresh_plan`` was left as an interim stub that always reported
-``{"state": "unreadable"}`` and produced a spurious AGENTS.md-freshness
-warning on every consumer ``task doctor`` run (#1389).
-
-This module is intentionally PURE: stdlib-only, no rich / prompt_toolkit /
-textual, and NO side effects at import time. Importing it from either rail
-is therefore safe and cheap.
-
-The marker contract mirrors ``run``: v1 (#1044 v0.26), v2 (#992 PR1 v0.27)
-and v3 (#1046 PR-B, with ``sha`` / ``refreshed`` / ``session`` provenance
-attributes on the open tag). ``cmd_agents_refresh`` stamps the v3 attributes
-at write time; the staleness classifier normalises the open tag to the bare
-v3 form before byte-comparing so the per-refresh attributes never poison
-idempotency.
-
-Story: #1389 (follow-up to #1335 / #1336 doctor carve; refs #1308 / #1309).
-"""
-
-from __future__ import annotations
-
-import re
-import subprocess
-import sys
-import uuid
-from collections.abc import Callable
-from datetime import UTC, datetime
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).resolve().parent))
-
-from _content_root import content_root  # noqa: E402
-
-# --- Managed-section marker contract (verbatim from run) -------------------
-#
-# v1 was the v0.26 marker (``<!-- deft:managed-section v1 -->``). v2 was the
-# v0.27 marker (#992 PR1). v3 is the #1046 PR-B marker that carries refresh
-# provenance as attributes on the open tag: ``<!-- deft:managed-section v3
-# sha=<framework-sha> refreshed=<iso> session=<id> -->``. The parser accepts
-# v1, v2 AND v3 (with or without attributes) so a consumer whose AGENTS.md is
-# bracketed by a legacy v1/v2 marker classifies as ``stale`` and the
-# bracketed block is byte-replaced in place by the current v3 render (#1044)
-# -- never appended as a second managed block.
-_AGENTS_MANAGED_OPEN = "<!-- deft:managed-section v3 -->"
-_AGENTS_MANAGED_OPEN_V2_LITERAL = "<!-- deft:managed-section v2 -->"
-_AGENTS_MANAGED_OPEN_V3_LITERAL = "<!-- deft:managed-section v3 -->"
-_AGENTS_MANAGED_CLOSE = "<!-- /deft:managed-section -->"
-
-# Accepts v1, v2 and v3 (with-or-without attributes). Group 1 = version
-# (1, 2 or 3). Group 2 = the raw attribute string or '' when no attributes
-# are present. v1 acceptance (#1044) is the load-bearing fix that routes a
-# legacy marker through the in-place byte-replace path instead of the
-# legacy-wrap append path.
-_AGENTS_MANAGED_OPEN_RE = re.compile(
-    r"<!--\s*deft:managed-section\s+v(1|2|3)(?:\s+([^>]*?))?\s*-->"
-)
-
-# Recognised attribute keys on the v3 marker. Extra keys are tolerated
-# (parsed into ``extras``) so a future minor extension does not require a
-# marker rebump; absence of any recognised key is also tolerated (the bare
-# ``v3`` form is the canonical template-shipped marker; attributes are
-# stamped at refresh time by ``cmd_agents_refresh``).
-_AGENTS_MANAGED_V3_ATTR_KEYS: tuple[str, ...] = ("sha", "refreshed", "session")
-
-
-# --- Framework-root + template resolution ----------------------------------
-
-
-def framework_root() -> Path:
-    """Return the framework root (the directory that owns ``templates/``).
-
-    This module lives at ``<framework-root>/scripts/_agents_md.py`` in both
-    the source checkout and a consumer install (``<deftDir>/scripts/``), so
-    the framework root is two parents up. Mirrors ``run::get_script_dir()``
-    (which returns the directory containing ``run`` at the framework root).
-    """
-    return Path(__file__).resolve().parent.parent
-
-
-def _agents_template_path() -> Path:
-    """Return the absolute path to the canonical AGENTS.md template."""
-    return content_root(framework_root()) / "templates" / "agents-entry.md"
-
-
-def _read_agents_template() -> str | None:
-    """Return the AGENTS.md template text, or None when not readable.
-
-    The Go installer embeds the same file via ``//go:embed`` in
-    ``templates/embed.go``; the Python rail reads it from disk at runtime so
-    ``cmd_agents_refresh`` works against the live framework checkout.
-    """
-    candidate = _agents_template_path()
-    if not candidate.is_file():
-        return None
-    try:
-        return candidate.read_text(encoding="utf-8")
-    except OSError:
-        return None
-
-
-# --- Managed-section parse / render helpers ---------------------------------
-
-
-def _find_managed_open_marker(text: str) -> re.Match | None:
-    """Return the regex match for the open marker (v1, v2 OR v3), or None."""
-    return _AGENTS_MANAGED_OPEN_RE.search(text)
-
-
-def _iter_managed_sections(text: str) -> list[tuple]:
-    """Yield ``(start, end, block)`` triples for every managed section (#1044).
-
-    Walks ``text`` left-to-right collecting every well-formed
-    ``<open>...<close>`` region. ``start`` is the open marker's first byte
-    index, ``end`` is the byte index just past the close marker, and
-    ``block`` is the corresponding text slice. Used by
-    ``_agents_refresh_plan`` to collapse the duplicate-block recovery case
-    (a v1 marker coexisting with a v3 marker because a partial upgrade ran
-    the append path before this fix) into a single v3 block at the position
-    of the first managed section -- preserving surrounding user content
-    order.
-    """
-    results: list[tuple] = []
-    pos = 0
-    while pos <= len(text):
-        open_match = _AGENTS_MANAGED_OPEN_RE.search(text, pos)
-        if open_match is None:
-            break
-        close_idx = text.find(_AGENTS_MANAGED_CLOSE, open_match.end())
-        if close_idx < 0:
-            break
-        end = close_idx + len(_AGENTS_MANAGED_CLOSE)
-        results.append((open_match.start(), end, text[open_match.start():end]))
-        pos = end
-    return results
-
-
-def _parse_managed_section_attrs(extracted: str) -> dict | None:
-    """Parse the open-marker attributes from an extracted managed section.
-
-    Returns a dict with keys ``version`` (int, 1, 2 or 3), ``sha`` (str or
-    None), ``refreshed`` (ISO 8601 str or None), ``session`` (str or None),
-    and ``extras`` (dict of unrecognised ``key=value`` pairs). Returns None
-    when ``extracted`` does not match the open marker regex. v1 markers
-    (#1044 back-compat) parse with ``version=1`` and ``None`` for every
-    provenance attribute -- v1 never carried attributes.
-
-    Attribute syntax is ``key=value`` separated by whitespace. Quoted values
-    (``key='value'``, ``key="value"``) are unwrapped automatically. Unknown
-    keys are captured in ``extras`` rather than silently dropped.
-    """
-    match = _find_managed_open_marker(extracted)
-    if match is None:
-        return None
-    version = int(match.group(1))
-    attrs_raw = match.group(2) or ""
-    result: dict = {
-        "version": version,
-        "sha": None,
-        "refreshed": None,
-        "session": None,
-        "extras": {},
-    }
-    for raw_pair in attrs_raw.split():
-        if "=" not in raw_pair:
-            continue
-        key, _, value = raw_pair.partition("=")
-        key = key.strip().lower()
-        value = value.strip().strip("'\"")
-        if not key:
-            continue
-        if key in _AGENTS_MANAGED_V3_ATTR_KEYS:
-            result[key] = value
-        else:
-            result["extras"][key] = value
-    return result
-
-
-def _strip_managed_section_attrs(section: str) -> str:
-    """Normalise the open marker to the bare v3 form (#1046 PR-B, #1044).
-
-    Replaces any legacy v1 / v2 / attributed-v3 open marker with the bare
-    ``<!-- deft:managed-section v3 -->`` literal so byte-equality comparisons
-    against the rendered template are not poisoned by per-refresh ``sha`` /
-    ``refreshed`` / ``session`` tokens. Only the FIRST open marker is
-    normalised. Pure -- no I/O.
-    """
-    return _AGENTS_MANAGED_OPEN_RE.sub(
-        _AGENTS_MANAGED_OPEN_V3_LITERAL, section, count=1
-    )
-
-
-def _render_managed_section(template_text: str) -> str | None:
-    """Extract the deft:managed-section block from the template.
-
-    Returns the byte sequence (newlines normalised to ``\\n``) bracketed by
-    the open/close markers, INCLUSIVE, with the open marker normalised to the
-    bare v3 form (the canonical staleness-comparison baseline). Returns None
-    when either marker is missing.
-
-    Placeholder substitution is intentionally a no-op: the documented tokens
-    (``{{UPSTREAM_SHA}}``, etc.) are inherited from the webinstaller
-    pin-marker contract and rendered there. Leaving them as literal text
-    keeps ``--check`` byte-stable when the framework is checked out without
-    git metadata.
-    """
-    normalised = template_text.replace("\r\n", "\n")
-    open_match = _find_managed_open_marker(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)
-    block = normalised[open_idx:end]
-    return _strip_managed_section_attrs(block)
-
-
-def _extract_managed_section(text: str) -> str | None:
-    """Pull the managed-section block out of the consumer's AGENTS.md text.
-
-    Returns the bracketed block (normalised to LF, marker bytes preserved
-    verbatim including any v3 ``sha=/refreshed=/session=`` attributes) or
-    None if either marker is absent. Accepts BOTH the legacy v2 and the
-    canonical v3 open markers (#1046 PR-B back-compat parser).
-    """
-    normalised = text.replace("\r\n", "\n")
-    open_match = _find_managed_open_marker(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]
-
-
-# --- Framework SHA + session id + timestamps -------------------------------
-
-
-def _now_utc() -> datetime:
-    """Return UTC-aware ``datetime.now`` (split out for test monkeypatching)."""
-    return datetime.now(UTC)
-
-
-def _now_utc_iso() -> str:
-    """UTC ISO-8601 timestamp at seconds precision."""
-    return _now_utc().strftime("%Y-%m-%dT%H:%M:%SZ")
-
-
-def _resolve_framework_sha() -> str:
-    """Return the current framework checkout's HEAD sha (short form).
-
-    Resolution: ``git rev-parse --short=12 HEAD`` rooted at the framework
-    root. Falls back to ``unknown`` on subprocess failure (git missing /
-    non-git checkout / hook permission error). Best-effort -- the v3 marker
-    tolerates the fallback string verbatim so refresh remains idempotent
-    across environments lacking git metadata.
-    """
-    script_dir = str(framework_root())
-    try:
-        result = subprocess.run(
-            ["git", "rev-parse", "--short=12", "HEAD"],
-            capture_output=True,
-            text=True,
-            timeout=5,
-            check=False,
-            cwd=script_dir,
-        )
-    except (subprocess.TimeoutExpired, OSError):
-        return "unknown"
-    if result.returncode != 0:
-        return "unknown"
-    sha = (result.stdout or "").strip()
-    return sha or "unknown"
-
-
-def _new_session_id() -> str:
-    """Return a freshly-synthesised 12-char session id (#1046 PR-B AC-5)."""
-    return uuid.uuid4().hex[:12]
-
-
-def _attribute_render_managed_section(
-    rendered: str,
-    *,
-    framework_sha: str,
-    refreshed: str,
-    session_id: str,
-) -> str:
-    """Inject v3 attributes into a bare-rendered managed section (#1046 PR-B AC-5).
-
-    Takes the byte-stable ``rendered`` block (open marker = bare
-    ``<!-- deft:managed-section v3 -->``) emitted by
-    ``_render_managed_section`` and produces the attribute-rich form
-    consumers write to disk::
-
-        <!-- deft:managed-section v3 sha=<sha> refreshed=<iso> session=<id> -->
-
-    Only the open marker is mutated -- the body bytes between the open/close
-    markers are preserved verbatim so subsequent staleness classification
-    (after attribute stripping) returns ``current``.
-    """
-    attr_string = f"v3 sha={framework_sha} refreshed={refreshed} session={session_id}"
-    attributed_open = f"<!--{' '}deft:managed-section {attr_string} -->"
-    return rendered.replace(_AGENTS_MANAGED_OPEN_V3_LITERAL, attributed_open, 1)
-
-
-def _wrap_legacy_in_markers(existing: str, rendered: str) -> str:
-    """Produce the once-per-project legacy-to-marker migration body.
-
-    The consumer's existing pre-marker AGENTS.md content is preserved
-    verbatim ABOVE the new managed section -- so user notes outside the deft
-    block survive the migration. The rendered managed-section block is
-    appended (with a blank-line separator) so subsequent refreshes can
-    operate on the bracketed region in place.
-    """
-    body = existing.replace("\r\n", "\n").rstrip("\n")
-    if body:
-        return body + "\n\n" + rendered + "\n"
-    return rendered + "\n"
-
-
-# --- Refresh-plan verdict --------------------------------------------------
-
-
-def _agents_refresh_plan(
-    project_root: Path,
-    *,
-    read_template: Callable[[], str | None] | None = None,
-    resolve_sha: Callable[[], str] | None = None,
-    now_iso: Callable[[], str] | None = None,
-    new_session: Callable[[], str] | None = None,
-) -> dict:
-    """Compute the plan ``cmd_agents_refresh`` would apply (no I/O writes).
-
-    The plan dict reports a ``state`` (``current`` / ``stale`` / ``missing``
-    / ``absent`` / ``unreadable`` / ``template-missing`` /
-    ``template-malformed``) and the byte-content the command would write on a
-    non-current state. The stale / absent / missing payloads carry the
-    v3-attributed marker stamped with a fresh sha / refreshed / session
-    triple so each refresh records its own session lineage (#1046 PR-B
-    AC-5). The staleness check itself ignores those attributes -- both the
-    extracted block and the rendered template are normalised to the bare
-    ``v3`` marker before byte-comparing, so re-running refresh on a current
-    file is a no-op.
-
-    The four ``read_template`` / ``resolve_sha`` / ``now_iso`` /
-    ``new_session`` seams are injectable so ``run`` can route its own
-    (monkeypatchable) helpers through the shared implementation while
-    ``scripts/doctor.py`` calls it with the module defaults. They default to
-    this module's own pure helpers when omitted (#1389).
-    """
-    _read = read_template or _read_agents_template
-    _sha = resolve_sha or _resolve_framework_sha
-    _now = now_iso or _now_utc_iso
-    _session = new_session or _new_session_id
-
-    template_text = _read()
-    if template_text is None:
-        return {
-            "state": "template-missing",
-            "path": str(project_root / "AGENTS.md"),
-            "rendered": None,
-            "existing": None,
-            "new_content": None,
-        }
-    rendered = _render_managed_section(template_text)
-    if rendered is None:
-        return {
-            "state": "template-malformed",
-            "path": str(project_root / "AGENTS.md"),
-            "rendered": None,
-            "existing": None,
-            "new_content": None,
-        }
-    framework_sha = _sha()
-    refreshed = _now()
-    session_id = _session()
-    attributed_rendered = _attribute_render_managed_section(
-        rendered,
-        framework_sha=framework_sha,
-        refreshed=refreshed,
-        session_id=session_id,
-    )
-    agents_md = project_root / "AGENTS.md"
-    if not agents_md.is_file():
-        return {
-            "state": "absent",
-            "path": str(agents_md),
-            "rendered": rendered,
-            "attributed_rendered": attributed_rendered,
-            "sha": framework_sha,
-            "refreshed": refreshed,
-            "session": session_id,
-            "existing": None,
-            "new_content": attributed_rendered + "\n",
-        }
-    try:
-        existing = agents_md.read_text(encoding="utf-8", errors="replace")
-    except OSError as exc:
-        return {
-            "state": "unreadable",
-            "path": str(agents_md),
-            "rendered": rendered,
-            "existing": None,
-            "new_content": None,
-            "error": str(exc),
-        }
-    normalised = existing.replace("\r\n", "\n")
-    blocks = _iter_managed_sections(normalised)
-    if not blocks:
-        # Legacy file with no markers -- one-time migration: wrap the
-        # existing content + render the managed-section beneath it.
-        new_content = _wrap_legacy_in_markers(normalised, attributed_rendered)
-        return {
-            "state": "missing",
-            "path": str(agents_md),
-            "rendered": rendered,
-            "attributed_rendered": attributed_rendered,
-            "sha": framework_sha,
-            "refreshed": refreshed,
-            "session": session_id,
-            "existing": existing,
-            "new_content": new_content,
-        }
-    if len(blocks) > 1:
-        # Duplicate-block recovery (#1044): collapse to a single
-        # v3-attributed block at the position of the FIRST block so
-        # surrounding user content order is preserved. Walk in reverse to
-        # keep slice indices valid as we remove each block.
-        first_start = blocks[0][0]
-        new_content = normalised
-        for start, end, _ in reversed(blocks):
-            new_content = new_content[:start] + new_content[end:]
-        new_content = (
-            new_content[:first_start]
-            + attributed_rendered
-            + new_content[first_start:]
-        )
-        return {
-            "state": "stale",
-            "path": str(agents_md),
-            "rendered": rendered,
-            "attributed_rendered": attributed_rendered,
-            "sha": framework_sha,
-            "refreshed": refreshed,
-            "session": session_id,
-            "existing": existing,
-            "new_content": new_content,
-        }
-    # Single managed block -- the canonical refresh path.
-    extracted = blocks[0][2]
-    # Force-upgrade v1 / v2 -> v3 even when body bytes match.
-    extracted_attrs = _parse_managed_section_attrs(extracted)
-    is_legacy_marker = (
-        extracted_attrs is not None and extracted_attrs["version"] in (1, 2)
-    )
-    if not is_legacy_marker and _strip_managed_section_attrs(extracted) == rendered:
-        return {
-            "state": "current",
-            "path": str(agents_md),
-            "rendered": rendered,
-            "existing": existing,
-            "new_content": existing,
-        }
-    # Stale: byte-replace the bracketed block in place with the
-    # v3-attributed rendered block.
-    new_content = normalised.replace(extracted, attributed_rendered, 1)
-    return {
-        "state": "stale",
-        "path": str(agents_md),
-        "rendered": rendered,
-        "attributed_rendered": attributed_rendered,
-        "sha": framework_sha,
-        "refreshed": refreshed,
-        "session": session_id,
-        "existing": existing,
-        "new_content": new_content,
-    }