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

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.