Skip to content

[Phase 1] Define the review artifact contract + rubric registry (pr_diff sole type) #611

Closed

Description

@github-actions

Story

As a maintainer of the org's review automation,
I want an explicit artifact contract and a rubric registry with pr_diff as the only registered type,
so that the reviewer's logic can later be reused for plans and skills without forking it three ways.

Acceptance Criteria

  1. A documented artifact contract specifies the four fields {artifact_type, content_ref, rubric, output_channel}, their meaning, and allowed values.
  2. A versioned rubric-registry manifest maps each artifact_type to its rubric source and output_channel; only pr_diff is registered.
  3. The pr_diff registry entry references the existing prompts cascade (triage.md -> deep-review.md -> synthesize.md) and the inline-PR-review output channel (post-pr-review.sh) with no behavior change.
  4. The registry and helper are covered by the global CODEOWNERS rule and documented in a README adjacent to them and linked from AGENTS.md.
  5. shellcheck passes on touched scripts and no existing test changes are required (scaffolding only).

Tasks / Subtasks

Dev Notes

  • The current PR 'rubric' is the prompt cascade in prompts/: triage.md (Tier 1), deep-review.md (Tier 2), rubber-duck.md + synthesize-duck.md (cross-engine adversarial), synthesize.md (merge + act), security-audit.md (Tier 3), shared.md (risk taxonomy), single-review.md, cascade-action.md. The pr_diff registry entry must reference this cascade, not copy it.
  • The current PR 'output channel' is GitHub inline review comments + an approve/escalate review, implemented in scripts/post-pr-review.sh (posts via gh pr review, dismisses stale reviews, escalates via scripts/request-codeowners-review.sh). Treat that as the pr_diff output_channel.
  • Model/engine routing lives in scripts/engine.sh (set_engine_config maps engine->tier models; run_triage/run_agentic/run_duck invoke tiers). The contract is an input-adapter/registry layer ABOVE engine.sh — do not change engine routing here.
  • Keep this story strictly additive and scaffolding-only: pr_diff is the sole registered type and must resolve to today's behavior. Do not edit the cascade prompts themselves.
  • Standards: scripts must be #!/usr/bin/env bash + set -euo pipefail and pass shellcheck (AGENTS.md Scripts); the global CODEOWNERS rule * @petry-projects/org-leads already gates everything, so the registry is CODEOWNER-gated by default.

Project Structure Notes

Put the shell helper in scripts/lib/ alongside engine.sh/review-one-pr.sh orchestration, with a sibling README. Keep prompts/ for rubric content only (the cascade), not for the registry wiring.

References

  • prompts/triage.md
  • prompts/deep-review.md
  • prompts/synthesize.md
  • prompts/shared.md
  • scripts/engine.sh#set_engine_config
  • scripts/review-one-pr.sh
  • scripts/post-pr-review.sh
  • AGENTS.md#scripts
  • .github/CODEOWNERS

Likely target surface

  • scripts/lib/review-registry.sh
  • AGENTS.md
  • prompts/

Story prepared by the BMAD Scrum Master (Bob) for epic #610. Status: ready-for-dev.

