agentic-qe 3.10.9 → 3.11.1

package/.claude/skills/verification-quality/SKILL.md

@@ -1,9 +1,7 @@
 ---
-name: "verification-quality"
-description: "Verifies agent outputs against expected results and validates code changes pass quality checks before merge. Use when verifying agent outputs are correct, validating code changes before merge, or configuring automatic rollback for failed quality checks."
-version: "2.0.0"
-category: "quality-assurance"
-tags: ["verification", "truth-scoring", "quality", "rollback", "metrics", "ci-cd"]
+name: "Verification & Quality Assurance"
+description: |
+  Comprehensive truth scoring, code quality verification, and automatic rollback system with 0.95 accuracy threshold for ensuring high-quality agent outputs and codebase reliability.
 ---
 
 # Verification & Quality Assurance Skill
@@ -19,26 +17,70 @@ This skill provides a comprehensive verification and quality assurance system th
 - **CI/CD Integration**: Export capabilities for continuous integration pipelines
 - **Real-time Monitoring**: Live dashboards and watch modes for ongoing verification
 
+> **Shipped vs. aspirational.** The *concrete, in-CI* verification stack — the 6 regression-guard jobs + the witness manifest + the tool-discoverability audit — is real and runs on every push. The truth-scoring / auto-rollback / WebSocket-dashboard surface described later in this doc is partly shipped (`ruflo verify` runs the witness checks) and partly design — treat the "CI Guards" section below as the authoritative current state.
+
+## CI Guards — what's actually shipped (current state)
+
+Ruflo's regression protection is three layers, all gated before publish. Authoritative reference: [`verification/README.md`](../../../verification/README.md).
+
+| Layer | What | CI job(s) in `.github/workflows/v3-ci.yml` | ADR |
+|---|---|---|---|
+| **1 — install/behavioral smoke** | Exercise user-visible failure modes against a real build | `smoke-install-no-bsqlite` (npm install on platforms w/o prebuilds), `plugin-hooks-smoke` (#1859/#1862 — hook flag parsing), `mcp-protocol-smoke` (#1874 — HTTP MCP wire format), `memory-import-smoke` (#1883/#1884 — WSL path + key sanitization), `mcp-roundtrip-smoke` (#1889 paired-tool round-trip + #1863 cli-no-crash + ADR-095 G2 consensus-transport) | ADR-102 |
+| **1 — discoverability gate** | Every MCP tool description must answer "use this over native when?" | `tool-descriptions-audit` — `scripts/audit-tool-descriptions.mjs`, baseline at `verification/mcp-tool-baseline.json` (monotone-decreasing: noGuidance / tooShort / duplicates) | ADR-112 |
+| **2 — cryptographic witness** | Every documented fix's load-bearing marker must still be present in dist; Ed25519-signed, per-OS bundles | `witness-verify` (ubuntu/macos/windows) — `plugins/ruflo-core/scripts/witness/verify.mjs` against `verification/<os>/manifest.md.json` | ADR-103 |
+| **3 — temporal history** | When was a regression introduced | `verification/<os>/history.jsonl` + `history.mjs` (`summary` / `regressions` / `timeline`) | ADR-103 |
+
+### Run the guards locally
+
+```bash
+# Tool-description discoverability audit (ADR-112)
+node scripts/audit-tool-descriptions.mjs                       # fails if any baseline count rises
+node scripts/audit-tool-descriptions.mjs --update-baseline     # lock the new floor after a fix lands
+
+# Behavioral smokes (each builds what it needs; safe to run individually)
+node plugins/ruflo-core/scripts/test-hooks.mjs "node $PWD/v3/@claude-flow/cli/bin/cli.js"
+node plugins/ruflo-core/scripts/test-mcp-protocol.mjs
+node plugins/ruflo-core/scripts/test-memory-import.mjs
+node plugins/ruflo-core/scripts/test-mcp-roundtrips.mjs        # #1889 paired-tool round-trip
+node plugins/ruflo-core/scripts/test-cli-no-crash.mjs          # #1863 unhandled-exception class
+node plugins/ruflo-core/scripts/test-consensus-transport.mjs   # ADR-095 G2 consensus transport
+
+# Witness manifest — regenerate + verify
+node scripts/regen-witness.mjs
+node plugins/ruflo-core/scripts/witness/verify.mjs --manifest verification/macos/manifest.md.json
+
+# Temporal history
+node plugins/ruflo-core/scripts/witness/history.mjs --history verification/macos/history.jsonl summary
+node plugins/ruflo-core/scripts/witness/history.mjs --history verification/macos/history.jsonl regressions
+```
+
+### Adding a new guard
+
+1. **Behavioral smoke** → write `plugins/ruflo-core/scripts/test-<name>.mjs`. Pattern: static dist-scan first (fast, always completes), behavioral probe second with an internal timeout + a process-level watchdog so CI never hangs. Add a step to the relevant job in `v3-ci.yml`.
+2. **Static gate with a baseline** → write `scripts/audit-<name>.mjs` that scans, counts violations, and fails if the count exceeds a monotone-decreasing baseline in `verification/<name>-baseline.json`. Support `--update-baseline`. Add a CI job; wire it into `witness-verify` `needs[]` if it should gate `publish`.
+3. **Documented-fix marker** → append `{ id, desc, file, marker }` to `verification/witness-fixes.json`, run `node scripts/regen-witness.mjs`. The marker must be a substring the fix specifically creates (not a generic pattern like `'function'`).
+
 ## Prerequisites
 
-- Claude Flow installed (`npx claude-flow@alpha`)
+- Ruflo installed (`npx ruflo@alpha`)
 - Git repository (for rollback features)
 - Node.js 18+ (for dashboard features)
+- `@noble/ed25519` (for the witness verifier — a single runtime dep, `npm i @noble/ed25519`)
 
 ## Quick Start
 
 ```bash
 # View current truth scores
-npx claude-flow@alpha truth
+npx ruflo@alpha truth
 
 # Run verification check
-npx claude-flow@alpha verify check
+npx ruflo@alpha verify check
 
 # Verify specific file with custom threshold
-npx claude-flow@alpha verify check --file src/app.js --threshold 0.98
+npx ruflo@alpha verify check --file src/app.js --threshold 0.98
 
 # Rollback last failed verification
-npx claude-flow@alpha verify rollback --last-good
+npx ruflo@alpha verify rollback --last-good
 ```
 
 ---
@@ -54,40 +96,40 @@ Display comprehensive quality and reliability metrics for your codebase and agen
 **Basic Usage:**
 ```bash
 # View current truth scores (default: table format)
-npx claude-flow@alpha truth
+npx ruflo@alpha truth
 
 # View scores for specific time period
-npx claude-flow@alpha truth --period 7d
+npx ruflo@alpha truth --period 7d
 
 # View scores for specific agent
-npx claude-flow@alpha truth --agent coder --period 24h
+npx ruflo@alpha truth --agent coder --period 24h
 
 # Find files/tasks below threshold
-npx claude-flow@alpha truth --threshold 0.8
+npx ruflo@alpha truth --threshold 0.8
 ```
 
 **Output Formats:**
 ```bash
 # Table format (default)
-npx claude-flow@alpha truth --format table
+npx ruflo@alpha truth --format table
 
 # JSON for programmatic access
-npx claude-flow@alpha truth --format json
+npx ruflo@alpha truth --format json
 
 # CSV for spreadsheet analysis
-npx claude-flow@alpha truth --format csv
+npx ruflo@alpha truth --format csv
 
 # HTML report with visualizations
-npx claude-flow@alpha truth --format html --export report.html
+npx ruflo@alpha truth --format html --export report.html
 ```
 
 **Real-time Monitoring:**
 ```bash
 # Watch mode with live updates
-npx claude-flow@alpha truth --watch
+npx ruflo@alpha truth --watch
 
 # Export metrics automatically
-npx claude-flow@alpha truth --export .claude-flow/metrics/truth-$(date +%Y%m%d).json
+npx ruflo@alpha truth --export .claude-flow/metrics/truth-$(date +%Y%m%d).json
 ```
 
 #### Truth Score Dashboard
@@ -143,40 +185,40 @@ Execute comprehensive verification checks on code, tasks, or agent outputs.
 **File Verification:**
 ```bash
 # Verify single file
-npx claude-flow@alpha verify check --file src/app.js
+npx ruflo@alpha verify check --file src/app.js
 
 # Verify directory recursively
-npx claude-flow@alpha verify check --directory src/
+npx ruflo@alpha verify check --directory src/
 
 # Verify with auto-fix enabled
-npx claude-flow@alpha verify check --file src/utils.js --auto-fix
+npx ruflo@alpha verify check --file src/utils.js --auto-fix
 
 # Verify current working directory
-npx claude-flow@alpha verify check
+npx ruflo@alpha verify check
 ```
 
 **Task Verification:**
 ```bash
 # Verify specific task output
-npx claude-flow@alpha verify check --task task-123
+npx ruflo@alpha verify check --task task-123
 
 # Verify with custom threshold
-npx claude-flow@alpha verify check --task task-456 --threshold 0.99
+npx ruflo@alpha verify check --task task-456 --threshold 0.99
 
 # Verbose output for debugging
-npx claude-flow@alpha verify check --task task-789 --verbose
+npx ruflo@alpha verify check --task task-789 --verbose
 ```
 
 **Batch Verification:**
 ```bash
 # Verify multiple files in parallel
-npx claude-flow@alpha verify batch --files "*.js" --parallel
+npx ruflo@alpha verify batch --files "*.js" --parallel
 
 # Verify with pattern matching
-npx claude-flow@alpha verify batch --pattern "src/**/*.ts"
+npx ruflo@alpha verify batch --pattern "src/**/*.ts"
 
 # Integration test suite
-npx claude-flow@alpha verify integration --test-suite full
+npx ruflo@alpha verify integration --test-suite full
 ```
 
 #### Verification Criteria
@@ -217,7 +259,7 @@ The verification system evaluates:
 
 ```bash
 # Get structured JSON output
-npx claude-flow@alpha verify check --json > verification.json
+npx ruflo@alpha verify check --json > verification.json
 
 # Example JSON structure:
 {
@@ -249,25 +291,25 @@ Automatically revert changes that fail verification checks.
 **Basic Rollback:**
 ```bash
 # Rollback to last known good state
-npx claude-flow@alpha verify rollback --last-good
+npx ruflo@alpha verify rollback --last-good
 
 # Rollback to specific commit
-npx claude-flow@alpha verify rollback --to-commit abc123
+npx ruflo@alpha verify rollback --to-commit abc123
 
 # Interactive rollback with preview
-npx claude-flow@alpha verify rollback --interactive
+npx ruflo@alpha verify rollback --interactive
 ```
 
 **Smart Rollback:**
 ```bash
 # Rollback only failed files (preserve good changes)
-npx claude-flow@alpha verify rollback --selective
+npx ruflo@alpha verify rollback --selective
 
 # Rollback with automatic backup
-npx claude-flow@alpha verify rollback --backup-first
+npx ruflo@alpha verify rollback --backup-first
 
 # Dry-run mode (preview without executing)
-npx claude-flow@alpha verify rollback --dry-run
+npx ruflo@alpha verify rollback --dry-run
 ```
 
 **Rollback Performance:**
@@ -284,31 +326,31 @@ Create detailed verification reports with metrics and visualizations.
 **Report Formats:**
 ```bash
 # JSON report
-npx claude-flow@alpha verify report --format json
+npx ruflo@alpha verify report --format json
 
 # HTML report with charts
-npx claude-flow@alpha verify report --export metrics.html --format html
+npx ruflo@alpha verify report --export metrics.html --format html
 
 # CSV for data analysis
-npx claude-flow@alpha verify report --format csv --export metrics.csv
+npx ruflo@alpha verify report --format csv --export metrics.csv
 
 # Markdown summary
-npx claude-flow@alpha verify report --format markdown
+npx ruflo@alpha verify report --format markdown
 ```
 
 **Time-based Reports:**
 ```bash
 # Last 24 hours
-npx claude-flow@alpha verify report --period 24h
+npx ruflo@alpha verify report --period 24h
 
 # Last 7 days
-npx claude-flow@alpha verify report --period 7d
+npx ruflo@alpha verify report --period 7d
 
 # Last 30 days with trends
-npx claude-flow@alpha verify report --period 30d --include-trends
+npx ruflo@alpha verify report --period 30d --include-trends
 
 # Custom date range
-npx claude-flow@alpha verify report --from 2025-01-01 --to 2025-01-31
+npx ruflo@alpha verify report --from 2025-01-01 --to 2025-01-31
 ```
 
 **Report Content:**
@@ -328,16 +370,16 @@ Run interactive web-based verification dashboard with real-time updates.
 
 ```bash
 # Launch dashboard on default port (3000)
-npx claude-flow@alpha verify dashboard
+npx ruflo@alpha verify dashboard
 
 # Custom port
-npx claude-flow@alpha verify dashboard --port 8080
+npx ruflo@alpha verify dashboard --port 8080
 
 # Export dashboard data
-npx claude-flow@alpha verify dashboard --export
+npx ruflo@alpha verify dashboard --export
 
 # Dashboard with auto-refresh
-npx claude-flow@alpha verify dashboard --refresh 5s
+npx ruflo@alpha verify dashboard --refresh 5s
 ```
 
 **Dashboard Features:**
@@ -392,13 +434,13 @@ Set verification preferences in `.claude-flow/config.json`:
 **Adjust verification strictness:**
 ```bash
 # Strict mode (99% accuracy required)
-npx claude-flow@alpha verify check --threshold 0.99
+npx ruflo@alpha verify check --threshold 0.99
 
 # Lenient mode (90% acceptable)
-npx claude-flow@alpha verify check --threshold 0.90
+npx ruflo@alpha verify check --threshold 0.90
 
 # Set default threshold
-npx claude-flow@alpha config set verification.threshold 0.98
+npx ruflo@alpha config set verification.threshold 0.98
 ```
 
 **Per-environment thresholds:**
@@ -428,14 +470,14 @@ jobs:
   verify:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Install Dependencies
         run: npm install
 
       - name: Run Verification
         run: |
-          npx claude-flow@alpha verify check --json > verification.json
+          npx ruflo@alpha verify check --json > verification.json
 
       - name: Check Truth Score
         run: |
@@ -457,7 +499,7 @@ jobs:
 verify:
   stage: test
   script:
-    - npx claude-flow@alpha verify check --threshold 0.95 --json > verification.json
+    - npx ruflo@alpha verify check --threshold 0.95 --json > verification.json
     - |
       score=$(jq '.overallScore' verification.json)
       if [ $(echo "$score < 0.95" | bc) -eq 1 ]; then
@@ -477,13 +519,13 @@ Run verification automatically during swarm operations:
 
 ```bash
 # Swarm with verification enabled
-npx claude-flow@alpha swarm --verify --threshold 0.98
+npx ruflo@alpha swarm --verify --threshold 0.98
 
 # Hive Mind with auto-rollback
-npx claude-flow@alpha hive-mind --verify --rollback-on-fail
+npx ruflo@alpha hive-mind --verify --rollback-on-fail
 
 # Training pipeline with verification
-npx claude-flow@alpha train --verify --threshold 0.99
+npx ruflo@alpha train --verify --threshold 0.99
 ```
 
 #### Pair Programming Integration
@@ -492,10 +534,10 @@ Enable real-time verification during collaborative development:
 
 ```bash
 # Pair with verification
-npx claude-flow@alpha pair --verify --real-time
+npx ruflo@alpha pair --verify --real-time
 
 # Pair with custom threshold
-npx claude-flow@alpha pair --verify --threshold 0.97 --auto-fix
+npx ruflo@alpha pair --verify --threshold 0.97 --auto-fix
 ```
 
 ### Advanced Workflows
@@ -506,13 +548,13 @@ Monitor codebase continuously during development:
 
 ```bash
 # Watch directory for changes
-npx claude-flow@alpha verify watch --directory src/
+npx ruflo@alpha verify watch --directory src/
 
 # Watch with auto-fix
-npx claude-flow@alpha verify watch --directory src/ --auto-fix
+npx ruflo@alpha verify watch --directory src/ --auto-fix
 
 # Watch with notifications
-npx claude-flow@alpha verify watch --notify --threshold 0.95
+npx ruflo@alpha verify watch --notify --threshold 0.95
 ```
 
 #### Monitoring Integration
@@ -521,18 +563,18 @@ Send metrics to external monitoring systems:
 
 ```bash
 # Export to Prometheus
-npx claude-flow@alpha truth --format json | \
+npx ruflo@alpha truth --format json | \
   curl -X POST https://pushgateway.example.com/metrics/job/claude-flow \
   -d @-
 
 # Send to DataDog
-npx claude-flow@alpha verify report --format json | \
+npx ruflo@alpha verify report --format json | \
   curl -X POST "https://api.datadoghq.com/api/v1/series?api_key=${DD_API_KEY}" \
   -H "Content-Type: application/json" \
   -d @-
 
 # Custom webhook
-npx claude-flow@alpha truth --format json | \
+npx ruflo@alpha truth --format json | \
   curl -X POST https://metrics.example.com/api/truth \
   -H "Content-Type: application/json" \
   -d @-
@@ -544,16 +586,16 @@ Automatically verify before commits:
 
 ```bash
 # Install pre-commit hook
-npx claude-flow@alpha verify install-hook --pre-commit
+npx ruflo@alpha verify install-hook --pre-commit
 
 # .git/hooks/pre-commit example:
 #!/bin/bash
-npx claude-flow@alpha verify check --threshold 0.95 --json > /tmp/verify.json
+npx ruflo@alpha verify check --threshold 0.95 --json > /tmp/verify.json
 
 score=$(jq '.overallScore' /tmp/verify.json)
 if (( $(echo "$score < 0.95" | bc -l) )); then
   echo "❌ Verification failed with score: $score"
-  echo "Run 'npx claude-flow@alpha verify check --verbose' for details"
+  echo "Run 'npx ruflo@alpha verify check --verbose' for details"
   exit 1
 fi
 
@@ -585,13 +627,13 @@ echo "✅ Verification passed with score: $score"
 **Low Truth Scores:**
 ```bash
 # Get detailed breakdown
-npx claude-flow@alpha truth --verbose --threshold 0.0
+npx ruflo@alpha truth --verbose --threshold 0.0
 
 # Check specific criteria
-npx claude-flow@alpha verify check --verbose
+npx ruflo@alpha verify check --verbose
 
 # View agent-specific issues
-npx claude-flow@alpha truth --agent <agent-name> --format json
+npx ruflo@alpha truth --agent <agent-name> --format json
 ```
 
 **Rollback Failures:**
@@ -600,7 +642,7 @@ npx claude-flow@alpha truth --agent <agent-name> --format json
 git status
 
 # View rollback history
-npx claude-flow@alpha verify rollback --history
+npx ruflo@alpha verify rollback --history
 
 # Manual rollback
 git reset --hard HEAD~1
@@ -609,10 +651,10 @@ git reset --hard HEAD~1
 **Verification Timeouts:**
 ```bash
 # Increase timeout
-npx claude-flow@alpha verify check --timeout 60s
+npx ruflo@alpha verify check --timeout 60s
 
 # Verify in batches
-npx claude-flow@alpha verify batch --batch-size 10
+npx ruflo@alpha verify batch --batch-size 10
 ```
 
 ### Exit Codes
@@ -625,10 +667,10 @@ Verification commands return standard exit codes:
 
 ### Related Commands
 
-- `npx claude-flow@alpha pair` - Collaborative development with verification
-- `npx claude-flow@alpha train` - Training with verification feedback
-- `npx claude-flow@alpha swarm` - Multi-agent coordination with quality checks
-- `npx claude-flow@alpha report` - Generate comprehensive project reports
+- `npx ruflo@alpha pair` - Collaborative development with verification
+- `npx ruflo@alpha train` - Training with verification feedback
+- `npx ruflo@alpha swarm` - Multi-agent coordination with quality checks
+- `npx ruflo@alpha report` - Generate comprehensive project reports
 
 ### Best Practices
 
@@ -641,20 +683,6 @@ Verification commands return standard exit codes:
 7. **Review Rollbacks**: Understand why changes were rejected
 8. **Train Agents**: Use verification feedback to improve agent performance
 
-## Skill Composition
-
-- **Before verification** → Run `/qe-test-generation` and `/qe-coverage-analysis` first
-- **If verification fails** → Use `/test-failure-investigator` for root cause analysis
-- **Ship decision** → Feed into `/qe-quality-assessment` for final assessment
-
-## Gotchas
-
-- Verification is the HIGHEST-VALUE skill category (Anthropic: "worth having an engineer spend a week making verification skills excellent")
-- "Success is silent, only failures are verbose" — swallow passing test output, surface only errors to avoid context window flooding
-- Agent completion claims are unreliable — always include programmatic assertions on state, not just "looks right"
-- Have Claude record a video of its output so you can see exactly what it tested (Playwright trace, screenshot evidence)
-- Hardcoded values are the #1 completion theater pattern — grep for literals that should be dynamic
-
 ### Additional Resources
 
 - Truth Scoring Algorithm: See `/docs/truth-scoring.md`

package/.opencode/skills/qe-agentic-quality-engineering.yaml

@@ -1,13 +1,13 @@
 name: qe-agentic-quality-engineering
-description: "AI agents as force multipliers for quality work. Core skill for all 19 QE agents using PACT principles."
+description: "Use when orchestrating QE agents, understanding PACTS principles, configuring the AQE v3 fleet, or leveraging AI agents as force multipliers for quality work."
 minModelTier: tier1-any
-tags: ["pact", "agents", "fleet", "coordination", "autonomous", "foundational", "qe", "quality-engineering", "qe-core"]
+tags: ["pacts", "agents", "fleet", "coordination", "autonomous", "structured", "foundational", "qe", "quality-engineering", "qe-core"]
 steps:
-  - name: pact-principles
-    description: "PACT Principles"
+  - name: pacts-principles
+    description: "PACTS Principles"
     tools: ["bash", "read", "edit"]
     prompt: |
-      PACT Principles
+      PACTS Principles
   - name: 19-agent-fleet
     description: "19-Agent Fleet"
     tools: ["bash", "read"]

package/.opencode/skills/qe-holistic-testing-pact.yaml

@@ -1,28 +1,28 @@
 name: qe-holistic-testing-pact
-description: "Apply the Holistic Testing Model evolved with PACT (Proactive, Autonomous, Collaborative, Targeted) principles. Use when designing comprehensive test strategies for Classical, AI-assisted, Agent based, or Agentic Systems building quality into the team, or implementing whole-team quality practices."
+description: "Apply the Holistic Testing Model evolved with PACTS (Proactive, Autonomous, Collaborative, Targeted, Structured) principles. Use when designing comprehensive test strategies for Classical, AI-assisted, Agent based, or Agentic Systems building quality into the team, or implementing whole-team quality"
 minModelTier: tier1-any
-tags: ["holistic", "pact", "quality", "whole-team", "proactive", "autonomous", "collaborative", "targeted", "qe", "quality-engineering", "testing-methodologies"]
+tags: ["holistic", "pacts", "quality", "whole-team", "proactive", "autonomous", "collaborative", "targeted", "structured", "qe", "quality-engineering", "testing-methodologies"]
 steps:
-  - name: pact-principles
-    description: "PACT Principles"
+  - name: pacts-principles
+    description: "PACTS Principles"
     tools: ["bash", "read", "grep"]
     prompt: |
-      PACT Principles
+      PACTS Principles
   - name: holistic-testing-quadrants
     description: "Holistic Testing Quadrants"
     tools: ["bash", "read", "grep"]
     prompt: |
       Holistic Testing Quadrants
-  - name: agent-selection-by-pact-quadrant
-    description: "Agent Selection by PACT + Quadrant"
+  - name: agent-selection-by-pacts-quadrant
+    description: "Agent Selection by PACTS + Quadrant"
     tools: ["bash", "read"]
     prompt: |
-      Agent Selection by PACT + Quadrant
-  - name: pact-in-practice
-    description: "PACT in Practice"
+      Agent Selection by PACTS + Quadrant
+  - name: pacts-in-practice
+    description: "PACTS in Practice"
     tools: ["bash", "read"]
     prompt: |
-      PACT in Practice
+      PACTS in Practice
   - name: proactive-test-before-bugs
     description: "Proactive: Test Before Bugs"
     tools: ["bash", "read"]

package/CHANGELOG.md

@@ -5,6 +5,106 @@ All notable changes to the Agentic QE project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.11.1] - 2026-06-25
+
+Benchmark-driven deepening of the opt-in "cheap-first" test generation from
+v3.11.0. We ran real model-vs-model benchmarks scored by a real oracle (mutation
+kill-rate + coverage) and shipped only what the measurements earned: **best-of-k**
+generation, **cross-model** diversity, and a **self-test Goodhart guard** — plus a
+reusable adversarial-verification gate, MCP self-governance, and signed provenance
+for delivered findings. Everything stays **opt-in and off by default**.
+
+See the new [Darwin-QE Self-Learning guide](docs/guides/darwin-qe-self-learning.md)
+for the benchmarks, what we learned, and how to use it.
+
+### Added
+
+- **Best-of-k generation** — tries a few diverse candidates and keeps the first
+  that passes the objective check; the extra call happens only when the first one
+  fails. Enable via `freeTierBestOfK`.
+- **Cross-model best-of-k (opt-in)** — draw those candidates from *different* model
+  families (e.g. a local model + a cloud model) so they cover each other's failures.
+  Measured **~+6 quality points** over a single model. Configure with
+  `freeTierCandidateProviders`.
+- **Cheap-first lane broadened beyond test generation** — now also covers
+  requirements → BDD/Gherkin scenario generation (opt-in), with an off-topic
+  relevance gate so generic boilerplate is rejected.
+- **`@ruvector/adversarial-verify`** — a host-agnostic blind-refuter verification
+  primitive (N independent refuters, majority-kill, default-refuted on uncertainty)
+  plus an opt-in **`verifyGate`** output gate that drops unverified findings before
+  they're emitted. New `agentic-qe/verification/adversarial-verify` export.
+- **MCP self-governance** — a default-deny policy for AQE's own MCP tool surface
+  (`.harness/mcp-policy.json`) with a CI gate that fails on any high-severity finding.
+- **Cost-Pareto value scoring** — rank models by quality-per-dollar (and compute the
+  non-dominated frontier) from *measured* data, not vendor claims. New
+  `agentic-qe/routing/value-score` export.
+- **Witnessed finding delivery** — delivered findings are recorded in the Ed25519
+  hash-chained witness log with fail-closed verification (tampering throws).
+- **Graceful optional-module loading** — native/optional dependencies now degrade
+  instead of crashing when a platform binary is absent, with a CI "absent drill"
+  that proves the degraded path (and never masks a real load failure).
+
+### Changed
+
+- **Default free-tier model is now `qwen3:30b-a3b`** (was `qwen3:8b`). A benchmark
+  showed the 8B model is below the test-generation quality floor; the 30B clears it
+  (~89% mutation kill). Set `freeTierModel` to fit your hardware — small-RAM users
+  get escalation-only value. Only affects users who opt into the free tier.
+- **Goodhart guard** — only an *objective* check (real test run, coverage, mutation,
+  schema) can lift routing confidence; a model's own self-authored "passing" test
+  never does.
+
+## [3.11.0] - 2026-06-20
+
+Run test generation on **free local models first**, falling back to paid models
+only when needed. This release adds an opt-in "cheap-first" path: a local model
+(Ollama, OpenRouter free tier, or any OpenAI-compatible endpoint) attempts test
+generation with an automatic repair loop, and only the hard cases escalate up to
+your normal LLM tiers — so most routine generation can run at $0. Every cheap-vs-
+escalated outcome feeds routing feedback, so model selection improves over time.
+
+Off by default; nothing changes unless you opt in. Inspired by the "the harness
+matters as much as the model" economics from Ruv's MetaHarness Darwin Mode.
+
+### Added
+
+- **Free-tier local test generation (opt-in).** Enable with `AQE_FREE_TIER=1`
+  (or `enableFreeTier` in the test-generation coordinator config) to generate
+  tests on a free/local model before any paid LLM call. Default model `qwen3:8b`.
+  See the [Free-Tier Local Models guide](docs/guides/free-tier-local-models.md).
+- **Configurable free-tier providers** — local Ollama, cloud Ollama, OpenRouter
+  free models, or any OpenAI-compatible endpoint (vLLM, LM Studio, Groq, …). API
+  keys are read from named environment variables and never stored.
+- **Repair loop** — when the local model's first output isn't a valid test, the
+  failure is fed back and it retries before falling back (configurable retries).
+- **Automatic escalation** — hard cases the local model + repair can't solve
+  escalate up the existing model ladder (Haiku → Sonnet → Opus) via the router.
+- **Self-learning routing feedback** — free-tier outcomes feed the routing
+  calibrator and escalation tracker, improving model-tier confidence over time.
+- **`agentic-qe/routing/free-tier` package export** for programmatic configuration.
+
+### Fixed
+
+- **Restored `@ruvector/ruvllm-*` optional platform packages** dropped from the
+  lockfile by a Dependabot update, which could break `npm ci` for consumers. (#541)
+- **Multi-file test-generation requests** now correctly fall back to the full
+  generation path so every requested file is covered (the free-tier path handles
+  the single-file case).
+- Security bump of the transitive `hono` dev dependency. (#541)
+
+### Changed
+
+- **Auto-escalation tracker is now ladder-configurable** (generic over tier
+  names) so a free local tier can sit below the paid tiers. Fully backward
+  compatible — existing behavior and the default Claude ladder are unchanged.
+- **QE framework evolved PACT → PACTS** — adds a fifth principle, **Structured**
+  (governance, observability, and explainability of agent behavior; measure
+  *confidence*, not trust), inspired by DORA's research on AI-assisted delivery.
+  Ships with a playbook + readiness-assessment guide. The skill id/dir
+  `holistic-testing-pact` and schema slugs are unchanged (cross-repo stable); the
+  output schema gains an **optional** `structured` dimension (non-breaking).
+  PACT originated with Reuven Cohen (Agentics Foundation); PACTS adds Structured. (#545)
+
 ## [3.10.9] - 2026-06-17
 
 MCP server reliability and database-free completeness, all from community-reported