feat(retrieval): add retrieval quality proofing workflow and archive change

[dubscode]

Summary

Implements the retrieval-quality-proofing change end-to-end and archives it via OpenSpec.

What this adds

• Retrieval proofing benchmark fixtures and profile configuration:
  • benchmarks/retrieval-proofing/benchmark.v1.json
  • benchmarks/retrieval-proofing/profiles.v1.json
• Proofing runtime modules:
  • deterministic multi-strategy runner (lexical, vector, hybrid)
  • deterministic grounding metrics scoring (evidence relevance, citation support, unsupported penalty)
  • aggregate metrics + hybrid delta + gate evaluation
  • JSON/Markdown reporting helpers
• CLI command:
  • dubsbot retrieval-proof (via pnpm dev retrieval-proof ...)
• CI integration:
  • smoke retrieval-proofing gate in PR workflow
• Tests:
  • determinism
  • report schema stability
  • gate pass/fail behavior
• Documentation:
  • benchmark schema/versioning
  • local + CI workflow and safe threshold updates
• OpenSpec archive:
  • archived change retrieval-quality-proofing
  • synced main spec: openspec/specs/retrieval-quality-proofing/spec.md

Why

Hybrid retrieval is a core claim; this introduces reproducible, deterministic proofing with enforceable CI gates so regressions are caught automatically.

Validation

• pnpm checks passed locally:
  • pnpm test
  • pnpm typecheck
  • pnpm lint
  • pnpm build

Notes

• Smoke profile is tuned for fast CI and currently allows a small hybrid-vs-lexical regression tolerance while requiring hybrid-vs-vector improvement.
• Full profile is available for deeper local evaluation.

---

🥞 DubStack

• feat(retrieval): add retrieval quality proofing workflow and archive change #6 feat(retrieval): add retrieval quality proofing workflow and archive change 👈
• feat(embedding): add strategy-based fallback engine with provenance #7 feat(embedding): add strategy-based fallback engine with provenance

[github-actions]

PR Checks Summary

• Status: passed
• Command: pnpm checks
• Workflow run: https://github.com/wiseiodev/dubsbot/actions/runs/22653390215
• Commit: d6ebee4

[Copilot]

Pull request overview

Adds a new “retrieval quality proofing” workflow to evaluate lexical/vector/hybrid retrieval against a versioned benchmark, emit JSON/Markdown reports, and enforce a configurable quality gate (including CI integration).

Changes:

• Introduces a retrieval proofing runner with scoring, gating, and report formatting.
• Adds a new retrieval-proof CLI command plus benchmark/profile fixtures and documentation.
• Adds Vitest coverage for determinism, schema stability, and gate pass/fail behavior; wires smoke-profile proofing into PR CI.

Reviewed changes

Copilot reviewed 16 out of 20 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
tests/retrieval-proofing.test.ts	New tests for determinism/schema stability/gating behavior.
src/context/retrieval/proofing/scoring.ts	Deterministic per-case scoring + aggregation helpers.
src/context/retrieval/proofing/schema.ts	Zod schemas for benchmark/profiles/report artifacts.
src/context/retrieval/proofing/runner.ts	Runs strategies, computes metrics/deltas, evaluates gate, builds report.
src/context/retrieval/proofing/reports.ts	Markdown report formatter for proofing output.
src/cli/commands/retrieval-proof.ts	CLI command implementation producing JSON/MD artifacts and failing on gate.
src/cli/commands.ts	Registers the retrieval-proof command + options.
openspec/specs/retrieval-quality-proofing/spec.md	New spec entry for retrieval quality proofing.
openspec/changes/retrieval-quality-proofing/tasks.md	Removes the active change task list (archived below).
openspec/changes/archive/2026-03-04-retrieval-quality-proofing/tasks.md	Archives tasks with completion status.
openspec/changes/archive/2026-03-04-retrieval-quality-proofing/specs/retrieval-quality-proofing/spec.md	Archives added requirements text.
openspec/changes/archive/2026-03-04-retrieval-quality-proofing/proposal.md	Archives proposal describing the motivation/scope.
openspec/changes/archive/2026-03-04-retrieval-quality-proofing/design.md	Archives design decisions, risks, and migration plan.
openspec/changes/archive/2026-03-04-retrieval-quality-proofing/.openspec.yaml	Archives OpenSpec metadata for the change.
docs/retrieval-proofing.md	How-to doc for running proofing locally/CI and updating thresholds.
docs/retrieval-proofing-benchmark-schema.md	Documents the benchmark/profile fixture schemas.
benchmarks/retrieval-proofing/profiles.v1.json	Adds initial smoke/full profiles + thresholds.
benchmarks/retrieval-proofing/benchmark.v1.json	Adds v1 benchmark dataset used by runner/tests.
README.md	Adds retrieval-proof usage + links to the new docs.
.github/workflows/pr-checks.yml	Runs smoke retrieval proofing in PR checks.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.