Activity

  1. don-petry commented on Jun 12, 2026

    @don-petry
    Collaborator

    Dev-Lead Implementation Plan

    Issue: #611 — [Phase 1] Define the review artifact contract + rubric registry (pr_diff sole type)

    Scope

    Add an additive, scaffolding-only artifact contract + versioned rubric-registry manifest with a sourced lookup helper that resolves an artifact_type to its {rubric, output_channel}; register only pr_diff, resolving to today's prompt cascade and inline-PR-review output channel with no behavior change.

    Implementation Checklist

    • scripts/lib/review-registry.tsv — versioned manifest (schema_version + one row per artifact_type). Register only pr_diff → rubric prompts/triage.md,prompts/deep-review.md,prompts/synthesize.md, output_channel scripts/post-pr-review.sh.
    • scripts/lib/review-registry.sh — sourced lookup helper (#!/usr/bin/env bash, set -euo pipefail) reading the manifest: version, list types, resolve rubric/output_channel for an artifact_type; non-zero on unknown type/field. Data-in-manifest pattern mirrors model-pricing.{sh,tsv}.
    • scripts/lib/README.md — document the 4-field artifact contract {artifact_type, content_ref, rubric, output_channel} (meaning + allowed values) and the registry manifest format. Adjacent to the registry.
    • AGENTS.md — link the new README from the Scripts section.
    • .github/workflows/lint.yml — register tests/test_review_registry.bats in the bats list (per AGENTS.md repo-specific test extension note).

    Tests to Write

    • tests/test_review_registry.bats — version is reported; pr_diff is the sole registered type; rubric resolves to the triage→deep-review→synthesize cascade; output_channel resolves to scripts/post-pr-review.sh; unknown artifact_type and unknown field both fail non-zero; referenced rubric + output_channel files exist on disk (proves no-fork reference to today's cascade).

    Test Command

    bats tests/test_review_registry.bats (full suite: the bats list in .github/workflows/lint.yml); lint via bash .dev-lead/scripts/dev-lead-lint.sh.

    Notes

    Strictly additive scaffolding — does not touch engine.sh routing or the cascade prompts; production PR path (review-one-pr.sh) is unchanged.

  2. don-petry commented on Jun 12, 2026

    @don-petry
    Collaborator

    Dev-Lead: Implementation Complete

    Plan Execution

    • Added versioned rubric-registry manifest scripts/lib/review-registry.tsv (schema_version: 1; pr_diff is the sole registered type).
    • Added sourced lookup helper scripts/lib/review-registry.sh (#!/usr/bin/env bash, set -euo pipefail) resolving an artifact_type to its {rubric, output_channel}.
    • pr_diff resolves to the existing cascade (prompts/triage.md,prompts/deep-review.md,prompts/synthesize.md) and the inline-PR-review output channel (scripts/post-pr-review.sh) — no behavior change.
    • Documented the 4-field artifact contract {artifact_type, content_ref, rubric, output_channel} and the manifest format in scripts/lib/README.md (adjacent to the registry).
    • Linked the README from AGENTS.md (Scripts section).
    • Registered tests/test_review_registry.bats in the .github/workflows/lint.yml bats list.
    • shellcheck + dev-lead-lint pass on touched scripts; production PR path (review-one-pr.sh, engine.sh) untouched.

    Test Results

    # bats tests/test_review_registry.bats
    ok 1 reports a non-empty integer schema version
    ok 2 pr_diff is registered
    ok 3 pr_diff is the only registered type
    ok 4 pr_diff rubric resolves to the triage -> deep-review -> synthesize cascade
    ok 5 pr_diff output_channel resolves to post-pr-review.sh
    ok 6 unknown artifact_type fails non-zero
    ok 7 unknown field fails non-zero
    ok 8 missing artifact_type argument fails non-zero
    ok 9 every referenced rubric file exists
    ok 10 referenced output_channel exists
    
    # full CI bats list (.github/workflows/lint.yml): 206/206 pass
    
    # bash .dev-lead/scripts/dev-lead-lint.sh
      [lint] shellcheck on 46 file(s)...
      [lint] validating 4 agent profile(s)...
      [lint] all checks passed
    

    Files Changed

    • scripts/lib/review-registry.tsv (new): versioned manifest mapping artifact_type -> rubric, output_channel. Only pr_diff registered.
    • scripts/lib/review-registry.sh (new): sourced helper — review_registry_version, review_registry_types, review_registry_lookup <type> <field> (exit 1 unknown type, 2 missing/unknown field).
    • scripts/lib/README.md (new): artifact contract field table + manifest/helper docs; notes CODEOWNERS coverage.
    • AGENTS.md: new "Review artifact contract & rubric registry" subsection linking the README.
    • .github/workflows/lint.yml: added tests/test_review_registry.bats to the bats list.
    • tests/test_review_registry.bats (new): 10 unit tests.

    Notes

    • Strictly additive / scaffolding-only: no change to engine.sh routing or the cascade prompts; no existing test changed (TDD applied — the new helper is the only behavior under test).
    • The registry & helper fall under the global CODEOWNERS rule * @petry-projects/org-leads (.github/CODEOWNERS), so they are CODEOWNER-gated by default (AC Optimize review: small-PR and incremental fast paths #4).
    • Pre-existing unrelated failure observed in tests/test_batch_fallback.bats (Gemini->Copilot engine fallback); it is not in the CI bats list and is untouched by this change.
  3. added 6 commits that reference this issue on Jun 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    dev-leadFor dev-lead agent pickupinitiativeEpic / initiative tracking issue

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions