toko-tooling 0.45.0

Shared development tools, CI helpers and engineering rules for Toko Studios
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
# Consumer Make interface

Use one reviewed snapshot entrypoint for common contributor commands:

```make
.DEFAULT_GOAL := help
override TOKO_TOOLING_ROOT := $(CURDIR)/vendor/toko-tooling
include vendor/toko-tooling/make/consumer.mk
```

The vendor directory is the standard installed location; `consumer.mk` also
derives `TOKO_TOOLING_ROOT` from its own location when no override is supplied.
Select `make/release.mk` and `make/cargo-publication.mk` explicitly during export
when using those optional features. Never include a moving sibling checkout. A non-Rust repository
sets `TOKO_TOOLING_RUST := 0` before the include; it still prepares the complete
common toolset, but does not expose Rust formatting or hook installation.
The include preserves the consumer's default goal, even when declared later.
Parsing it never installs tools, activates hooks or starts a release.

Toko Tooling releases are opt-in: set `TOKO_TOOLING_RELEASE := 1` before including
`consumer.mk` only after providing the [release adapters](../releases/releases.md).
The default `0` supplies no shared release or empty-directory cleanup targets
and leaves consumer-owned release recipes alone. Existing users of the shared
release runner must add this setting when adopting 0.39.0. A focused include of
`make/release.mk` itself remains an explicit opt-in. `ci` is always phony;
consumers supply their product gate alongside shared snapshot admission.

To restrict release delivery, set `RELEASE_DELIVERY_POLICY` before the include
to a consumer-owned regular data file containing `direct`, `pr`, or both, one
per line. The common include refuses unsupported selections when a standard
release command or metadata hook is requested as a Make goal. Unset selection defaults to direct; an explicit
empty selection refuses. Unrelated goals do not read the policy. Without a policy
file, the existing direct/PR contract is unchanged. `SHARED_RELEASE_TARGETS`
provides the canonical command/hook roster for consumer declarations.

Standalone metadata entrypoints call
`bash vendor/toko-tooling/scripts/ci/check-release-delivery.sh "$policy_file" "${RELEASE_DELIVERY-direct}"`
before effects, using that same file; never source it as shell code. An empty
file-path argument admits the standard direct/PR set. File selection and delivery
choice remain consumer-owned; this helper grants no release or merge authority.
Make admission resolves the helper beside the selected include, independently of
runtime `TOKO_TOOLING_ROOT` overrides. Keep its snapshot companion selected.

Selecting `make/consumer.mk` as a snapshot entrypoint includes the common
installers, common pin catalogs and default LOC helper through their declared
dependencies. Product pin exceptions remain consumer-owned; optional fleet
reports require explicit selection.

| Commands | Shared owner | Consumer inputs |
| --- | --- | --- |
| `install-tools`, `tools-check`, narrow host/IC/Rust commands | Common pins, ordered setup and offline admission | Explicit pin exceptions and ordered product tool extensions |
| `tools-report` | Aggregate existing offline checks and retain all failures | Same ordered local check targets; no setup or release admission |
| `fmt`, `fmt-check`, `format-tools-check` | Prerequisite check, compact output, retained failure logs | Cargo environment and complete custom formatter commands when needed |
| `install-hooks` | Safe repository-local activation | Tracked `vendor/toko-tooling/.githooks/pre-commit` and its companions |
| `toko-tooling-status`, `toko-tooling-update`, `toko-tooling-install` | Report installed/locked registry identities; install the existing Cargo.lock selection, then install/check tools | Optional `TOKO_TOOLING_VERSION` assertion matching the lock, `TOKO_TOOLING_MANIFEST`; `TOKO_TOOLING_SOURCE` only for one-time Git migration proof |
| `toko-tooling-check` | Offline snapshot integrity and Cargo selection agreement | `TOKO_TOOLING_MANIFEST`, default `.toko-tooling.snapshot` |
| `toko-tooling-preview` | Preview the selected crate refresh without changing consumer files or tools | `TOKO_TOOLING_MANIFEST`, optional `TOKO_TOOLING_SOURCE` |
| `cloc` | Workspace report | Optional report/manifest selection |
| `release-patch`, `release-minor`, `release-major`, `release-resume` | Opt-in admission and exact-version recovery runner | `TOKO_TOOLING_RELEASE := 1`, metadata, validation, delivery policy, branch and remote |
| `release-batch-timings` | Read retained [phase timing observations]../releases/release-batches.md#phase-timings as JSON without rerunning delivery | `BATCH=batch-XXXXXXXX` |

