fix(workspace): overhaul workspace detection and tooling

- Extract hardcoded Tier markers into dynamic detector Options
- Redesign walkUp to retain highest-priority roots instead of returning eagerly
- Refactor rag_index_workspace tool to necessitate a solid 'workspace_root' rather than 'file_path'
- Introduce dual-stage AI validation via the 'confirm' tool schema parameter
- Eradicate legacy hardcoded workspace paths inside test suite (avoid 'backend' assumptions)
- Update documentation and server.json resolving legacy file_path instructions
- Expose FindAlternativeCandidates securely via engine wrappers
- Introduce structural clean-ups in index_status (hasParentRagcode) and Registry logic (absorbChildren) to thwart fragmentation

Author: doITmagic

pkg/indexer/index_status.go

@@ -55,13 +55,39 @@ func callerChain(skip, depth int) string {
 	return strings.Join(parts, " ← ")
 }
 
+// hasParentRagcode walks up the directory tree to check if a `.ragcode` folder exists
+// up to 10 levels above the starting root.
+func hasParentRagcode(root string) bool {
+	dir := root
+	if abs, err := filepath.Abs(dir); err == nil {
+		dir = abs
+	}
+	for i := 0; i < 10; i++ {
+		parent := filepath.Dir(dir)
+		if parent == dir {
+			break
+		}
+		dir = parent
+
+		ragcodePath := filepath.Join(dir, ".ragcode")
+		if stat, err := os.Stat(ragcodePath); err == nil && stat.IsDir() {
+			return true
+		}
+	}
+	return false
+}
+
 // SaveIndexStatus writes the IndexStatus to {workspaceRoot}/.ragcode/index_status.json.
 // The write is atomic: data is written to a temp file first, then renamed into place,
 // so concurrent readers always see a complete JSON file.
 func SaveIndexStatus(workspaceRoot string, status *IndexStatus) {
 	if workspaceRoot == "" || status == nil {
 		return
 	}
+	if hasParentRagcode(workspaceRoot) {
+		logger.Instance.Debug("[INDEX_STATUS] 🚫 Blocked creating .ragcode in %s (parent already has .ragcode)", workspaceRoot)
+		return
+	}
 	dir := filepath.Join(workspaceRoot, ".ragcode")
 	dirExisted := true
 	if _, statErr := os.Stat(dir); os.IsNotExist(statErr) {

pkg/workspace/registry/registry.go

@@ -145,6 +145,7 @@ func (r *Registry) Upsert(root, name, client string) (*Entry, error) {
 		if client != "" {
 			entry.Client = client
 		}
+		r.absorbChildren(root)
 		return entry, r.save()
 	}
 
@@ -164,6 +165,7 @@ func (r *Registry) Upsert(root, name, client string) (*Entry, error) {
 		r.indexName[lower] = append(r.indexName[lower], id)
 	}
 
+	r.absorbChildren(root)
 	return entry, r.save()
 }
 
@@ -221,6 +223,7 @@ func (r *Registry) PromoteCandidate(ctx context.Context, root, client string, ex
 		"candidate_count":     candidate.Count,
 	})
 
+	r.absorbChildren(cleanRoot)
 	return r.save()
 }
 
@@ -281,6 +284,51 @@ func (r *Registry) FindParentWorkspace(path string) (string, bool) {
 	return bestRoot, true
 }
 
+// absorbChildren removes any registered entries that are subdirectories of parentRoot.
+// It also cleans up the associated .ragcode folders on disk.
+func (r *Registry) absorbChildren(parentRoot string) {
+	cleanParent := strings.ToLower(filepath.Clean(parentRoot))
+	prefix := strings.TrimRight(cleanParent, string(filepath.Separator)) + string(filepath.Separator)
+
+	var toDelete []string
+	for id, entry := range r.entries {
+		entryRoot := strings.ToLower(filepath.Clean(entry.Root))
+		if entryRoot != cleanParent && strings.HasPrefix(entryRoot, prefix) {
+			toDelete = append(toDelete, id)
+		}
+	}
+
+	for _, id := range toDelete {
+		child := r.entries[id]
+		delete(r.entries, id)
+		delete(r.indexRoot, strings.ToLower(child.Root))
+		if child.Name != "" {
+			lower := strings.ToLower(child.Name)
+			ids := r.indexName[lower]
+			filtered := make([]string, 0, len(ids))
+			for _, existing := range ids {
+				if existing != id {
+					filtered = append(filtered, existing)
+				}
+			}
+			if len(filtered) == 0 {
+				delete(r.indexName, lower)
+			} else {
+				r.indexName[lower] = filtered
+			}
+		}
+
+		// Auto-cleanup: remove .ragcode directory from child
+		ragcodeDir := filepath.Join(child.Root, ".ragcode")
+		_ = os.RemoveAll(ragcodeDir)
+
+		r.audit.Record(context.Background(), "registry.child_absorbed", map[string]any{
+			"child_root":  child.Root,
+			"parent_root": parentRoot,
+		})
+	}
+}
+
 // LookupByName returns entries matching the provided name.
 func (r *Registry) LookupByName(name string) []*Entry {
 	r.mu.Lock()