boost-skill-cli 1.2.210__tar.gz → 1.2.211__tar.gz

{boost_skill_cli-1.2.210 → boost_skill_cli-1.2.211}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.2.210
+Version: 1.2.211
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License-Expression: Apache-2.0

{boost_skill_cli-1.2.210 → boost_skill_cli-1.2.211}/boost_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.2.210'
-__version_tuple__ = version_tuple = (1, 2, 210)
+__version__ = version = '1.2.211'
+__version_tuple__ = version_tuple = (1, 2, 211)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.2.210 → boost_skill_cli-1.2.211}/boost_cli/commands/configuration.py

@@ -208,7 +208,6 @@ def cmd_clean(argv) -> int:
             and store.points_into_store(link)
         )
 
-    configured = {t.safe_name for t in registry.list_taps()}
     # With config.json unreadable or corrupt, the tap list is DEFAULTS' empty
     # one, so every tap's cache read as stale and was deleted — on a file
     # whose bytes, under a mode-000 config, still list every one of them.
@@ -220,11 +219,13 @@ def cmd_clean(argv) -> int:
         # Skip boost's own derived artifacts. They live in the same directory and
         # end in .json, but no tap is named `rag_index` or `discovery`, so the
         # stem test alone called both stale and deleted them every run — see
-        # paths.INTERNAL_CACHE_FILES.
+        # paths.INTERNAL_CACHE_FILES. A live tap's cache spelled in another
+        # case on disk is the same file, and `stale_caches` asks the disk.
         items.extend(
             (f, "stale tap cache", f.stat().st_size)
-            for f in sorted(paths.cache_dir().glob("*.json"))
-            if f.stem not in configured and f.name not in paths.INTERNAL_CACHE_FILES
+            for f in registry.stale_caches([
+                c for c in sorted(paths.cache_dir().glob("*.json"))
+                if c.name not in paths.INTERNAL_CACHE_FILES])
         )
 
     if paths.lock_history_dir().is_dir():
@@ -1994,9 +1995,12 @@ def _install_lines(res: store.InstallResult, entry: dict) -> list[str]:
     # A workflow's copy in the skill store is how a skills-only agent reaches
     # it; an agent told nothing concludes the same as above.
     if res.skill_copy is not None:
-        lines.append("as a skill: %s" % res.skill_copy)
+        lines.append("as a skill: %s%s" % (
+            res.skill_copy, " (linked for %s)" % ", ".join(res.copy_linked)
+            if res.copy_linked else ""))
     if res.skill_note:
         lines.append(res.skill_note)
+    lines += ["skill copy not linked: %s" % why for why in res.copy_blocked]
     # Skill-only, as `boost install` prints it: a rule or workflow has no
     # score, and "quality score: 0/100" told the agent a valid one scored zero.
     if res.kind == "skill":
@@ -2111,6 +2115,14 @@ def _tool_doctor(args: dict):
         "out_of_scope_links": lambda rows: [
             "%s is linked for %s, outside its declared scope — `boost sync "
             "--prune` removes the link" % (n, a) for n, a in rows],
+        "missing_copy_links": lambda rows: [
+            "workflow %s's skill copy is not linked for %s — `boost sync` "
+            "links it" % (n, a) for n, a in rows],
+        "stale_copy_links": lambda rows: [
+            "workflow %s's skill copy is linked for %s, %s — `boost sync` "
+            "removes the link"
+            % (n, a, store.stale_copy_reason(lockfile.get_workflow(n) or {},
+                                             a)) for n, a in rows],
         "unrecorded_store": unrecorded,
     }
     for key, vals in plan.items():

{boost_skill_cli-1.2.210 → boost_skill_cli-1.2.211}/boost_cli/commands/pkg.py

@@ -281,6 +281,19 @@ def _report_result(res: store.InstallResult, no_mcp: bool = False) -> None:
         where = " (this repo)" if res.scope == "project" else ""
         out.ok("materialized%s → %s"
                % (where, " · ".join(res.linked) or "(no enabled agents)"))
