@event4u/agent-config 6.0.0 → 7.0.0

package/src/scripts/_lib/changelog_eras.py

@@ -1,330 +0,0 @@
-"""Shared constants + helpers for CHANGELOG.md era discipline.
-
-The drift gate (``tests/test_changelog_eras.py``) and the release
-automation (``scripts/release.py``) both reason about the same era
-shape: a single ``# Era: X.Y.x — current`` header followed by inline
-entries, then ``# Era: pre-X.Y.0 — archived`` pointers to files under
-``docs/archive/``. Keeping the regex / cap / path constants in one
-place prevents drift between the gate and the auto-split logic.
-
-Normative source: ``docs/contracts/CHANGELOG-conventions.md § Era splits``.
-"""
-from __future__ import annotations
-
-import re
-from dataclasses import dataclass
-from pathlib import Path
-
-REPO_ROOT = Path(__file__).resolve().parent.parent.parent.parent
-CHANGELOG = REPO_ROOT / "CHANGELOG.md"
-CONVENTIONS = REPO_ROOT / "docs" / "contracts" / "CHANGELOG-conventions.md"
-ARCHIVE_DIR = REPO_ROOT / "docs" / "archive"
-
-# Drift cap — entries between the current era header and the next era
-# header may not exceed this many lines. Raising the cap is a contract
-# change (see CHANGELOG-conventions.md § Era splits).
-CURRENT_ERA_BODY_CAP = 250
-
-ERA_HEADER_RE = re.compile(
-    r"^# Era: (?P<label>[^\n]+?)(?: — (?P<state>current|archived))?\s*$"
-)
-ARCHIVE_LINK_RE = re.compile(r"\(docs/archive/(CHANGELOG-pre-[^)\s]+\.md)\)")
-VERSION_HEADING_RE = re.compile(r"^## \[?(?P<version>\d+\.\d+\.\d+)")
-ERA_LABEL_RE = re.compile(r"^(?P<major>\d+)\.(?P<minor>\d+)\.x$")
-
-
-@dataclass(frozen=True)
-class EraSpan:
-    """One era header in CHANGELOG.md, with its line index."""
-
-    line_index: int
-    label: str
-    state: str  # "current" | "archived" | ""
-
-
-def read_changelog_lines() -> list[str]:
-    """Return CHANGELOG.md split into lines (no trailing newlines)."""
-    return CHANGELOG.read_text(encoding="utf-8").splitlines()
-
-
-def era_spans(lines: list[str]) -> list[EraSpan]:
-    """Return every era header in line-order."""
-    spans: list[EraSpan] = []
-    for i, line in enumerate(lines):
-        m = ERA_HEADER_RE.match(line)
-        if m:
-            spans.append(
-                EraSpan(
-                    line_index=i,
-                    label=m.group("label"),
-                    state=m.group("state") or "",
-                )
-            )
-    return spans
-
-
-def current_era_index(spans: list[EraSpan]) -> int | None:
-    """Return the line index of the ``— current`` era header, or None."""
-    for span in spans:
-        if span.state == "current":
-            return span.line_index
-    return None
-
-
-def current_era_body_size(lines: list[str] | None = None) -> int:
-    """Return the number of lines between the current era header and
-    the next era header (exclusive of both)."""
-    if lines is None:
-        lines = read_changelog_lines()
-    spans = era_spans(lines)
-    current_idx = current_era_index(spans)
-    if current_idx is None:
-        return 0
-    next_era_line = len(lines)
-    for span in spans:
-        if span.line_index > current_idx:
-            next_era_line = span.line_index
-            break
-    return next_era_line - current_idx - 1
-
-
-def parse_era_label(label: str) -> tuple[int, int] | None:
-    """Parse ``M.N.x`` into ``(M, N)``; return None for archived labels."""
-    m = ERA_LABEL_RE.match(label.strip())
-    if not m:
-        return None
-    return int(m.group("major")), int(m.group("minor"))
-
-
-def archive_path_for_boundary(boundary: str) -> Path:
-    """Return ``docs/archive/CHANGELOG-pre-<boundary>.md``."""
-    return ARCHIVE_DIR / f"CHANGELOG-pre-{boundary}.md"
-
-
-def collapsed_era_block(boundary: str) -> str:
-    """Render the standard ``# Era: pre-<boundary> — archived`` pointer
-    block that replaces archived entries in CHANGELOG.md.
-
-    Mirrors the wording the manual splits already used (verified against
-    every existing collapsed era as of 3.2.x).
-    """
-    archive_rel = f"docs/archive/CHANGELOG-pre-{boundary}.md"
-    return (
-        f"# Era: pre-{boundary} — archived\n"
-        "\n"
-        f"> All entries before `{boundary}` live in\n"
-        f"> [`{archive_rel}`]({archive_rel}).\n"
-        "> The archive is read-only; git tags remain the canonical\n"
-        "> source for what shipped. Splitting them out of the main file\n"
-        "> keeps the active era under the 250-line drift cap enforced by\n"
-        "> `tests/test_changelog_eras.py`.\n"
-    )
-
-
-def archive_file_header(boundary: str) -> str:
-    """Return the standard prologue for ``docs/archive/CHANGELOG-pre-<boundary>.md``."""
-    return (
-        f"# Changelog Archive — pre-{boundary}\n"
-        "\n"
-        f"> Frozen snapshot of `event4u/agent-config` changelog entries\n"
-        f"> released before `{boundary}`, split out of the main\n"
-        "> [`CHANGELOG.md`](../../CHANGELOG.md) by `scripts/release.py`\n"
-        "> once the active era's body crossed the drift cap enforced by\n"
-        "> `tests/test_changelog_eras.py`.\n"
-        ">\n"
-        "> **Read-only.** New entries land in `CHANGELOG.md`. Entries\n"
-        "> here are not amended — git tags remain the canonical source\n"
-        "> for what shipped.\n"
-        ">\n"
-        "> Entry shape follows\n"
-        "> [`../contracts/CHANGELOG-conventions.md`](../contracts/CHANGELOG-conventions.md).\n"
-        "\n"
-    )
-
-
-# ─── split planning + execution ────────────────────────────────────────────────
-
-
-_RELEASE_VERSION_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)$")
-
-
-@dataclass(frozen=True)
-class SplitPlan:
-    """Recipe for an era split during release of ``release_version``."""
-
-    release_version: str  # e.g. "3.3.0"
-    boundary: str  # e.g. "3.3.0" — used in archive filename + pointer
-    new_era_label: str  # e.g. "3.3.x"
-    old_era_label: str  # e.g. "3.2.x"
-    archive_path: Path
-
-    @property
-    def commit_subject(self) -> str:
-        return (
-            f"chore(changelog): split era {self.old_era_label} "
-            f"→ pre-{self.boundary}"
-        )
-
-
-def plan_split(release_version: str) -> SplitPlan | None:
-    """Plan an era split when releasing ``release_version``.
-
-    Returns None when no split is needed (release is a patch within the
-    current era, or no current era header exists). Returns a SplitPlan
-    when the release crosses a minor or major boundary; the caller
-    decides whether to invoke ``perform_split`` based on era body size.
-
-    Raises ValueError when ``release_version`` is not bare semver, or
-    when it would move backward relative to the current era label.
-    """
-    m = _RELEASE_VERSION_RE.match(release_version.strip())
-    if not m:
-        raise ValueError(f"not a bare semver (X.Y.Z): {release_version!r}")
-    rel_major, rel_minor, _rel_patch = (int(m.group(i)) for i in (1, 2, 3))
-
-    lines = read_changelog_lines()
-    spans = era_spans(lines)
-    current = next((s for s in spans if s.state == "current"), None)
-    if current is None:
-        return None
-
-    parsed = parse_era_label(current.label)
-    if parsed is None:
-        return None
-    era_major, era_minor = parsed
-
-    if (rel_major, rel_minor) < (era_major, era_minor):
-        raise ValueError(
-            f"release {release_version!r} is older than current era "
-            f"{current.label!r}; refusing to plan a backwards split"
-        )
-    if (rel_major, rel_minor) == (era_major, era_minor):
-        # Patch release within the current era — no era boundary crossed,
-        # so an auto-split would create a nonsensical archive name. The
-        # caller is expected to die() with the manual-intervention message.
-        return None
-
-    boundary = f"{rel_major}.{rel_minor}.0"
-    return SplitPlan(
-        release_version=release_version,
-        boundary=boundary,
-        new_era_label=f"{rel_major}.{rel_minor}.x",
-        old_era_label=current.label,
-        archive_path=archive_path_for_boundary(boundary),
-    )
-
-
-def new_era_intro_block(new_era_label: str, boundary: str) -> str:
-    """Render the header + blockquote intro for a freshly-split current era."""
-    parsed = parse_era_label(new_era_label)
-    if parsed is None:
-        next_example = "# Era: <next>.x"
-    else:
-        m, n = parsed
-        next_example = f"# Era: {m}.{n + 1}.x"
-    return (
-        f"# Era: {new_era_label} — current\n"
-        "\n"
-        f"> Started at `{boundary}`. Full entries live inline below.\n"
-        "> The drift test caps this era at 250 lines of entry body; growth past\n"
-        f"> that forces a new era split (`{next_example}`, etc.) — see\n"
-        "> [`docs/contracts/CHANGELOG-conventions.md § Era splits`](docs/contracts/CHANGELOG-conventions.md).\n"
-    )
-
-
-def _era_body_bounds(
-    lines: list[str], current_idx: int
-) -> tuple[int, int, int]:
-    """Return ``(body_start, body_end, next_era_line)`` for the era at
-    ``current_idx``.
-
-    * ``body_start`` — first line after the header + leading blockquote
-      intro + the blank line that follows.
-    * ``body_end`` — exclusive; one line before the next era marker (or
-      end of file). Trailing blank lines are NOT trimmed; the caller
-      reattaches them on splice.
-    * ``next_era_line`` — index of the next ``# Era:`` line, or
-      ``len(lines)`` when none follows.
-    """
-    next_era_line = len(lines)
-    for i in range(current_idx + 1, len(lines)):
-        if ERA_HEADER_RE.match(lines[i]):
-            next_era_line = i
-            break
-
-    cursor = current_idx + 1
-    # Skip leading blank lines between header and blockquote intro.
-    while cursor < next_era_line and lines[cursor].strip() == "":
-        cursor += 1
-    # Skip the leading blockquote intro (consecutive `>`-prefixed lines).
-    while cursor < next_era_line and lines[cursor].startswith(">"):
-        cursor += 1
-    # Skip the blank separator between intro and entries.
-    while cursor < next_era_line and lines[cursor].strip() == "":
-        cursor += 1
-
-    return cursor, next_era_line, next_era_line
-
-
-def current_era_insertion_point(lines: list[str]) -> int | None:
-    """Return the line index at which a new release entry should be
-    prepended within the current era.
-
-    Strategy:
-    * If the current era body contains one or more ``## [X.Y.Z]``
-      headings, return the line of the topmost (newest) one.
-    * Otherwise, return the first line after the era intro blockquote.
-
-    Returns None when no current era header exists.
-    """
-    spans = era_spans(lines)
-    current_idx = current_era_index(spans)
-    if current_idx is None:
-        return None
-    body_start, body_end, _ = _era_body_bounds(lines, current_idx)
-    for i in range(body_start, body_end):
-        if VERSION_HEADING_RE.match(lines[i]):
-            return i
-    return body_start
-
-
-def perform_split(plan: SplitPlan) -> None:
-    """Execute ``plan`` against the on-disk CHANGELOG.md.
-
-    * Refuses to overwrite an existing archive file.
-    * Moves every entry in the current era body into the new archive.
-    * Replaces the current era block with the collapsed pointer + the
-      freshly-labelled new current era header (empty body).
-    """
-    if plan.archive_path.exists():
-        raise FileExistsError(
-            f"archive already exists at {plan.archive_path} — "
-            "likely a previous --resume run; inspect manually"
-        )
-
-    lines = read_changelog_lines()
-    spans = era_spans(lines)
-    current_idx = current_era_index(spans)
-    if current_idx is None:
-        raise RuntimeError("no current era header found in CHANGELOG.md")
-
-    body_start, _, next_era_line = _era_body_bounds(lines, current_idx)
-    entries = lines[body_start:next_era_line]
-    # Trim trailing blank lines so the archive doesn't accumulate them.
-    while entries and entries[-1].strip() == "":
-        entries.pop()
-
-    collapsed = collapsed_era_block(plan.boundary).rstrip("\n").splitlines()
-    new_era = new_era_intro_block(plan.new_era_label, plan.boundary).rstrip("\n").splitlines()
-
-    head = lines[:current_idx]
-    tail = lines[next_era_line:]
-    new_lines = head + collapsed + [""] + new_era + [""] + tail
-    new_text = "\n".join(new_lines).rstrip() + "\n"
-
-    archive_body = "\n".join(entries).rstrip() + "\n" if entries else ""
-    archive_text = archive_file_header(plan.boundary) + archive_body
-
-    plan.archive_path.parent.mkdir(parents=True, exist_ok=True)
-    plan.archive_path.write_text(archive_text, encoding="utf-8")
-    CHANGELOG.write_text(new_text, encoding="utf-8")

