specpro-cli 0.1.0__py3-none-any.whl

specpro_cli/integrations/claude/__init__.py

@@ -0,0 +1,101 @@
+"""Claude Code — skills layout under `.claude/skills/`.
+
+**Why the skills layout and not `.claude/commands/`** ⚠️: this was decided twice. The
+2026-09-16 ruling kept the flat commands layout to avoid redoing the bootstrap mirror;
+the 2026-09-17 ruling reversed it and aligned with spec-kit. The reversal is recorded in
+`agent-registry.md` → 「`claude` 的落位对齐 spec-kit」, together with the fact that it
+**accepts the migration cost** — so the note here is a pointer, not a second decision.
+
+The consequence a reader needs: the invocation name is the **skill directory name**, so
+`specpro.specify` is invoked as `/specpro-specify`. `SkillsIntegration` already carries
+that (`invoke_separator = "-"` plus the dot-to-hyphen passes in `command_filename` and
+`build_command_invocation`), so this module declares only what is claude's own.
+
+Source: L2 spec-kit 1.0.8.dev0 (vendored `de2a5ff`)
+[`src/specify_cli/integrations/claude/__init__.py:38` (`class ClaudeIntegration(SkillsIntegration)`)
+· `:43` (`config`) · `:49` (`registrar_config`)]
+"""
+
+from __future__ import annotations
+
+import json
+
+from specpro_cli.integrations import registry
+from specpro_cli.integrations.base import SkillsIntegration
+
+# ---------------------------------------------------------------------------------------
+# argument-hint per command
+# ---------------------------------------------------------------------------------------
+#
+# Claude Code renders `argument-hint` next to the slash command as a usage prompt. The
+# values below mirror what each command's own documentation already says it accepts —
+# `CLAUDE.md` → 「常用命令」 and the command documents' own argument lists. Keeping them
+# once, here, is what makes this a *declaration* rather than a second specification: the
+# command documents stay the source for what an argument means, and this table owns only
+# how it is displayed.
+#
+# ⚠️ A command that takes nothing is **absent** rather than mapped to an empty string, and
+# `_hint_for` returns no line for it. An emitted `argument-hint: ""` would render as an
+# empty prompt, which reads as "usage information is missing" instead of "this command
+# takes no arguments" — the two look identical to the user and only one is true.
+_ARGUMENT_HINTS: dict[str, str] = {
+    "constitution": "[project description, or --review-issues]",
+    "specify": "<feature description>",
+    "clarify": "[--scan]",
+    "plan": "[--review-issues | --continue]",
+    "tasks": "[--review-issues]",
+    "implement": "[--once | --count N | --phase <phase> | --review-issues | --fix-defects]",
+    "test-plan": "[--review-issues]",
+    "test-implement": "[--layer <infra|integration|ce2e|ae2e>]",
+    "qc": "[--scope <full|incremental>] [--auto]",
+    "checklist": "[domain]",
+    "analyze": "[--persist | --summary | --incremental]",
+}
+
+
+def _hint_for(stem: str) -> str | None:
+    """The hint for `stem`, or `None` when the command takes no arguments."""
+    return _ARGUMENT_HINTS.get(stem)
+
+
+class ClaudeIntegration(SkillsIntegration):
+    """Claude Code: one skill directory per command, under `.claude/skills/`."""
+
+    key = "claude"
+    cli_command = "claude"  # FR-068 — the agent's own CLI, probed by `specpro check`
+
+    config = {
+        "name": "Claude Code",
+        "folder": ".claude/",
+        "commands_subdir": "skills",
+    }
+
+    registrar_config = {
+        "dir": ".claude/skills",
+        "format": "markdown",
+        "extension": "/SKILL.md",
+    }
+
+    # Declared in `agent-registry.md` → 「每个集成模块必须声明」→ `multi_install_safe`
+    # ("声明可与他人共存于同一项目", claude · cursor-agent · qodercli). It is a claim
+    # about the *layout*, not a feature: each agent writes under its own dot-directory, so
+    # two agents installed into one project cannot collide.
+    multi_install_safe = True
+
+    def skill_frontmatter_extra(
+        self, stem: str, description: str, source_name: str
+    ) -> list[str]:
+        """Inject `argument-hint` — the agent-specific processing this subclass exists for.
+
+        This is T020's override: `agent-registry.md` lists claude as the agent carrying
+        「子类方法覆写」, and the field it injects is `argument-hint`.
+        """
+        hint = _hint_for(stem)
+        if hint is None:
+            return []
+        # Quoted via `json.dumps`, the same way `build_skill_frontmatter` quotes its own
+        # values — a hint containing `>` or `:` would otherwise be re-read as YAML.
+        return [f"argument-hint: {json.dumps(hint, ensure_ascii=False)}"]
+
+
+registry.register(ClaudeIntegration())

