# AI-LSC MoE QA Pass — Final Report

**Source:** `ai-lsc-main(1).tar.gz`
**Date:** 2026-08-31
**Pass scope:** Surgical cleanup (one more pass after v3.1 critique + v3.2 taxonomy migration).
**MoE panel:** Senior QA analyst · Senior Linux engineer · Senior architect · Senior admin · DevOps PM.

## 1. Standards referenced

| Standard | Application |
|---|---|
| PEP 868 / PEP 8 | Type annotations, line length ≤100, import ordering. |
| POSIX sh / bash | `set -euo pipefail`, no bashisms in sourced contexts. |
| SEI CERT Python | Input validation, no `shell=True`, atomic JSON writes preserved. |
| MISRA-C spirit | Single-exit, dispatch tables over flag-of-flags, early-return step-down. |
| Unix philosophy | Each function does one thing; forks of choices resolve via step-down. |

## 2. Wording sweep — "restored / brought back / related logic" eliminated

All instances rewritten as decisive statements. Source files touched:

| File | Line(s) | Change |
|---|---|---|
| `src/ai_lsc/registry/layers/routing.py` | docstring | "Restored layer (v3.1.1b)" → "L5 (Intelligent API Routers & Proxies) holds …"; added source-of-truth note. |
| `TODO.md` | 6 | "restored in full from the v3.1.1b routing tarball" → "the canonical 1.3 k-line implementation now lives in-tree". |
| `scripts/apply_10layer_taxonomy.py` (now retired) | 201, 668, 757 | "restored from the routing tarball" → "canonical 124-category cascade"; "the restored Routing layer" → "the L5 Routing layer". |
| `CHANGES.md` | 224, 254, 269, 321 | "Restored in full from the v3.1.1b routing tarball" → "canonical 1.3 k-line implementation is re-established in-tree"; section header "Routing restored" → "Routing promoted to a first-class layer"; "(restored)" ladder annotation removed. |
| `whatremains.txt` | 9 | "the restored installer cmds" → "the canonical installer cmds". |
| `docs/ADR-003-workspace-tab.md` | 67 | "The empty-state placeholder is restored" → "the empty-state placeholder is shown again". |

Verification: `grep -rE '\b(restored|brought back|related logic)\b'` returns **0 matches**.

## 3. Author metadata

| File | Field | Value |
|---|---|---|
| `pyproject.toml` | `authors`, `maintainers` | Jeremy Anderson `<info@dcos.net>` |
| `README.md` | header | Author + email + https://dcos.net link |
| `README.md` | clone URL | `https://github.com/dcos-net/ai-lsc.git` |
| `LICENSE` | header | AUTHOR + COPYRIGHT + HOMEPAGE = `dcos.net` |

## 4. Code patterns — nested ifs → arrays/dispatch tables

### 4.1 `src/ai_lsc/manifest/support.py` — `build_system_context`

Replaced 6 cascaded `if field:` blocks with a single `_FIELDS` tuple + comprehension:

```python
_FIELDS: tuple[tuple[str, str], ...] = (
    ("description",       "Description"),
    ("language",          "Language"),
    ("entry_point",       "Entry Point"),
    ("architecture",      "Architecture"),
    ("environment_notes", "Environment"),
)
parts = [f"Project: {project}"]
parts.extend(
    f"{label}: {manifest.get(key)}"
    for key, label in _FIELDS
    if manifest.get(key)
)
```

Added a "Source-of-truth boundary" docstring noting the manifest is a derived view; the registry layer files remain authoritative.

### 4.2 `src/ai_lsc/manifest/support.py` — `resolve_context_files`

Replaced outer-for + inner-for + if with a single list comprehension (one pass over patterns → files → filter).

### 4.3 `src/ai_lsc/ui/pages/chatbot_console.py` — `_build_payload_history` (M-40 / L-09)

Replaced the 3-way nested ternary
`parts[0] + "\n\n" + parts[1] if len(parts) == 2 else (parts[0] if parts else "")`
with the flat `"\n\n".join(parts)`. Behavior preserved (empty parts → empty string).

### 4.4 `src/ai_lsc/ui/pages/chatbot_console.py` — HTML bubble builder (M-22)

Extracted `_render_bubble(msg)` helper. Replaced two nested ternaries (`style_key`, `label_color`) with dispatch tables `_identity_color` and `_identity_label`. The main loop is now a one-liner:

```python
html += "".join(_render_bubble(m) for m in self.chat_messages)
```

## 5. Unix philosophy — step-down (early return) refactors

### 5.1 `bootstrap.sh` — base-dir detection (lines 70-100)

The 4-level nested `if/elif/else` (root → prompt → sudo/alt-base/error) was inverted to a step-down `if/elif/else` where each branch resolves one situation and exits the block. Removed one nesting level.

### 5.2 `src/ai_lsc/runtime/installer.py` — `install_git` / `install_git_node`

Both methods had a 3-way fork (pull / re-clone-on-failure / clone-non-git-dir / fresh-clone) with duplicated `shutil.move + makedirs + git clone` code across branches. Extracted:

- `_backup_existing(dest) -> str` — single-purpose backup helper.
- `_clone_fresh(pkg, dest) -> None` — single-purpose clone helper.

Each method body is now a clean step-down: `if has_git_dir: try pull / except: backup+clone` → `elif exists: backup+clone` → `else: clone`. Behavior identical; ~30 lines of duplication removed.

### 5.3 `src/ai_lsc/registry/openengineer/importer.py` — directory scan

The two `for md_file in sorted(...)` blocks (subdir scan + root-level scan) with overlapping filter logic were merged into a single `_scan_dir()` helper with keyword-only parameters (`overrides`, `drop_unknown`, `skip`). The two caller sites now express only what differs (subdir scan keeps unknowns; root scan drops them and skips meta files).

## 6. Docs vs source — source-of-truth boundary

The manifest module (`src/ai_lsc/manifest/support.py`) and the routing layer file (`src/ai_lsc/registry/layers/routing.py`) now both carry explicit "source of truth" docstrings:

> The manifest file itself is an optional convenience; if absent, callers fall back to defaults — the registry layer files in `ai_lsc.registry.layers` remain the authoritative source for tool definitions.

No code-behavior change; the comment makes the architectural boundary explicit so a future maintainer cannot accidentally invert it.

## 7. Verification

| Check | Result |
|---|---|
| AST-parse 100 Python files | **0 failures** |
| `bash -n` on bootstrap.sh + run.sh | **0 failures** |
| Refactored modules import cleanly | **OK** |
| `build_system_context` smoke test | **OK** (dispatch table produces identical output) |
| `resolve_context_files` smoke test | **OK** (returns same file list) |
| Wording sweep grep | **0 matches** for `restored|brought back|related logic` |

## 8. Out-of-scope (preserved per user policy)

- `curl|sh` installers (Ollama, Grafana Alloy, Meilisearch) — C-05 policy (see `whatremains.txt`).
- Layer-file `filesystem` backfill (L-18) — mechanical, ~10 min/layer.
- `defaults.py` 3700-line split (L-14) — conflicts with layer-file decomposition.
- Pre-existing unused imports `JCL_FILE_NAME` (support.py) and `Path` (installer.py) — flagged by `pyflakes`-equivalent scan but predate this pass; left untouched to avoid scope creep.

## 9. Tarball

Packaged as `ai-lsc-moe-qa-pass.tar.gz` in `/home/z/my-project/download/`. Contains the full project tree post-cleanup.

---

## 10. Post-pass cleanup (follow-up)

After the initial MoE QA pass was packaged, two follow-up changes were applied:

### 10.1 Retirement of one-shot migration scripts

The following five scripts were one-shot migrations that had already been
applied to the registry/layer files. Per the project-manager perspective
on the MoE panel ("don't leave dead code sitting around"), they have been
removed from the tree:

- `apply_taxonomy_migration.py` (root) — v3.2 superseded by `apply_10layer_taxonomy.py`.
- `scripts/apply_10layer_taxonomy.py` — taxonomy re-org, applied.
- `scripts/backfill_layer_flags.py` — H-15 flag backfill, applied.
- `scripts/backfill_tool_licenses.py` — license field backfill, applied.
- `scripts/backfill_default_licenses.py` — license default backfill, applied.

