post-smoke-ci-plan-boundary-hardening

# Post-smoke CI plan boundary hardening

Use when:
- a previous issue already unblocked workflow startup/checkout/smoke
- the workflow is still red at later gates (lint, mypy, coverage, quality-gate)
- the next issue is a bounded CI-hardening tranche, not a repo-wide cleanup

## Goal
Draft a plan that removes the current first post-smoke blockers without pretending to solve all downstream CI debt.

## Required approach

1. Verify the live split from the validating CI run
- Inspect the exact run/job graph, not just issue comments.
- Record which OS/jobs fail at which step.
- Separate:
  - current first blocker(s)
  - later-stage blockers that will surface after those are removed

2. Reproduce locally enough to classify scope
- Run the exact or nearest local validator for the current failing gate(s).
- For typing gates, quantify breadth (example: "286 errors across 39 files") before promising fixes.
- If the failure surface is broad, do not draft a plan that quietly absorbs repo-wide debt.

3. Convert vague “make CI green” wording into an honest bounded tranche
If the issue body is broader than what the evidence supports, the plan must explicitly define:
- what gate is being fixed now
- what red state is allowed to remain
- what later-stage failures must be split or referenced

Do not use vague success phrases like:
- “meaningfully green”
- “advances past blockers”
without naming the exact next expected state.

4. Lock the workflow scope explicitly
For workflow edits, name the exact maintained target list.
Examples:
- exact flake8 path set
- exact mypy target files/modules
- exact dependency-install step(s) that change

Do not leave key questions open in the plan such as:
- “Should lint target X or Y?”
- “Should we install stubs or suppress?”
These must be resolved before plan-review if they affect correctness.

5. Create explicit follow-up issues for excluded surfaces
If you narrow CI scope away from broken but real files, create tracking issues immediately.
Typical excluded surfaces:
- auxiliary `.agent-os/` or tooling scripts
- duplicate non-package module copies
- broad repo-wide type debt already tracked elsewhere

In the plan, cite the concrete follow-up issue numbers, not placeholders or intentions.

6. Make TDD executable for workflow changes
For workflow-scope changes, add a real test artifact path.
Good pattern:
- create a workflow-scope regression test file under tests/
- parse/assert the exact workflow targets
- require a red phase before editing the workflow

Also ensure test commands match repo policy exactly:
- use `uv run` consistently if required by repo contract
- preserve `python -m pytest` / `--noconftest` conventions when the repo defines them

7. Keep review bookkeeping honest
If a review artifact is empty, timed out, or invalid:
- mark it INVALID explicitly
- do not fabricate or summarize findings that do not exist
- do not move to `status:plan-review` until enough valid review evidence exists per repo policy

## Planning checklist
- Exact validating run ID captured
- First blocker per OS/job captured
- Local breadth quantified for current failing gate
- Exact workflow target list defined
- Any exclusion has a follow-up issue number
- TDD workflow-test file path exists in Files to Change
- Static-analysis red phase is explicit, not implied
- Review summary matches actual artifacts on disk
- Success condition is bounded and falsifiable

## Common failure modes
- promising green CI while only fixing the first blocker
- narrowing lint/type scope without tracking excluded files
- using vague close criteria instead of explicit workflow states
- leaving critical implementation branches as “open questions”
- claiming review convergence when artifact files are empty

## Good outcome
A plan that says, in effect:
- “This tranche fixes lint scope X and mypy target Y”
- “These excluded surfaces are tracked in follow-up issues A/B”
- “Broad residual debt remains under issue C”
- “We will only move to plan-review after valid review artifacts support this exact bounded contract”