autocoverage

name	autocoverage
description	Use when a user asks to generate or improve unit tests with measurable coverage gains using a strict staged workflow (build -> baseline -> plan -> generate -> verify -> coverage delta). Trigger phrases: generate unit tests, improve coverage, write tests for uncovered code, make PR-ready tests. Do not use for integration/E2E testing, production refactoring, or planning-only requests without code generation intent.
lastReviewed	2026-04-30T00:00:00.000Z

Auto Unit Test Generator

Constraints (apply at ALL stages)

DO:

• Run until target coverage is reached or all modules are terminal (done/stalled)
• Use measured coverage gaps as input -- never guess
• Prioritize exception handlers, error paths, retry logic, validation
• Build and pass all tests locally before every commit
• Prove a measured coverage delta each iteration
• Branch from default integration branch; atomic commits per iteration
• Stick to verified facts from repo files, commands, and recorded artifacts -- never assume

NEVER:

• Generate tests on a broken build
• Test constants, DTOs, constructors, properties, default values, or logging
• Create a test project in the same folder as an existing project
• Rename folders, move files, rename projects, or change production code

Skill structure

SKILL.md                        -- Pipeline (this file)
scripts/
  parse-cobertura.ps1           -- Parse Cobertura XML into JSON
  parse-coverage-text.ps1       -- Parse pytest/Jest/Vitest text coverage into JSON
references/
  code-coverage.md              -- Coverage commands, tools, parsing
  test-planning.md              -- Prioritization + plan format
  test-generation.md            -- Code gen rules, framework compat, Moq, metadata
  test-quality.md               -- Anti-patterns, review checklist, quality gate
  test-finalization.md          -- Incorporate feedback, produce final code
  ci-pipeline-checklist.md      -- PR/pipeline readiness
  skill-templates.md            -- Reusable output templates
  pr-description-template.md    -- Final PR description template

Reference Lookup

Load the reference file(s) when entering the listed stage.

Stage	Reference file(s)
2, 7	code-coverage.md
3	test-planning.md
4	test-generation.md, test-quality.md
5	test-quality.md, test-finalization.md
7 (PR)	pr-description-template.md
Pre-PR	test-quality.md, test-finalization.md
CI	ci-pipeline-checklist.md
any	skill-templates.md

---

Progress Manifest

Create .coverage-progress.json at the repo root to persist state across iterations and sessions:

Local-state only rule: .coverage-progress.json is runtime state. Never stage or commit this file.

See the "Progress Manifest Example" section in references/skill-templates.md.

Add one module entry per detected language/project. Examples: C# (dotnet test), Rust (cargo test), TypeScript (npx jest), Python (pytest), C++ (ctest).

Resuming from interruption

On every invocation, check for .coverage-progress.json at the repo root:

Status	Action
in-progress	Re-run coverage to get current state, continue from where it left off
pending	Start from Stage 0 for that module
done	Skip this module
stalled	Skip (report why it stalled in previous session)
skipped	Skip

After completing each stage, update the manifest with current coverage numbers, status, and lastUpdated timestamp. This makes the skill resilient across sessions -- a 50-module monorepo processes over multiple sessions without losing progress.

If the file does not exist, create it during Stage 0. If a branch is recorded in the manifest, check it out before resuming.

---

Memory (Cross-Session Context)

Use /memories/repo/ to cache context discovered during Stage 0 so it persists across sessions. This avoids re-discovering the same information every time.

Memory path resolution (tool path vs shell path)

• /memories/repo/... is the logical memory path for the memory tool.
• Local (interactive): $env:USERPROFILE\.copilot\memories\repo\...; use APPDATA fallback only if needed.
• CI environment: Use $env:AGENT_TEMPDIRECTORY (ADO Pipelines — available in all Azure DevOps pipeline agents) or $env:RUNNER_TEMP (GitHub Actions) as the memory root. Never write to user profile paths in CI — they may not exist or persist. Memory files are ephemeral in CI and must not be checked in.

On first run (Stage 0), save to /memories/repo/test-gen-context-<repo-name>.md:

Derive <repo-name> from the repo root folder name (e.g., for C:\repos\MyService, use test-gen-context-MyService.md). This allows multiple repos to have their own context without overwriting each other.

Use exactly ONE memory file per repo. If you find multiple files (e.g., both test-gen-context.md and test-gen-context-MyService.md), merge them into the test-gen-context-<repo-name>.md file and delete the other. Do not maintain duplicates.

See the "Memory Context Template" section in references/skill-templates.md.

On every invocation, check memory FIRST:

1. Read /memories/repo/test-gen-context-<repo-name>.md -- if it exists, check the Source Fingerprint section:
   • Compare the stored git commit hash of copilot-instructions.md and AGENTS.md against the current git log for those files:

     git log -1 --format="%H" -- .github/copilot-instructions.md
     git log -1 --format="%H" -- AGENTS.md
     

   • If hashes match: memory is valid. Use cached context, skip full Stage 0 discovery.
   • If hashes differ (files were updated in a newer commit): repo instructions have changed. Re-run full Stage 0 discovery and overwrite the memory (preserve the Gotchas and Known Exclusions sections -- only regenerate Build & Test, Conventions, CI Pipeline, and Project Rules).
2. If the memory file does not exist, run full Stage 0 discovery and save the results.
3. After every iteration, if you learned something not already in memory -- a new gotcha, a convention, an exclusion, a workaround -- append it. The memory should get smarter over time so the next session starts where this one left off.

---

Pipeline Stages

STRICT SEQUENTIAL EXECUTION: 0 --> 1 --> [ 2 --> 3 --> 4 --> 5 --> 6 --> 7 --> loop ]

Model requirement: Both the orchestrator and all subagents MUST use Claude Opus 4.6 (1M context). When spawning subagents, explicitly specify model: "Claude Opus 4.6 (1M context)" to ensure the same model with full 1M token context window is used for iteration execution.

Context management: Each iteration generates substantial terminal output (build, test, coverage commands) that is never needed again. To prevent context rot:

• Subagent per iteration: When looping (CONTINUE), delegate the next iteration (Stages 2-7) to a subagent using Claude Opus 4.6 (1M context) model. The subagent gets a fresh context window, executes the full stage sequence, and returns ONLY the coverage scoreboard, loop decision, commit hash, and any errors. The parent context stays clean.
• Proactive compact: If subagents are unavailable, compact after every 3-5 iterations with focus: "keep coverage scoreboard, gap, next targets, completedFiles, gotchas; drop terminal output, build logs, and file contents."
• Required artifacts are never optional: Stage 3 plan table, Stage 5 verdict table, and Stage 7 scoreboard must always be emitted (by the subagent or inline), even in compact mode.