package/src/scripts/_lib/claude_desktop_bundler.py

@@ -1,238 +0,0 @@
-"""Claude Desktop skill ZIP bundler (Phase 4 of event4u-namespace roadmap).
-
-Claude Desktop has no filesystem convention for skills; the Customize →
-Skills UI accepts a ZIP per skill via the Upload button. This module
-walks ``<package_root>/dist/agent-src/skills/*`` and produces one
-``<skill-name>.zip`` per directory into ``dest_dir``. It additionally
-walks ``<package_root>/dist/agent-src/commands/`` and produces one
-``<command-slug>.zip`` per command ``.md`` file so Claude Desktop sees
-the same surface that Claude Code exposes via the ``.claude/skills/``
-symlink wrapper layer.
-
-Contract:
-
-- Each ZIP contains ``SKILL.md`` plus every sibling file under the same
-  directory (recursive). Symlinks are dereferenced so the ZIP is
-  self-contained.
-- Command bundles wrap a single ``dist/agent-src/commands/<path>.md`` file
-  as ``SKILL.md`` inside the ZIP. Nested commands flatten to
-  ``<cluster>-<leaf>`` slugs (e.g. ``council/default.md`` →
-  ``council-default.zip``) to mirror ``condense.py``.
-- Exclusions: ``.git*``, ``__pycache__``, ``*.pyc`` — matched on the
-  basename of any path component.
-- A skill folder without a ``SKILL.md`` is skipped (defensive: avoids
-  shipping Claude-Code orchestrator stubs that don't follow the
-  Anthropic skill schema).
-- Command files named ``AGENTS.md`` are skipped (cluster authoring docs,
-  not invocable commands).
-- A command slug that collides with an existing skill name is skipped —
-  the real skill bundle wins, matching ``condense.generate_claude_commands``.
-- Writes are atomic via tempfile → ``os.replace``.
-- Idempotent: each ZIP gets a sibling ``<slug>.sha256`` recording
-  the manifest digest. If the recomputed digest matches the recorded
-  one, the existing ZIP is left untouched (unless ``force=True``).
-"""
-from __future__ import annotations
-
-import hashlib
-import os
-import tempfile
-import zipfile
-from pathlib import Path
-from typing import Iterable, Optional
-
-#: Filenames or path components that are never included in a bundle.
-_EXCLUDED_BASENAMES = frozenset({"__pycache__", ".DS_Store"})
-_EXCLUDED_PREFIXES = (".git",)
-_EXCLUDED_SUFFIXES = (".pyc", ".pyo")
-
-
-def _is_excluded(rel_parts: tuple[str, ...]) -> bool:
-    """Return True if any component matches the exclusion lists."""
-    for part in rel_parts:
-        if part in _EXCLUDED_BASENAMES:
-            return True
-        if part.startswith(_EXCLUDED_PREFIXES):
-            return True
-        if part.endswith(_EXCLUDED_SUFFIXES):
-            return True
-    return False
-
-
-def _walk_skill_files(skill_dir: Path) -> list[tuple[Path, tuple[str, ...]]]:
-    """Return ``[(abs_path, rel_parts), ...]`` for every file in the skill.
-
-    Symlinks are followed (``os.walk(..., followlinks=True)``) so a
-    bundle from a symlinked entry under ``dist/agent-src/skills/`` contains
-    the actual target content, not a dangling symlink.
-    """
-    out: list[tuple[Path, tuple[str, ...]]] = []
-    resolved = skill_dir.resolve()
-    for root, dirs, files in os.walk(resolved, followlinks=True):
-        root_path = Path(root)
-        rel_root = root_path.relative_to(resolved)
-        # Prune excluded dirs in-place so os.walk skips them.
-        dirs[:] = [d for d in dirs if not _is_excluded((d,))]
-        for fname in files:
-            rel_parts = (*rel_root.parts, fname) if rel_root.parts else (fname,)
-            if _is_excluded(rel_parts):
-                continue
-            out.append((root_path / fname, rel_parts))
-    out.sort(key=lambda item: item[1])
-    return out
-
-
-def _manifest_digest(files: Iterable[tuple[Path, tuple[str, ...]]]) -> str:
-    """Hash sorted (rel_path, content_sha256) pairs into one digest.
-
-    Stable across runs as long as the input set + bytes are stable. Used
-    as the idempotency token written to ``<skill>.sha256``.
-    """
-    h = hashlib.sha256()
-    for abs_path, rel_parts in files:
-        rel = "/".join(rel_parts)
-        h.update(rel.encode("utf-8"))
-        h.update(b"\x00")
-        h.update(hashlib.sha256(abs_path.read_bytes()).digest())
-        h.update(b"\x00")
-    return h.hexdigest()
-
-
-def _atomic_write_zip(
-    zip_path: Path, files: list[tuple[Path, tuple[str, ...]]]
-) -> None:
-    """Write ``files`` into ``zip_path`` atomically (temp + rename)."""
-    zip_path.parent.mkdir(parents=True, exist_ok=True)
-    fd, tmp_name = tempfile.mkstemp(
-        prefix=f".{zip_path.stem}.", suffix=".zip.tmp", dir=str(zip_path.parent),
-    )
-    os.close(fd)
-    tmp_path = Path(tmp_name)
-    try:
-        with zipfile.ZipFile(tmp_path, "w", zipfile.ZIP_DEFLATED) as zf:
-            for abs_path, rel_parts in files:
-                zf.write(abs_path, arcname="/".join(rel_parts))
-        os.replace(tmp_path, zip_path)
-    finally:
-        if tmp_path.exists():
-            tmp_path.unlink()
-
-
-def build_skill_bundles(
-    package_root: Path,
-    dest_dir: Path,
-    force: bool = False,
-    curation: Optional[list[str]] = None,
-) -> list[Path]:
-    """Build per-skill ZIPs under ``dest_dir``.
-
-    Returns the list of ZIP paths that were (re-)written this call. ZIPs
-    skipped because their content digest matched the existing sidecar
-    are not in the returned list (but remain on disk).
-
-    ``curation`` optionally restricts the build to the given skill
-    names; ``None`` bundles every skill folder containing ``SKILL.md``.
-    """
-    skills_root = package_root / "dist/agent-src" / "skills"
-    if not skills_root.is_dir():
-        return []
-    dest_dir.mkdir(parents=True, exist_ok=True)
-    written: list[Path] = []
-    for entry in sorted(skills_root.iterdir()):
-        if not (entry.is_dir() or entry.is_symlink()):
-            continue
-        skill_name = entry.name
-        if curation is not None and skill_name not in curation:
-            continue
-        skill_md = entry / "SKILL.md"
-        if not skill_md.exists():
-            continue
-        files = _walk_skill_files(entry)
-        if not files:
-            continue
-        digest = _manifest_digest(files)
-        zip_path = dest_dir / f"{skill_name}.zip"
-        digest_path = dest_dir / f"{skill_name}.sha256"
-        recorded = digest_path.read_text(encoding="utf-8").strip() if digest_path.exists() else ""
-        if not force and recorded == digest and zip_path.exists():
-            continue
-        _atomic_write_zip(zip_path, files)
-        digest_path.write_text(digest + "\n", encoding="utf-8")
-        written.append(zip_path)
-    return written
-
-
-def _command_slug(source_file: Path, commands_root: Path) -> str:
-    """Return the flat slug for a command source file.
-
-    Mirrors ``scripts/condense.py::_command_slug``: top-level commands
-    keep their stem (``commit.md`` → ``commit``); nested commands flatten
-    the relative path with ``-`` (``council/default.md`` →
-    ``council-default``).
-    """
-    rel = source_file.relative_to(commands_root)
-    return "-".join(rel.with_suffix("").parts)
-
-
-def _iter_command_files(commands_root: Path) -> Iterable[Path]:
-    """Yield every command ``.md`` file under ``commands_root`` (recursive).
-
-    Skips ``AGENTS.md`` cluster authoring docs, matching
-    ``scripts/condense.py::_iter_commands``.
-    """
-    for source_file in sorted(commands_root.rglob("*.md")):
-        if source_file.name == "AGENTS.md":
-            continue
-        yield source_file
-
-
-def build_command_bundles(
-    package_root: Path,
-    dest_dir: Path,
-    force: bool = False,
-    curation: Optional[list[str]] = None,
-) -> list[Path]:
-    """Build per-command ZIPs under ``dest_dir``.
-
-    Each ZIP contains a single ``SKILL.md`` whose bytes are the source
-    command ``.md`` file — same wrapping pattern that
-    ``condense.generate_claude_commands`` uses for Claude Code via
-    ``.claude/skills/<slug>/SKILL.md`` symlinks.
-
-    Slugs that collide with an existing skill folder under
-    ``<package_root>/dist/agent-src/skills/`` are skipped so the real skill
-    bundle wins.
-
-    Returns the list of ZIP paths that were (re-)written this call. ZIPs
-    skipped because their content digest matched the existing sidecar
-    are not in the returned list (but remain on disk).
-
-    ``curation`` optionally restricts the build to the given command
-    slugs; ``None`` bundles every command file.
-    """
-    commands_root = package_root / "dist/agent-src" / "commands"
-    if not commands_root.is_dir():
-        return []
-    skills_root = package_root / "dist/agent-src" / "skills"
-    skill_names: set[str] = set()
-    if skills_root.is_dir():
-        skill_names = {entry.name for entry in skills_root.iterdir() if entry.is_dir()}
-    dest_dir.mkdir(parents=True, exist_ok=True)
-    written: list[Path] = []
-    for source_file in _iter_command_files(commands_root):
-        slug = _command_slug(source_file, commands_root)
-        if slug in skill_names:
-            continue
-        if curation is not None and slug not in curation:
-            continue
-        files = [(source_file.resolve(), ("SKILL.md",))]
-        digest = _manifest_digest(files)
-        zip_path = dest_dir / f"{slug}.zip"
-        digest_path = dest_dir / f"{slug}.sha256"
-        recorded = digest_path.read_text(encoding="utf-8").strip() if digest_path.exists() else ""
-        if not force and recorded == digest and zip_path.exists():
-            continue
-        _atomic_write_zip(zip_path, files)
-        digest_path.write_text(digest + "\n", encoding="utf-8")
-        written.append(zip_path)
-    return written

