drop claude symlink trees for migrated assets

README.md

@@ -48,16 +48,13 @@ Manual commands:
 ~/.mosaic/bin/mosaic-sync-skills --link-only
 ```
 
-## Runtime Compatibility Linking
+## Runtime Compatibility Sync
 
-Installer also links Claude-compatible paths back to Mosaic canonicals:
+Installer syncs Claude runtime overlays as regular files (not symlinks):
 
-- `~/.claude/agent-guides` -> `~/.mosaic/guides`
+- `~/.claude/{CLAUDE.md,settings.json,hooks-config.json,context7-integration.md}` <- `~/.mosaic/runtime/claude/...`
-- `~/.claude/scripts/{git,codex,bootstrap,cicd,portainer}` -> `~/.mosaic/rails/...`
+
-- `~/.claude/templates` -> `~/.mosaic/templates/agent`
+Legacy symlink trees under `~/.claude` for migrated guides/scripts/templates/presets are pruned during sync.
-- `~/.claude/presets/{domains,tech-stacks,workflows}` -> `~/.mosaic/profiles/...`
-- `~/.claude/presets/*.json` runtime overlays -> `~/.mosaic/runtime/claude/settings-overlays/`
-- `~/.claude/{CLAUDE.md,settings.json,hooks-config.json,context7-integration.md}` -> `~/.mosaic/runtime/claude/...`
 
 Run manually:
 

bin/mosaic-doctor

@@ -9,7 +9,7 @@ usage() {
   cat <<USAGE
 Usage: $(basename "$0") [options]
 
-Audit Mosaic runtime linkage and detect drift across agent runtimes.
+Audit Mosaic runtime state and detect drift across agent runtimes.
 
 Options:
   --fail-on-warn   Exit non-zero when warnings are found
@@ -41,16 +41,12 @@ while [[ $# -gt 0 ]]; do
 done
 
 warn_count=0
-
+warn() { warn_count=$((warn_count + 1)); echo "[WARN] $*"; }
-warn() {
-  warn_count=$((warn_count + 1))
-  echo "[WARN] $*"
-}
-
 pass() {
   if [[ $VERBOSE -eq 1 ]]; then
     echo "[OK] $*"
   fi
+  return 0
 }
 
 expect_dir() {
@@ -71,32 +67,46 @@ expect_file() {
   fi
 }
 
-check_tree_links() {
+check_runtime_file_copy() {
-  local src_root="$1"
+  local src="$1"
-  local dst_root="$2"
+  local dst="$2"
 
-  [[ -d "$src_root" ]] || return
+  [[ -f "$src" ]] || return 0
 
-  while IFS= read -r -d '' src; do
+  if [[ ! -e "$dst" ]]; then
-    local rel dst
+    warn "Missing runtime file: $dst"
-    rel="${src#$src_root/}"
+    return
-    dst="$dst_root/$rel"
-
-    if [[ ! -L "$dst" ]]; then
-      warn "Not symlinked: $dst (expected -> $src)"
-      continue
   fi
 
-    local dst_real src_real
+  if [[ -L "$dst" ]]; then
-    dst_real="$(readlink -f "$dst" 2>/dev/null || true)"
+    warn "Runtime file should not be symlinked: $dst"
-    src_real="$(readlink -f "$src" 2>/dev/null || true)"
+    return
+  fi
 
-    if [[ -z "$dst_real" || -z "$src_real" || "$dst_real" != "$src_real" ]]; then
+  if ! cmp -s "$src" "$dst"; then
-      warn "Drifted link: $dst (expected -> $src)"
+    warn "Runtime file drift: $dst (does not match $src)"
   else
-      pass "Linked: $dst"
+    pass "Runtime file synced: $dst"
+  fi
+}
+
+warn_if_symlink_tree_present() {
+  local p="$1"
+  [[ -e "$p" ]] || return 0
+
+  if [[ -L "$p" ]]; then
+    warn "Legacy symlink path still present: $p"
+    return
+  fi
+
+  if [[ -d "$p" ]]; then
+    symlink_count=$(find "$p" -type l 2>/dev/null | wc -l | tr -d ' ')
+    if [[ "$symlink_count" != "0" ]]; then
+      warn "Legacy symlink entries still present under $p: $symlink_count"
+    else
+      pass "No symlinks under legacy path: $p"
+    fi
   fi
-  done < <(find "$src_root" -type f -print0)
 }
 
 echo "[mosaic-doctor] Mosaic home: $MOSAIC_HOME"
@@ -112,37 +122,29 @@ expect_dir "$MOSAIC_HOME/skills-local"
 expect_file "$MOSAIC_HOME/bin/mosaic-link-runtime-assets"
 expect_file "$MOSAIC_HOME/bin/mosaic-sync-skills"
 
-# Claude runtime checks
+# Claude runtime file checks (copied, non-symlink).
-check_tree_links "$MOSAIC_HOME/guides" "$HOME/.claude/agent-guides"
-check_tree_links "$MOSAIC_HOME/rails/git" "$HOME/.claude/scripts/git"
-check_tree_links "$MOSAIC_HOME/rails/codex" "$HOME/.claude/scripts/codex"
-check_tree_links "$MOSAIC_HOME/rails/bootstrap" "$HOME/.claude/scripts/bootstrap"
-check_tree_links "$MOSAIC_HOME/rails/cicd" "$HOME/.claude/scripts/cicd"
-check_tree_links "$MOSAIC_HOME/rails/portainer" "$HOME/.claude/scripts/portainer"
-check_tree_links "$MOSAIC_HOME/templates/agent" "$HOME/.claude/templates"
-check_tree_links "$MOSAIC_HOME/profiles/domains" "$HOME/.claude/presets/domains"
-check_tree_links "$MOSAIC_HOME/profiles/tech-stacks" "$HOME/.claude/presets/tech-stacks"
-check_tree_links "$MOSAIC_HOME/profiles/workflows" "$HOME/.claude/presets/workflows"
-check_tree_links "$MOSAIC_HOME/runtime/claude/settings-overlays" "$HOME/.claude/presets"
-
 for rf in CLAUDE.md settings.json hooks-config.json context7-integration.md; do
-  src="$MOSAIC_HOME/runtime/claude/$rf"
+  check_runtime_file_copy "$MOSAIC_HOME/runtime/claude/$rf" "$HOME/.claude/$rf"
-  dst="$HOME/.claude/$rf"
-  [[ -f "$src" ]] || continue
-  if [[ ! -L "$dst" ]]; then
-    warn "Not symlinked: $dst (expected -> $src)"
-    continue
-  fi
-  dst_real="$(readlink -f "$dst" 2>/dev/null || true)"
-  src_real="$(readlink -f "$src" 2>/dev/null || true)"
-  if [[ -z "$dst_real" || -z "$src_real" || "$dst_real" != "$src_real" ]]; then
-    warn "Drifted link: $dst (expected -> $src)"
-  else
-    pass "Linked: $dst"
-  fi
 done
 
-# Skills runtime checks
+# Legacy migration surfaces should no longer contain symlink trees.
+legacy_paths=(
+  "$HOME/.claude/agent-guides"
+  "$HOME/.claude/scripts/git"
+  "$HOME/.claude/scripts/codex"
+  "$HOME/.claude/scripts/bootstrap"
+  "$HOME/.claude/scripts/cicd"
+  "$HOME/.claude/scripts/portainer"
+  "$HOME/.claude/templates"
+  "$HOME/.claude/presets/domains"
+  "$HOME/.claude/presets/tech-stacks"
+  "$HOME/.claude/presets/workflows"
+)
+for p in "${legacy_paths[@]}"; do
+  warn_if_symlink_tree_present "$p"
+done
+
+# Skills runtime checks (still symlinked into runtime-specific skills dirs).
 for runtime_skills in "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.config/opencode/skills"; do
   [[ -d "$runtime_skills" ]] || continue
 
@@ -157,7 +159,6 @@ for runtime_skills in "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.confi
     fi
 
     if [[ ! -L "$target" ]]; then
-      # Runtime-specific local skills are allowed only for hidden/system entries.
       warn "Non-symlink skill entry: $target"
       continue
     fi
@@ -172,16 +173,12 @@ for runtime_skills in "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.confi
   done < <(find "$MOSAIC_HOME/skills" "$MOSAIC_HOME/skills-local" -mindepth 1 -maxdepth 1 -type d -print0)
 done
 
+# Broken links only in managed runtime skill dirs.
 link_roots=(
-  "$HOME/.claude/agent-guides"
-  "$HOME/.claude/scripts"
-  "$HOME/.claude/templates"
-  "$HOME/.claude/presets"
   "$HOME/.claude/skills"
   "$HOME/.codex/skills"
   "$HOME/.config/opencode/skills"
 )
-
 existing_link_roots=()
 for d in "${link_roots[@]}"; do
   [[ -e "$d" ]] && existing_link_roots+=("$d")
@@ -192,7 +189,7 @@ if [[ ${#existing_link_roots[@]} -gt 0 ]]; then
   broken_links=$(find "${existing_link_roots[@]}" -xtype l 2>/dev/null | wc -l | tr -d ' ')
 fi
 if [[ "$broken_links" != "0" ]]; then
-  warn "Broken symlinks detected across runtimes: $broken_links"
+  warn "Broken skill symlinks detected: $broken_links"
 fi
 
 echo "[mosaic-doctor] warnings=$warn_count"

bin/mosaic-link-runtime-assets

@@ -2,59 +2,74 @@
 set -euo pipefail
 
 MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
-
 backup_stamp="$(date +%Y%m%d%H%M%S)"
 
-link_file() {
+copy_file_managed() {
   local src="$1"
   local dst="$2"
 
   mkdir -p "$(dirname "$dst")"
 
   if [[ -L "$dst" ]]; then
-    local cur
+    rm -f "$dst"
-    cur="$(readlink -f "$dst" 2>/dev/null || true)"
+  fi
-    local want
+
-    want="$(readlink -f "$src" 2>/dev/null || true)"
+  if [[ -f "$dst" ]]; then
-    if [[ -n "$cur" && -n "$want" && "$cur" == "$want" ]]; then
+    if cmp -s "$src" "$dst"; then
       return
     fi
-    rm -f "$dst"
-  elif [[ -e "$dst" ]]; then
     mv "$dst" "${dst}.mosaic-bak-${backup_stamp}"
   fi
 
-  ln -s "$src" "$dst"
+  cp "$src" "$dst"
 }
 
-link_tree_files() {
+remove_legacy_path() {
-  local src_root="$1"
+  local p="$1"
-  local dst_root="$2"
 
-  [[ -d "$src_root" ]] || return
+  if [[ -L "$p" ]]; then
+    rm -f "$p"
+    return
+  fi
 
-  while IFS= read -r -d '' src; do
+  if [[ -d "$p" ]]; then
-    local rel
+    find "$p" -depth -type l -delete 2>/dev/null || true
-    rel="${src#$src_root/}"
+    find "$p" -depth -type d -empty -delete 2>/dev/null || true
-    local dst="$dst_root/$rel"
+    return
-    link_file "$src" "$dst"
+  fi
-  done < <(find "$src_root" -type f -print0)
+
+  # Remove stale symlinked files if present.
+  if [[ -e "$p" && -L "$p" ]]; then
+    rm -f "$p"
+  fi
 }
 
-# Claude compatibility layer: keep existing ~/.claude workflows functional,
+# Remove compatibility symlink surfaces for migrated content.
-# but source canonical rails from ~/.mosaic.
+legacy_paths=(
-link_tree_files "$MOSAIC_HOME/guides" "$HOME/.claude/agent-guides"
+  "$HOME/.claude/agent-guides"
-link_tree_files "$MOSAIC_HOME/rails/git" "$HOME/.claude/scripts/git"
+  "$HOME/.claude/scripts/git"
-link_tree_files "$MOSAIC_HOME/rails/codex" "$HOME/.claude/scripts/codex"
+  "$HOME/.claude/scripts/codex"
-link_tree_files "$MOSAIC_HOME/rails/bootstrap" "$HOME/.claude/scripts/bootstrap"
+  "$HOME/.claude/scripts/bootstrap"
-link_tree_files "$MOSAIC_HOME/rails/cicd" "$HOME/.claude/scripts/cicd"
+  "$HOME/.claude/scripts/cicd"
-link_tree_files "$MOSAIC_HOME/rails/portainer" "$HOME/.claude/scripts/portainer"
+  "$HOME/.claude/scripts/portainer"
-link_tree_files "$MOSAIC_HOME/templates/agent" "$HOME/.claude/templates"
+  "$HOME/.claude/scripts/debug-hook.sh"
-link_tree_files "$MOSAIC_HOME/profiles/domains" "$HOME/.claude/presets/domains"
+  "$HOME/.claude/scripts/qa-hook-handler.sh"
-link_tree_files "$MOSAIC_HOME/profiles/tech-stacks" "$HOME/.claude/presets/tech-stacks"
+  "$HOME/.claude/scripts/qa-hook-stdin.sh"
-link_tree_files "$MOSAIC_HOME/profiles/workflows" "$HOME/.claude/presets/workflows"
+  "$HOME/.claude/scripts/qa-hook-wrapper.sh"
-link_tree_files "$MOSAIC_HOME/runtime/claude/settings-overlays" "$HOME/.claude/presets"
+  "$HOME/.claude/scripts/qa-queue-monitor.sh"
+  "$HOME/.claude/scripts/remediation-hook-handler.sh"
+  "$HOME/.claude/templates"
+  "$HOME/.claude/presets/domains"
+  "$HOME/.claude/presets/tech-stacks"
+  "$HOME/.claude/presets/workflows"
+  "$HOME/.claude/presets/jarvis-ralph.json"
+)
 
+for p in "${legacy_paths[@]}"; do
+  remove_legacy_path "$p"
+done
+
+# Runtime files are synced as regular files (not symlinks) to reduce path confusion.
 for runtime_file in \
   CLAUDE.md \
   settings.json \
@@ -62,20 +77,8 @@ for runtime_file in \
   context7-integration.md; do
   src="$MOSAIC_HOME/runtime/claude/$runtime_file"
   [[ -f "$src" ]] || continue
-  link_file "$src" "$HOME/.claude/$runtime_file"
+  copy_file_managed "$src" "$HOME/.claude/$runtime_file"
 done
 
-for qa_script in \
+echo "[mosaic-link] Runtime assets synced (non-symlink mode)"
-  debug-hook.sh \
-  qa-hook-handler.sh \
-  qa-hook-stdin.sh \
-  qa-hook-wrapper.sh \
-  qa-queue-monitor.sh \
-  remediation-hook-handler.sh; do
-  src="$MOSAIC_HOME/rails/qa/$qa_script"
-  [[ -f "$src" ]] || continue
-  link_file "$src" "$HOME/.claude/scripts/$qa_script"
-done
-
-echo "[mosaic-link] Runtime compatibility assets linked"
 echo "[mosaic-link] Canonical source: $MOSAIC_HOME"

profiles/README.md

@@ -19,4 +19,4 @@ Current runtime overlay example:
 
 ## Claude Compatibility
 
-`mosaic-link-runtime-assets` links these into `~/.claude/presets/*` so existing Claude flows keep working while `~/.mosaic` remains canonical.
+`mosaic-link-runtime-assets` prunes legacy preset symlink trees from `~/.claude` so Mosaic remains canonical and Claude uses runtime overlays that reference Mosaic paths directly.