run-quality-gate

name	run-quality-gate
description	Run a reusable quality gate over a stage artifact using explicit acceptance criteria, blocking rules, and required invariants. Use when Codex must return PASS, WARN, FAIL, or BLOCKED with evidence, required fixes, and artifact metadata updates. Do not use to produce the stage artifact itself.

Run Quality Gate

Goal

Act as the reusable gate engine for stage artifacts. Evaluate an artifact against explicit rules, decide whether the stage may proceed, and return metadata updates that materialize approval state.

Read Shared Contract Reference before running the gate. Prefer repo-backed profiles from ../../gate-profiles when available.

Trigger boundary

• Use after a producer step has created or updated an artifact that needs approval.
• Do not use to generate the artifact under review.
• Do not invent acceptance criteria or blocking rules.

Required input

• Required: stage
• Required: gate_profile
• Required: artifacts_under_review
• Required: upstream_artifacts
• Required: acceptance_criteria, either provided directly or loaded from a repo-backed gate profile
• Required: blocking_rules, either provided directly or loaded from a repo-backed gate profile
• Required: required_invariants, either provided directly or loaded from a repo-backed gate profile
• Optional: stage_policy
• Optional: review_scope

Refusal and blocked policy

• Return BLOCKED when any required gate input is missing.
• Return BLOCKED when the artifact under review lacks enough evidence or structure for the gate profile to evaluate it.
• Do not silently relax acceptance criteria, blocking rules, or invariants.
• Do not rewrite the artifact under review; report required fixes instead.

Workflow

1. Confirm the stage, gate profile, and reviewed artifact inventory.
2. Load the reusable gate profile from the repo when available and merge any explicit overrides.
3. Check that all required gate inputs are present and concrete.
4. Evaluate the artifact against acceptance criteria, blocking rules, and required invariants.
5. Separate blocking issues, non-blocking issues, and traceability gaps.
6. Decide PASS, WARN, FAIL, or BLOCKED using the shared decision semantics and the active stage policy.
7. Produce concrete required fixes and metadata updates for every reviewed artifact.

Output contract

Write gate-report.yaml or return equivalent YAML using this structure:

artifact_metadata:
  artifact_id: ""
  artifact_type: gate-report
  artifact_status: current | superseded
  approval_status: approved | changes_required | rejected | pending_review
  approved_by_gate_profile: ""
  gate_report_ref: self
  upstream_artifact_refs:
    - ""
stage: ""
gate_profile: ""
decision: PASS | WARN | FAIL | BLOCKED
decision_rationale: ""
summary: ""
reviewed_artifacts:
  - artifact_ref: ""
    artifact_type: ""
blocking_issues:
  - issue_id: ISSUE-*
    rule_id: RULE-*
    artifact_ref: ""
    issue: ""
    evidence_source: ""
    evidence_excerpt_or_reference: ""
    impact: ""
non_blocking_issues:
  - issue_id: ISSUE-*
    rule_id: RULE-*
    artifact_ref: ""
    issue: ""
    evidence_source: ""
    evidence_excerpt_or_reference: ""
    impact: ""
traceability_gaps:
  - issue_id: ISSUE-*
    missing_link_from: ""
    missing_link_to: ""
    impact: ""
required_fixes:
  - artifact_ref: ""
    fix: ""
approved_artifacts:
  - ""
artifact_metadata_updates:
  - artifact_ref: ""
    artifact_status: current | superseded
    approval_status: approved | changes_required | rejected | pending_review
    approved_by_gate_profile: ""
    gate_report_ref: ""
next_step_allowed: true

Quality bar

• Every decision must be explainable from explicit rules and evidence.
• Use BLOCKED instead of guessing when gate inputs are missing.
• Emit artifact metadata updates for every reviewed artifact, even on FAIL.
• Keep required fixes concrete enough to drive a rework brief.
• Prefer repo-backed gate profiles over ad hoc criteria passed only in prose.