audit and remediate mosaic framework path inconsistencies

2026-02-17 13:08:55 -06:00
parent 4d6a78a277
commit 5ac015b177
10 changed files with 134 additions and 19 deletions
--- a/AUDIT-2026-02-17-framework-consistency.md
+++ b/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.
--- a/rails/bootstrap/agent-lint.sh
+++ b/rails/bootstrap/agent-lint.sh
@@ -11,7 +11,7 @@
 # Checks per project:
 #   1. Has CLAUDE.md?
 #   2. Has AGENTS.md?
-#   3. CLAUDE.md references agent-guides (conditional loading)?
+#   3. CLAUDE.md references conditional context/guides?
 #   4. CLAUDE.md has quality gates?
 #   5. For monorepos: sub-directories have AGENTS.md?

@@ -102,10 +102,10 @@ check_agents_md() {
  [[ -f "$1/AGENTS.md" ]]
 }

-# Check conditional loading (references agent-guides)
+# Check conditional loading/context (references guides or conditional section)
 check_conditional_loading() {
  local claude_md="$1/CLAUDE.md"
-  [[ -f "$claude_md" ]] && grep -qi "agent-guides\|conditional.*loading\|conditional.*documentation" "$claude_md" 2>/dev/null
+  [[ -f "$claude_md" ]] && grep -qi "agent-guides\|~/.mosaic/guides\|conditional.*loading\|conditional.*documentation\|conditional.*context" "$claude_md" 2>/dev/null
 }

 # Check quality gates
@@ -205,7 +205,7 @@ JSONEOF
  if $VERBOSE && ! $JSON_OUTPUT; then
    [[ "$has_claude" == "MISS" ]] && echo "    ${DIM}  CLAUDE.md missing${NC}"
    [[ "$has_agents" == "MISS" ]] && echo "    ${DIM}  AGENTS.md missing${NC}"
-    [[ "$has_guides" == "MISS" ]] && echo "    ${DIM}  No conditional loading (agent-guides not referenced)${NC}"
+    [[ "$has_guides" == "MISS" ]] && echo "    ${DIM}  No conditional context/loading section detected${NC}"
    [[ "$has_quality" == "MISS" ]] && echo "    ${DIM}  No quality gates section${NC}"
    if [[ "$mono_status" == MISS:* ]]; then
      echo "    ${DIM}  Monorepo sub-AGENTS.md missing: ${mono_status#MISS:}${NC}"
--- a/rails/bootstrap/agent-upgrade.sh
+++ b/rails/bootstrap/agent-upgrade.sh
@@ -135,7 +135,7 @@ inject_fragment() {
  # Determine detection pattern for this fragment
  local detect_pattern
  case "$fragment_name" in
-    conditional-loading) detect_pattern="agent-guides\|Conditional.*Loading\|Conditional.*Documentation" ;;
+    conditional-loading) detect_pattern="agent-guides\|~/.mosaic/guides\|Conditional.*Loading\|Conditional.*Documentation\|Conditional.*Context" ;;
    commit-format) detect_pattern="<type>.*#issue\|Types:.*feat.*fix" ;;
    secrets) detect_pattern="NEVER hardcode secrets\|\.env.example.*committed" ;;
    multi-agent) detect_pattern="Multi-Agent Coordination\|pull --rebase.*before" ;;
--- a/rails/qa/qa-hook-handler.sh
+++ b/rails/qa/qa-hook-handler.sh
@@ -1,6 +1,6 @@
 #!/bin/bash
 # Universal QA hook handler with robust error handling
-# Location: ~/.mosaic/rails/qa-hook-handler.sh
+# Location: ~/.mosaic/rails/qa/qa-hook-handler.sh

 # Don't exit on unset variables initially to handle missing params gracefully
 set -eo pipefail