+        # An agent the config keeps out gets no row, so nothing after this
+        # report would ever name it (`store.skipped_agents`) -- unless a
+        # workflow's skill copy was linked into it, which the line says.
+        copied = set(getattr(res, "copy_linked", None) or ())
+        for agent, why in getattr(res, "skipped_agents", None) or ():
+            out.dim("  %s" % agents.skip_line(agent, why,
+                                              via_copy=agent in copied),
+                    wrap=True)
+        # A subagent is not `/<name>`, and the install line alone reads as
+        # though it were (`workflows.invocation_hint`). It quotes the
+        # frontmatter `name`, a tap's text, so it is printed plain.
+        for line in getattr(res, "invocation", None) or ():
+            out.dim("  %s" % out.plain(line), wrap=True)
         _report_skill_copy(res)
         _warn_unwritable(res)
         out.ok("lock updated (.skill-lock.json)")
@@ -324,8 +337,14 @@ def _report_skill_copy(res) -> None:
     predicts. Why there is none is :func:`_warn_unwritable`'s to say, so
     update, reinstall and sync say it too."""
     copy = getattr(res, "skill_copy", None)
+    linked = getattr(res, "copy_linked", None) or []
     if copy is not None:
-        out.ok("as a skill → %s" % _tilde(copy))
+        # The agents that reach it through a link: those with no file of
+        # the workflow's own (`store.copy_link_targets`).
+        out.ok("as a skill → %s%s" % (_tilde(copy), ", linked → %s"
+                                      % " · ".join(linked) if linked else ""))
+    for agent in getattr(res, "copy_unlinked", None) or ():
+        out.dim("  %s: unlinked its skill copy" % agent, wrap=True)
 
 
 def _warn_submodules(res, stream=None) -> None:
@@ -353,9 +372,16 @@ def _warn_unwritable(res, stream=None) -> None:
     note = getattr(res, "skill_note", None)
     if note:
         out.info(note, stream=stream, wrap=True)
+    # A link to that copy something of the user's held the place of.
+    for line in getattr(res, "copy_blocked", None) or ():
+        out.warn("%s: skill copy not linked: %s" % (res.name, line),
+                 stream=stream, wrap=True)
     # Written, but not everything in the source survived the conversion.
+    # Plain: a note may quote the file it is about (a subagent's `tools`
+    # entries), and that file is a tap's.
     for line in getattr(res, "render_notes", None) or ():
-        out.warn("%s: %s" % (res.name, line), stream=stream, wrap=True)
+        out.warn("%s: %s" % (res.name, out.plain(line)), stream=stream,
+                 wrap=True)
     # A link in the skill the copy left out: the rest installed, and this
     # names the file the skill may still expect.
     for line in getattr(res, "skipped_links", None) or ():
@@ -549,9 +575,16 @@ def _install_closure(entries: list[dict], *, scope: str = scopes.SCOPE_USER,
 # ── install ──────────────────────────────────────────────────────────────
 
 def _preview_skill_copy(e: dict, seen: dict | None, as_skill: bool | None,
-                        scope: str) -> None:
+                        scope: str, written=(), narrowed: bool = False
+                        ) -> None:
     """The dry run's line for a workflow's skill copy, asked the way the run
-    decides it, so the two agree."""
+    decides it, so the two agree.
+
+    Its links go to the linking agents outside ``written``, the agents the
+    run writes the workflow's file for, and nowhere under a ``narrowed``
+    scope. A path the user's own file holds, or an agent that would reject
+    the file, is only found by the run, which leaves those out too.
+    """
     from ..core import workflows
     if scope == scopes.SCOPE_PROJECT or not store.wants_skill_copy(as_skill,
                                                                    seen):
@@ -570,7 +603,10 @@ def _preview_skill_copy(e: dict, seen: dict | None, as_skill: bool | None,
     if blocker:
         out.info("  %s" % blocker, wrap=True)
         return
-    out.info("  as a skill → %s" % _tilde(store.skill_store_dir(e["name"])))
+    linked = store.copy_link_agents(set(written), narrowed=narrowed)
+    out.info("  as a skill → %s%s"
+             % (_tilde(store.skill_store_dir(e["name"])),
+                ", linked → %s" % " · ".join(linked) if linked else ""))
 
 
 def _refuse_preview_by_policy(e: dict, scope: str, pbase, seen) -> None:
@@ -792,8 +828,10 @@ def cmd_install(argv: list[str]) -> int:
                                 e["tap"], where))
                     out.info("  materialize → %s" % " · ".join(mat))
                     if k == "workflow":
-                        _preview_skill_copy(e, seen, args.as_skill,
-                                            args.scope)
+                        _preview_skill_copy(
+                            e, seen, args.as_skill, args.scope, written=mat,
+                            narrowed=bool(only or (seen or {}).get(
+                                "only_agents")))
                     continue
                 # Same refusal as the run ("already installed", "is pinned");
                 # past it, a seen record is one --force overwrites.