The included `tools.mk`, `rust-format.mk`, `release.mk` and `execution.mk` are
the implementation owners. Existing focused includes remain supported; full
consumer adoption uses `consumer.mk` instead of including the same modules twice.
Toko Tooling itself selects the non-Rust profile. Its source checkout has no
consumer snapshot to verify; `toko-tooling-check` is for adopted copies.

Execution admission runs only when a protected formatting, setup or release
recipe is selected, including through a wrapper target. Unrelated `make -n`
previews and completion queries do not execute the probe. Protected recipes still
reject ignore-errors, dry-run, touch and question modes by default. For an explicit
preview, use `make -n check TOKO_TOOLING_DRY_RUN=1` (likewise `patch`, `setup-dev`,
`install-dev` or a shared target). This option requires GNU Make dry-run mode;
shared recipes print their commands with forced/recursive execution disabled.
The guard still runs its isolated read-only probe. Shared recursive Make commands
are printed without traversing their submakes. Consumer-owned `+` recipes and
Make expansions retain GNU Make's normal behavior and must be reviewed separately.
Consumer-owned effectful targets can add `| toko-execution-check` to their
prerequisites; opting into preview does not suppress their own `+` recipes.
Set `TOKO_TOOLING_INSTALL_TOOLS=0` for snapshot-only install/update; normal updates
still prepare and check tools. See the [adoption guide](migrations.md#baseline-filename-migration-in-0370)
for bootstrap, prerequisites and the hard-cut migration.

Tooling adoption uses the [agent audit tasks](https://github.com/dragginzgame/toko-tooling/blob/08cd17240fd60dfd309e35eb131e73323e883e6f/docs/fleet-tools.md#tooling-adoption-audit),
not a consumer LOC target or deployment gate. Rust LOC uses the separate
[`toko-cloc` command](../fleet/fleet-tools.md#cargo-workspace-loc-report), with
ordinary command-line options; there is no Make target or alias.

## Keep product policy local

Keep build, test, publication, deployment, cleanup, validation gates and release
metadata adapters in the consumer. CI and documentation call the same public Make
targets. Adapters may use documented shared helper APIs; a single entrypoint is
not a ban on the helpers that implement those adapters.

Use the existing `LOCAL_TOOL_INSTALL_TARGETS` and `LOCAL_TOOL_CHECK_TARGETS`
ordered extension lists for product tools, including IC Testkit's PocketIC CLI.
Their install phase follows the common Cargo tools; native/system bootstrap
that changes Cargo fingerprints must happen earlier in the consumer adapter.
See [setup](local-setup.md) for pins and executable storage. Do not add unordered
prerequisites to the aggregate installation target or duplicate its recipes.

Add prerequisites and target-specific environment to common targets when the
consumer needs stronger admission; do not define a second recipe. For example:

```make
release-patch release-minor release-major release-resume: local-release-preflight
release-patch release-minor release-major release-resume: export LOCAL_RELEASE_PREPARE := 1
format-tools-check: local-formatter-check
```

Those local names are examples, not new shared targets. Retain the actual
consumer's checks. The [release contract](../releases/releases.md) owns adapter requirements
and recovery. Consumers such as IC Backup also verify a product-owned receipt
after explicit resume. Set `RELEASE_RESUME_CHECK_COMMAND` to that existing check,
for example `bash scripts/release/release.sh resume-check "$(VERSION)"`.
It runs only after the runner succeeds, with the requested exact version;
failure stops Make. It must only verify existing evidence, never repeat delivery,
publish or clean. The default is a no-op. Keep receipt identity and schema at
their consumer owner; ordinary release validation remains in the existing
runner adapters. The include does not change user-owned release authority or add
publication, deployment or cleanup. Preserve unfinished plans, prior tool
installations, logs and build artifacts during adoption.

### Native bootstrap adapter

Keep native/system installation in the consumer's existing explicit setup or
release-preparation adapter, before calling the shared installer. For example,
this **consumer-owned** target has a sequential recipe, including under parallel
Make; the local target names are examples, not additions to Toko Tooling's interface:

```make
.PHONY: prepare-release-prerequisites
prepare-release-prerequisites:
	+$(MAKE) install-native-tools
	+$(MAKE) native-tools-check
	+$(MAKE) install-tools
	+$(MAKE) install-product-dependencies
	+$(MAKE) native-tools-check
	+$(MAKE) tools-check
	+$(MAKE) product-prerequisites-check
```

`install-tools` includes the consumer's selected release editor when declared in
its ordered extension list. The product-dependency phase must not change the
compiler/native inputs used to prepare those tools; move such work to bootstrap.
The final admission covers native prerequisites, declared shared/local tools and
the remaining product prerequisites before validation starts. Do not turn this
into sibling prerequisites that race under `make -j`.

Call that sequence only where setup is already authorized. Standalone
`tools-check`, `native-tools-check` and `product-prerequisites-check` remain
read-only. Validation consumes prepared prerequisites without implicitly
installing packages. Keep the actual command roster
with the consumer; see [bootstrap ordering and re-preparation](local-setup.md#native-bootstrap-before-cargo-tools).

## Custom formatting without replacement recipes

By default Rust formatting sorts the root Cargo workspace with `--grouped` and
runs rustfmt through `scripts/ci/run-rust-formatting.pl`. Each pass shows progress
and elapsed time while its verbose output stays in a private log; failures retain
the log and exact exit status. Blank-separated dependency sections are preserved.
Use reviewed literal `FORMAT_RUST_ARGS` for extra workspaces, optional derive
sorting, root/extra manifest order and standalone Rust files, instead of copying
the orchestration:

```make
FORMAT_RUST_ARGS = --sort-derives \
    --extra-workspace integrations/consumer \
    --extra-workspace 'integrations/embedded consumer' \
    --extra-manifest-order workspace,package,lib,dependencies,dev-dependencies,build-dependencies,profile
include vendor/toko-tooling/make/consumer.mk
```

The root sequence is grouped manifest sorting, optional derive sorting, then
Rustfmt. Each extra workspace gets grouped manifest sorting and Rustfmt, in the
declared order. Derive sorting runs once at the checkout root, preserving the
sorter's ignore-aware traversal. `--manifest-order` selects root ordering;
`--extra-manifest-order` selects ordering for extra roots. Extra roots must be
distinct directories inside this checkout. Reuse a consumer's existing roster
when constructing these arguments; do not create another workspace registry.

For sources outside Cargo's formatter inventory, repeat `--rustfmt-source PATH`
and select `--rustfmt-edition 2015|2018|2021|2024` explicitly. These files are
formatted in a separate timed pass after all workspaces. Missing, duplicate or
outside-checkout files and unsupported editions reject before any write. Direct
Rustfmt is admitted before workspace mutations; `--rustfmt PATH` selects one
executable, and target-specific `RUSTUP_TOOLCHAIN` applies to it too. For example:

```make
FORMAT_RUST_ARGS = --extra-workspace testing/runtime-qualification \
    --rustfmt-source testing/package-consumer.rs --rustfmt-edition 2024
```

Use the consumer's existing file list; if it contains globs, expand them with
Make's `$(wildcard ...)` and emit one option per file with `$(foreach ...)`.
Selections containing standalone files run uncached, including their workspace
passes, because arbitrary standalone modules/configuration are not inventoried
by the cache contract. This preserves full coverage and visible progress rather
than certifying an incomplete input set.

Before running passes, the driver can reuse a successful result for identical
workspace/source/manifests/lock/configuration, formatter identities and policy.
It observes Cargo metadata and hashes source bytes; Git cleanliness or mtimes
alone do not establish an unchanged input set. Input observation and result
recording have their own timings, so shortcut overhead remains visible.
The local receipt is `target/toko-tooling/formatting.receipt`. Missing, corrupt
or unreadable bookkeeping is a miss. Cargo member selection must succeed before
any write, even with `--no-cache`; metadata failure cannot fall back to `--all`.
Each selected workspace formats only its explicit member packages. External path
dependencies are not formatting inputs. Incomplete cache discovery, custom
`RUSTFMT`, explicit module paths or external target paths disable reuse;
owned formatting still runs. Optional derive reuse also needs `rg`; no tool is
installed implicitly. Standard Cargo package sources, root/ancestor Cargo and
Rustfmt configuration, toolchain inputs and derive configuration are covered.
Module-path screening uses the shared Rust lexer and balanced attribute trees,
including nested conditional attributes. Comments, literals and later source
text do not become module overrides. Incomplete token trees or unsupported
conditional metadata still disable reuse. The driver and its declared `RustSource.pm` companion are
both fingerprinted; refresh their complete snapshot and hook-fixture closure.

Only a successful check or write with unchanged observed inputs records a
reusable result. A write that changes files needs a later check or unchanged
write before reuse; it does not run a second check-before-write sequence.
Failed or interrupted runs never publish a receipt. Keep source stable during
formatting, as with other working-tree checks. Isolated staged-hook worktrees
always run their formatters; developer receipts do not qualify staged inputs.
Use `FORMAT_RUST_ARGS += --no-cache` to force all passes for explicit qualification.
Prepared-tool checks still run before a cache hit. This is local result reuse,
not a replacement for release source/evidence admission or native qualification.

For genuinely different policies or additional frontend formatting, the existing
paired command interface remains available. Those opaque commands are uncached
and use the compact `run-formatting.sh` log wrapper:

```make
FORMAT_WRITE_COMMAND = bash scripts/dev/format-workspaces.sh --write
FORMAT_CHECK_COMMAND = bash scripts/dev/format-workspaces.sh --check
include vendor/toko-tooling/make/consumer.mk

fmt fmt-check format-tools-check: export RUSTUP_TOOLCHAIN := $(VALIDATION_TOOLCHAIN)
fmt fmt-check format-tools-check: export CARGO_HOME := $(LOCAL_CARGO_HOME)
```

Keep all required formatter coverage in a custom adapter. Do not wrap it in
`run-formatting.sh` again: the shared targets own that wrapper. A fixed
`bash -ec '...'` command is also supported; these values are reviewed Makefile
commands, not untrusted strings. Quote paths and use Make's `$$` escaping for
shell variables. Supplying only one command or an empty command is rejected.
`FORMAT_CARGO` selects the executable used for Rust prerequisite checks and the
standard driver;
target-specific environment applies to those checks and the formatter.

A snapshot refresh preserves explicit command overrides; migrating a supported
Rust-only adapter requires removing both overrides and selecting its inputs with
`FORMAT_RUST_ARGS`. Update the actual caller and hook fixtures, including manual
shared-file copies and aggregate-output assertions. Preserve standalone file and
edition inputs when replacing their adapter. Nesting
the driver inside a custom command still captures its progress in the aggregate
log; it does not provide live per-pass output.

The shared recipes preserve jobserver descriptors, prepared-tool/offline policy,
failure status and retained logs. Custom commands own extra prerequisites and
must stop on failure. Keep [hook qualification](../../rules/git-hooks.md) for the
actual workspaces and frontend inputs. Native consumer tests are still required;
shared substitute fixtures prove routing, not a product's formatter behavior.

## Qualification without recipe overrides

In disposable fixtures, keep exactly one recipe per target. Appending substitute
recipes to an exported production Makefile causes repeated override warnings on
every recursive Make invocation; suppressing stderr hides genuine diagnostics.

Prefer substituting the effectful scripts in the disposable export while keeping
the real shared includes. The existing `test-tool-commands.sh` fixture does this
for installers: it records arguments, injects failures and verifies ordering,
Make admission and inherited jobserver descriptors. Its fixture gate calls the
actual `install-tools` and `tools-check` recipes, with product targets supplied
through the existing ordered extension lists. `test-make-consumer.sh` separately
checks actual release routing with a substitute runner.

When product gate recipes themselves need replacement, construct one small
fixture-owned Makefile with the actual shared includes and only the required
product targets. Define each recipe once. Keep real product metadata transforms
and assertions for release preparation/reconciliation in that fixture; substitute
external setup/build effects at their script boundary. For example, a release
fixture can define its single `ci` recipe to check prepared markers and inject a
gate failure, while its single `release-prepare-version` recipe calls the real
metadata adapter before injecting an interruption. Do not replace shared ordered
aggregates or the release runner just to avoid warnings in a recovery test.

This is consumer fixture construction, not a new production override API.
Qualify the consumer's real Makefile separately, and retain its actual disposable
Git/bare-remote recovery tests. Shared routing substitutes do not qualify product
metadata, delivery or native hosts. Check successful fixture logs for unexpected
recipe warnings rather than filtering them from every invocation.

## Adoption

1. Refresh the [recorded snapshot]consuming-snapshots.md, selecting
   `make/consumer.mk` as an entrypoint. The exporter derives its companion closure;
   preview reports all additions, updates and automatic retirements. Include other
   locally used executable roots and the baseline; read reference docs online; this entrypoint is not their inventory.
2. Replace the separate shared includes and equivalent local hook/snapshot-check
   recipes. Retain stronger prerequisites, target environment and extra snapshot
   checks. `TOKO_TOOLING_MANIFEST` names one manifest; additional bundles remain
   explicitly checked by consumer-owned targets attached to `toko-tooling-check`.
3. Move custom formatting commands into the two inputs above, deleting only their
   equivalent local `fmt`/`fmt-check` recipes. Preserve every workspace, derive,
   frontend and prepared-tool check. Keep the Rust hook and its root-layout
   companions at their required paths, even if other tooling lives in a subdirectory.
4. Update CI, help, setup documentation and isolated Make/hook/release fixture
   inputs together. Export all includes that will be parsed, including
   `make/consumer.mk`; the release command checker still substitutes only the
   runner and must never reach the real checkout's release adapter.
5. Trace every command in the consumer's actual release gates, including nested
   workspaces, native generators, the metadata editor and browser tooling. Map
   each prerequisite to explicit setup and read-only admission. Prepare native
   inputs before Cargo tools, keeping post-common extensions for later tools.
   A successful `tools-check` alone does not cover the full gate's prerequisites.
6. Run focused consumer formatting/hook and release routing checks. Full delivery
   gates remain release-owned or explicitly requested; applicable native macOS
   qualification remains required. Delete local installers
   or aliases only after tracing their callers and verifying equivalent behavior;
   do not remove product setup merely because it invokes a shared helper.

No old public command is removed by this addition. Any later retirement must
identify callers and actual replacement coverage before selecting a breaking
Toko Tooling release. Consumer library adoption is normally contributor tooling
work, not a reason to bump the library's minor version.

## Hosted preparation and disposable fixtures

Toko Tooling's producer fixtures own exhaustive Make flag aliases, inherited
and replaced flags, and common-tool preflight/install/check failure permutations.
Consumers can use `make_probe_target_admission` from
`scripts/ci/make-adapter-probes.sh` to exercise each actual target with the four
unsafe behaviors (`-i`, `-n`, `-t`, `-q`), requiring status 2 and no recorded
effects. Keep local target rosters, effect stubs, parallel descriptor checks,
diagnostic selection and recovery-state custody at the consumer. The full
execution-mode matrix lives in the producer fixture; it is not exported.
The common-tool action fixture executes the actual shared Make aggregates with
only installer leaves substituted; it admits phase order, failure stopping,
stdout/stderr retention and PATH publication. No tools are installed by it.

The optional `.github/actions/prepare-common-tools` action runs `make install-tools`
then `make tools-check`, retaining complete `tools-install.log` and `tools-check.log`
under `RUNNER_TEMP`. It appends common host/Cargo executable directories to
`GITHUB_PATH` only after both commands succeed. Selected IC consumers publish
their admitted `.tools/ic/bin` separately. Consumers own compiler setup,
Make's ordered local extensions, caches and product gates. The action requires
an existing checkout, `RUNNER_TEMP` and `GITHUB_PATH`; it does not select a compiler.

Use `bash vendor/toko-tooling/scripts/ci/prepare-script-fixture.sh SOURCE EXISTING-FIXTURE ROOT...`
for Make fixtures too. Select `make/consumer.mk` for the consumer interface,
`make/tools.mk` for tool aggregates or `make/release.mk` for release routing.
Their declared companions supply the complete closure. Apply local Makefiles,
catalogs and leaf stubs after preparation; callers retain assertions and evidence.
The former `prepare-make-fixture.sh` command is removed.

For an adapter with native bootstrap, exercise the **actual preparation sequence**
in a disposable consumer export, replacing installation/process leaves at their
existing script boundaries. Let the native installer record a setup marker and
make the Cargo-tool setup substitute refuse without it. Assert the successful
order (also with parallel Make), reverse the bootstrap/Cargo calls and require
refusal before later setup or validation. Check that failed prerequisite admission
stops gate dispatch and that standalone checks reach no installer. Do not test a
handwritten duplicate of the adapter or invoke host package managers in a fixture.

Toko Tooling's Cargo-tool fixtures own native-environment fingerprint invalidation and
explicit re-preparation. Retain that rejection/recovery behavior; consumers
qualify their wiring and named missing product proofs instead of copying the
generic matrix. Substituted ordering fixtures do not prove native compilation,
product behavior or macOS support. These requirements belong in the
[consumer qualification selection](consuming-snapshots.md#consumer-qualification-selection).

## Reusing fixture exit qualification

`scripts/ci/fixture-retention-probes.sh` owns the common failure injections,
status comparisons and retained-evidence checks. Consumers keep source rosters,
working directories and domain-specific diagnostic assertions.
`fixture_probe_exits` includes cleanup refusal alongside command, early-exit,
completion and incomplete-run cases; callers need not append `cleanup-failure`.
Existing
`FIXTURE_PROBE_ROOT_VARIABLE` / `FIXTURE_PROBE_DIRECTORY_VARIABLE` selections may
be paired with `FIXTURE_PROBE_COMPLETION_VARIABLE` (default `fixture_complete`)
and `FIXTURE_PROBE_TEMPORARY_ROOT` (default the probe root). Variable names are
admitted as shell identifiers before child execution. Relative and aliased scratch
roots are checked against their physical directory; a caller using RUNNER_TEMP
selects that environment explicitly too. On success `fixture_probe_retained`
contains the checked physical path for any caller-owned diagnostic comparison.
Selected assertion probes preserve a function context for return-based guards.
Repeated exit probes require a fresh receipt from each child; earlier retained
directories remain available when a later child fails during initialization.
No consumer fixture body is run by these prefix-only probes.

## Empty source directories during deployment

Standard release entrypoints and release preflight automatically run
`clean-empty-source-dirs`, including before frozen-batch capture. No consumer
cleanup configuration is required once shared releases are opted into. The helper
selects existing conventional source roots:
`src`, `crates`, `apps`, `backend`, `fleets`, `canisters`, `packages`, `tests`,
`testing`, `schema`, `profiler`, `scripts`, `frontend/src` and `frontend/tests`.
Repositories without those roots report zero deletions. Application deployment
adapters that bypass the standard release entrypoints can call
`make clean-empty-source-dirs` with the same automatic selection.

The helper walks children before parents and deletes only empty directories
matched by Git ignore rules. Git's inability to track an empty directory alone
does not make it eligible. Selected roots, indexed paths (including missing
tracked files), symlinks, Git metadata, target/build/dist/coverage, node_modules,
vendor, tool/cache and recovery-evidence directories are preserved. It prints
the number deleted. Cleanup never removes files or follows directory links.
The helper also accepts explicit repository-relative source paths for standalone
use, including quoted paths containing spaces.

## Rustdoc diagnostic baselines

Select `scripts/ci/check-public-docs.pl` as an explicit snapshot entrypoint when
maintaining a bounded missing-documentation baseline. Consumers own the Cargo
package/feature selection and baseline file. Run from the directory used by Cargo
so diagnostic source paths resolve against the same checkout.

```bash
perl vendor/toko-tooling/scripts/ci/check-public-docs.pl diagnostics.jsonl public-docs-baseline.json
```

The checker compares item identities, preserves occurrence counts, and refuses
malformed diagnostics, unsupported identities and missing source files. Updating
the baseline requires the explicit `--write-baseline` option; normal checks never
rewrite it. Generic identity/rejection fixtures run in producer `test-public-docs`
CI; consumers retain their Cargo/rustdoc caller checks.

When replacing a consumer-owned checker at this path, review and commit its
local changes first. The installer may replace a clean tracked native file;
modified or staged differing files are refused. Preview the selected release
with the complete existing entrypoint list plus `scripts/ci/check-public-docs.pl`,
then install that same selection. Explicit entrypoints replace the recorded
selection, so retain every still-needed entrypoint. Never edit the snapshot
receipt or managed checker by hand. Keep the consumer baseline and compiler
caller tests; retire its generic comparator tests after shared adoption passes.