docs: v4.0 documentation update and cleanup (closes #229) (#230)

v4.0 docs update: CHANGELOG, README, FEATURES, API-REFERENCE, 11 new SOPs, MCP docs, version bumps to 4.0.0, docs cleanup. Closes #229.
2026-08-28 02:44:59 +00:00 · 2026-03-21 12:20:16 -05:00 · 2026-03-21 12:20:16 -05:00 · 70c8c06e56
commit 70c8c06e56
parent e50119ab1e
28 changed files with 3113 additions and 13 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -11,11 +11,90 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 - Mass archive failure caused by missing `/api/tasks/bulk-archive-by-ids` endpoint

+## [4.0.0] - 2026-03-21
+
+### ✨ Highlights
+
+**Veritas Kanban 4.0 is the agent governance release.** This release adds a complete Agent Governance Layer — configurable policies, behavioral drift detection, decision audit trails, output evaluation, and user feedback analytics — alongside a fully customizable dashboard widget grid, a Prompt Template Registry with version control, and a real-time Global System Health Status Bar.
+
+All shadcn/ui components have been upgraded to v4 with Tailwind v4 integration. This release also adds MCP comment CRUD tools and project management tools, wires lifecycle hooks to the notification service, and ships seven new SOP guides plus updated API documentation.
+
 ### Added

+- **Agent Policy & Guard Engine (#178)** — Configurable tool/action policies with guard rules
+  - Define policies with `allow`/`deny`/`require-approval` guard rules per tool and action
+  - Policy evaluation engine with configurable precedence (deny-first or allow-first)
+  - REST API: `GET/POST /api/policies`, `GET/PUT/DELETE /api/policies/:id`, `POST /api/policies/:id/evaluate`
+  - Per-agent and per-project policy scoping
+  - Built-in audit log for every policy decision
+
+- **Decision Audit Trail with Assumption Tracking (#179)** — Log agent decisions with assumptions and outcomes
+  - Structured decision records: decision text, confidence score, supporting evidence, assumptions
+  - Outcome tracking: record what happened after a decision and whether assumptions held
+  - Full-text search and filtering by agent, task, confidence range
+  - REST API: `GET/POST /api/decisions`, `GET/PUT/DELETE /api/decisions/:id`, `POST /api/decisions/:id/outcome`
+
+- **Agent Output Evaluation & Scoring Framework (#180)** — Quality scoring for agent outputs
+  - Scoring profiles with weighted criteria: `RegexMatch`, `KeywordContains`, `NumericRange`, `CustomExpression`
+  - Composite scoring methods: `weightedAvg`, `minimum`, `geometricMean`
+  - Evaluation history with per-scorer breakdown and per-dimension explanations
+  - REST API: `GET/POST /api/scoring/profiles`, `GET/PUT/DELETE /api/scoring/profiles/:id`, `POST /api/scoring/evaluate`, `GET /api/scoring/history`
+
+- **Behavioral Drift Detection & Alerting (#181)** — Detect and alert on agent behavior changes
+  - Metric tracking with configurable baselines and alert thresholds
+  - Drift status lifecycle: `ok` → `warning` → `alert` → `resolved`
+  - Automatic timestamp of detection and resolution events
+  - REST API: `GET/POST /api/drift`, `GET/PUT/DELETE /api/drift/:id`, `POST /api/drift/:id/resolve`
+
+- **User Feedback Loop with Sentiment Analytics (#182)** — Collect and analyze user feedback on agent outputs
+  - Feedback collection with sentiment (`positive`/`neutral`/`negative`) and category tagging
+  - Aggregate analytics: sentiment breakdowns, trends over time, category distributions
+  - REST API: `GET/POST /api/feedback`, `GET/DELETE /api/feedback/:id`, `GET /api/feedback/analytics`
+
+- **Draggable & Resizable Dashboard Widget Grid (#183)** — Customizable dashboard layouts
+  - Drag-and-drop widget repositioning with smooth animations
+  - Resizable widgets with snap-to-grid behavior
+  - Layout persistence via `settings.json`
+  - Add/remove widgets from the widget library
+
+- **Prompt Template Registry with Version Control (#184)** — Manage and version prompt templates
+  - Template CRUD with variable extraction (e.g., `{{agent_name}}`, `{{task_context}}`)
+  - Full version history with changelog entries; rollback to any version
+  - Usage tracking: model, tokens, rendered output (optional)
+  - Preview rendering with sample variable injection
+  - REST API: `GET/POST /api/prompt-registry/templates`, `GET/PUT/DELETE /api/prompt-registry/templates/:id`, `GET /api/prompt-registry/templates/:id/versions`, `POST /api/prompt-registry/templates/:id/versions`, `GET /api/prompt-registry/templates/:id/versions/:versionId`, `POST /api/prompt-registry/templates/:id/preview`, `GET /api/prompt-registry/templates/:id/stats`, `POST /api/prompt-registry/templates/:id/usage`
+
+- **Global System Health Status Bar (#185)** — Real-time system health monitoring
+  - Five health levels: `stable` → `reviewing` → `drifting` → `elevated` → `alert`
+  - Three signal categories: `system` (storage/disk/memory), `agents` (online/offline counts), `operations` (success rate, recent runs)
+  - Persistent header bar with expand/collapse for detail panel
+  - REST API: `GET /api/v1/system/health`
+
+- **MCP comment CRUD tools (PR #206)** — Full comment lifecycle from MCP
+  - New MCP tools: `add_comment`, `list_comments`, `get_comment`, `update_comment`, `delete_comment`
+  - Works with both task-level and sprint-level comments
+
+- **MCP project management tools (PR #227)** — Full project lifecycle from MCP
+  - New MCP tools: `list_projects`, `get_project`, `create_project`, `update_project`, `delete_project`, `get_project_stats`, `reorder_projects`
+
+- **Lifecycle hooks wired to notification service (PR #201)** — Hook outcomes now trigger real-time notifications
+  - Hooks with `notify: true` push events through the notification service
+  - Integrates with @mention notification system for addressable hook alerts
+
 - Comprehensive MCP server documentation at `docs/mcp/README.md` — architecture, quickstart, full tool catalog with examples, security model, troubleshooting playbook, and FAQ
 - Condensed root README MCP section with link to dedicated docs

+### Changed
+
+- **Upgraded shadcn/ui components to v4 (#186, PR #219)** — All UI components updated for shadcn/ui v4 compatibility with Tailwind v4 integration; breaking prop changes resolved across the component tree
+
+### Fixed
+
+- **Squad chat panel scroll (PR #225, #224)** — Panel now properly scrolls to latest message; overflow clipping bug in nested flex containers resolved
+- **False cycle detection in dependency API (PR #208, #188)** — DFS algorithm no longer flags valid multi-path dependencies as cycles when two nodes share a common ancestor
+- **TypeScript build errors (PR #207, #177)** — Resolved type mismatches introduced by shadcn/ui v4 and Zod 4 type inference changes
+- **SystemHealthBar successRate percentage display (PR #212, #211)** — `successRate` is now correctly formatted as a percentage (0–100) instead of a decimal (0–1)
+
 ## [3.3.3] - 2026-03-01

 ### ✨ Highlights
@ -1269,7 +1348,9 @@ Veritas Kanban is an AI-native project management board built for developers and

 _Built by [Digital Meld](https://digitalmeld.io) — AI-driven enterprise automation._

-[unreleased]: https://github.com/BradGroux/veritas-kanban/compare/v1.4.1...HEAD
+[unreleased]: https://github.com/BradGroux/veritas-kanban/compare/v4.0.0...HEAD
+[4.0.0]: https://github.com/BradGroux/veritas-kanban/compare/v3.3.3...v4.0.0
+[3.3.3]: https://github.com/BradGroux/veritas-kanban/compare/v3.3.2...v3.3.3
 [1.4.1]: https://github.com/BradGroux/veritas-kanban/compare/v1.4.0...v1.4.1
 [1.4.0]: https://github.com/BradGroux/veritas-kanban/compare/v1.3.0...v1.4.0
 [1.3.0]: https://github.com/BradGroux/veritas-kanban/compare/v1.2.0...v1.3.0
--- a/README.md
+++ b/README.md
@ -10,7 +10,7 @@ Built for developers who want a visual Kanban board that works with autonomous c

 [![CI](https://github.com/BradGroux/veritas-kanban/actions/workflows/ci.yml/badge.svg)](https://github.com/BradGroux/veritas-kanban/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-3.3.3-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-4.0.0-blue.svg)](CHANGELOG.md)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)

@ -100,12 +100,24 @@ Open [http://localhost:3000](http://localhost:3000) — that's it. The board aut

 ## ✨ Feature Highlights

+### 🛡️ Agent Governance (New in v4.0)
+
+**Policy Engine** — Define what agents can and can't do. Configurable tool/action policies with `allow`, `deny`, and `require-approval` guard rules. Every policy decision is logged. **Decision Audit Trail** — Log agent decisions with confidence scores, supporting evidence, and stated assumptions. Record outcomes afterward to see whether assumptions held. **Behavioral Drift Detection** — Set metric baselines and thresholds; get alerted when an agent's behavior deviates. **User Feedback Loop** — Collect feedback on agent outputs with sentiment tagging and category analytics. **Output Evaluation** — Score agent outputs against weighted criteria profiles (regex, keyword, numeric range, custom expressions).
+
 ### 🤖 Agent Orchestration

 Spawn autonomous coding agents on tasks. Track them in real-time with the multi-agent dashboard — status indicators, expandable agent cards, model attribution. Squad Chat gives agents a shared communication channel with system lifecycle events (spawned, completed, failed). Assign multiple agents per task, set permission levels (Intern/Specialist/Lead), and let them coordinate.

 ![Agent orchestration](assets/demo-overview.gif)

+### 📊 Customizable Dashboard (New in v4.0)
+
+**Draggable & Resizable Widget Grid** — Rearrange and resize dashboard widgets via drag-and-drop. Layouts persist across sessions. Add widgets from the library or remove ones you don't need. **Global System Health Bar** — Persistent header status bar with five health levels (stable → alert) across three signal categories: system resources, agent availability, and operation success rate.
+
+### 📝 Prompt Template Registry (New in v4.0)
+
+Version-controlled prompt templates with variable extraction, full version history with rollback, usage tracking, and preview rendering with sample variable injection. Manage your prompt library the same way you manage code.
+
 ### ⚡ Workflow Engine

 Define multi-step agent pipelines as version-controlled YAML. Sequential steps, parallel fan-out/fan-in, loop iteration over collections, gate approvals with human-in-the-loop, and retry routing. Think GitHub Actions — but for AI agents. Live execution view with step-by-step progress. Monitoring dashboard with success rates, active runs, and per-workflow health metrics.
@ -126,7 +138,7 @@ Tasks are markdown files. Settings are JSON. Workflows are YAML. No database, no

 ### 🔌 Three Integration Surfaces

- **MCP Server** — 26 tools across 6 categories via Model Context Protocol
+- **MCP Server** — 33+ tools across 7 categories via Model Context Protocol (v4.0 adds project management and comment CRUD tools)
 - **CLI** — `vk begin <id>` / `vk done <id> "summary"` replaces 6 API calls with 2 commands
 - **REST API** — Full lifecycle management. If it can make HTTP calls, it can drive the board.

--- a/docs/API-REFERENCE.md
+++ b/docs/API-REFERENCE.md
@ -1765,6 +1765,686 @@ These endpoints follow the same auth/error patterns documented above:
 | `/api/integrations`              | External integrations                         |
 | `/api/settings/transition-hooks` | Status transition hooks                       |

+| `/api/feedback`                  | User feedback & sentiment analytics           |
+| `/api/decisions`                 | Decision audit trail                          |
+| `/api/drift`                     | Behavioral drift detection                    |
+| `/api/policies`                  | Agent policy & guard engine                   |
+| `/api/scoring/profiles`          | Output evaluation profiles                    |
+| `/api/scoring/evaluate`          | Run an output evaluation                      |
+| `/api/scoring/history`           | Evaluation history                            |
+| `/api/prompt-registry`           | Prompt template registry                      |
+| `/api/v1/system/health`          | Global system health                          |
+
+---
+
+## v4.0 API Reference
+
+### User Feedback (`/api/feedback`)
+
+Collect feedback on agent outputs and query aggregate sentiment analytics.
+
+#### List Feedback
+
+```
+GET /api/feedback
+```
+
+Query params: `agent`, `taskId`, `sentiment` (`positive` | `neutral` | `negative`), `since` (ISO timestamp), `limit` (default 50), `offset`.
+
+**Response:** Array of feedback objects.
+
+```json
+[
+  {
+    "id": "fb_abc123",
+    "content": "The summary was concise and accurate.",
+    "sentiment": "positive",
+    "category": "output-quality",
+    "agent": "TARS",
+    "taskId": "task_20260321_abc",
+    "createdAt": "2026-03-21T14:00:00.000Z"
+  }
+]
+```
+
+#### Submit Feedback
+
+```
+POST /api/feedback
+```
+
+```json
+{
+  "content": "The response missed the key point.",
+  "sentiment": "negative",
+  "category": "accuracy",
+  "agent": "CASE",
+  "taskId": "task_20260321_xyz"
+}
+```
+
+**Response:** `201` with created feedback object.
+
+#### Get Feedback Item
+
+```
+GET /api/feedback/:id
+```
+
+**Response:** Single feedback object.
+
+#### Delete Feedback
+
+```
+DELETE /api/feedback/:id
+```
+
+**Response:** `204 No Content`.
+
+#### Feedback Analytics
+
+```
+GET /api/feedback/analytics
+```
+
+Query params: `agent`, `since`, `until`.
+
+**Response:**
+
+```json
+{
+  "total": 42,
+  "sentimentBreakdown": {
+    "positive": 30,
+    "neutral": 8,
+    "negative": 4
+  },
+  "topCategories": [
+    { "category": "output-quality", "count": 18 },
+    { "category": "accuracy", "count": 12 }
+  ],
+  "trend": [
+    { "date": "2026-03-21", "positive": 5, "neutral": 1, "negative": 0 }
+  ]
+}
+```
+
+---
+
+### Decision Audit Trail (`/api/decisions`)
+
+Log agent decisions with assumptions and record outcomes.
+
+#### List Decisions
+
+```
+GET /api/decisions
+```
+
+Query params: `agent`, `taskId`, `minConfidence` (0–1), `maxConfidence` (0–1), `since`, `until`, `limit`, `offset`.
+
+**Response:** Array of decision objects.
+
+```json
+[
+  {
+    "id": "dec_abc123",
+    "decision": "Use Redis for session caching",
+    "confidence": 0.85,
+    "reasoning": "Redis has sub-ms latency and supports TTL natively.",
+    "evidence": ["benchmark results", "existing infra"],
+    "assumptions": ["Redis cluster is available", "TTL of 1h is sufficient"],
+    "agent": "VERITAS",
+    "taskId": "task_20260321_abc",
+    "createdAt": "2026-03-21T14:00:00.000Z",
+    "outcome": null
+  }
+]
+```
+
+#### Log a Decision
+
+```
+POST /api/decisions
+```
+
+```json
+{
+  "decision": "Refactor auth to use JWT instead of sessions",
+  "confidence": 0.9,
+  "reasoning": "Sessions require sticky routing; JWT is stateless.",
+  "evidence": ["architecture review notes"],
+  "assumptions": ["Clients will store tokens securely"],
+  "agent": "VERITAS",
+  "taskId": "task_20260321_abc"
+}
+```
+
+**Response:** `201` with created decision object.
+
+#### Get Decision
+
+```
+GET /api/decisions/:id
+```
+
+#### Update an Assumption
+
+```
+PATCH /api/decisions/:id/assumptions/:idx
+```
+
+Update a specific assumption by its zero-based index.
+
+```json
+{
+  "text": "Clients will store tokens securely (confirmed via security review)",
+  "held": true
+}
+```
+
+**Response:** Updated decision object with the assumption patched.
+
+---
+
+### Behavioral Drift Detection (`/api/drift`)
+
+Track agent metric baselines and detect behavioral deviations.
+
+#### List Drift Alerts
+
+```
+GET /api/drift/alerts
+```
+
+Query params: `agent`, `acknowledged` (boolean), `since`, `limit`.
+
+**Response:** Array of drift alert objects.
+
+```json
+[
+  {
+    "id": "drift_abc123",
+    "agent": "TARS",
+    "metric": "task_completion_rate",
+    "baseline": 0.92,
+    "current": 0.71,
+    "deviation": 0.21,
+    "threshold": 0.1,
+    "severity": "high",
+    "acknowledged": false,
+    "detectedAt": "2026-03-21T14:00:00.000Z"
+  }
+]
+```
+
+#### Acknowledge Drift Alert
+
+```
+POST /api/drift/alerts/:id/acknowledge
+```
+
+```json
+{
+  "notes": "Agent was rate-limited by upstream API — not a behavior change."
+}
+```
+
+**Response:** Updated alert with `acknowledged: true`.
+
+#### List Baselines
+
+```
+GET /api/drift/baselines
+```
+
+Query params: `agent`, `metric`.
+
+**Response:** Array of baseline records showing current metric norms per agent.
+
+#### Reset Baselines
+
+```
+POST /api/drift/baselines/reset
+```
+
+```json
+{
+  "agent": "TARS",
+  "metric": "task_completion_rate"
+}
+```
+
+**Response:** `200` with updated baseline record.
+
+#### Run Drift Analysis
+
+```
+POST /api/drift/analyze
+```
+
+```json
+{
+  "agent": "TARS"
+}
+```
+
+Compares current metrics against baselines and creates alerts for any out-of-threshold deviations.
+
+**Response:** `200` with analysis summary including number of alerts created.
+
+---
+
+### Agent Policy Engine (`/api/policies`)
+
+Define configurable guard rules for agent tool and action access.
+
+#### List Policies
+
+```
+GET /api/policies
+```
+
+Query params: `agent`, `project`, `enabled` (boolean).
+
+**Response:** Array of policy objects.
+
+```json
+[
+  {
+    "id": "pol_abc123",
+    "name": "No web access for Intern agents",
+    "description": "Intern-level agents cannot use browser or fetch tools.",
+    "enabled": true,
+    "scope": { "agentLevel": "intern" },
+    "rules": [
+      {
+        "tool": "browser",
+        "action": "*",
+        "effect": "deny"
+      }
+    ],
+    "precedence": "deny-first",
+    "createdAt": "2026-03-21T14:00:00.000Z"
+  }
+]
+```
+
+#### Create Policy
+
+```
+POST /api/policies
+```
+
+```json
+{
+  "name": "Require approval for file deletion",
+  "enabled": true,
+  "scope": { "global": true },
+  "rules": [
+    {
+      "tool": "exec",
+      "action": "rm",
+      "effect": "require-approval"
+    }
+  ],
+  "precedence": "deny-first"
+}
+```
+
+**Response:** `201` with created policy object.
+
+#### Get Policy
+
+```
+GET /api/policies/:id
+```
+
+#### Update Policy
+
+```
+PUT /api/policies/:id
+```
+
+#### Delete Policy
+
+```
+DELETE /api/policies/:id
+```
+
+**Response:** `204 No Content`.
+
+#### Evaluate Policy
+
+```
+POST /api/policies/:id/evaluate
+```
+
+```json
+{
+  "agent": "TARS",
+  "tool": "browser",
+  "action": "navigate",
+  "metadata": { "url": "https://example.com" }
+}
+```
+
+**Response:**
+
+```json
+{
+  "allowed": false,
+  "effect": "deny",
+  "matchedRule": { "tool": "browser", "action": "*", "effect": "deny" },
+  "policyId": "pol_abc123",
+  "auditId": "audit_xyz789"
+}
+```
+
+---
+
+### Output Evaluation & Scoring (`/api/scoring`)
+
+Create scoring profiles and evaluate agent outputs against weighted criteria.
+
+#### List Scoring Profiles
+
+```
+GET /api/scoring/profiles
+```
+
+Query params: `limit`, `offset`.
+
+**Response:** Array of scoring profile objects.
+
+#### Create Scoring Profile
+
+```
+POST /api/scoring/profiles
+```
+
+```json
+{
+  "name": "Code Quality Baseline",
+  "description": "Checks for common quality indicators in generated code.",
+  "compositeMethod": "weightedAvg",
+  "scorers": [
+    {
+      "id": "s1",
+      "name": "No hardcoded secrets",
+      "type": "RegexMatch",
+      "pattern": "(password|secret|api_key)\\s*=\\s*['\"][^'\"]+['\"]",
+      "flags": "i",
+      "invert": true,
+      "weight": 2,
+      "scoreOnMatch": 0,
+      "scoreOnMiss": 1
+    },
+    {
+      "id": "s2",
+      "name": "Has error handling",
+      "type": "KeywordContains",
+      "keywords": ["try", "catch", "error"],
+      "matchMode": "any",
+      "weight": 1
+    }
+  ]
+}
+```
+
+**Response:** `201` with created profile.
+
+#### Get Scoring Profile
+
+```
+GET /api/scoring/profiles/:id
+```
+
+#### Update Scoring Profile
+
+```
+PUT /api/scoring/profiles/:id
+```
+
+#### Delete Scoring Profile
+
+```
+DELETE /api/scoring/profiles/:id
+```
+
+**Response:** `204 No Content`.
+
+#### Evaluate Output
+
+```
+POST /api/scoring/evaluate
+```
+
+```json
+{
+  "profileId": "prof_abc123",
+  "output": "function getUser(id) {\n  try {\n    return db.find(id);\n  } catch (e) {\n    throw e;\n  }\n}",
+  "action": "generate_function",
+  "agent": "TARS",
+  "taskId": "task_20260321_abc"
+}
+```
+
+**Response:**
+
+```json
+{
+  "id": "eval_xyz789",
+  "profileId": "prof_abc123",
+  "score": 0.88,
+  "compositeMethod": "weightedAvg",
+  "scorerResults": [
+    { "id": "s1", "name": "No hardcoded secrets", "score": 1.0, "weight": 2 },
+    { "id": "s2", "name": "Has error handling", "score": 1.0, "weight": 1 }
+  ],
+  "agent": "TARS",
+  "taskId": "task_20260321_abc",
+  "evaluatedAt": "2026-03-21T14:00:00.000Z"
+}
+```
+
+#### Evaluation History
+
+```
+GET /api/scoring/history
+```
+
+Query params: `profileId`, `agent`, `taskId`, `since`, `limit`, `offset`.
+
+**Response:** Array of past evaluation results.
+
+---
+
+### Prompt Template Registry (`/api/prompt-registry`)
+
+Manage version-controlled prompt templates with variable extraction and usage tracking.
+
+#### List Templates
+
+```
+GET /api/prompt-registry
+```
+
+Query params: `tag`, `search`, `limit`, `offset`.
+
+**Response:** Array of template summaries (without full content for performance).
+
+#### Create Template
+
+```
+POST /api/prompt-registry
+```
+
+```json
+{
+  "name": "Task Completion Summary",
+  "description": "Generates a completion summary for a finished task.",
+  "content": "You completed task {{task_title}}. Summarize what was done in 2-3 sentences, referencing the acceptance criteria: {{acceptance_criteria}}",
+  "tags": ["completion", "summary"],
+  "changelog": "Initial version"
+}
+```
+
+**Response:** `201` with created template including auto-extracted variables (`task_title`, `acceptance_criteria`).
+
+#### Get Template
+
+```
+GET /api/prompt-registry/:id
+```
+
+**Response:** Full template with current content, version number, variables list, and metadata.
+
+#### Update Template
+
+```
+PATCH /api/prompt-registry/:id
+```
+
+Body: Partial template fields. Triggers automatic version creation.
+
+```json
+{
+  "content": "You completed task {{task_title}} (ID: {{task_id}}). Summarize...",
+  "changelog": "Added task_id variable"
+}
+```
+
+#### Delete Template
+
+```
+DELETE /api/prompt-registry/:id
+```
+
+**Response:** `204 No Content`.
+
+#### List Versions
+
+```
+GET /api/prompt-registry/:id/versions
+```
+
+**Response:** Array of version objects (id, versionNumber, changelog, createdAt). Does not include full content for performance.
+
+#### Get Usage History
+
+```
+GET /api/prompt-registry/:id/usage
+```
+
+Query params: `limit`, `offset`.
+
+**Response:** Array of usage records with model, token counts, and timestamps.
+
+#### Template Stats
+
+```
+GET /api/prompt-registry/:id/stats
+```
+
+**Response:**
+
+```json
+{
+  "totalUses": 42,
+  "averageInputTokens": 312,
+  "averageOutputTokens": 128,
+  "lastUsedAt": "2026-03-21T14:00:00.000Z"
+}
+```
+
+#### Aggregate Stats (All Templates)
+
+```
+GET /api/prompt-registry/stats/all
+```
+
+**Response:** Aggregate usage stats across all templates.
+
+#### Preview Template
+
+```
+POST /api/prompt-registry/:id/render-preview
+```
+
+```json
+{
+  "variables": {
+    "task_title": "Add OAuth login",
+    "acceptance_criteria": "Users can log in with Google."
+  }
+}
+```
+
+**Response:** `{ "rendered": "You completed task Add OAuth login. Summarize..." }`
+
+#### Record Usage
+
+```
+POST /api/prompt-registry/:id/record-usage
+```
+
+```json
+{
+  "model": "anthropic/claude-sonnet-4-6",
+  "inputTokens": 320,
+  "outputTokens": 145,
+  "renderedOutput": "You completed task Add OAuth login...",
+  "variables": { "task_title": "Add OAuth login" }
+}
+```
+
+**Response:** `201` with logged usage record.
+
+---
+
+### System Health (`/api/v1/system/health`)
+
+Get a real-time snapshot of system health across resources, agents, and operations.
+
+```
+GET /api/v1/system/health
+```
+
+No query params required.
+
+**Response:**
+
+```json
+{
+  "status": "stable",
+  "level": 0,
+  "signals": {
+    "system": {
+      "status": "stable",
+      "storageUsedPercent": 42,
+      "diskFreeGb": 120,
+      "memoryUsedPercent": 58
+    },
+    "agents": {
+      "status": "stable",
+      "online": 3,
+      "offline": 0,
+      "total": 3
+    },
+    "operations": {
+      "status": "stable",
+      "successRate": 0.97,
+      "recentRuns": 50,
+      "recentFailures": 1
+    }
+  },
+  "timestamp": "2026-03-21T14:00:00.000Z"
+}
+```
+
+**Health levels:** `stable` (0) · `reviewing` (1) · `drifting` (2) · `elevated` (3) · `alert` (4)
+
 ---

 _For workflow engine endpoints, see [API-WORKFLOWS.md](API-WORKFLOWS.md)._  
--- a/docs/CLI-AGENT-PULL.md
+++ b/docs/CLI-AGENT-PULL.md
--- a/docs/DOC-FRESHNESS.md
+++ b/docs/DOC-FRESHNESS.md
@ -47,7 +47,7 @@ When completing a task that changes user-facing behavior:
 Each doc should include a freshness header:

 ```markdown
-<!-- doc-freshness: 2026-03-02 | v3.3.3 | @tars -->
+<!-- doc-freshness: 2026-03-21 | v4.0.0 | @tars -->
 ```

 Format: `date | version | last-updater`
--- a/docs/FEATURES.md
+++ b/docs/FEATURES.md
@ -1882,4 +1882,216 @@ Working toward WCAG 2.1 AA compliance.

 ---

-_Last updated: 2026-03-07 · [Back to README](../README.md)_
+---
+
+## v4.0 Features
+
+### Agent Policy & Guard Engine
+
+Define what agents are allowed to do. The Policy Engine lets you create configurable tool/action policies with guard rules, evaluated at runtime before any agent executes a tool or action. Every evaluation decision is logged for audit.
+
+**Key capabilities:**
+
+- Define policies scoped to a specific agent, project, or globally
+- Guard rule actions: `allow`, `deny`, `require-approval`
+- Configurable precedence: `deny-first` (default) or `allow-first`
+- Policy conditions: match by tool name, action type, agent, project, or arbitrary metadata
+- Every policy evaluation is logged in the built-in audit log
+- `POST /api/policies/:id/evaluate` for programmatic pre-flight checks
+
+**API endpoints:**
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/policies` | List all policies |
+| `POST` | `/api/policies` | Create a policy |
+| `GET` | `/api/policies/:id` | Get a single policy |
+| `PUT` | `/api/policies/:id` | Update a policy |
+| `DELETE` | `/api/policies/:id` | Delete a policy |
+| `POST` | `/api/policies/:id/evaluate` | Evaluate a policy against an action |
+
+**Related:** `server/src/routes/policies.ts` · `shared/src/types/policy.types.ts` · `docs/SOP-agent-policy-engine.md`
+
+---
+
+### Decision Audit Trail with Assumption Tracking
+
+Log structured decision records for every significant agent choice. Each decision captures the rationale, confidence score, supporting evidence, and stated assumptions. After execution, record the outcome to see whether the decision was sound and whether assumptions held.
+
+**Key capabilities:**
+
+- Structured records: decision text, confidence (0–1), evidence array, assumptions array
+- Outcome recording: what happened, whether assumptions held, a retrospective rating
+- Full-text search and filtering by agent, task, confidence range, and date range
+- Queryable from MCP for agent self-review
+- Aggregate analysis: frequency, confidence trends, assumption hit rate
+
+**API endpoints:**
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/decisions` | List decisions (filterable by agent, task, confidence) |
+| `POST` | `/api/decisions` | Log a new decision |
+| `GET` | `/api/decisions/:id` | Get a single decision |
+| `PATCH` | `/api/decisions/:id/assumptions/:idx` | Update an assumption by index |
+
+**Related:** `server/src/routes/decisions.ts` · `shared/src/types/decision.types.ts` · `docs/SOP-decision-audit-trail.md`
+
+---
+
+### Agent Output Evaluation & Scoring Framework
+
+Define scoring profiles with weighted criteria and evaluate agent outputs against them. Get a composite score, per-scorer breakdown, and per-dimension explanations that make quality regressions auditable.
+
+**Key capabilities:**
+
+- Four scorer types: `RegexMatch`, `KeywordContains`, `NumericRange`, `CustomExpression`
+- Weighted scorers with optional `target`: `action`, `output`, or `combined`
+- Composite scoring methods: `weightedAvg`, `minimum`, `geometricMean`
+- Per-evaluation history with scorer-level breakdowns
+- Attach evaluations to a task (`taskId`) or agent (`agent`) for trend analysis
+
+**API endpoints:**
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/scoring/profiles` | List scoring profiles |
+| `POST` | `/api/scoring/profiles` | Create a profile |
+| `GET` | `/api/scoring/profiles/:id` | Get a profile |
+| `PUT` | `/api/scoring/profiles/:id` | Update a profile |
+| `DELETE` | `/api/scoring/profiles/:id` | Delete a profile |
+| `POST` | `/api/scoring/evaluate` | Evaluate an output against a profile |
+| `GET` | `/api/scoring/history` | Get evaluation history |
+
+**Related:** `server/src/routes/scoring.ts` · `docs/SOP-output-evaluation.md`
+
+---
+
+### Behavioral Drift Detection & Alerting
+
+Define metric baselines for agents and get alerted when behavior deviates beyond configured thresholds. Drift records track status lifecycle (`ok` → `warning` → `alert` → `resolved`) and timestamps for detection and resolution events.
+
+**Key capabilities:**
+
+- Track any numeric metric with a name, baseline, current value, and threshold
+- Alert types: `z-score`, `percentage-change`, `absolute-deviation`
+- Drift status lifecycle with automatic timestamp tracking
+- Manual or programmatic resolution with notes
+- Queryable by agent, status, and date range
+
+**API endpoints:**
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/drift/alerts` | List drift alerts |
+| `POST` | `/api/drift/alerts/:id/acknowledge` | Acknowledge a drift alert |
+| `GET` | `/api/drift/baselines` | List agent metric baselines |
+| `POST` | `/api/drift/baselines/reset` | Reset baselines for an agent/metric |
+| `POST` | `/api/drift/analyze` | Trigger drift analysis for an agent |
+
+**Related:** `server/src/routes/drift.ts` · `shared/src/types/drift.types.ts` · `docs/SOP-behavioral-drift-detection.md`
+
+---
+
+### User Feedback Loop with Sentiment Analytics
+
+Collect feedback on agent outputs from users, tag it with sentiment and categories, and query aggregate analytics to identify patterns and improvement areas.
+
+**Key capabilities:**
+
+- Feedback items: content text, sentiment (`positive`/`neutral`/`negative`), category tags
+- Link feedback to a task (`taskId`) and/or agent (`agent`)
+- Analytics endpoint: sentiment breakdowns, trends over time, top categories
+- Filter by agent, task, sentiment, date range
+- Soft-delete support (feedback can be removed without breaking analytics history)
+
+**API endpoints:**
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/feedback` | List feedback items |
+| `POST` | `/api/feedback` | Submit feedback |
+| `GET` | `/api/feedback/:id` | Get a single item |
+| `DELETE` | `/api/feedback/:id` | Delete a feedback item |
+| `GET` | `/api/feedback/analytics` | Get aggregate sentiment analytics |
+
+**Related:** `server/src/routes/feedback.ts` · `shared/src/types/feedback.types.ts` · `docs/SOP-user-feedback.md`
+
+---
+
+### Draggable & Resizable Dashboard Widget Grid
+
+The dashboard is now fully customizable. Widgets can be repositioned via drag-and-drop and resized to fit your workflow. Layouts persist to `settings.json` so your arrangement survives page reloads and server restarts.
+
+**Key capabilities:**
+
+- Drag widgets to any grid position; snap-to-grid keeps layouts clean
+- Resize handles on every widget; minimum and maximum size constraints per widget type
+- Layout persistence via the settings API — no extra config needed
+- Widget library: add/remove widgets from a catalog panel
+- All existing widgets (task metrics, agent status, recent activity, squad chat) supported
+
+**Related:** `web/src/components/DraggableWidgetGrid` · `docs/FEATURES.md` (this file)
+
+---
+
+### Prompt Template Registry with Version Control
+
+A centralized library for managing prompt templates used across your agent fleet. Templates are versioned, variable-extracted, and usage-tracked. Roll back to any previous version with a single API call.
+
+**Key capabilities:**
+
+- Template CRUD with variable extraction: `{{variable_name}}` syntax auto-detected
+- Full version history — every save creates an immutable version entry with optional changelog
+- Rollback: promote any historical version to current
+- Preview rendering: POST sample variable values and get the rendered prompt back
+- Usage tracking: log which model, how many tokens, and the rendered output (optional)
+- Stats endpoint: total uses, average tokens, most recent use
+
+**API endpoints:**
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/prompt-registry` | List all templates |
+| `POST` | `/api/prompt-registry` | Create a new template |
+| `GET` | `/api/prompt-registry/:id` | Get a template |
+| `PATCH` | `/api/prompt-registry/:id` | Update a template (auto-versions) |
+| `DELETE` | `/api/prompt-registry/:id` | Delete a template |
+| `GET` | `/api/prompt-registry/:id/versions` | List all versions of a template |
+| `GET` | `/api/prompt-registry/:id/usage` | Get usage history |
+| `GET` | `/api/prompt-registry/:id/stats` | Get usage statistics |
+| `GET` | `/api/prompt-registry/stats/all` | Aggregate stats across all templates |
+| `POST` | `/api/prompt-registry/:id/render-preview` | Render a preview with variable injection |
+| `POST` | `/api/prompt-registry/:id/record-usage` | Record a usage event |
+| `POST` | `/api/prompt-registry/templates/:id/usage` | Log a template usage |
+
+**Related:** `server/src/routes/prompt-registry.ts` · `shared/src/types/prompt-registry.types.ts` · `docs/SOP-prompt-registry.md`
+
+---
+
+### Global System Health Status Bar
+
+A persistent header status bar that gives you a real-time overview of system health across three signal categories: system resources, agent availability, and operation success rate. Five health levels from `stable` to `alert` tell you at a glance when something needs attention.
+
+**Key capabilities:**
+
+- Five health levels: `stable` · `reviewing` · `drifting` · `elevated` · `alert`
+- Three signal categories:
+  - **System:** storage usage, disk space, memory
+  - **Agents:** online vs offline agent counts
+  - **Operations:** success rate, recent run counts
+- Expand/collapse detail panel inline in the header
+- Configurable thresholds via settings
+- REST API for programmatic polling or external monitoring
+
+**API endpoints:**
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/v1/system/health` | Get current system health snapshot |
+
+**Related:** `server/src/routes/system-health.ts` · `shared/src/types/system-health.types.ts` · `web/src/components/SystemHealthBar` · `docs/SOP-system-health-monitoring.md`
+
+---
+
+_Last updated: 2026-03-21 · [Back to README](../README.md)_
--- a/docs/SOP-agent-policy-engine.md
+++ b/docs/SOP-agent-policy-engine.md
@ -0,0 +1,170 @@
+# SOP: Agent Policy & Guard Engine
+
+Configure and enforce access policies for agent tools and actions.
+
+---
+
+## Overview
+
+The Agent Policy Engine lets you define named policies with guard rules that control what tools and actions each agent can access. Rules support three effects:
+
+| Effect              | Behavior                                           |
+| ------------------- | -------------------------------------------------- |
+| `allow`             | Permit the tool/action immediately                 |
+| `deny`              | Block the tool/action with a 403 response          |
+| `require-approval`  | Hold the request until a human approves            |
+
+Policies are evaluated in order of precedence. The engine supports two precedence strategies:
+
+- **`deny-first`** — Any matching `deny` rule blocks, regardless of `allow` rules
+- **`allow-first`** — First matching rule wins
+
+---
+
+## Prerequisites
+
+- VK server running (v4.0+)
+- API key with write access
+- Understanding of which agents need restricted or expanded access
+
+---
+
+## Step-by-Step Procedure
+
+### 1. List Existing Policies
+
+Before creating, check what's already configured:
+
+```bash
+curl http://localhost:3001/api/policies \
+  -H "X-API-Key: YOUR_KEY"
+```
+
+Filter by agent or project:
+
+```bash
+curl "http://localhost:3001/api/policies?agent=TARS&enabled=true" \
+  -H "X-API-Key: YOUR_KEY"
+```
+
+### 2. Create a Policy
+
+```bash
+curl -X POST http://localhost:3001/api/policies \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: YOUR_KEY" \
+  -d '{
+    "name": "Restrict browser access for intern agents",
+    "description": "Prevent intern-level agents from using browser or fetch tools.",
+    "enabled": true,
+    "scope": { "agentLevel": "intern" },
+    "rules": [
+      { "tool": "browser", "action": "*", "effect": "deny" },
+      { "tool": "web_fetch", "action": "*", "effect": "deny" }
+    ],
+    "precedence": "deny-first"
+  }'
+```
+
+**Response:** `201` with the created policy object including its `id`.
+
+### 3. Evaluate a Policy
+
+Test a policy before relying on it in production:
+
+```bash
+curl -X POST http://localhost:3001/api/policies/pol_abc123/evaluate \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: YOUR_KEY" \
+  -d '{
+    "agent": "TARS",
+    "tool": "browser",
+    "action": "navigate"
+  }'
+```
+
+**Response:**
+
+```json
+{
+  "allowed": false,
+  "effect": "deny",
+  "matchedRule": { "tool": "browser", "action": "*", "effect": "deny" },
+  "policyId": "pol_abc123",
+  "auditId": "audit_xyz789"
+}
+```
+
+### 4. Update a Policy
+
+Enable, disable, or modify rules:
+
+```bash
+curl -X PUT http://localhost:3001/api/policies/pol_abc123 \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: YOUR_KEY" \
+  -d '{
+    "enabled": false
+  }'
+```
+
+### 5. Delete a Policy
+
+```bash
+curl -X DELETE http://localhost:3001/api/policies/pol_abc123 \
+  -H "X-API-Key: YOUR_KEY"
+```
+
+**Response:** `204 No Content`.
+
+---
+
+## API Endpoints
+
+| Method   | Path                           | Description                     |
+| -------- | ------------------------------ | ------------------------------- |
+| `GET`    | `/api/policies`                | List all policies                |
+| `POST`   | `/api/policies`                | Create a new policy              |
+| `GET`    | `/api/policies/:id`            | Get a specific policy            |
+| `PUT`    | `/api/policies/:id`            | Update a policy                  |
+| `DELETE` | `/api/policies/:id`            | Delete a policy                  |
+| `POST`   | `/api/policies/:id/evaluate`   | Evaluate a policy for an action  |
+
+---
+
+## Policy Object Schema
+
+| Field         | Type     | Required | Description                                      |
+| ------------- | -------- | -------- | ------------------------------------------------ |
+| `name`        | string   | ✅       | Human-readable policy name                       |
+| `description` | string   | ❌       | What the policy does                             |
+| `enabled`     | boolean  | ✅       | Whether the policy is active                     |
+| `scope`       | object   | ❌       | Targeting: `{ agent, agentLevel, project }`      |
+| `rules`       | array    | ✅       | Array of guard rules (see below)                 |
+| `precedence`  | enum     | ✅       | `deny-first` or `allow-first`                    |
+
+### Guard Rule Schema
+
+| Field    | Type   | Required | Description                                      |
+| -------- | ------ | -------- | ------------------------------------------------ |
+| `tool`   | string | ✅       | Tool name or `*` for any                         |
+| `action` | string | ✅       | Action name or `*` for any                       |
+| `effect` | enum   | ✅       | `allow`, `deny`, or `require-approval`           |
+
+---
+
+## Common Issues
+
+**Policy not applying:** Check that `enabled: true` is set and the scope matches the agent making the request.
+
+**Evaluation returns `allow` unexpectedly:** If using `allow-first`, ensure deny rules come before allow rules in the `rules` array, or switch to `deny-first` precedence.
+
+**Audit log missing entries:** Every evaluation creates an audit entry even if not explicitly requested. Check the audit log API for policy decision history.
+
+---
+
+## Related Docs
+
+- [FEATURES.md — Agent Policy Engine](./FEATURES.md#agent-policy--guard-engine)
+- [API-REFERENCE.md — Policies](./API-REFERENCE.md#agent-policy-engine-apipolicies)
+- [SOP: Decision Audit Trail](./SOP-decision-audit-trail.md)
--- a/docs/SOP-behavioral-drift-detection.md
+++ b/docs/SOP-behavioral-drift-detection.md
@ -0,0 +1,166 @@
+# SOP: Behavioral Drift Detection & Alerting
+
+Monitor agent metric baselines and respond to detected drift.
+
+---
+
+## Overview
+
+Drift detection compares an agent's current performance metrics against established baselines. When a metric deviates beyond a configured threshold, an alert is created. Alerts move through a lifecycle:
+
+| State          | Meaning                                       |
+| -------------- | --------------------------------------------- |
+| `detected`     | Deviation found, alert created                |
+| `acknowledged` | A human or process has reviewed the alert     |
+
+Metrics that drift detection monitors (examples):
+- Task completion rate
+- Average run duration
+- Error rate
+- Token usage per task
+- Output quality score
+
+---
+
+## Prerequisites
+
+- VK server running (v4.0+)
+- Baselines populated (either from historical data or manually set)
+- Thresholds configured per metric
+
+---
+
+## Step-by-Step Procedure
+
+### 1. Check Current Baselines
+
+Before responding to drift, understand what the system considers normal:
+
+```bash
+curl http://localhost:3001/api/drift/baselines
+```
+
+Filter by agent:
+
+```bash
+curl "http://localhost:3001/api/drift/baselines?agent=TARS"
+```
+
+**Response:** Array of baseline records showing `metric`, `baseline` value, `threshold`, and last updated timestamp.
+
+### 2. Run Drift Analysis
+
+Trigger an analysis to check if current metrics have drifted from baselines:
+
+```bash
+curl -X POST http://localhost:3001/api/drift/analyze \
+  -H "Content-Type: application/json" \
+  -d '{
+    "agent": "TARS"
+  }'
+```
+
+**Response:**
+
+```json
+{
+  "agent": "TARS",
+  "alertsCreated": 2,
+  "metricsChecked": 5,
+  "summary": [
+    { "metric": "task_completion_rate", "baseline": 0.92, "current": 0.71, "status": "alert" },
+    { "metric": "error_rate", "baseline": 0.03, "current": 0.08, "status": "warning" },
+    { "metric": "avg_run_duration_ms", "baseline": 4200, "current": 4350, "status": "ok" }
+  ]
+}
+```
+
+### 3. List Active Drift Alerts
+
+```bash
+# All unacknowledged alerts
+curl "http://localhost:3001/api/drift/alerts?acknowledged=false"
+
+# All alerts for a specific agent
+curl "http://localhost:3001/api/drift/alerts?agent=TARS"
+```
+
+**Response:** Array of drift alert objects.
+
+### 4. Acknowledge an Alert
+
+When you've investigated an alert and it's been addressed:
+
+```bash
+curl -X POST http://localhost:3001/api/drift/alerts/drift_abc123/acknowledge \
+  -H "Content-Type: application/json" \
+  -d '{
+    "notes": "TARS was rate-limited by upstream API from 14:00–15:30. Not a behavioral change. Resolved."
+  }'
+```
+
+**Response:** Updated alert with `acknowledged: true` and your notes.
+
+### 5. Reset Baselines
+
+After intentional changes to an agent's behavior or workload, reset its baselines to reflect the new normal:
+
+```bash
+# Reset a specific metric for an agent
+curl -X POST http://localhost:3001/api/drift/baselines/reset \
+  -H "Content-Type: application/json" \
+  -d '{
+    "agent": "TARS",
+    "metric": "task_completion_rate"
+  }'
+```
+
+**Response:** Updated baseline record with new `baseline` value.
+
+---
+
+## API Endpoints
+
+| Method | Path                                     | Description                              |
+| ------ | ---------------------------------------- | ---------------------------------------- |
+| `GET`  | `/api/drift/alerts`                      | List drift alerts                        |
+| `POST` | `/api/drift/alerts/:id/acknowledge`      | Acknowledge a drift alert                |
+| `GET`  | `/api/drift/baselines`                   | List agent metric baselines              |
+| `POST` | `/api/drift/baselines/reset`             | Reset baselines for an agent/metric      |
+| `POST` | `/api/drift/analyze`                     | Trigger drift analysis for an agent      |
+
+---
+
+## Alert Object Schema
+
+| Field            | Type    | Description                                         |
+| ---------------- | ------- | --------------------------------------------------- |
+| `id`             | string  | Alert ID                                            |
+| `agent`          | string  | Agent the alert is for                              |
+| `metric`         | string  | Metric that triggered the alert                     |
+| `baseline`       | number  | Expected value                                      |
+| `current`        | number  | Observed value                                      |
+| `deviation`      | number  | Absolute difference (current − baseline)            |
+| `threshold`      | number  | Deviation amount that triggers alerting             |
+| `severity`       | string  | `low`, `medium`, `high`                             |
+| `acknowledged`   | boolean | Whether the alert has been reviewed                 |
+| `detectedAt`     | string  | ISO 8601 timestamp of detection                     |
+
+---
+
+## Common Issues
+
+**Alerts immediately after a reset:** Resetting baselines sets the new normal from current data. If the agent is still in a degraded state when you reset, the new baseline will be low, making future detection harder.
+
+**Too many low-severity alerts:** Increase thresholds for noisy metrics, or add a minimum severity filter to your alert queries.
+
+**Analysis returns `alertsCreated: 0` but performance looks wrong:** Baselines may not be populated yet. Check `GET /api/drift/baselines` — if empty, the system has no baseline to compare against.
+
+---
+
+## Related Docs
+
+- [FEATURES.md — Behavioral Drift Detection](./FEATURES.md#behavioral-drift-detection--alerting)
+- [API-REFERENCE.md — Drift](./API-REFERENCE.md#behavioral-drift-detection-apidrift)
+- [SOP: Output Evaluation](./SOP-output-evaluation.md)
+- [SOP: System Health Monitoring](./SOP-system-health-monitoring.md)
--- a/docs/SOP-broadcasts.md
+++ b/docs/SOP-broadcasts.md
@ -0,0 +1,172 @@
+# SOP: Broadcast System
+
+<!-- doc-freshness: 2026-03-21 | v4.0.0 | @tars -->
+
+## Purpose
+
+Send system-wide announcements to agents and users. Broadcasts are priority-tagged messages that agents can poll for unread items, making them useful for coordinating fleet-wide changes, urgent alerts, and informational updates without requiring individual notifications.
+
+## Prerequisites
+
+- Veritas Kanban server running
+- API access (localhost:3001 by default)
+- Agent name for unread tracking (optional but recommended)
+
+## Concepts
+
+| Term | Definition |
+|------|------------|
+| **Broadcast** | A system-wide message with a priority level and optional metadata |
+| **Priority** | `info` (default), `action-required`, or `urgent` |
+| **Read tracking** | Each agent marks broadcasts read independently — unread state is per-agent |
+| **WebSocket delivery** | New broadcasts are pushed via WebSocket in real-time; polling is available as fallback |
+
+## Step-by-Step: Send a Broadcast
+
+### Standard info broadcast
+
+```bash
+curl -s -X POST http://localhost:3001/api/broadcasts \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "message": "Deployment complete: VK 4.0.0 is now running. All agents should reload their task context.",
+    "priority": "info",
+    "source": "VERITAS"
+  }'
+```
+
+→ Returns `201` with the broadcast record including its `id`. The WebSocket event fires immediately — all connected clients receive it.
+
+### Urgent broadcast requiring agent action
+
+```bash
+curl -s -X POST http://localhost:3001/api/broadcasts \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "message": "API quota exhausted for OpenAI. All agents: pause LLM calls until further notice.",
+    "priority": "urgent",
+    "source": "VERITAS",
+    "metadata": { "affectedService": "openai", "resumeEta": "2026-03-21T16:00:00Z" }
+  }'
+```
+
+## Step-by-Step: Read and Acknowledge Broadcasts
+
+### List all recent broadcasts (any priority)
+
+```bash
+curl -s "http://localhost:3001/api/broadcasts?limit=10"
+```
+
+### List unread broadcasts for a specific agent
+
+```bash
+curl -s "http://localhost:3001/api/broadcasts?agent=TARS&unread=true"
+```
+
+> **Note:** `unread=true` requires the `agent` parameter. Omitting `agent` with `unread=true` returns a 400 error.
+
+### Mark a broadcast as read
+
+```bash
+curl -s -X PATCH http://localhost:3001/api/broadcasts/bcast_abc123/read \
+  -H 'Content-Type: application/json' \
+  -d '{ "agent": "TARS" }'
+```
+
+→ Returns `{ "success": true }`.
+
+### Get a single broadcast by ID
+
+```bash
+curl -s "http://localhost:3001/api/broadcasts/bcast_abc123"
+```
+
+## Step-by-Step: Agent Broadcast Polling
+
+Integrate into an agent's startup or polling loop:
+
+```typescript
+// On agent startup or heartbeat cycle
+async function checkBroadcasts(agentName: string): Promise<void> {
+  const response = await fetch(
+    `${VK_API_URL}/api/broadcasts?agent=${agentName}&unread=true`
+  );
+  const broadcasts = await response.json();
+
+  for (const broadcast of broadcasts) {
+    console.log(`[BROADCAST] [${broadcast.priority.toUpperCase()}] ${broadcast.message}`);
+
+    // Handle action-required or urgent broadcasts
+    if (broadcast.priority === 'urgent') {
+      await pauseCurrentWork();
+      // surface to operator / human
+    }
+
+    // Mark as read
+    await fetch(`${VK_API_URL}/api/broadcasts/${broadcast.id}/read`, {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ agent: agentName })
+    });
+  }
+}
+```
+
+## Step-by-Step: Filter Broadcasts
+
+### By priority
+
+```bash
+# Only urgent broadcasts
+curl -s "http://localhost:3001/api/broadcasts?priority=urgent"
+
+# Action-required only
+curl -s "http://localhost:3001/api/broadcasts?priority=action-required"
+```
+
+### Since a timestamp
+
+```bash
+# Broadcasts in the last hour
+curl -s "http://localhost:3001/api/broadcasts?since=2026-03-21T13:00:00Z"
+```
+
+### Combined filters
+
+```bash
+# Unread urgent broadcasts for TARS since noon
+curl -s "http://localhost:3001/api/broadcasts?agent=TARS&unread=true&priority=urgent&since=2026-03-21T12:00:00Z"
+```
+
+## Priority Guide
+
+| Priority | When to use | Agent response |
+|----------|-------------|----------------|
+| `info` | Routine announcements (deployments, completions, status updates) | Acknowledge when convenient |
+| `action-required` | Something needs attention but isn't critical (config change, review needed) | Address before starting new work |
+| `urgent` | Immediate action required (quota exhausted, production incident, system failure) | Stop current work and respond immediately |
+
+## API Endpoints Used
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `POST` | `/api/broadcasts` | Send a broadcast |
+| `GET` | `/api/broadcasts` | List broadcasts (filterable) |
+| `GET` | `/api/broadcasts/:id` | Get a single broadcast |
+| `PATCH` | `/api/broadcasts/:id/read` | Mark as read for an agent |
+
+## Common Issues / Troubleshooting
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| `400` on `unread=true` | Missing `agent` param | Add `?agent=<agentname>` to the query |
+| Broadcast not appearing real-time | Agent isn't connected via WebSocket | Check WebSocket connection; fall back to polling |
+| Agent sees same broadcasts repeatedly | Not calling the `/read` endpoint after processing | Always mark broadcasts read after handling them |
+| Old broadcasts cluttering the list | No TTL/expiry in v4.0 | Use `?since=` to filter by recency |
+
+## Related Docs
+
+- [docs/features/broadcasts.md](features/broadcasts.md) — Feature deep-dive
+- [SOP-agent-task-workflow.md](SOP-agent-task-workflow.md) — How broadcasts fit into the agent task lifecycle
+- [SOP-lifecycle-hooks.md](SOP-lifecycle-hooks.md) — Hooks can trigger broadcasts on task events
--- a/docs/SOP-decision-audit-trail.md
+++ b/docs/SOP-decision-audit-trail.md
@ -0,0 +1,150 @@
+# SOP: Decision Audit Trail
+
+Log, track, and review agent decisions with assumptions.
+
+---
+
+## Overview
+
+The Decision Audit Trail gives every agent-made decision a permanent, searchable record. Each decision includes:
+
+- The decision text and the agent that made it
+- A confidence score (0–1)
+- Reasoning and supporting evidence
+- A list of assumptions the decision depends on
+
+Assumptions can be marked as held or not-held after the fact, providing a post-hoc quality signal for decision-making.
+
+---
+
+## Prerequisites
+
+- VK server running (v4.0+)
+- Agent identifier (e.g., `TARS`, `VERITAS`)
+
+---
+
+## Step-by-Step Procedure
+
+### 1. Log a Decision
+
+Call this immediately when an agent makes a significant decision:
+
+```bash
+curl -X POST http://localhost:3001/api/decisions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "decision": "Use Redis for session caching",
+    "confidence": 0.85,
+    "reasoning": "Redis provides sub-ms latency and native TTL support — both required by the auth system SLA.",
+    "evidence": ["benchmark results from ticket #204", "existing Redis cluster in infra"],
+    "assumptions": [
+      "Redis cluster remains available during peak hours",
+      "1-hour TTL is sufficient for user sessions"
+    ],
+    "agent": "VERITAS",
+    "taskId": "task_20260321_abc"
+  }'
+```
+
+**Response:** `201` with decision object including `id`.
+
+### 2. List Decisions
+
+```bash
+# All decisions
+curl http://localhost:3001/api/decisions
+
+# Filter by agent and confidence
+curl "http://localhost:3001/api/decisions?agent=VERITAS&minConfidence=0.8"
+
+# Filter by task
+curl "http://localhost:3001/api/decisions?taskId=task_20260321_abc"
+```
+
+### 3. Retrieve a Single Decision
+
+```bash
+curl http://localhost:3001/api/decisions/dec_abc123
+```
+
+### 4. Update an Assumption
+
+After the outcome is known, mark individual assumptions as held or not held:
+
+```bash
+# Update assumption at index 0 (zero-based)
+curl -X PATCH http://localhost:3001/api/decisions/dec_abc123/assumptions/0 \
+  -H "Content-Type: application/json" \
+  -d '{
+    "text": "Redis cluster remains available during peak hours (confirmed — 99.9% uptime observed)",
+    "held": true
+  }'
+
+# Mark assumption at index 1 as not held
+curl -X PATCH http://localhost:3001/api/decisions/dec_abc123/assumptions/1 \
+  -H "Content-Type: application/json" \
+  -d '{
+    "text": "1-hour TTL proved insufficient — users reported session drops after 45 minutes",
+    "held": false
+  }'
+```
+
+---
+
+## API Endpoints
+
+| Method  | Path                                       | Description                           |
+| ------- | ------------------------------------------ | ------------------------------------- |
+| `GET`   | `/api/decisions`                           | List decisions (filterable)           |
+| `POST`  | `/api/decisions`                           | Log a new decision                    |
+| `GET`   | `/api/decisions/:id`                       | Get a single decision                 |
+| `PATCH` | `/api/decisions/:id/assumptions/:idx`      | Update a specific assumption by index |
+
+---
+
+## Decision Object Schema
+
+| Field         | Type     | Required | Description                                         |
+| ------------- | -------- | -------- | --------------------------------------------------- |
+| `decision`    | string   | ✅       | The decision made                                   |
+| `confidence`  | number   | ✅       | 0–1 confidence score                                |
+| `reasoning`   | string   | ❌       | Why this decision was made                          |
+| `evidence`    | string[] | ❌       | Supporting evidence references                      |
+| `assumptions` | string[] | ❌       | Assumptions the decision depends on                 |
+| `agent`       | string   | ✅       | Agent identifier                                    |
+| `taskId`      | string   | ❌       | Associated task ID                                  |
+
+---
+
+## Query Parameters (List)
+
+| Param           | Type   | Description                                  |
+| --------------- | ------ | -------------------------------------------- |
+| `agent`         | string | Filter by agent name                         |
+| `taskId`        | string | Filter by task ID                            |
+| `minConfidence` | number | Minimum confidence score (0–1)               |
+| `maxConfidence` | number | Maximum confidence score (0–1)               |
+| `since`         | string | ISO 8601 datetime — decisions after this     |
+| `until`         | string | ISO 8601 datetime — decisions before this    |
+| `limit`         | number | Max records to return (default: 50)          |
+| `offset`        | number | Pagination offset                            |
+
+---
+
+## Common Issues
+
+**Assumptions indexed incorrectly:** Assumptions are zero-indexed. The first assumption in the array is index `0`.
+
+**Low-confidence decisions not surfacing:** Filter with `maxConfidence=0.5` to review decisions where the agent was uncertain.
+
+**Decision not linked to a task:** If `taskId` was omitted on creation, the decision can't be patched to add it — log a new decision.
+
+---
+
+## Related Docs
+
+- [FEATURES.md — Decision Audit Trail](./FEATURES.md#decision-audit-trail-with-assumption-tracking)
+- [API-REFERENCE.md — Decisions](./API-REFERENCE.md#decision-audit-trail-apidecisions)
+- [SOP: Agent Policy Engine](./SOP-agent-policy-engine.md)
+- [SOP: Output Evaluation](./SOP-output-evaluation.md)
--- a/docs/SOP-delegation.md
+++ b/docs/SOP-delegation.md
@ -0,0 +1,192 @@
+# SOP: Delegation Management
+
+<!-- doc-freshness: 2026-03-21 | v4.0.0 | @tars -->
+
+## Purpose
+
+Configure and manage task delegation — temporarily routing new task assignments to a designated delegate agent when the primary agent is unavailable, overloaded, or explicitly stepping back. Delegation includes scope, exclusions, and automatic expiry.
+
+## Prerequisites
+
+- Veritas Kanban server running with admin API key configured
+- Admin-level authentication (required for setting and revoking delegation)
+- The delegate agent must be active and capable of handling delegated scope
+
+## Concepts
+
+| Term | Definition |
+|------|------------|
+| **Delegate agent** | The agent that receives tasks during the delegation period |
+| **Expires** | ISO timestamp when delegation automatically ends (must be in the future) |
+| **Scope** | Which task categories are delegated: `all`, `unassigned`, or `matching` (specific criteria) |
+| **Exclude priorities** | Task priorities that are NOT delegated (e.g., don't delegate `critical` tasks) |
+| **Exclude tags** | Task tags that are NOT delegated |
+
+## Step-by-Step: Set Up Delegation
+
+### 1. Check current delegation status
+
+```bash
+curl -s http://localhost:3001/api/delegation
+```
+
+Returns `{ "delegation": null }` if no delegation is active, or the current delegation object.
+
+### 2. Configure delegation
+
+> **Requires admin auth.** Include your admin API key in the `Authorization` header.
+
+```bash
+curl -s -X POST http://localhost:3001/api/delegation \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer <your-admin-key>' \
+  -d '{
+    "delegateAgent": "CASE",
+    "expires": "2026-03-22T09:00:00Z",
+    "scope": "all",
+    "excludePriorities": ["critical"],
+    "excludeTags": ["security", "production"],
+    "createdBy": "brad"
+  }'
+```
+
+**Response:**
+```json
+{
+  "delegation": {
+    "id": "deleg_abc123",
+    "delegateAgent": "CASE",
+    "expires": "2026-03-22T09:00:00Z",
+    "scope": "all",
+    "excludePriorities": ["critical"],
+    "excludeTags": ["security", "production"],
+    "createdBy": "brad",
+    "createdAt": "2026-03-21T17:00:00Z",
+    "active": true
+  }
+}
+```
+
+**Validation:** If `expires` is in the past, the server returns `400 Validation Error: Expiry date must be in the future`.
+
+### 3. Verify delegation is active
+
+```bash
+curl -s http://localhost:3001/api/delegation | jq '.delegation.active'
+# → true
+```
+
+### 4. Review the delegation log
+
+```bash
+# All delegation approvals
+curl -s "http://localhost:3001/api/delegation/log"
+
+# For a specific task
+curl -s "http://localhost:3001/api/delegation/log?taskId=task_20260321_abc"
+
+# For a specific agent
+curl -s "http://localhost:3001/api/delegation/log?agent=CASE&limit=20"
+```
+
+## Step-by-Step: Revoke Delegation
+
+Revoke immediately before the scheduled expiry:
+
+```bash
+curl -s -X DELETE http://localhost:3001/api/delegation \
+  -H 'Authorization: Bearer <your-admin-key>'
+```
+
+**Response:** `{ "success": true }` on success. `404` if no active delegation exists.
+
+Revocation is logged in the audit log automatically.
+
+## Scope Reference
+
+| Scope | Behavior |
+|-------|----------|
+| `all` | All new task assignments go to the delegate (minus exclusions) |
+| `unassigned` | Only tasks with no assigned agent go to the delegate |
+| `matching` | Only tasks matching specific criteria (configure in `matchCriteria`) |
+
+## Exclusion Reference
+
+Use exclusions to protect your most critical work from delegation:
+
+```json
+{
+  "excludePriorities": ["critical"],
+  "excludeTags": ["security", "production", "pii"]
+}
+```
+
+Tasks matching any exclusion bypass delegation and require direct handling (or remain unassigned until the primary agent is available).
+
+## Delegation Expiry
+
+Delegation expires automatically at the `expires` timestamp. No action needed — the system reverts to normal assignment routing.
+
+To check time remaining:
+
+```bash
+curl -s http://localhost:3001/api/delegation | jq '.delegation.expires'
+```
+
+## Common Delegation Scenarios
+
+### Overnight coverage
+
+```bash
+# Delegate everything non-critical until morning
+curl -s -X POST http://localhost:3001/api/delegation \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer <key>' \
+  -d '{
+    "delegateAgent": "CASE",
+    "expires": "2026-03-22T08:00:00Z",
+    "scope": "all",
+    "excludePriorities": ["critical"],
+    "createdBy": "brad"
+  }'
+```
+
+### Focused work block (unassigned only)
+
+```bash
+# Only route unassigned tasks to CASE while primary handles an important task
+curl -s -X POST http://localhost:3001/api/delegation \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer <key>' \
+  -d '{
+    "delegateAgent": "CASE",
+    "expires": "2026-03-21T19:00:00Z",
+    "scope": "unassigned",
+    "createdBy": "brad"
+  }'
+```
+
+## API Endpoints Used
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `GET` | `/api/delegation` | Get current delegation settings |
+| `POST` | `/api/delegation` | Set (or replace) delegation — requires admin |
+| `DELETE` | `/api/delegation` | Revoke delegation — requires admin |
+| `GET` | `/api/delegation/log` | View delegation approval log |
+
+## Common Issues / Troubleshooting
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| `403 Forbidden` on POST/DELETE | Using a non-admin API key | Switch to the admin key; check `authorize('admin')` config |
+| `400 Expiry date must be in the future` | `expires` timestamp is in the past | Use a future timestamp; check server timezone if unsure |
+| `404` on DELETE | No active delegation to revoke | Verify with `GET /api/delegation` first |
+| Delegation not routing tasks | `scope` or exclusions too restrictive | Review exclusion list; test with a low-priority, untagged task |
+| Tasks going to wrong agent | Delegation expired | Check `expires` timestamp; re-set delegation if needed |
+
+## Related Docs
+
+- [docs/features/delegation.md](features/delegation.md) — Feature deep-dive
+- [SOP-agent-task-workflow.md](SOP-agent-task-workflow.md) — How delegation fits into the standard task workflow
+- [SOP-lifecycle-hooks.md](SOP-lifecycle-hooks.md) — Hooks can fire on delegation events
--- a/docs/SOP-deliverables.md
+++ b/docs/SOP-deliverables.md
@ -0,0 +1,206 @@
+# SOP: Task Deliverables
+
+<!-- doc-freshness: 2026-03-21 | v4.0.0 | @tars -->
+
+## Purpose
+
+Attach structured deliverable records to tasks — tracking what artifacts an agent is expected to produce, their status, and their output paths. Deliverables give human reviewers and orchestrators a clear checklist of what a task produced and whether each output is ready for review.
+
+## Prerequisites
+
+- Veritas Kanban server running
+- An existing task ID to attach deliverables to
+- API access (localhost:3001 by default)
+
+## Concepts
+
+| Term | Definition |
+|------|------------|
+| **Deliverable** | A tracked output artifact associated with a task |
+| **Type** | What kind of artifact: `file`, `url`, `text`, `pr`, `report`, or `other` |
+| **Status** | Lifecycle state: `pending` → `in-progress` → `ready` → `approved` → `rejected` |
+| **Path** | Optional file path or URL pointing to the artifact |
+| **Agent** | Which agent is responsible for producing this deliverable |
+
+## Step-by-Step: Add Deliverables to a Task
+
+### At task start — declare expected outputs
+
+Add deliverables when beginning a task so reviewers know what to expect:
+
+```bash
+curl -s -X POST http://localhost:3001/api/tasks/task_20260321_abc/deliverables \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "title": "Updated CHANGELOG.md",
+    "type": "file",
+    "path": "CHANGELOG.md",
+    "agent": "TARS",
+    "description": "v4.0.0 entry with all PRs and features documented"
+  }'
+```
+
+→ Returns the updated task object. The new deliverable has `status: "pending"` by default.
+
+### Add multiple deliverables
+
+Call the endpoint once per deliverable. Each becomes a separate tracked item:
+
+```bash
+# Second deliverable — the PR
+curl -s -X POST http://localhost:3001/api/tasks/task_20260321_abc/deliverables \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "title": "Pull Request #229",
+    "type": "pr",
+    "path": "https://github.com/BradGroux/veritas-kanban/pull/229",
+    "agent": "TARS",
+    "description": "PR with all doc changes and version bumps"
+  }'
+```
+
+### List all deliverables for a task
+
+```bash
+curl -s "http://localhost:3001/api/tasks/task_20260321_abc/deliverables"
+```
+
+**Response:**
+```json
+[
+  {
+    "id": "deliverable_abc123",
+    "title": "Updated CHANGELOG.md",
+    "type": "file",
+    "path": "CHANGELOG.md",
+    "status": "pending",
+    "agent": "TARS",
+    "description": "v4.0.0 entry with all PRs and features documented",
+    "created": "2026-03-21T14:00:00.000Z"
+  }
+]
+```
+
+## Step-by-Step: Update Deliverable Status
+
+Update status as work progresses — this drives the task's completion checklist.
+
+### Mark as in-progress
+
+```bash
+curl -s -X PATCH \
+  "http://localhost:3001/api/tasks/task_20260321_abc/deliverables/deliverable_abc123" \
+  -H 'Content-Type: application/json' \
+  -d '{ "status": "in-progress" }'
+```
+
+### Mark as ready for review
+
+```bash
+curl -s -X PATCH \
+  "http://localhost:3001/api/tasks/task_20260321_abc/deliverables/deliverable_abc123" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "status": "ready",
+    "path": "CHANGELOG.md"
+  }'
+```
+
+### Mark as approved (by reviewer)
+
+```bash
+curl -s -X PATCH \
+  "http://localhost:3001/api/tasks/task_20260321_abc/deliverables/deliverable_abc123" \
+  -H 'Content-Type: application/json' \
+  -d '{ "status": "approved" }'
+```
+
+### Mark as rejected (needs rework)
+
+```bash
+curl -s -X PATCH \
+  "http://localhost:3001/api/tasks/task_20260321_abc/deliverables/deliverable_abc123" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "status": "rejected",
+    "description": "CHANGELOG entry missing Fixed section — needs all PR #225 details"
+  }'
+```
+
+## Step-by-Step: Remove a Deliverable
+
+```bash
+curl -s -X DELETE \
+  "http://localhost:3001/api/tasks/task_20260321_abc/deliverables/deliverable_abc123"
+```
+
+**Response:** `204 No Content`.
+
+## Deliverable Status Lifecycle
+
+```
+pending → in-progress → ready → approved
+                         ↓
+                       rejected → (agent reworks) → ready → approved
+```
+
+Only `approved` deliverables count as "complete" for task checklist purposes.
+
+## Deliverable Type Reference
+
+| Type | Use For |
+|------|---------|
+| `file` | Files on disk (code, docs, config) — use `path` for filepath |
+| `url` | Web resources (reports, dashboards, hosted docs) — use `path` for URL |
+| `text` | Plain text output (summaries, analysis results) |
+| `pr` | Pull requests — use `path` for the GitHub PR URL |
+| `report` | Structured reports (HTML, PDF) |
+| `other` | Anything else |
+
+## Integrating into Agent Workflows
+
+```typescript
+// At task start: declare deliverables
+const changelog = await vkClient.addDeliverable(taskId, {
+  title: 'CHANGELOG.md entry',
+  type: 'file',
+  path: 'CHANGELOG.md',
+  agent: agentName,
+  description: 'v4.0.0 release notes'
+});
+
+// Mark in-progress when starting
+await vkClient.updateDeliverable(taskId, changelog.id, { status: 'in-progress' });
+
+// ... do the work ...
+
+// Mark ready when done
+await vkClient.updateDeliverable(taskId, changelog.id, {
+  status: 'ready',
+  path: 'CHANGELOG.md'
+});
+```
+
+## API Endpoints Used
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `GET` | `/api/tasks/:id/deliverables` | List all deliverables for a task |
+| `POST` | `/api/tasks/:id/deliverables` | Add a deliverable |
+| `PATCH` | `/api/tasks/:id/deliverables/:deliverableId` | Update status, path, or description |
+| `DELETE` | `/api/tasks/:id/deliverables/:deliverableId` | Remove a deliverable |
+
+## Common Issues / Troubleshooting
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| `404 Task not found` | Task ID doesn't exist | Verify the task ID with `GET /api/tasks/:id` |
+| `404 Deliverable not found` on PATCH | Deliverable ID doesn't exist on that task | `GET /api/tasks/:id/deliverables` to list valid IDs |
+| Status not advancing | Calling PATCH with correct body but wrong deliverable ID | Double-check the `deliverableId` in the URL path |
+| Deliverables not visible in UI | UI may filter by status | Check if the UI is filtering for `pending` or `ready` only |
+
+## Related Docs
+
+- [docs/features/deliverables.md](features/deliverables.md) — Feature deep-dive
+- [SOP-agent-task-workflow.md](SOP-agent-task-workflow.md) — How deliverables fit into the standard task lifecycle
+- [docs/mcp/README.md](mcp/README.md) — Deliverables are also accessible via MCP tools
--- a/docs/SOP-output-evaluation.md
+++ b/docs/SOP-output-evaluation.md
@ -0,0 +1,189 @@
+# SOP: Agent Output Evaluation & Scoring
+
+Define scoring profiles and evaluate agent outputs for quality.
+
+---
+
+## Overview
+
+The Scoring Framework lets you define profiles with weighted criteria that evaluate agent outputs. Each evaluation runs the output through all scorers, combines scores using a composite method, and returns a per-scorer breakdown for diagnostics.
+
+**Scorer types:**
+
+| Type                | What it checks                                               |
+| ------------------- | ------------------------------------------------------------ |
+| `RegexMatch`        | Whether the output matches a regular expression              |
+| `KeywordContains`   | Whether the output contains required keywords                |
+| `NumericRange`      | Whether a numeric field in the output falls within a range   |
+| `CustomExpression`  | A custom evaluation expression                               |
+
+**Composite methods:**
+
+| Method          | Behavior                                              |
+| --------------- | ----------------------------------------------------- |
+| `weightedAvg`   | Weighted average of all scorer scores                 |
+| `minimum`       | Score is the lowest individual scorer score           |
+| `geometricMean` | Geometric mean — penalizes any single low scorer      |
+
+---
+
+## Prerequisites
+
+- VK server running (v4.0+)
+- Know what "good" looks like for the outputs you want to evaluate
+
+---
+
+## Step-by-Step Procedure
+
+### 1. Create a Scoring Profile
+
+```bash
+curl -X POST http://localhost:3001/api/scoring/profiles \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Task Summary Quality",
+    "description": "Evaluate quality of agent task completion summaries.",
+    "compositeMethod": "weightedAvg",
+    "scorers": [
+      {
+        "id": "has-action-items",
+        "name": "Contains action items",
+        "type": "KeywordContains",
+        "weight": 0.4,
+        "target": "output",
+        "keywords": ["completed", "implemented", "fixed", "added"],
+        "matchMode": "any",
+        "caseSensitive": false
+      },
+      {
+        "id": "length-check",
+        "name": "Summary length",
+        "type": "NumericRange",
+        "weight": 0.3,
+        "target": "output",
+        "valuePath": "length",
+        "min": 50,
+        "max": 500
+      },
+      {
+        "id": "no-apologies",
+        "name": "No apology language",
+        "type": "RegexMatch",
+        "weight": 0.3,
+        "target": "output",
+        "pattern": "I apologize|I\\'m sorry|unfortunately|I cannot",
+        "flags": "i",
+        "scoreOnMatch": 0,
+        "scoreOnMiss": 1,
+        "invert": false
+      }
+    ]
+  }'
+```
+
+**Response:** `201` with profile object including `id`.
+
+### 2. List Available Profiles
+
+```bash
+curl http://localhost:3001/api/scoring/profiles
+```
+
+### 3. Evaluate an Output
+
+```bash
+curl -X POST http://localhost:3001/api/scoring/evaluate \
+  -H "Content-Type: application/json" \
+  -d '{
+    "profileId": "prof_abc123",
+    "output": "Implemented the OAuth login feature using Passport.js. Added Google and GitHub providers. Tests pass.",
+    "action": "task-completion",
+    "agent": "TARS",
+    "taskId": "task_20260321_abc"
+  }'
+```
+
+**Response:**
+
+```json
+{
+  "id": "eval_xyz789",
+  "profileId": "prof_abc123",
+  "score": 0.87,
+  "passed": true,
+  "breakdown": [
+    { "scorerId": "has-action-items", "score": 1.0, "weight": 0.4, "weighted": 0.4 },
+    { "scorerId": "length-check", "score": 0.85, "weight": 0.3, "weighted": 0.255 },
+    { "scorerId": "no-apologies", "score": 1.0, "weight": 0.3, "weighted": 0.3 }
+  ],
+  "agent": "TARS",
+  "taskId": "task_20260321_abc",
+  "createdAt": "2026-03-21T14:00:00.000Z"
+}
+```
+
+### 4. Review Evaluation History
+
+```bash
+# All history
+curl http://localhost:3001/api/scoring/history
+
+# Filter by profile and agent
+curl "http://localhost:3001/api/scoring/history?profileId=prof_abc123&agent=TARS&limit=20"
+```
+
+### 5. Update a Profile
+
+```bash
+curl -X PUT http://localhost:3001/api/scoring/profiles/prof_abc123 \
+  -H "Content-Type: application/json" \
+  -d '{
+    "compositeMethod": "minimum"
+  }'
+```
+
+### 6. Delete a Profile
+
+Built-in profiles cannot be deleted.
+
+```bash
+curl -X DELETE http://localhost:3001/api/scoring/profiles/prof_abc123
+```
+
+**Response:** `204 No Content`.
+
+---
+
+## API Endpoints
+
+| Method   | Path                        | Description                          |
+| -------- | --------------------------- | ------------------------------------ |
+| `GET`    | `/api/scoring/profiles`     | List all scoring profiles            |
+| `POST`   | `/api/scoring/profiles`     | Create a scoring profile             |
+| `GET`    | `/api/scoring/profiles/:id` | Get a specific profile               |
+| `PUT`    | `/api/scoring/profiles/:id` | Update a profile                     |
+| `DELETE` | `/api/scoring/profiles/:id` | Delete a profile (non-built-in only) |
+| `POST`   | `/api/scoring/evaluate`     | Evaluate an output against a profile |
+| `GET`    | `/api/scoring/history`      | List evaluation history              |
+
+---
+
+## Common Issues
+
+**`Cannot delete built-in profile`:** Built-in profiles ship with VK and cannot be removed. Create a custom profile instead.
+
+**Score unexpectedly low:** Check the breakdown field in the evaluation response — it shows which scorer penalized the score.
+
+**`NumericRange` scorer always returns 0:** Ensure `valuePath` correctly addresses a numeric property of the output object. For string length, use `length`.
+
+**`KeywordContains` with `matchMode: "all"` is too strict:** Switch to `"any"` if you want partial credit, or use `partialCredit: true` to award fractional scores.
+
+---
+
+## Related Docs
+
+- [FEATURES.md — Output Evaluation](./FEATURES.md#agent-output-evaluation--scoring-framework)
+- [API-REFERENCE.md — Scoring](./API-REFERENCE.md#output-evaluation--scoring-apisc)
+- [SOP: Decision Audit Trail](./SOP-decision-audit-trail.md)
+- [SOP: Behavioral Drift Detection](./SOP-behavioral-drift-detection.md)
--- a/docs/SOP-prompt-registry.md
+++ b/docs/SOP-prompt-registry.md
@ -0,0 +1,204 @@
+# SOP: Prompt Template Registry
+
+Create, version, and manage prompt templates with variable injection.
+
+---
+
+## Overview
+
+The Prompt Template Registry provides a centralized store for prompt templates used by agents. Key capabilities:
+
+- Version history — every update creates a new version automatically
+- Variable extraction — `{{variable_name}}` syntax for dynamic injection
+- Usage tracking — record which model ran which template and with what token costs
+- Preview rendering — test variable injection before using in production
+
+**Template categories:** `system` · `agent` · `tool` · `evaluation`
+
+---
+
+## Prerequisites
+
+- VK server running (v4.0+)
+- Prompt content ready to store (use `{{variable}}` syntax for injection points)
+
+---
+
+## Step-by-Step Procedure
+
+### 1. Create a Template
+
+```bash
+curl -X POST http://localhost:3001/api/prompt-registry \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Task Completion Summary",
+    "description": "Generates a completion summary for a finished task.",
+    "category": "agent",
+    "content": "You completed task {{task_title}}. Write a 2-3 sentence summary of what was done. Acceptance criteria: {{acceptance_criteria}}. Agent: {{agent_name}}."
+  }'
+```
+
+**Response:** `201` with template object including `id`, `version` (starts at 1), and extracted `variables` list.
+
+### 2. List Templates
+
+```bash
+curl http://localhost:3001/api/prompt-registry
+```
+
+**Response:** Array of all templates with metadata but not full content (for performance).
+
+### 3. Get a Template
+
+```bash
+curl http://localhost:3001/api/prompt-registry/tmpl_abc123
+```
+
+**Response:** Full template with current content, version number, variables list, and metadata.
+
+### 4. Preview with Variables
+
+Test variable injection before using the template in production:
+
+```bash
+curl -X POST http://localhost:3001/api/prompt-registry/tmpl_abc123/render-preview \
+  -H "Content-Type: application/json" \
+  -d '{
+    "templateId": "tmpl_abc123",
+    "sampleVariables": {
+      "task_title": "Add OAuth login",
+      "acceptance_criteria": "Users can log in with Google and GitHub.",
+      "agent_name": "TARS"
+    }
+  }'
+```
+
+**Response:** `{ "rendered": "You completed task Add OAuth login. Write a 2-3 sentence summary..." }`
+
+### 5. Update a Template
+
+Every update automatically creates a new version:
+
+```bash
+curl -X PATCH http://localhost:3001/api/prompt-registry/tmpl_abc123 \
+  -H "Content-Type: application/json" \
+  -d '{
+    "content": "You completed task {{task_title}} (Task ID: {{task_id}}). Write a 2-3 sentence summary. Acceptance criteria: {{acceptance_criteria}}. Agent: {{agent_name}}.",
+    "changelog": "Added task_id variable for traceability"
+  }'
+```
+
+**Response:** Updated template with incremented `version` number.
+
+### 6. List Version History
+
+```bash
+curl http://localhost:3001/api/prompt-registry/tmpl_abc123/versions
+```
+
+**Response:** Array of version objects with `versionNumber`, `changelog`, and `createdAt`. Use this to identify which version to roll back to.
+
+### 7. Roll Back (by Pinning an Old Version)
+
+There's no automatic rollback endpoint — to use an older version, retrieve it from the versions list and create a new update with the old content:
+
+```bash
+# 1. Get the target version's content from the versions list
+curl http://localhost:3001/api/prompt-registry/tmpl_abc123/versions
+
+# 2. Update the template with the old content and note the rollback
+curl -X PATCH http://localhost:3001/api/prompt-registry/tmpl_abc123 \
+  -H "Content-Type: application/json" \
+  -d '{
+    "content": "<content from old version>",
+    "changelog": "Rolled back to v2 — v3 introduced regression in output quality"
+  }'
+```
+
+### 8. Record Usage
+
+After using a template, record the usage for analytics:
+
+```bash
+curl -X POST http://localhost:3001/api/prompt-registry/tmpl_abc123/record-usage \
+  -H "Content-Type: application/json" \
+  -d '{
+    "usedBy": "TARS",
+    "model": "anthropic/claude-sonnet-4-6",
+    "inputTokens": 320,
+    "outputTokens": 145,
+    "renderedPrompt": "You completed task Add OAuth login..."
+  }'
+```
+
+**Response:** `201` with usage record.
+
+### 9. View Usage History and Stats
+
+```bash
+# Usage history (last 50 uses)
+curl http://localhost:3001/api/prompt-registry/tmpl_abc123/usage
+
+# Stats summary
+curl http://localhost:3001/api/prompt-registry/tmpl_abc123/stats
+
+# Aggregate stats across all templates
+curl http://localhost:3001/api/prompt-registry/stats/all
+```
+
+### 10. Delete a Template
+
+```bash
+curl -X DELETE http://localhost:3001/api/prompt-registry/tmpl_abc123
+```
+
+**Response:** `204 No Content`.
+
+---
+
+## API Endpoints
+
+| Method   | Path                                         | Description                          |
+| -------- | -------------------------------------------- | ------------------------------------ |
+| `GET`    | `/api/prompt-registry`                       | List all templates                   |
+| `POST`   | `/api/prompt-registry`                       | Create a new template                |
+| `GET`    | `/api/prompt-registry/:id`                   | Get a template                       |
+| `PATCH`  | `/api/prompt-registry/:id`                   | Update a template (auto-versions)    |
+| `DELETE` | `/api/prompt-registry/:id`                   | Delete a template                    |
+| `GET`    | `/api/prompt-registry/:id/versions`          | List all versions of a template      |
+| `GET`    | `/api/prompt-registry/:id/usage`             | Get usage history                    |
+| `GET`    | `/api/prompt-registry/:id/stats`             | Get usage statistics                 |
+| `GET`    | `/api/prompt-registry/stats/all`             | Aggregate stats across all templates |
+| `POST`   | `/api/prompt-registry/:id/render-preview`    | Render a preview with variables      |
+| `POST`   | `/api/prompt-registry/:id/record-usage`      | Record a usage event                 |
+
+---
+
+## Template Schema
+
+| Field         | Type   | Required | Description                                              |
+| ------------- | ------ | -------- | -------------------------------------------------------- |
+| `name`        | string | ✅       | Template name                                            |
+| `description` | string | ❌       | What the template is for                                 |
+| `category`    | enum   | ✅       | `system`, `agent`, `tool`, or `evaluation`               |
+| `content`     | string | ✅       | Template body with `{{variable}}` placeholders           |
+| `changelog`   | string | ❌       | Description of changes (for update operations)           |
+
+---
+
+## Common Issues
+
+**Variables not being extracted:** Ensure you use `{{variable_name}}` double-brace syntax. Single braces or other formats won't be recognized.
+
+**Stats endpoint returns empty:** Stats are only populated after `record-usage` calls. The system does not auto-track usage — you must call `record-usage` explicitly.
+
+**Version history growing large:** Each `PATCH` creates a new version. This is by design — don't update for cosmetic reasons. Batch changes into single updates.
+
+---
+
+## Related Docs
+
+- [FEATURES.md — Prompt Template Registry](./FEATURES.md#prompt-template-registry-with-version-control)
+- [API-REFERENCE.md — Prompt Registry](./API-REFERENCE.md#prompt-template-registry-apiprompt-registry)
+- [SOP: Output Evaluation](./SOP-output-evaluation.md)
--- a/docs/SOP-squad-chat.md
+++ b/docs/SOP-squad-chat.md
@ -0,0 +1,166 @@
+# SOP: Squad Chat Usage & Protocol
+
+<!-- doc-freshness: 2026-03-21 | v4.0.0 | @tars -->
+
+## Purpose
+
+Squad chat is the real-time communication channel for agents and the orchestrator. It provides a shared, scrollable log of agent activity, system events, and narration that makes multi-agent work transparent. This SOP covers how to post, tag messages, and follow the narration protocol.
+
+## Prerequisites
+
+- Veritas Kanban server running (squad chat endpoint at `localhost:3001/api/chat/squad`)
+- Agent name and model name (required fields for every post)
+- For sub-agents without the `squad-post.sh` script: direct curl access
+
+## Concepts
+
+| Term | Definition |
+|------|------------|
+| **Squad chat** | Persistent message channel shared across all agents and the VK web UI |
+| **Agent** | Name of the posting agent (e.g., `VERITAS`, `TARS`, `CASE`) |
+| **Model** | The LLM powering the agent (e.g., `claude-sonnet-4-6`, `gpt-5.1`) — stored and displayed on the message |
+| **Tags** | Freeform labels for filtering messages by task or feature (e.g., `["docs-v4", "cleanup"]`) |
+| **System events** | Automated events (agent spawned, task completed) that the server pushes to squad chat |
+
+## Step-by-Step: Post to Squad Chat
+
+### Using squad-post.sh (preferred, main agent)
+
+```bash
+~/clawd/scripts/squad-post.sh VERITAS "Starting PR review for #229" docs-v4
+```
+
+Format: `squad-post.sh <AGENT> "<MESSAGE>" [TAG]`
+
+### Direct API call (sub-agents and cron jobs)
+
+```bash
+curl -s -X POST http://localhost:3001/api/chat/squad \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "agent": "TARS",
+    "message": "Step 3/7: CHANGELOG.md v4.0.0 entry written",
+    "model": "claude-sonnet-4-6",
+    "tags": ["docs-v4"]
+  }'
+```
+
+**Required fields:** `agent`, `message`, `model`  
+**Optional:** `tags` (array of strings)
+
+## The Narration Protocol (Mandatory)
+
+Squad chat is how multi-agent work stays visible. **Post at every major step** — not just at the start and end.
+
+### When to post
+
+| Trigger | Post |
+|---------|------|
+| Starting a multi-step task | `Starting [task title] — [N] steps`  |
+| Completing a major step | `Step N/Total: [what was done]` |
+| Encountering an error | `⚠️ Error on step N: [what failed and what I'm doing about it]` |
+| Completing the full task | `[Task title] complete — [brief summary of what changed]` |
+| Spawning a sub-agent | `Spawning [AgentName] for [subtask]` |
+| Sub-agent completes | `[AgentName] done: [result summary]` |
+
+### What makes a good squad post
+
+- **Specific, not generic.** "Step 3/7: CHANGELOG v4.0.0 entry written" beats "Making progress".
+- **Action + result.** What did you do, and what's the state now?
+- **No spam.** Don't post for every file write or minor substep. Batch related micro-actions.
+- **Flag blockers immediately.** Don't wait until the end to mention a problem.
+
+### What to skip
+
+- Trivial tool calls (reading a file, checking a variable)
+- Redundant confirmations ("Confirmed that the above worked")
+- Status-quo messages when nothing changed
+
+## Step-by-Step: Read Squad Chat
+
+### Via the web UI
+
+Open the Squad Chat panel in the VK dashboard — messages stream in real-time via WebSocket.
+
+### Via the API
+
+```bash
+# Recent 20 messages
+curl -s "http://localhost:3001/api/chat/squad?limit=20"
+
+# Filter by tag
+curl -s "http://localhost:3001/api/chat/squad?tag=docs-v4"
+
+# Filter by agent
+curl -s "http://localhost:3001/api/chat/squad?agent=TARS"
+
+# Messages since a timestamp
+curl -s "http://localhost:3001/api/chat/squad?since=2026-03-21T14:00:00Z"
+```
+
+## Step-by-Step: Tag Conventions
+
+Use consistent tags so messages are filterable by project or task:
+
+| Pattern | Example | Use For |
+|---------|---------|---------|
+| Project name | `rubicon` | All work on a specific project |
+| Task type | `docs-v4`, `security`, `cleanup` | Ongoing task category |
+| Sprint | `sprint-12` | Sprint-scoped work |
+| Feature | `policy-engine` | Specific feature work |
+| System | `health`, `drift`, `heartbeat` | Monitoring and system events |
+
+## Sub-Agent Template Block
+
+Every `sessions_spawn` task prompt must include this block so sub-agents can post to squad chat:
+
+```
+SQUAD CHAT (mandatory — post at every major step):
+curl -s -X POST http://localhost:3001/api/chat/squad \
+  -H 'Content-Type: application/json' \
+  -d '{"agent":"<AGENT_NAME>","message":"<STEP_DESCRIPTION>","model":"<MODEL_NAME>","tags":["<TASK_TAG>"]}'
+Post when: starting work, each major milestone, completion, and errors.
+The "model" field is REQUIRED — the server stores and displays it automatically.
+```
+
+## Heartbeat Protocol
+
+Every heartbeat must post start and end messages:
+
+```bash
+# Heartbeat start
+curl -s -X POST http://localhost:3001/api/chat/squad \
+  -H 'Content-Type: application/json' \
+  -d '{"agent":"VERITAS","message":"Heartbeat: checking email, calendar, drift alerts","model":"claude-sonnet-4-6","tags":["heartbeat"]}'
+
+# ... do the checks ...
+
+# Heartbeat end
+curl -s -X POST http://localhost:3001/api/chat/squad \
+  -H 'Content-Type: application/json' \
+  -d '{"agent":"VERITAS","message":"Heartbeat complete — 2 unread emails, Guide Energy meeting at 3pm, all drift ok","model":"claude-sonnet-4-6","tags":["heartbeat"]}'
+```
+
+## API Endpoints Used
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `POST` | `/api/chat/squad` | Post a message to squad chat |
+| `GET` | `/api/chat/squad` | List messages (filterable) |
+
+## Common Issues / Troubleshooting
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| `400` on POST | Missing required fields | Ensure `agent`, `message`, and `model` are all present |
+| Messages not appearing in UI | WebSocket disconnected | Refresh the browser; check that the VK server is running |
+| Squad chat panel scroll broken | Known issue (fixed in v4.0, PR #225) | Upgrade to v4.0.0+ if on an older version |
+| Sub-agent posts missing | Sub-agent prompt didn't include the squad chat block | Add the template block to every `sessions_spawn` prompt |
+| Model field blank in UI | `model` field omitted from POST body | Always include `"model": "<model-name>"` — it's required |
+
+## Related Docs
+
+- [docs/features/squad-chat.md](features/squad-chat.md) — Feature deep-dive
+- [docs/SQUAD-CHAT-PROTOCOL.md](SQUAD-CHAT-PROTOCOL.md) — Detailed narration rules and examples
+- [AGENTS.md — Squad Chat section](../AGENTS.md#squad-chat-narrate-your-own-work-mandatory) — Workspace-level narration rules
+- [SOP-agent-task-workflow.md](SOP-agent-task-workflow.md) — How squad chat fits into the full task workflow
--- a/docs/SOP-system-health-monitoring.md
+++ b/docs/SOP-system-health-monitoring.md
@ -0,0 +1,183 @@
+# SOP: System Health Monitoring
+
+Read system health indicators and respond to alerts.
+
+---
+
+## Overview
+
+The Global System Health API aggregates three signal streams into a single status response, displayed in real-time by the health status bar in the VK dashboard:
+
+| Signal       | What It Monitors                                     |
+| ------------ | ---------------------------------------------------- |
+| `system`     | Storage access, disk space (>100 MB free), memory    |
+| `agents`     | Agent registry — online, offline, total counts       |
+| `operations` | Run metrics — 24h success rate, failed runs          |
+
+**Overall status values (ordered by severity):**
+
+| Status      | Meaning                                                       |
+| ----------- | ------------------------------------------------------------- |
+| `stable`    | All signals OK                                                |
+| `reviewing` | One warning signal detected                                   |
+| `drifting`  | Two or more warnings, or at least one agent offline           |
+| `elevated`  | Any signal is `critical`                                      |
+| `alert`     | System storage failure, or operations success rate < 50%      |
+
+---
+
+## Prerequisites
+
+- VK server running (v4.0+)
+- No authentication required — this endpoint is public
+
+---
+
+## Step-by-Step Procedure
+
+### 1. Check System Health
+
+```bash
+curl http://localhost:3001/api/system/health
+```
+
+**Response:**
+
+```json
+{
+  "timestamp": "2026-03-21T14:00:00.000Z",
+  "status": "stable",
+  "signals": {
+    "system": {
+      "status": "ok",
+      "storage": true,
+      "disk": true,
+      "memory": true
+    },
+    "agents": {
+      "status": "ok",
+      "total": 3,
+      "online": 3,
+      "offline": 0
+    },
+    "operations": {
+      "status": "ok",
+      "recentRuns": 47,
+      "successRate": 96,
+      "failedRuns": 2
+    }
+  }
+}
+```
+
+### 2. Interpret the Status
+
+**`stable`:** No action needed.
+
+**`reviewing`:** Look at which signal is `warn`:
+- `system.memory: false` → heap usage >90% — monitor for leaks or restart if persistent
+- `operations.status: warn` → success rate 80–99% or >5 failed runs — check recent task failures
+
+**`drifting`:** Two signals are warning or agents are offline:
+- Check `agents.offline` count — confirm agents are expected to be offline
+- Run `GET /api/agents` to see which agents are offline and their last heartbeat
+
+**`elevated`:** A critical signal exists:
+- `agents.status: critical` → all agents offline — check agent processes
+- `operations.status: critical` → success rate <50% or massive failure count — check logs immediately
+
+**`alert`:** Immediate action required:
+- `system.storage: false` → data directory inaccessible — check filesystem permissions
+- `system.disk: false` → <100 MB disk free — clean up disk space immediately
+- `operations.successRate < 50` → more than half of recent runs failed — check server logs
+
+### 3. Diagnosing Agent Issues
+
+When `agents.status` is `warn` or `critical`:
+
+```bash
+# List all agents and their statuses
+curl http://localhost:3001/api/agents
+
+# Check the agent registry
+curl http://localhost:3001/api/agent/status
+```
+
+Look for agents with `status: offline` and a stale `lastHeartbeat` timestamp.
+
+### 4. Diagnosing Operations Issues
+
+When `operations.status` is `warn` or `critical`:
+
+```bash
+# Check recent run telemetry
+curl "http://localhost:3001/api/telemetry/events?type=run.completed&limit=20"
+
+# Look for failed runs
+curl "http://localhost:3001/api/telemetry/events?type=run.completed&success=false&limit=20"
+```
+
+Review the task IDs in failed runs to understand which work is failing.
+
+### 5. Polling for Status Changes
+
+For automated monitoring, poll the health endpoint and alert on status changes:
+
+```bash
+#!/bin/bash
+PREV_STATUS=""
+while true; do
+  STATUS=$(curl -s http://localhost:3001/api/system/health | jq -r '.status')
+  if [ "$STATUS" != "$PREV_STATUS" ] && [ "$STATUS" != "stable" ]; then
+    echo "ALERT: System status changed to $STATUS"
+    # trigger your notification here
+  fi
+  PREV_STATUS=$STATUS
+  sleep 60
+done
+```
+
+---
+
+## API Endpoints
+
+| Method | Path                  | Description                          |
+| ------ | --------------------- | ------------------------------------ |
+| `GET`  | `/api/system/health`  | Get aggregated system health status  |
+
+---
+
+## Status Escalation Logic
+
+```
+All OK → stable
+1 warning → reviewing
+2+ warnings OR any agent offline → drifting
+Any critical signal → elevated
+System storage fail OR successRate < 50% → alert
+```
+
+Thresholds (hardcoded in v4.0):
+- **Memory warn:** heap used > 90%
+- **Disk fail:** free space < 100 MB
+- **Operations warn:** success rate 80–99%, or failedRuns > 5
+- **Operations critical:** success rate < 50%
+
+---
+
+## Common Issues
+
+**Status shows `elevated` with all agents appearing online:** Check the operations signal — `status: critical` also triggers `elevated`. The agent registry shows registered agents, not process health.
+
+**`system.disk: false` immediately after startup:** The data directory path may be wrong. Check the `DATA_DIR` environment variable — it should point to the `.veritas-kanban` data directory.
+
+**Health endpoint returns 500:** The metrics service or agent registry service failed to initialize. Check the server startup logs.
+
+---
+
+## Related Docs
+
+- [FEATURES.md — System Health Status Bar](./FEATURES.md#global-system-health-status-bar)
+- [API-REFERENCE.md — System Health](./API-REFERENCE.md#system-health-apisystemhealth)
+- [SOP: Behavioral Drift Detection](./SOP-behavioral-drift-detection.md)
+- [SOP: Output Evaluation](./SOP-output-evaluation.md)
--- a/docs/SOP-user-feedback.md
+++ b/docs/SOP-user-feedback.md
@ -0,0 +1,189 @@
+# SOP: User Feedback Loop with Sentiment Analytics
+
+Collect agent output feedback, analyze sentiment, and act on results.
+
+---
+
+## Overview
+
+The User Feedback system captures ratings and comments on agent work, automatically infers sentiment, and provides an analytics API for trend analysis. Feedback is categorized and can be marked resolved to track follow-up.
+
+**Categories:** `quality` · `performance` · `accuracy` · `safety` · `ux`
+
+**Sentiment (auto-inferred from rating):** `positive` (4–5) · `neutral` (3) · `negative` (1–2)
+
+**Rating scale:** 1 (worst) → 5 (best)
+
+---
+
+## Prerequisites
+
+- VK server running (v4.0+)
+- Tasks exist in the system that feedback can be attached to
+
+---
+
+## Step-by-Step Procedure
+
+### 1. Submit Feedback
+
+Call this immediately after reviewing agent output:
+
+```bash
+curl -X POST http://localhost:3001/api/feedback \
+  -H "Content-Type: application/json" \
+  -d '{
+    "taskId": "task_20260321_abc",
+    "agent": "TARS",
+    "rating": 4,
+    "comment": "Output was accurate and well-structured. Could be more concise.",
+    "categories": ["quality", "accuracy"]
+  }'
+```
+
+**Response:** `201` with feedback object including `id` and auto-inferred `sentiment` (`positive`).
+
+### 2. List Feedback
+
+```bash
+# All feedback
+curl http://localhost:3001/api/feedback
+
+# Filter by agent, category, and sentiment
+curl "http://localhost:3001/api/feedback?agent=TARS&sentiment=negative&limit=20"
+
+# Filter by task
+curl "http://localhost:3001/api/feedback?taskId=task_20260321_abc"
+
+# Unresolved only
+curl "http://localhost:3001/api/feedback?resolved=false"
+```
+
+### 3. View the Unresolved Queue
+
+The unresolved queue is your action backlog — feedback that needs follow-up:
+
+```bash
+curl http://localhost:3001/api/feedback/unresolved
+```
+
+**Response:** Array of feedback items sorted by age (oldest first), limited to 100 by default.
+
+### 4. Get Analytics
+
+Understand patterns across your feedback data:
+
+```bash
+# Overall analytics
+curl http://localhost:3001/api/feedback/analytics
+
+# Analytics for a specific agent
+curl "http://localhost:3001/api/feedback/analytics?agent=TARS"
+
+# Analytics for a specific time window
+curl "http://localhost:3001/api/feedback/analytics?since=2026-03-01T00:00:00Z&until=2026-03-21T23:59:59Z"
+```
+
+**Response:**
+
+```json
+{
+  "totalCount": 142,
+  "averageRating": 3.8,
+  "sentimentBreakdown": {
+    "positive": 89,
+    "neutral": 32,
+    "negative": 21
+  },
+  "categoryBreakdown": {
+    "quality": 67,
+    "accuracy": 54,
+    "performance": 21,
+    "safety": 0,
+    "ux": 0
+  },
+  "unresolvedCount": 8,
+  "trend": "improving"
+}
+```
+
+### 5. Mark Feedback Resolved
+
+After acting on feedback, mark it resolved to remove it from the unresolved queue:
+
+```bash
+curl -X PUT http://localhost:3001/api/feedback/fb_abc123 \
+  -H "Content-Type: application/json" \
+  -d '{
+    "resolved": true
+  }'
+```
+
+### 6. Update Feedback
+
+If feedback needs correction:
+
+```bash
+curl -X PUT http://localhost:3001/api/feedback/fb_abc123 \
+  -H "Content-Type: application/json" \
+  -d '{
+    "rating": 3,
+    "comment": "Updated after re-reviewing the output — conciseness was fine, accuracy was the issue.",
+    "categories": ["accuracy"]
+  }'
+```
+
+### 7. Delete Feedback
+
+```bash
+curl -X DELETE http://localhost:3001/api/feedback/fb_abc123
+```
+
+**Response:** `204 No Content`.
+
+---
+
+## API Endpoints
+
+| Method   | Path                         | Description                                   |
+| -------- | ---------------------------- | --------------------------------------------- |
+| `GET`    | `/api/feedback`              | List feedback (filterable)                    |
+| `POST`   | `/api/feedback`              | Submit new feedback                           |
+| `GET`    | `/api/feedback/analytics`    | Get analytics and sentiment breakdown         |
+| `GET`    | `/api/feedback/unresolved`   | List unresolved feedback items                |
+| `GET`    | `/api/feedback/:id`          | Get a specific feedback item                  |
+| `PUT`    | `/api/feedback/:id`          | Update feedback (rating, comment, resolved)   |
+| `DELETE` | `/api/feedback/:id`          | Delete a feedback item                        |
+
+---
+
+## Query Parameters (List)
+
+| Param       | Type    | Description                                       |
+| ----------- | ------- | ------------------------------------------------- |
+| `taskId`    | string  | Filter by task ID                                 |
+| `agent`     | string  | Filter by agent name                              |
+| `category`  | string  | `quality`, `performance`, `accuracy`, `safety`, `ux` |
+| `sentiment` | string  | `positive`, `neutral`, `negative`                 |
+| `resolved`  | boolean | Filter by resolved status                         |
+| `since`     | string  | ISO 8601 — feedback submitted after this date     |
+| `until`     | string  | ISO 8601 — feedback submitted before this date    |
+| `limit`     | number  | Max records (default: 50)                         |
+
+---
+
+## Common Issues
+
+**Sentiment looks wrong for a rating:** Sentiment is inferred from rating: 1–2 = `negative`, 3 = `neutral`, 4–5 = `positive`. Updating the rating will update the sentiment.
+
+**Unresolved queue not clearing:** Feedback is resolved explicitly via `PUT /:id` with `{ "resolved": true }` — it doesn't auto-resolve.
+
+**Analytics showing stale data:** Analytics are computed on-demand from the full dataset. If you recently deleted or updated feedback, re-query for fresh results.
+
+---
+
+## Related Docs
+
+- [FEATURES.md — User Feedback Loop](./FEATURES.md#user-feedback-loop-with-sentiment-analytics)
+- [API-REFERENCE.md — Feedback](./API-REFERENCE.md#user-feedback-apifeedback)
+- [SOP: Output Evaluation](./SOP-output-evaluation.md)
--- a/docs/archive/BASE-UI-VS-RADIX.md
+++ b/docs/archive/BASE-UI-VS-RADIX.md
--- a/docs/archive/DOCS-AUDIT-2026-03-02.md
+++ b/docs/archive/DOCS-AUDIT-2026-03-02.md
--- a/docs/archive/SHADCN-V4.md
+++ b/docs/archive/SHADCN-V4.md
--- a/docs/archive/design-parallel-visualization.md
+++ b/docs/archive/design-parallel-visualization.md
--- a/docs/mcp/README.md
+++ b/docs/mcp/README.md
@ -489,7 +489,131 @@ When a sprint is referenced by one or more tasks (i.e., tasks have `sprint: "spr

 The reference check is **skipped entirely**. The sprint is deleted regardless of how many tasks reference it. Tasks that referenced the deleted sprint will retain their `sprint` field value, but it will point to a non-existent sprint (orphaned reference). This is useful for cleanup scenarios where you know the references are stale or the tasks will be updated separately.

-**This applies to all managed lists** (sprints, projects, task-types) — they all use the same `ManagedListService` base class with identical force delete semantics. The MCP server currently only exposes sprint management tools, but the server REST API supports force delete on `/api/projects/:id?force=true` and `/api/task-types/:id?force=true` as well.
+**This applies to all managed lists** (sprints, projects, task-types) — they all use the same `ManagedListService` base class with identical force delete semantics. The MCP server supports force delete on `/api/projects/:id?force=true` and `/api/task-types/:id?force=true` as well.
+
+---
+
+### Project Management (7 tools) <small>_New in v4.0_</small>
+
+Full project lifecycle management from MCP — create, organize, and track projects without leaving your agent context.
+
+| Tool                  | Description                          | Required Inputs | Key Options                  |
+| --------------------- | ------------------------------------ | --------------- | ---------------------------- |
+| `list_projects`       | List all projects                    | _(none)_        | `includeHidden`              |
+| `get_project`         | Get a project by ID                  | `id`            | —                            |
+| `create_project`      | Create a new project                 | `label`         | `description`, `color`       |
+| `update_project`      | Update project fields                | `id`            | `label`, `description`, `isHidden` |
+| `delete_project`      | Delete a project                     | `id`            | `force`                      |
+| `get_project_stats`   | Task counts and status breakdown     | `id`            | —                            |
+| `reorder_projects`    | Reorder projects in the sidebar      | `orderedIds`    | —                            |
+
+<details>
+<summary><strong>Examples</strong></summary>
+
+**Create a project:**
+
+```json
+{
+  "name": "create_project",
+  "arguments": { "label": "Rubicon", "description": "Industrial safety AI platform", "color": "#8B5CF6" }
+}
+```
+
+**Get project task breakdown:**
+
+```json
+{
+  "name": "get_project_stats",
+  "arguments": { "id": "rubicon" }
+}
+```
+
+→ Returns:
+
+```json
+{
+  "id": "rubicon",
+  "label": "Rubicon",
+  "total": 24,
+  "byStatus": { "todo": 8, "in-progress": 5, "blocked": 2, "done": 9 }
+}
+```
+
+**Reorder projects:**
+
+```json
+{
+  "name": "reorder_projects",
+  "arguments": { "orderedIds": ["rubicon", "brainmeld", "dealmeld"] }
+}
+```
+
+**Force-delete a project with tasks still assigned:**
+
+```json
+{
+  "name": "delete_project",
+  "arguments": { "id": "old-project", "force": true }
+}
+```
+
+</details>
+
+---
+
+### Comment Management (5 tools) <small>_New in v4.0_</small>
+
+Full CRUD for task and sprint comments, enabling agents to participate in async review threads.
+
+| Tool             | Description              | Required Inputs             | Key Options  |
+| ---------------- | ------------------------ | --------------------------- | ------------ |
+| `add_comment`    | Add a comment to a task  | `taskId`, `content`         | `author`     |
+| `list_comments`  | List comments for a task | `taskId`                    | `limit`      |
+| `get_comment`    | Get a single comment     | `taskId`, `commentId`       | —            |
+| `update_comment` | Edit a comment           | `taskId`, `commentId`, `content` | —       |
+| `delete_comment` | Delete a comment         | `taskId`, `commentId`       | —            |
+
+<details>
+<summary><strong>Examples</strong></summary>
+
+**Add a code review comment:**
+
+```json
+{
+  "name": "add_comment",
+  "arguments": {
+    "taskId": "task_20260321_abc",
+    "content": "Auth token refresh looks good. One nit: the 5-minute buffer could be configurable.",
+    "author": "TARS"
+  }
+}
+```
+
+**List comments on a task:**
+
+```json
+{
+  "name": "list_comments",
+  "arguments": { "taskId": "task_20260321_abc" }
+}
+```
+
+→ Returns array of `{ id, content, author, createdAt, updatedAt }`.
+
+**Update a comment:**
+
+```json
+{
+  "name": "update_comment",
+  "arguments": {
+    "taskId": "task_20260321_abc",
+    "commentId": "cmt_xyz789",
+    "content": "Auth token refresh looks good — marking as approved."
+  }
+}
+```
+
+</details>

 ---

@ -594,7 +718,7 @@ Configure telemetry retention in `server/.env`:

 | Component          | Version      | Notes                       |
 | ------------------ | ------------ | --------------------------- |
-| MCP server package | `3.3.3`      | Matches VK server version   |
+| MCP server package | `4.0.0`      | Matches VK server version   |
 | MCP SDK            | `1.27.1`     | `@modelcontextprotocol/sdk` |
 | MCP protocol       | `2024-11-05` | Latest stable spec          |
 | Node.js            | `≥ 18`       | ES modules required         |
@ -638,4 +762,4 @@ The `findTask` utility matches the last N characters of a task ID (minimum 6). I

 ---

-_Last updated: 2026-03-02 · VK v3.3.3 · 26 tools / 6 categories_
+_Last updated: 2026-03-21 · VK v4.0.0 · 33 tools / 7 categories_
--- a/mcp/package.json
+++ b/mcp/package.json
@ -1,6 +1,6 @@
 {
  "name": "@veritas-kanban/mcp",
-  "version": "3.3.3",
+  "version": "4.0.0",
  "description": "MCP server for Veritas Kanban",
  "type": "module",
  "main": "./dist/index.js",
--- a/package.json
+++ b/package.json
@ -1,6 +1,6 @@
 {
  "name": "veritas-kanban",
-  "version": "3.3.3",
+  "version": "4.0.0",
  "private": true,
  "description": "Local-first task management and AI agent orchestration platform",
  "author": "Brad Groux <brad@digitalmeld.io>",
--- a/server/package.json
+++ b/server/package.json
@ -1,6 +1,6 @@
 {
  "name": "@veritas-kanban/server",
-  "version": "3.3.3",
+  "version": "4.0.0",
  "private": true,
  "type": "module",
  "main": "./dist/index.js",
--- a/server/src/routes/v1/index.ts
+++ b/server/src/routes/v1/index.ts
@ -79,6 +79,8 @@ import { systemHealthRouter } from '../system-health.js';
 import { transcriptRoutes } from '../transcripts.js';
 import { decisionRoutes } from '../decisions.js';
 import { scoringRoutes } from '../scoring.js';
+import { feedbackRoutes } from '../feedback.js';
+import promptRegistryRoutes from '../prompt-registry.js';

 const v1Router: IRouter = Router();

@ -173,5 +175,7 @@ v1Router.use('/transcripts', transcriptRoutes);
 v1Router.use('/scoring', scoringRoutes);
 v1Router.use('/system/health', systemHealthRouter);
 v1Router.use('/decisions', decisionRoutes);
+v1Router.use('/feedback', feedbackRoutes);
+v1Router.use('/prompt-registry', promptRegistryRoutes);

 export { v1Router };
--- a/shared/package.json
+++ b/shared/package.json
@ -1,6 +1,6 @@
 {
  "name": "@veritas-kanban/shared",
-  "version": "3.3.3",
+  "version": "4.0.0",
  "private": true,
  "type": "module",
  "main": "./dist/index.js",
--- a/web/package.json
+++ b/web/package.json
@ -1,6 +1,6 @@
 {
  "name": "@veritas-kanban/web",
-  "version": "3.3.3",
+  "version": "4.0.0",
  "private": true,
  "type": "module",
  "scripts": {