@@ -194,4 +194,4 @@ claude -p "Use Task tool to launch universal-qa-agent for report: $REPORT_PATH"
 \`\`\`
 EOF

-echo "[$(date '+%Y-%m-%d %H:%M:%S')] Created report template at: $REPORT_PATH" | tee -a "$LOG_FILE"
+echo "[$(date '+%Y-%m-%d %H:%M:%S')] Created report template at: $REPORT_PATH" | tee -a "$LOG_FILE"
--- a/rails/qa/qa-hook-stdin.sh
+++ b/rails/qa/qa-hook-stdin.sh
@@ -1,6 +1,6 @@
 #!/bin/bash
 # QA Hook handler that reads from stdin
-# Location: ~/.mosaic/rails/qa-hook-stdin.sh
+# Location: ~/.mosaic/rails/qa/qa-hook-stdin.sh

 set -eo pipefail

@@ -51,9 +51,9 @@ if ! [[ "$FILE_PATH" =~ \.(ts|tsx|js|jsx|mjs|cjs)$ ]]; then
 fi

 # Call the main QA handler with extracted parameters
-if [ -f ~/.mosaic/rails/qa-hook-handler.sh ]; then
+if [ -f ~/.mosaic/rails/qa/qa-hook-handler.sh ]; then
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] Calling QA handler for $FILE_PATH" >> "$LOG_FILE"
-    ~/.mosaic/rails/qa-hook-handler.sh "$TOOL_NAME" "$FILE_PATH" 2>&1 | tee -a "$LOG_FILE"
+    ~/.mosaic/rails/qa/qa-hook-handler.sh "$TOOL_NAME" "$FILE_PATH" 2>&1 | tee -a "$LOG_FILE"
 else
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] [ERROR] QA handler script not found" >> "$LOG_FILE"
-fi
+fi
--- a/rails/qa/qa-hook-wrapper.sh
+++ b/rails/qa/qa-hook-wrapper.sh
@@ -13,7 +13,7 @@ echo "[$(date '+%Y-%m-%d %H:%M:%S')] Hook wrapper called: tool=$TOOL_NAME file=$

 # Call the actual QA handler if we have a file
 if [ -n "$FILE_PATH" ]; then
-    ~/.mosaic/rails/qa-hook-handler.sh "$TOOL_NAME" "$FILE_PATH"
+    ~/.mosaic/rails/qa/qa-hook-handler.sh "$TOOL_NAME" "$FILE_PATH"
 else
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] No file path available for QA check" >> logs/qa-automation.log 2>/dev/null || true
-fi
+fi
--- a/rails/qa/qa-queue-monitor.sh
+++ b/rails/qa/qa-queue-monitor.sh
@@ -1,6 +1,6 @@
 #!/bin/bash
 # Monitor QA queues with graceful handling of missing directories
-# Location: ~/.mosaic/rails/qa-queue-monitor.sh
+# Location: ~/.mosaic/rails/qa/qa-queue-monitor.sh

 PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)

@@ -88,4 +88,4 @@ echo "=== Queue Processing Tips ==="
 echo "• View pending reports: ls -la $PROJECT_ROOT/docs/reports/qa-automation/pending/"
 echo "• Check stale reports: find $PROJECT_ROOT -path '*/in-progress/*' -mmin +60"
 echo "• Manual escalation: mv {report} {path}/escalated/"
-echo "• View full log: tail -f $PROJECT_ROOT/logs/qa-automation.log"
+echo "• View full log: tail -f $PROJECT_ROOT/logs/qa-automation.log"
--- a/rails/qa/remediation-hook-handler.sh
+++ b/rails/qa/remediation-hook-handler.sh
@@ -1,6 +1,6 @@
 #!/bin/bash
 # Universal remediation hook handler with error recovery
-# Location: ~/.mosaic/rails/remediation-hook-handler.sh
+# Location: ~/.mosaic/rails/qa/remediation-hook-handler.sh

 set -euo pipefail

@@ -63,4 +63,4 @@ claude -p "Use Task tool to launch auto-remediation-agent for:
 - Remediation Report: $IN_PROGRESS_DIR/$(basename "$REPORT_FILE")
 - Actions File: $ACTIONS_PATH
 - Max Iterations: 5
-Process the report, create action plan using Sequential Thinking, research with Context7, and execute fixes systematically." 2>&1 | tee -a "$LOG_FILE"
+Process the report, create action plan using Sequential Thinking, research with Context7, and execute fixes systematically." 2>&1 | tee -a "$LOG_FILE"
--- a/runtime/claude/CLAUDE.md
+++ b/runtime/claude/CLAUDE.md
@@ -17,7 +17,7 @@ Before applying any runtime-specific guidance in this file, load and apply:

 ## Skills System

-**97 skills available in `~/.mosaic/skills/`.** Skills are instruction packages that provide domain expertise. Source: `mosaic/agent-skills` repo (93 community) + 4 local-only.
+**Skills are available in `~/.mosaic/skills/`.** Skills are instruction packages that provide domain expertise from `mosaic/agent-skills` plus local Mosaic skills.

 **Load a skill by reading its SKILL.md:**
 ```
--- a/templates/agent/SPEC.md
+++ b/templates/agent/SPEC.md
@@ -56,7 +56,7 @@ The `agent-lint.sh` tool checks for these markers:
 |-------|---------------|
 | CLAUDE.md exists | File present at project root |
 | AGENTS.md exists | File present at project root |
-| Conditional loading | CLAUDE.md contains `agent-guides` or `Conditional` + `Loading` |
+| Conditional context/loading | CLAUDE.md contains `~/.mosaic/guides` or `Conditional` + `Loading/Context` |
 | Quality gates | CLAUDE.md contains `Quality Gates` or quality commands (test, lint, typecheck) |
 | Monorepo sub-agents | Each app/package dir with own manifest has AGENTS.md |