Allowed Stage Transitions (Explicit Matrix)

Current Stage	Allowed Next Stage(s)
Stage 0	Stage 1
Stage 1	Stage 2
Stage 2	Stage 3
Stage 3	Stage 4
Stage 4	Stage 5
Stage 5	Stage 6
Stage 6	Stage 7
Stage 7	Stage 2 (next iteration) OR End (Done/Stalled)

Transitions not listed above are invalid and must be treated as blocked.

Normative Rules (Single Source of Truth)

• R1 Sequential stages only: Do not skip stages. Stage 2 must be followed by Stage 3 before Stage 4.
• R2 Generation gate: Do not generate code before Stage 4. Stage 4 is blocked without a valid Stage 3 plan artifact.
• R3 Full-scope verification: Stage 1 and Stage 2 must run against the full project/workspace scope, not isolated modules unless dependency-complete equivalence is proven and documented.
• R4 Multi-language completeness: Stage 3 planning must cover all detected language modules. If a language has no actionable targets, record the reason explicitly.
• R5 Exploration is input, not approval: Discovery/subagent output cannot replace Stage 3 planning artifacts.
• R6 Verification is mandatory: Build verification cannot be skipped (Stages 1 and 6).
• R7 Explicit stage reporting: Every progress update must include iteration and stage labels.
• R8 Checkpoint behavior: Stage 0 and first-iteration Stage 3 checkpoints stop in interactive mode, continue in auto mode after emitting checkpoint output.
• R9 State persistence: Update .coverage-progress.json after each completed stage.

Mandatory Stage TODO Contract

Before Stage 0, create this checklist and use it as a hard gate:

See the "Mandatory Stage TODO Checklist" section in references/skill-templates.md.

Rules:

• Only one stage can be active at a time; do not advance with an unchecked TODO.
• Each TODO is bound to its stage instructions: execute ALL required steps in that stage before marking the TODO complete.
• Mark complete only when that stage's required output and completion checks are satisfied.
• If a stage fails, mark blocked with one-line reason and stop.
• Include TODO delta in each user-facing update.

Execution Integrity Guards (Prevent False Completion)

Only current-run evidence can close a TODO.

• Create runId (YYYYMMDD-HHMMSS-<short-branch>) and store it in .coverage-progress.json.
• Every stage artifact must carry the same runId.
• Memory/previous logs can prefill context but never count as proof.
• Resume only when branch + runId + prior stage artifacts all match; else restart from earliest incomplete stage.
• Narrative text is not evidence; missing required table/artifact means stage stays unchecked.
• For each stage start/end, print: runId, iteration, stage, TODO delta, and artifact names.
• If Stage 0 or first-iteration Stage 3 checkpoint output is missing, mark blocked and stop. In auto mode, output is still mandatory even though user confirmation is not.
• If Stage 4 starts without a Stage 3 plan artifact for the same runId and iteration, mark blocked and return to Stage 3.

Stage Artifact Contract (Machine-Checkable)

A stage is complete only when its required artifact exists for the current runId and iteration.

Stage	Required Artifact (must be emitted in output)
Stage 0	Context checkpoint table (languages/modules/commands/scope/branch/target)
Stage 1	Baseline verification summary (build/test/lint counts)
Stage 2	Coverage baseline table + priority targets table
Stage 3	Structured per-language plan table with TP IDs
Stage 4	Generated test file list mapped to TP IDs
Stage 5	Per-test verdict table (APPROVED/NEEDS REVISION/REJECT)
Stage 6	Before/after regression summary (tests + lint)
Stage 7	Coverage delta table + loop decision row
Pre-PR Gate	Post-fix verdict scorecard (per-file verdicts, dimension scores, fix summary, build+test verification)

Missing artifact => stage remains incomplete.

---

Stage 0: Context, Scope & Branch (runs ONCE)

Goal: Understand how the project builds, tests, and lints. Create the working branch.

Subagent usage (allowed in Stage 0):

• You MAY use a read-only subagent (for example Explore) to accelerate file/context discovery in Stage 0.
• Scope subagent tasks to discovery only (instructions, project files, test inventory, CI pipeline files, language detection).
• Do NOT delegate code generation, file edits, commits, or stage completion decisions to a subagent.
• You remain responsible for validating findings against actual files and producing the required Stage 0 checkpoint output.

1. Check memory and existing progress:

   • Read /memories/repo/test-gen-context-<repo-name>.md (derive <repo-name> from the repo root folder name) -- if it exists, load cached build commands, conventions, CI details. Skip steps 2-7 below (just verify with a quick build in Stage 1).
   • If memory tool access is unavailable and you must use shell checks, use the Memory path resolution rules above. Do not assume APPDATA path is authoritative.
   • If .coverage-progress.json exists, read it. If a branch is recorded, check it out (git checkout <branch>). Resume from the last incomplete stage -- do not repeat Stage 0.
   • If neither exists, proceed with full discovery below.

2. Read repo instructions (MANDATORY first step):

   • .github/copilot-instructions.md -- look for the ## Repo Context for AI Automation section first; it contains pre-curated build commands, test commands, coverage commands, CI pipeline details, and known gotchas specifically for AI automation. Use these values directly without re-discovering them.
   • AGENTS.md -- setup, code style, gotchas
   • If neither exists, read the root directory, README.md, and project config files

3. Extract from the instructions:

   • If ## Repo Context for AI Automation exists in copilot-instructions.md: read it fully and treat its values as authoritative. Skip manual discovery for any field already specified there.
   • Build command (e.g., dotnet build, npm run build, cargo build)
   • Test command (e.g., dotnet test, npx vitest run, pytest)
   • Lint/format command (e.g., dotnet format, npx eslint ., ruff check .) -- if available
   • Custom CI lint checks -- look for line-length validators, custom PowerShell/bash scripts in CI that enforce max line length or other code style rules beyond standard linters. Record these as additional lint commands.
   • Max line length -- check .editorconfig (), CI pipeline scripts (e.g., line-length validation steps), and linter configs. Record the discovered limit in memory.

3b. Discover ALL languages in the repository (MANDATORY): The skill must detect every language that has source code AND tests, not just one. Scan for:

• C#: *.sln, *.csproj files
• Rust: Cargo.toml, Cargo.lock files
• TypeScript/JavaScript: package.json with test scripts, jest.config.*, vitest.config.*
• Python: setup.py, pyproject.toml, pytest.ini, tox.ini
• C++: CMakeLists.txt, *.vcxproj

For EACH detected language, record:

• Build command
• Test command
• Coverage collection command (see references/code-coverage.md)
• Test framework

If the repo has multiple languages, create a module entry in .coverage-progress.json for EACH language. The skill runs through the full pipeline for each language module, and coverage is merged across all of them to match what CI reports.

Check the CI pipeline YAML to see how CI collects and merges coverage across languages. The skill must collect coverage for all languages locally and merge them using scripts/parse-cobertura.ps1 so that local and CI coverage numbers match.

4. Target scoping: Determine what the user wants to test. Skip: bin, obj, node_modules, generated code, lock files, DTOs, constants.

   • Stage 0 scope must be recorded per language module. If multiple languages are detected, do NOT collapse scope to one language in the Stage 0 checkpoint.

5. Read source files: Read full content only for files to be tested and their direct dependency interfaces.

6. Existing test inventory: Grep for existing test files to understand test patterns, naming conventions, assertion styles, and project structure.

   • CRITICAL — Source-to-test-project mapping: For every source project in scope, identify ALL existing test projects that reference or test it — regardless of naming convention. Test project names often differ from their source project (e.g., SystemActivities.UnitTest.csproj tests Workflow.SystemActivities.csproj). Search by <ProjectReference> targets, not just by name matching. Record the mapping in the Stage 0 checkpoint so Stage 4 never creates a duplicate test project for an already-tested source project.

7. CI pipeline check: Look for pipeline definitions (.yml, .yaml in .pipelines/, .azure-pipelines/, .github/workflows/). Note how tests are discovered and executed.

   • CRITICAL: Identify how CI collects coverage for EACH language and how reports are merged.
   • Extract the ACTUAL CI coverage commands, task names, flags, report paths, publish steps, and merge steps from pipeline files or repo automation docs. Do not substitute preferred local defaults unless CI explicitly uses them.
   • Note the exact flags, .runsettings, and exclusion patterns CI uses per language.
   • Record the CI coverage merge strategy in .coverage-progress.json (coverageMode: "merged").
   • If CI merges multiple languages into a single Cobertura report, the skill MUST replicate this locally.
   • If CI coverage behavior cannot be proven from pipeline files, repo automation docs, or checked-in scripts, mark coverage mode as provisional, record the missing evidence, and tell the user that local coverage may diverge from CI until verified.
   • Check copilot-instructions.md for any repo-specific actions required when a new test project is created (e.g., CloudTest map file registration, workspace config updates, explicit project lists). Record the actions and target files.

• Default target is 100 unless the user explicitly requests a different target.
• Default maxIterations is 100. The user may override with a lower value.

11. Save context to memory: Write /memories/repo/test-gen-context-<repo-name>.md (derive <repo-name> from the repo root folder name) with all discovered information (build commands, test framework, conventions, CI pipeline, .runsettings, gotchas). See the "Memory Context Template" section in references/skill-templates.md. This ensures future sessions start with full context.

[STOP] CHECKPOINT: Present to the user:

• Languages detected and modules per language
• Files to test and files excluded (per language)
• Build, test, coverage, and lint commands discovered (per language)
• Target framework per language
• CI pipeline info (including the exact coverage collection commands/tasks/settings, exclusions, report paths, and coverage merge strategy)
• Repo-specific post-creation actions from Stage 0 context (e.g., CI registration files, CloudTest map updates, workspace configs)
• Branch name created
• Coverage target
• Module manifest (for monorepos / multi-language repos)

Checkpoint validity rule:

• If CI coverage collection details are missing, inferred, or only partially known, Stage 0 must label coverage as provisional and list the missing evidence explicitly. Do not present local coverage numbers as CI-equivalent unless the CI collection path has been verified.

Checkpoint validity rule:

• If multiple languages were detected but the checkpoint scope is reported as single-language (for example "C# module only"), Stage 0 is INCOMPLETE and must be redone before Stage 1.

In interactive mode: End your response and wait for user confirmation. In auto mode: report the checkpoint, then continue to Stage 1.

---

Stage 1: Pre-Flight (Build + Test + Lint)

Verify the codebase is healthy before generating anything. Run for ALL language modules discovered in Stage 0.

Note: All required commands and details are already captured in Stage 0 Repo Context memory (/memories/repo/test-gen-context-<repo-name>.md).

1. Clean and build locally (ALL languages): clean stale build artifacts before building (dotnet clean, cargo clean, rm -rf dist/, npm run clean, etc.) to prevent inflated coverage from outdated binaries. Then run the build command for EVERY module from repo context memory. If any build fails: diagnose, report, STOP.

2. Run existing tests (ALL languages): record per-language total, passed, failed, skipped. If tests fail, report and wait for acknowledgment.

3. Run linter/formatter (if discovered in Stage 0): record existing lint warnings/errors as baseline. Generated tests must not introduce new violations.

4. Record baseline state: exact counts of passing tests, failing tests, skipped tests, lint violations.

---

Stage 2: Coverage Baseline

Reference: Read references/code-coverage.md for tool-specific commands, parsing, and multi-language report merging.

Note: All required coverage commands and settings are already captured in Stage 0 Repo Context memory (/memories/repo/test-gen-context-<repo-name>.md).

Execution guard for stored coverage commands (mandatory): execute the stored command as-is; if quoting fails, fix only shell escaping (not command intent), and prefer $env:TEMP for coverage outputs.

1. Create a temp directory for coverage output (never write into the repo).
2. Honor coverage exclusions/settings first:
   • If the repo has .runsettings, coverlet config, .nycrc, or coverage.config, read exclusions before collecting coverage.
   • Use the same settings as CI when running local coverage.
   • Record which coverage settings file was used in .coverage-progress.json.
3. Collect coverage for EVERY language module discovered in Stage 0 (not just one):
   • For each module, run its coverage command from repo context memory and produce a Cobertura XML.
   • Run coverage for ALL detected languages, not just one.
   • Store each language's Cobertura XML separately (e.g., <language>-coverage.cobertura.xml).
4. Merge all Cobertura reports into a single combined report (mirrors CI behavior):
   • Use scripts/parse-cobertura.ps1 with ALL report files as input (it merges automatically):

     $allReports = Get-ChildItem $coverageDir -Recurse -Filter "*.cobertura.xml" | ForEach-Object { $_.FullName }
     .\scripts\parse-cobertura.ps1 @allReports
     

   • The merged coverage number is the baseline, not any single language's number.
