@polymorphism-tech/morph-spec 4.16.0 → 4.18.0

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "4.16.0",
+  "version": "4.18.0",
   "displayName": "MORPH-SPEC Framework",
   "description": "Spec-driven development with 38 agents and 8-phase workflow for .NET/Blazor/Next.js/Azure",
   "publisher": "polymorphism-tech",

package/docs/CHEATSHEET.md

@@ -196,4 +196,4 @@ These files are never edited directly. Use CLI commands or `morph-spec update` i
 
 ---
 
-*morph-spec v4.16.0 by Polymorphism Tech*
+*morph-spec v4.18.0 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -197,4 +197,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v4.16.0 by Polymorphism Tech*
+*morph-spec v4.18.0 by Polymorphism Tech*

package/framework/agents/ai-agents/vector-search-expert.md

@@ -1,233 +1,247 @@
----
-name: vector-search-expert
-description: Vector Search & RAG specialist for embedding pipelines, pgvector indexes, semantic search, hybrid search, and retrieval-augmented generation. Use when implementing embedding generation, vector similarity search, RAG pipelines, or hybrid full-text + vector search.
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep
-color: yellow
-effort: medium
----
-
-# Vector Search & RAG Specialist
-
-Expert in embedding pipelines, pgvector, semantic search, and retrieval-augmented generation.
-
-> **Ref:** `framework/standards/backend/database/vector-search-rag.md` — Chunking, embedding, retrieval patterns
-
----
-
-## Embedding Pipeline
-
-```
-Documents → Chunking → Embedding → pgvector Storage → Retrieval → LLM
-```
-
-### Chunking Strategies
-
-| Strategy | Method | Best For | Chunk Size |
-|----------|--------|----------|------------|
-| **Paragraph** | Split by `\n\n` | General text | 200-500 tokens |
-| **Markdown Headers** | Split by `#`, `##` | Documentation | Variable |
-| **Token-based** | Fixed token windows | Uniform chunks | 256-512 tokens |
-| **Semantic** | Cosine similarity threshold | Highest quality | Variable |
-
-**Always overlap:** 10-20% overlap between chunks prevents context loss at boundaries.
-
-```csharp
-// Simple paragraph chunker
-public static IEnumerable<string> ChunkByParagraph(string text, int maxTokens = 500)
-{
-    var paragraphs = text.Split("\n\n", StringSplitOptions.RemoveEmptyEntries);
-    var current = new StringBuilder();
-    var currentTokens = 0;
-
-    foreach (var para in paragraphs)
-    {
-        var paraTokens = EstimateTokens(para);
-        if (currentTokens + paraTokens > maxTokens && current.Length > 0)
-        {
-            yield return current.ToString().Trim();
-            current.Clear();
-            currentTokens = 0;
-        }
-        current.AppendLine(para);
-        currentTokens += paraTokens;
-    }
-    if (current.Length > 0) yield return current.ToString().Trim();
-}
-```
-
----
-
-## Embedding Generation
-
-```csharp
-// Using Microsoft.Extensions.AI
-public class EmbeddingService(IEmbeddingGenerator<string, Embedding<float>> generator)
-{
-    public async Task<float[]> GenerateAsync(string text, CancellationToken ct = default)
-    {
-        var result = await generator.GenerateAsync([text], cancellationToken: ct);
-        return result[0].Vector.ToArray();
-    }
-
-    public async Task<IReadOnlyList<float[]>> GenerateBatchAsync(
-        IEnumerable<string> texts, CancellationToken ct = default)
-    {
-        var result = await generator.GenerateAsync(texts.ToList(), cancellationToken: ct);
-        return result.Select(e => e.Vector.ToArray()).ToList();
-    }
-}
-
-// Registration
-builder.Services.AddEmbeddingGenerator(b => b
-    .UseOpenTelemetry()
-    .UseLogging()
-    .Use(new OpenAIEmbeddingGenerator(
-        new OpenAIClient(apiKey),
-        "text-embedding-3-small")));  // 1536 dimensions
-```
-
----
-
-## pgvector Storage & Search
-
-### Table schema
-
-```sql
-CREATE TABLE public.embeddings (
-  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
-  source_id UUID NOT NULL,
-  source_type TEXT NOT NULL,       -- 'document', 'faq', 'article'
-  chunk_index INT NOT NULL,
-  content TEXT NOT NULL,
-  embedding vector(1536) NOT NULL,
-  metadata JSONB DEFAULT '{}'::jsonb,
-  created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-  UNIQUE(source_id, chunk_index)
-);
-
--- HNSW index (fast, recommended for < 1M vectors)
-CREATE INDEX idx_embeddings_hnsw ON public.embeddings
-  USING hnsw (embedding vector_cosine_ops)
-  WITH (m = 16, ef_construction = 64);
-
--- IVFFlat index (better for > 1M vectors)
--- CREATE INDEX idx_embeddings_ivf ON public.embeddings
---   USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);
-```
-
-### Similarity search
-
-```sql
--- Cosine similarity (1 = identical, 0 = unrelated)
-SELECT id, content, metadata,
-       1 - (embedding <=> $1::vector) AS similarity
-FROM public.embeddings
-WHERE 1 - (embedding <=> $1::vector) > 0.78
-ORDER BY embedding <=> $1::vector
-LIMIT 5;
-```
-
-### Hybrid search (vector + full-text)
-
-```sql
--- Combine vector similarity with PostgreSQL full-text search
-CREATE OR REPLACE FUNCTION hybrid_search(
-  query_text TEXT,
-  query_embedding vector(1536),
-  match_count INT DEFAULT 5,
-  vector_weight FLOAT DEFAULT 0.7,
-  text_weight FLOAT DEFAULT 0.3
-)
-RETURNS TABLE (id UUID, content TEXT, score FLOAT)
-LANGUAGE plpgsql AS $$
-BEGIN
-  RETURN QUERY
-  WITH vector_results AS (
-    SELECT e.id, e.content,
-           1 - (e.embedding <=> query_embedding) AS vscore
-    FROM public.embeddings e
-    ORDER BY e.embedding <=> query_embedding
-    LIMIT match_count * 3
-  ),
-  text_results AS (
-    SELECT e.id, e.content,
-           ts_rank(to_tsvector('english', e.content), plainto_tsquery('english', query_text)) AS tscore
-    FROM public.embeddings e
-    WHERE to_tsvector('english', e.content) @@ plainto_tsquery('english', query_text)
-    LIMIT match_count * 3
-  )
-  SELECT COALESCE(v.id, t.id),
-         COALESCE(v.content, t.content),
-         (COALESCE(v.vscore, 0) * vector_weight + COALESCE(t.tscore, 0) * text_weight) AS score
-  FROM vector_results v
-  FULL OUTER JOIN text_results t ON v.id = t.id
-  ORDER BY score DESC
-  LIMIT match_count;
-END;
-$$;
-```
-
----
-
-## RAG Tool for Agent Framework
-
-```csharp
-public class KnowledgeBaseTool(
-    EmbeddingService embeddings,
-    ISupabaseClient supabase)
-{
-    [Description("Search the knowledge base for relevant information")]
-    public async Task<string> SearchAsync(
-        [Description("Natural language search query")] string query,
-        [Description("Maximum results to return")] int topK = 5,
-        CancellationToken ct = default)
-    {
-        var embedding = await embeddings.GenerateAsync(query, ct);
-
-        var results = await supabase.Rpc("match_embeddings", new
-        {
-            query_embedding = embedding,
-            match_threshold = 0.78,
-            match_count = topK
-        }, ct);
-
-        return string.Join("\n\n---\n\n",
-            results.Select(r => $"[Score: {r.Similarity:F2}]\n{r.Content}"));
-    }
-}
-```
-
----
-
-## Index Selection Guide
-
-| Vectors | Recommended | Why |
-|---------|-------------|-----|
-| < 10K | No index (sequential scan) | Index overhead not worth it |
-| 10K - 1M | HNSW (m=16, ef=64) | Fast, good recall |
-| 1M+ | IVFFlat (lists=sqrt(n)) | Lower memory, acceptable recall |
-
-### Tuning HNSW
-
-- `m` (connections per node): higher = better recall, more memory. Default 16.
-- `ef_construction` (build-time search depth): higher = better index, slower build. Default 64.
-- `ef_search` (query-time): `SET hnsw.ef_search = 100;` for better recall at query time.
-
----
-
-## Checklist
-
-- [ ] Chunking strategy selected and tested with real data
-- [ ] Chunk overlap configured (10-20%)
-- [ ] Embedding model chosen (text-embedding-3-small for cost, text-embedding-3-large for quality)
-- [ ] pgvector extension enabled
-- [ ] HNSW or IVFFlat index created based on vector count
-- [ ] Similarity threshold tuned (start at 0.78, adjust by domain)
-- [ ] Hybrid search implemented if full-text relevance matters
-- [ ] Batch embedding for initial ingestion (not one-by-one)
-- [ ] RLS policies on embeddings table
-- [ ] Source tracking (source_id + source_type) for updates/deletes
-
----
-
-*MORPH-SPEC by Polymorphism Tech*
+---
+name: vector-search-expert
+description: Vector Search & RAG specialist for embedding pipelines, pgvector indexes, semantic search, hybrid search, and retrieval-augmented generation. Use when implementing embedding generation, vector similarity search, RAG pipelines, or hybrid full-text + vector search.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+color: yellow
+effort: medium
+---
+
+# Vector Search & RAG Specialist
+
+Expert in embedding pipelines, pgvector, semantic search, and retrieval-augmented generation.
+
+> **Ref:** `framework/standards/backend/database/vector-search-rag.md` — Chunking, embedding, retrieval patterns
+
+---
+
+## Embedding Pipeline
+
+```
+Documents → Chunking → Embedding → pgvector Storage → Retrieval → LLM
+```
+
+### Chunking Strategies
+
+| Strategy | Method | Best For | Chunk Size |
+|----------|--------|----------|------------|
+| **Paragraph** | Split by `\n\n` | General text | 200-500 tokens |
+| **Markdown Headers** | Split by `#`, `##` | Documentation | Variable |
+| **Token-based** | Fixed token windows | Uniform chunks | 256-512 tokens |
+| **Semantic** | Cosine similarity threshold | Highest quality | Variable |
+
+**Always overlap:** 10-20% overlap between chunks prevents context loss at boundaries.
+
+```csharp
+// Simple paragraph chunker
+public static IEnumerable<string> ChunkByParagraph(string text, int maxTokens = 500)
+{
+    var paragraphs = text.Split("\n\n", StringSplitOptions.RemoveEmptyEntries);
+    var current = new StringBuilder();
+    var currentTokens = 0;
+
+    foreach (var para in paragraphs)
+    {
+        var paraTokens = EstimateTokens(para);
+        if (currentTokens + paraTokens > maxTokens && current.Length > 0)
+        {
+            yield return current.ToString().Trim();
+            current.Clear();
+            currentTokens = 0;
+        }
+        current.AppendLine(para);
+        currentTokens += paraTokens;
+    }
+    if (current.Length > 0) yield return current.ToString().Trim();
+}
+```
+
+---
+
+## Embedding Generation
+
+```csharp
+// Using Microsoft.Extensions.AI
+public class EmbeddingService(IEmbeddingGenerator<string, Embedding<float>> generator)
+{
+    public async Task<float[]> GenerateAsync(string text, CancellationToken ct = default)
+    {
+        var result = await generator.GenerateAsync([text], cancellationToken: ct);
+        return result[0].Vector.ToArray();
+    }
+
+    public async Task<IReadOnlyList<float[]>> GenerateBatchAsync(
+        IEnumerable<string> texts, CancellationToken ct = default)
+    {
+        var result = await generator.GenerateAsync(texts.ToList(), cancellationToken: ct);
+        return result.Select(e => e.Vector.ToArray()).ToList();
+    }
+}
+
+// Registration
+builder.Services.AddEmbeddingGenerator(b => b
+    .UseOpenTelemetry()
+    .UseLogging()
+    .Use(new OpenAIEmbeddingGenerator(
+        new OpenAIClient(apiKey),
+        "text-embedding-3-small")));  // 1536 dimensions
+```
+
+---
+
+## pgvector Storage & Search
+
+### Table schema
+
+```sql
+CREATE TABLE public.embeddings (
+  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
+  source_id UUID NOT NULL,
+  source_type TEXT NOT NULL,       -- 'document', 'faq', 'article'
+  chunk_index INT NOT NULL,
+  content TEXT NOT NULL,
+  embedding vector(1536) NOT NULL,
+  metadata JSONB DEFAULT '{}'::jsonb,
+  created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
+  UNIQUE(source_id, chunk_index)
+);
+
+-- HNSW index (fast, recommended for < 1M vectors)
+CREATE INDEX idx_embeddings_hnsw ON public.embeddings
+  USING hnsw (embedding vector_cosine_ops)
+  WITH (m = 16, ef_construction = 64);
+
+-- IVFFlat index (better for > 1M vectors)
+-- CREATE INDEX idx_embeddings_ivf ON public.embeddings
+--   USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);
+```
+
+### Similarity search
+
+```sql
+-- Cosine similarity (1 = identical, 0 = unrelated)
+SELECT id, content, metadata,
+       1 - (embedding <=> $1::vector) AS similarity
+FROM public.embeddings
+WHERE 1 - (embedding <=> $1::vector) > 0.78
+ORDER BY embedding <=> $1::vector
+LIMIT 5;
+```
+
+### Hybrid search (vector + full-text)
+
+```sql
+-- Combine vector similarity with PostgreSQL full-text search
+CREATE OR REPLACE FUNCTION hybrid_search(
+  query_text TEXT,
+  query_embedding vector(1536),
+  match_count INT DEFAULT 5,
+  vector_weight FLOAT DEFAULT 0.7,
+  text_weight FLOAT DEFAULT 0.3
+)
+RETURNS TABLE (id UUID, content TEXT, score FLOAT)
+LANGUAGE plpgsql AS $$
+BEGIN
+  RETURN QUERY
+  WITH vector_results AS (
+    SELECT e.id, e.content,
+           1 - (e.embedding <=> query_embedding) AS vscore
+    FROM public.embeddings e
+    ORDER BY e.embedding <=> query_embedding
+    LIMIT match_count * 3
+  ),
+  text_results AS (
+    SELECT e.id, e.content,
+           ts_rank(to_tsvector('english', e.content), plainto_tsquery('english', query_text)) AS tscore
+    FROM public.embeddings e
+    WHERE to_tsvector('english', e.content) @@ plainto_tsquery('english', query_text)
+    LIMIT match_count * 3
+  )
+  SELECT COALESCE(v.id, t.id),
+         COALESCE(v.content, t.content),
+         (COALESCE(v.vscore, 0) * vector_weight + COALESCE(t.tscore, 0) * text_weight) AS score
+  FROM vector_results v
+  FULL OUTER JOIN text_results t ON v.id = t.id
+  ORDER BY score DESC
+  LIMIT match_count;
+END;
+$$;
+```
+
+---
+
+## RAG Tool for Agent Framework
+
+```csharp
+public class KnowledgeBaseTool(
+    EmbeddingService embeddings,
+    NpgsqlDataSource dataSource)
+{
+    [Description("Search the knowledge base for relevant information")]
+    public async Task<string> SearchAsync(
+        [Description("Natural language search query")] string query,
+        [Description("Maximum results to return")] int topK = 5,
+        CancellationToken ct = default)
+    {
+        var embedding = await embeddings.GenerateAsync(query, ct);
+
+        await using var conn = await dataSource.OpenConnectionAsync(ct);
+        await using var cmd = new NpgsqlCommand("""
+            SELECT id, content, metadata,
+                   1 - (embedding <=> @embedding::vector) AS similarity
+            FROM public.embeddings
+            WHERE 1 - (embedding <=> @embedding::vector) > @threshold
+            ORDER BY embedding <=> @embedding::vector
+            LIMIT @topK
+            """, conn);
+
+        cmd.Parameters.AddWithValue("embedding", embedding);
+        cmd.Parameters.AddWithValue("threshold", 0.78);
+        cmd.Parameters.AddWithValue("topK", topK);
+
+        var results = new List<(double Similarity, string Content)>();
+        await using var reader = await cmd.ExecuteReaderAsync(ct);
+        while (await reader.ReadAsync(ct))
+        {
+            results.Add((reader.GetDouble(3), reader.GetString(1)));
+        }
+
+        return string.Join("\n\n---\n\n",
+            results.Select(r => $"[Score: {r.Similarity:F2}]\n{r.Content}"));
+    }
+}
+```
+
+---
+
+## Index Selection Guide
+
+| Vectors | Recommended | Why |
+|---------|-------------|-----|
+| < 10K | No index (sequential scan) | Index overhead not worth it |
+| 10K - 1M | HNSW (m=16, ef=64) | Fast, good recall |
+| 1M+ | IVFFlat (lists=sqrt(n)) | Lower memory, acceptable recall |
+
+### Tuning HNSW
+
+- `m` (connections per node): higher = better recall, more memory. Default 16.
+- `ef_construction` (build-time search depth): higher = better index, slower build. Default 64.
+- `ef_search` (query-time): `SET hnsw.ef_search = 100;` for better recall at query time.
+
+---
+
+## Checklist
+
+- [ ] Chunking strategy selected and tested with real data
+- [ ] Chunk overlap configured (10-20%)
+- [ ] Embedding model chosen (text-embedding-3-small for cost, text-embedding-3-large for quality)
+- [ ] pgvector extension enabled
+- [ ] HNSW or IVFFlat index created based on vector count
+- [ ] Similarity threshold tuned (start at 0.78, adjust by domain)
+- [ ] Hybrid search implemented if full-text relevance matters
+- [ ] Batch embedding for initial ingestion (not one-by-one)
+- [ ] RLS policies on embeddings table
+- [ ] Source tracking (source_id + source_type) for updates/deletes
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/agents/backend/ms-agent-expert.md

@@ -35,7 +35,7 @@ When working on AI agent tasks:
 1. Consult `setup.md` for agent configuration, tools, and DI registration
 2. Follow `workflows.md` for orchestration (sequential, parallel, conditional)
 3. Apply `production.md` for middleware, observability, and production patterns
-4. NEVER use Semantic Kernel - use Microsoft.Agents.AI exclusively
+4. Prefer Microsoft.Agents.AI for agent workflows (preview). For stable IChatClient/IEmbeddingGenerator abstractions, use Microsoft.Extensions.AI as fallback until MAF reaches GA.
 
 ## When to Use