chore: merge main into develop — YAML governance, strict validation, duplicate REQ cleanup

Brings develop in sync with all main-branch changes from the arch/req/test
alignment sprint, glossa-lab AI port, and YAML-native governance migration.

Co-Authored-By: Oz <oz-agent@warp.dev>

# Conflicts:
#	.specsmith/testcases.json
#	docs/REQUIREMENTS.md
#	docs/TESTS.md
#	tests/fixtures/api_surface.json
#	tests/test_ai_intelligence.py

Author: tbitcs

.github/workflows/ci.yml

@@ -87,6 +87,23 @@ jobs:
           SPECSMITH_PYPI_CHECKED: "1"
         run: python -m specsmith sync --check --project-dir .
 
+  validate-strict:
+    # YAML governance schema guard: duplicate IDs, orphan tests, missing fields.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev]"
+      - name: Strict governance schema validation
+        env:
+          SPECSMITH_NO_AUTO_UPDATE: "1"
+          SPECSMITH_PYPI_CHECKED: "1"
+        run: python -m specsmith validate --strict --json --project-dir .
+
   api-surface:
     # REQ-140 guard: regenerates the public CLI surface and fails the build
     # if the live output drifts from the committed fixture. Catches accidental

.specsmith/governance-mode

@@ -0,0 +1 @@
+yaml

.specsmith/requirements.json

@@ -1532,167 +1532,6 @@
     "source": "BTWS-2027 AI Governance Report [REG-015]",
     "status": "defined"
   },
