fix(flowctl): use vector_distance_cos for skill matching

Replace vector_top_k (requires ANN index, fails in embedded libSQL)
with vector_distance_cos (exact search, no index needed). Works
unconditionally in embedded mode. Performance is <1ms for 30 skills.

Also lower default threshold from 0.75 to 0.70 based on testing —
"deprecate old module" scores 0.73 against flow-code-deprecation.

Tested: all 5 new skills match correctly with relevant queries.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: z23cc

flowctl/crates/flowctl-cli/src/commands/skill.rs

@@ -33,7 +33,7 @@ pub enum SkillCmd {
         #[arg(long, default_value = "5")]
         limit: usize,
         /// Minimum cosine similarity threshold.
-        #[arg(long, default_value = "0.75")]
+        #[arg(long, default_value = "0.70")]
         threshold: f64,
     },
 }

flowctl/crates/flowctl-db/src/skill.rs

@@ -112,27 +112,33 @@ impl SkillRepo {
         };
         let lit = vec_to_literal(&vec);
 
+        // Use vector_distance_cos() instead of vector_top_k() — works without
+        // a vector index (no ANN index required in embedded mode). Exact search
+        // via full table scan; perfectly fast for <10,000 rows (~30 skills).
         let rows_result = self
             .conn
             .query(
-                "SELECT s.name, s.description, top.distance
-                   FROM vector_top_k('skills_emb_idx', vector32(?1), ?2) AS top
-                   JOIN skills s ON s.rowid = top.id",
+                "SELECT s.name, s.description,
+                        vector_distance_cos(s.embedding, vector32(?1)) AS distance
+                   FROM skills s
+                  WHERE s.embedding IS NOT NULL
+                  ORDER BY distance ASC
+                  LIMIT ?2",
                 params![lit, limit as i64],
             )
             .await;
 
         let mut rows = match rows_result {
             Ok(r) => r,
-            Err(_) => return Ok(vec![]), // vector index unavailable
+            Err(_) => return Ok(vec![]), // vector functions unavailable
         };
 
         let mut out = Vec::new();
         while let Some(row) = rows.next().await? {
             let dist: f64 = row.get(2)?;
-            // Convert L2 distance to cosine similarity.
-            // For unit-norm vectors: cos_sim = 1 - (L2^2 / 2).
-            let score = 1.0 - (dist * dist / 2.0);
+            // Cosine distance → cosine similarity: sim = 1 - dist
+            // (0 = identical, 1 = orthogonal, 2 = opposite)
+            let score = 1.0 - dist;
             if score >= threshold {
                 out.push(SkillMatch {
                     name: row.get::<String>(0)?,
@@ -231,8 +237,9 @@ mod tests {
         assert!(matches.len() <= 5);
     }
 
-    /// Semantic match end-to-end. Gated behind `#[ignore]` because the
-    /// first run downloads the BGE-small model (~130MB).
+    /// Semantic match end-to-end using vector_distance_cos (no index needed).
+    /// Gated behind `#[ignore]` because the first run downloads the
+    /// BGE-small model (~130MB).
     #[tokio::test]
     #[ignore = "requires fastembed model (~130MB); run with --ignored"]
     async fn test_match_skills_semantic() {
@@ -248,13 +255,19 @@ mod tests {
             .expect("upsert");
 
         let matches = repo
-            .match_skills("architecture design", 2, 0.3)
+            .match_skills("architecture design", 3, 0.3)
             .await
             .expect("match_skills");
         assert!(!matches.is_empty(), "expected at least one match");
+        // "plan" (Design and architect...) should be the best match
         assert_eq!(
             matches[0].name, "plan",
-            "expected 'plan' as best match for architecture query"
+            "expected 'plan' as best match for architecture query, got '{}'",
+            matches[0].name
         );
+        // Scores should be between 0 and 1
+        for m in &matches {
+            assert!(m.score > 0.0 && m.score <= 1.0, "score out of range: {}", m.score);
+        }
     }
 }

skills/flow-code-plan/steps.md

@@ -66,7 +66,7 @@ After clarity check, match the request against registered engineering discipline
 1. Translate the request to English keywords (if not already English). This costs zero tokens — you're already processing the request.
 2. Run:
    ```bash
-   $FLOWCTL skill match "<english keywords>" --threshold 0.75 --limit 3 --json
+   $FLOWCTL skill match "<english keywords>" --threshold 0.70 --limit 3 --json
    ```
 3. If matches found (non-empty JSON array): save them for Step 5 (task spec writing). Each matched skill will be referenced in the task's Approach section.
 4. If empty result, error, or embedder unavailable: skip silently. Skill routing is advisory, never blocking.