/factory-review

name: factory-review
description: Use when reviewing PRs for severity-ranked policy compliance against REVIEW.md, babysitting agent PRs to merge, or self-healing Important findings before a human sees them.

factory-review

What this skill does

`factory-review` is the PR-review compliance engine of the software factory. It acts as the automated component of **The Great Filter**, reviewing Pull Requests against organizational policy-as-code (`REVIEW.md`) and babysitting agent-opened PRs until they are ready for merge.

It operates as a **Kind-B control-plane skill** integrated with the PR hosting provider (GitHub / GitLab) via the tracker-agnostic integration layer (`factory-mission/references/tracker-integration.md`).

In `--self-heal` mode, it enters a **three-sub-agent converge loop** mirroring `factory-mission` Phase 5's test/code/converge pattern. Three separate sub-agents — Review Agent (read-only), Fix Agent (writeable src/), Converge Agent (independent judge) — are dispatched per iteration via lane-based dispatch, communicating only through the comment bus. The converge step returns `DONE` / `CONTINUE` / `SPEC_CORRECTION_NEEDED`, bounded by a circuit breaker and score-regression counter.

---

When to use

• Before any PR is merged, to run identical, consistent compliance checks.
• To have the agent automatically address reviewer comment threads and push fixes.
• To manage agent-opened PRs (sweeping unresolved threads, resolving failing tests) until they are ready for final sign-off.
• With `--self-heal` to proactively fix Important findings before a human reviews the PR.

**When NOT to use**:

• To evaluate test execution correctness (use `factory-mission` / evals judges instead).
• To bypass branch protection (this skill **never approves or merges PRs**).

---

Process

1. Policy-as-Code Configuration

1. Read the `REVIEW.md` file from the repository root. If absent, create a default template (see `references/review-policy.md`). 2. The policy defines:

• **Review passes**: Bugs & logical errors, security vulnerabilities, and compliance against design documents (`docs/adlc/product/PRD.md`/`docs/adlc/architect/AD.md`).
• **Severity weights**: What constitutes an *Important* block (e.g., memory leak, security risk, spec deviation) vs. a *Nit* (formatting, style).
• **Skip lists**: Generated paths, vendor files, and CI-validated paths.

**Team index fallback:** when no team record-class index was injected at session start, read the binding records directly from `docs/adlc/memory/` (dual-read order: `docs/adlc/memory` first, legacy `.adlc/memory` fallback) and state that fallback in one line. Never block on the missing injection.

2. PR Review Pipeline (single review, no self-heal)

When triggered with `--pr <id>` (without `--self-heal`):

1. Discover credentials and PR hosting tools (`factory-mission/references/tracker-integration.md`). 2. **Exact-head checkout**: Create an isolated checkout under the factory worktree root: `.adlc/worktrees/factory-review-<sha-short>/`. Check out the exact PR `headRefOid` in detached state: `git checkout --detach <head-sha>`. Review from this checkout, not the user's working tree, the base branch, or a rendered GitHub diff alone. Never reuse another run's checkout. Do not edit source code in this checkout. If the head moves during review: discard all evidence, remove the checkout, re-review the new head. Define the reviewed revision as `(head SHA, base SHA, merge base)`. 3. Fetch the PR diff and description. 4. Run the identical passes defined in `REVIEW.md`. As each pass executes, accumulate findings in the run-private scratchpad named `review-findings`. 5. Once all passes are complete, read the scratchpad and compile them into a single, consolidated, severity-ranked review comment (or inline PR comments) via MCP. The review comment MUST name the reviewed revision (head SHA in the marker `head=<sha>`). The `head=<sha>` field is what makes the verdict checkable: `scripts/check-verdict-head.sh` reads the verdict back, compares the head it names with the head being merged, and fails when they differ. Never post a verdict without it. Post the marker as ONE HTML comment at the top of the comment — the checker reads `head=` from inside that marker and requires the full 40-character SHA. Submit the verdict as a native Review-type COMMENT submission — never Approve: `create_pull_request_review(event=COMMENT)` (MCP) or `gh pr review <pr> --comment --body-file <file>` (CLI). Verdicts go through Review-type submissions; general comments stay reserved for status, lease, and decisions (tracker-integration.md Operation 4). 6. If findings contain `Important` issues, set PR label to `validation`. If clean, set to `validation` + advise code-owner of merge-readiness. 7. **Separation of Duties (Mandatory)**: The review agent physically cannot approve or merge the PR. A human code-owner's explicit approval is always required. 8. **Re-review after any fix push (mandatory)**: A fix commit — whether from babysit, self-heal, or a human addressing review feedback — invalidates the prior review verdict. The verdict applies to exactly one head SHA; once the head moves, it is stale. Before declaring merge-readiness (or letting a merged-state audit stand), re-run all REVIEW.md passes on the new head and post the updated verdict with the new `head=<sha>`. The merge-ready comment must name the head it certifies; a merge-ready claim on a superseded head is a contract violation. (Evidence: MR !21 — iter-1 verdict on `b1221aa` went stale after the babysit fix `913504a`; the merged head was never re-reviewed and carried 2 Important findings found only in a post-merge audit.) **Enforced mechanically** by `scripts/check-verdict-head.sh` (see §2 step 5) — the same rule recurred on adlc-cli #41, where the verdict for `003cf8a` went stale across four fix commits and the PR merged carrying the finding.

3. Self-Heal Converge Loop (`--self-heal` mode)