boost-skill-cli 1.0.297__tar.gz → 1.0.299__tar.gz

{boost_skill_cli-1.0.297 → boost_skill_cli-1.0.299}/.vale/styles/config/vocabularies/boost/accept.txt

@@ -89,7 +89,10 @@ toolchain
 toolkits
 traceback
 tracebacks
+typosquat
+typosquatted
 unkilled
+unlinking
 unregister
 unstaged
 untap

{boost_skill_cli-1.0.297 → boost_skill_cli-1.0.299}/CLAUDE.md

@@ -101,8 +101,15 @@ line coverage. Target `boost_cli/core` behavior with assertions, not just import
   (structural pattern matching, `X | Y` runtime unions in non-annotation context).
 - **Three item kinds, one scanner.** `core/catalog.scan_dir` indexes `skill`
   (SKILL.md), `rule` (.mdc/.cursorrules/.windsurfrules/.clinerules), and
-  `workflow` (commands/agents/workflows Markdown). **Only `skill` installs** —
-  `store.install` refuses non-skill kinds; rules/workflows are search/tap-only.
+  `workflow` (commands/agents/workflows Markdown). **All three install**, and
+  each honors `scope`: `store.install` dispatches to `_install_rule` /
+  `_install_workflow` and only raises for a kind outside those three. They land
+  in different places, which is the part to get right — a skill is copied into
+  the canonical store and symlinked out, a rule is materialised into each
+  agent's context file (`rules.CONTEXT_FILES`, e.g. `~/.claude/CLAUDE.md`), and
+  a workflow is rendered per agent (TOML for Gemini, see
+  `workflows.TOML_COMMAND_AGENTS`). Installing a rule therefore edits a file the
+  user reads every session — treat it as more invasive than a skill, not less.
 
 ## Parallel work & concurrent loops
 