@@ -1150,10 +1188,14 @@ _PLAN_LABELS = [
     ("unrecorded_store", "store dirs the lock file has lost"),
     ("missing_materializations", "missing rule/workflow files"),
     ("out_of_scope_links", "linked outside declared scope"),
+    ("missing_copy_links", "workflow skill copies missing a link"),
+    ("stale_copy_links", "workflow skill copies linked beside the "
+                         "workflow's own file or outside its --agent scope"),
 ]
 
 #: Plan keys whose items are ``(skill, agent)`` pairs rather than paths.
-_PAIR_KEYS = ("missing_links", "out_of_scope_links")
+_PAIR_KEYS = ("missing_links", "out_of_scope_links", "missing_copy_links",
+              "stale_copy_links")
 
 #: ``unrecorded_store``'s label over a lock that is corrupt or in another
 #: schema: sync re-records what a missing lock lost, and nothing over these.

{boost_skill_cli-1.2.210 → boost_skill_cli-1.2.211}/boost_cli/commands/quality.py

@@ -704,6 +704,13 @@ def cmd_doctor(argv):
                          "boost does not link into it"
                          % (aname, _tilde(spec["dir"]),
                             agents.display_name(aname)), wrap=True)
+        # A note, not an issue: `skills_only` is the user's own setting, and
+        # boost honours it. It is said because a profile copied from the
+        # antigravity row loses every subagent, command and rule with no
+        # line anywhere saying so (`store.skipped_agents`).
+        for aname in agents.claude_profile_rows():
+            rep.note("agent-config", agents.claude_profile_note(aname),
+                     wrap=True)
     for aname, err in agent_errs:
         key = "agents.%s.dir" % aname
         bad("agent-config", "%s: %s — %s, or set a path with `boost config set "
@@ -1351,6 +1358,20 @@ def cmd_doctor(argv):
                 mat_issues += 1
         if mat_issues == before:
             mat_issues += _drifted("workflow", name, entry, bad)
+        # Its skill copy's links, read as `boost sync` reads them, so the
+        # remedy named is the one that runs. A live link to the copy is
+        # expected; only a missing one, or one beside the workflow's own
+        # file or outside its `--agent` scope, is a fault.
+        for agent in store.missing_copy_links(name, entry):
+            bad("workflow", "workflow %s's skill copy is not linked for %s — "
+                "run `boost sync`" % (name, agent), wrap=True)
+            mat_issues += 1
+        for agent in store.stale_copy_links(name, entry):
+            bad("workflow", "workflow %s's skill copy is linked for %s, %s — "
+                "run `boost sync`"
+                % (name, agent, store.stale_copy_reason(entry, agent)),
+                wrap=True)
+            mat_issues += 1
     # A note, not an issue: the workflow works for every agent with a workflow
     # format. Only an agent that reads skills alone (Codex) misses it.
     unreached = store.workflows_without_skill_copy() if agents_ok else []
@@ -1375,6 +1396,20 @@ def cmd_doctor(argv):
                  % (len(off), _s(len(off)), "s" if len(off) == 1 else "",
                     ", ".join(shown), _mat_remedy(off)),
                  wrap=True)
+    # The agents the note above cannot see: excluded from the write set from
+    # the start, so they never got a row to be stale. A note for the same
+    # reason that one is -- the config said so -- and each agent once, with
+    # the items it skips, rather than a line per item.
+    left_out = store.skipped_agent_items() if agents_ok else []
+    if left_out:
+        rep.note("skipped-agents", "; ".join(
+            "%s for %s" % (agents.skip_line(agent, why, via_copy=copied),
+                           ", ".join(items[:_MAT_NOTE_SHOWN]
+                                     + (["and %d more"
+                                         % (len(items) - _MAT_NOTE_SHOWN)]
+                                        if len(items) > _MAT_NOTE_SHOWN
+                                        else [])))
+            for agent, why, copied, items in left_out), wrap=True)
     # The per-row note above answers "which row, which agent, why". This
     # answers a different question the surfaces had nowhere to put: skip every
     # row an item has and the item reached no agent at all. `rep.note`, not
@@ -1417,10 +1452,11 @@ def cmd_doctor(argv):
                 bits.append("%d workflow%s" % (quarantined_workflows,
                                                _s(quarantined_workflows)))
             note = " (%s quarantined)" % " and ".join(bits)
