From 5ac015b17788ffb14a36221ba851ee5123e4228b Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Tue, 17 Feb 2026 13:08:55 -0600 Subject: [PATCH] audit and remediate mosaic framework path inconsistencies --- AUDIT-2026-02-17-framework-consistency.md | 115 ++++++++++++++++++++++ rails/bootstrap/agent-lint.sh | 8 +- rails/bootstrap/agent-upgrade.sh | 2 +- rails/qa/qa-hook-handler.sh | 4 +- rails/qa/qa-hook-stdin.sh | 8 +- rails/qa/qa-hook-wrapper.sh | 4 +- rails/qa/qa-queue-monitor.sh | 4 +- rails/qa/remediation-hook-handler.sh | 4 +- runtime/claude/CLAUDE.md | 2 +- templates/agent/SPEC.md | 2 +- 10 files changed, 134 insertions(+), 19 deletions(-) create mode 100644 AUDIT-2026-02-17-framework-consistency.md diff --git a/AUDIT-2026-02-17-framework-consistency.md b/AUDIT-2026-02-17-framework-consistency.md new file mode 100644 index 0000000..c5c27c1 --- /dev/null +++ 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. diff --git a/rails/bootstrap/agent-lint.sh b/rails/bootstrap/agent-lint.sh index 0294c46..762b012 100755 --- 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}" diff --git a/rails/bootstrap/agent-upgrade.sh b/rails/bootstrap/agent-upgrade.sh index efd3bd6..c642503 100755 --- 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=".*#issue\|Types:.*feat.*fix" ;; secrets) detect_pattern="NEVER hardcode secrets\|\.env.example.*committed" ;; multi-agent) detect_pattern="Multi-Agent Coordination\|pull --rebase.*before" ;; diff --git a/rails/qa/qa-hook-handler.sh b/rails/qa/qa-hook-handler.sh index e89e332..4e55aff 100755 --- 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" \ No newline at end of file +echo "[$(date '+%Y-%m-%d %H:%M:%S')] Created report template at: $REPORT_PATH" | tee -a "$LOG_FILE" diff --git a/rails/qa/qa-hook-stdin.sh b/rails/qa/qa-hook-stdin.sh index e84d891..a20d500 100755 --- 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 \ No newline at end of file +fi diff --git a/rails/qa/qa-hook-wrapper.sh b/rails/qa/qa-hook-wrapper.sh index 9428379..d3d24a3 100755 --- 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 \ No newline at end of file +fi diff --git a/rails/qa/qa-queue-monitor.sh b/rails/qa/qa-queue-monitor.sh index 7f83fe7..267ce47 100755 --- 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" \ No newline at end of file +echo "• View full log: tail -f $PROJECT_ROOT/logs/qa-automation.log" diff --git a/rails/qa/remediation-hook-handler.sh b/rails/qa/remediation-hook-handler.sh index 102c857..1b8fbb8 100755 --- 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" \ No newline at end of file +Process the report, create action plan using Sequential Thinking, research with Context7, and execute fixes systematically." 2>&1 | tee -a "$LOG_FILE" diff --git a/runtime/claude/CLAUDE.md b/runtime/claude/CLAUDE.md index 9978e12..fa69d36 100644 --- 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:** ``` diff --git a/templates/agent/SPEC.md b/templates/agent/SPEC.md index 30785e3..0d5aad7 100644 --- 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 |