{boost_skill_cli-1.0.297 → boost_skill_cli-1.0.299}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.0.297
+Version: 1.0.299
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE
@@ -911,7 +911,9 @@ boost bundle dump > Boostfile     # everyone else runs: boost bundle install
 [`docs/index.html`](docs/index.html), and for every flag of every command see
 [`docs/commands.html`](docs/commands.html). For a GIF of one flagship command
 per group — recorded live with [VHS](https://github.com/charmbracelet/vhs) — see
-[`docs/carousel.html`](docs/carousel.html).
+[`docs/carousel.html`](docs/carousel.html). For how boost is put together
+internally — C4 diagrams of the context, containers, engine components and the
+install path — see [`docs/architecture/`](docs/architecture/README.md).
 
 | Group | Commands |
 |---|---|

{boost_skill_cli-1.0.297 → boost_skill_cli-1.0.299}/README.md

@@ -195,7 +195,9 @@ boost bundle dump > Boostfile     # everyone else runs: boost bundle install
 [`docs/index.html`](docs/index.html), and for every flag of every command see
 [`docs/commands.html`](docs/commands.html). For a GIF of one flagship command
 per group — recorded live with [VHS](https://github.com/charmbracelet/vhs) — see
-[`docs/carousel.html`](docs/carousel.html).
+[`docs/carousel.html`](docs/carousel.html). For how boost is put together
+internally — C4 diagrams of the context, containers, engine components and the
+install path — see [`docs/architecture/`](docs/architecture/README.md).
 
 | Group | Commands |
 |---|---|

{boost_skill_cli-1.0.297 → boost_skill_cli-1.0.299}/boost_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.0.297'
-__version_tuple__ = version_tuple = (1, 0, 297)
+__version__ = version = '1.0.299'
+__version_tuple__ = version_tuple = (1, 0, 299)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.0.297 → boost_skill_cli-1.0.299}/boost_skill_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.0.297
+Version: 1.0.299
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE
@@ -911,7 +911,9 @@ boost bundle dump > Boostfile     # everyone else runs: boost bundle install
 [`docs/index.html`](docs/index.html), and for every flag of every command see
 [`docs/commands.html`](docs/commands.html). For a GIF of one flagship command
 per group — recorded live with [VHS](https://github.com/charmbracelet/vhs) — see
-[`docs/carousel.html`](docs/carousel.html).
+[`docs/carousel.html`](docs/carousel.html). For how boost is put together
+internally — C4 diagrams of the context, containers, engine components and the
+install path — see [`docs/architecture/`](docs/architecture/README.md).
 
 | Group | Commands |
 |---|---|

{boost_skill_cli-1.0.297 → boost_skill_cli-1.0.299}/boost_skill_cli.egg-info/SOURCES.txt

@@ -114,6 +114,11 @@ docs/mcp-hub.html
 docs/rag-architecture.md
 docs/roadmap.html
 docs/.claude/settings.local.json
+docs/architecture/README.md
+docs/architecture/c4-components-core.md
+docs/architecture/c4-containers.md
+docs/architecture/c4-context.md
+docs/architecture/c4-dynamic-install.md
 docs/carousel/gifs/distill.gif
 docs/carousel/gifs/doctor.gif
 docs/carousel/gifs/explain.gif
@@ -217,6 +222,7 @@ docs/roadmap/items/install-resolves-skill-dependencies.md
 docs/roadmap/items/install-scope-user-or-project.md
 docs/roadmap/items/installed-skill-trust-audit.md
 docs/roadmap/items/integrity-verification-boost-verify.md
+docs/roadmap/items/internal-architecture-diagrams.md
 docs/roadmap/items/invocation-pid-logging-for-crash-correlation.md
 docs/roadmap/items/journal-rotation-race-and-handle-leak.md
 docs/roadmap/items/layering-guard-import-linter.md
@@ -500,6 +506,7 @@ tests/unit/test_mcphost.py
 tests/unit/test_minisign.py
 tests/unit/test_mutation_hardening.py
 tests/unit/test_mutation_shards.py
+tests/unit/test_mutation_subfile_shards.py
 tests/unit/test_mutmut_source_paths.py
 tests/unit/test_nethttp.py
 tests/unit/test_output.py

boost_skill_cli-1.0.299/docs/architecture/README.md

@@ -0,0 +1,45 @@
+# boost architecture
+
+C4-model diagrams of how boost is put together, in Mermaid so they render on GitHub and stay
+reviewable in a diff. Read them in order — each one opens a box the previous one drew.
+
+| Level | Diagram | Answers |
+|-------|---------|---------|
+| 1 | [System context](c4-context.md) | Who uses boost and what it talks to |
+| 2 | [Containers](c4-containers.md) | The processes and the directories on disk |
+| 3 | [Core components](c4-components-core.md) | How the 45 engine modules group, and the layering rule |
+| — | [Dynamic: install](c4-dynamic-install.md) | What `boost install` actually does, step by step |
+
+Subsystem designs live beside these rather than inside them:
+[rag-architecture.md](../rag-architecture.md) covers retrieval in depth, and
+[DEBUGGING.md](../DEBUGGING.md) covers the diagnostic surfaces.
+
+## The three invariants worth knowing before you read code
+
+**1. Layering is enforced.** `cli → commands → core`, checked by `import-linter` in `make lint` and
+CI. `core/` is the engine and the only layer the mutation gate targets; `commands/` is thin glue.
+Putting behaviour in the command layer means it is covered by neither.
+
+**2. Paths resolve at call time.** `core/paths.py` reads `$HOME` (or `$BOOST_HOME`) on every call
+rather than caching at import. That is not incidental — it is what lets the whole test suite point
+a temporary directory at `HOME` and exercise real install paths without touching your machine.
+
+**3. Optional is always optional.** Dense retrieval falls back to BM25; the AI bridge falls back to
+heuristics. The shipped runtime is stdlib-only and `[project].dependencies` is empty. Any new
+dependency belongs behind an extra, and any new path through it needs a degraded branch.
+
+## Keeping these honest
+
+These diagrams are hand-written, not generated, so they can drift. They describe *structure* —
+layers, boundaries, which component owns which decision — rather than anything that changes with a
+routine edit, so drift should be rare and visible. The claims most worth re-checking when the
+engine changes:
+
+- the component groupings in [c4-components-core.md](c4-components-core.md), against
+  `ls boost_cli/core/`
+- the layering contract, against `[tool.importlinter]` in `pyproject.toml`
+- the install sequence, against `core/store.py::install`
+- the agent-target split, against `agents.linking_agents()` and `agents.native_store_agents()`
+
+Command-level reference is generated and lives elsewhere: `docs/commands.html` is built from the
+`COMMANDS` registry by `scripts/build_command_reference.py`. Do not hand-edit it.

boost_skill_cli-1.0.299/docs/architecture/c4-components-core.md

@@ -0,0 +1,92 @@
+# C4 Level 3 — Components of the core engine
+
+`boost_cli/core/` is the engine: 45 modules that hold all the behaviour. This diagram groups them
+into the ten components that actually have distinct responsibilities, and shows the one-way
+dependency rule the build enforces.
+
+```mermaid
+C4Component
+  title Component Diagram — boost_cli/core
+
+  Container(cli, "boost_cli/cli.py", "Python", "COMMANDS registry; lazy dispatch")
+  Container(cmds, "boost_cli/commands/", "Python", "Thin CLI glue — parse, format, delegate")
+
+  Container_Boundary(core, "boost_cli/core — the engine") {
+    Component(registry, "Registry & catalog", "registry, catalog, frontmatter, staleness", "Clones taps; classifies skill / rule / workflow")
+    Component(bm25, "BM25 retrieval", "rag", "Always-on, zero-dependency full-content index")
+    Component(dense, "Dense retrieval", "dense, embed", "Optional vectors behind the [rag] extra")
+    Component(ai, "AI bridge", "ai, faithfulness, stackprobe, imperative", "LLM-assisted paths; heuristics when absent")
+    Component(resolve, "Resolution", "resolve, scopes, updatediff", "Dependency closure; user vs project scope")
+    Component(store, "Store & lock", "store, lockfile, projectlock, integrity, installscan", "Install, uninstall, sync; owns the lock file")
+    Component(targets, "Agent targets", "agents, rules, workflows, adapters, claude_settings, mcphost", "Per-agent formats, linking and MCP grammar")
+    Component(trust, "Trust & safety", "provenance, minisign, ed25519, secretscan, injectscan, typosquat, capabilities, policy, trustaudit", "Signing, scanning and governance")
+    Component(found, "Foundation", "paths, config, util, output", "Path resolution at call time; rendering")
+    Component(obs, "Diagnostics & I/O", "logs, journal, gitutil, nethttp", "Rotating log, pulse feed, git and HTTP")
+  }
+
+  Rel(cli, cmds, "Lazy-imports one module per invocation")
+  Rel(cmds, registry, "Taps and indexes")
+  Rel(cmds, bm25, "Searches")
+  Rel(cmds, store, "Installs and syncs")
+  Rel(cmds, trust, "Audits")
+  Rel(bm25, registry, "Indexes the catalog of")
+  Rel(dense, bm25, "Falls back to")
+  Rel(ai, bm25, "Reranks results from")
+  Rel(resolve, registry, "Looks up dependencies in")
+  Rel(store, resolve, "Expands the request with")
+  Rel(store, targets, "Links and materialises through")
+  Rel(store, trust, "Gates the install on")
+  Rel(registry, obs, "Clones via")
+
+  UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
+```
+
+Every component depends on **Foundation** (`paths`, `config`, `util`, `output`); those arrows are
+omitted because drawing ten of them into one box hides the structure rather than showing it.
+
+## The layering rule is enforced, not aspirational
+
+`import-linter` runs in `make lint` and CI, with the contract declared in `pyproject.toml`:
+
+```text
+layers = ["cli", "commands", "core"]
+```
+
+Higher layers may import lower ones, never the reverse. `core/` must import neither `commands/` nor
+`cli`, and `commands/` must not reach up into `cli`. There is exactly one allowlisted exception —
+`boost_cli.commands.configuration -> boost_cli.cli` — because `boost completions` reads the
+`COMMANDS` registry, which lives in `cli.py` by design. Any other upward import fails the build.
+
+This is why behaviour belongs in `core/` and not in `commands/`: the mutation gate targets
+`boost_cli/core` at an 80% kill floor, so logic placed in the command layer is covered by neither
+mutation testing nor the layering contract.
+
+## Why retrieval is two components, not one
+
+`rag.py` is the always-on BM25 engine — pure stdlib, full-content index, auto-builds on first
+search. It is what the required `eval` gate floors at recall@k ≥ 0.85 over the pinned golden set.
+
+`dense.py` is optional vector retrieval, active only when both the `[rag]` extra and an embeddings
+key are present, and falling back to BM25 otherwise. Modelling them as one "search" component would
+hide the property that matters most: **the zero-dependency path is the default, and the optional
+one can never be a hard requirement.**
+
+The same shape governs the AI bridge. `ai.py` shells out to the `claude` CLI or
+`ANTHROPIC_API_KEY` when available and degrades to heuristics when not, so `search --smart`,
+`explain` and `distill` get worse without a key, never broken.
+
+## Three item kinds, one scanner
+
+`catalog.scan_dir` walks a tap's clone and classifies every file into one of three kinds:
+
+| Kind | Recognised by | Installable |
+|------|---------------|-------------|
+| `skill` | `SKILL.md` | yes — copied into the canonical store |
+| `rule` | `.mdc`, `.cursorrules`, `.windsurfrules`, `.clinerules` | yes — materialised into each agent's context file |
+| `workflow` | Markdown under `commands/`, `agents/`, `workflows/` | yes — rendered per agent, TOML for Gemini |
+
+Per-agent *formats* are pure functions in `core/`: `rules.CONTEXT_FILES` maps an agent with no
+rules directory to its context file, and `workflows.TOML_COMMAND_AGENTS` marks the agents whose
+slash commands are TOML. Gemini's `commands/` slot is `.toml`
+(`workflows.render_gemini_command`) while its `agents/` slot stays verbatim Markdown — getting that
+backwards produces a file the agent silently never loads.

boost_skill_cli-1.0.299/docs/architecture/c4-containers.md

@@ -0,0 +1,78 @@
+# C4 Level 2 — Containers
+
+The deployable and persistent pieces inside boost. Everything here lives on one machine: boost has
+no server side, and every path is resolved at call time from `$HOME` (or `$BOOST_HOME`) by
+`core/paths.py`, which is what makes `HOME=<tempdir>` sandboxing work in tests.
+
+```mermaid
+C4Container
+  title Container Diagram — boost
+
+  Person(dev, "Developer", "Runs boost commands")
+  System_Ext(agents, "AI coding agents", "Claude Code, Cursor, Windsurf, Gemini CLI")
+  System_Ext(github, "GitHub", "Registry repos and skill sources")
+
+  Container_Boundary(boost, "boost") {
+    Container(cli, "boost CLI", "Python 3.9+, stdlib only", "78 commands in 8 groups; lazy-imports one module per invocation")
+    Container(mcp, "MCP server", "JSON-RPC over stdio", "Exposes search/install/doctor as agent tools")
+    Container(web, "boost serve", "http.server", "Local read-only web UI")
+    Container(engine, "core engine", "Python package", "Catalog, retrieval, store, trust — see the component diagram")
+  }
+
+  Boundary(state, "boost state — ~/.boost") {
+    ContainerDb(repos, "repos/", "shallow git clones", "Tapped registries")
+    ContainerDb(cache, "cache/", "JSON", "Catalogs built from frontmatter")
+    ContainerDb(statedir, "state/", "JSON", "Pins, policy, profiles, snapshots")
+  }
+
+  Boundary(installed, "installed skills") {
+    ContainerDb(store, "~/.agents/skills", "files + .skill-lock.json v3", "Canonical store — single source of truth")
+    ContainerDb(links, "~/.claude, ~/.cursor, ~/.windsurf", "symlinks into the store", "Three linking agents")
+    ContainerDb(gemini, "~/.gemini", "GEMINI.md + TOML commands", "Rules and workflows only")
+  }
+
+  Rel(dev, cli, "Invokes")
+  Rel(agents, mcp, "Calls tools", "stdio")
+  Rel(cli, engine, "Delegates to")
+  Rel(mcp, engine, "Delegates to")
+  Rel(web, engine, "Reads from")
+  Rel(engine, github, "Clones and searches", "git, REST")
+  Rel(engine, repos, "Clones taps into")
+  Rel(engine, cache, "Indexes catalogs into")
+  Rel(engine, statedir, "Persists policy and pins")
+  Rel(engine, store, "Copies skills into")
+  Rel(engine, links, "Symlinks out to")
+  Rel(engine, gemini, "Materialises rules and commands")
+  Rel(agents, store, "Reads directly", "Gemini CLI only")
+  Rel(agents, links, "Reads")
+
+  UpdateLayoutConfig($c4ShapeInRow="2", $c4BoundaryInRow="2")
+```
+
+## Four agent targets, but only three get symlinks
+
+Gemini CLI implements the Agent Skills standard and discovers `~/.agents/skills` — the canonical
+store — *directly*, so it is configured with `links_skills: false`. Linking into `~/.gemini/skills`
+as well would put one skill in two of its discovery tiers, where the `.agents` alias out-ranks
+whatever was linked, costing a "Skill conflict detected" line per skill per session and buying
+nothing.
+
+That distinction is load-bearing for anything you write:
+
+- Iterate `agents.linking_agents()` for anything symlink-shaped — linking, unlinking, stale-link
+  sweeps, coverage counts.
+- Use `agents.enabled_agents()` for rules and workflows, which materialise into `~/.gemini/` like
+  any other agent's dotdir. `agents.native_store_agents()` is the complement, for reporting.
+
+## Why the canonical store exists
+
+One copy of each skill lives in `~/.agents/skills`; every linking agent gets a symlink to it. That
+is what makes "install once, available everywhere" true without N copies drifting apart, and it is
+why `.skill-lock.json` lives beside the store rather than per-agent. Uninstall removes the copy and
+sweeps the links; `boost sync` reconciles reality against the lock.
+
+## The state directory is not the store
+
+`~/.boost` is *derived* data — clones, indexes and preferences that boost can rebuild. `~/.agents`
+is *user* data: the skills themselves. Deleting `~/.boost` costs a re-tap and a re-index; deleting
+`~/.agents/skills` uninstalls everything. Keeping them apart is deliberate.

boost_skill_cli-1.0.299/docs/architecture/c4-context.md

@@ -0,0 +1,45 @@
+# C4 Level 1 — System context
+
+Who uses boost, and what it talks to. This is the only diagram that shows boost as a single box;
+every other diagram in this directory opens that box.
+
+```mermaid
+C4Context
+  title System Context — boost
+
+  Person(dev, "Developer", "Installs and governs agent skills")
+
+  System(boost, "boost", "CLI + MCP server that finds, installs and governs the skill, rule and workflow files AI coding agents run on")
+
+  System_Ext(agents, "AI coding agents", "Claude Code, Cursor, Windsurf, Gemini CLI")
+  System_Ext(github, "GitHub", "Hosts registry repos (taps) and skill sources")
+  System_Ext(llm, "Anthropic API / claude CLI", "Optional LLM-assisted ranking and authoring")
+  System_Ext(embed, "Voyage / OpenAI embeddings", "Optional vectors for dense retrieval")
+  System_Ext(pypi, "PyPI", "Distributes the boost-skill-cli package")
+
+  Rel(dev, boost, "Runs commands", "terminal")
+  Rel(dev, pypi, "Installs boost from", "pipx / pip")
+  Rel(agents, boost, "Calls boost_search / boost_install", "MCP, JSON-RPC over stdio")
+  Rel(boost, github, "Clones taps and searches code", "git, REST")
+  Rel(boost, agents, "Writes skills, rules and slash-commands", "files + symlinks")
+  Rel(boost, llm, "Ranks, explains, distills", "optional, degrades to heuristics")
+  Rel(boost, embed, "Embeds the catalog", "optional, falls back to BM25")
+
+  UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
+```
+
+## What the boundaries mean
+
+**boost never requires the network to be useful.** Both external AI services are optional and
+degrade rather than fail: `core/ai.py` falls back to heuristics when neither the `claude` CLI nor
+`ANTHROPIC_API_KEY` is present, and `core/dense.py` falls back to BM25 when the `[rag]` extra or an
+embeddings key is missing. Only tapping and installing genuinely need GitHub.
+
+**The agents are consumers, not integrations.** boost does not drive an agent or run inside one.
+It writes files into the locations agents already read, so a skill installed once is visible to
+every configured agent with no per-agent wiring — see
+[c4-containers.md](c4-containers.md) for where those files land.
+
+**The shipped runtime is stdlib-only.** `[project].dependencies` is empty by design, so the arrow
+to PyPI carries a package with no runtime dependency closure of its own. Everything optional lives
+behind an extra.

boost_skill_cli-1.0.299/docs/architecture/c4-dynamic-install.md

@@ -0,0 +1,63 @@
+# C4 Dynamic — what `boost install` actually does
+
+The install path is where most of the engine meets. This is the `user`-scope skill case; rules and
+workflows branch at step 5 into `_install_rule` / `_install_workflow`, and `project` scope writes
+real directories inside the repo instead of symlinking out of the canonical store.
+
+```mermaid
+C4Dynamic
+  title Dynamic Diagram — boost install <name> (user scope, kind=skill)
+
+  Person(dev, "Developer", "Runs the command")
+
+  Container_Boundary(engine, "boost_cli") {
+    Component(cmd, "commands/pkg", "Python", "Thin CLI glue")
+    Component(cat, "core/registry + catalog", "Python", "Resolves the entry")
+    Component(res, "core/resolve", "Python", "Dependency closure")
+    Component(trust, "core/policy + capabilities + scanners", "Python", "Governance gate")
+    Component(store, "core/store", "Python", "Copy and link")
+    Component(targets, "core/agents + rules + workflows", "Python", "Per-agent materialisation")
+    Component(lock, "core/lockfile + integrity", "Python", "Records the digest")
+  }
+
+  ContainerDb(canon, "~/.agents/skills", "files", "Canonical store")
+  ContainerDb(links, "~/.claude, ~/.cursor, ~/.windsurf", "symlinks", "Linking agents")
+
+  Rel(dev, cmd, "1. boost install <name>")
+  Rel(cmd, cat, "2. Look up the entry in the cached catalog")
+  Rel(cmd, res, "3. Expand to the full dependency closure")
+  Rel(cmd, store, "4. install(entry)")
+  Rel(store, trust, "5. Gate: policy, capabilities, typosquat, secrets, injection")
+  Rel(store, canon, "6. Copy the skill directory in")
+  Rel(store, targets, "7. Link and materialise per agent")
+  Rel(targets, links, "8. Symlink into each linking agent")
+  Rel(store, lock, "9. Record version + sha256 in .skill-lock.json")
+  Rel(store, dev, "10. Report what was written")
+
+  UpdateRelStyle(store, trust, $offsetY="-20")
+  UpdateRelStyle(store, lock, $offsetY="20")
+```
+
+## The parts that are easy to get wrong
+
+**Step 5 fails closed.** The gate raises `BoostError` rather than warning. A skill whose declared
+capabilities exceed policy, or that trips the secret / prompt-injection / typosquat scanners, is
+not installed at all — there is no "installed but quarantined" state to reason about later.
+
+**Step 7 is not "symlink into every agent".** Only `agents.linking_agents()` get symlinks. Gemini
+CLI reads `~/.agents/skills` natively and is deliberately excluded, because linking into
+`~/.gemini/skills` too would put one skill in two of its discovery tiers and produce a "Skill
+conflict detected" line per skill per session. Rules and workflows *do* materialise into
+`~/.gemini/`, so the right helper depends on what you are writing —
+see [c4-containers.md](c4-containers.md).
+
+**Step 9 is binding, not advisory.** `core/integrity` makes the recorded digest enforceable, which
+is what lets `boost sync` and `boost doctor` tell "the user edited this skill" apart from "the tap
+moved underneath it". `core/staleness` is the single source of truth for the second question.
+
+## Where uninstall differs
+
+Uninstall is not the reverse of this diagram. It removes the canonical copy, sweeps every symlink
+that pointed at it — including stale links left by an agent that was disabled since install — and
+drops the lock entry. Sweeping links for agents that are *not* currently enabled is the part
+hand-rolled reversals miss, which is why `store.uninstall` owns it rather than the command layer.

boost_skill_cli-1.0.299/docs/roadmap/items/internal-architecture-diagrams.md

@@ -0,0 +1,44 @@
+---
+id: internal-architecture-diagrams
+board: code
+section: docsite
+status: shipped
+category: Docs · Onboarding
+complexity: M
+impact: Med
+wow: 3
+note: 45 core modules and an enforced layering rule, with no diagram of either
+order: 12
+owner: loop/architecture-diagrams
+pr: 345
+title: The engine had no architecture diagram — and the one written rule was documented backwards
+---
+boost had <b>no internal architecture diagram of any kind</b>. <code>docs/rag-architecture.md</code>
+covers retrieval and <code>docs/DEBUGGING.md</code> covers diagnostics, but nothing described the
+shape of the thing: 45 modules in <code>boost_cli/core</code>, 78 commands across 12 command
+modules, four agent targets that are deliberately <i>not</i> symmetric, and a
+<code>cli&nbsp;&rarr;&nbsp;commands&nbsp;&rarr;&nbsp;core</code> layering rule that
+<code>import-linter</code> enforces on every build. A new contributor — or a new agent session —
+had to reconstruct all of that from <code>ls</code>.
+
+Shipped as C4-model diagrams in Mermaid under <code>docs/architecture/</code>, so they render on
+GitHub and stay reviewable in a diff rather than being a binary nobody updates: context, containers,
+core components, and a dynamic walk through <code>boost install</code>. Mermaid was already a
+dependency-free choice here — the repo had none before this, so nothing new ships.
+
+Writing them turned up a documentation bug worth more than the diagrams. <code>CLAUDE.md</code>
+stated <b>"Only <code>skill</code> installs — <code>store.install</code> refuses non-skill kinds;
+rules/workflows are search/tap-only."</b> That is backwards: <code>store.install</code> dispatches
+to <code>_install_rule</code> and <code>_install_workflow</code>, every kind honours
+<code>scope</code>, and it raises only for a kind outside the three. The consequence is not
+cosmetic — installing a <i>rule</i> materialises it into the agent's context file, so a
+<code>boost install</code> of a rule appends to <code>~/.claude/CLAUDE.md</code> and is read every
+session afterwards. Every agent reading <code>CLAUDE.md</code> to learn this repo was being told the
+most invasive install kind could not happen. Corrected in the same change, with the landing places
+for all three kinds spelled out.
+
+The diagrams are hand-written rather than generated, which is a deliberate trade: they describe
+structure — layers, boundaries, which component owns which decision — not anything that moves on a
+routine edit, so drift should be rare and visible in review. <code>docs/architecture/README.md</code>
+lists the four claims most worth re-checking against the code when the engine changes, so the
+staleness question has an answer rather than being left to erode.

boost_skill_cli-1.0.299/docs/roadmap/items/mutation-shard-floor-is-one-file.md

@@ -0,0 +1,101 @@
+---
+id: mutation-shard-floor-is-one-file
+board: code
+section: pipeline
+status: shipped
+category: CI speed
+complexity: M
+impact: Med
+wow: 3
+note: shard 0 is store.py alone — 9.3-11.7 min against a 6.1 even split
+order: 61
+owner: loop/mutation-subfile-shards
+pr: 346
+title: The mutation gate's floor is a single file &mdash; shard 0 <em>is</em> <code>store.py</code>
+---
+Sharding took the mutation gate from ~28 minutes to ~12 (see
+<code>mutation-gate-was-the-whole-critical-path</code>), but it cannot go lower without
+splitting one file. Measured across four consecutive six-shard runs:
+
+<code>638bffeb</code> ran 1.9, 3.9, 5.7, 6.7, 7.2, <b>11.7</b>&nbsp;minutes;
+<code>02c18bd6</code> ran 2.7, 5.0, 5.2, 5.5, 5.9, <b>11.7</b>; <code>fc427839</code> ran 3.1,
+4.8, 5.3, 6.4, 7.3, <b>9.7</b>; and <code>f42e617b</code> ran 2.9, 4.9, 5.5, 6.6, 7.3,
+<b>9.3</b>.
+<b><code>mutation-shard (0)</code> was the slowest leg in all four.</b> Total work is
+36&ndash;37 job-minutes, so a perfectly even split would be <b>6.1</b>; the actual critical
+path is 9.3&ndash;11.7, or <b>1.5&ndash;1.9&times;</b> that. The gap is not bad packing &mdash;
+the planner balances mutant <em>count</em> to within 1.10&times; of ideal. It is that count is
+a poor proxy for time: measured throughput spans <b>3.39 to 14.19 mutants/second</b>, because a
+<code>store.py</code> mutant re-runs a far larger covering test set than an
+<code>ed25519.py</code> one, and survivors run their tests to completion where kills exit early.
+
+Re-weighting the planner by seconds would even out the <em>billed</em> minutes but not the wall
+clock, because <code>store.py</code> is <b>1931 mutants (18.4% of the repo)</b> in one file and
+longest-processing-time packing cannot place a single file across two bins. The floor is that
+file.
+
+The way under it: mutant names are addressable per function, so
+<code>boost_cli.core.store.install_*</code> can be its own shard. That would bring the critical
+path toward the 6.1-minute even split. Two things must survive the change &mdash;
+<code>pattern_for()</code> still has to emit patterns that match nothing else, and
+<code>cmd_merge</code>'s completeness assertion has to keep failing closed, since mutmut counts
+an unrun mutant inside <code>total</code> and a partial merge would silently depress the score
+rather than error.
+
+<b>Shipped.</b> A file heavier than an even share is now split into one unit per top-level
+function, and those units pack independently. <code>store.py</code>'s 31 functions come out as a
+<b>complete partition</b> &mdash; each assigned exactly once, each matched by exactly one pattern
+&mdash; and spread across all six shards, so no shard is more than <b>27%</b> store.py where one
+was previously <b>100%</b>. By mutant count the critical path drops from <b>1931 to 1786</b>, i.e.
+from 1.08&times; of ideal to <b>1.00&times;</b>, and the packing lands within 0.4% of a perfect
+split (1777&ndash;1786 against an ideal 1779).
+
+Both invariants are asserted rather than argued. Patterns anchor on the
+<code>__mutmut_</code> suffix, which is what stops <code>install</code> swallowing
+<code>install_from_path</code> &mdash; a real pair in this file. And the merge now <b>unions</b>
+each shard's results: every shard writes a <code>.meta</code> listing every key in the file with
+<code>None</code> against what it did not run, so a mutant is only "unrun" when it is
+<code>None</code> everywhere. A function no shard was assigned therefore reddens the gate. That
+was verified adversarially &mdash; a synthetic mutant name outside the enumerated partition matches
+no shard's pattern, stays <code>None</code>, and is reported. Any file whose partition cannot be
+enumerated exactly (a class with methods, a duplicate name, a syntax error) is left whole rather
+than guessed at.
+
+<b>Splitting alone was not enough, and the first green run proved it.</b> With
+<code>store.py</code> divided, <code>mutation-shard (0)</code> fell from 9.3&ndash;11.7 minutes to
+<b>4.7</b> &mdash; it is no longer the slowest leg, which is exactly what the card predicted. But
+shard 3 became the new bottleneck at <b>10.3</b> minutes, leaving the run at 1.6&times; ideal. The
+diagnosis above was right and incomplete: counts were balanced to 0.4%, and the <em>time</em>
+spread across shards was still 2.6&times;.
+
+So the second half is weighting by measured time, which a divisible file finally makes possible.
+<code>weights</code> now records mutmut's per-mutant durations and the planner prefers them. The
+count-based split, balanced to <b>1.08&times;</b> of ideal <i>by count</i>, was <b>2.24&times;</b> of
+ideal <i>by time</i> &mdash; one shard carrying 39.3 minutes of summed test time against a
+17.5-minute even share.
+
+<b>Measured, that bought less than the arithmetic suggested.</b> Time-weighting moved the critical
+path from 10.3 to <b>9.3</b> minutes (shards 5.2, 5.8, 6.3, 6.8, 6.2, 9.3), 1.41&times; ideal rather
+than the 1.04&times; the summed-time model predicted. Summed test time is not shard wall clock:
+mutmut runs mutants across parallel workers, so a shard's elapsed time is its summed time divided by
+an effective worker count, and the model ignored that. Per-shard fixed overhead was ruled out by
+measurement rather than assumed &mdash; checkout, venv and install together are <b>0.4 minutes</b>,
+against 4.8&ndash;8.9 minutes inside <code>mutmut run</code> itself.
+
+The residual had a specific cause, and it is the same proxy error one level down: a split file's
+time was apportioned across its functions by <em>mutant count</em>. Across
+<code>store.py</code>'s functions the per-mutant cost spans <b>0.273 s to 3.900 s</b> &mdash;
+<b>14.3&times;</b> &mdash; and <code>install</code> alone is <b>36%</b> of the file's time from
+<b>12%</b> of its mutants, so the shard that drew it ran 8.9 minutes against a 4.8-minute sibling.
+<code>weights</code> now records per-<em>function</em> durations too and apportions on those, which
+balances the plan to <b>0.06%</b>. Whether that closes the wall-clock gap is a claim the next run
+gets to settle, not this card.
+
+Two bugs found by running it rather than reasoning about it. mutmut records durations in
+<b>seconds</b>, so summing them into a field named <code>millis</code> understated
+<code>store.py</code>'s 2360 seconds of test time as 2.4 &mdash; a 1000&times; mislabel. And
+requiring a duration for <i>every</i> file before trusting the tier was too brittle to fire: one
+file of 46 (<code>util.py</code>) came back short on the first run, which would have silently
+dropped the planner back to counting mutants and looked like the feature simply not working. A
+missing file is now imputed at the measured mean rate, which keeps every weight in one unit
+&mdash; the property that actually matters.