cleanup: harden contracts, unify doctor health checks, and fix lint

Author: josephgoksu

CLAUDE.md

@@ -307,17 +307,18 @@ TaskWing provides project memory for AI assistants via MCP tools and slash comma
 |------|-------------|
 | `recall` | Retrieve project knowledge (decisions, patterns, constraints) |
 | `task` | Unified task lifecycle (next, current, start, complete) |
-| `plan` | Plan management (clarify, decompose, expand, generate, finalize, audit) |
+| `plan` | Plan management (clarify, generate, audit) |
 | `code` | Code intelligence (find, search, explain, callers, impact, simplify) |
 | `debug` | Diagnose issues systematically with AI-powered analysis |
 | `remember` | Store knowledge in project memory |
 
 ### CLI Commands
 ```bash
-taskwing bootstrap   # Initialize project memory (first-time setup)
-taskwing goal "goal" # Create and activate a development plan
-taskwing task list   # List tasks from active plan
-taskwing plan status # Show progress of active plan
+tw bootstrap        # Initialize project memory (first-time setup)
+tw context "query"  # Search knowledge semantically
+tw add "content"    # Add knowledge to memory
+tw plan new "goal"  # Create development plan
+tw task list        # List tasks from active plan
 ```
 
 ### Autonomous Task Execution (Hooks)

GEMINI.md

@@ -200,17 +200,18 @@ TaskWing provides project memory for AI assistants via MCP tools and slash comma
 |------|-------------|
 | `recall` | Retrieve project knowledge (decisions, patterns, constraints) |
 | `task` | Unified task lifecycle (next, current, start, complete) |
-| `plan` | Plan management (clarify, decompose, expand, generate, finalize, audit) |
+| `plan` | Plan management (clarify, generate, audit) |
 | `code` | Code intelligence (find, search, explain, callers, impact, simplify) |
 | `debug` | Diagnose issues systematically with AI-powered analysis |
 | `remember` | Store knowledge in project memory |
 
 ### CLI Commands
 ```bash
-taskwing bootstrap   # Initialize project memory (first-time setup)
-taskwing goal "goal" # Create and activate a development plan
-taskwing task list   # List tasks from active plan
-taskwing plan status # Show progress of active plan
+tw bootstrap        # Initialize project memory (first-time setup)
+tw context "query"  # Search knowledge semantically
+tw add "content"    # Add knowledge to memory
+tw plan new "goal"  # Create development plan
+tw task list        # List tasks from active plan
 ```
 
 ### Autonomous Task Execution (Hooks)

README.md