specpro_cli/integrations/copilot/__init__.py

@@ -0,0 +1,153 @@
+"""GitHub Copilot — **two** locations: the agent file, plus a companion prompt file.
+
+Declared in `specs/contracts/agent-registry.md` -> 「首批 agent」:
+
+    `copilot` | GitHub Copilot | Base 直接子类 | **主**：`.github/agents/`（`.agent.md`）
+                                          | **伴生**：`.github/prompts/`（`.prompt.md`）
+
+⚠️ **The 主落位 is `.github/agents/`, NOT `.github/prompts/`** — the contract carries an
+explicit correction on this point: an earlier revision recorded the companion directory
+as the main one, and that error is exactly the shape this repository keeps meeting (a
+value stated in two places, one of them wrong, and nothing compares them).
+
+⚠️ **Why this is an `IntegrationBase` DIRECT subclass rather than one of the five format
+bases**: the five bases each describe *one* output shape. This agent's deliverable is
+*two* files per command, and the second one is not a re-rendering of the first — it is a
+companion that points at it. `plan.md` -> the format table records this as the 「需额外伴生
+文件的特例」, and the base-class docstring is explicit that "required" is enforced at
+runtime rather than by `@abstractmethod` — so what this module MUST do is declare the
+constants and override `setup`, and the registry's registration check is what catches a
+half-declared subclass.
+
+⚠️ **What was NOT done, stated honestly**: the companion's *content* below is the minimum
+that makes it a prompt file — a frontmatter naming the agent it invokes, plus a body that
+delegates to it. The registry contract's Source column lists the reference
+implementation's field set (`description` / `name` / `argument-hint` / `agent` / `model` /
+`tools`) but does **not** state which of those this project must emit or what each means
+for this agent, and inventing the other three from the field *names* would be an
+unmeasured claim about a peer's behaviour — the same class of assertion the contract's
+own 「未经测量的对端行为断言」 note corrects elsewhere. ⇒ **Emitted: `description`,
+`name`, `agent`.** The rest are left out rather than guessed.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from specpro_cli.integrations import registry
+from specpro_cli.integrations.base import IntegrationBase, command_stem
+
+
+class CopilotIntegration(IntegrationBase):
+    """GitHub Copilot: an agent file under `.github/agents/`, plus its companion prompt."""
+
+    key = "copilot"
+    cli_command = "copilot"  # FR-068 — the agent's own CLI, probed by `specpro check`
+
+    config = {
+        "name": "GitHub Copilot",
+        "folder": ".github/",
+        "commands_subdir": "agents",
+    }
+
+    registrar_config = {
+        "dir": ".github/agents",
+        "format": "markdown",
+        "extension": ".agent.md",
+    }
+
+    # --- the companion location --------------------------------------------------------
+    #
+    # Declared as a constant rather than inlined at its use site: the entry layer reads
+    # `registrar_config` to compute 落位 and MUST NOT hardcode a path, so the second
+    # location belongs beside the first rather than inside `setup`'s body.
+    companion_subdir: str = "prompts"
+    companion_extension: str = ".prompt.md"
+
+    def companion_dest(self, project_root: Path) -> Path:
+        """Where this integration's companion prompt files land."""
+        config = self._require_config()
+        return project_root / config["folder"] / self.companion_subdir
+
+    def companion_filename(self, template_name: str) -> str:
+        return f"specpro.{command_stem(template_name)}{self.companion_extension}"
+
+    def command_filename(self, template_name: str) -> str:
+        # Mirrors `registrar_config["extension"]`; a base-class default would produce
+        # `specpro.<name>.md`, which this agent does not read.
+        return f"specpro.{command_stem(template_name)}.agent.md"
+
+    def planned_paths(self, project_root: Path, commands_dir: Path) -> list[Path]:
+        """Both files per command — the agent file AND its companion prompt.
+
+        The uninstall contract removes "exactly what `setup()` would write"; for this
+        agent that is twice the template count, and a default that listed only the
+        agent files would leave every companion behind as an orphan pointing at an
+        uninstalled agent.
+        """
+        dest_dir = self.commands_dest(project_root)
+        companion_dir = self.companion_dest(project_root)
+        return [
+            path
+            for src in self.list_command_templates(commands_dir)
+            for path in (
+                dest_dir / self.command_filename(src.name),
+                companion_dir / self.companion_filename(src.name),
+            )
+        ]
+
+    def deploy_roots(self, project_root: Path) -> list[Path]:
+        return [self.commands_dest(project_root), self.companion_dest(project_root)]
+
+    def setup(
+        self, project_root: Path, commands_dir: Path, *, force: bool = False
+    ) -> tuple[list[Path], list[Path]]:
+        """Deploy BOTH files per command, and return everything written or skipped.
+
+        ⚠️ **The return value is the report's only input** (`install-cli.md` -> Output
+        Contract): a companion written but not returned would be a file the user is never
+        told about — and "installed" would then be a claim about a subset nobody named.
+
+        The conflict gate judges the PAIR by the agent file: if it exists and no
+        `--force` was given, both halves are reported skipped together. The two files
+        are one command's deliverable — an agent file kept (possibly user-edited) under
+        a freshly overwritten companion would deploy a half-old half-new command while
+        the report counted only one skip, so the pair moves as one.
+        """
+        dest_dir = self.commands_dest(project_root)
+        dest_dir.mkdir(parents=True, exist_ok=True)
+        companion_dir = self.companion_dest(project_root)
+        companion_dir.mkdir(parents=True, exist_ok=True)
+
+        written: list[Path] = []
+        skipped: list[Path] = []
+        for src in self.list_command_templates(commands_dir):
+            stem = command_stem(src.name)
+            agent_path = dest_dir / self.command_filename(src.name)
+            companion_path = companion_dir / self.companion_filename(src.name)
+            if agent_path.exists() and not force:
+                skipped.append(agent_path)
+                skipped.append(companion_path)
+                continue
+            self.write_file(src.read_text(encoding="utf-8"), agent_path)
+            written.append(agent_path)
+            written.append(
+                self.write_file(self._render_companion(stem), companion_path)
+            )
+        return written, skipped
+
+    @staticmethod
+    def _render_companion(stem: str) -> str:
+        """The companion prompt: frontmatter naming the agent, then a delegation body."""
+        return (
+            "---\n"
+            f"name: specpro-{stem}\n"
+            f"description: Run the specpro `{stem}` command as a Copilot agent.\n"
+            f"agent: specpro-{stem}\n"
+            "---\n"
+            "\n"
+            f"Invoke the `specpro-{stem}` agent with the arguments below.\n"
+        )
+
+
+registry.register(CopilotIntegration())