5. Parse merged results into structured data.
6. Record baseline: overall line/branch coverage, per-file breakdown (all languages), uncovered line ranges.
7. Update mergedBaseline in .coverage-progress.json and each module's individual baseline.
8. Classify uncovered code by priority (P0-P3), while excluding known exclusions (constants, DTOs, properties, logging, simple constructors, dead code):
   • P0 -- Critical: business logic with < 50% coverage
   • P1 -- Critical: exception handlers, error paths, retry logic, catch blocks
   • P2 -- Medium: utility methods with < 50% coverage
   • P3 -- Low: branch gaps in already-covered methods
9. Exclude from gap list (do NOT target these for tests):
   • Constants, constant classes, constant fields
   • Default value assignments
   • Auto-properties (get/set only)
   • DTO/POCO classes, records, and data containers (properties only, no logic)
   • Logging convention code, logger providers, log formatters

• Match the actual CI collector/tool choice per language before running local coverage (for example built-in Code Coverage, XPlat Code Coverage, dotnet-coverage, Jest/Vitest coverage reporters, pytest --cov, cargo-llvm-cov).
• Match CI settings files, include/exclude patterns, output formats, report paths, and publish-time merge assumptions. - If CI merges N language reports, local baseline must also merge N reports.
• If CI settings are unknown, record that explicitly in output and mark the result provisional; do not claim parity with CI.

11. Clean up temp directory.

Stage 2 output: Present a summary table showing where the skill will focus next:

See the "Stage 2 Output Template" section in references/skill-templates.md.

Include rows for EVERY detected language. Show ALL actionable targets (every file/module where coverage can be increased) plus any notable exclusions. Do NOT cap the list at any fixed number — the plan and each iteration must cover the maximum possible files.

COMPLETION CHECK: If your Stage 2 output does not contain the Priority Targets table, you have not completed Stage 2. The raw coverage numbers alone are not enough -- the agent and user need to see the prioritized file list before planning.

This coverage data is the PRIMARY INPUT for test planning.

If tests cannot run (build failures, missing deps), note the blocker, skip this stage, proceed without baseline. If coverage is already 90%+, focus only on remaining hotspots.

---

Stage 3: Plan

Reference: Read references/test-planning.md for prioritization rules, plan format, and categories.

This is a SEPARATE stage. Do NOT generate code here.

1. Use coverage gaps from Stage 2 as PRIMARY input, prioritized P0-P3. 1a. Build the Stage 3 plan across ALL detected language modules in .coverage-progress.json, not just the current/lowest-coverage language. 1b. Batch multiple files per iteration: Plan tests for 10-15 source files per iteration (grouped by module or dependency proximity). More files per iteration = fewer loop cycles = more coverage per session. Do not plan for only 1 file when multiple actionable files exist.
2. Critical path first:
   • Exception handlers and catch blocks --> MUST have tests
   • Error return paths --> MUST have tests
   • Retry/fallback logic --> MUST have tests
   • Validation logic --> MUST have tests
   • Happy path business logic --> standard coverage
3. Do NOT plan tests for: constants, default values, properties, DTOs, logging, simple constructors, dead code, already-covered code. 3b. Behavioral deduplication (MANDATORY): Before planning tests for any source file, read the existing test files that cover it. If an existing test already validates the same scenario/behavior (even if lines are marked uncovered due to mocking differences), do NOT plan a duplicate. New tests must add incremental behavioral value — covering a genuinely untested code path or scenario — not re-test what existing tests already verify.
4. If deferring a plan item, document WHY (e.g., "requires integration test", "testability blocker -- static factory with no seam", "external dependency cannot be mocked"). Every TP-<SourceFile>-<ShortName> ID must be either implemented or have an explicit skip reason.
   • ID format: TP-<SourceFile>-<ShortName> where <SourceFile> is the short source file name (no extension, no path) and <ShortName> is a ≤5-word camel-case description of the scenario (e.g., TP-OrderService-PaymentFailurePath, TP-LeaseHook-NullInputReturnsError).
5. Each test case: ID, Name, Priority, Coverage Target (file:lines), Arrange, Act, Assert.
6. Map every test to a specific coverage gap.
7. Flag latent bugs with WARNING.

Plan output: structured markdown table with ID, Language, Test Name, Priority (P0-P3), Coverage Target, Arrange, Act, Assert.

Stage 3 Plan Quality Gate (MANDATORY before Stage 4):

• Verify each planned test has a meaningful assertion strategy (not coverage-only / not assert-free).
• Verify planned tests target real behavioral contracts — not assumed behavior. Each test's expected outcome must be derivable from the source code, not guessed.
• Verify planned tests comply with "Do NOT generate" exclusions.
• Verify each planned test maps to a concrete Stage 2 coverage gap.
• Verify the plan includes entries for every detected language module that still has actionable uncovered targets, or explicitly records why a language has no planned items.
• If any planned item violates quality/exclusion rules, revise the plan before proceeding.

[STOP] CHECKPOINT: Show the complete per-language test plan. Include a short language coverage summary (planned items per language, or explicit "no actionable targets" reason). In interactive mode: end your response and wait for user confirmation before proceeding to Stage 4. In auto mode: report the checkpoint and continue to Stage 4 automatically.

Stage 4: Generate

Reference: Read references/test-generation.md for framework rules, namespace verification, test framework compatibility, Moq workarounds, metadata, and project file rules. Read references/test-quality.md Part 2 for anti-patterns to avoid.

Canonical Gate Check (single source): You must have a written, quality-gated Stage 3 plan for the current iteration. Required:

• TP IDs for each planned test
• Structured Stage 3 per-language plan table
• Stage 3 quality gate pass
• Current runId and iteration number
• Plan entries for all detected language modules

If any are missing, stop and return to Stage 3.

Step 0 — Think Before Generating (MANDATORY per source file):

Before writing ANY test code for a source file, reason explicitly:

1. Read the source file fully — understand its purpose, dependencies, and behavioral contracts.
2. State assumptions — list what you believe the method/class does and what constitutes correct vs incorrect behavior. If uncertain about any behavior, flag it — do not guess and run with it.
3. Surface ambiguities — if multiple interpretations of behavior exist (e.g., "does null input throw or return empty?"), check the source code, existing tests, or documentation to resolve. If unresolvable, pick the interpretation supported by the code and note it as a comment in the test.
4. Identify tradeoffs — if a simpler test approach exists (fewer mocks, less setup), prefer it. If 200 lines of setup could be 50, rewrite the approach before generating.
5. Push back on the plan — if a planned test item is untestable, redundant, or would produce a low-value test, skip it with a documented reason rather than generating junk.