@@ -21,6 +21,26 @@ taskwing goal "Add Stripe billing"
 /tw-done
 ```
 
+## Bootstrap and Repair Model
+
+- `taskwing bootstrap` auto-repairs only TaskWing-managed local AI assets.
+- If drift is unmanaged (marker missing/user-owned), bootstrap warns and does not mutate files.
+- Global MCP repair is explicit via `taskwing doctor --fix`.
+- Unmanaged adoption is explicit via `taskwing doctor --fix --adopt-unmanaged`.
+
+Recovery examples:
+
+```bash
+# Inspect current health
+taskwing doctor
+
+# Apply safe repairs for managed drift and MCP config
+taskwing doctor --fix --yes
+
+# Explicitly adopt unmanaged TaskWing-like files, then repair
+taskwing doctor --fix --adopt-unmanaged --yes --ai claude
+```
+
 ## What TaskWing Does
 
 - Stores architecture decisions, constraints, and patterns in local project memory.
@@ -44,7 +64,7 @@ taskwing goal "Add Stripe billing"
 ```json
 {
   "mcpServers": {
-    "taskwing": {
+    "taskwing-mcp": {
       "command": "taskwing",
       "args": ["mcp"]
     }

cmd/bootstrap.go

@@ -36,10 +36,14 @@ var bootstrapCmd = &cobra.Command{
 Bootstrap analyzes your codebase to extract architectural knowledge:
   • Creates .taskwing/ directory structure
   • Sets up AI assistant integration (Claude, Cursor, etc.)
+  • Auto-repairs managed local AI config drift
   • Indexes code symbols (functions, types, etc.)
   • Analyzes code patterns and architecture (requires API key)
   • Extracts decisions and understands WHY choices were made
 
+Bootstrap does NOT adopt unmanaged AI config automatically and does NOT mutate
+global MCP in run mode. Use "taskwing doctor --fix" for explicit repair flows.
+
 Requires: OPENAI_API_KEY or TASKWING_LLM_APIKEY environment variable.
 
 Use --skip-analyze for CI/testing (deterministic, no LLM).`,
@@ -132,25 +136,22 @@ func runBootstrap(cmd *cobra.Command, args []string) error {
 	// ═══════════════════════════════════════════════════════════════════════
 	// PHASE 1: Probe Environment (no side effects)
 	// ═══════════════════════════════════════════════════════════════════════
+	existingGlobalAIs := detectExistingMCPConfigs()
+	globalMCPSet := make(map[string]bool, len(existingGlobalAIs))
+	for _, ai := range existingGlobalAIs {
+		globalMCPSet[ai] = true
+	}
+	previousDetector := bootstrap.GlobalMCPDetector
+	bootstrap.GlobalMCPDetector = func(aiName string) bool {
+		return globalMCPSet[aiName]
+	}
+	defer func() { bootstrap.GlobalMCPDetector = previousDetector }()
+
 	snapshot, err := bootstrap.ProbeEnvironment(cwd)
 	if err != nil {
 		return fmt.Errorf("probe environment: %w", err)
 	}
 
-	// Enhance snapshot with global MCP detection (uses existing helper)
-	existingGlobalAIs := detectExistingMCPConfigs()
-	if len(existingGlobalAIs) > 0 {
-		snapshot.HasAnyGlobalMCP = true
-		snapshot.GlobalMCPAIs = existingGlobalAIs
-		// Update AI health with global MCP info
-		for _, ai := range existingGlobalAIs {
-			if health, ok := snapshot.AIHealth[ai]; ok {
-				health.GlobalMCPExists = true
-				snapshot.AIHealth[ai] = health
-			}
-		}
-	}
-
 	// ═══════════════════════════════════════════════════════════════════════
 	// PHASE 2: Decide Plan (pure function, deterministic)
 	// ═══════════════════════════════════════════════════════════════════════
@@ -203,6 +204,17 @@ func runBootstrap(cmd *cobra.Command, args []string) error {
 
 	// Final success message
 	if !flags.Quiet {
+		if len(plan.ManagedDriftAIs) > 0 {
+			fmt.Printf("managed_drift_fixed: %s\n", strings.Join(plan.ManagedDriftAIs, ", "))
+		}
+		if len(plan.UnmanagedDriftAIs) > 0 {
+			fmt.Printf("unmanaged_drift_detected: %s\n", strings.Join(plan.UnmanagedDriftAIs, ", "))
+			fmt.Println("  ↳ Run `taskwing doctor --fix --adopt-unmanaged` to claim and repair unmanaged TaskWing-like configs.")
+		}
+		if len(plan.GlobalMCPDriftAIs) > 0 {
+			fmt.Printf("global_mcp_drift_detected: %s\n", strings.Join(plan.GlobalMCPDriftAIs, ", "))
+			fmt.Println("  ↳ Run `taskwing doctor --fix` to repair global MCP registration.")
+		}
 		fmt.Println()
 		fmt.Println("✅ Bootstrap complete!")
 	}

cmd/bootstrap_test.go

@@ -45,22 +45,11 @@ func TestInstallMCPServers_OpenCode(t *testing.T) {
 		t.Fatal("MCP section is nil")
 	}
 
-	// Server name should include project directory name
-	expectedServerName := "taskwing-mcp-" + filepath.Base(tmpDir)
+	// Server name must be canonical (strict naming policy)
+	expectedServerName := "taskwing-mcp"
 	serverCfg, ok := config.MCP[expectedServerName]
 	if !ok {
-		// Check if any taskwing-mcp server exists
-		found := false
-		for name := range config.MCP {
-			if len(name) >= 12 && name[:12] == "taskwing-mcp" {
-				found = true
-				serverCfg = config.MCP[name]
-				break
-			}
-		}
-		if !found {
-			t.Fatalf("No taskwing-mcp server entry found in MCP section. Got: %v", config.MCP)
-		}
+		t.Fatalf("Canonical taskwing-mcp server entry missing in MCP section. Got: %v", config.MCP)
 	}
 
 	// Verify type is "local"