specpro_cli/integrations/cursor_agent/__init__.py

@@ -0,0 +1,51 @@
+"""Cursor — one skill directory per command, under `.cursor/skills/`.
+
+Declared in `specs/contracts/agent-registry.md` -> 「首批 agent」: `cursor-agent` is a
+**Skills** agent with 落位 `.cursor/skills/` (source: the reference implementation's
+`cursor_agent/__init__.py:21,35`, `dir=".cursor/skills"`).
+
+⚠️ **This module declares constants and overrides nothing** — that is the `IntegrationBase`
+contract ("a new agent declares four groups of constants and overrides nothing else").
+Anything the base already does right MUST NOT be restated here: a second copy of the
+invocation-name rule (`SkillsIntegration` already turns `/specpro.specify` into
+`/specpro-specify`) would drift from the base silently, and the drift would be invisible
+because both copies would keep looking authoritative.
+
+⚠️ **Key vs module name**: `key` is the user-facing `--agent` value and matches the
+agent's own binary name (hyphenated); the Python module uses an underscore because that
+is what an import accepts. The registry contract states both, and they are not required
+to agree.
+"""
+
+from __future__ import annotations
+
+from specpro_cli.integrations import registry
+from specpro_cli.integrations.base import SkillsIntegration
+
+
+class CursorAgentIntegration(SkillsIntegration):
+    """Cursor: one skill directory per command, under `.cursor/skills/`."""
+
+    key = "cursor-agent"
+    cli_command = "cursor-agent"  # FR-068 — the agent's own CLI, probed by `specpro check`
+
+    config = {
+        "name": "Cursor",
+        "folder": ".cursor/",
+        "commands_subdir": "skills",
+    }
+
+    registrar_config = {
+        "dir": ".cursor/skills",
+        "format": "markdown",
+        "extension": "/SKILL.md",
+    }
+
+    # `agent-registry.md` -> 「可选声明」-> `multi_install_safe`: "声明可与他人共存于同一
+    # 项目", and the contract lists cursor-agent among the three that declare it. It is a
+    # claim about the *layout*, not a feature: each agent writes under its own
+    # dot-directory, so two agents installed into one project cannot collide.
+    multi_install_safe = True
+
+
+registry.register(CursorAgentIntegration())