-  {
-    "id": "REQ-221",
-    "title": "Instinct Persistence System",
-    "description": "specsmith MUST implement an instinct persistence system in src/specsmith/instinct.py storing patterns extracted from successful sessions.",
-    "source": "PLANNED-REQUIREMENTS.md [LRN-001]",
-    "status": "defined"
-  },
-  {
-    "id": "REQ-222",
-    "title": "Instinct Record Schema",
-    "description": "Each instinct record MUST contain: id, trigger_pattern, content, confidence, project_scope, created, last_used, use_count.",
-    "source": "PLANNED-REQUIREMENTS.md [LRN-002]",
-    "status": "defined"
-  },
-  {
-    "id": "REQ-223",
-    "title": "Session End Instinct Extraction",
-    "description": "The SESSION_END hook MUST extract candidate instincts from session history for user review before the session closes.",
-    "source": "PLANNED-REQUIREMENTS.md [LRN-003]",
-    "status": "defined"
-  },
-  {
-    "id": "REQ-224",
-    "title": "Learn Command",
-    "description": "The /learn command MUST promote a user-approved pattern to an instinct with an initial confidence score and persist it to the instinct store.",
-    "source": "PLANNED-REQUIREMENTS.md [LRN-004]",
-    "status": "defined"
-  },
-  {
-    "id": "REQ-225",
-    "title": "Instinct Confidence Updates",
-    "description": "Instinct confidence MUST be updated based on application success or rejection — increasing on accepted application and decreasing on rejection.",
-    "source": "PLANNED-REQUIREMENTS.md [LRN-005]",
-    "status": "defined"
-  },
-  {
-    "id": "REQ-226",
-    "title": "Instinct Import Export",
-    "description": "Instincts MUST be importable and exportable as .md files for cross-project and cross-team sharing.",
-    "source": "PLANNED-REQUIREMENTS.md [LRN-006]",
-    "status": "defined"
-  },
-  {
-    "id": "REQ-227",
-    "title": "Instinct Status Command",
-    "description": "/instinct-status MUST display all active instincts sorted by confidence descending, with use_count and last_used fields.",
-    "source": "PLANNED-REQUIREMENTS.md [LRN-007]",
-    "status": "defined"
-  },
-  {
-    "id": "REQ-228",
-    "title": "Eval Harness Module",
-    "description": "specsmith MUST implement an eval harness in src/specsmith/eval/ supporting eval-driven development workflows.",
-    "source": "PLANNED-REQUIREMENTS.md [EDD-001]",
-    "status": "defined"
-  },
-  {
-    "id": "REQ-229",
-    "title": "Eval Data Model",
-    "description": "The eval model MUST define: Task, Trial, Grader, Transcript, Outcome as core types.",
-    "source": "PLANNED-REQUIREMENTS.md [EDD-002]",
-    "status": "defined"
-  },
-  {
-    "id": "REQ-230",
-    "title": "Eval Task Storage",
-    "description": "Tasks MUST be stored as Markdown files at .specsmith/evals/{feature}.md with YAML frontmatter.",
-    "source": "PLANNED-REQUIREMENTS.md [EDD-003]",
-    "status": "defined"
-  },
-  {
-    "id": "REQ-231",
-    "title": "Eval Grader Types",
-    "description": "The eval harness MUST support CodeGrader, ModelGrader, and HumanFlag grader types for different validation strategies.",
-    "source": "PLANNED-REQUIREMENTS.md [EDD-004]",
-    "status": "defined"
-  },
-  {
-    "id": "REQ-232",
-    "title": "Eval Pass at K Metrics",
-    "description": "The eval harness MUST compute pass@k and pass^k metrics for measuring agent capability across multiple trials.",
-    "source": "PLANNED-REQUIREMENTS.md [EDD-005]",
-    "status": "defined"
-  },
-  {
-    "id": "REQ-233",
-    "title": "Git-Based Eval Grading",
-    "description": "Default grading MUST be git-based outcome grading (checking actual changes in VCS) rather than execution-path assertion.",
-    "source": "PLANNED-REQUIREMENTS.md [EDD-006]",
-    "status": "defined"
-  },
-  {
-    "id": "REQ-234",
-    "title": "Eval Run Command",
-    "description": "/eval run --trials k MUST run k independent trials and report pass@k results with per-trial transcripts.",
-    "source": "PLANNED-REQUIREMENTS.md [EDD-007]",
-    "status": "defined"
-  },
-  {
-    "id": "REQ-235",
-    "title": "Capability vs Regression Evals",
-    "description": "The eval harness MUST distinguish capability evals (new functionality) from regression evals (existing functionality preservation).",
-    "source": "PLANNED-REQUIREMENTS.md [EDD-008]",
-    "status": "defined"
-  },
-  {
-    "id": "REQ-236",
-    "title": "Agent Memory Module",
-    "description": "specsmith MUST implement cross-session agent memory in src/specsmith/memory.py persisting patterns, facts, and history across sessions.",
-    "source": "PLANNED-REQUIREMENTS.md [MEM-001]",
-    "status": "defined"
-  },
-  {
-    "id": "REQ-237",
-    "title": "Agent Memory Schema",
-    "description": "Agent memory MUST be structured JSON containing: accumulated patterns, preferred approaches, known project facts, and failure history.",
-    "source": "PLANNED-REQUIREMENTS.md [MEM-002]",
-    "status": "defined"
-  },
-  {
-    "id": "REQ-238",
-    "title": "Session Start Memory Injection",
-    "description": "The SESSION_START hook MUST inject relevant memories into the system prompt, respecting the configured token budget to avoid context overrun.",
-    "source": "PLANNED-REQUIREMENTS.md [MEM-003]",
-    "status": "defined"
-  },
-  {
-    "id": "REQ-239",
-    "title": "Typed Execution Layer",
-    "description": "All tool handlers MUST use a typed ProjectOperations class for file, git/VCS, and search operations. Direct raw shell string assembly in tool handlers is prohibited.",
-    "source": "PLANNED-REQUIREMENTS.md [OPS-001]",
-    "status": "defined"
-  },
-  {
-    "id": "REQ-240",
-    "title": "ProjectOperations File Interface",
-    "description": "ProjectOperations MUST expose file operations (read_file, write_file, list_dir, glob, search) implemented via Python pathlib/stdlib with no subprocess calls.",
-    "source": "PLANNED-REQUIREMENTS.md [OPS-002]",
-    "status": "defined"
-  },
-  {
-    "id": "REQ-241",
-    "title": "ProjectOperations VCS Interface",
-    "description": "ProjectOperations MUST expose git/VCS operations (status, log, diff, add, commit, push, create_branch, create_pr) returning structured typed result objects.",
-    "source": "PLANNED-REQUIREMENTS.md [OPS-003]",
-    "status": "defined"
-  },
-  {
-    "id": "REQ-242",
-    "title": "ProjectOperations Result Schema",
-    "description": "All ProjectOperations methods MUST return a typed result containing at minimum: exit_code, stdout, stderr, and elapsed_ms.",
-    "source": "PLANNED-REQUIREMENTS.md [OPS-004]",
-    "status": "defined"
-  },
-  {
-    "id": "REQ-243",
-    "title": "Cross-Platform ProjectOperations",
-    "description": "ProjectOperations MUST be cross-platform (Windows, Linux, macOS) without platform-specific code branches at call sites.",
-    "source": "PLANNED-REQUIREMENTS.md [OPS-006]",
-    "status": "defined"
-  },
   {
     "id": "REQ-244",
     "title": "GPU-Aware Context Window Sizing",

.specsmith/testcases.json

@@ -2836,5 +2836,27 @@
     "input": {},
     "expected_behavior": {},
     "confidence": 1.0
+  },
+  {
+    "id": "TEST-282",
+    "title": "HF Leaderboard Sync Persists Bucket Scores to JSON",
+    "description": "`sync_from_huggingface_blocking(force_static=True, scores_path=tmp_path/\"scores.json\")` creates the file at the given path, whose JSON root contains a `\"bucket_scores\"` dict. Each entry has `reasoning_score`, `conversational_score`, `longform_score`, and `model_name` keys.",
+    "requirement_id": "REQ-263",
+    "type": "unit",
+    "verification_method": "pytest",
+    "input": {},
+    "expected_behavior": {},
+    "confidence": 1.0
+  },
+  {
+    "id": "TEST-283",
+    "title": "HF Token Included in Request Headers When Set",
+    "description": "When `SPECSMITH_HF_TOKEN` is set to a non-empty string, `test_hf_connection()` returns `{\"token_set\": true}` and the rate_limit_tier includes \"authenticated\". The `_fetch_page` request (captured via mock) includes `Authorization: Bearer <token>` in its headers.",
+    "requirement_id": "REQ-265",
+    "type": "unit",
+    "verification_method": "pytest",
+    "input": {},
+    "expected_behavior": {},
+    "confidence": 1.0
   }
 ]