-        if off:
+        if off or left_out:
             # Without this the line reads as a flat contradiction of the note
             # right above it: "fully materialized" is true of the agents boost
-            # writes, and that is now a smaller set than the rows record.
+            # writes, and that is now a smaller set than the rows record --
+            # or than the agents a skill reaches.
             note += " for every agent boost writes"
         # Counted over the items that reach at least one agent. The suffix
         # above is what the note said this line contradicted -- "fully

{boost_skill_cli-1.2.210 → boost_skill_cli-1.2.211}/boost_cli/commands/safety.py

@@ -697,11 +697,18 @@ def cmd_quarantine(argv):
         else:
             skipped: list[str] = []
             theirs: list[str] = []
+            unlinked: list[str] = []
             restored = store.release_materialized(kind, name, entry,
                                                   skipped=skipped,
-                                                  foreign=theirs)
+                                                  foreign=theirs,
+                                                  problems=unlinked)
             out.ok("released %s %s (restored: %s)"
                    % (kind, name, ", ".join(restored) or "none"))
+            # Install's words for a link to its skill copy something of the
+            # user's holds the place of.
+            for line in unlinked:
+                out.warn("%s: skill copy not linked: %s" % (name, line),
+                         wrap=True)
             for d in skipped:
                 out.info("not restored as a skill: %s now holds something "
                          "else — left alone" % paths.tilde(d), wrap=True)

{boost_skill_cli-1.2.210 → boost_skill_cli-1.2.211}/boost_cli/commands/taps.py

@@ -102,7 +102,8 @@ def _print_held(plan: list[dict]) -> int:
     rc = 0
     for row in plan:
         if row.get("skipped"):
-            out.info(out.role("%s already tapped" % row["name"], "muted"))
+            out.info(out.role(registry.already_tapped(
+                row["name"], row.get("tapped_as", row["name"])), "muted"))
         elif not row.get("todo"):
             out.warn("would not tap %s: %s" % (row["name"], row["error"]),
                      wrap=True)
@@ -144,7 +145,7 @@ def _skip_if_already_tapped(spec: str) -> bool:
                 and registry.same_source(t.url, url)), None)
     if hit is None:
         return False
-    out.info(out.role("%s already tapped" % hit.name, "muted"))
+    out.info(out.role(registry.already_tapped(name, hit.name), "muted"))
     return True
 
 
