Wire agent docs into the audit harness and spec coverage

[cryptoxdog]

Summary

Three doc directories were referenced by no tool, so their contents could drift without anything failing. This connects each to the tool that should own it, and adds tests so the links cannot silently rot again.

Directory	Now	Why
docs/agent-tasks/fix-*.md	tools/auditors/remediation/	They are audit fix runbooks — they belong next to the harness that links them
docs/Dev-Docs/	tools/research/	Consumed by tools/spec_extract.py as spec-coverage input
docs/agent-tasks/ dev playbooks	consolidated into .claude/skills/	Skills are the path agents actually load

What changed

Audit remediation links were broken. Four auditors pointed at remediation_doc / contract_file paths that did not resolve, so every finding linked nowhere. Paths are corrected, the runbooks moved next to the harness, and audit_dispatch now prints a remediation index listing the fix runbook for each auditor that produced findings. tests/contracts/test_auditor_wiring.py asserts every contract_file and remediation_doc on every registered auditor resolves to a real file.

Research is now a tracked gap report. The five leverage patterns are checklist items in exactly the shape spec_extract already consumes. Each gains an engine_mapping block (search tokens plus scoped engine paths), and spec_extract emits a research_pattern category into artifacts/coverage_matrix.json. All five currently resolve to real subsystems — engine/kge, engine/hoprag, engine/traversal/multihop.py, engine/resolution, engine/gds — so today they report IMPLEMENTED; the point is that a regression would now show up as PARTIAL/MISSING. tests/contracts/test_research_wiring.py pins the mapping.

Two playbooks were actively wrong. add-action-handler.md documented a stale handler return shape and add-gate-type.md described a one-file-per-gate layout that no longer matches engine/gates/types/all_gates.py — following either produced a broken change. The four dev playbooks are marked status: deprecated with a banner pointing at their replacement skill. They are not deleted; DEFERRED-004 tracks removal pending approval, per the destructive-operation rule.

make agent-check — one command mirroring CI's blocking set (action refs, contract files, contract scan, lint, types, tests, audit harness). Thirteen references to this gate already existed in agent docs and pointed at nothing.

docs/contracts/README.md — the documented validation commands did not match CI and implied covered surface that is not covered. Corrected, with an explicit known-gaps table (openapi-spec-validator and jsonschema are undeclared dependencies, so those tests skip in a clean environment). Hardcoded test counts are replaced with the command to compute them, since they were already stale.

Scope note

The working tree this came from also contains unrelated in-progress work (chassis/engine/docker changes and a contract-registry expansion). This branch was built in an isolated worktree off origin/main and contains only the doc-wiring change set — no contracts/*.yaml, chassis/, engine/, or workflow changes.

artifacts/* are regenerated from this branch's content. artifacts/harness_report.md is left untracked: its four siblings are tracked, but adding a new generated file to git is a separate decision the repo has not made.

Test plan

Run from a clean checkout of this branch:

• python3 tools/verify_contracts.py — all 20 present and wired
• python3 tools/contract_scanner.py — no violations
• python3 tools/check_action_refs.py — passes (10 pre-existing pin-convention warnings)
• python3 tools/audit_harness.py — HARNESS PASSED
• ruff check . && ruff format --check .
• pytest tests/ — full suite green
• pytest tests/contracts/test_auditor_wiring.py tests/contracts/test_research_wiring.py — 37 tests, the new coverage
• make agent-check — the new gate, end to end

All of the above were run on this branch before pushing. make agent-check's mypy step could not be verified locally: the mypy on PATH runs under Python 3.9 while the project targets 3.12, which is a pre-existing environment issue unrelated to this change. CI runs it correctly.

Made with Cursor

[github-actions]

❌ PR Too Large
Reviewable lines changed: 2642
Limit: 1000 lines
Action Required: Break into smaller, atomic PRs

📋 Best Practices for Large Changes

1. Refactoring + Features: Separate into 2 PRs
2. Multiple Features: One PR per feature
3. Database + Code: Separate migration from logic
4. Generated Code: Exclude it from reviewable-size accounting

---

🚫 This PR is blocked until reviewable size limits are met.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud