audit and remediate mosaic framework path inconsistencies

AUDIT-2026-02-17-framework-consistency.md

@@ -0,0 +1,115 @@
+# Mosaic Framework Consistency Audit
+
+Date: 2026-02-17
+Scope:
+- `~/src/mosaic-bootstrap`
+- `~/src/agent-skills`
+- Installed runtime check: `~/.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:
+- `rails/qa/qa-hook-wrapper.sh`
+- `rails/qa/qa-hook-stdin.sh`
+- `rails/qa/qa-hook-handler.sh`
+- `rails/qa/remediation-hook-handler.sh`
+- `rails/qa/qa-queue-monitor.sh`
+
+Change:
+- Standardized handler paths to `~/.mosaic/rails/qa/...`.
+
+### MF-002 + MF-003 (conditional loading/context detection)
+Updated:
+- `rails/bootstrap/agent-lint.sh`
+- `rails/bootstrap/agent-upgrade.sh`
+- `templates/agent/SPEC.md`
+
+Change:
+- Detection now recognizes both legacy and Mosaic patterns:
+  - `agent-guides` (legacy compatibility)
+  - `~/.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 `~/.mosaic/rails/git/...`.
+- Replaced `~/.claude/skills/...` with `~/.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 `~/.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/jarvis-ralph.json`
+
+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 "~/.mosaic/rails/(qa-hook|remediation-hook|qa-queue-monitor)" ~/src/mosaic-bootstrap -S`
+  - Result: no invalid old-style QA rail paths remain.
+- Installed runtime validation:
+  - `~/.mosaic` contains `rails/git`, `rails/portainer`, `rails/cicd`, `skills`, and `bin` tooling.