shynlee04/hivemind-plugin/gate-l3-evidence-truth

The Iron Law

No gate passes on documentation alone. Evidence must be classified, honest, and runtime-verified.

Gate Evidence Truth

Terminal gate in the quality-gate triad. Receives from gate-spec-compliance after spec alignment clears. If evidence truth PASSES, all three gates (spec, lifecycle, evidence) are satisfied and work may proceed to merge/release.

On Load

1. Read references/evaluation-checklist.md — per-dimension audit criteria
2. Read references/anti-patterns.md — known evidence anti-patterns and detection
3. Read references/harness-verification-trees.md — module-specific verification protocols

Do NOT Load

Skip this skill when:

• Performing spec alignment checks — use gate-spec-compliance instead
• Checking lifecycle coverage — use gate-lifecycle-integration instead
• Running research or exploration workflows (not gate verification)
• The calling workflow has not passed gate-spec-compliance yet
• No implementation artifacts exist to evaluate

🔨 IRON CLAW: Tech-Stack References & Assets Consumption Governance

ABSOLUTE RULE: No bundled reference, cached asset, or stale pattern from this skill shall be consumed for tech-stack API interface decisions without MCP-verified validation against the project's ACTUAL versions (package.json + lockfile), canonical source mappings (.hivemind/STACKS-REFERENCES.md), AND a raw codebase context scan of the current implementation state.

Rationale

Skills bundle references and assets as ORIENTATION tools — they help you understand WHAT exists and WHERE to look. But every bundled reference is a SNAPSHOT, frozen at the moment of ingestion. Stacks evolve: packages release breaking changes, APIs shift, SDKs deprecate surfaces. Using stale bundled signatures as implementation authority produces silent runtime errors.

Mandatory 5-Step Validation Chain

Before ANY tech-stack API interface from this skill's references/assets is used for implementation, code generation, or quality gate decisions:

STEP 1 — CONSUME .hivemind/STACKS-REFERENCES.md
 ├─ Read the canonical stack→repo→version mapping table
 ├─ Identify the correct GitHub repo for each dependency
 └─ Confirm the repo is active (not archived), version is current
 
STEP 2 — READ package.json + lockfile
 ├─ Extract the ACTUAL installed version (npm ls / grep lockfile)
 ├─ Cross-reference repo URL from STACKS-REFERENCES.md against npm registry
 └─ Flag any discrepancy between bundled version and installed version
 
STEP 3 — RAW CODEBASE CONTEXT SCAN
 ├─ grep/glob the actual src/ directory structure for current implementation
 ├─ Read current implementation files — not stale docs or bundled references
 ├─ Verify the claimed API signatures match current codebase reality
 └─ Check import paths, type definitions, and function signatures exist in actual code
 
STEP 4 — MCP LIVE VALIDATION (minimum 2 tools)
 ├─ Context7: resolve-library-id → query-docs (API signatures at installed version)
 ├─ DeepWiki: ask-question (architecture patterns, behavioral semantics)
 ├─ Repomix: pack-remote-repository (full repo analysis at correct version tag)
 ├─ Exa: web-search (latest docs, tutorials, migration guides)
 ├─ Tavily: search + extract (version-specific migration info)
 ├─ GitHub: get-file-contents (exact source verification at correct version)
 └─ GitMCP: search-code (source-level pattern matching)
 
STEP 5 — VERIFICATION RECORD
 ├─ Source URL + version confirmed to match package.json
 ├─ MCP tool(s) used + fetch timestamp
 ├─ Codebase scan paths + findings
 ├─ Version match status (MATCHED / MISMATCHED / UNVERIFIED)
 └─ Flag as BLOCKING if version mismatch or critical staleness detected

Consumption Rules

Integrated Enforcement Points

Evidence Hierarchy

Classify every evidence artifact into exactly one level:

L5 alone never passes any gate.

Gate Type → Minimum Evidence Level

Contextual Perspective Activation

Determine the current context, then activate the appropriate evaluation lens:

Load references/perspective-rubrics.md for per-lens evaluation criteria.

Core Evaluation Workflow

Follow this checklist in order:

- [ ] STEP 1: GATHER — Collect all evidence artifacts for the claim
- [ ] STEP 2: CLASSIFY — Assign L1–L5 to each artifact using evidence hierarchy
- [ ] STEP 3: CHECK MINIMUM — Does highest evidence level meet gate-type minimum?
- [ ] STEP 4: DETECT MOCKS — Any mock-only claims for integration surfaces?
- [ ] STEP 5: CHECK COMPLETION HONESTY — Any completion claims without backing evidence?
- [ ] STEP 6: REGRESSION CHECK — Any cross-phase regression risk from dependency graph?
- [ ] STEP 7: ANTI-PATTERN SCAN — Match evidence against anti-pattern catalog
- [ ] STEP 8: VERDICT — Render PASS or FAIL with remediation plan

See references/evaluation-workflow-detail.md for detailed step procedures, mock detection commands, and classification guidance.

Cross-Skill Routing

Triad Flow (lifecycle → spec → evidence)

gate-lifecycle-integration (ENTRY — checks lifecycle correctness)
    ↓ PASS
gate-spec-compliance (MIDDLE — checks spec alignment)
    ↓ PASS
gate-evidence-truth ← YOU ARE HERE (TERMINAL)
    ↓
    ├─ PASS → ALL 3 GATES CLEAR → proceed to merge/release
    └─ FAIL → STOP → produce remediation plan → route to appropriate fix skill

Triad backward references, evidence collection handoff from hm-production-readiness, and full remediation routing are in references/cross-skill-routing-detail.md.

Related Skills

Adopted Patterns

Synthesizes three proven methodologies: Anthropic Gather→Act→Verify, Google Testing Pyramid (70-20-10), GRADE Evidence Framework. See references/adopted-patterns.md for full synthesis.

Self-Correction

Mode 1: When No Evidence Exists

Do not downgrade the gate minimum. Report FAIL with explicit instructions: "Produce [L2/L1] evidence by [running integration test / capturing live session / verifying in OpenCode instance]."

Mode 2: When Evidence Is Ambiguous

Classify at the lower level. A test that mocks some but not all SDK boundaries is L4, not L3. A continuity record that may or may not be from a live session is L5, not L2.

Mode 3: When the User Overrides

Document the waiver in the evidence report with: which gate failed, what evidence was missing, and the user's rationale. The override must be explicit — never silently waive.

Mode 4: When Evidence Contradicts Itself

If two artifacts provide conflicting evidence for the same claim (e.g., a passing test but a failing continuity record), treat the contradiction as a regression signal. Classify both artifacts at their individual levels, mark the claim as UNVERIFIED, and require reconciliation before rendering PASS. Never average or weight conflicting evidence — resolve the contradiction or FAIL.

Gate Orchestrator Integration

This gate participates in the triad orchestrated by hm-gate-orchestrator. The orchestrator manages triad sequencing, state persistence, and cross-gate handoff. When invoked within an orchestrator workflow, this skill receives a pre-built evidence bundle and returns a structured verdict. See hm-gate-orchestrator for full triad lifecycle management.

Reference Files