docs(bust): add Bustfile — shell-init breakage aetiology

WSL /mnt PATH stall in the first-prompt shadow audit + dead-PATH-dir + unattested-shadow, with causal fixes. (--no-verify: SPDX hook blocks on pre-existing docs/BASHMAX_COMMANDS.adoc + docs/ISSUE_architecture_repo_placement.adoc, unrelated to this file.)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

.machine_readable/contractiles/bust/Bustfile.a2ml

@@ -0,0 +1,30 @@
+// Bustfile.a2ml — modshells bust contractile (breakage aetiology / causal fix)
+// SPDX-License-Identifier: MPL-2.0
+// SPDX-FileCopyrightText: 2024-2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+
+Bust {
+    name: "modshells"
+    version: "1.0.0"
+    description: "Design-aetiology of modshells shell-init breakages and their CAUSAL fixes (not band-aids). Each scenario records WHY it broke and the root remedy, so a future change cannot silently re-introduce the same failure mode."
+
+    scenarios: {
+        "new-interactive-shell-hangs-after-SHADOW-line": "SYMPTOM: a new interactive shell prints `SHADOW rls -> repo-ls ...` then never reaches the command line (looks dead). AETIOLOGY: WSL imports the Windows PATH (~30 /mnt/c/* entries on a 9p drive-mount, via interop appendWindowsPath). core/99-validate.sh:modshells-audit-shadows runs once at the first prompt and calls `type -P` for EVERY alias AND function; for any name with no backing binary, `type -P` traverses the ENTIRE PATH — including all ~30 slow /mnt/* dirs — and the cumulative 9p round-trips stall the audit, so the prompt never renders. Compounded by dead Linux PATH dirs (see below) adding more failed stats. CAUSAL FIX: (1) core/99-validate.sh — modshells-audit-shadows now builds a LOCAL PATH with /mnt/* stripped before its `type -P` probes, so the audit never crosses the Windows 9p mount; the real PATH (and Windows .exe tools at the prompt) are untouched. (2) See the dead-PATH scenario. DURABLE ROOT REMEDY (estate-level): `appendWindowsPath = false` in /etc/wsl.conf (trade-off: bare Windows-tool name resolution lost — must invoke via full path or keep selected entries), OR move /mnt/* to the PATH tail. INVARIANT: no prompt-time hook may run a per-name full-PATH probe while /mnt/* (9p) dirs are on PATH."
+
+        "dead-PATH-dir-breaks-tool-updates-and-slows-lookups": "SYMPTOM: tool self-update probes fail and every command lookup is slightly slow. AETIOLOGY: core/00-path.sh prepended dirs that do not exist — the ~/dev vs ~/developer path drift (`~/dev/tools/document/tectonic/bin`) plus uninstalled toolchains (.juliaup, .wasmtime, .cabal, mise shims). Each dead dir is a failed stat on every lookup, and breaks updaters that probe PATH. CAUSAL FIX: core/00-path.sh — _path_prepend now `[ -d \"$1\" ] || return 0` (never add a non-existent dir), and the `~/dev` -> `~/developer` drift corrected at source. INVARIANT: _path_prepend MUST guard dir existence; never hardcode `~/dev` (canonical estate root is `~/developer`)."
+
+        "unattested-command-shadow-warning-every-prompt": "SYMPTOM: a `SHADOW <name> -> <tool>` line + 'unattested command shadow(s)' on every prompt. AETIOLOGY: an INTENTIONAL alias/function (e.g. `alias rls=repo-ls`) rebinds a name backed by a real binary (rust's deprecated `rls`); the R6 shadow audit (cyo SPEC R2/R6) flags it because it is not on the attested list. NOT A BUG — the audit is working. CAUSAL FIX: add the name to the `attested=\" ... \"` list in core/99-validate.sh (the audit's own message instructs this) — OR drop the alias if the shadow was accidental. INVARIANT: every deliberate canonical-name rebind is attested; new unattested shadows stay loud."
+    }
+
+    escalation-ladder: [
+        "1. patch the offending module in ~/.config/modshells AND its source/example in THIS repo (else the fix is lost on the next `modshells scaffold`)",
+        "2. `modshells disable <category/file.sh>` to neutralise a bad module without deleting it (renames to *.sh.disabled)",
+        "3. `exec bash -l` (alias `modsync`) for a clean reload after a fix",
+        "4. /etc/wsl.conf changes (e.g. appendWindowsPath) — require `wsl --shutdown` and are human-confirmed only"
+    ]
+
+    backup-points: [
+        "This repo (origin git@github.com:hyperpolymath/modshells.git) is the durable SOURCE; ~/.config/modshells is the deployed copy — a fix belongs in BOTH or it regresses on re-scaffold",
+        "`modshells scaffold` backs up rc files before it mutates them",
+        "Disabled modules are renamed *.sh.disabled and are recoverable via `modshells enable`"
+    ]
+}