specpro_cli/integrations/gemini/__init__.py

@@ -0,0 +1,44 @@
+"""Gemini CLI — one TOML file per command, under `.gemini/commands/`.
+
+Declared in `specs/contracts/agent-registry.md` -> 「首批 agent」: `gemini` is a **Toml**
+agent with 落位 `.gemini/commands/` (source: the reference implementation's
+`gemini/__init__.py:6,15`, `dir=".gemini/commands"` · `extension=".toml"`).
+
+⚠️ **This module declares constants and overrides nothing** — same rule as every other
+agent module: `TomlIntegration` already owns the `.toml` filename, the `{{args}}`
+placeholder and the frontmatter→`prompt` repackaging, so a subclass that restated any of
+them would be a second source for a fact the base already answers.
+
+⚠️ **Why this agent is not `MarkdownIntegration`**: the delivered file is not Markdown
+with a header — it is TOML whose `prompt` key holds the Markdown body as a scalar. That
+transformation is the reason the format base classes exist (`plan.md` -> the five-format
+table), and picking the wrong one would produce a file that *looks* deployed and is not
+readable by the agent.
+"""
+
+from __future__ import annotations
+
+from specpro_cli.integrations import registry
+from specpro_cli.integrations.base import TomlIntegration
+
+
+class GeminiIntegration(TomlIntegration):
+    """Gemini CLI: one TOML file per command, under `.gemini/commands/`."""
+
+    key = "gemini"
+    cli_command = "gemini"  # FR-068 — the agent's own CLI, probed by `specpro check`
+
+    config = {
+        "name": "Gemini CLI",
+        "folder": ".gemini/",
+        "commands_subdir": "commands",
+    }
+
+    registrar_config = {
+        "dir": ".gemini/commands",
+        "format": "toml",
+        "extension": ".toml",
+    }
+
+
+registry.register(GeminiIntegration())

specpro_cli/integrations/opencode/__init__.py