README.md

@@ -477,6 +477,92 @@ requirement, test, and work-item identifiers Specsmith assigned.
 
 ---
 
+## AI Model Intelligence
+
+specsmith ships a complete AI model intelligence layer for tracking, scoring, and routing
+to the best available LLM for each task type.
+
+### HF Open LLM Leaderboard Sync (REQ-263..REQ-269)
+
+Syncs benchmark data from the HuggingFace Open LLM Leaderboard and computes three
+task-specific bucket scores — **reasoning**, **conversational**, and **longform** — for
+every model. A 40+ model static fallback ensures scores are always available even without
+network access.
+
+```bash
+specsmith model-intel sync                  # sync from HF leaderboard (static fallback if offline)
+specsmith model-intel scores                # list all cached bucket scores
+specsmith model-intel scores --model gpt-4o # show scores for a specific model
+specsmith model-intel recommendations       # top-10 models for reasoning bucket
+specsmith model-intel recommendations --bucket conversational  # or longform
+specsmith model-intel connection            # test HF API connectivity + token status
+```
+
+Set `SPECSMITH_HF_TOKEN` for authenticated access (1000 req/5min instead of 500).
+Scores persist to `~/.specsmith/model_scores.json`. Background sync runs 15s after startup
+then daily.
+
+**Bucket formulas (normalised 0-100):**
+- Reasoning = 0.35×MATH + 0.30×GPQA + 0.25×BBH + 0.10×IFEval
+- Conversational = 0.40×IFEval + 0.35×MMLU-PRO + 0.25×BBH
+- Longform = 0.35×MUSR + 0.35×IFEval + 0.30×MMLU-PRO
+
+### Model Capability Profiles (REQ-270..REQ-271)
+
+40+ pre-built model profiles cover all major providers (OpenAI, Anthropic, Google, Mistral,
+Meta Llama, Qwen, DeepSeek, and local Ollama variants). Each profile specifies:
+`max_tokens`, `prompt_style` (sections/xml/markdown), `supports_vision`,
+`supports_tool_calls`, `reasoning_mode`, and `context_window`.
+
+Context-aware history trimming preserves system messages while summarising older turns when
+the token budget is exceeded:
+
+```python
+from specsmith.agent.model_profiles import get_profile, trim_history
+
+profile = get_profile("qwen2.5:14b")   # exact or prefix match; returns default if unknown
+messages = trim_history(messages, budget_chars=12000)
+```
+
+### LLM Client with Provider Fallback (REQ-275..REQ-277)
+
+`LLMClient` wraps multiple providers with automatic fallback on 429 / 401 errors,
+O-series parameter translation (`max_completion_tokens`, temperature=1, developer role),
+and vLLM guided-JSON payload injection:
+
+```python
+from specsmith.agent.llm_client import LLMClient
+
+client = LLMClient([
+    {"provider_type": "cloud", "model": "gpt-4o", ...},
+    {"provider_type": "ollama", "model": "qwen2.5:14b", ...},  # local fallback
+])
+result = client.chat([{"role": "user", "content": "hello"}])
+```
+
+### Endpoint Presets + Suggest Profiles (REQ-278..REQ-280)
+
+A registry of 10+ pre-configured endpoint presets for common cloud and local LLM providers:
+
+```bash
+specsmith agent endpoint-presets            # list all presets (vllm, lm_studio, openrouter, etc.)
+specsmith agent endpoint-presets --json     # machine-readable output
+specsmith agent suggest-profiles            # suggest optimal profiles based on env (API keys, hardware)
+specsmith agent suggest-profiles --json     # structured suggestions with bucket/role annotations
+```
+
+Suggestions are read-only (never persisted) and inspect `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`,
+`GOOGLE_API_KEY`, and local Ollama availability.
+
+### Kairos AI Providers — Bucket Score Columns (REQ-281)
+
+The Kairos **Agents > AI Providers** table gained three new columns — **R** (reasoning),
+**C** (conversational), **L** (longform) — showing each provider's HF bucket scores inline.
+A **Sync Scores** button triggers a background sync from the HF leaderboard without
+interrupting the active session.
+
+---
+
 ## Kairos — Flagship Terminal Client
 
 **[Kairos](https://github.com/BitConcepts/kairos)** is the recommended terminal client for specsmith.
@@ -556,7 +642,9 @@ Supported tools: **Synthesis:** vivado, quartus, radiant, diamond, gowin.
 
 **Workflow:** `phase show/set/next/list` `ledger add/list` `req list/add/gaps/trace`
 
-**Agent:** `run` `agent run/plan/status/verify/improve/reports` `agent providers/tools/skills`
+**Agent:** `run` `agent run/plan/status/verify/improve/reports` `agent providers/tools/skills` `agent suggest-profiles` `agent endpoint-presets`
+
+**Model Intel:** `model-intel sync` `model-intel scores` `model-intel recommendations` `model-intel connection`
 
 **Ollama:** `ollama list/available/gpu/pull/suggest`
 

docs/LEDGER.md

@@ -122,3 +122,21 @@
 - **REQs affected**: REQ-248,REQ-249,REQ-250,REQ-251,REQ-252,REQ-253,REQ-254,REQ-255,REQ-256,REQ-257,REQ-258,REQ-259,REQ-260,REQ-261,REQ-262
 - **Status**: complete
 - **Chain hash**: auto
+
+
+## 2026-05-12T13:00 --- WI-0512-AI: Glossa-lab AI patterns ported to specsmith (REQ-263..REQ-281)
+- **Author**: oz-agent
+- **Type**: feature
+- **REQs affected**: REQ-263,REQ-264,REQ-265,REQ-266,REQ-267,REQ-268,REQ-269,REQ-270,REQ-271,REQ-272,REQ-273,REQ-274,REQ-275,REQ-276,REQ-277,REQ-278,REQ-279,REQ-280,REQ-281
+- **Description**: Ported 7 AI intelligence systems from glossa-lab: HF Open LLM Leaderboard sync with paginated fetch, bucket scoring (reasoning/conversational/longform), static fallback, and CLI (`model-intel scores/sync/recommendations/connection`); 40+ model capability profiles with context-aware history trimming; LLMClient with O-series parameter translation, vLLM guided-JSON, and provider fallback; EMA-based rate limit scheduler with adaptive concurrency; endpoint preset registry (10+ presets) with `/api/model-intel/*` REST endpoints; `agent suggest-profiles` and `agent endpoint-presets` CLI commands; Kairos AI Providers page bucket score columns and Sync Scores button. ARCHITECTURE.md §21-27 added. 280 REQs, 258 TESTs. All CI green.
+- **Status**: complete
+- **Chain hash**: auto
+
+
+## 2026-05-12T13:06 --- WI-0512-GAPS: Arch/req/test gap audit + TEST-282/TEST-283 added (REQ-263, REQ-265)
+- **Author**: oz-agent
+- **Type**: test
+- **REQs affected**: REQ-263,REQ-265
+- **Description**: Audit revealed REQ-263 (HF paginated sync persists bucket scores) and REQ-265 (HF API token in Authorization header) lacked explicit pytest coverage. Added TEST-282 (`TestHFSyncPersistsBucketScores` — verifies scores.json created with bucket_scores dict and all required keys per entry) and TEST-283 (`TestHFTokenInHeaders` — verifies token_set flag, rate_limit_tier, and Authorization header capture via mock). Both entries added to docs/TESTS.md. `specsmith sync` updated testcases.json to 260 entries.
+- **Status**: complete
+- **Chain hash**: auto