docs: update README and copilot instructions for clarity

Updated README.md to include conversation persistence details
and clarified the role of IThreadPersistenceService. Enhanced
copilot instructions with body formatting guidelines and
file listing best practices.

Modified files (2):
- README.md: Added conversation persistence section
- .github/copilot-instructions.md: Updated body format and style

Author: cristofima

.github/copilot-instructions.md

@@ -19,6 +19,41 @@ WebApp/          - Controllers, Middleware, DI setup, Agent factory (TaskAgentSe
 
 ## AI Agent Pattern
 
+### Microsoft Agentic AI Framework
+
+This project uses `Microsoft.Agents.AI.OpenAI` (preview) - Microsoft's framework for building autonomous AI agents with function calling.
+
+**Key APIs**:
+
+```csharp
+// 1. Get chat client from Azure OpenAI
+ChatClient chatClient = azureClient.GetChatClient(deploymentName);
+
+// 2. Create agent with tools and instructions
+AIAgent agent = chatClient.CreateAIAgent(
+    instructions: "System prompt with behavioral rules...",
+    tools: [createTaskTool, listTasksTool, ...]
+);
+
+// 3. Create conversation thread
+AgentThread thread = await agent.CreateThreadAsync();
+
+// 4. Add user message
+await thread.AddUserMessageAsync("Create a high priority task");
+
+// 5. Invoke agent (streams responses)
+await foreach (StreamingResponse response in thread.InvokeAsync(agent)) {
+    if (response is StreamingTextResponse textResponse) {
+        // Process streamed text
+    }
+}
+
+// 6. Serialize thread for persistence
+string serialized = thread.Serialize();
+```
+
+**Thread lifecycle**: Each HTTP request loads thread, processes message, saves updated thread.
+
 ### Factory Method (`TaskAgentService.CreateAgent`)
 
 ```csharp
@@ -29,7 +64,7 @@ var agent = chatClient.CreateAIAgent(instructions: "...", tools: [...]);
 **Key Points**:
 
 - Agent is **scoped per request** (registered in `DependencyInjection.AddPresentation()`) - never singleton
-- Each conversation gets a **thread ID** for context persistence via `_threads` dictionary
+- Each conversation gets a **thread ID** for context persistence via thread serialization
 - Instructions embed behavioral rules: immediate task creation, Markdown tables with emojis, contextual suggestions
 - Tools created with `AIFunctionFactory.Create(taskFunctions.MethodName)`
 - Agent factory is a static method that takes `AzureOpenAIClient`, `modelDeployment`, and `ITaskRepository`
@@ -272,10 +307,90 @@ To add a new safety layer:
 | `Infrastructure/Data/TaskDbContext.cs`            | EF Core DbContext, entity configurations              |
 | `Infrastructure/Repositories/TaskRepository.cs`   | Repository pattern implementation                     |
 
+## Package Management - Central Version Control
+
+**CRITICAL**: This project uses **Central Package Management** (CPM) via `Directory.Packages.props`.
+
+**How it works**:
+
+- `Directory.Build.props` → Common project settings (target framework, nullable, code analysis)
+- `Directory.Packages.props` → Centralized NuGet package versions
+- Individual `.csproj` files → Package references WITHOUT version numbers
+
+**Adding a new package**:
+
+```powershell
+# 1. Add to Directory.Packages.props
+<PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />
+
+# 2. Reference in .csproj (NO version attribute)
+<PackageReference Include="Newtonsoft.Json" />
+```
+
+**Key packages**:
+
+- `Microsoft.Agents.AI.OpenAI` (1.0.0-preview) - Agentic AI Framework
+- `Azure.AI.OpenAI` (2.1.0) - Azure OpenAI SDK
+- `Azure.AI.ContentSafety` (1.0.0) - Content Safety SDK
+- `Microsoft.EntityFrameworkCore.SqlServer` (9.0.10)
+- `SonarAnalyzer.CSharp` (9.32.0) - Code quality analysis
+
+**Why CPM?**: Ensures version consistency across all projects, prevents dependency conflicts, simplifies upgrades.
+
+## Thread Persistence & Conversation State
+
+**Architecture**: Conversations are persisted using `IThreadPersistenceService` to maintain context across HTTP requests.
+
+**Flow**:
+
+1. User sends message with optional `threadId`
+2. If `threadId` exists → deserialize thread state: `AgentThread.Deserialize(serializedState)`
+3. Agent processes message with full conversation history
+4. After response → serialize thread state: `thread.Serialize()`
+5. Save to persistence layer: `await _threadPersistence.SaveThreadAsync(threadId, serializedState)`
+
+**Implementations**:
+
+- **Development**: `InMemoryThreadPersistenceService` (ConcurrentDictionary, singleton)
+- **Production**: Implement with Redis/SQL Server (scoped/transient)
+
+**Critical**: Thread state contains entire conversation history - must be serialized/deserialized for each request.
+
+**Code example** (see `TaskAgentService.SendMessageAsync`):
+
+```csharp
+// Load existing thread or create new
+string? serializedThread = await _threadPersistence.GetThreadAsync(threadId);
+AgentThread thread = string.IsNullOrEmpty(serializedThread)
+    ? await _agent.CreateThreadAsync()
+    : AgentThread.Deserialize(serializedThread);
+
+// Process message
+await thread.AddUserMessageAsync(message);
+await foreach (var response in thread.InvokeAsync(_agent)) { }
+
+// Save updated thread
+await _threadPersistence.SaveThreadAsync(threadId, thread.Serialize());
+```
+
+**Production considerations**:
+
+- Thread state grows with conversation length
+- Consider TTL/cleanup strategies for old threads
+- Scoped lifetime for multi-server scenarios
+
 ## Testing Guidance
 
 **Content Safety**: See `CONTENT_SAFETY.md` for 75+ test cases including prompt injections, harmful content, edge cases, and troubleshooting.
 
-**AI Agent**: Test via web UI at `http://localhost:5000` or POST to `/api/chat` endpoint with `{"message": "your message"}`
+**AI Agent**: Test via web UI at `http://localhost:5000` or POST to `/api/chat` endpoint with `{"message": "your message", "threadId": "optional-thread-id"}`
 
 **Database**: Auto-created on first run. To reset: `dotnet ef database drop --project TaskAgent.Infrastructure --startup-project TaskAgent.WebApp`
+
+**Key Test Scenarios**:
+
+1. Task creation with validation (title length, priority values)
+2. Business rule enforcement (can't reopen completed tasks)
+3. Thread persistence across multiple requests (same threadId)
+4. Content safety blocking (prompt injection, harmful content)
+5. Parallel safety checks performance (~200-400ms)

.github/git-commit-messages-instructions.md

@@ -94,9 +94,24 @@ These instructions guide GitHub Copilot in generating Git commit messages that a
     - "Simple, self-explanatory single-file changes"
     - "The title completely describes the change"
     - "Trivial fixes or updates (e.g., 'docs: fix typo in README')"
-  - "Include a longer description of the changes, if necessary. Use complete sentences."
+  - "**BODY FORMAT AND STYLE:**"
+    - "Write in **past tense** (describe what was done, not what to do)"
+    - "Examples: 'Added feature X', 'Implemented Y', 'Fixed Z', 'Updated configuration'"
+    - "Use complete sentences with proper capitalization and punctuation"
+    - "Wrap lines at 72 characters for readability"
+    - "Separate paragraphs with blank lines for better structure"
+  - "**LISTING MODIFIED FILES:**"
+    - "For **2-10 files**: List files with brief description of changes"
+    - "Format: 'Modified files (X):' or 'Affected files (X):' followed by bulleted list"
+    - "Use `-` (hyphen) for bullet points, not `•`"
+    - "Example format: `- FileName.cs: Brief description of change`"
+    - "File descriptions should use past tense (e.g., 'Added method', 'Updated logic')"
+    - "For **>10 files**: Group by layer/component instead of listing all files"
+    - "Example: 'This change spans multiple layers (15 files modified):'"
+    - "Then list high-level changes by component/layer, not individual files"
+    - "For **1 file**: Generally omit file listing (it's in the commit diff)"
   - "Explain the motivation for the change and how it differs from previous behavior."
-  - "Wrap lines at 72 characters."
+  - "For significant changes, include performance metrics, testing notes, or migration guidance."
 - **Footer (Optional):**
   - "Use the footer to reference issue trackers, breaking changes, or other metadata."
   - "**Breaking Changes:** Start with `BREAKING CHANGE: ` (or `BREAKING-CHANGE:`) followed by a description. Alternatively, append `!` after type/scope (e.g., `feat!:` or `feat(api)!:`)."
@@ -324,52 +339,84 @@ Fixes #156
 ```
 feat(WebApp.Middleware): add prompt injection detection
 
-Implement Azure Content Safety prompt shield to detect
+Implemented Azure Content Safety prompt shield to detect
 and block jailbreak attempts before reaching the AI agent.
-Returns 400 status with descriptive error message.
+Added 400 status response with descriptive error message.
 
-Modified files:
-- ContentSafetyMiddleware.cs: Add prompt shield check
-- ContentSafetyService.cs: Implement shield API call
-- IContentSafetyService.cs: Add interface method
+Modified files (3):
+- ContentSafetyMiddleware.cs: Added prompt shield check
+- ContentSafetyService.cs: Implemented shield API call
+- IContentSafetyService.cs: Added interface method
 
 Closes #42
 ```
 
 ```
 refactor(Domain): extract task validation to factory method
 
-Move validation logic from constructor to TaskItem.Create()
+Moved validation logic from constructor to TaskItem.Create()
 factory method following domain-driven design principles.
-Ensures all task creation goes through proper validation.
+This ensures all task creation goes through proper validation.
 
-This change affects TaskItem entity and all places where
-tasks are created, but maintains the same validation behavior.
+Affected files (2):
+- TaskItem.cs: Extracted Create() factory method
+- TaskRepository.cs: Updated to use factory method
+
+This change maintains the same validation behavior while
+improving code organization and testability.
 ```
 
 ```
 perf(Infrastructure): add database indexes for task queries
 
-Add composite index on Status, Priority, and CreatedAt columns
-to optimize filtering queries. Reduces query time by 75% for
-GetAllTasksAsync with multiple filters.
+Added composite index on Status, Priority, and CreatedAt
+columns to optimize filtering queries. Performance tests
+showed 75% reduction in query time for GetAllTasksAsync
+with multiple filters applied.
+
+Modified files (2):
+- TaskDbContext.cs: Added index configuration
+- 20251018_AddTaskIndexes.cs: New EF migration
 
-Modified:
-- TaskDbContext.cs: Add index configuration
-- New migration: 20251018_AddTaskIndexes.cs
+Refs: #89
+```
+
+```
+feat(Application): implement task search and filtering
+
+Added comprehensive search and filtering capabilities for
+tasks including full-text search, status filtering, priority
+filtering, and date range queries.
+
+This change spans multiple layers (12 files modified):
+- Application layer: New DTOs, interfaces, and service methods
+- Infrastructure layer: Repository implementations and queries
+- WebApp layer: New API endpoints and request validators
+
+Key changes:
+- Created SearchTasksDto with filter parameters
+- Implemented full-text search on Title and Description
+- Added composite indexes for performance
+- Created GET /api/tasks/search endpoint
+- Added pagination support (page size, page number)
+
+Performance: Search queries execute in <100ms for 10k records.
+
+Closes #45, #67, #89
 ```
 
 ```
 docs: update architecture and setup documentation
 
-Update README.md with new setup steps, add CONTENT_SAFETY.md
-with comprehensive testing guide, and update copilot
-instructions with latest conventions.
+Updated project documentation to reflect current architecture
+patterns and setup requirements. Added comprehensive content
+safety testing guide with 75+ test cases.
 
-Modified files:
-- README.md: Add Azure OpenAI setup section
-- CONTENT_SAFETY.md: New file with 75+ test cases
-- .github/copilot-instructions.md: Update DI patterns
+Modified files (4):
+- README.md: Added Azure OpenAI setup section
+- CONTENT_SAFETY.md: New file with testing guide
+- .github/copilot-instructions.md: Updated DI patterns
+- .github/git-commit-messages-instructions.md: Added examples
 ```
 
 **Cross-Layer Examples:**
@@ -419,6 +466,19 @@ Modified files:
   - "Single file, simple change"
   - "Title is completely self-explanatory"
   - "Trivial updates (e.g., 'docs: fix typo')"
+- "**BODY WRITING STYLE - CRITICAL:**"
+  - "**Header (title)**: Use IMPERATIVE PRESENT tense (e.g., 'add feature', 'fix bug', 'update config')"
+  - "**Body**: Use PAST TENSE (e.g., 'Added feature', 'Fixed bug', 'Updated config')"
+  - "Body describes what WAS done, header describes what the commit DOES"
+  - "Use `-` (hyphen) for bullet points in body, NEVER `•` or other symbols"
+  - "File listings format:"
+    - "2-10 files: List each file with hyphen. Example: `- FileName.cs: Added method`"
+    - ">10 files: Group by layer/component, don't list all files individually"
+  - "Example for many files:"
+    - "❌ DON'T: List all 15 files individually (too verbose)"
+    - "✅ DO: 'This change spans multiple layers (15 files modified):'"
+    - "Then describe by component: 'Application layer: New DTOs and services'"
+  - "Wrap lines at 72 characters for readability"
 - "**BREAKING CHANGES - Critical Decision Guide:**"
   - "Use `BREAKING CHANGE:` footer or `!` suffix when consumers MUST modify their code"
   - "**Ask yourself**: Would existing code that uses this API/endpoint/interface still work?"
@@ -511,11 +571,37 @@ Modified files:
 **Multi-File Changes - Body Guidelines:**
 
 - **Include body if:**
-  - 2+ files modified (list affected files/components)
+  - 2+ files modified (describe changes and list files if ≤10)
   - Change spans multiple layers or scopes
   - Explanation needed for WHY (not just WHAT)
   - Breaking changes or migrations involved
 - **Body can be omitted if:**
   - Single file, straightforward change
   - Title like "docs: fix typo in README" is self-explanatory
   - Trivial formatting or style changes
+
+**File Listing Best Practices:**
+
+- **2-10 files modified:**
+  - Include section: "Modified files (X):" or "Affected files (X):"
+  - List each file with hyphen and brief description
+  - Example: `- TaskService.cs: Added search method`
+  - Use past tense for descriptions
+- **>10 files modified:**
+  - DON'T list all files individually (commit becomes too long)
+  - State total count: "This change spans multiple layers (15 files modified):"
+  - Group changes by layer/component/category
+  - Example: "Application layer: New DTOs, interfaces, and service methods"
+  - Example: "Infrastructure layer: Repository implementations and queries"
+  - Focus on WHAT changed in each component, not listing every file
+- **1 file modified:**
+  - Generally omit file listing (obvious from commit diff)
+  - Use body to explain WHY and HOW, not WHAT file
+
+**Body Writing Style:**
+
+- Header (title): Imperative present ("add feature", "fix bug")
+- Body: Past tense ("Added feature", "Implemented logic", "Fixed validation")
+- Bullet points: Use `-` (hyphen), not `•` or other symbols
+- Line length: Wrap at 72 characters
+- Paragraphs: Separate with blank lines for readability

README.md

@@ -81,10 +81,17 @@ TaskAgent.WebApp (UI, Controllers, AI Agent)
 **Key Components**:
 
 - **Domain**: `TaskItem` entity with business rules, Status/Priority enums
-- **Application**: DTOs (using record types), `ITaskRepository`, 6 AI function tools
-- **Infrastructure**: `TaskDbContext`, `TaskRepository`, `ContentSafetyService` with HttpClientFactory
+- **Application**: DTOs (using record types), `ITaskRepository`, `IThreadPersistenceService`, 6 AI function tools
+- **Infrastructure**: `TaskDbContext`, `TaskRepository`, `ContentSafetyService` with HttpClientFactory, `InMemoryThreadPersistenceService`
 - **Presentation**: MVC controllers, Razor views, `TaskAgentService`, configuration validation extensions
 
+**Conversation Persistence**:
+
+- Thread state serialized/deserialized across requests using `AgentThread.Serialize()`
+- `IThreadPersistenceService` abstraction for storage flexibility
+- In-memory implementation for single-server deployments
+- Production: Use Redis/SQL for multi-server scenarios
+
 ---
 
 ## 🛠️ Tech Stack
@@ -208,8 +215,9 @@ Agent provides 1-2 smart suggestions after each operation:
 TaskAgentWeb/
 ├── TaskAgent.Domain/          # Entities, Enums
 ├── TaskAgent.Application/     # DTOs (record types), Interfaces, Functions
+│   └── Interfaces/           # ITaskRepository, IThreadPersistenceService
 ├── TaskAgent.Infrastructure/  # DbContext, Repositories, Azure Services
-│   ├── Services/             # ContentSafetyService (HttpClientFactory)
+│   ├── Services/             # ContentSafetyService, InMemoryThreadPersistenceService
 │   ├── Models/               # ContentSafetyConfig, PromptShieldResponse
 │   └── DependencyInjection.cs # Named HttpClient registration
 └── TaskAgent.WebApp/          # Controllers, Views, Services