This step produces no file output — it is internal reasoning that makes generated code accurate on the first attempt. Skip this step only for trivially simple tests (e.g., single-line validation methods).

1. Generate compilable test code implementing every planned test case.
2. Follow AAA pattern (Arrange-Act-Assert) with explicit comments.
3. Test names: MethodName_Scenario_ExpectedBehavior. 3b. Plan ID comments (RECOMMENDED): Add a comment mapping each test method to its plan item: // TP-<SourceFile>-<ShortName>. This aids traceability but missing TP comments do not block the quality gate or Stage 5 review. 3c. Line length limit (MANDATORY): Keep all generated lines within the repo's max line length (from .editorconfig or CI checks). Break long lines — split string literals, chain method calls across lines, use intermediate variables. This is a common CI gate failure.
4. Read actual source files before generating -- verify namespaces, types, method signatures. Never assume.
5. Match the repo's test framework AND assertion library exactly -- detect from existing test projects (NUnit, MSTest, xUnit, Jest, pytest, etc.). Also detect the assertion library (FluentAssertions .Should(), Shouldly, built-in Assert.*). Use whichever the repo already uses — do NOT mix assertion styles. Follow the version-specific API rules from test-generation.md.
6. Apply Moq expression tree workarounds for optional parameters.
7. If creating a new .csproj: apply project file rules, set <ProjectUsageType>UnitTest</ProjectUsageType>.

Project placement: NEVER create a .csproj in the same folder as another project. Before creating a test project, discover the repo's existing convention:

1. Search for existing *.Tests.csproj or *.UnitTests.csproj files and note where they live relative to their source projects.
2. Check if a test project already exists for the source project — search ALL existing test .csproj files for <ProjectReference> elements pointing to the source project. Test project names frequently differ from their source (e.g., SystemActivities.UnitTest.csproj tests Workflow.SystemActivities.csproj). If an existing test project already references the source, add new tests to THAT project instead of creating a new one.
3. Match that pattern exactly. Common conventions (in order of prevalence):
   • test/<Source>.Tests/ (separate test root: src/MyService/ --> test/MyService.Tests/)
   • src/<Source>.Tests/ (sibling under src: src/MyService/ --> src/MyService.Tests/)
   • tests/<Source>.Tests/ (plural test root)
   • <Source>/tests/ (tests subfolder per project)
4. If no existing test projects exist, prefer the test/ or tests/ root convention if those directories exist, otherwise use sibling folder under src/.
5. Check the target directory contents before creating -- if any .csproj already exists there, choose a different folder.

Traceability attributes (MANDATORY):

• NUnit: [Category("AutoGenerated")] and [Category("CopilotSkill:autocoverage")]
• MSTest: [TestCategory("AutoGenerated")] and [TestCategory("CopilotSkill:autocoverage")]
• xUnit: use [Trait("Category", "AutoGenerated")] and [Trait("Category", "CopilotSkill:autocoverage")]
• Jest/Vitest: add // @category AutoGenerated CopilotSkill:autocoverage at top of file
• pytest: use @pytest.mark.auto_generated marker

Placement rule: Always place traceability attributes on each new test method, never on the class. This ensures only generated methods are tagged, regardless of whether the class is new or pre-existing.

File organization: One test class per source class, one test file per test class. Never combine test classes for unrelated source classes in a single file.

• Test file name must match the source class: OrderService.cs → OrderServiceTests.cs.
• NEVER prefix file or class names with tool/skill/iteration identifiers (AutoCoverage_, Iter<N>_, Generated_, etc.). Traceability goes in attributes and comments, not filenames. See references/test-generation.md "File Naming" and "Coexistence with Existing Test Files" sections.
• If a test file already exists for the source class, add methods to it or create <SourceClass>ExtendedTests.cs — never a tool-prefixed duplicate.
• If a source file contains multiple public classes, each gets its own test file.
• Never create a single "catch-all" test file that tests multiple unrelated classes.

Do NOT generate tests that:

• Re-compute expected values from production logic (tautological)
• Exist only to increase coverage without validating behavior (coverage-only tests)
• Have no meaningful assertions (including assertion-free tests or exception-only smoke tests)
• Only assert IsNotNull without checking values
• Mock the class under test
• Use reflection to test private methods
• Have 50+ lines of setup for one assertion
• Duplicate production code in the test
• Duplicate behavior already tested by existing tests (same scenario, same assertions on same class)
• Test constants, DTOs, records, constructors, properties, logging, or [Obsolete] classes/methods
• Target methods with unbounded while loops or gRPC/async stream consumers — they deadlock test runners
• Test pure delegation methods (return await x.Method()) — only proves the mock works
• Assert on log-message string fragments — breaks on any message rewording

---

Stage 5: Review + Finalize

Reference: Read references/test-quality.md for the full review checklist and quality gate. Read references/test-finalization.md for the compliance checklist.

This stage has TWO mandatory parts. Completing only Part A is a VIOLATION. You MUST complete Part B before proceeding to Stage 6.

Part A -- Build: Build the test project. Fix all compilation errors (StyleCop, analyzers, missing usings, wrong APIs). Iterate until clean build. Do not proceed to Part B with broken code.

Part B -- Quality Review (MANDATORY -- build passing is NOT enough): After the build passes, evaluate EACH generated test against the checklist in test-quality.md Part 3. Check every test for:

• Reasoning accuracy — does the test demonstrate correct understanding of the source behavior? If assertions test the wrong expected values or misinterpret method contracts, the test is REJECT regardless of whether it passes.
• Assertion quality (HIGH/MEDIUM/LOW) -- are assertions validating behavior or just checking not-null?
• Coverage-only pattern -- does the test exist only to execute lines without validating outcomes?
• Assertion presence -- does the test include at least one meaningful behavioral assertion?
• Tautological patterns -- does any test re-compute expected values from production logic?
• Exclusion violations -- does any test target constants, DTOs, constructors, properties, or logging?
• Mock correctness -- is the class under test being mocked? Are mocks set up and verified properly?
• Edge cases -- null, empty, boundary inputs covered?
• Determinism -- any time/random/network dependence?

