Codebase Evaluation — Framework & Governance
Docs » Codebase Evaluation — Framework & Governance » Handoff Schema & Downstream Integration
Raw .md

Handoff Schema & Downstream Integration Contract

Purpose: Formal specifications for packaging evaluation results into an authoritative, tool-agnostic handoff manifest ready for downstream remediation, technical program management, and automated backlog minting.

Specification Metadata Value
Framework Version CEF v0.1.0
Governance Tier Authoritative Core (Handoff Boundary)
Target Roles Lead Integrators, Process Engineers, Swarm Orchestrators
Target Systems ZQK Knowledge Kernel, Issue Trackers, CI/CD Gate Orchestrators

1. Handoff Package Directory Structure

Upon completion of Wave 4, the lead integrator packages evaluation artifacts into a versioned, self-contained directory:

cef-run-<timestamp>/
  run_scope.yaml                  # Frozen scope configuration
  scorecard.json                  # Multi-axis Diamond Scale scores
  findings.jsonl                  # Validated, post-adversarial findings
  adversarial_resolutions.jsonl   # Auditor verification log
  diagrams/**                     # Anchored architectural diagrams
  tooling_gaps.md                 # Discovered scanner and tooling deficiencies
  run_log.md                      # Operational execution journal
  handoff_manifest.json           # Canonical integration manifest

2. Handoff Manifest Schema (handoff_manifest.json)

The handoff_manifest.json file serves as the canonical contract between evaluation analysis and downstream remediation execution:

{
  "cef_version": "0.1.0",
  "mode": "truth_map",
  "repo_fingerprint": "7e51cb7a61d15dfb8efb36873bcdd74bf93f2f51",
  "accepted_finding_ids": [
    "F-ARCH-001",
    "F-SEC-002",
    "F-CONC-003"
  ],
  "waived": [
    {
      "finding_id": "F-PERF-004",
      "reason": "Bounded by memory limits in container runtime.",
      "by": "lead-architect"
    }
  ],
  "suggested_program_shape": {
    "missions": [],
    "workstreams": [],
    "goals": [],
    "milestones": [],
    "priority_plans": [],
    "requirements": [],
    "criteria": [],
    "test_cases": [],
    "work_items": [],
    "agent_tasks": [],
    "agent_instructions": []
  },
  "notes": "Consolidated evaluation synthesis for engineering remediation."
}

3. Work Item Mapping Guidance

Downstream process engineers and orchestration pipelines map findings to work structures using the following taxonomy:

Finding Shape Suggested Downstream Artifact Types
Discrete defect with clear automated verification gate requirement + criterion + test_case + work_item
Systemic architectural conflict or boundary violation goal + workstream + milestone + tech_debt
Missing automated linter, scanner, or analyzer tooling_gap + work_item
Documentation inaccuracy or mental model conflict work_item + agent_instruction
Important

Minting Isolation Invariant: Evaluation agents must never mint tracker objects or backlog items directly during analysis. Decoupling the objective truth map from backlog creation prevents issue tracker sprawl and maintains evaluation objectivity.

4. Architectural Analysis & Tradeoffs

Advantage Operational Consideration
Prevents evaluation swarms from polluting production issue trackers with speculative tasks. Requires a downstream process engineer or automation to ingest and objectify the handoff package.
Tool-agnostic architecture integrates cleanly with ZQK, GitHub Issues, Jira, or plain Markdown plans. Mapping taxonomy provides guidance rather than rigid enforcement, accommodating varied organizational workflows.