# Mosaic Framework Consistency Audit

Date: 2026-02-17
Scope:

- `~/src/mosaic-bootstrap`
- `~/src/agent-skills`
- Installed runtime check: `~/.config/mosaic`

## Findings

| ID     | Severity | Finding                                                                                                                              | Status     |
| ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
| MF-001 | High     | QA rails scripts referenced invalid paths (missing `/qa/` segment) for `qa-hook-handler.sh` calls.                                   | Remediated |
| MF-002 | Medium   | Conditional-loading detection was biased to legacy `agent-guides` markers and missed Mosaic `guides`/`Conditional Context` phrasing. | Remediated |
| MF-003 | Medium   | Framework spec text still described detection as `agent-guides`-based only.                                                          | Remediated |
| MF-004 | Medium   | Runtime Claude overlay hardcoded skill count, which drifts over time.                                                                | Remediated |
| MF-005 | High     | `pr-reviewer` skill used legacy `~/.claude/scripts/git` and `~/.claude/skills` paths.                                                | Remediated |
| MF-006 | Medium   | `using-git-worktrees` prioritized `CLAUDE.md` only and ignored Mosaic-first docs (`AGENTS.md`/`SOUL.md`).                            | Remediated |
| MF-007 | Medium   | Marketing skills used `.claude/product-marketing-context.md` instead of Mosaic repo-local path.                                      | Remediated |
| MF-008 | Low      | `agent-skills/README.md` manual install/adaptation guidance referenced legacy Claude-only paths.                                     | Remediated |
| MF-009 | Low      | Historical creation-log contained stale Claude-specific path examples.                                                               | Remediated |

## Remediation Details

### MF-001 (QA rails path correction)

Updated:

- `tools/qa/qa-hook-wrapper.sh`
- `tools/qa/qa-hook-stdin.sh`
- `tools/qa/qa-hook-handler.sh`
- `tools/qa/remediation-hook-handler.sh`
- `tools/qa/qa-queue-monitor.sh`

Change:

- Standardized handler paths to `~/.config/mosaic/tools/qa/...`.

### MF-002 + MF-003 (conditional loading/context detection)

Updated:

- `tools/bootstrap/agent-lint.sh`
- `tools/bootstrap/agent-upgrade.sh`
- `templates/agent/SPEC.md`

Change:

- Detection now recognizes both legacy and Mosaic patterns:
  - `agent-guides` (legacy compatibility)
  - `~/.config/mosaic/guides`
  - `Conditional Loading`
  - `Conditional Context`

### MF-004 (runtime overlay drift-proofing)

Updated:

- `runtime/claude/CLAUDE.md`

Change:

- Removed hardcoded skills count text.

### MF-005 (pr-reviewer skill path migration)

Updated:

- `skills/pr-reviewer/SKILL.md`

Change:

- Replaced all `~/.claude/scripts/git/...` with `~/.config/mosaic/tools/git/...`.
- Replaced `~/.claude/skills/...` with `~/.config/mosaic/skills/...`.

### MF-006 (worktree skill docs hierarchy)

Updated:

- `skills/using-git-worktrees/SKILL.md`

Change:

- Replaced CLAUDE-only checks with `AGENTS.md` / `SOUL.md` (fallback: `CLAUDE.md`).

### MF-007 (marketing context path migration)

Updated:

- `skills/product-marketing-context/SKILL.md`
- All skills referencing product-marketing-context path (bulk update)

Change:

- Standardized context path to `.mosaic/product-marketing-context.md`.

### MF-008 + MF-009 (repo guidance cleanup)

Updated:

- `README.md` (agent-skills)
- `skills/writing-skills/SKILL.md`
- `skills/writing-skills/examples/CLAUDE_MD_TESTING.md`
- `skills/systematic-debugging/CREATION-LOG.md`

Change:

- Standardized references to `~/.config/mosaic/skills`.
- Removed stale Claude-only wording.

## Residual Legacy References (Intentional)

The following legacy references remain in `mosaic-bootstrap` by design and are not inconsistencies:

- Runtime compatibility tooling for Claude home directory management:
  - `bin/mosaic-link-runtime-assets`
  - `bin/mosaic-clean-runtime`
  - `bin/mosaic-doctor`
  - `bin/mosaic-sync-skills`
  - `bin/mosaic-migrate-local-skills`
- Documentation explaining Claude runtime overlays:
  - `README.md`
  - `profiles/README.md`
  - `adapters/claude.md`
  - `runtime/claude/settings-overlays/` (sample overlay; now shipped sanitized under `examples/overlays/`)

These are required to support existing Claude runtime integration while keeping Mosaic as canonical source.

## Verification

Executed checks:

- `rg -n "~/.claude|\\.claude/|agent-guides" ~/src/agent-skills -S`
  - Result: no matches after remediation.
- `rg -n "~/.config/mosaic/tools/(qa-hook|remediation-hook|qa-queue-monitor)" ~/src/mosaic-bootstrap -S`
  - Result: no invalid old-style QA rail paths remain.
- Installed runtime validation:
  - `~/.config/mosaic` contains `tools/git`, `tools/portainer`, `tools/cicd`, `skills`, and `bin` tooling.