package/src/scripts/_lib/cli_wrapper.py

@@ -1,64 +0,0 @@
-"""Install / refresh the consumer-facing ``./agent-config`` wrapper.
-
-Python counterpart to ``install_cli_wrapper`` in ``scripts/install.sh``.
-The wrapper is gitignored and meant to be regenerated on every install,
-but the normal update cadence (``upgrade``, ``refresh --project``) never
-re-ran the bash installer — so an older, fallback-less wrapper could
-linger in a consumer project and break every Claude hook (the hook
-resolves the master CLI *through* this wrapper). These helpers let the
-update commands re-stamp the wrapper from the canonical template.
-
-The template is the single source of truth (``src/templates/agent-config-wrapper.sh``);
-the installer copies it verbatim with no substitution, so refreshing is a
-plain copy + ``chmod``.
-"""
-from __future__ import annotations
-
-import shutil
-from pathlib import Path
-from typing import Optional
-
-# scripts/_lib/cli_wrapper.py → parents[2] is the package root.
-_PACKAGE_ROOT = Path(__file__).resolve().parents[3]
-_TEMPLATE = _PACKAGE_ROOT / "src" / "templates" / "agent-config-wrapper.sh"
-
-
-def template_path() -> Path:
-    """Absolute path to the canonical wrapper template."""
-    return _TEMPLATE
-
-
-def _target(project_root: Path) -> Path:
-    return Path(project_root) / "agent-config"
-
-
-def needs_refresh(project_root: Path) -> bool:
-    """True when the project wrapper is missing or differs from the template.
-
-    Returns ``False`` when the template itself is unavailable (corrupt /
-    maintainer-only checkout) — there is nothing to refresh *to*.
-    """
-    if not _TEMPLATE.is_file():
-        return False
-    target = _target(project_root)
-    if not target.is_file():
-        return True
-    try:
-        return target.read_text(encoding="utf-8") != _TEMPLATE.read_text(
-            encoding="utf-8")
-    except OSError:
-        return True
-
-
-def install_cli_wrapper(project_root: Path) -> Optional[Path]:
-    """Copy the canonical wrapper template to ``<project_root>/agent-config``.
-
-    Returns the written target path, or ``None`` when the template is
-    missing (corrupt package / maintainer checkout without templates).
-    """
-    if not _TEMPLATE.is_file():
-        return None
-    target = _target(project_root)
-    shutil.copyfile(_TEMPLATE, target)
-    target.chmod(0o755)
-    return target