The empty `scripts/` directory was also removed. All historical references
in `CHANGES.md`, `TODO.md`, and `QA-PASS-REPORT.md` were patched so no
doc points at a missing file.

### 10.2 Open WebUI launcher fix

`open-webui serve` dropped the `--data-dir` CLI option in a recent
release; the registry's three open-webui launcher commands all used it
and were failing at startup with:

```
No such option '--data-dir'.
```

The data directory is now set via the `WEBUI_DATA_DIR` environment
variable, which is the supported mechanism in current open-webui. The
hermes_webui launcher also dropped the invalid `--env OLLAMA_BASE_URL=...`
trailer (open-webui reads `OLLAMA_BASE_URL` from the process environment
directly, not via a CLI flag). Three sites patched:

- `src/ai_lsc/registry/layers/user_interfaces.py` — `openwebui` launcher.
- `src/ai_lsc/registry/layers/user_interfaces.py` — `hermes_webui` launcher.
- `src/ai_lsc/registry/defaults.py` — `openwebui` launcher.

Each launcher now reads (e.g. for the canonical openwebui):

```
WEBUI_DATA_DIR={workspaces_root}/openwebui open-webui serve --port {port}
```

For hermes_webui the env-prefix also carries `OLLAMA_BASE_URL`:

```
WEBUI_DATA_DIR={workspaces_root}/hermes-webui OLLAMA_BASE_URL=http://localhost:17051 open-webui serve --port {port}
```

The ai-lsc runtime resolves env-prefix shells via `shlex.split()` on the
launcher cmd, so the env-assignment form is parsed correctly.

---

## 11. Open WebUI Python-3.13 audioop fix (follow-up #2)

After the launcher fix landed, open-webui started successfully but crashed
at import time inside the uv-managed tool env:

```
ModuleNotFoundError: No module named 'audioop'
…
ModuleNotFoundError: No module named 'pyaudioop'
```

Root cause: Python 3.13 removed the `audioop` stdlib module (PEP 594).
`pydub` (an open-webui dep) imports `audioop` and falls back to
`pyaudioop` on ImportError; neither was present in the uv-managed
open-webui env at `~/.local/share/uv/tools/open-webui/`.

### Fix

`uv tool install` supports `--with <extra>` for additional dependencies.
The `pkg` field in the registry now carries that flag, and `install_uv`
was hardened to shlex-split `pkg` so the flag passes through verbatim:

- `src/ai_lsc/runtime/installer.py` `install_uv` — shlex-splits `pkg`;
  validates only the first token as the package name; passes remaining
  tokens as additional argv to `uv tool install`. Falls back to pipx
  using just the first token.
- `src/ai_lsc/runtime/installer.py` `_detect_installation` /
  `_binary_name` / `_detect_version` — all now take only the first
  shlex token of `pkg` when looking up the binary on PATH or building
  version-detection commands. (Without this, preflight would look for
  a binary literally named `open-webui --with audioop-lts`.)
- `src/ai_lsc/registry/layers/user_interfaces.py` — both `openwebui`
  and `hermes_webui` installer.pkg changed from `"open-webui"` to
  `"open-webui --with audioop-lts"`. Inline comment explains the
  Python-3.13 / PEP-594 rationale.
- `src/ai_lsc/registry/defaults.py` — openwebui entry updated to match.

### Verification

- 95 Python files AST-parse cleanly.
- Registry loads 187 tools; `validate_registry()` reports 0 errors.
- `shlex.split("open-webui --with audioop-lts")` yields the expected
  argv: `["open-webui", "--with", "audioop-lts"]`.
- `_binary_name("open-webui --with audioop-lts", "uv")` resolves to
  `"open_webui"` (the actual on-PATH binary name).

### Operator workaround for existing installs

If open-webui was installed before this fix landed, the audioop-lts
backport can be added in place:

```bash
~/.local/share/uv/tools/open-webui/bin/python -m pip install audioop-lts
```

Or reinstall via the new pkg spec:

```bash
uv tool install --force "open-webui --with audioop-lts"
```