@@ -168,7 +169,8 @@ def _tap_all(urls: list[str], jobs: int | None,
     for res in results:
         name = res["name"]
         if res.get("skipped"):
-            out.info(out.role("%s already tapped" % name, "muted"))
+            out.info(out.role(registry.already_tapped(
+                name, res.get("tapped_as", name)), "muted"))
             continue
         if not res.get("ok"):
             out.warn("could not tap %s: %s" % (name, res.get("error", "")),

{boost_skill_cli-1.2.210 → boost_skill_cli-1.2.211}/boost_cli/core/agents.py

@@ -709,6 +709,96 @@ WITHDRAWN_REASONS = (REASON_SKILLS_ONLY, REASON_NO_COMMAND_FORMAT)
 #: ladder and to none of these would be classified by silence.
 UNREMEDIED_REASONS = (REASON_UNCONFIGURED, REASON_UNKNOWN)
 
+#: The agent-row key behind each reason one flag of the row decides, so a
+#: report can say where the decision lives. The other two have no key: an
+#: agent missing from the config, and the ladder's fallback.
+REASON_FLAGS = {REASON_SKILLS_ONLY: "skills_only",
+                REASON_NO_COMMAND_FORMAT: "workflows",
+                REASON_DISABLED: "enabled",
+                REASON_NO_PROJECT_SCOPE: "project_scope"}
+
+
+def _withdrawn_by_boost(agent: str, reason: str, key: str) -> bool:
+    """Whether ``agent`` skips for a :data:`WITHDRAWN_REASONS` reason only
+    because its built-in row says so: ``key`` holds :func:`flag_default`'s
+    value. A row the config added cannot -- its default is
+    :data:`FLAG_DEFAULTS`', which takes rules and workflows -- and neither
+    can a built-in row the user set the other way."""
+    if reason not in WITHDRAWN_REASONS:
+        return False
+    spec = known_agents().get(agent)
+    return spec is not None and spec[key] == flag_default(agent, key)
+
+
+def skip_line(agent: str, reason: str, via_copy: bool = False) -> str:
+    """One agent an item was not written into, and why, for a report.
+
+    ``claude-personal: takes skills only (agents.claude-personal.skills_only)
+    — not written``. The key is named because the skip is the config's
+    decision, and the row is where to read it. Not for a format boost
+    withdrew and the row still has as boost set it -- ``antigravity``'s
+    ``skills_only``, ``windsurf``'s ``workflows: false``: flipping that writes
+    a file the agent never loads, :data:`config.DEFAULTS` says why at the key
+    itself, and a line printed on every install would read as an invitation.
+
+    ``via_copy``: the agent does reach the item, through the link to a
+    workflow's skill copy (``store.copy_link_targets``) -- so it ends "skill
+    copy only" rather than "not written", which beside the install's
+    "linked → windsurf" line read as a contradiction.
+    """
+    key = REASON_FLAGS.get(reason)
+    where = (" (agents.%s.%s)" % (agent, key)
+             if key and not _withdrawn_by_boost(agent, reason, key) else "")
+    return "%s: %s%s — %s" % (agent, reason, where,
+                              "skill copy only" if via_copy else "not written")
+
+
+def claude_profile_rows() -> list[str]:
+    """Config-added agents that look like a Claude Code profile and take
+    skills only -- the rows ``boost doctor`` offers ``skills_only false`` to.
+
+    The marker is ``.claude.json`` in the row's dotdir: Claude Code keeps it
+    at ``$CLAUDE_CONFIG_DIR/.claude.json`` for a relocated profile (and at
+    ``~/.claude.json`` otherwise, which is why ``claude-code``'s own
+    ``~/.claude`` does not hold one). A profile is Claude Code, so it reads
+    ``agents/``, ``commands/`` and ``rules/`` like ``~/.claude`` does; a row
+    copied from the ``antigravity`` template carries that agent's
+    ``skills_only`` and gets none of them. A built-in row is never asked: its
+    flags are boost's own, and :data:`config.DEFAULTS` says why at each.
+
+    The probe is :func:`os.path.isfile`, which answers False on any
+    ``OSError``. ``Path.is_file`` raises PermissionError on Python 3.12 and
+    3.13 for a path under a dir the user cannot search, and doctor asks this
+    on every run -- so a row pointing there ended the report in a crash, when
+    doctor's own agent-dir check names exactly that problem.
+    """
+    defaults: dict = config.DEFAULTS["agents"]  # type: ignore[assignment]
+    return [name for name, spec in known_agents().items()
+            if name not in defaults and spec["enabled"]
+            and spec["skills_only"]
+            and os.path.isfile(spec["dir"].parent / ".claude.json")]
+
+
+def claude_profile_note(name: str) -> str:
+    """`boost doctor`'s line for one of :func:`claude_profile_rows`.
+
+    It names ``skills_only false`` and ``boost sync``, and -- when the row
+    takes project scope, which a config-added row does unless it says
+    otherwise -- ``project_scope false`` first: in a repo Claude Code reads
+    ``<repo>/.claude/`` whatever profile it runs under, so a project install
+    for the row lands in ``<repo>/.claude-personal/``, which nothing loads.
+    Named, never set: the row is the user's (no config is rewritten).
+    """
+    spec = known_agents()[name]
+    note = ("agents.%s looks like a Claude Code profile — `boost config set "
+            "agents.%s.skills_only false` then `boost sync` gives it agents/, "
+            "commands/ and rules/" % (name, name))
+    if spec["project_scope"]:
+        note += ("; run `boost config set agents.%s.project_scope false` "
+                 "first — in a repo Claude Code reads `.claude/` under any "
+                 "profile, never `%s/`" % (name, spec["dir"].parent.name))
+    return note
+
 
 def materialization_skip_reason(kind: str, base, agent) -> str | None:
     """Why :func:`materialization_is_written` refuses, or ``None`` if it does

{boost_skill_cli-1.2.210 → boost_skill_cli-1.2.211}/boost_cli/core/config.py

@@ -128,10 +128,13 @@ DEFAULTS = {
     "policy_enforce": True,
     # A workflow (a subagent, or a slash command with a description) also gets
     # a copy in the canonical store, ``~/.agents/skills/<name>/SKILL.md``, so
-    # agents that read skills and no workflow format — Codex — can reach it.
-    # `boost install --as-skill/--no-as-skill` overrides it per install, and
-    # that choice sticks; with neither flag an install follows this. See
-    # store._skill_copy.
+    # agents that read skills and no workflow format can reach it: Codex reads
+    # the store directly, and the copy is linked into each linking agent that
+    # got no workflow file of its own (windsurf, antigravity, a `skills_only`
+    # profile) -- never into one that holds the workflow's file, which would
+    # show it the procedure twice. `boost install --as-skill/--no-as-skill`
+    # overrides it per install, and that choice sticks; with neither flag an
+    # install follows this. See store._skill_copy and store.copy_link_targets.
     "workflows_as_skills": True,
     # No `telemetry` key: it sat here for releases with no reader, so `config
     # set telemetry true` reported success for a feature that does not

{boost_skill_cli-1.2.210 → boost_skill_cli-1.2.211}/boost_cli/core/gitutil.py

@@ -452,6 +452,15 @@ def owned_clone(repo: Path) -> bool:
     agrees it is the top of its work tree. The last is what stops a plain
     directory there (the builtin tap) from resolving to an enclosing repo — a
     ``$HOME`` kept in git — and cleaning *that*.
+
+    git names its top in the case on disk, and ``resolve()`` keeps whatever
+    case it was given, so on APFS a tap configured as ``Leonxlnx/x`` over a
+    clone at ``repos/leonxlnx__x`` failed the last check and was never
+    cleaned. A respelling that differs **by case alone** is put to the
+    filesystem; any other is refused without asking, because ``samefile``
+    compares only ``(st_dev, st_ino)`` and a mount that reports inode 0 (some
+    FAT, SMB and FUSE ones) calls every two paths on it one file — which
+    would let the enclosing repo through.
     """
     try:
         root = paths.repos_dir().resolve()
@@ -467,7 +476,9 @@ def owned_clone(repo: Path) -> bool:
     if proc.returncode != 0:
         return False
     try:
-        return Path(proc.stdout.strip()).resolve() == real
+        top = Path(proc.stdout.strip()).resolve()
+        return top == real or (str(top).casefold() == str(real).casefold()
+                               and os.path.samefile(top, real))
     except OSError:
         return False
 

{boost_skill_cli-1.2.210 → boost_skill_cli-1.2.211}/boost_cli/core/lockfile.py

@@ -1120,9 +1120,11 @@ def agent_names(kind: str, entry: dict | None) -> list[str]:
     two presentations of the same fact that happened to disagree.
 
     A workflow's skill copy (:func:`is_skill_copy`) is a row too, and names no
-    agent: it sits in the canonical store, reached by whichever agents read
-    that. It is left out here, because ``None`` sorted beside agent names
-    raises, and printing it as ``?`` names an agent that does not exist.
+    agent: it sits in the canonical store, reached by the agents that read
+    that and, through a link, by the linking agents that got no workflow file
+    of their own (``store.copy_link_targets``, derived and never recorded).
+    It is left out here, because ``None`` sorted beside agent names raises,
+    and printing it as ``?`` names an agent that does not exist.
     """
     if not entry:
         return []

{boost_skill_cli-1.2.210 → boost_skill_cli-1.2.211}/boost_cli/core/projectlock.py

@@ -101,10 +101,18 @@ def mutate(base, fn: Callable[[dict], bool | None]) -> bool:
     project` runs used to each read, add their row and write, and the second
     write dropped the first's row — leaving a copy on disk that install then
     refused and uninstall disowned. ``fn`` returning False skips the write;
-    returns whether it wrote. Refuses over a corrupt lock (:func:`write`).
+    returns whether it wrote.
+
+    Refuses over a corrupt lock before ``fn`` runs, so a no-op ``fn`` cannot
+    report "nothing to change" about a record boost cannot read. That check
+    is a read too, and it belongs here under the guard: on Windows a read
+    that lands inside another process's ``os.replace`` is refused
+    (Permission denied), and ``remove_skill`` doing it unlocked reported a
+    sound lock as corrupt on windows-latest.
     """
     with util.file_lock(guard_path(base), what="the project lock",
                         strict=False):
+        refuse_corrupt(base)
         lock = read(base)
         if fn(lock) is False:
             return False
@@ -239,8 +247,9 @@ def remove_skill(base, name: str) -> bool:
 
     Refuses over a corrupt lock even though it reads as holding nothing:
     "not present" would be a false answer about a record boost cannot read.
+    :func:`mutate` makes that check under the lock; only the existence probe
+    runs unlocked, so a missing lock creates no ``.boost/`` sidecar.
     """
-    refuse_corrupt(base)
     if not exists(base):
         return False    # nothing to remove, and no reason to create .boost/