Produce a per-test verdict table:

Test Name	Plan Item	Assertion Quality	Issues	Verdict

Verdicts: APPROVED / NEEDS REVISION / REJECT.

Part C -- Quality Gate (MANDATORY HARD GATE before Stage 6): Run the quality gate from test-quality.md Part 4 against all generated tests in this iteration. Produce the scorecard:

Dimension	Target	Actual	Status
Assertion Density	>= 1.5/test	X.X	PASS/FAIL
Assertion Quality	>= 60% HIGH	X%	PASS/FAIL
Determinism	100%	X%	PASS/FAIL
Flakiness	0 patterns	N	PASS/FAIL
Exclusion Compliance	0 violations	N	PASS/FAIL
Tautological Tests	0%	X%	PASS/FAIL

GATE RULE: ALL dimensions must report PASS (not FAIL, not CONDITIONAL PASS). Any FAIL dimension blocks Stage 6 unconditionally.

Rejection/Revision Loop (mandatory until PASS):

1. For each FAIL dimension, identify contributing tests from the verdict table
2. Remove all REJECT tests that caused FAIL dimensions
3. For each NEEDS REVISION test marked in verdict table, apply fixes from references/test-finalization.md
4. If FAIL dimension persists after fixes, remove those tests too
5. Rebuild test project and re-run quality gate
6. Repeat until ALL dimensions report PASS
7. This loop runs up to 3 iterations per iteration cycle. If PASS not achieved by iteration 3, mark the iteration as STALLED and move to next batch

COMPLETION CHECK: Stage 5 is NOT complete until ALL THREE parts are present:

• Part A: Build clean
• Part B: Verdict table with per-test results
• Part C: Quality gate scorecard with ALL dimensions PASS (not CONDITIONAL, not FAIL)

STAGE 6 ENTRY GATE: Stage 6 is BLOCKED if:

• Quality gate scorecard is missing, OR
• Any dimension shows FAIL or CONDITIONAL PASS status, OR
• Verdict table shows rejected/unresolved NEEDS REVISION tests

If any gate condition is true: DO NOT proceed to Stage 6. Loop back to Part B and apply rejection/revision fixes above.

Stage	Status
...	...
Stage 5: Build + Quality Review	PASS Build clean | Quality: N approved, N needs-revision (fixed), N rejected | Gate: ALL DIMENSIONS PASS

---

Stage 6: Post-Generation Verification (Build + Test + Lint)

After review and fixes, verify everything end-to-end.

1. Build the entire solution/workspace (not just the test project).
2. Run ALL tests (existing + new):
   • All previously-passing tests must still pass (no regressions)
   • All new tests must pass
   • If a new test fails after 2 fix attempts: remove it and document why
3. Run linter/formatter (MANDATORY if lint/format command exists in Stage 0 context):
   • Run the EXACT lint/format command from Stage 0 context against all new/modified test files.
   • For repos with Prettier: run the Prettier check command (e.g., npx prettier --check) against generated files.
   • For repos with ESLint: run ESLint against generated files.
   • For repos with dotnet format: run dotnet format --verify-no-changes.
   • Run any custom CI lint checks discovered in Stage 0 (e.g., line-length validators, custom scripts). These are often separate from standard linters and catch issues like max line length that dotnet format does not enforce.
   • If violations found: fix them and re-run until clean.
   • Stage 6 is NOT complete if the lint/format check was skipped when a command exists.
   • If lint/format was not discovered in Stage 0, record "no lint command found" explicitly.
4. Compare counts:
   • Before: X passed, Y failed, Z skipped, W lint violations
   • After: X+N passed, Y failed (same or fewer), Z skipped, W lint violations (same or fewer)
   • Report: "Added N new passing tests. No regressions. No new lint violations."

---

Stage 7: Measure, Commit, Loop Decision

Reference: Read references/code-coverage.md for commands, parsing, and multi-language report merging.

Stage 7 runs four steps in order. Every step must complete before the next begins.

Step A — Measure

