@andespindola/crow-skills 0.1.0 → 0.4.0

package/crow_skills/guide.py

@@ -0,0 +1,585 @@
+"""Managed, additive agent guidance in each CLI's native always-loaded location.
+
+Only mechanisms proven with a sentinel in a fresh interactive session of the
+CLI are supported, all of them at user scope and all additive: the CLI keeps
+loading its existing base/shared prompt next to this guide. Shared prompts
+(for example a ~/.claude/CLAUDE.md symlink) and their targets are never
+written, and mechanisms that replace a base prompt are not used.
+
+Ownership: a whole file that this CLI creates (claude, gemini, devin) or a
+single marked block holding one top-level key in a config file (codex). The
+rest of a shared config file is preserved byte for byte.
+"""
+from copy import deepcopy
+from datetime import datetime, timezone
+import hashlib
+import os
+from pathlib import Path
+import re
+import stat
+import uuid
+
+try:  # Python 3.11+; required only to verify config.toml edits.
+    import tomllib
+except ImportError:  # pragma: no cover - CI and supported hosts have 3.11+
+    tomllib = None
+
+from .agents import destinations
+from .source import CrowError, SHA
+from .storage import atomic_json, checked, private_dir, read_json
+
+HEADER = "<!-- Gerenciado por crow-skills guide. Não edite; use crow-skills guide install/uninstall. -->"
+BEGIN = "# >>> crow-skills guide (gerenciado; use crow-skills guide uninstall) >>>"
+END = "# <<< crow-skills guide <<<"
+TOML_KEY = "developer_instructions"
+MAX_CONFIG = 4 * 1024 * 1024
+HEX = re.compile(r"[a-f0-9]{64}\Z")
+PRESERVED = re.compile(r"[a-f0-9]{32}/[a-z]+\.bak\Z")
+
+# path is relative to the user's home. All entries were verified on 2026-10-21
+# with a sentinel loaded in a fresh session alongside the existing base prompt.
+MECHANISMS = {
+    "claude": {"kind": "file", "path": ".claude/rules/crow-skills.md", "frontmatter": False,
+               "label": "Claude Code", "invoke": "/{name}",
+               "load": "use a ferramenta Skill com o nome da skill ou digite /nome"},
+    "codex": {"kind": "toml", "path": ".codex/config.toml", "label": "Codex CLI", "invoke": "${name}",
+              "load": "mencione $nome ou abra o SKILL.md dela pela lista de skills disponíveis"},
+    "gemini": {"kind": "file", "path": ".gemini/config/rules/crow-skills.md", "frontmatter": True,
+               "label": "Antigravity CLI, agy", "invoke": "/{name}",
+               "load": "use a ferramenta de skills do agy ou digite /nome"},
+    "devin": {"kind": "file", "path": ".devin/rules/crow-skills.md", "frontmatter": True,
+              "label": "Devin CLI", "invoke": "/devin:{name}",
+              "load": "use a ferramenta de skills do Devin ou digite /devin:nome"},
+}
+UNVERIFIED = {
+    "shared": "shared é um diretório de skills, não um CLI; não há onde gravar instruções.",
+}
+# Shared prompt files (often symlinks into ~/.config/uniflow) and their targets.
+PROTECTED = (".claude/CLAUDE.md", ".codex/AGENTS.md", ".codex/AGENTS.override.md", ".gemini/GEMINI.md",
+             ".config/devin/CLAUDE.md", ".config/devin/AGENTS.md", ".config/uniflow")
+
+
+def sha(data):
+    if data is None:
+        return None
+    if isinstance(data, str):
+        data = data.encode("utf-8")
+    return hashlib.sha256(data).hexdigest()
+
+
+def now():
+    return datetime.now(timezone.utc).isoformat()
+
+
+def select(agents):
+    if not agents:
+        raise CrowError("usage", "Selecione --agents; não há instalação implícita em todos os agentes.")
+    names = agents.split(",") if isinstance(agents, str) else list(agents)
+    result = []
+    for name in (n.strip() for n in names):
+        if name in UNVERIFIED:
+            raise CrowError("unsupported_guide", "Sem mecanismo verificado para " + name + ": " + UNVERIFIED[name])
+        if name not in MECHANISMS:
+            raise CrowError("unsupported_guide", "Sem mecanismo nativo verificado para '" + name +
+                            "'. Suportados: " + ",".join(MECHANISMS) + ".")
+        if name not in result:
+            result.append(name)
+    return result
+
+
+def protect(path, home):
+    """Refuse symlinked components, shared prompts and anything inside their targets."""
+    path = checked(path)
+    for rel in PROTECTED:
+        guard = Path(os.path.abspath(home / rel))
+        guards = {guard}
+        if os.path.lexists(guard):
+            guards.add(Path(os.path.realpath(guard)))
+        for item in guards:
+            if path == item or path.is_relative_to(item):
+                raise CrowError("protected_path", "Arquivo de prompt compartilhado (ou alvo dele) não é gravado: " + str(path))
+    return path
+
+
+def read_regular(path):
+    if not os.path.lexists(path):
+        return None
+    info = path.lstat()
+    if not stat.S_ISREG(info.st_mode):
+        raise CrowError("unsafe_destination", "Destino do guia não é arquivo regular: " + str(path))
+    if info.st_nlink > 1:
+        raise CrowError("unsafe_destination", "Destino do guia tem hard links; recusado: " + str(path))
+    if info.st_size > MAX_CONFIG:
+        raise CrowError("unsafe_destination", "Destino do guia excede o limite de leitura segura.")
+    return path.read_bytes()
+
+
+def write_atomic(path, data, mode):
+    temp = path.parent / ("." + path.name + ".crow-" + uuid.uuid4().hex)
+    try:
+        fd = os.open(temp, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0), 0o600)
+        with os.fdopen(fd, "wb") as f:
+            f.write(data)
+            f.flush()
+            os.fsync(f.fileno())
+        os.chmod(temp, mode)
+        os.replace(temp, path)
+        fd = os.open(path.parent, os.O_RDONLY)
+        try:
+            os.fsync(fd)
+        finally:
+            os.close(fd)
+    finally:
+        if os.path.lexists(temp):
+            temp.unlink()
+
+
+# --- content -----------------------------------------------------------------
+
+def clean(text):
+    return "".join(c for c in str(text) if c.isprintable()).replace("'''", "'").replace("-->", "->")
+
+
+def managed_skills(agent, home, store):
+    """crow-* packages this CLI manages for the agent (edited copies still count)."""
+    target = destinations(agent, home)[0]
+    return sorted(r["name"] for r in store.status([target], ()) if r["status"] in ("installed", "modified"))
+
+
+def present_skills(agent, home, store, catalog):
+    return [n for n in managed_skills(agent, home, store) if n in catalog]
+
+
+def render_body(agent, catalog, revision, skills):
+    mech = MECHANISMS[agent]
+    invoke = mech["invoke"].format
+    specialists = [n for n in skills if n != "crow-behaviour"]
+    example = " (por exemplo, " + invoke(name=specialists[0]) + ")" if specialists else ""
+    lines = [
+        "# Crow skills neste agente (" + mech["label"] + ")",
+        "",
+        "Gerado por crow-skills guide a partir do catálogo " + revision[:12] + ". Complementa as instruções do usuário e do projeto; havendo conflito, elas prevalecem.",
+        "",
+        "## crow-behaviour: quando aplicar",
+        "- Tarefa substantiva (várias etapas ou partes, exploração e decisões, mudanças em vários arquivos ou componentes, ou entrega que exige verificação): carregue a skill crow-behaviour ANTES de começar, por iniciativa própria, sem esperar pedido. Para carregar, " + mech["load"] + "; por exemplo, " + invoke(name="crow-behaviour") + ". Siga-a até a entrega.",
+        "- Vale também quando a entrega é só um plano, um diagnóstico ou uma revisão, ou quando não há código no diretório: depurar, auditar, investigar, migrar ou planejar uma mudança com várias etapas continua sendo tarefa substantiva.",
+        "- Conversa, pergunta factual curta ou ajuste trivial e local: responda direto, sem carregá-la.",
+        "",
+        "## Skills especialistas",
+    ]
+    lines += [
+        "- Antes de executar, consulte a lista de skills disponíveis neste agente e carregue pelo nome a especialista cujo domínio corresponde à tarefa" + example + ". Se a tarefa cruzar domínios, combine as pertinentes; a crow-behaviour coordena, a especialista executa.",
+        "- Handoffs entre skills são sugestões opcionais, não dependências; não carregue a biblioteca inteira.",
+        "- Se uma skill não estiver disponível no host, diga isso e siga sem ela; nunca simule o conteúdo de uma skill que não carregou.",
+        "",
+        "## Crow skills gerenciadas neste agente",
+    ]
+    for name in skills:
+        lines.append("- " + invoke(name=name) + " — " + clean(catalog[name].get("title") or catalog[name]["owns"]))
+    return "\n".join(lines) + "\n"
+
+
+def managed_content(agent, body):
+    """Exact bytes owned by this CLI: a whole file, or one marked TOML block."""
+    mech = MECHANISMS[agent]
+    if mech["kind"] == "toml":
+        if "'''" in body or any(not (c.isprintable() or c in "\n\t") for c in body):
+            raise CrowError("invalid_guide", "Conteúdo do guia não cabe numa string TOML literal.")
+        return BEGIN + "\n" + TOML_KEY + " = '''\n" + body + "'''\n" + END + "\n"
+    front = "---\ntrigger: always_on\n---\n\n" if mech["frontmatter"] else ""
+    return front + HEADER + "\n\n" + body
+
+
+# --- codex config.toml block ------------------------------------------------------
+
+def parse_toml(text):
+    if tomllib is None:
+        raise CrowError("unsupported_platform", "Python 3.11+ (tomllib) é necessário para editar config.toml com verificação.")
+    try:
+        return tomllib.loads(text)
+    except tomllib.TOMLDecodeError as exc:
+        raise CrowError("invalid_config", "config.toml não é TOML válido; nada alterado.") from exc
+
+
+def find_block(text):
+    """Return (start, end) offsets of the managed block, or None."""
+    begins = [m.start() for m in re.finditer(r"(?m)^" + re.escape(BEGIN) + r"\n", text)]
+    ends = [m.end() for m in re.finditer(r"(?m)^" + re.escape(END) + r"\n", text)]
+    if not begins and not ends:
+        return None
+    if len(begins) != 1 or len(ends) != 1 or ends[0] <= begins[0]:
+        raise CrowError("guide_corrupted", "Marcadores do bloco crow-skills em config.toml estão incompletos ou duplicados; revise manualmente.")
+    return begins[0], ends[0]
+
+
+def decode(data):
+    try:
+        return data.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise CrowError("invalid_config", "config.toml não é UTF-8; nada alterado.") from exc
+
+
+def toml_block(data):
+    if data is None:
+        return None
+    text = decode(data)
+    span = find_block(text)
+    return text[span[0]:span[1]] if span else None
+
+
+def toml_compose(old_bytes, old_block, new_block, body=None):
+    """Remove the existing managed block and prepend the new one; verify parse."""
+    text = decode(old_bytes) if old_bytes is not None else ""
+    if old_block is not None:
+        start, end = find_block(text)
+        text = text[:start] + text[end:]
+    base = parse_toml(text)
+    if TOML_KEY in base:
+        raise CrowError("unmanaged_conflict", "config.toml já define " + TOML_KEY + " fora do bloco gerenciado; remova ou mova antes. Nada alterado.")
+    result = (new_block or "") + text
+    parsed = parse_toml(result)
+    expected = dict(base)
+    if new_block is not None:
+        expected[TOML_KEY] = body if body is not None else parse_toml(new_block)[TOML_KEY]
+    if parsed != expected:
+        raise CrowError("invalid_config", "Edição do config.toml não preservou o restante do arquivo; nada alterado.")
+    return result.encode("utf-8")
+
+
+# --- state ----------------------------------------------------------------------
+
+def state_path(store):
+    return store.root / "guides" / "state.json"
+
+
+def validate_state(data):
+    try:
+        if data["schema_version"] != 1 or not isinstance(data["guides"], dict):
+            raise ValueError("schema")
+        for agent, record in data["guides"].items():
+            if agent not in MECHANISMS or record["mechanism"] != MECHANISMS[agent]["kind"]:
+                raise ValueError("agent")
+            if (not isinstance(record["path"], str) or not HEX.fullmatch(record["sha256"]) or
+                    not SHA.fullmatch(record["revision"]) or not isinstance(record["skills"], list) or
+                    not all(isinstance(d, str) for d in record.get("created_dirs", [])) or
+                    not isinstance(record.get("created_file", False), bool)):
+                raise ValueError("record")
+            preserved = record.get("preserved")
+            if preserved is not None and (not HEX.fullmatch(preserved["sha256"]) or
+                                          not PRESERVED.fullmatch(preserved.get("backup") or "")):
+                raise ValueError("preserved")
+    except (KeyError, TypeError, ValueError) as exc:
+        raise CrowError("invalid_state", "Estado de guias inválido; nenhuma alteração aplicada.") from exc
+    return data
+
+
+def load_state(store):
+    path = checked(state_path(store))
+    if not path.exists():
+        return {"schema_version": 1, "guides": {}}
+    return validate_state(read_json(path))
+
+
+def validate_journal(data, txid):
+    try:
+        if data["id"] != txid or data["phase"] not in ("prepared", "restoring", "committed", "rolled_back"):
+            raise ValueError("phase")
+        validate_state(data["before"])
+        validate_state(data["after"])
+        if "linked" in data and not re.fullmatch(r"[a-f0-9]{32}", data["linked"] or ""):
+            raise ValueError("linked")
+        if not isinstance(data["items"], list) or not data["items"]:
+            raise ValueError("items")
+        for item in data["items"]:
+            if item["agent"] not in MECHANISMS or item["kind"] != MECHANISMS[item["agent"]]["kind"]:
+                raise ValueError("agent")
+            if str(checked(item["path"])) != item["path"]:
+                raise ValueError("path")
+            for key in ("old_sha", "new_sha"):
+                if item[key] is not None and not HEX.fullmatch(item[key]):
+                    raise ValueError("sha")
+            for key in ("old_block", "new_block"):
+                if item[key] is not None and not isinstance(item[key], str):
+                    raise ValueError("block")
+            if item["backup"] is not None and not re.fullmatch(r"[a-z]+\.bak", item["backup"]):
+                raise ValueError("backup")
+            item.setdefault("removed_dirs", [])
+            for key in ("created_dirs", "removed_dirs"):
+                if not isinstance(item[key], list) or not all(isinstance(d, str) and str(checked(d)) == d for d in item[key]):
+                    raise ValueError("dirs")
+    except (KeyError, TypeError, ValueError) as exc:
+        raise CrowError("invalid_transaction", "Registro transacional de guia inconsistente; recuperação recusada.") from exc
+    return data
+
+
+# --- plan / apply / restore -----------------------------------------------------------
+
+def current(agent, home):
+    """(path, file bytes, managed bytes-or-text) for an agent; never follows links."""
+    mech = MECHANISMS[agent]
+    path = protect(home / mech["path"], home)
+    data = read_regular(path)
+    if mech["kind"] == "toml":
+        return path, data, toml_block(data)
+    return path, data, data.decode("utf-8", "replace") if data is not None else None
+
+
+def plan(store, action, agents, home, source=None, replace=False, overwrite=False, skills_after=None):
+    """Plan guide changes. action is "install"/"uninstall" or a {agent: action} map.
+
+    skills_after maps an agent to the managed skills it will have once a pending
+    skills transaction applies; without it the current installation is used.
+    """
+    if store.pending():
+        raise CrowError("recovery_required", "Há uma transação interrompida. Execute recover antes de alterar instalações.")
+    actions = action if isinstance(action, dict) else {agent: action for agent in agents}
+    before = load_state(store)
+    after = deepcopy(before)
+    items, changes, payload, previews = [], [], {}, {}
+    for agent in agents:
+        action = actions[agent]
+        mech = MECHANISMS[agent]
+        path, data, managed = current(agent, home)
+        record = before["guides"].get(agent)
+        if record and record["path"] != str(path):
+            raise CrowError("invalid_state", "Guia registrado em outro caminho para " + agent + "; revise o estado.")
+        managed_sha = sha(managed)
+        if action == "uninstall":
+            if not record:
+                raise CrowError("not_managed", "Guia não gerenciado para " + agent + "; nada removido.")
+            if managed_sha != record["sha256"] and not overwrite:
+                raise CrowError("local_changes", "Guia de " + agent + " alterado/ausente. Revise; --overwrite-modified autoriza backup e remoção.")
+            new_managed, body, skills = None, None, None
+            original = preserved_original(store, record)
+        else:
+            if "crow-behaviour" not in source.catalog:
+                raise CrowError("invalid_catalog", "Catálogo sem crow-behaviour.")
+            if skills_after is not None and agent in skills_after:
+                skills = [n for n in skills_after[agent] if n in source.catalog]
+            else:
+                skills = present_skills(agent, home, store, source.catalog)
+            if "crow-behaviour" not in skills:
+                raise CrowError("guide_requires_skill", "crow-behaviour não está instalada para " + agent +
+                                "; instale antes: crow-skills install crow-behaviour --agents " + agent + " --global --yes")
+            body = render_body(agent, source.catalog, source.revision, skills)
+            new_managed = managed_content(agent, body)
+            previews[agent] = new_managed
+            if record and managed_sha == sha(new_managed):
+                after["guides"][agent].update(revision=source.revision, skills=skills)
+                changes.append({"agent": agent, "path": str(path), "mechanism": mech["kind"], "action": "unchanged"})
+                continue
+            if record and managed_sha != record["sha256"] and not overwrite:
+                raise CrowError("local_changes", "Guia de " + agent + " alterado/ausente desde a instalação. Revise; --overwrite-modified autoriza backup e substituição.")
+            if not record and managed is not None and not replace:
+                raise CrowError("unmanaged_conflict", "Já existe conteúdo não gerenciado em " + str(path) + ". Revise; --replace autoriza backup e substituição.")
+        if mech["kind"] == "toml":
+            new_data = toml_compose(data, managed, new_managed, body)
+            if new_data == b"" and new_managed is None and record.get("created_file", False):
+                new_data = None  # This CLI created the file and only our block is left: remove it.
+        elif new_managed is not None:
+            new_data = new_managed.encode("utf-8")
+        else:
+            new_data = original  # Uninstall: put back what --replace displaced, or remove our file.
+        created = []
+        if new_data is not None:
+            parent = path.parent
+            while not parent.exists() and parent != home and home in parent.parents:
+                created.append(str(parent))
+                parent = parent.parent
+        mode = stat.S_IMODE(path.lstat().st_mode) if data is not None else (0o600 if mech["kind"] == "toml" else 0o644)
+        items.append({"agent": agent, "kind": mech["kind"], "path": str(path), "old_sha": sha(data), "new_sha": sha(new_data),
+                      "old_block": managed if mech["kind"] == "toml" else None,
+                      "new_block": new_managed if mech["kind"] == "toml" else None,
+                      "mode": mode, "backup": None, "created_dirs": created,
+                      "removed_dirs": record.get("created_dirs", []) if action == "uninstall" else []})
+        payload[agent] = (data, new_data)
+        if action == "uninstall":
+            after["guides"].pop(agent)
+            act = "remove"
+        else:
+            entry = {"path": str(path), "mechanism": mech["kind"], "sha256": sha(new_managed),
+                     "revision": source.revision, "skills": skills, "installed_at": now(),
+                     "created_dirs": created + (record.get("created_dirs", []) if record else [])}
+            if mech["kind"] == "toml":
+                entry["created_file"] = record.get("created_file", False) if record else data is None
+            if record and record.get("preserved"):
+                entry["preserved"] = record["preserved"]
+            elif not record and data is not None and mech["kind"] == "file":
+                entry["preserved"] = {"sha256": sha(data)}  # backup id is set by apply()
+            after["guides"][agent] = entry
+            act = "replace" if managed is not None else "install"
+        changes.append({"agent": agent, "path": str(path), "mechanism": mech["kind"], "action": act,
+                        "edits": "bloco " + TOML_KEY + " marcado" if mech["kind"] == "toml" else "arquivo próprio"})
+    return {"before": before, "after": after, "items": items, "payload": payload, "changes": changes, "previews": previews}
+
+
+def apply(store, plan_data, home, linked=None):
+    """Apply a guide plan; linked is the skills transaction this one completes."""
+    if not plan_data["items"]:
+        if plan_data["after"] != plan_data["before"]:
+            with store.lock():
+                if load_state(store) != plan_data["before"]:
+                    raise CrowError("changed_during_plan", "O estado mudou após o preview; execute novamente.")
+                atomic_json(state_path(store), plan_data["after"])
+        return None
+    with store.lock():
+        if store.pending():
+            raise CrowError("recovery_required", "Recuperação pendente; nenhuma alteração aplicada.")
+        if load_state(store) != plan_data["before"]:
+            raise CrowError("changed_during_plan", "O estado mudou após o preview; execute novamente.")
+        for item in plan_data["items"]:
+            if sha(read_regular(protect(Path(item["path"]), home))) != item["old_sha"]:
+                raise CrowError("changed_during_plan", "Um destino mudou após o preview; execute novamente.")
+        for item in plan_data["items"]:
+            # A skills transaction applied after planning may have created parents
+            # (for example ~/.claude); this transaction does not own those.
+            existing = [d for d in item["created_dirs"] if os.path.lexists(d)]
+            if existing:
+                item["created_dirs"] = [d for d in item["created_dirs"] if d not in existing]
+                entry = plan_data["after"]["guides"].get(item["agent"])
+                if entry is not None:
+                    entry["created_dirs"] = [d for d in entry["created_dirs"] if d not in existing]
+        txid = uuid.uuid4().hex
+        backups = private_dir(store.root / "guide-backups") / txid
+        backups = private_dir(backups)
+        for item in plan_data["items"]:
+            old, _ = plan_data["payload"][item["agent"]]
+            if old is not None:
+                item["backup"] = item["agent"] + ".bak"
+                write_atomic(backups / item["backup"], old, 0o600)
+                kept = plan_data["after"]["guides"].get(item["agent"], {}).get("preserved")
+                if kept is not None and "backup" not in kept:
+                    kept["backup"] = txid + "/" + item["backup"]
+        data = {"id": txid, "kind": "guide", "phase": "prepared", "created_at": now(),
+                "before": plan_data["before"], "after": plan_data["after"], "items": plan_data["items"]}
+        if linked:
+            data["linked"] = linked
+        journal = store.root / "transactions" / (txid + ".json")
+        atomic_json(journal, data)
+        try:
+            for item in plan_data["items"]:
+                path = protect(Path(item["path"]), home)
+                if sha(read_regular(path)) != item["old_sha"]:
+                    raise CrowError("changed_during_install", "Destino do guia alterado durante a instalação.")
+                _, new = plan_data["payload"][item["agent"]]
+                if new is None:
+                    if os.path.lexists(path):
+                        path.unlink()
+                    remove_empty(item["removed_dirs"])
+                else:
+                    for directory in reversed(item["created_dirs"]):
+                        os.mkdir(directory, 0o755)
+                    write_atomic(path, new, item["mode"])
+            atomic_json(state_path(store), plan_data["after"])
+            data["phase"] = "committed"
+            atomic_json(journal, data)
+        except (Exception, KeyboardInterrupt):
+            restore(store, data, home)
+            raise
+        return txid
+
+
+def restore(store, data, home):
+    """Return every guide to its pre-transaction content, refusing over later edits."""
+    state = load_state(store)
+    if state != data["before"] and state != data["after"]:
+        raise CrowError("recovery_conflict", "Estado de guias mudou após a transação; recuperação recusada.")
+    backups = store.root / "guide-backups" / data["id"]
+    operations = []
+    for item in reversed(data["items"]):
+        path = protect(Path(item["path"]), home)
+        now_data = read_regular(path)
+        now_sha = sha(now_data)
+        if now_sha == item["old_sha"]:
+            continue
+        old = None
+        if item["old_sha"] is not None:
+            old = read_regular(checked(backups / item["backup"]))
+            if sha(old) != item["old_sha"]:
+                raise CrowError("recovery_conflict", "Backup do guia ausente ou alterado; recuperação recusada.")
+        if now_sha == item["new_sha"]:
+            operations.append((path, old, item))
+        elif item["kind"] == "toml" and now_data is not None and toml_block(now_data) == item["new_block"]:
+            # Codex rewrote other parts of config.toml: undo only our block.
+            operations.append((path, toml_compose(now_data, item["new_block"], item["old_block"]), item))
+        else:
+            raise CrowError("recovery_conflict", "Guia de " + item["agent"] + " mudou após a transação; recuperação não sobrescreverá alterações.")
+    data["phase"] = "restoring"
+    atomic_json(store.root / "transactions" / (data["id"] + ".json"), data)
+    for path, content, item in operations:
+        if content is None:
+            if os.path.lexists(path):
+                path.unlink()
+        else:
+            for directory in reversed(item["removed_dirs"]):
+                if not os.path.lexists(directory):
+                    os.mkdir(directory, 0o755)
+            write_atomic(path, content, item["mode"])
+    for item in data["items"]:
+        remove_empty(item["created_dirs"])
+    atomic_json(state_path(store), data["before"])
+    data["phase"] = "rolled_back"
+    atomic_json(store.root / "transactions" / (data["id"] + ".json"), data)
+
+
+def preserved_original(store, record):
+    """Bytes that --replace displaced for this guide, verified against the state; None if nothing was displaced."""
+    kept = record.get("preserved")
+    if not kept:
+        return None
+    data = read_regular(checked(store.root / "guide-backups" / kept["backup"]))
+    if sha(data) != kept["sha256"]:
+        raise CrowError("recovery_conflict", "Backup do conteúdo original substituído por --replace está ausente ou alterado; nada removido.")
+    return data
+
+
+def remove_empty(directories):
+    """Remove directories this CLI created, deepest first, only while empty."""
+    for directory in directories:
+        try:
+            os.rmdir(checked(directory))
+        except OSError:
+            pass  # Not empty or already gone: never remove foreign content.
+
+
+def rollback(store, data, home, recovery=False):
+    if not recovery and load_state(store) != data["after"]:
+        raise CrowError("rollback_conflict", "Há mudanças posteriores nos guias; rollback antigo recusado.")
+    restore(store, data, home)
+
+
+# --- status ---------------------------------------------------------------------
+
+def status(store, home, agents):
+    state = load_state(store)
+    rows = []
+    for agent in agents:
+        if agent not in MECHANISMS:
+            continue
+        mech = MECHANISMS[agent]
+        record = state["guides"].get(agent)
+        row = {"agent": agent, "path": str(home / mech["path"]), "mechanism": mech["kind"],
+               "revision": record["revision"] if record else None, "activation_verified": False}
+        try:
+            path, data, managed = current(agent, home)
+            parsed = parse_toml(decode(data)) if mech["kind"] == "toml" and data is not None else {}
+            if record is None:
+                row["status"] = "unmanaged" if managed is not None or TOML_KEY in parsed else "absent"
+            elif managed is None:
+                row["status"] = "missing"
+            elif sha(managed) != record["sha256"]:
+                row["status"] = "modified"
+            elif mech["kind"] == "toml" and parsed.get(TOML_KEY) != parse_toml(managed).get(TOML_KEY):
+                row["status"] = "modified"
+                row["note"] = "Bloco gerenciado não está mais no nível superior do config.toml."
+            elif managed_skills(agent, home, store) != record["skills"]:
+                row["status"] = "outdated"
+                row["note"] = "Skills instaladas mudaram; execute crow-skills guide install para regenerar."
+            else:
+                row["status"] = "installed"
+        except CrowError as exc:
+            row["status"] = "unsafe"
+            row["note"] = str(exc)
+        rows.append(row)
+    return rows
+