Define Org-Wide Agent Run Contract

[FScholPer]

Goal

Define one mandatory execution contract for agent-driven changes across repositories.

Why

Developers need a concrete, repeatable checklist for what must run before merge, independent of optional proprietary accelerators.

Mandatory Contract (Applies to all repos)

1. Lane A (mandatory): all merge-critical checks run with open-source tooling only. Merge eligibility is determined exclusively from Lane A results.
2. Lane B (optional): proprietary or LLM-assisted accelerators may improve productivity but cannot be required for merge and cannot override a Lane A denial.

Required Contract Fields

• Runtime/container requirements (image, tool versions, reproducibility settings)
• Required command sequence (build, tests, policy checks, artifact generation)
• Required evidence artifacts and retention
• Failure categories and retry strategy
• Waiver process (approver, reason, expiry, audit reference)
• Fallback behavior when optional accelerators are unavailable

Implementation Tasks

• Publish a reusable contract template (run_contract.yaml or equivalent) for all repos.
• Define a per-repo command mapping table.
• Define rerun consistency criteria and tolerance window.
• Define branch protection check names linked to contract stages.

Docs-as-code pilot (first implementation)

• Build docs and generate needs data
• Generate traceability metrics JSON via existing traceability tooling
• Enforce thresholds via existing traceability gate
• Run repository tests
• Emit standardized evidence artifacts

Done When

• Contract template is approved by maintainers and referenced by onboarding issues.
• At least one pilot repo (docs-as-code) passes all required Lane A checks end-to-end.
• Contract includes explicit fallback behavior for unavailable accelerators.

Parent: #2852