1. Collect coverage for ALL language modules (not just this iteration's language).
2. Merge all Cobertura reports (same strategy as Stage 2 / CI).
3. Compute and emit the coverage scoreboard — this is the primary Stage 7 output:

Metric	Original Baseline	Current (merged)	Total Gain	Target	Gap
Lines	XX.X%	XX.X%	+X.X%	100%	X.X%
Branch	XX.X%	XX.X%	+X.X%	100%	X.X%

• Original Baseline = coverage at run start (iteration 1 Stage 2). Set once, never overwritten (originalBaseline in manifest).
• Gap = Target - Current. If Gap > 0, the run is not done.
• This-iteration delta: Iteration Start: XX.X% → Iteration End: XX.X% (+X.X%).
• Per-language breakdown (if multi-language): include Current, Delta, Gap to Target per module.
• Always report actual percentages. Never use "covered" or approximate language.

4. If coverage did NOT increase this iteration: warn and explain which tests may be redundant.
5. If any file's coverage decreased: investigate before proceeding.
6. Run quality gate from references/test-quality.md Part 4.

Step B — Persist State (BLOCKING — must complete before Step C or D)

7. Update .coverage-progress.json before committing or deciding:
   • originalBaseline: set ONCE in iteration 1. Never overwrite.
   • baseline: start-of-iteration coverage.
   • current: end-of-iteration coverage.
   • mergedCurrent: merged values across all languages.
   • gap: target - mergedCurrent.lines.
   • Increment totalIterations. Update completedFiles, filesRemaining, lastUpdated.
   • Verification: after writing, read back mergedCurrent and gap from the file to confirm the write succeeded. If the file was not updated, Stage 7 is blocked.
8. Append new learnings to /memories/repo/test-gen-context-<repo-name>.md (if any). Skip if nothing new.
9. Proactive compact (if running inline, not as subagent): After every 3rd iteration completed in this session, trigger a context compact focused on: "keep coverage scoreboard, gap, .coverage-progress.json state, next targets, gotchas. Drop all terminal output, build logs, file contents, and stage-status tables from previous iterations."

Step C — Commit

9. Pre-commit gate: Stage 6 lint/format must have been run (when a lint command exists). If not, re-run Stage 6 step 3 before committing.
10. Stage test files only. Never stage .coverage-progress.json or production code.
11. Commit: test(<scope>): add unit tests for <component> [iteration N] with coverage delta in the message.
12. Record commit hash in .coverage-progress.json commits array.

Step D — Loop Decision

Gate: Step D cannot execute unless Step B has written mergedCurrent, gap, and totalIterations to .coverage-progress.json. If these fields are missing or stale, return to Step B.

13. Recompute actionable inventory across ALL languages/modules. Produce the Remaining Actionable Targets table:

Language	Module	Actionable Files	Excluded/Blocked	Next Candidates

Narrative claims are not evidence. Only this table is evidence.

14. Execute the decision algorithm:

gap = target - mergedCurrent.lines
globalActionable = SUM(actionableFiles) across ALL modules

IF gap <= 0:                    decision = DONE
ELIF globalActionable == 0:     decision = STALLED
ELIF totalIterations >= maxIterations: decision = STALLED
ELSE:                           decision = CONTINUE

15. Branch on decision:

• CONTINUE: Unconditional branch — start the next iteration immediately.

  • Preferred: delegate to subagent using Claude Opus 4.6 (1M context) model and the prompt template below (defined once, reused every iteration):

    Model: Claude Opus 4.6 (1M context). Execute iteration N+1 (Stages 2-7) on branch <branch>. Read .coverage-progress.json and repo context memory. Target: <target>%. Current: <current>%. Gap: <gap>%. Batch 10-15 files. Execute ALL stages in order: Stage 2 (coverage baseline), Stage 3 (plan with TP IDs), Stage 4 (generate tests), Stage 5 (build + quality review + quality gate), Stage 6 (full verification + lint), Stage 7 (measure + commit + loop decision). At Stage 5, read references/test-quality.md and references/test-finalization.md — apply EVERY check from both files. Honor .editorconfig and repo coding standards in all generated code. Ensure traceability: every new test method gets [TestCategory("AutoGenerated")] at method level (never class level). Add // TP-<SourceFile>-<ShortName> comments where practical (recommended, not blocking). Only commit APPROVED tests with ALL-PASS quality gate; delete the rest before commit. NEVER generate tests for: logging conventions, simple constructors, DTOs, constants, properties, default values, [Obsolete] code, generated code, pure delegation methods (return await x.Method()), or methods with unbounded while/gRPC async stream loops. NEVER assert on log-message string fragments. Use $env:TEMP for coverage output, NEVER a repo subdirectory. Update .coverage-progress.json before committing. If spawning further subagents (multi-language fan-out), use Claude Opus 4.6 (1M context) model. Return RETAIN block (scoreboard table, commit hash, decision, manifest fields) and VERIFY-THEN-DISCARD block (plan table, verdict table, quality gate scorecard, errors).

    RETAIN format the subagent must use:

    | Metric | Baseline | Current | Gain | Target | Gap |
    | Lines  | XX.X%    | XX.X%   | +X.X%| 100%   | X.X%|
    Commit: <hash>  Decision: CONTINUE/DONE/STALLED
    

  • Multi-language fan-out: If .coverage-progress.json has 2+ modules with actionable files, spawn one subagent per language in parallel using Claude Opus 4.6 (1M context) model (e.g., C# subagent + TypeScript subagent simultaneously). Each subagent targets only its language module. Parent collects both RETAIN blocks, merges coverage, then decides CONTINUE/DONE/STALLED on the merged result.

Stage 7 is incomplete without both the coverage scoreboard AND the Loop Decision row.

---

Exclusion Rules (ALL stages)

Do NOT generate tests for:

Exclusion	Rationale
Constants and constant fields	Compile-time fixed; no behavior
Default value assignments	No logic; just initialization
Auto-properties (get/set only)	No behavior beyond storage
DTO/POCO classes	Data containers with no logic
Logging conventions	Infrastructure concern, not business logic
Simple constructors	Assignment-only; no branching
Generated code files	Maintained by tooling

Exception: constructors with branching logic (if/switch/validation) ARE eligible.

---

No-Refactoring Rule (ALL stages)

The following are STRICTLY PROHIBITED during test generation:

• Renaming folders
• Moving files to different directories
• Renaming project files (.csproj, .vbproj, etc.)
• Renaming assembly names
• Changing namespaces in production code
• Restructuring project layout
• Adding/removing package references in production projects (test projects are OK)
• Modifying production code in any way

If any of these seem necessary: STOP, report to the user, let them decide. Do not propose refactoring plans.

---

CI Pipeline Readiness

Reference: Read references/ci-pipeline-checklist.md.

Before delivering output:

1. Check pipeline definitions for test project auto-discovery patterns
2. Ensure new test project name matches the discovery pattern
3. Add test project to .sln if applicable: dotnet sln add <TestProject.csproj>
4. Execute any repo-specific post-creation actions recorded in Stage 0 context (e.g., CloudTest map file registration, workspace config updates, explicit project lists)
5. Report whether CI will automatically pick up the new tests and whether any manual registration was required, using Stage 0 context as the source of truth

---

Gotchas

See references/gotchas.md for known anti-patterns, symptoms, and fixes.

---

Output (Per Iteration)

Each iteration through Stages 2-7 produces:

Do NOT include the final PR description in per-iteration output.

See the "Per-Iteration Output Template" section in references/skill-templates.md.

Final Summary (after all iterations)

See the "Final Summary Output Template" section in references/skill-templates.md.

Pre-PR Quality Gate (MANDATORY before PR Creation)

A quality sweep over only the test files generated during this run that executes once, after the loop terminates (DONE or STALLED), before any push or PR. Stage 5 reviews each iteration's batch in isolation; this gate re-evaluates all files generated across iterations together and automatically fixes every issue it finds — catching cross-iteration drift, inconsistencies, and problems that only surface at aggregate scope.

Scope: Only test files created or modified across all iterations of this run (tracked in .coverage-progress.json completedFiles). Do NOT audit pre-existing test files that were not generated by this run.

Checklist: Stage 5 quality checklist (references/test-quality.md Parts 1-4) plus references/test-finalization.md compliance checklist — applied branch-wide. Same bar, wider lens.

Subagent: Audit → Fix → Verify

Delegate to a subagent (Claude Opus 4.6 (1M context)) that audits, fixes, and verifies in a single pass:

Model: Claude Opus 4.6 (1M context). You are a test quality enforcer. Read references/test-quality.md (all Parts) and references/test-finalization.md. Read ALL test files generated across all iterations of this run (listed in .coverage-progress.json completedFiles). Do NOT audit pre-existing tests that were not generated by this run. For each file, evaluate against both checklists. Then:

Phase 1 — Audit: Produce a per-file verdict table and quality gate scorecard (see dimensions below). Identify every issue with file:line references.

Phase 2 — Fix: For every issue found, apply the prescribed fix from references/test-quality.md (anti-patterns → remediation) and references/test-finalization.md (compliance checklist). Remove tests that violate exclusion rules entirely; fix everything else in-place.

Phase 3 — Verify: After all fixes, build the full solution and run all tests. Confirm zero regressions and zero new lint violations. Re-score the quality gate. If any dimension still FAILs, loop back to Phase 2 (max 3 fix-verify cycles).

Return exactly:

1. Per-File Verdict Table (post-fix state):

File	Tests	Assertion Quality (H/M/L)	Issues Fixed	Remaining Issues	Verdict

2. Quality Gate Scorecard (post-fix state):

Dimension	Target	Actual	Status
Assertion Density	>= 1.5/test		PASS/FAIL
Assertion Quality	>= 60% HIGH		PASS/FAIL
Determinism	100%		PASS/FAIL
Flakiness	0 patterns		PASS/FAIL
Exclusion Compliance	0 violations		PASS/FAIL
Tautological Tests	0%		PASS/FAIL
Verify-Only Tests (no Assert)	0		PASS/FAIL
Deprecated Patterns ([ExpectedException])

Gate Rules

• APPROVED (all dimensions PASS, all files APPROVED) → proceed to PR Creation.
• CONDITIONAL PASS / REJECT after max fix cycles → proceed to PR Creation with the final scorecard as a ## Quality Gate disclosure in the PR description listing unresolved findings.
• Commit fixes: stage only test files. Message: test(<scope>): pre-PR quality fixes. Record commit hash in .coverage-progress.json.
• Record final scorecard in .coverage-progress.json under prQualityGate (overall verdict + dimension scores).

---

PR Creation

When the Pre-PR Quality Gate completes (APPROVED or max fix iterations exhausted):

1. Push the branch: git push -u origin <branch-name>

2. Render the PR description using references/pr-description-template.md. Do NOT inline a custom format.

3. Write the rendered description to a temp file, then pass it to az repos pr create:

   $prDescFile = Join-Path $env:TEMP "pr-description-$runId.md"
   Set-Content -Path $prDescFile -Value $prDescription -Encoding utf8
   # Create (new PR):
   az repos pr create --title "test(<scope>): add unit tests [auto-generated]" --description "@$prDescFile" --source-branch <branch> --target-branch <default-branch> --draft --output json
   # Update (existing PR):
   az repos pr update --id <pr-id> --description "@$prDescFile"
   Remove-Item $prDescFile -ErrorAction SilentlyContinue
   

   The @<filepath> syntax tells az CLI to read the description from a file — this avoids shell argument length limits and special character escaping issues that cause empty descriptions.

4. If az CLI is not available, push branch only and output the rendered description for manual paste.

5. Record the PR ID in .coverage-progress.json so resumed runs update the same PR.

6. If STALLED — post "Why Stalled & How to Improve" as a PR comment: The full stall analysis is too large for the PR description (ADO character limits). Post it as a separate PR comment thread so reviewers see actionable next steps without description bloat.

   • Build the comment body from stallAnalysis in .coverage-progress.json.
   • Use repo_create_pull_request_thread (ado MCP) or az repos pr thread create.
   • Comment format (see template below).
   • The PR description contains a short pointer: "See the Why Stalled & How to Improve PR comment below."

   Comment template:

   ## Why Stalled & How to Improve
   
   **Stalled at XX.X% line coverage** (target: XX.X%, gap: X.X%)
   
   | Category | Files | Action to Unblock | Effort | Est. Gain |
   |----------|-------|-------------------|--------|----------|
   | Testability blocker | `[<file1.cs#Lnn>](<url>)`, `[<file2.cs#Lnn>](<url>)` | Extract interface / add DI seam for `<Symbol>` | S | +X.X% |
   | External dependency | `[<file3.cs#Lnn>](<url>)` | Wrap `<ExternalCall>` behind abstraction | M | +X.X% |
   | Integration test needed | `[<file4.cs#Lnn>](<url>)` | Add integration test for `<Component>` | L | +X.X% |
   | Quality gate rejection | `[<file5.cs#Lnn>](<url>)` | Refactor to make assertions meaningful | S | +X.X% |
   | Dead/unreachable code | `[<file6.cs#Lnn>](<url>)` | Remove dead code (reduces denominator) | S | +X.X% |
   | Max iterations reached | N files remaining | Re-run with higher `maxIterations` | None | +X.X% |
   
   **Effort**: S (< 1 hr) · M (1-4 hrs) · L (> 4 hrs / architectural)
   
   ---
   Categories: testability blocker · external dependency · integration test needed · quality gate rejection · dead/unreachable code · max iterations reached
   

---

Post-PR Pipeline Monitoring

After PR creation, monitor CI and self-heal using ado MCP server tools.

Prerequisites

The ado MCP server must be configured. Add to ~/.copilot/mcp-config.json (or VS Code MCP settings):

{
  "mcpServers": {
    "ado": {
      "command": "agency",
      "args": ["mcp", "ado"]
    }
  }
}

Key tools (server: ado):

• repo_get_pull_request_by_id — PR details, merge status
• pipelines_get_builds — find PR build (branch: refs/pull/<prId>/merge, requires repo GUID)
• pipelines_get_build_status — build result with stage/job breakdown
• pipelines_get_build_log — list all log entries for a build
• pipelines_get_build_log_by_id — read a specific log by ID (supports startLine for large logs)
• pipelines_run_pipeline — re-queue a pipeline run
• repo_list_pull_request_threads — CI-posted comments (test results, coverage reports)

Workflow

1. Find build: pipelines_get_builds with refs/pull/<prId>/merge. Check result via pipelines_get_build_status.

2. On failure — diagnose:

   • pipelines_get_build_status → find which stage/job failed
   • pipelines_get_build_log → list log entries, identify the failed step's log ID
   • pipelines_get_build_log_by_id → read the actual error output

   Type	Action
   Build/test error in files from this PR	Fix locally, verify against references/test-quality.md and references/test-finalization.md, rebuild, re-run tests, push (auto-retriggers)
   Error in files NOT modified by this PR	Report to user — do not fix
   Timeout	Report to user — cannot self-heal
   Infra/agent issue	Re-queue via pipelines_run_pipeline or report

3. Fix-push-monitor loop: max 3 cycles. After 3 failures, report to user.

4. On success: repo_get_pull_request_by_id to confirm merge readiness. PR is ready for review.