Tier-aware pre-merge pipeline — reads classification tags only, fail-safe red

[rucka]

Story Statement

As a team delivering with pair
I want the pre-merge quality gate pipeline modulated by the risk tier read from PR classification tags — always install+lint+type+build, unit from 🟡, integration+E2E only on 🔴, untagged PR treated as 🔴 — with deterministic secret scanning always on
So that gate effort matches risk with zero classification logic in CI (the pipeline only reads tags) and no PR merges past a red gate

Where: CI pipeline of the adopting project (generated/configured via pair-capability-setup-gates) + PR checks on the code host

Epic Context

Parent Epic: CI/CD gates tag-driven #210
Status: Refined
Priority: P0 (Must-Have)

Status Workflow

• Refined: Story is detailed, estimated, and ready for development
• In Progress: Story is actively being developed
• Done: Story delivered and accepted

Acceptance Criteria

Functional Requirements

Given-When-Then Format:

1. Given a PR tagged risk:green
   When the pre-merge pipeline runs
   Then it executes install+lint+type+build only — no unit, no integration/E2E jobs are scheduled

2. Given a PR tagged risk:yellow
   When the pre-merge pipeline runs
   Then unit tests run in addition to the base checks, and integration/E2E do not

3. Given a PR tagged risk:red OR a PR with no classification tags
   When the pre-merge pipeline runs
   Then the full matrix runs (base + unit + integration + E2E) — untagged ⇒ treated as 🔴 (fail-safe)

4. Given any tier
   When any required gate job fails (including secret scanning)
   Then the PR is blocked from merging until the gate is green

5. Given a diff containing a secret/key
   When the deterministic secret-scanning layer (gitleaks, KB default A4) runs
   Then the build goes red — no LLM involved, always on at every tier

6. Given a merge to the main branch
   When the post-merge staging pipeline runs
   Then it performs build+deploy only (no gate re-run)

Business Rules

• The pipeline contains NO classification criteria of its own (D18): it only reads classification tags on the PR — grep-verifiable
• Tag reading happens at pipeline start; tags are produced upstream by classify (pair-capability-classify + tag projection + risk-matrix delta #233) and propagated by publish-pr
• Secret scanning tool is gitleaks by KB default, replaceable in adoption (A4)
• Pipeline config is produced/updated by pair-capability-setup-gates for the adopted tech stack; hooks default to husky (A11)
• Gate ≠ review (R5.4): the gate is the first, deterministic filter; review starts only at green gates

Edge Cases and Error Handling

• Untagged PR: full 🔴 matrix (fail-safe), never silently skipped
• Unknown/malformed tag value: treated as 🔴 + warning annotation on the PR
• Tag changed mid-review (review raises the tier): next pipeline run re-reads tags and widens the matrix — never narrows against a previous run
• Missing test suites at a tier that requires them (e.g. 🔴 with no E2E suite): gate fails with an explicit "suite missing" error, not a silent pass

Definition of Done Checklist

Development Completion

• All acceptance criteria implemented and verified
• KB guideline + setup-gates templates follow project conventions
• Code review completed and approved
• Automated tests written and passing (pipeline config generation fixtures)
• Documentation updated — docs site (apps/website) page for tag-driven gates
• CLI (apps/pair-cli) updated where install/update/distribution is touched

Quality Assurance

• Matrix verified on a sample repo for all three tiers + untagged case
• Grep audit: no classification criteria inside generated pipeline config
• Secret-scanning red path verified with a planted dummy secret

Story Sizing and Sprint Readiness

Refined Story Points

Final Story Points: 5 (L)
Confidence Level: Medium
Sizing Justification: confirmed L(5) — gate matrix + setup-gates generation across stacks + fail-safe/edge handling + deterministic security layer; consumption-only design (no classify logic) keeps it out of XL

Sprint Capacity Validation

Sprint Fit Assessment: yes, single sprint with prerequisites landed
Total Effort Assessment: fits — Yes

Dependencies and Coordination

Story Dependencies

Prerequisite Stories: #233 (classify produces tags), #202 (canonical states/board semantics); publish-pr tag propagation (#206 scope)
Dependent Stories: verify-quality gate-matrix integration (sibling); #212 automation (consumes green gates)

External Dependencies

Third-party Integrations: gitleaks (default, swappable via adoption); CI provider of the adopting project (config stays provider-shaped but criteria-free)

Validation and Testing Strategy

Acceptance Testing Approach

Testing Methods: fixture repo with PRs tagged green/yellow/red/untagged; assert scheduled job set per tier; failing job ⇒ merge blocked
Test Data Requirements: sample diffs incl. one with a dummy secret

Notes and Additional Context

Refinement Session Insights: fail-safe default (untagged ⇒ 🔴) is non-negotiable; pipeline is a pure tag consumer (D18)
Documentation Links: R8.1 · Spec G9 (+G7 deterministic layer) · D18, A4, A11

Technical Analysis

Implementation Approach

Technical Strategy: extend pair-capability-setup-gates to emit tier-aware pipeline config: a first step resolves classification tags from the PR into a TIER value (fail-safe red), subsequent jobs are conditioned on TIER; secret scanning job unconditional; KB guideline documents the matrix (tier → checks) as the single source
Key Components: setup-gates SKILL.md + config templates per stack; gate-matrix section in quality guidelines; tag-resolution step (provider-agnostic shell)
Integration Points: classification tags (#233), publish-pr propagation (#206), verify-quality (sibling story), branch protection/required checks on the code host

Technical Risks and Mitigation

Risk	Impact	Probability	Mitigation Strategy
CI-provider lock-in in templates	Medium	Medium	criteria live in KB matrix; templates thin per-provider adapters
Tag drift between runs	Medium	Low	tags re-read at every run; matrix can only widen vs previous run on same PR

Task Breakdown

Checklist

• T1 — KB guideline: gate matrix (tier → checks), fail-safe rule, staging post-merge scope
• T2 — Tag-resolution step (PR tags → TIER, untagged ⇒ red) as provider-agnostic snippet
• T3 — setup-gates: emit tier-conditioned pipeline config + required-check wiring
• T4 — Deterministic secret scanning (gitleaks default, adoption override) always-on job
• T5 — Fixture verification (3 tiers + untagged + planted secret) + docs site + distribution

Dependency Graph

T1 → T2 → T3 → T5; T4 → T5

AC Coverage

Task	AC1	AC2	AC3	AC4	AC5	AC6
T1	✓	✓	✓			✓
T2			✓
T3	✓	✓	✓	✓		✓
T4				✓	✓
T5	✓	✓	✓	✓	✓	✓