@@ -0,0 +1,48 @@
+"""opencode — one Markdown file per command, under `.opencode/commands/`.
+
+Declared in `specs/contracts/agent-registry.md` -> 「首批 agent」: `opencode` is a
+**Markdown** agent with 落位 `.opencode/commands/`.
+
+⚠️ **This module declares constants and overrides nothing** — same rule as every other
+agent module: `MarkdownIntegration` already owns the target filename (the source name
+unchanged — specpro's templates carry the `specpro.` prefix), the `$ARGUMENTS`
+placeholder and the frontmatter/body substitution, so a subclass that restated any of
+them would be a second source for a fact the base already answers.
+
+The reference implementation also records an older flat dir for this agent
+(`.opencode/command`, singular); the contract's optional-field table lists the
+`legacy_flat_command_*` pair as used by `qodercli` alone in the first batch, so it is
+deliberately not declared here — adding it without a consumer would be machinery
+nobody reads.
+
+Source: L2 spec-kit 1.0.8.dev0 (vendored `de2a5ff`)
+[`src/specify_cli/integrations/opencode/__init__.py:9,18` (`dir=".opencode/commands"`
+· `legacy_dir=".opencode/command"`)]
+"""
+
+from __future__ import annotations
+
+from specpro_cli.integrations import registry
+from specpro_cli.integrations.base import MarkdownIntegration
+
+
+class OpencodeIntegration(MarkdownIntegration):
+    """opencode: one Markdown file per command, under `.opencode/commands/`."""
+
+    key = "opencode"
+    cli_command = "opencode"  # FR-068 — the agent's own CLI, probed by `specpro check`
+
+    config = {
+        "name": "opencode",
+        "folder": ".opencode/",
+        "commands_subdir": "commands",
+    }
+
+    registrar_config = {
+        "dir": ".opencode/commands",
+        "format": "markdown",
+        "extension": ".md",
+    }
+
+
+registry.register(OpencodeIntegration())

specpro_cli/integrations/qodercli/__init__.py

@@ -0,0 +1,54 @@
+"""Qoder CLI — skills layout under `.qoder/skills/`.
+
+Declared in `specs/contracts/agent-registry.md` -> 「首批 agent」: `qodercli` is a
+**Skills** agent with 落位 `.qoder/skills/`, plus the first-batch's only legacy
+declaration — versions before 1.24 used the flat `.qoder/commands/` layout, recorded
+via `legacy_flat_command_dir` / `legacy_flat_command_extension` for migration and
+cleanup (the fields' consumers live with the entry layer's migration path, not here:
+this module only declares the facts).
+
+`multi_install_safe = True` follows the contract's optional-field table (claude ·
+cursor-agent · qodercli): each writes under its own dot-directory, so two agents
+installed into one project cannot collide. Like claude's, it is a claim about the
+*layout*, not a feature.
+
+The invocation name is the skill directory name (`/specpro-<stem>`); `SkillsIntegration`
+already carries that (`invoke_separator = "-"` plus the dot-to-hyphen passes), so this
+module declares only what is qodercli's own.
+
+Source: L2 spec-kit 1.0.8.dev0 (vendored `de2a5ff`)
+[`src/specify_cli/integrations/qodercli/__init__.py:11,20,26` (`dir=".qoder/skills"`
+· `legacy_flat_command_dir=".qoder/commands"` · `legacy_flat_command_extension=".md"`)]
+"""
+
+from __future__ import annotations
+
+from specpro_cli.integrations import registry
+from specpro_cli.integrations.base import SkillsIntegration
+
+
+class QodercliIntegration(SkillsIntegration):
+    """Qoder CLI: one skill directory per command, under `.qoder/skills/`."""
+
+    key = "qodercli"
+    cli_command = "qoder"  # FR-068 — the agent's own CLI, probed by `specpro check`
+
+    config = {
+        "name": "Qoder CLI",
+        "folder": ".qoder/",
+        "commands_subdir": "skills",
+    }
+
+    registrar_config = {
+        "dir": ".qoder/skills",
+        "format": "markdown",
+        "extension": "/SKILL.md",
+    }
+
+    legacy_flat_command_dir = ".qoder/commands"
+    legacy_flat_command_extension = ".md"
+
+    multi_install_safe = True
+
+
+registry.register(QodercliIntegration())

specpro_cli/integrations/registry.py

@@ -0,0 +1,88 @@
+"""The integration registry — the install system's single source of truth.
+
+`specs/contracts/agent-registry.md` -> `## Registry` defines this module's job:
+a module-level `key -> integration instance` map, each integration registering itself
+on import, with the entry layer deriving everything (candidate enumeration, `--agent`
+validation, invocation resolution) from this map rather than keeping a second list.
+
+**Why a registry and not a config file**: the five format base classes already carry
+the common part of "how to transform"; what remains is per-agent processing that only
+code can express (claude's argument hints are the first case). Forcing both into a data
+file yields a data file with an escape hatch — the shape the v1.0 design was rejected
+for.
+
+⚠️ **No manifest**: spec-kit's `setup(project_root, manifest, ...)` tracks installed
+files in a manifest object. specpro's contract declares no such artifact, and the
+information it would hold — what is installed where — is derivable from the registry
+plus the `--agent` key. Adding it would be a design change, not an implementation one.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover
+    from specpro_cli.integrations.base import IntegrationBase
+
+__all__ = [
+    "clear",
+    "get",
+    "keys",
+    "register",
+    "registered",
+]
+
+# The single source of truth. Consumers read this; nothing else keeps a key list.
+_REGISTRY: dict[str, IntegrationBase] = {}
+
+
+def register(integration: IntegrationBase) -> IntegrationBase:
+    """Register `integration` under its `key`.
+
+    Two failures are refused rather than absorbed, because both would otherwise be
+    silent: an **empty key** produces an entry no `--agent` value can ever select, and
+    a **duplicate key** means the second registration overwrites the first — after
+    which which integration answers for that key depends on import order, and nothing
+    reports it.
+    """
+    key = getattr(integration, "key", "")
+    if not key:
+        raise ValueError(
+            f"{type(integration).__name__}: `key` MUST be a non-empty string "
+            "(an empty key names no `--agent` value and can never be selected)"
+        )
+    if key in _REGISTRY:
+        existing = type(_REGISTRY[key]).__name__
+        raise ValueError(
+            f"duplicate integration key {key!r}: already registered by {existing}, "
+            f"now {type(integration).__name__} — duplicate registration MUST fail "
+            "rather than silently overwrite"
+        )
+    _REGISTRY[key] = integration
+    return integration
+
+
+def registered() -> dict[str, IntegrationBase]:
+    """The whole map. Returns a copy — callers must not mutate the source of truth."""
+    return dict(_REGISTRY)
+
+
+def keys() -> list[str]:
+    """Every registered key, sorted. The value set of `--agent`."""
+    return sorted(_REGISTRY)
+
+
+def get(key: str) -> IntegrationBase | None:
+    """The integration for `key`, or `None`.
+
+    Returning `None` rather than raising is deliberate: the caller's job is to reject
+    an unknown `--agent` value with a message that lists the valid ones (FR-005), and a
+    lookup that raised would make "not found" and "lookup itself failed"
+    indistinguishable at the call site.
+    """
+    return _REGISTRY.get(key)
+
+
+def clear() -> None:
+    """Empty the registry. For tests only — there is no production caller."""
+    _REGISTRY.clear()

specpro_cli/packaged/__init__.py

@@ -0,0 +1,5 @@
+"""Packaging manifest — which assets enter the wheel.
+
+The snapshot under `assets/` is synced from the repository root at build time and
+MUST NOT be hand-maintained (Constraint 4).
+"""

specpro_cli/packaged/sync.py

@@ -0,0 +1,106 @@
+"""The asset snapshot — synced from the repository root, never hand-maintained.
+
+Constraint 4: the assets inside the wheel MUST match the repository root, and MUST be
+produced by the build rather than edited. `assets/` is `.gitignore`d, so nothing here
+is ever committed; the wheel gets it through `force-include`, which (unlike the
+`packages` channel) does not respect `.gitignore`.
+
+⚠️ **The interesting part is not the copying — it is making "snapshot equals source"
+checkable.** `specs/contracts/install-cli.md` carries the gap explicitly: without a
+reproducible check, "the snapshot matches the source" is an unverifiable statement —
+the shape Constitution Principle I calls a declaration rather than a mechanism. Two
+properties below carry that weight:
+
+- **`sync_assets` is idempotent** — running it twice leaves byte-identical results, so
+  a second run is a safe no-op rather than a rebuild.
+- **`verify_assets` re-derives the comparison from both trees** — the same function
+  the build uses, so the check and the act cannot drift apart.
+
+Both are asserted in `tests/test_asset_snapshot.py`.
+"""
+
+from __future__ import annotations
+
+import filecmp
+import shutil
+from pathlib import Path
+
+__all__ = ["ASSET_NAMES", "verify_assets", "sync_assets"]
+
+# The distributed trees. Names are relative to the repository root and to `assets/`.
+# `scripts/` is listed once and recurses: `bash/` and `powershell/` are its children,
+# so adding a third shell later needs no change here — and a shell that exists in the
+# source but not in the snapshot is caught by `verify_assets`.
+#
+# ⚠️ **This tuple is asserted LITERALLY** — `tests/test_asset_snapshot.py` →
+# `test_asset_names_is_exactly_the_three_distributed_trees`. Editing it here changes what
+# **every installed project receives**, and that assertion will say so by name. `tools/`
+# in particular is a forbidden zone: it is Layer 4 (maintainers only, FR-019), and no
+# user-facing document mentions it.
+ASSET_NAMES: tuple[str, ...] = ("commands", "templates", "scripts")
+
+
+def _repo_root_from_assets(assets_dir: Path) -> Path:
+    """`<repo>/tools/install/assets` -> `<repo>`."""
+    return assets_dir.resolve().parents[2]
+
+
+def sync_assets(repo_root: Path, assets_dir: Path) -> list[str]:
+    """Mirror the distributed trees from `repo_root` into `assets_dir`.
+
+    Idempotent: the destination trees are removed and recreated, so a second run
+    produces a byte-identical snapshot rather than layering changes. Returns the asset
+    names synced, for the build log.
+
+    A missing **top-level** asset is an error, not a silent skip — a snapshot that
+    quietly omits `templates/` would ship a CLI that installs nothing, and the wheel
+    would build successfully.
+    """
+    synced: list[str] = []
+    assets_dir.mkdir(parents=True, exist_ok=True)
+    for name in ASSET_NAMES:
+        src = repo_root / name
+        if not src.is_dir():
+            raise FileNotFoundError(
+                f"asset source missing: {src} — the snapshot must not silently omit a "
+                f"distributed tree (Constraint 4)"
+            )
+        dst = assets_dir / name
+        if dst.exists():
+            shutil.rmtree(dst)
+        shutil.copytree(src, dst)
+        synced.append(name)
+    return synced
+
+
+def verify_assets(repo_root: Path, assets_dir: Path) -> list[str]:
+    """Return the differing relative paths between the source trees and the snapshot.
+
+    The verification is **file-by-file content comparison**, not a timestamp or size
+    heuristic: `copy2` preserves mtime, so a metadata comparison would pass on a
+    snapshot whose contents had been edited by hand — which is the one failure this
+    exists to catch.
+
+    An empty list means the snapshot is current.
+    """
+    differing: list[str] = []
+    for name in ASSET_NAMES:
+        src = repo_root / name
+        dst = assets_dir / name
+        if not dst.is_dir():
+            differing.append(f"{name} (missing from the snapshot)")
+            continue
+        _compare(src, dst, name, differing)
+    return sorted(differing)
+
+
+def _compare(src: Path, dst: Path, prefix: str, out: list[str]) -> None:
+    comparison = filecmp.dircmp(src, dst)
+    out.extend(f"{prefix}/{name}" for name in comparison.left_only)
+    out.extend(f"{prefix}/{name} (stale in the snapshot)" for name in comparison.right_only)
+    out.extend(f"{prefix}/{name}" for name in comparison.diff_files)
+    # `funny_files` are entries that exist on both sides but could not be compared —
+    # reporting them as differences is the safe direction.
+    out.extend(f"{prefix}/{name} (uncomparable)" for name in comparison.funny_files)
+    for name in comparison.common_dirs:
+        _compare(src / name, dst / name, f"{prefix}/{name}", out)