DEVFLOW_SYSTEM_OVERVIEW.md

# PRFlow: Complete System Reference

> **Purpose of this document.** This is a single, detail-rich reference describing
> *everything* about the PRFlow system: what it is, who it's for, how every piece
> works, and why the design is the way it is. It is written to be handed to other
> agents (and people) as source material for **marketing decks, technical decks,
> and explainer videos**. It mixes the "elevator pitch" framing marketers need with
> the precise mechanics engineers need, and flags which is which.
>
> **Provenance & accuracy.** Every fact here was extracted from the PRFlow source
> repository (`The01Geek/prflow`): the README, the skill definitions
> (`skills/*/SKILL.md`), the agent definitions (`agents/*.md`), the GitHub Actions
> workflows (`.github/workflows/*.yml`), the composite actions, the config schema
> (`.prflow/config.schema.json`), and the docs (`docs/*.md`). Where a number,
> file path, or named mechanism appears, it is quoted as-is so decks/videos don't
> drift from reality. Internal/strategy material (the private roadmap) is
> deliberately **excluded**.
>
> **Version.** This document carries no version literal on purpose — a hand-maintained
> one drifts silently, which is exactly what the accuracy promise above forbids. The
> shipped version is the `version` field of [`.claude-plugin/plugin.json`](../.claude-plugin/plugin.json),
> and [`CHANGELOG.md`](../CHANGELOG.md) records what changed in each release.
> License: MIT © 2026 Daniel Radman.

---

## Withheld from this release: the automatic pull-request-triggered review tier

**The automatic review on pull request is not shipped in this release.** A fresh
installation receives none of `.github/workflows/devflow-review.yml`,
`.github/workflows/devflow-runner.yml` or `.github/workflows/telemetry-push.yml`, and
`install.sh` no longer copies them.

**Why.** The tier's caller triggered on `pull_request`, `pull_request_target`, `check_run`,
`workflow_run`, `check_suite` and `status`, called a reusable workflow with
`secrets: inherit`, checked out the pull-request head, and carried no actor-authorization
gate. Two open defects describe the consequences and neither is close to landing:

- [**#930**](https://github.com/The01Geek/prflow/issues/930) — the `precheck` job
  performs a bare `actions/checkout`, which under the `pull_request` trigger resolves the
  pull request's merge ref. The config that decides whether a review runs at all therefore
  comes from the pull request under review, so "it defaults to off" is not a mitigation.
- [**#920**](https://github.com/The01Geek/prflow/issues/920) — blocked on #930.
  It is unknown whether the collaborator-permission API call succeeds under `precheck`'s
  `pull-requests: read` token, and a fork `pull_request` event receives a read-only
  `GITHUB_TOKEN` regardless of the `permissions:` block, so the job cannot post the required
  check and the context goes unreported.

**The supported review path is `/prflow:review` by comment**, and this change does not edit it. A
repository collaborator with write, admin or maintain permission comments `/prflow:review`
on a pull request; `devflow.yml`'s `gate` job authorizes the actor through
`scripts/authorize-actor.sh`, and the review runs. **An outside fork contributor cannot
self-trigger a PRFlow review — a repository collaborator must post the comment.**

**If you already installed the tier, you keep it.** `install.sh`'s
`prune_stale_devflow_workflows()` is deliberately not extended, so re-running the installer
leaves the three files in place and your auto-review keeps working. That continues to hold
across a plugin upgrade only because **every helper those workflows call is still shipped**
even though nothing in PRFlow's own tree reaches them any more: `install.sh` re-stamps
`prflow_version` to the installed commit, so re-running the installer keeps your workflow
files while vendoring a newer plugin, and a helper deleted as "unreachable" would go missing
underneath them — `finalize_check` fails **closed** when `derive-review-verdict.sh` is absent,
which would report every review `incomplete` and wedge every pull request behind a required
check that never reports, while an absent `derive-review-preconditions.sh` fails **open** and
silently drops the freshness and CI-green gates. That is why those helpers are retained rather
than swept. It also means such a repository **remains exposed to the #930 and #920 defects for
as long as `workflows["devflow-review"]` is `true` in its `.prflow/config.json`**. Removing the tier
is a manual step:

1. Delete `.github/workflows/devflow-review.yml`, `.github/workflows/devflow-runner.yml`
   and `.github/workflows/telemetry-push.yml`.
2. Set `workflows["devflow-review"]` to `false` in `.prflow/config.json`.
3. Remove the `Devflow Review` context from any branch protection rule or ruleset that
   requires it — otherwise every subsequent pull request wedges against a required check
   that nothing will report.

The removed caller's bytes are preserved on the `preserved/auto-review-tier` branch, whose
`PRESERVATION.md` records the `devflow-runner.yml` object ID it was cut against. Re-shipping
the tier is a **reconstruction against whatever that callee says at that later time**, not a
restore.


## Table of contents

1. [The one-sentence pitch](#1-the-one-sentence-pitch)
2. [The problem PRFlow solves](#2-the-problem-prflow-solves)
3. [What PRFlow is, concretely](#3-what-prflow-is-concretely)
4. [The two tiers: local and cloud](#4-the-two-tiers-local-and-cloud)
5. [The end-to-end workflow (the headline demo)](#5-the-end-to-end-workflow-the-headline-demo)
6. [The skill catalog](#6-the-skill-catalog)
7. [Deep dive: `/prflow:implement` (the 4-phase orchestrator)](#7-deep-dive-prflowimplement-the-4-phase-orchestrator)
8. [Deep dive: the review engine (`/prflow:review` + `/prflow:review-and-fix`)](#8-deep-dive-the-review-engine)
9. [Deep dive: shadow review (the audit-your-own-audit mechanism)](#9-deep-dive-shadow-review)
10. [Deep dive: the docs suite](#10-deep-dive-the-docs-suite)
11. [Deep dive: `/prflow:create-issue`](#11-deep-dive-prflowcreate-issue)
12. [Deep dive: the retrospective loop (self-improvement)](#12-deep-dive-the-retrospective-loop)
13. [The Scope-Acknowledged Findings contract](#13-the-scope-acknowledged-findings-contract)
14. [The cloud tier: GitHub Actions architecture](#14-the-cloud-tier-github-actions-architecture)
15. [Security model](#15-security-model)
16. [Observability: efficiency traces & telemetry](#16-observability-efficiency-traces--telemetry)
17. [Configuration reference](#17-configuration-reference)
18. [Installation & updates](#18-installation--updates)
19. [Repository layout](#19-repository-layout)
20. [Glossary](#20-glossary)
21. [Messaging guide: themes, taglines, talking points](#21-messaging-guide)

---

## 1. The one-sentence pitch

**PRFlow makes agentic coding work on real codebases, turning a one-line request into a complete, tested, reviewed, documented pull request that's ready for a developer's final review.**

Out-of-the-box coding agents are dazzling on a demo repo, then you point one at a real ticket in a large, business-grade codebase and it comes back half-done: wrong patterns, missing tests, stale docs. PRFlow is the end-to-end development-workflow plugin for [Claude Code](https://code.claude.com) that closes that gap: it turns a rough idea into a codebase-grounded issue, then orchestrates the full lifecycle, plan, implement, test, review, fix, document, and audits its own review before handing you the PR. Then it closes the loop with a weekly self-improvement pass that reads its own track record and proposes the smallest change that would prevent its next mistake.

---

## 2. The problem PRFlow solves

**The wedge.** AI coding agents can write code, and they look incredible doing it on a fresh, small project. Point one at a real ticket inside a large production codebase and it stalls: it doesn't know the existing patterns, plans against greenfield assumptions, implements half the change, skips the tests, leaves the docs stale, and hands you something that *looks* done but isn't. The hard part of shipping software was never writing code; it's the *workflow around* the code, and that workflow is exactly what breaks down at production scale:

- Turning a vague request into a crisp, buildable spec grounded in *this* codebase.
- Planning against the existing architecture instead of greenfield assumptions.
- Writing the tests, including the test automation the change actually needs.
- Reviewing the change rigorously, not rubber-stamping.
- Fixing what the review finds, then re-reviewing.
- Keeping internal docs, customer docs, and release notes in sync.
- Doing all of this *consistently*, every time, regardless of how big or small the change is.

**What you'd reach for instead, and what it leaves on your plate:**

| Instead of PRFlow | What it leaves you to do |
|---|---|
| Raw coding agents (Claude Code alone, Cursor, Copilot, Devin) | Great on toy projects; on a real codebase *you* still spec, plan, test, review, fix, and document, the agent only drafted part of the code. |
| The stock `@claude` GitHub App | Answers questions and writes code, but enforces no lifecycle, no plan gate, no review-and-fix loop, no docs, no acceptance-criteria check. |
| The manual senior-engineer loop | It works, at the cost of your most expensive people doing spec → plan → implement → test → review → fix → document by hand, inconsistently, on every ticket. |
| Merging the agent's first attempt | The fastest path to a PR that looks done, passes nothing, and resurfaces in production. |

Most "AI writes your code" tools stop at the first step and hand you a diff. PRFlow automates the **entire** loop and treats "committing code as the halfway point, not the finish line."

**The deeper insight (good for a keynote slide).** A single LLM pass is variable: it can miss things, rationalize its own work, or declare victory early, and that variance is exactly what sinks it on a large codebase, where the margin for a half-finished change is zero. PRFlow's architecture is built around *not trusting any single pass*: it uses independent verification checklists, multiple specialized reviewers, a structurally-independent "shadow" re-review to audit its own approval, and a weekly retrospective that audits the whole system. The product thesis is **disciplined, auditable AI software delivery at production scale**: not just code generation.

---

## 3. What PRFlow is, concretely

PRFlow is distributed as a **Claude Code plugin**. The repository is also its own plugin **marketplace**. It bundles:

- **Skills**: the user-facing commands (`/prflow:implement`, `/prflow:review`, the `/prflow:docs` family, `/prflow:create-issue`, `/prflow:retrospective-weekly`, etc.). Each is a `SKILL.md` file containing the procedure the model follows; a larger skill may split its detailed per-phase procedure into on-demand reference files that the `SKILL.md` reads at each step — as `/prflow:implement` does, where a thin orchestrator `SKILL.md` reads one `phases/phase-N-*.md` file at the start of each phase and a phase file in turn reaches a **predicate-gated** `references/*.md` file only when a durable predicate says that procedure applies (Phase 4.0's deferred-AC follow-up filing, gated on `scripts/workpad.py deferred-presence` — issue #815); as the shared review engine does, where a state-owning root reads a gated `phases/*.md` reference through an identity-and-boundary entry gate (§8); and as `/prflow:create-issue` does, where a thin root reads a marker-gated `references/*.md` file at each step entry and, separately, loads a fallback reference only when that arm's predicate fires (§11).
- **Agents**: ten specialized first-party subagents — `checklist-generator`, `checklist-deduper`, `checklist-verifier` power the review engine; the five Phase-3 review agents `code-reviewer`, `silent-failure-hunter`, `comment-analyzer`, `pr-test-analyzer`, `type-design-analyzer` do the bulk of `/prflow:review`'s work (vendored from Anthropic's pr-review-toolkit plugin under Apache-2.0, retained at `LICENSES/pr-review-toolkit-LICENSE`); and `code-explorer` (codebase discovery) and `code-architect` (planning) power `/prflow:implement` (vendored from Anthropic's feature-dev plugin under Apache-2.0, retained at `LICENSES/feature-dev-LICENSE`). PRFlow owns all the vendored agents as a hard fork.
- **Scripts** (`scripts/`, `lib/`), deterministic helpers in Bash, `jq`, and Python that do all the mechanical work (fetching context, computing patterns, gating, git/PR mechanics) so the LLM is only invoked for genuine judgment.
- **Cloud workflows** (`.github/`), optional GitHub Actions that make PRFlow run autonomously on issue/PR events.

It declares **zero companion-plugin dependencies** — every external asset the engine once dispatched is now a first-party PRFlow file, internalized as a hard fork across three seams:

- The five Phase-3 review agents (`code-reviewer`, `silent-failure-hunter`, `comment-analyzer`, `pr-test-analyzer`, `type-design-analyzer`) and the discovery/planning subagents `code-explorer` / `code-architect` are first-party agents under `agents/` (vendored from Anthropic's `pr-review-toolkit` and `feature-dev` plugins under Apache-2.0, retained at `LICENSES/pr-review-toolkit-LICENSE` and `LICENSES/feature-dev-LICENSE`), dispatched as `devflow:<name>` — so neither `pr-review-toolkit` nor `feature-dev` is a dependency.
- The final-pass reviewer (`requesting-code-review`) and the fix-loop `receiving-code-review` principles are first-party skills under `skills/` (vendored from the `superpowers` plugin under its MIT license — Jesse Vincent — retained at `LICENSES/superpowers-LICENSE`), dispatched/invoked as `devflow:<name>` — so `superpowers` is no longer a runtime dependency. (The `writing-skills` authoring discipline is **not** vendored — it remains the external `superpowers` skill, a development-time tool PRFlow's own contributors use, not something the engine dispatches.)

PRFlow owns all the vendored agents and skills as a hard fork, and may modify them from this point forward. With the `superpowers` seam internalized there are **no companion-plugin install dependencies left at all** — PRFlow installs and runs on its own.

The "zero companion-plugin dependencies" claim is scoped precisely: it means the **consumer `/plugin install`** resolves with no `claude-plugins-official` prerequisite, and PRFlow's **engine** (everything under `skills/` + `agents/`) dispatches no companion plugin. It is *not* a claim that the cloud workflows install nothing else — `devflow.yml`, `devflow-implement.yml`, and `devflow-runner.yml` still install `code-review@claude-plugins-official` and `claude-md-management@claude-plugins-official` to make the **ambient** `/code-review` and `/revise-claude-md` slash commands available inside the runner. Those are convenience commands the engine never dispatches as part of a review or implementation, so they are not engine dependencies and do not affect the consumer install. Since issue #505 the cloud workflows additionally honor consumer-declared `enabledPlugins` and `github`-kind `extraKnownMarketplaces` entries from the trusted base-ref `.claude/settings.json` (composed into the same `plugins`/`plugin_marketplaces` inputs by `scripts/resolve-extra-plugins.sh`) — a consumer-chosen convenience mirroring what Claude Code already honors locally, **not** an engine dependency: the engine dispatches none of those plugins, and the entries are composed only from a trusted ref — the maintainer-committed default-branch checkout on the two write tiers, and the materialized base-ref copy on the review tier (which never reads the PR-head checkout's settings file).

`/simplify` (used for self-review) is a **built-in** Claude Code skill, intentionally *not* a dependency.

---

## 4. The two tiers: local and cloud

This distinction is central to every pitch, lead with it.

### Local tier (zero config, no infrastructure)
The skills you run **inside Claude Code**. Works with **no configuration file at all**: every setting has a built-in default. You type `/prflow:implement 42` (or `/prflow:review`, etc.) in your editor and it runs in your session. Requirements: `git`, `gh` (GitHub CLI, authenticated), `jq`, and Python 3.11+; PyYAML is an advisory extra on this tier (a missing PyYAML degrades one helper rather than blocking, and `bash lib/preflight.sh` reports it but still exits 0). A `bash lib/preflight.sh` verifies the environment. Shell helpers avoid GNU-only flags, so macOS/BSD work without GNU coreutils. The toolchain is also self-defending on Windows / non-UTF-8 hosts: a committed `.gitattributes` forces every `*.sh`/`*.py`/`*.jq` to LF on checkout regardless of `core.autocrlf` (so a shebang never becomes `bash\r`), and every first-party `scripts/*.py` forces its own streams and `gh` I/O to UTF-8 (so an em-dash or emoji never trips a cp1252 codec). On a stock Windows Python install (where Python is on PATH only as `python`/`py -3`, with no `python3`), run `bash scripts/provision-python3-shim.sh --apply` once to install a consent-gated `python3` shim that forwards to the first `>=3.11` interpreter — preflight points you there, and it is a no-op on macOS/Linux where a real `python3` already exists. External binaries are resolved with the same execution-verified discipline through a shared resolver family: `lib/resolve-bin.sh` is the single source of truth for the generic selection contract (`devflow_resolve_bin <tool>`), sourced by `lib/preflight.sh` (which only DETECTS) and — via thin per-tool wrappers — by every helper that USES the tool, mirroring their sibling `lib/resolve-python.sh`. The contract: an explicit, non-empty `DEVFLOW_<TOOL>` override (`DEVFLOW_GH`, `DEVFLOW_JQ`) wins outright with no probe; otherwise the first of `<tool>`/`<tool>.exe` whose network- and auth-free `<tool> --version` actually runs is selected (rejecting a present-but-unrunnable Windows/WSL shim); if neither runs, the bare tool is returned with a stderr breadcrumb naming the override remedy (always exit 0). `lib/resolve-gh.sh` delegates to it for `gh` (kept as its own file because every gh-calling helper sources it by name; the `DEVFLOW_GH` contract is unchanged, and the seven Python gh-callers — `workpad.py`, `file-deferrals.py`, `match-deferrals.py`, `parse-acs.py`, `export-workflow-lifecycle-census.py`, `build-experiment-records.py`, `preflight.py` — honor the same override), and `lib/resolve-jq.sh` is the `jq` sibling, sourced by every jq-calling helper to resolve `jq` once into `DEVFLOW_JQ`. `scripts/run-jq.sh` is the agent-tier sibling of that helper for the `jq` an agent composes inside a `SKILL.md` body (every executable agent-composed `jq` site — the retrospective family plus the cloud-governed `implement`, `docs-release-notes`, and `review` skill bodies): because each skill-body `jq` runs in a fresh per-Bash-call agent shell where `DEVFLOW_JQ` is neither exported nor persisted, the source-once-then-reuse idiom does not translate, so those skills invoke `run-jq.sh` **by path** (`"${CLAUDE_SKILL_DIR:-<absolute skill base directory this runner reports in context>}"/../../scripts/run-jq.sh`, or the vendored `.prflow/vendor/prflow/scripts/run-jq.sh` the cloud allowlist grants) in place of bare `jq` — it sources the shared `resolve-jq.sh` and execs the resolved binary, selecting a runnable `jq` on a shim-shadowed Windows/WSL host exactly as the helper tier does (a transparent no-op elsewhere; degrades to bare `jq` with a breadcrumb on a partial deployment). `lib/preflight.sh` execution-verifies both `gh` and `jq` with a two-branch diagnosis (not installed vs. present-but-unrunnable, each naming the override remedy); `install.sh` alone carries an inline jq adaptation because it runs standalone before any checkout exists (there a broken `DEVFLOW_JQ` warns and routes to the python3 arm). A companion helper, `lib/normalize-path.sh` (`devflow_normalize_path`), converts a Windows-form path (`C:\...`) to the running shell's POSIX form — `wslpath`, else `cygpath`, else an environment-detected translation (`/mnt/c/...` under WSL, `/c/...` under MSYS/Git Bash), else unchanged with a breadcrumb — and the skill preambles paraphrase that chain as prompt-time normalization guidance (the anchor is what locates `lib/`, so it cannot source the helper it bootstraps — see §6). On macOS/Linux/cloud, where the bare tools run, every resolver returns the bare name on the first probe — no behavior change. The **bash that RUNS** those `.sh` helpers is a level above the resolver family: it is chosen at the invocation boundary (the agent/runner that shells into bash) before any `.sh` executes, so a sourced resolver cannot select it (bootstrap — the resolver would itself need a chosen bash to run). PRFlow supports **any** POSIX bash — WSL bash, Git Bash, or MSYS2 bash, none mandated — and the invocation layer honors a **`DEVFLOW_BASH`** override to point at one. Consistent with its detect-not-select posture, `lib/preflight.sh` is a diagnostic here too: under bash it emits a `devflow-bash:` breadcrumb (interpreter path + `$BASH_VERSION`) and surfaces `DEVFLOW_BASH` when set; run under a non-bash POSIX shell (empty `$BASH_VERSION`) it prints a remedy naming the three supported bashes + the override and exits non-zero before the first bash-only `${BASH_SOURCE[0]}`, failing closed rather than aborting with a cryptic "Bad substitution" (a host with no POSIX bash at all — PowerShell-only — is out of scope). See `CONTRIBUTING.md` for the residual Windows caller-side execution discipline.

### Cloud tier (autonomous, optional)
GitHub Actions workflows make PRFlow run **autonomously on issue/PR events**. You comment `/prflow:implement 42` on an issue and the workflow drives the whole lifecycle without you in the editor. It needs only one secret **by default**, `CLAUDE_CODE_OAUTH_TOKEN`, and a little setup (see `docs/cloud-setup.md`); routing a workflow through an optional third-party model provider adds one more, `DEVFLOW_PROVIDER_API_KEY`. No GitHub App required.

**Both tiers can run on one repo** without conflict. The local marketplace copy is cached centrally; the cloud tier materializes its own copy of the plugin at runtime.

---

## 5. The end-to-end workflow (the headline demo)

This is the canonical story for a demo video or "how it works" slide:

```
   you: a rough idea
        │
        ▼
  ┌───────────────────┐   /prflow:create-issue
  │ 1. Create issue   │   turns the idea into a structured GitHub issue
  └───────────────────┘   (asks clarifying questions, you confirm before it files)
        │
        ▼
  ┌───────────────────┐   comment  /prflow:implement <#>  on the issue
  │ 2. Trigger        │   (a human comment starts it)
  └───────────────────┘
        │
        ▼
  ┌───────────────────┐   devflow-implement.yml runs /prflow:implement autonomously:
  │ 3. Implement      │   branch → plan → code → tests → draft PR → /simplify →
  └───────────────────┘   /prflow:review-and-fix → docs → marks the PR ready
        │
        ▼
  ┌───────────────────┐   devflow-review.yml posts a /prflow:review verdict as a
  │ 4. Review gate    │   PR check; you review and merge
  └───────────────────┘
```

**Narration points:**

1. **Create the issue.** `/prflow:create-issue Add CSV export to the reports page`. PRFlow interviews you until the issue is unambiguous, shows you the rendered draft, and files it **only after you confirm**. Say it lands as **#42**.
2. **Trigger implementation.** Comment `/prflow:implement 42` on the issue. Because *you* (a real user) posted it, GitHub fires the workflow natively, no bot, PAT, or GitHub App needed. (Note: the trigger is the bare `/prflow:*` form, **not** `@claude`, that prefix is ceded to Anthropic's Claude GitHub App.)
3. **PRFlow implements it.** The workflow creates a branch, plans against your codebase, writes code and tests, opens a **draft** PR, self-reviews with `/simplify`, runs `/prflow:review-and-fix`, files follow-up issues for any deferred findings, updates the docs, and flips the PR to **ready**.
4. **Review and merge.** A second workflow runs `/prflow:review` as a gate and posts its verdict as a PR check. A human does the final review and merges.

**Prefer the editor?** Run `/prflow:implement 42` directly in Claude Code, both reach the same lifecycle.

---

## 6. The skill catalog

| Skill | What it does | How it's invoked |
|---|---|---|
| `/prflow:implement <issue#>` | Full lifecycle: fetch issue → branch + workpad → discover/plan → implement → test → draft PR → `/simplify` → `/prflow:review-and-fix` → acceptance gate → file follow-up issues → docs → ready PR | interactively, or by commenting on an issue (cloud) |
| `/prflow:review [PR#]` | Verification-checklist-driven review; runs the first-party `prflow:` review agents + the first-party `prflow:requesting-code-review` final-pass reviewer; returns **APPROVE/REJECT** (no auto-fix) | interactively, or a bare `/prflow:review` comment on the PR |
| `/prflow:review-and-fix [PR#]` | `/prflow:review` + an automatic fix loop (max **4** iterations); writes a deferrals manifest at Loop Exit | interactively; called by `/prflow:implement` Phase 3 |
| `/prflow:pr-description [issue#]` | Generate/update PR description from the branch diff; renders the Scope-Acknowledged Findings block | interactively; called by `/prflow:implement` Phase 4 |
| `/prflow:docs` | Orchestrates the three doc steps in one session | interactively; called by `/prflow:implement` Phase 4 |
| `/prflow:docs-sync-internal` | Update internal docs to match branch code changes | called by `/docs` |
| `/prflow:docs-sync-external` | Align external/customer docs with internal docs | called by `/docs` |
| `/prflow:docs-release-notes` | Generate a release-note entry for customer-visible changes; on a version-bump branch, also reconcile that version's CHANGELOG entry (any PR, not just customer-visible) | called by `/docs` |
| `/prflow:docs-verify <topic>` | Verify/refresh internal docs for one topic (has `--report-only` mode, which also accepts an explicit search-space operand) | interactively; dispatched as a peer subagent by `/prflow:create-issue` Step 1 |
| `/prflow:docs-bootstrap-internal` | Stand up an internal-docs structure from scratch | interactively |
| `/prflow:docs-bootstrap-external` | Generate initial external docs from internal docs | interactively |
| `/prflow:create-issue` | Rough idea → well-structured GitHub issue | interactively |
| `/prflow:init` | One-time setup: scaffold `.prflow/config.json` + refresh schema | interactively |
| `/prflow:retrospective-weekly` | The weekly self-improvement loop orchestrator | interactively |
| `/prflow:retrospective` | Stage A: per-PR retrospective analysis | subagent only |
| `/prflow:retrospective-audit` | Stage B: per-pattern issue-spec drafting | subagent only |

**Agents** (`agents/`): `checklist-generator`, `checklist-deduper`, `checklist-verifier`.

**Naming note (important for accuracy in any demo):** PRFlow's commands use the `prflow:`-namespaced form. This matters most for names that collide with built-ins: `/review`, `/init`, and `/security-review` are *built-in* Claude Code commands, so always use `/prflow:review` and `/prflow:init` to reach PRFlow, especially from GitHub Actions comments, where the namespaced form is required.

### Extending skills with prompt extensions (consumer-owned)

Every skill in the catalog honors one upgrade-safe extension convention. As a standardized first step, each skill runs the bundled reader

```bash
"${CLAUDE_SKILL_DIR:-<absolute skill base directory this runner reports in context>}"/../../scripts/load-prompt-extension.sh <skill-name>
```

which prints the contents of `.prflow/prompt-extensions/<skill-name>.md` (resolved relative to the repo root — see the `DEVFLOW_PROMPT_EXTENSION_ROOT` override below) when that file exists, and the skill treats that text as **additional instructions appended verbatim to the end of its own prompt** for that run. `<skill-name>` is the skill's directory name under `skills/` (`create-issue`, `implement`, `review`, …) and is the reader's only **positional** argument. When the file is **absent** — or present but empty — the helper prints nothing and the step is a **no-op**: the skill behaves exactly as it does without it. A file that exists but cannot be delivered (unreadable, a broken symlink, or not a regular file) is refused loudly with a non-zero exit and a breadcrumb, and the skill surfaces that rather than silently skipping it — so a misconfigured extension never vanishes without a trace.

**Which directory the reader reads (`DEVFLOW_PROMPT_EXTENSION_ROOT`, issue #874).** The reader has **two** directory-selection branches. When `DEVFLOW_PROMPT_EXTENSION_ROOT` is set and non-empty it names the extension directory outright, so the composed path is `<root>/<skill-name>.md` with **no** `.prflow/prompt-extensions/` segment appended and **no** `git rev-parse` call; that branch writes a stderr breadcrumb naming the directory it resolved. Otherwise the reader takes the repo-root branch described above — the only branch the issue-#295 repo-root-reader enumerations (in `.prflow/config.schema.json` and `scripts/emit-git-env.sh`) are about. The variable is top precedence and inert both when unset **and** when set empty, the same `DEVFLOW_GH` / `DEVFLOW_JQ` / `DEVFLOW_BASH` convention, so every caller that leaves it unset sees byte-identical stdout and exit codes. **Who may write the file and which checkout supplies its bytes are different questions.** The extension is consumer-owned on every tier; but the automated cloud review runner checks out the *pull request's head*, so it sets this variable to a `$RUNNER_TEMP` closure it materialized from the trusted base ref — see the **base-ref trust boundary** bullet in §15 (Security model), the canonical statement of that boundary and of the residuals it does not close (notably the manual `/prflow:review` path in `devflow.yml`, which is not covered).

**Loading one section instead of the whole file (`--section`, issue #611).** A skill that re-loads its extension repeatedly — `/prflow:create-issue` re-loads at four points, deliberately, because context compaction can evict the turn-one text and a heading-less extension makes that loss invisible — paid a full-extension dump into context every time, when each consumption site wanted exactly one section. The reader therefore accepts an optional `--section '<## heading>'` after the positional: `load-prompt-extension.sh create-issue --section '## Audit dimensions'`. A section spans its heading line to the next line beginning `## ` (two hashes **plus a space**, so a `###` sub-heading is section content and terminates nothing), else to end of file; duplicate same-heading sections concatenate in file order; a `##` line inside an open HTML comment block or inside a fenced code block is never a heading, and an unclosed fence runs to end of file. Both CommonMark fence characters are tracked (` ``` ` and `~~~`), and a fence closes only on its own kind. The comment rule is scoped by *where the line begins*: a line that **begins** `## ` is a heading whatever trails it, including an inline comment (`## Evidence axes <!-- consumer note -->`), while a line that merely contains `<!--` without starting `## ` (`<!-- ## Commented -->`) is inert — testing the comment shape first would make an inline-annotated heading unselectable *and* make the absent-heading breadcrumb enumerate the file as though a heading the consumer can plainly see were not there. Comment-block state is resolved by the **last** marker on each line, so `<!-- a --> <!--` leaves the block open for the lines that follow; trailing whitespace is stripped from both the candidate heading line and the flag's value before comparison, so a CRLF-authored extension still extracts. At most one section per invocation — a repeated flag takes its last occurrence. The extraction is **bash-builtin-only** (no `awk`/`sed`/`tr`/`head`): the emitted section decides what the consuming skill sees, and under the repo's non-preflight-PATH-tool rule such a value must not be derived through a tool `lib/preflight.sh` does not guarantee, which would empty the selection silently rather than failing loudly.

Two contracts keep the flag safe to adopt. A **flagless** invocation stays byte-identical to the full-file behavior above, so every pre-existing caller is untouched. And the two ways a section can yield nothing are held apart: an **absent heading in a non-empty extension** stays the designed no-op (exit 0, empty stdout) but additionally emits a stderr breadcrumb naming the requested heading and the headings actually present — so a near-miss heading (case drift, a typo) is observable instead of silently contributing nothing — while an **empty section** stays breadcrumb-free, because its heading *was* found and there is nothing to fix. Malformed flag usage is refused loudly at exit 2 rather than silently reverting to the full dump: an unrecognized `--`-prefixed argument; a `--section` missing its value, empty after stripping, or given a **flag-shaped** value (`--section --bogus`, the shape a dropped heading argument leaves); a `--`-prefixed token in the skill-name slot (a transposed flag, which would otherwise look up a skill literally named `--section` and no-op at exit 0); and a **heading-shaped bare positional** (`load-prompt-extension.sh create-issue '## Audit dimensions'` — a dropped `--section`, which would otherwise emit the *whole* extension at exit 0, the exact opposite of what the caller asked for and indistinguishable at the call site from a legitimate full-file load). Each refusal closes a shape that would otherwise select silently; a bare **plain word** extra argument keeps its pre-existing ignored behavior. This `--section` flag remains the sibling extraction implementation for its own callers; since issue #600 the create-issue audit hooks are owned by `scripts/render-audit-prompt.py`, and the extraction rule is **specified** in `skills/create-issue/references/audit-prompt-template.md`.

**Runner-portable anchor (single-statement, generalized to every local-tier skill).** `${CLAUDE_SKILL_DIR}` is exported by Claude Code but is *empty* on other agentic CLIs (confirmed on Copilot CLI v1.0.67; expected on Cursor, Codex CLI, Gemini CLI, …), where the bare `${CLAUDE_SKILL_DIR}/../../scripts/…` form collapses to a broken `/../../scripts/…` path. A second defeat stacks on top: Copilot CLI's inline `bash -c` marshaling **strips a variable assigned in one statement and read in a later statement of the same inline command** (verified: `bash -c 'v=hi && echo $v'` prints empty), so the earlier assign-then-reuse recipe (`SKILL_DIR="${CLAUDE_SKILL_DIR:-…}"; … "$SKILL_DIR"/../../scripts/…`) also fails there. Every skill therefore resolves the anchor **inline in the same single statement that invokes the helper**: `"${CLAUDE_SKILL_DIR:-<absolute skill base directory this runner reports in context>}"/../../scripts/…` — preferring `$CLAUDE_SKILL_DIR` when set and non-empty (the `:-` expansion treats empty the same as unset), and otherwise the agent substitutes the placeholder with the skill base directory the runner reports in context (e.g. a `Base directory for this skill:` line), converting a Windows-form path (`C:\…`) to POSIX form first at prompt time (one standalone `wslpath -u`/`cygpath -u` probe, or the textual drive-letter rules from `lib/normalize-path.sh` — the skills carry no shell normalization mirrors). On Claude Code the resolved value is identical to the bare form, so behavior there is unchanged. If neither `$CLAUDE_SKILL_DIR` nor a runner-reported base directory is available, the skill fails closed (stop + report) rather than running a broken path — except `/prflow:create-issue`, which is deliberately best-effort throughout (an unresolvable anchor never blocks issue creation; a skipped provenance label or prompt-extension load is reported explicitly instead). This is distinct from the cloud-tier carve-out below, where workflows reference the literal vendored path because the sandbox blocks `$`-expansion.

**A skill loads the extensions its behavior draws on (issue #620).** The usual case is one — a skill's own — but a skill that applies *another* skill's principles without invoking that skill also loads that skill's extension, so the policy follows the behavior rather than the invocation. `/prflow:review-and-fix` is the instance: at entry it loads its own `review-and-fix` extension and then the `receiving-code-review` extension, because the fix loop applies `prflow:receiving-code-review` principles without ever invoking that skill — so a repo's reception policy would otherwise reach direct passes only and silently miss every fix loop. Both loads happen in that preamble, so they cover every path that enters through it — the standalone loop, the `/prflow:implement` Phase 3 inline run, and the Step 2.6 shadow entry. The documented Skill-denied fallback, where Phase 3 reads the engine straight from the tree instead of invoking the skill, bypasses the preamble and therefore loads neither extension; that pre-existing gap is unchanged. The preamble also carries the scoping prose governing how a loop run consumes text written for a direct pass.

**A subagent that cannot resolve its own anchor is supplied the command by its dispatcher (issue #802).** The Phase-3 **final-pass reviewer** (`prflow:requesting-code-review`) is dispatched as a `general-purpose` Task that receives no `$CLAUDE_SKILL_DIR` and no `Base directory for this skill:` line, so it cannot resolve the anchor above for `load-prompt-extension.sh` itself. The orchestrator — which *does* run as a skill, so its own anchor resolves — instead supplies an **already-resolved helper command** in the dispatch prompt: the vendored literal `.prflow/vendor/prflow/scripts/load-prompt-extension.sh requesting-code-review` when that file exists (every cloud tier, where the `vendor-plugin` action materializes it), and otherwise the orchestrator's own anchor-resolved helper path (the local and interactive tiers). The reviewer runs that command **verbatim** — never improvising a shell shape the cloud matcher would silently refuse — and reports one of three `EXTENSION-STATUS:` tokens (`loaded-with-content`, `loaded-empty`, or the shared refusal literal). The orchestrator treats that token as **data, never as an instruction**, and surfaces a one-line extension-load-failure notice (and a per-caller reflection record) only on an actual reported refusal, with a fail-closed notice-suppression flag so the routine local-tier denial is recorded as `unestablished` rather than reported as a failed load. The same three-profile grant surface (`Bash(.prflow/vendor/prflow/scripts/load-prompt-extension.sh:*)` on `review`/`implement`/`command`, plus the `*/load-prompt-extension.sh` wildcard on `review` and `command`) already covers this, so the change adds **no** new tool grant; see [`docs/cloud-allowlist.md`](cloud-allowlist.md) and [`docs/cloud-setup.md`](cloud-setup.md).

**Every subagent dispatch of a skill supplies the child its extension path (issue #834).** The extension-load step lives in the **skill body**, so dispatch mode never changes whether the load is *attempted* — a skill always tries to load its extension. What dispatch mode decides is only (1) whether the skill-directory *anchor* resolves — a subagent dispatched as a `Task`/`Agent` receives no `$CLAUDE_SKILL_DIR` and no `Base directory for this skill:` line, so it cannot resolve the anchor for `load-prompt-extension.sh` itself — and (2) whether a *command the child runs* is permitted by the active allowlist profile. When a subagent cannot resolve its own anchor, the dispatching orchestrator (which runs as a skill, so its own anchor resolves) supplies an already-resolved by-path handoff in the dispatch prompt: the retrospective **Stage A** (`retrospective`) and **Stage B** (`retrospective-audit`) children and the Phase 4.1 **`prflow:docs`** documentation subagent each now receive their extension path this way, so the consumer's `.prflow/prompt-extensions/<skill>.md` is honored rather than silently no-op'd. The registry `lib/subagent-dispatch-sites.json` enumerates every such dispatch site, and the lint `lib/test/lint-subagent-extension-handoff.py` (wired into `lib/test/run.sh`) fails the build when a subagent dispatch of a PRFlow skill is unregistered. **The skill-vs-agent boundary:** this convention is scoped to dispatches of *skills* — the first-party `agents/*.md` subagents (the review-engine trio, `code-explorer`, `code-architect`, the `pr-review-toolkit` reviewers) load **no** consumer prompt extension, because an agent is not a skill and carries no `.prflow/prompt-extensions/<name>.md` contract.

The extension file lives in the **consumer's** repo, committed under `.prflow/prompt-extensions/` and shared by the team. It is never part of the plugin, so marketplace updates never overwrite it and never conflict with it — the same consumer-owned-vs-plugin separation that keeps your `.prflow/config.json` yours across updates (note the extension files are *tracked/committed* so a team shares them — as is the live `config.json`, which is committed so the cloud tier reads it from the tree, not gitignored). `/prflow:init` scaffolds the directory with a commented, inert `<skill-name>.md.example` for **every** skill — each carrying a skill-specific hint — so adopters discover that the convention works for all of them, not just one. The examples are backfilled per file (each created only when absent), so an adopter who scaffolded earlier picks up any newly added examples on re-run while their own extension files (an edited `.example`, or a live `<skill-name>.md`) are never overwritten. Re-running the scaffolder also **skips creating a `<skill-name>.md.example` when a live `<skill-name>.md` already exists** for that skill: once an adopter has activated an extension, dropping a redundant `.example` beside it would just be confusing clutter, so the live `.md` (read-only here, never modified) suppresses its own example. A pre-existing `.example` is likewise left untouched. The helper validates the skill-name argument (rejecting any value containing `/` or `..`) before any filesystem access, so the resolved path can never escape `.prflow/prompt-extensions/`.

**Worked example — Azure DevOps test cases in every generated issue.** An adopter who stores test cases in Azure DevOps wants `/prflow:create-issue` to list the applicable test cases in each generated issue body, while upstream PRFlow stays Azure-DevOps-agnostic. They:

1. Register a **project-scoped Azure DevOps MCP server** in their repo's `.mcp.json`.
2. Commit `.prflow/prompt-extensions/create-issue.md` containing, for example:
   > When building the issue body, call the Azure DevOps MCP server to fetch the test cases applicable to this work item and list them under a new "## Applicable Azure DevOps Test Cases" section.

Because the injected text is appended verbatim and MCP tools are model-invoked from prose (not deterministically function-called), the extension must **tell the model to call the tool** rather than assume it runs automatically. No plugin file is edited; the customization is entirely consumer-owned and survives every plugin update.

**`create-issue` audit-dimensions hook (issue #443).** The `create-issue` extension has one **structured** hook the skill reads by heading: a section headed exactly `## Audit dimensions` in `.prflow/prompt-extensions/create-issue.md` is forwarded verbatim to the Step 3.6 fresh-context audit subagent (§11), appended to its generic dimension checklist, so a consumer teaches the auditor the repo-specific premises its issues must respect. Since issue #600 that read + extraction is performed natively in-process by `scripts/render-audit-prompt.py` (not `load-prompt-extension.sh`), whose `render-status:` line reports whether the section was appended. An extension without that heading changes nothing. Since issue #729 a consumer bullet may optionally declare its own coverage key with a `<!-- dim-key: <lowercase-kebab> -->` marker on the line immediately above it (emitted as `c:<declared-key>` by the renderer's `enumerate-dimensions` mode and stripped from the auditor-facing prose); an undeclared bullet keys off its bold-lead name slug, else a hash of its text, so inserting a bullet mid-section no longer renumbers its siblings — but only a declared key survives a reword. The declaration arms are specified once, in `skills/create-issue/references/audit-prompt-template.md`, and deliberately not paraphrased here. Consumers discover the contract from the scaffolded `create-issue.md.example`, which carries an inert sample of the heading; this repo's own live `.prflow/prompt-extensions/create-issue.md` ships the PRFlow-engine audit dimensions, each carrying an explicit declaration.

**`create-issue` evidence-axes hook (issue #548).** A **second** structured hook mirrors the first: a section headed exactly `## Evidence axes` in `.prflow/prompt-extensions/create-issue.md` extends the generic evidence-axis floor the Step 2 independent-derivation *evidence-bundle sub-pass* records (§11), so a consumer adds repo-specific axes the pass must evidence before the approach question is asked. The two hooks are extracted by the **same heading-extraction rule** — since issue #600 owned and implemented once by `scripts/render-audit-prompt.py`'s section-extraction mode and documented in `skills/create-issue/references/audit-prompt-template.md` (the `## Audit dimensions` hook consumes it spliced into a dispatch arm as `{CONSUMER_DIMENSIONS}`, while `extract --hook evidence-axes` exposes the same rule for the evidence-axes hook, whose operative pass-time re-load remains `scripts/load-prompt-extension.sh --section`; that flag also remains the sibling implementation for its own other callers) — and each is appended only at its own consumption site, so an extension carrying both feeds `## Audit dimensions` to the audit dispatch and `## Evidence axes` to the evidence pass independently. The rule is deliberately **not** restated here: it lived at three sites before issue #611 and drifted, so this paragraph references the specification rather than paraphrasing it. A denied or failed pass-time re-load is surfaced (`consumer axes: unestablished — loader denied or failed`), never read as "no extension"; an absent heading in a non-empty extension is likewise reported from the loader's stderr breadcrumb rather than passing silently. The scaffolded `create-issue.md.example` carries an inert sample of this heading too; this repo's live extension ships the PRFlow-engine evidence axes (see the live extension's `## Evidence axes` section for the current axis list — this paragraph deliberately does not enumerate them, so it cannot rot when an axis is added).

---

## 7. Deep dive: `/prflow:implement` (the 4-phase orchestrator)

This is PRFlow's flagship. It runs a **mandatory 4-phase lifecycle** for a GitHub issue, every phase runs regardless of issue size. The orchestrator does most work directly in its own continuous session; it uses subagents only for context-isolated work (exploration, architecture, documentation).

> **Tagline:** *"Committing code is the halfway point, not the finish line."* The PR stays a **draft** until Phase 4.3.

### The Workpad: the run's single source of truth
PRFlow maintains **exactly one** marker-tagged comment on the GitHub issue for the whole run (marker: `<!-- prflow:workpad -->`, configurable). It is the durable progress surface, the "job started" acknowledgment, and the resume point. It is driven by `scripts/workpad.py`, a stateless CLI.

- **Status glyphs:** 🚀 (in progress) → 🎉 (`Complete`) / 👎 (`Blocked`) / 💥 (`Failed`) / 🛑 (`Cancelled`). The first three drive the **emoji reaction** on the triggering comment (rocket / hooray / -1). **💥 (`Failed`) and 🛑 (`Cancelled`) are workpad-only and have no triggering-comment reaction** — the cloud stall backstop writes 💥 when a run dead-ends and 🛑 when a run is cancelled (issue #498; see the Stall-backstop note below), never the agent, so no outcome reaction is emitted for either.
- **Sections (in order):** marker, header, `Status`, `Branch`, `Run`, `PR`, `Last updated`, `## Progress`, `## Plan`, `## Acceptance Criteria`, `## Reproduction` (bug-report classification only), `## Devflow Reflection`. The bug-only `reproduction captured` `## Progress` row is pre-rendered from the `bug` *label* by the deterministic producers (the cloud `gate` job and `new-body`), then reconciled to the recorded **content** classification by Phase 1.3's `workpad.py update --reconcile-reproduction` (issue #449) — idempotent, run on every entry, and it never removes a *ticked* row or a populated `## Reproduction` section (historical evidence).
- **Checkbox ticking is addressable two ways.** `workpad.py update` ticks a `## Progress`/`## Plan`/`## Acceptance Criteria` checkbox either by **unique substring** (`--tick-progress`/`--tick-plan`/`--tick-ac`) or — for Plan and Acceptance Criteria — by **1-based index** within that section (`--tick-plan-n`/`--tick-ac-n`, counting every `[ ]` and `[x]` row in document order; Progress has no index form). The Phase 3.4 acceptance gate ticks ACs by index, so it no longer depends on hand-picked unique prose substrings.
- **Reflection bullets are grouped by kind.** Inside the collapsed `## Devflow Reflection` `<details>` block, `workpad.py update --reflection-kind {blocked|deferred|dropped-failed|improvement|issue-accuracy|note}` renders each bullet under one of **three** `### ` sub-sections, in the canonical order `### ⚠️ Action required` → `### 💡 Improvements` → `### ℹ️ Notes`: the three actionable kinds (`⛔ Blocked` / `⏭️ Deferred` / `❗ Dropped/Failed`, all **labeled**) under **`### ⚠️ Action required`**; engine/process-improvement proposals (`💡`, **glyph-only**) under **`### 💡 Improvements`**; and wrong/underspecified-issue-claim feedback (`📝 **Issue accuracy:**`, **labeled**) plus informational notes (`ℹ️`, the default, **glyph-only**) under **`### ℹ️ Notes`**. A kind whose heading already names it drops the redundant bold label (issue #476: `note`, `improvement`); the others keep it. Reflection text passed via `--reflection-file PATH` (or stdin `-`) is read verbatim as UTF-8, bypassing shell interpolation for text containing backticks/`$`/quotes. Sub-headings are `### ` (level-3, never `## `) so the retrospective parser is not truncated. The Phase 1.6 issue-claim audit records clean confirmations as `## Progress` `--note`s (not reflections), so a frictionless run leaves `reflections[]` empty and stays cheap.
- **The workpad answers a bounded predicate, and it is never read as a body to gate on (issue #815).** Phase 2.2.5's scope decisions are stored as hidden `kind=deferred` records on `## Progress` bullets, and Phase 4.0 decides whether to load its follow-up-filing reference by asking `workpad.py deferred-presence <issue> <pr>` — never by reading the workpad body, which at Phase 4 is larger than the procedure being gated. The answer is **three-state, on the exit code** (`grep(1)`'s idiom): **0** `outstanding: <n>` plus one normalized `criterion:` line each; **1** `not-outstanding: <n>`; **2** `unestablished: reason=<token> unbound=<u> corrupted=<c>` — the workpad was unreadable, it does not carry exactly one `## Progress` section, records are still `pr=pending` or bound to a superseded PR, a bound record's payload is corrupt, or the isolated-bullet reader sees fewer records than the whole-body reader `acs-resolve` uses. Phase 4 **loads the reference on both 0 and 2**: an unavailable operand is never read as "nothing was deferred", because that reading strands deferred work silently while a needless load costs one read. The predicate is decided in Python over the record grammar `workpad.py` already owns — never through a `grep`/`tr`/`sed` pipeline, which `lib/preflight.sh` does not guarantee and which would fail *open* exactly where the tool is absent. Once a criterion's follow-up is filed, `workpad.py update --mark-deferred-filed '<criterion line verbatim>'` writes a durable `<!-- prflow:deferred-filed … -->` marker as its own isolated `## Progress` bullet, so a second Phase 4 entry files no duplicate; a value matching no `kind=deferred` record only breadcrumbs (it discharges nothing, and is never a mutation failure). Both readers scan **only** isolated `## Progress` bullets whose whole note text is the marker, so a marker-shaped literal pasted into an AC row, a reflection, or free-text note prose is invisible to them.
- **Rule:** never create a second workpad; always verify a status update actually landed. The **exit code** is the success signal for every mutation (see the failure-isolation rule below), and `update` writes nothing to stdout by default (issue #814) — the landed-`Status` read-back that an exit code cannot discharge comes from the one-line stderr success breadcrumb, which names the PATCHed comment id and, on a `--status` call, the `Status:` value read back from the PATCH response — plus a separate `WARNING` line whenever that read-back does not match the requested status. On the **volatile-tick-miss** path no success breadcrumb is written (the failure-isolation rule below), so there the read-back comes from that path's still-echoed body instead, and the miss is recovered by re-ticking only the named row — never by re-issuing the whole call. `--print-body` restores the old whole-body echo for a caller that genuinely consumes it.
- **Failure isolation (volatile vs. structural).** A `update` call PATCHes once. A **structural** failure (a missing target section, a missing `Status`/`Last updated` line, an unreadable `--*-file`, a failed `gh` PATCH, or a terminal `--status Complete` write with any non-post-merge `## Acceptance Criteria` row still `- [ ]` — the self-record gate that keeps a run from recording itself Complete over an unmet AC; unticked `## Plan` rows and an un-mirrored AC placeholder only warn) aborts the whole call before any change is persisted — all-or-nothing, as before. The one exception is a **volatile per-row tick miss** (a `--tick-*` substring matching zero or multiple rows, or a `--tick-*-n` index out of range or landing on an already-ticked row, *inside a present section*): it is **isolated, not aborted** — every other mutation (`--status`/`--note`/`--reflection` and any tick that did resolve) still applies and PATCHes, and the call then exits non-zero with a stderr report naming each missed tick. A miss is therefore never silently dropped, but because the body still PATCHes with the target row left `- [ ]`, callers must treat a non-zero exit from a tick call as "at least one tick did not land" and re-tick only the named row(s). The volatile-miss path is the one arm that still echoes the patched body to stdout under the default (issue #814) — it is the row inventory that positional re-resolution reads — and it writes **no** success breadcrumb, so a success-shaped stderr line never accompanies a failing exit code.
- In **cloud runs**, a lightweight `gate` job creates a lean workpad *before* the heavy Claude job boots, so the user gets immediate acknowledgment.
- **Run-link refresh on resume.** When a cloud `/prflow:implement` run stalls mid-PR and the stall-backstop auto-resumes it (or a human re-triggers), the resumed run lands on a **new** GitHub Actions run with a new run URL. The issue workpad's `Run:` link is rewritten to the current run at the workflow (`gate`) level (the early-workpad step calls `workpad.py update --run-link`), so an operator reading the **issue** clicks through to the active job's logs. The draft **PR** description's `[View run](...)` line — written once at PR creation (Phase 3.1) and never touched again by that path — is likewise refreshed to the resumed run at the **§1.4 Resume pre-check seam** (best-effort, REST `gh api` PATCH `pulls/{n}`, cloud-only; a local-tier resume leaves it absent), so a reviewer who arrives at the resumed run via the **PR** (not the issue) reaches the currently-active job's logs in one click. The two surfaces then agree on which run is live. (Accepted coverage boundary: the PR-body refresh fires inside the `claude` job at §1.4, not at the gate level, so a resumed `claude` job that stalls again before reaching §1.4 leaves the PR-body link stale until the next resume that gets past §1.4.)

- **Startup-lifecycle observability (issue #537).** A cloud run's workpad timestamps **up to four** startup boundaries (a normal fresh run writes three — the `gate-adopted` row only fires on the adopted/resume path) so an operator can attribute startup latency from the workpad alone, and it uses **truthful lifecycle wording** — a normal first run no longer falsely reads "run resumed". The mechanism has these parts:
  - **Handoff record.** The `gate` job decides this run's provenance — exactly one of `created-current-run` (gate saw no workpad and created one), `adopted-existing` (gate found an existing workpad), or `unknown` — and publishes it through a job output. The `claude` job normalizes it into a five-field JSON record (`schema_version`, `issue`, `run_id`, `run_attempt`, `origin`) written to `.prflow/tmp/implement-handoff-<issue>-<run_id>-<run_attempt>.json` before the action. It is workflow-owned, gitignored, non-secret, advisory, and is **not** passed through Claude action settings.
  - **`workpad.py handoff-state`** validates that record **offline** (no network) and prints the origin token, degrading every malformed/mismatched/missing shape to `unknown` with a targeted breadcrumb (so a lost record degrades visibly, never guesses).
  - **Lifecycle wording.** Phase 1.3 selects the hydration event from provenance × live status: `created-current-run` → `agent initialized; Phase 1 workpad hydrated` (never "resumed"); `adopted-existing` + an **interim** workpad → `/prflow:implement run resumed; …`; `adopted-existing` + a **terminal** workpad → `/prflow:implement new run initialized from terminal workpad; …`; `unknown` → `agent initialized; workpad provenance unavailable; …`. `run resumed` is reserved for adoption of an interim workpad from an earlier execution. Local runs read no cloud record and select from live status alone.
  - **Idempotent checkpoints.** `workpad.py update --checkpoint KEY TEXT` writes one timestamped `## Progress` row carrying a hidden `<!-- prflow:checkpoint KEY -->` marker. Keys are `gha:<run_id>:<run_attempt>:<stage>` with the closed stage vocabulary `gate-adopted` / `claude-invoke` / `phase1-entered` / `phase1-hydrated`; including the run **attempt** means a GitHub re-run gets fresh rows while a replay inside one attempt does not. A checkpoint-only replay whose keys already exist is a pure no-op — no `Last updated` refresh, no PATCH. Bounded-write discipline (AC19): the gate-adopted checkpoint is issued as a **separate** best-effort PATCH following the run-link refresh (a combined call would abort structurally on a legacy workpad lacking `## Progress` and silently drop the run-link refresh too), but it fires only on the **adopted/resume** path — never on a normal fresh run, which creates rather than adopts — while phase1-hydrated rides the Phase 1 hydration update, so a normal fresh cloud run adds at most two standalone PATCHes (`claude-invoke`, `phase1-entered`).
  - **Read-failure & race safety.** Phase 1 preserves `workpad.py id`'s three-way exit contract (0 found / 2 the sole create authorization / 1 unreadable-stop, never a duplicate create) and `status`'s 0/1/2/3 contract, reads the live body before resetting Status, and passes the observed comment ID + Status word as `--expect-comment-id`/`--expect-status` so a concurrent terminal-backstop flip or delete/recreate aborts the stale hydration before any PATCH (exit 4). Checkpoint failures are best-effort (warn and continue); the incomplete-vendor guard fails the job before the action when the vendored `workpad.py` is missing.
  - **Consumer version-skew.** An **old workflow + new plugin** lacks the handoff record, so Phase 1 degrades to `unknown` provenance and still runs. A **new workflow + old plugin** has a helper lacking `--checkpoint`/`handoff-state`, so the checkpoint steps warn and continue and Phase 1 keeps legacy `run resumed` wording. Duplicate-read protection is complete only once **both** the shipped workflow and the pinned plugin carry this fix.

### Phase 1: Setup
- **1.1** Fetch the issue (`gh issue view`), then **classify it bug-report / non-bug from its content** (title + body), with a `bug` label as one input signal; content overrides the label on a positive read, and ambiguity defaults to the label when present (else non-bug). Phase 2.1.5 keys on this recorded classification, not the label.
- **1.2** Parse Acceptance Criteria via `scripts/parse-acs.py`; tag post-merge items.
- **1.3** Initialize or resume the workpad; if `Status: Blocked`, surface the reflection and pause. Record the 1.1 classification as a superseding `classification: ` note and reconcile the reproduction row to it (`--record-classification` / `--reconcile-reproduction`) — a fresh run, a resume with no note, or a terminal re-trigger classifies afresh; an in-flight resume reads the recorded note. The same step also records a durable `resume-kind: ` note (`in-flight` / `terminal-re-trigger` / `fresh`) — the compaction-surviving signal the **Phase 2 §2.0 resume-idempotency gate** reads back (the live `Status` cannot serve, since 1.3 overwrites it to `Setup` on every arm), written as a bare literal and compared by exact value, never containment.
- **1.4** Create or detect the branch (`scripts/branch-for-issue.py`, off the config-driven `base_branch`). Branch creation is skipped when the run is already in a linked git worktree (naming-independent harness signal) or when the current branch matches a recognized feature-branch pattern — the existing branch is reused as-is. On the adopted-branch arm and (since issue #780) the landed-resume arm, §1.4.0.5 then runs the ahead-of-base branch-state preflight (Verdict B — `scripts/preflight.py branch-state`) before the update-branch checkpoint and the push (see the *Ahead-of-base branch-state preflight* note below). The **update-branch checkpoint is then the last step of §1.4 on every arm** — new branch, adopted branch, and landed resume alike (issue #779) — so Phase 1 reconciles with the base on every path, while the freshness record stays adopted-arm-only.
- **1.5** Push the branch.

### Phase 1.3.5: Early declared-dependency preflight
Between workpad hydration (**1.3**) and branch work (**1.4**), `/prflow:implement` runs an extracted declared-dependency preflight (`scripts/preflight.py`). It runs before branch adoption, creation, base reconciliation, and push, so open or unresolvable dependencies end the run Blocked **without a new branch side effect**. The cloud implementation requires both the vendored `scripts/preflight.py` helper and its explicit `devflow-implement.yml` allowlist grant.

### Phase 2: Discover, Plan & Implement
- **2.0 Resume-idempotency gate** (fires on an auto-resumed run before §2.1). The Phase 2 `code-explorer`/`code-architect` subagents produce **ephemeral, read-only, in-context** output — neither declares a `Write`/`Edit`/`Bash` tool, so a stall-backstop auto-resume cannot recover their analysis and the entry-gate `Read` restores only the §2.1/§2.2 *procedure*, which unconditionally re-dispatches them. The gate is the Phase 2 analogue of §1.4's Resume pre-check, keyed on the conjunction of a durable Phase 1.3 `resume-kind: in-flight` marker and a committed non-placeholder `## Plan`. On a fire it **skips** the discovery/architecture dispatches and re-plan and builds on the committed Plan and the §1.4-adopted branch — still running §2.2.5/§2.2.6 idempotently and re-verifying against a fresh tree (the #429 rules stay in force), routing to Phase 3 when the Plan is fully ticked and nothing remains. A fresh run, a run that died mid-§2.1 before any Plan, and a terminal re-trigger each fail a conjunct, so full discovery runs unchanged. The gate's fire conditions and skip scope are stated authoritatively at §2.0 of `skills/implement/phases/phase-2-implement.md`.
- **2.1** Discovery via the first-party `prflow:code-explorer` subagent.
- **2.1.5 Reproduce-First Gate** (fires when the recorded content classification is bug-report, not on the `bug` label): capture a reproduction signal (failing test / error log) *before* planning; if it can't reproduce → `Blocked`.
- **2.2** Assess complexity. **Simple** (≤5 files, clear, no architecture) → implement directly. **Complex** → the first-party `prflow:code-architect` produces a blueprint (held in context, never committed). Sub-gates: **2.2.4 Reuse & Altitude** (reuse existing helpers by `file:line`), **2.2.5 Scope-Adjustment** (multi-PR issues), **2.2.6 AC-Plan reconciliation**.
- **2.3 Implement** with mandatory post-write **sweeps** (the discipline that prevents half-finished changes — each heading states its own trigger; the six always-on sweeps — convention, boundary-assumption, self-authored-claim, coverage-claim enumeration, simplification, and error-handling — are the ones no diff shape deselects; each sweep's own heading stays authoritative, and 2.3.4b's states its trigger as a diff that adds prose):
  - **2.3.0** Changed-contract sweep (a modified signature/renamed-or-moved symbol/tightened validator/rerouted predicate — **or a relocated prose literal, heading, section, or file path** whose old-location citations, a `run.sh` pin / docs cross-reference / config-key list, would otherwise dangle → reconcile every dependent site; re-run after any merge/rebase of main)
  - **2.3.0a** Peer-checkpoint completeness sweep
  - **2.3.0b** Enum-enumeration reconciliation sweep (added value to an enumerated set → reconcile every enumerating site, incl. doc/comment enumerations and fall-through consumers)
  - **2.3.0c** Operand-trace sweep (a diff that adds a guard/predicate/validator/coverage invariant in code, or ships agent-executed policy-stating prose → trace every operand back to its producer; the load-bearing "what OTHER inputs produce the same value?" check owns exactly the in-diff code 2.3.4 carves out)
  - **2.3.0d** Describing-prose reconciliation sweep (a **removal** from an enumerated set, or a **weakened** universal — softened, scoped, or removed → reconcile prose the change falsified without editing it: describing prose naming no member literal, and surviving full-strength copies of the weakened claim; repo-wide enumeration reusing §2.3.0's normalized search, with an explicit unrunnable arm naming the covering backstop instead of a clean pass)
  - **2.3.1** Orphaned-setup sweep
  - **2.3.2** Stranded-dependents sweep
  - **2.3.3** Convention-compliance sweep
  - **2.3.4** Boundary-assumption verification sweep (claims the diff *depends on* about boundaries it doesn't own)
  - **2.3.4a** Self-authored-claim reconciliation sweep (every behavioral claim the diff *authors* in internal/external docs and code comments, reconciled against the shipped code path before commit; the code is the fact)
  - **2.3.4b** Coverage-claim enumeration sweep (every **coverage universal** the diff's *added prose* asserts — a sentence claiming a universal about the change's own coverage, "every call site is updated" — grounded before commit one of three ways: pinned by an executed enumeration of the set the quantifier ranges over, scoped to what the change actually covers, or removed. Reading the sentence back does not discharge it. Seeded by `scripts/stale-prose-lint.py`'s recognition-only coverage-universal tier run in its `--worktree` mode over the uncommitted delta; the detector's rows are a floor, not the population. Its twin 2.3.4a owns claims about what the shipped *code* does — a coverage universal describes the *change*, so that trace never selects it)
  - **2.3.5** Simplification & efficiency sweep
  - **2.3.6** Error-handling & silent-failure sweep
  - **2.3.7** Collection-cardinality sweep (trigger-gated: an added collection output with ordering/dedup/aggregation logic → a multi-element test case; a single-element test does not discharge it)
- **2.4** Run tests + lint in parallel; fix failures.
- **2.5** Commit (`feat:`) and push.

### Phase 3: Review & Fix
- **3.1** Create the **draft** PR against the configured `base_branch` (`Resolves #{issue}`) — behind an **existing-PR guard**, because a resumed run (a §2.0 gate fire, or any run whose §1.4 pre-check adopted a branch/PR) reaches 3.1 with the prior attempt's PR already open and a bare create would abort. The resolution is branch-selecting logic, so it lives in `scripts/resolve-existing-pr.sh` — invoked as a single leading-token vendored-literal command taking only the issue number, with the head branch and base re-derived inside the helper — and `lib/test/run.sh` drives every arm and the arm order over the full input matrix, per the repo's workflow inline-shell extraction convention. The helper queries `gh pr list --head … --state open` (open-scoped and branch-explicit — never `gh pr view`, which resolves across OPEN/CLOSED/MERGED), picks the newest by `createdAt`, and prints exactly one token with a matching exit code: `ADOPT <n> OK` (0), `ADOPT <n> WARN:<checks>` (0), `CREATE` (2), `REFUSED` (3). It has no silent path, so a fence that prints nothing is a harness refusal routed as `REFUSED`. **Adopt** takes the found PR (never re-writing its body, and reading its URL by explicit PR number so link and number cannot disagree) — and adoption is *validated*, not head-branch-match alone: the helper checks that the PR lists the run's issue in `closingIssuesReferences` and targets the run's base, naming each failed check in the `WARN:<checks>` token (`closes-issue`, `base-ref`). A `WARN` adoption still proceeds — a visibility obligation, not a stop — with the failed checks recorded durably on the workpad as a `note` reflection. **Create** runs when the query cleanly found none; **REFUSED** (never collapsed onto create) is on a *resume* a terminal `Blocked` stop with a durable reflection rather than a duplicate PR, and on a *fresh* run falls through to the create (no prior attempt to duplicate). A create that itself fails takes the same terminal stop; the create and PR-link fences print their own outcome tokens so success is read, not inferred.
- **3.2** Self-review with the built-in `/simplify` skill; commit fixes (`refactor:`).
- **3.3** Run `/prflow:review-and-fix --push-each-iteration` (the flag propagates each iteration to remote so CI validates). Handles the loop's verdicts, including the special `APPROVE WITH UNRESOLVED SHADOW FINDINGS` (a bounded single re-review). A non-clean exit (AWUSF or `REJECT`) routes through a **severity-aware exit**: only a genuine unresolved Critical (or an unparseable verdict) takes the Blocked path; a non-Critical residual soft-proceeds (surfaced, PR left review-ready).
- **3.4 Acceptance Criteria Gate:** every **non-post-merge** AC checkbox must be ticked (via a passing test, a documented manual check, or a `file:line` reference) before the phase passes. The gate ticks confirmed ACs **by 1-based section index** (`--tick-ac-n`, repeatable in one call) rather than hand-picked prose substrings, and gates on the tick call's **exit code**: a volatile index miss still PATCHes the body while leaving the AC `- [ ]`, so the gate passes only when the targeted row reads `- [x]` **and** the tick exited 0 (an unresolved index re-resolves or routes to Blocked). A `(post-merge)` tag is allowed **only** for a criterion that genuinely needs a runtime environment absent during the run (a live deploy target, a real third-party endpoint). A criterion that is runnable on the orchestrator host — or blocked only by a local tooling/environment gap — or any criterion whose purpose is to confirm a behavioral claim the PR already asserts, or any **self-reconfiguration** criterion whose only unmet precondition is the orchestrator's own session/harness/account being in the configuration the diff just shipped (a hook the diff registered now active, a flag/setting the diff added now enabled — issue #338), is **never** retagged post-merge; it is run-and-evidenced (an automated test driving the now-active path, or a separate session observing the change live) or takes the existing **`Blocked`** escalation path instead. Every mid-run `(post-merge)` retag via `--rewrite-ac` is auditable: `workpad.py` structurally rejects a `--rewrite-ac` call that appends the tag (a single pair or a crafted multi-pair sequence) without a non-empty `--note` rationale (issue #338). This makes the gate enforce "verified before merge" rather than trust the run's narrative. As a special case, an AC whose verification is *running a test/lint/build command* that was **not** observed passing locally is never satisfied by CI deferral alone: after a genuine local-denial fallback, the gate reads the **`lib + python tests`** result for the current `git rev-parse HEAD` and splits three ways — observed **green** for HEAD → tick (recording the gh-resolved SHA via `--note`/`--reflection`); observed **red** for HEAD → the **Blocked** path (a red CI is a real failure, not a deferral); **not-yet-reported** or unreadable → retag `(post-merge)` so the human merger confirms it. A grep of a few SKILL-contract pins is not a substitute for the suite.

### Phase 4: Documentation
- **4.0** File follow-up issues for deferred ACs.
- **4.0.5** Discover the run-scoped deferral manifests (via `scripts/discover-deferral-manifests.py`), merge them into one slug-level aggregate, then file **one follow-up issue per source file** (via `scripts/file-deferrals.py`) for review findings deliberately deferred during the fix loop. Discovery is **status-bearing** (issue #555): the helper searches each candidate root *independently*, classifies each `ok`/`absent`/`failed`, and carries the outcome in its exit code (`0` clean, `3` partial, `4` all-failed) with fixed stderr markers on the degraded outcomes — so a search that *failed* is no longer indistinguishable from a genuine no-match. The phase records `discovery=` on its unconditional sentinel and routes fail-closed: only `ok`/`partial` may file, `failed` (or a refused discovery command, which prints nothing and lands as `discovery=[]`) records a `dropped-failed` reflection and files nothing, and only `discovery=[ok]` with an empty manifest is read as the clean no-op. The predecessor — one multi-root `find … | sort` whose exit status the pipe masked and the capture discarded — read a degraded search as that clean no-op and silently stranded acknowledged deferrals (observed live on issue #533).
- Both deferral channels (4.0 and 4.0.5) label the follow-up issues they file with the configured **`deferred.labels`** (comma-separated, default `PRFlow,Deferred`) — resolved via `config-get.sh`, normalized like `docs.labels`, ensured via `ensure-label.sh`, and applied best-effort after creation so a label hiccup never blocks filing (an empty/whitespace-only value applies none). Labeling lives in the skill, not `file-deferrals.py` (config stays resolver territory — read through `config-get.sh`, not from Python); it is independent of the hardcoded `PRFlow` provenance label (and its superseded `DevFlow` spelling) the retrospective scan matches.
- **4.1** Update internal + external docs + release notes (via the `/prflow:docs` subagent); commit (`docs:`); apply configured labels (default `Documented`).
- **4.2** Generate the PR description (`/prflow:pr-description`).
- **4.3** Run the pre-ready base-branch update checkpoint, then publish the PR (`gh pr ready`) — unless `prflow_implement.implement_pr_state` is `draft`, which leaves it the Phase 3.1 draft for a human to publish; set status `Complete`; emit the 🎉 reaction (both cases). Since issue #779 both the publish and the `Complete` flip are **gated on the checkpoint reporting a clean token** — a non-clean one records `Blocked` naming the observed line instead (see [`docs/implement-skill.md`](implement-skill.md)).

### Single-flight verification (issue #528, Wave 2)

A PRFlow lifecycle can launch the same multi-minute verification profile many times — Implement's inline review pass and each Review-and-Fix iteration relaunch the full suite, and a timeout, lost tool result, or compacted context can force yet another launch. `scripts/verification-flight.py` coordinates each **same-checkout** full-verification flight so an unchanged suite is not re-run, **without ever executing the command itself** (it launches no subprocess, accepts no executable argv, and runs no `git` — the existing caller keeps command ownership and allowlist enforcement).

- **Handle lifecycle.** The owner `claim`s a flight (atomic `O_CREAT|O_EXCL` publish, one owner only; a one-time owner token is returned and only its SHA-256 digest is stored), records `mark-running` immediately before launching its already-authorized command, then `finish`es with terminal evidence (suite summary, terminal result, `skipped_checks`). A later same-checkout caller attaches and `status`/`wait`s to **consume** a `passed` result instead of relaunching. Every **owner** transition (`mark-running`, `finish`) is a token-checked compare-and-swap; attacher, stale-token, replay, and post-terminal transitions are rejected. The two **read-time invalidations** are deliberately tokenless and non-owner — a `claimed` handle whose lease expired before `mark-running` becomes `incomplete`, and an active handle whose stored checkout no longer matches a supplied current checkout becomes `stale` — and each can only move an active handle to a **non-pass** terminal state, never to `passed`.
- **The flight key.** The reusable identity binds a **command descriptor** — sorted-key compact UTF-8 JSON of `{profile_version, argv, cwd, environment, toolchain, dependencies}`, SHA-256'd by the helper — plus checkout identity, HEAD, index, tracked changes, and untracked inputs. Commits, edits, merges, rebases, profile changes, and relevant dependency changes all change the key and so **invalidate reuse by construction**; generated suite outputs under declared `output_roots` never churn the key — **an exclusion the caller-supplied `checkout` fingerprint carries, by the caller's discipline; `_derive` folds only `profile` and `checkout` into the key and enforces no output-root rule of its own.** Separately (issue #668), `scripts/verification-flight.py` accepts an optional top-level `candidate_identity` declaration field — the content-based identity `scripts/reception_identity.py` derives (see below), recorded verbatim on the handle as an **independent observability field that does not participate in the key**. It is a sibling of `checkout`, never a member of it, so `descriptor_digest` and `flight_key` stay byte-unchanged and every stored handle stays valid.
- **Unknown is never a pass.** States are exactly `claimed`, `running`, `passed`, `failed`, `timed_out`, `cancelled`, `stale`, `incomplete`. Only `passed` with complete matching bindings satisfies verification. Missing/partial/timed-out/unreadable/stale state is an attributable non-pass and never authorizes an automatic relaunch; a lease that expires before `mark-running` becomes `incomplete`; checkout drift becomes `stale`; missing terminal evidence becomes `incomplete`. A `wait` bound elapsing returns a non-mutating `wait_expired` observation — only the owner records a terminal `timed_out`.
- **Consumers.** Implement persists the handle + terminal evidence in its durable state and re-anchors after nested work/compaction; Review-and-Fix persists them in its `iter-<N>.json`. On `wait_expired`, Implement and implement-driven Review-and-Fix take the existing **Blocked** path without relaunch; standalone Review-and-Fix records `verification_evidence.result: skipped` (reason `flight_wait_expired`) and cannot report a clean pass. **CI-grounded standalone `/prflow:review` creates no flight and runs no verification command.** Config lives under the versioned `verification_flight` namespace; the vendored helper is granted in `devflow.yml` and `devflow-implement.yml` only — `devflow-runner.yml` gains no grant.

### Receiving-review session artifacts (issue #668)

The `receiving-code-review` skill's **Reception Preflight** now produces a machine-checkable session identity instead of only rendering in-chat facts. Two bundled helpers ship (by the `prflow_version` vendor fetch), and their cloud grants ship by `install.sh`'s workflow copy loop — two independently-upgraded artifacts, so the two-halves upgrade coupling applies.

- **`scripts/reception_identity.py`** — an importable, python3 standard-library-only routine exposing `derive_candidate_identity()`. **The candidate identity is the git tree object ID of the working-tree *content*** — tracked files at their working-tree content plus untracked non-ignored files, with gitignored content and HEAD excluded. It is derived through git's own index-cached plumbing: a temporary index **seeded from the current index** (load-bearing — it preserves the skip-worktree entries a cone-mode sparse checkout leaves off disk), a `git add -A` staging all such content including deletions and renames, and a `git write-tree`. **The current index is an input, not an exclusion:** for an ordinary path `git add -A` resolves the entry to worktree content, but for an entry git deliberately does not re-stat — a skip-worktree (sparse) entry, or an `assume-unchanged` (CE_VALID) entry — the index content decides the value, so an `assume-unchanged` path's worktree edit does not change the derived identity. That is the documented consequence of seeding from the real index, which sparse-checkout correctness requires. The repository's own index is never modified and no history is read. **Contract:** for a working state whose content is then committed unchanged (a commit form that stages untracked content), the derived value is byte-equal to `git rev-parse HEAD^{tree}` after that commit — commit-invariant across the recorded content — while any tracked-content change after the verified state compares unequal. `git commit -am`, which stages tracked modifications only, correctly compares unequal for a derivation that included a new untracked file. Every failure mode raises a named breadcrumb and yields no identity.
- **`scripts/reception-record.py`** — the CLI. One `record` invocation derives the identity (via the library — exactly one implementation ships), mints a per-session cryptographic **claim-context nonce**, and writes an **identity artifact** and a **findings ledger** under the gitignored session directory keyed by the nonce, plus a fixed-name **session pointer** naming them. It confirms the directory is ignored — through `git check-ignore`, not a path-shape assumption — before writing, so a repository lacking the ignore rule is reported rather than given a self-invalidating identity. `append-disposition` appends one per-finding disposition with a **helper-assigned finding id**; a deferral disposition must name one of the skill's four durable channels or is rejected.
- **The two new preflight facts.** The block grows from nine to **eleven facts** — candidate identity (fact 10) and claim-context token (fact 11) — each carrying a status from the skill's existing six-member closed set. Both render `established` only when the invocation exits 0 **and** its stdout parses as a JSON object carrying both values; any non-zero exit, absent or non-parsing stdout, or a stderr `{"ok": false}` record renders both `missing` and the run continues (causes: absent, denied, unavailable interpreter, an unignored/unwritable session directory, or a failed identity derivation). The predicate is the exit status plus the stdout parse, not "produced no output" — every failure path writes a record to **stderr**, so a no-output test would never reach the `missing` arm. The editing gate is untouched (it bars only on a `mismatch` head-match verdict or an `ambiguous` subject).

### The completion-evidence check (issue #550)

A receiving-review completion claim is now gated on a **producer-owned completion-evidence check** so a claim's own evidence is validated before a maintainer merges on it. `scripts/check-completion-evidence.py` is a thin, deterministic, semantic-free validator (python3 stdlib-only, repo-agnostic): it re-derives the claim-time candidate identity by **calling** `scripts/reception_identity.py` (one identity implementation, never a second) and validates a claim against current, producer-owned artifacts — the durable verification record (the #528 handle), the candidate-identity and findings anchors, the disposition ledger, and any deferral traces — printing exactly one verdict line, `completion-check: <token> — <detail>`.

- **Eight tokens, first failing class wins** (presence/parseability/binding evaluated before any value comparison): `pass` (exit 0) → `missing-evidence` → `stale-candidate` (the recorded candidate identity differs from claim-time content) → `verification-not-pass` → `skipped-checks-present` (a blocking-gate or unclassified skip, fail-closed; host-capability skips are surfaced in the detail but never flip the token) → `undischarged-findings` → `non-durable-deferral` → `unverifiable-trace`. Each non-pass exits 1; an internal failure exits 2 and prints no verdict line. Unknown never collapses onto `pass`.
- **What stays out (semantic exclusion).** The validator re-grades no severity, re-judges no fix, re-runs no test, and evaluates no finding content beyond the presence and binding of its disposition trace — it validates references (existence, parseability, identity-binding, set-emptiness, trace presence). The loop's own routing pre-scopes the effective fix set (findings marked `in_fix_set`), so the validator performs no severity comparison. A run.sh negative asserts the validator source spawns no subprocess whose head is anything other than the resolved `gh` (its only spawn, on the remote-trace arm); git is confined to the imported identity-derivation routine.
- **Two invocation contexts.** The `receiving-code-review` Verification Gate gains a fifth evidence item — run the bundled check via the portable anchor, quote its verdict line verbatim, and phrase the claim "complete" only on a quoted `pass` (a named non-pass token states what is missing; no verdict line at all is the `degraded: unvalidated (<reason>)` arm, never read as `pass`). The `review-and-fix` loop discharges the same item at **Loop Exit** over its run-scoped records, refreshing the verification record on an identity-keyed mismatch (the Step 3.5 inner-re-fix case) and carrying any non-pass token into its final verdict line (`<verdict> — completion evidence: <token>`); where an issue workpad exists a non-pass verdict is additionally recorded as a `## Devflow Reflection` bullet (the status-word vocabulary is untouched).
- **Deferral traces.** A deferral is durable when its trace resolves in one of the four channels: the loop-record manifest, an in-tree code-comment marker, or a remote PR-thread / follow-up-issue reference. A remote reference that 404s **in the validator's own repository** (read access established) is a provable absence → `non-durable-deferral`; a 404 **outside the credential's provable scope** is `unverifiable-trace` (GitHub serves 404 for unauthorized reads, so absence there is unknown). The remote arm reads `gh` via `DEVFLOW_GH` with no probe and degrades to `unverifiable-trace` when GitHub is unreachable — no network in the test suite (the suite's `gh` stubs drive every remote arm).
- **The attach-path residual is closed here.** `candidate_identity` is outside the flight key, so two declarations sharing a checkout fingerprint but declaring different content identities map to one handle. As the first consumer to read the handle's `candidate_identity` as authoritative, the check closes the PR #681 residual: on attach, a declared `candidate_identity` that differs from the handle's is no longer a reusable pass (`reuse_ready`/`candidate_identity_match` are False) — while `descriptor_digest`/`flight_key` stay byte-unchanged, so every stored handle stays valid.

The plugin tree (the validator + skill bodies + tests) ships via the `prflow_version` vendor fetch; the two workflow allowlist grants ship via `install.sh` file-copy — the two-halves upgrade coupling applies. A consumer that upgrades one half gets a silently-denied validator on cloud runs, which the no-output-is-degraded rule converts into a visible `degraded: unvalidated` outcome, never a silent pass.

---

## 8. Deep dive: the review engine

`/prflow:review` and `/prflow:review-and-fix` share the **same engine**: Phases 0–4.3 are executed verbatim by both. `/prflow:review` reports a verdict; `/prflow:review-and-fix` wraps the engine in a fix loop and skips the GitHub-posting phase.

### The engine is a bundle, not one file (issue #529)

The engine used to be a single `skills/review/SKILL.md` that every caller read end to end, whatever the run actually needed. It is now a **bundle**: a thin state-owning root at `skills/review/SKILL.md` plus per-phase reference files under `skills/review/phases/`. The root keeps only what the whole run shares — the live-progress-comment machinery, the per-subagent overrides block, the cross-phase invariants, the prompt-extension load, the phase routing table, and the fail-closed entry. **Each phase's authoritative procedure lives in its own reference**; the routing table's phase descriptions are orientation only, and the reference wins wherever the two could be read against each other. Some references are gated out of a given run by predicates the earlier phases establish — standalone-only mode, a config toggle, an adjudication that has something to adjudicate — so an ordinary run loads only the references it needs, which is what makes the default path cheaper than the old read-everything monolith. Keeping the root and the per-phase references lean stays an ongoing goal — less prompt prose loaded per pass is less budget spent — but it is a matter of authoring discipline, not a mechanically enforced ceiling.

**The entry gate (mandatory on every phase entry).** Before acting in a phase, the engine re-derives **root identity**, `Read`s that phase's reference, and clears the reference's **boundary contract** — in that order, never from an earlier read or a remembered summary. This applies to a `/prflow:review-and-fix` Step 2.6 **shadow** entry too: a shadow entry is a phase entry.

- **Root identity.** At engine entry the root resolves its own skill directory (via the portable single-statement anchor — see §6) and hashes itself and its references with `git hash-object`, authoring a bundle manifest — canonical root path, root hash, and each reference's path and hash — into the run-scoped scratch dir. Re-deriving means re-resolving the anchor, re-reading the manifest, and re-hashing the root and the reference about to be read. A hash that cannot be derived, a manifest that is absent or unparseable, a root that has moved, or a hash that no longer matches each stops the phase under its own named label. Every path resolves relative to the **located root**, never to the working directory — which finds nothing under a vendored install and would strand the engine.
- **Boundary contract.** Each reference carries a `prflow:review-ref` start marker as its literal first line, and the matching end marker as its literal last line. Each marker names the reference's own phase id and path, so a mis-routed read — a marker naming a different phase or file — matches nothing and fails closed. After the `Read`, the engine quotes the body's actual first and last lines and decides the outcome from those quoted lines rather than from an impression that the markers look right. A refused read, an empty body, absent markers, a half-present pair, duplicates, a reversed pair, and a pair that is present but not first-and-last each carry a distinct stop label, tested in a fixed order so the first to fire is the attributed shape.

On any identity or boundary stop the engine reports the label with the phase id and reference path and does **not** act on the body, improvise the phase from its orientation text, or repair the file. This is the point of the contract: a body can read as complete and correct and still fail these checks, and that case *is* the reason they exist — a defective boundary or identity means what the engine holds is not the bundle it was built against, so the body's plausibility is worth nothing.

Because the bundle is the engine, the **reviewed surface is every source in it, not just the root**: the command-head and command-shape scanners take the whole bundle in one call, and the suite asserts engine-content pins against the concatenated bundle, so a sentence may move between references without breaking its pin.

> **The thesis (good for a technical-deck slide):** don't trust a single review pass. Build an *independent, evidence-based* checklist of every claim the diff makes, verify each claim against the actual source, run a panel of specialized reviewers, and use cross-reviewer corroboration to *calibrate confidence* in each finding, a single-source finding is flagged for extra human scrutiny, never silently dropped.

### Phase 0: Setup & diff classification
Caches the diff to a run-scoped path. **Phase 0.5** classifies the diff with five flags that decide the engine profile:
- `small_diff` (<100 changed lines AND ≤3 files)
- `config_only` (all changed files are config/docs extensions)
- `has_new_types` (added code defines classes/interfaces/types/enums/structs/traits)
- `engine_self_modifying` (touches `skills/**`, `agents/**`, or `lib/**`)
- `detect_all_audit` (the diff adds/changes a "detect-all" scanner/audit/coverage-invariant — code that *enumerates a population* AND *asserts a completeness property* over it)

**Phase 0.4 — issue discovery and acceptance-criteria resolution (runs before 0.5).** Two independent resolutions happen here: *which* issue this PR is about, and *which* set of acceptance criteria the engine judges against.

*Issue-number precedence.* A caller-supplied `--issue N` — the flag both `/prflow:review` and `/prflow:review-and-fix` parse out of `$ARGUMENTS` and bind as `$ISSUE_OVERRIDE` — **suppresses** both derivations: it is not run alongside them and never compared against them. With no override, the engine falls back to the PR body's `Resolves`/`Fixes`/`Closes` reference, then to the `issue-{N}` branch-name pattern `/prflow:implement` sets. (The cloud comment tier is unaffected: `scripts/resolve-command-trigger.sh` synthesizes a two-token command, so a `--issue` typed into a trigger comment is discarded before the skill runs and that path keeps the derivations.)

*Criteria precedence.* The engine does **not** read acceptance criteria off the GitHub issue body. `/prflow:implement`'s authoritative set lives in the **workpad comment** — Phase 2.2.5 narrows it, 2.2.6 rewrites its text, 3.4 retags it — so a review judging the issue body would be judging the PR against a specification the implementing run had already, legitimately, moved. Phase 0.4 therefore calls `scripts/workpad.py acs-resolve`, which does the whole resolution deterministically in one process: it fetches the issue body itself, resolves **both** surfaces (never a short-circuit chain, because the non-selected set is the divergence comparand), parses the workpad section once and renders that one item list twice — unfiltered as the comparand, post-merge-filtered as the reviewer-facing value — runs a **PR-identity guard** confirming the workpad section belongs to *this* PR rather than to a sibling PR's run on the same issue, and selects the value. The precedence is: the workpad set when it is confirmed as this PR's, otherwise the issue body. The selected criteria are handed to later phases with their tick column **neutralized** — a tick is Phase 3.4's assertion *by the author of the code under review* that a criterion is met, and the merge-gating judge must not be handed a specification pre-annotated by the party it is judging.

*The source token.* Every resolution names its own source, and `acs-resolve` exits 0 on every resolvable state — an absent or unreadable workpad is a *routed outcome carrying a token*, not a run-ending error. The token set (`workpad`, `issue-body`, `workpad-unmirrored`, `workpad-read-failed`, `pr-identity-mismatch`, `resolver-unavailable`, `none`) is defined authoritatively in `skills/review/phases/phase-0-setup.md` §0.4, and Phase 4's `## Issue Compliance` section renders **each token in its own distinct wording** (`skills/review/phases/phase-4-verdict.md`) — collapsing any two destroys the signal. The distinctions that carry the most weight: `resolver-unavailable` means the helper never ran, so *neither* surface was examined and nothing is known about whether criteria exist — an unestablished measurement that is never collapsed onto the real value `none`; `workpad-unmirrored` means a PRFlow run's mirroring silently failed, the opposite claim from a PR that simply has no workpad; and `workpad-read-failed` is a transport failure that must never present as a normal issue-body resolution. The engine also reports **normalized** divergence between the two surfaces — post-merge tag stripped, tick state ignored, whitespace collapsed — so a criterion the issue body carries and the workpad dropped with no recorded scope decision surfaces as a finding, while decisions the run did record read as audited narrowing.

*Criteria are never truncated.* Phase 0.4's 200-line cap on the issue body bounds the narrative `issue_context` **only**. It never bounds the criteria, which `acs-resolve` locates structurally and carries in full however far into the body their section begins.

A `small_diff AND config_only` change skips the checklist phases (intentional). An `engine_self_modifying` change forces the **full** checklist — it is a checklist-only override and forces no Phase 3 agent on; the Phase 3 roster is decided by Phase 3.1's applicability gates on every profile. `detect_all_audit` is additive (it never suppresses the other flags' profile): it forces a **Phase 3.1.5 completeness-critic pass** that independently re-enumerates the audit's target population by a signal *other than the audit's own pattern* and records any uncovered member as a finding — the engine's guard against a vacuous or self-certified "detect-all" audit.

**Phase 0.6 — deterministic stale counted-prose lint (runs immediately after 0.5).** A deterministic pre-pass, `scripts/stale-prose-lint.py` (python3-stdlib), that flags **diff-added prose whose counted claims a later commit outgrows or falsifies** — the authoring-speed front line in front of the LLM self-contradicting-diff carve-out. It reads the unified diff the engine already cached in 0.2 on stdin and resolves each claim's referent against the current head via an explicit `--rev HEAD` (never `git merge-base`, so it is shallow-clone safe), emitting TSV rows (`verdict<TAB>rule<TAB>file<TAB>line<TAB>detail`) and exiting `0` (no STALE), `1` (at least one STALE), or `2` (internal error). Four rule classes, defined authoritatively in the helper's own header (the engine does **not** paraphrase them): **R1** a range header its block outgrew ("Cases A–B"), **R2** a legend sum contradicting an `Expected total = N`, **R3/R3b** an exact `count-locked` header (exact/two-item counts), and **R4** a deny-absolute about a shell operator token the same file also asserts permitted. Each `STALE` row enters **Phase 4.2 verdict computation** as an engine finding at the config-gated severity, carrying its TSV row verbatim as evidence — no new verdict rule and no new accounting rule. `UNRESOLVABLE` rows are informational and **never gate**; `VERIFIED` rows need no action. The lint is **move-aware** (issue #629): a diff-added prose line that is a byte-identical relocation — an extraction refactor moving prose it did not author — is never graded `STALE` but is *demoted* to an `UNRESOLVABLE` row naming the relocation, under multiplicity and referent rules the helper's header defines authoritatively (again, not paraphrased here) along with the design record bounding the exemption. The lint also honors an **illustrative-example opt-out** (issue #635): a prose/comment line carrying the plain, language-agnostic marker `stale-prose-lint: example` is skipped for **all** rule recognition (R1–R4 and both non-gating recognition tiers) — so a design-record example, a fixture-comment idiom, or engine docs *describing* a claim shape are no longer graded as a real claim of that shape — and instead of falling silent the helper emits one non-gating `UNRESOLVABLE` "EX" audit row, exactly as with the move-aware demotion; the marker match, its trailing negative-lookahead (so `examples`/`example-driven` do not match), and the disclosed non-goals are defined authoritatively in the helper's own module-header design record. Because the engine is shared, standalone `/prflow:review`, `/prflow:review-and-fix`, and the shadow pass all inherit the phase identically. A second **recognition-only** tier (issue #818) sits alongside the `count-locked` one and the `EX` audit row: it recognizes a **coverage universal** — a *coverage-scope* token from a closed set (deliberately wider than the universal quantifiers: `only`/`complete`/`entire`/`whole` are scope claims and are recognized too) adjacent to a coverage-referent noun from a closed set ("every call site", "all four arms") — and emits a non-gating `CU` row, plus an `RT` row for the declared `stale-prose-lint: rule-text` opt-out, whose visibility property mirrors `EX`'s; both closed sets are specified authoritatively in the helper's header, not here. Like the `count-locked` tier it resolves no referent, never emits `STALE`, and leaves the four gating classes' own verdicts untouched — the one control-flow change is that R4's short-circuit now fires only when R4 actually emitted a row, so a deny-absolute carrying no backticked operator token no longer silently swallows either non-gating tier (it can add only non-gating rows, never change the exit code). The two non-gating tiers overlap by design and neither terminates the other, so a line matching both emits both rows. Phase 0.6 emits these rows like any other, but does not **act** on them — their consumer is the implement engine's Phase 2 §2.3.4b sweep, which runs the helper in its `--worktree` post-image mode — the on-disk file rather than `git show <rev>:<path>` — so an **uncommitted** tree, including a brand-new `.changeset/*.md`, resolves to its post-change content and the claim is grounded before commit rather than at review time. Detection ships in the engine; the pin-or-don't-write policy for a `count-locked` row lives in this repo's `.prflow/prompt-extensions/review-and-fix.md`.

*Cross-run adjudication carry-forward (issue #466).* A STALE row is re-derived from scratch every run, so a false positive the lint keeps raising (a `count-locked` claim that is actually accurate against HEAD — the lint miscounted) would re-gate on every run with no channel to make a prior triage stick. The engine carries a false-positive adjudication forward across runs. **Producer (Phase 4.1.7, PR mode):** when a run's Phase 4 triage resolves a STALE row's claim against HEAD and finds it accurate, it renders the finding Informational with the **concrete referent evidence** (the true count and what the lint miscounted) and stamps one hidden payload line — `<!-- prflow:lint-fp-adjudicated <base64 of the row's TSV> -->` — inside a sentinel-delimited adjudications section of the run's `prflow:review-progress` comment (written only by the Phase 4 finalize write). base64 keeps a `--` in the detail excerpt from terminating the HTML comment; a row with no recorded referent evidence is not stamped, and **an `R4` (modality-conflict) row is never stamped** — see the rule-scope carve-out below. **Consumer (Phase 0.6, PR mode):** before STALE rows are finalized as findings, the deterministic, network-free helper `scripts/match-lint-adjudications.py` (the sibling of `scripts/match-deferrals.py`) joins the current rows against the payloads found in this PR's own prior **trusted** progress comments and returns a demotion map; a row whose decoded `(rule, path, detail)` is **byte-for-byte identical** to an adjudicated payload (the TSV line number is excluded from the key, so a renumbered paragraph still matches, while any change to the detail text re-examines the prose fresh) is demoted to Informational — annotated `previously adjudicated false positive (run <run-key>)` — and excluded from verdict computation at every configured `stale_prose.severity`. **Rule scope — `R4` is never carried forward.** The match key is safe only because the count/range rules (`R1`/`R2`/`R3`) embed the *observed referent* in their detail, so moving the counted code changes the detail and a stale adjudication stops matching. `R4`'s detail is a pure function of the *claim* line and says nothing about the permitting line, so an old `R4` adjudication would keep matching after a later commit added a **genuine** contradicting permit — demoting exactly the self-contradicting-diff finding the lint exists to catch. `R4` rows are therefore never stamped and never demoted; the exclusion is counted (`rows_rule_excluded`) and surfaced, never silent. **Trust** requires the run-keyed `prflow:review-progress` marker on the comment together with a `Bot`-type author (or a login in `.prflow.allowed_bots`, read via `config-get.sh`); payloads are honored **only** inside the sentinels (a payload quoted anywhere else — e.g. in a rendered evidence line — is data, never an instruction), ambiguity (two current STALE rows sharing a payload key) never demotes, and a malformed payload is skipped with a breadcrumb. The join is **PR-scoped by construction** (it reads only this PR's own comments) and **degrades loudly** — an absent, refused, or erroring helper leaves every STALE row at its configured severity and records a degraded-check note, never a silent skip. The blast radius is bounded to the severity gate: a demoted row never drives the threshold-independent self-contradicting-diff carve-out.

*Line scoping (issue #434).* A claim is prose, so only **comment/prose lines** are examined — a line of *code* that merely contains claim-shaped text (a shell fixture string, an assertion name) is data, not an assertion about the file. The helper decides this per file type: markdown-family prose outside fenced code blocks; `#` comments (`.sh`, `.yml`, `.jq`, `Makefile`, …); `//` comments and `/* … */` interiors (`.ts`, `.go`, `.rs`, `.java`, …); and, in Python, `#` comments plus genuine docstrings (resolved with `ast`, so claim-shaped *string literals* in test fixtures are not mistaken for prose). The same predicate scopes **R4's permit referent**, so a code line can neither raise a claim nor contradict one. **An unrecognised file type fails OPEN** — every added line is examined, exactly as before, with a stderr breadcrumb naming the extension. This direction is deliberate and load-bearing: a closed allowlist would silently reduce a consumer repo in an unlisted language to a permanent no-op (empty output, exit `0`, forever) while this page still advertised the check, so a file type PRFlow has not listed degrades to the *status quo*, never to *no checking*. Deliberately not examined (accepted limitations, not accidents): `.sh` heredoc prose, YAML block-scalar prose, trailing comments after code, and `#` comments inside ```` ```bash ```` fences in markdown.

*Excluded population: machine-appended corpora (issue #672).* Diff-added lines under `.prflow/learnings/` and `.prflow/logs/` are not examined at all. Those files are records PRFlow *writes* — a retrospective, an experiment record, a log — each quoting reviewed prose verbatim inside a JSON string. The quoted text is data about a past PR, never an assertion about the file it now sits in, and the post-diff state holds no referent to resolve it against. Rewriting any such record therefore re-presents it as diff-*added* prose and grades a previous PR's counted claim as though this PR had authored it, which is how a redaction pass that only replaced an operator home path with `~` failed the lint's own self-scan. The exclusion is keyed to the path rather than to any one edit, and each excluded path is named on stderr — an intended coverage drop is still a coverage drop, and stays as discoverable as the fail-open arm above. `CHANGELOG.md` and `.changeset/` are deliberately **in** scope: both are human-authored prose about the current change, exactly the surface the lint exists to grade.

*Config gate.* `prflow_review.stale_prose.enabled` defaults `true` (only an explicit `false` disables the phase — the fail-safe, feature-on direction) and `prflow_review.stale_prose.severity` defaults `important` (enum-validated inline to `critical|important|suggestion`, falling back to `important` on a bad/absent value with a breadcrumb), both read through `config-get.sh`.

*Degradation arms (fail-safe, never fail-silent — the run proceeds in every arm and the note is visible in the review report):* **(a) harness-refused invocation** — the command never executes (the consumer-skew state: a consumer's installed workflow `TOOLS` grants lag the vendored plugin) → record a note **naming the missing grant and the tier-appropriate remedy** (for the cloud review runner: re-sync the installed workflow's `TOOLS` line — `prflow_runner.allowed_tools` is appended post-floor only inside `devflow-runner.yml`'s `provision_env` gate, which defaults off, so it bridges the grant only on a reviewer already running `provision_env: true`; `prflow_implement.allowed_tools` / `devflow.allowed_tools` for the implement / command tiers); **(b) helper absent** (`No such file`) → note that the vendored helper was not found; **(c) helper internal error** (exit 2, no verdict rows on stdout) → note the internal error and carry its stderr (the empty stdout is **not** read as a clean pass); **(d) config-disabled** → the recorded config-disabled note. No arm stalls the run and no arm silently skips the phase.

**Phase 0.3.6 — blocker-recheck fast path (standalone `/prflow:review` only).** Evaluated before issue discovery (0.4) and diff classification (0.5). When a PR's most recent recorded verdict is a REJECT driven **solely** by enumerated self-contradicting-diff carve-out blockers (zero checklist FAIL/INCONCLUSIVE, and every REJECT-driving finding — at any severity — carries the producer-emitted ` [self-contradicting-diff carve-out: {file}]` marker), **and** every commit since the rejected head touches only the enumerated blocker sites, the engine re-verifies each named blocker at the PR's pushed head (`$PR_HEAD_SHA`) with a single blinded `general-purpose` verifier, then finalizes its own progress comment per the Phase 4 update protocol (flip Status, write the report, stamp `Reviewed HEAD = $PR_HEAD_SHA`, and record the `checklist not run (blocker-recheck fast path)` sentinel tally) **before** posting a refreshed verdict through the existing Phase 4.4 machinery — an APPROVE reuses `dismiss-stale-rejections.sh` unchanged — instead of a full four-phase re-review. This makes clearing a carve-out REJECT (a stale doc/release-note line, comment, or test the diff itself introduced) proportionate to the one-line fix it demands, rather than mortality-prone (a full re-run that dies mid-flight leaves the REJECT outstanding at merge). Two coupled producer keys in the Review bundle feed it: a machine-detectable `Reviewed HEAD:` line stamped on the finalized review-progress comment at Phase 4 (the deterministic join between the reviews-API REJECT's `commit_id` and its report-carrying comment — the root owns that comment's shape, so its producer rule sits with the rest of the live-comment machinery in `skills/review/SKILL.md`), and the unconditional ` [self-contradicting-diff carve-out: {file}]` marker Phase 4.1 stamps on every carve-out finding (a Phase 4 procedure, so it lives in the Phase 4 reference under `skills/review/phases/`) (its `{file}` field is the only place a blocker's path survives into the rendered report, so it is what precondition 4 enumerates blockers from). Every unmet, unparseable, or errored precondition falls **closed** to the full pipeline; any still-unfixed blocker re-REJECTs; and the gate is **off** for `/prflow:review-and-fix` (which passes `head_override = local`), so the fix loop never takes it mid-loop and the shared engine stays single-sourced. It is a review with a formal verdict, **not** a bypass — it narrows, never closes: the scoped verification confirms each blocker's claim is now true but does not re-review the blocker file for new problems (precondition-5 bounds the blast radius to the enumerated sites).

### Engine ground truth: the injected block (cloud runs only)

A cloud review used to have no ground truth about which commands it may run, nor about the CI that already ran on the commit under review — it discovered them by trial and denial, and a run could burn its whole budget probing the boundary and terminate with **no verdict**, leaving a red required `Devflow Review` check with no findings and no stated cause. Cloud review runs now **prepend a `> [!IMPORTANT]` engine-ground-truth block** to the review prompt, on **every** cloud review path: the automated `devflow-review.yml` path (through `devflow-runner.yml`'s `Compose review prompt` step) and the manual `/prflow:review` comment path (through `devflow.yml`'s `Compose review grounding block` step). The block is rendered by `scripts/render-grounding-block.sh` — the single deterministic renderer of a load-bearing prompt surface, a convention `scripts/render-audit-prompt.py` (the create-issue Step 3.6 audit prompt, issue #600) is the **second** application of, with one disclosed transport divergence: the grounding block is *workflow-injected* into the review prompt, whereas the audit prompt is *fetched by the auditor* running the renderer in its own context (the transport that removes the orchestrator's per-dispatch emission). The grounding block states three ground-truth things:

1. **The CI conclusions already observed for the reviewed HEAD**, produced by `scripts/summarize-ci-checks.sh`: one line per signal, drawn from the paginated `actions/runs?head_sha=` runs and their per-run `/jobs`, plus `commits/{sha}/check-runs`. It excludes PRFlow's own workflow, the duplicate `github-actions` app check-runs (already counted once via the jobs API), and the reviewer's own `Devflow Review` check. It **always exits 0**; on any query failure it prints the literal `CI status unavailable` with a query-specific stderr breadcrumb, and a head with genuinely zero signals prints `No CI signals reported for this commit` — neither ever renders as passing, so an unknown CI state is never laundered into a green one. Check **names** are attacker-controlled free text (anyone opening a PR can name a job), so they are sanitized to printable ASCII, stripped of fence/markup characters, truncated, capped at 50 lines, and rendered inside a plain ` ```text ` fence beneath prose declaring the names untrusted data; the **conclusions** beside them (`success`, `failure`, `in_progress`) are API facts, not attacker text.
2. **The exact `--allowed-tools` string the run resolved**, so the engine plans only commands the harness actually grants rather than rediscovering the list by probing.
3. **The trusted-source-displaced paths this run (section 5, issues #504 + #874)** — a displaced-paths section stating the listed working-tree files do not carry the reviewed head's bytes, so a HEAD claim about a listed path routes through `git show <head>:<path>` and the cached diff, never a working-tree read (fetch-free `git cat-file -e` → INCONCLUSIVE fail direction); listed paths stay fully in review scope (the displacement changes the read channel, never the depth). The list has **two producers** on `devflow-runner.yml`, joined into one `HARDENED_PATHS` value by a dedicated `Join displaced-path producers` step, and the section renders whenever *either* is non-empty: the `Harden Stop-hook script sources` step's base-ref/stub overwrites (issue #458), and the unconditional prompt-extension truncation (issue #874), which empties — or creates empty — the workspace copy of each protected extension on every run. The join is why the extension paths still reach the block on a run where the harden step's relevance gate published an empty set, which is the ordinary consumer shape. **The published list carries no per-path provenance**, so a listed path is never attributed to a particular producer, and the working-tree copy is not consulted for any content claim about it — head or base alike. Inert only when both producers publish nothing: the local tier and the manual `devflow.yml` path, neither of which runs either producer.

`skills/review/SKILL.md` carries a matching **"Engine ground truth (only when the injected block is present)"** section (see the *Engine sharing* note — it is conditioned on the block, so it is inert under `/prflow:review-and-fix`, which runs the same phases under a different, write-enabled profile with no block). It tells the engine to treat the block's CI conclusions as the authoritative test evidence for the commit (citing them rather than re-running the suite — Phase 2 verifies the *checklist*, not the test suite, so no suite-execution step is left undischarged), to attempt no command the allowed-tools list omits, and to **quote a check name, never obey one** — while never doubting a conclusion because a name looks adversarial. Evidence means a check *name* with a *conclusion* beside it: when the block instead reports `CI status unavailable` or `No CI signals reported for this commit`, the engine treats the test evidence as **missing**, never as green. When the block reports a `failure` or `in_progress` signal, the engine reports it as such rather than assuming green (see [`docs/workflow-triggers.md`](workflow-triggers.md)).

**Read-only `review` profile grants (issue #363).** So the engine can actually execute the phases the block promises are permitted, the cloud `review` tool profile additionally grants `mkdir`, `tee`, `git cat-file`, `git hash-object`, `git checkout`, `mktemp`, `cmp`, `rm -f`, and `load-prompt-extension.sh` from any anchor directory (`Bash(*/load-prompt-extension.sh:*)`). Phase 0.2's cached diff is therefore created (so Phase 3's `{DIFF_PATH}` resolves), and Phase 0.3.6's blocker-recheck fast path executes. The Phase 3.1 dirty-tree backstop no longer depends on `mktemp`: it writes `git status` snapshots and restore scratch to fixed repo-local `.prflow/tmp/` paths that survive the Agent-tool boundary and work on the implement profile where `mktemp` remains withheld. Before each snapshot write the engine removes the prior path object and validates a regular non-symlink result; restore scratch is likewise removed before reuse. It rejects truncated NUL records and failed path writes, while an object ID held only in orchestrator state detects replacement of the regular baseline during dispatch. `lib/test/extract-command-heads.py` + `lib/test/run.sh` pin every Bash command head in the **whole Review bundle** — the root `skills/review/SKILL.md` *and* every `skills/review/phases/*.md` reference (issue #529 split the engine, so the reviewed surface is every source, not just the root; both extractors take all of them in one call) — against **both** allowlists the skill runs under, so a command the skill invokes but a profile omits turns the suite RED instead of being silently denied at runtime. The extractor is quote/comment/heredoc-aware, `$(…)`-descending, wrapper-stripping, and **arm-position-aware** (issue #392: `case` arm patterns are stripped only where an arm may legally begin — after `case … in` and after each `;;` — so a command in a case *body* keeps its head; nested `case` blocks are an accepted flag-not-depth-counter limitation).

**Granted heads are not enough — the matcher also denies composite SHAPES (issues #401, #455).** A statement every one of whose heads is granted is still refused when its *shape* is one the matcher rejects, and a refused command fails **silently**: it produces no output at all. `lib/test/extract-command-shapes.py` (driven by `lib/test/run.sh`) is the desk-time pin for that class, and it carries **one rule set per tool profile**, because the read-only `review` allowlist and the read-write `devflow-implement` allowlist are separate profiles with separately-probed behavior — a shape proven on one tier is *unproven* on the other:
- **`--profile review` (default; rules R1–R4)** covers the whole Review bundle (`skills/review/SKILL.md` + `skills/review/phases/*.md`): a leading `VAR=value` assignment, a leading `cd`, a redirect (stdout or stderr) targeting `/tmp`, and an interpreter head (`python3`) are all denied in the review runner (evidence: run 29105381021 — 22 denials, no verdict). The **leading-`cd`** row of that evidence is **confounded by an independently-denied redirect (stdout or stderr) and is therefore unproven** — it is kept for a redirect-free re-probe and pinned absent in `run.sh` (see [`docs/cloud-allowlist.md`](cloud-allowlist.md)); the rule enforces the leading-`cd` **authoring** rule rather than a measured refusal. (A fifth **discipline-only** rule, **R5** — a command-substitution assignment in `if`/`elif` **condition** position, issue #857 — was **retired in issue #869** once `matcher-probe.yml`'s review Shape 18 recorded that shape PERMITTED, run 30310938175.) Permitted alternatives, each with its own evidence status (issue #871): the Write tool into `.prflow/tmp/**` (probe-proven, run 29111394360), `… | tee` and `tee <<'EOF'` (probe rows 10 and 6, no per-row verdict transcribed), and repo-relative vendored-literal helper paths (the **leading-token** form is **probe-proven at the *implement* tier only, row I2, and unrecorded at the review tier**; review shape 18 measured the same path in command-substitution-condition position, which is confounding evidence, not a leading-token measurement). See [`docs/cloud-allowlist.md`](cloud-allowlist.md) for the per-entry record.
- **`--profile implement` (rules IR1/IR2/IR3/IR4/IR5)** covers `skills/implement/SKILL.md` + `skills/implement/phases/*.md` + `skills/implement/references/*.md` (and, to keep the idiom uniform, `skills/create-issue/SKILL.md` + `skills/init/SKILL.md`): the implement matcher denies a `for` loop (IR1), a `while`/`until` loop (IR2), and a command substitution / `VAR="$(…)"` capture (IR3) **wrapping a label helper** (`ensure-label.sh` / `apply-labels.sh`) — measured as probe rows 4/5/6 — plus a leading `cd` (IR4, issue #855; enforced as an authoring lint) and a stdout/stderr redirect (append or truncate) to a `/tmp/…` target (IR5, issue #915), mirroring the review tier's R3 redirect arm so engine scratch stays on the probe-permitted `.prflow/tmp/` target (implement-probe row 11 PERMITTED, row 10 `/tmp` DENIED). IR5 does not inherit R3's `cat`-headed heredoc arm (row 12 records a plain heredoc write PERMITTED on this tier). It also proved the explicit vendored-literal grant *form* PERMITTED (rows 2/3). Row 1 (the unexpanded `${CLAUDE_SKILL_DIR:-…}` anchor as leading token) is **not** lint-pinnable on either tier — every legitimate helper call keeps that portable anchor in source (#275) and resolves it at runtime — so it stays prose discipline. Rows 8/9 now disambiguate non-label and redirect-free label captures; the former is permitted and the latter denied.

Both rule tables are additionally applied *by reachability* rather than by file glob: `lib/test/cloud_writer_contract.py`'s `check_shape_conformance()` guard (see the cloud-writer reachability contract below) runs them over every fenced command in each cloud root's closure, keyed by each profile whose own reach includes the asset.

**Recorded implement-probe table (issues #450, #455, and #571).** `.github/workflows/matcher-probe.yml` is repository-internal measurement infrastructure and `install.sh` does not ship it to consumer repositories. Rows 10–16 extend the existing evidence table with everyday ad-hoc command forms; they change neither the implement recipes nor `lib/test/extract-command-shapes.py`'s lint rules. Multi-operation statements such as `A; B` and `A && B` remain excluded because the shipped phase fences already exercise them, so another probe row would not isolate a new matcher property.

| Row | Command shape | Observed verdict |
|---:|---|---|
| 1 | Unexpanded `${CLAUDE_SKILL_DIR:-…}` anchor leading token | DENIED |
| 2 | Vendored-literal `apply-labels.sh` leading token | PERMITTED |
| 3 | Vendored-literal `ensure-label.sh` leading token | PERMITTED |
| 4 | `for …; do helper; done` | DENIED |
| 5 | Piped `while read` loop | DENIED |
| 6 | `VAR="$(label-helper …)"` capture with `2>&1` | DENIED |
| 7 | Plain granted command (positive control) | PERMITTED |
| 8 | `VAR=$(non-label-helper …)` capture | PERMITTED |
| 9 | Redirect-free `VAR="$(label-helper …)"` capture | DENIED |
| 10 | Granted head with `> /tmp/f` | DENIED |
| 11 | Granted head with `> .prflow/tmp/f` | PERMITTED |
| 12 | Plain heredoc write through a granted head | PERMITTED |
| 13 | Captured `VAR="$(cat <<'EOF' …)"` heredoc | PERMITTED |
| 14 | `echo "$VAR"` simple expansion after a granted head | DENIED |
| 15 | Literal leading `VAR=value` assignment | DENIED |
| 16 | Computed leading `VAR="$(head)"` assignment | DENIED |

The evidence of record is the user-directed API dispatch [run 29623046995](https://github.com/The01Geek/prflow/actions/runs/29623046995), `implement-probe` job `88021801138`, at head `f2162d7683bc7a352fce4efce3f092e864aab8b9`. The job completed successfully; every row recorded `tool_use=yes`, rows 1–6 and 8–16 recorded `shape=ok`, row 7 recorded `shape=n/a`, and no row was REFORMULATED or UNATTEMPTED. The parent workflow was intentionally cancelled after that evidence job completed. An autonomous implement run cannot discharge this human-direction evidence gate by itself.

**No-verdict observability.** Two independent halves signal a no-verdict run so a stalled review is diagnosable rather than a frozen `🚀 Reviewing` comment:
- The **engine** stamps a terminal `❌` on its own progress comment on any path that reaches no verdict — not only a fatal mid-run error but also budget/turn exhaustion or repeated permission denials — flipping `Status` to `❌ Review failed` with a `REVIEW INCOMPLETE — <reason>` verdict line.
- The **workflow** does not rely on that step running. `scripts/surface-execution-diagnostics.sh` emits a `::warning::` when a run recorded permission denials and publishes `permission_denials_count` (a digit string, or the literal `unavailable` when the count could not be established — never collapsed onto `0`); `devflow-runner.yml` exposes it as a job output, and `devflow-review.yml`'s `finalize_check` emits an `::error::` on a no-verdict run naming the reviewed HEAD and rendering one of three clauses via `scripts/describe-denial-count.sh`. That helper is also the reference implementation of the repo's **workflow inline-shell extraction convention** (`CLAUDE.md`, the shell sibling of the inline-jq-parser rule): inline shell in a workflow that selects a branch or composes a user-facing message is extracted into a `scripts/*.sh` helper so `lib/test/run.sh` can drive each branch and its arm-order — a grep-pin on a message literal is not coverage of the selection that chooses it. Beneath that `permission_denials_count` line the check-run summary also renders the review-tier PreToolUse shape guard's visibility — its heartbeat presence, per-arm denial counts, and denied-command detail (job outputs `pretooluse_guard_fired`, `pretooluse_guard_counts`, `permission_denials_commands`) — via `scripts/render-guard-visibility.sh`, which neutralizes the un-redacted, attacker-influenced command text (backtick-strip, `::`-workflow-command neutralization, fencing, truncation) before it reaches the summary; `scripts/resolve-guard-counts-file.sh` owns the run-keyed/bare/glob selection of the guard's counts store so a fire-but-deny-nothing run reports a known zero rather than `unavailable`.

**Permissions.** The CI queries need `checks: read`; it is added to `devflow-runner.yml`, to its caller job in `devflow-review.yml` (a reusable workflow requesting a permission its caller did not grant aborts at graph-build time — a coupled pair), and to `devflow.yml`'s `command` job.

### Phase 1: Verification checklist generation
The `prflow:checklist-generator` agent (model: **opus**) reads full file contents and enumerates **every verifiable claim** the diff makes, across its categories: **dependency interactions, test-mock alignment, data-format assumptions, API contracts, string presence, and absolute claims**. Output is a JSON checklist. Key points:
- It **enumerates, does not judge** correctness.
- Files are batched (≤10 per generator; batches of 10 above that).
- **The diff reaches the generator by file reference, not inline (issue #426).** A single batch passes the Phase 0.2 cached `diff.patch` path directly; a multi-batch run authors each batch's slice with a shell-only `awk … >`-redirect that extracts the batch's `^diff --git` sections from the cached diff into a run-scoped slice file, and passes the generator that slice's *path* — the same `{DIFF_PATH}` file-reference handoff Phase 3 uses, so the slice content never transits the orchestrator's context (the cost the shadow re-paid on every pass). The extraction `>`-redirects to the file rather than piping through `tee`, precisely so the slice is not echoed to the orchestrator's stdout (a `tee` would re-incur that transit as a Bash-tool result on every pass). The slice is gated on the authoring command's **own exit status** plus a guard-class-2 `test -s` non-empty check — an `&&`-chain, not a size proxy alone: `test -s` would wave through a **non-empty but truncated** slice from a partial write (`ENOSPC`, quota, a killed `awk`), and the batch would then review a thinned surface with the missing files silently unrepresented. Any observable slice-authoring failure — a non-zero `awk`/redirect exit, or a missing/empty slice (a shallow checkout, a run-id hiccup) — routes that batch to the full `diff.patch` path (a host with no `awk` at all degrades Phase 0.2's `diff.patch` build first — an upstream failure, not one this batch-level fallback masks). The residual window is named rather than papered over: a write error `awk` itself neither reports nor exits non-zero on would still yield a truncated slice. It reads no `git` objects and takes no **per-file** filename arguments (its only operand is the fixed run-scoped `diff.patch` path), and reuses heads (`awk`/`test`/`echo`) already granted in both cloud allowlists — **no allowlist change**. The same `{DIFF_PATH}`-style file-reference handoff now also covers the **issue body** in `/prflow:implement`'s own Phase 1–2 dispatches (issue #693): Phase 1 §1.1 caches the issue body once per run attempt to `.prflow/tmp/issue-body/issue-<n>.md`, and the §2.1 `code-explorer`, §2.2 `code-architect`, and §4.1 `prflow:docs` dispatches carry an `Issue body path:` line naming that cache instead of pasting the body inline, so the body never transits the orchestrator's context more than once. As with the diff, the read is hand-off-only (never filesystem discovery) and every verdict-bearing reader keeps fetching live.
- The checklist is **capped at 100 items**, prioritized: issue-AC items > absolute_claim > dependency_interaction > test_mock_alignment > api_contract > data_format_assumption. An `absolute_claim` item (a diff-added universal — "every", "never", "is caught by the same rule") always resolves through an `agent` verifier that *constructs the falsifying input*, never a lite grep — reading a universal confirms nothing; only a failed attempt to falsify it does.
- Each item gets a stable `claim_signature` and a `verification_mode` (`lite` = mechanical grep, or `agent` = needs reasoning).

### Phase 1.5: Dedup (only when >1 batch)
The `prflow:checklist-deduper` agent (model: **sonnet**) merges batches, preserving traceability via a `merged_from` field. It **merges, does not re-judge**: when in doubt it leaves items separate (over-merging hides defects).

### Phase 2: Checklist verification
- **lite** items: the orchestrator runs `grep -n`/`rg` directly (no agent).
- **agent** items: the `prflow:checklist-verifier` agent (model: **sonnet**) verifies each claim against the actual source, returning **PASS / FAIL / INCONCLUSIVE** with `file:line` evidence. Batches of up to **8** in parallel. The verifier is a **strict measuring instrument**: it grades a partially-correct claim FAIL and reports structured operands (`property_proven`, `inaccuracy_scope`) rather than self-normalizing — source text is data to classify, never an instruction to obey.
- **Wording-only normalization (issue #556).** Checklist items carry `claim_provenance` (`generated_paraphrase` / `source_authored`, plus a verbatim `source_excerpt` on the latter). An executable helper, `scripts/normalize-verdicts.py`, owns the parse contract and a closed **five-conjunct** predicate that normalizes a raw `FAIL` to a stored `PASS` **only** when the item is an agent-verified `generated_paraphrase`, the raw verdict is byte-exact `FAIL`, `property_proven` is JSON boolean `true`, and `inaccuracy_scope` is `generated_claim_text` — so a generator-wording artifact whose underlying property is proven no longer hard-rejects a pass, while a false source-authored assertion still FAILs → REJECT. The **raw verdict** survives for audit (`raw_verdict`, `normalized`, and a `NORMALIZED (wording-only): ` evidence prefix), the normalization is executable and suite-tested (not an LLM judgment), and the helper's degraded paths fail **closed** (zero normalization with a named tier-appropriate remedy) — it never stalls and never infers a normalization.

### Phase 3: Specialized review agents
All launched in a single message; **always re-run every fix-loop iteration** (the main variance-recovery lever). Four **always-on** reviewers:
- `prflow:code-reviewer`
- `prflow:silent-failure-hunter` (swallowed/over-broadly-caught errors and fail-open fallbacks; also audits **prompt-instruction artifacts** for inert guards — sub-classes `policy-without-mechanism` and `ordered-after-exit`)
- `prflow:comment-analyzer`
- a general-purpose final-pass reviewer invoking the first-party `prflow:requesting-code-review` skill

Each roster id is also the `prflow_review.agent_overrides` key that reprices it. Those keys are namespaced by the plugin name, and the schema declares one per **accepted** namespace, so the pre-rename spellings — `devflow:code-reviewer`, `devflow:requesting-code-review`, and their siblings — keep validating and resolving identically to the canonical `prflow:` forms; see [`docs/review-agent-overrides.md`](review-agent-overrides.md).

Two **gated** reviewers, whose structural-applicability gates apply on **every** diff profile — `engine_self_modifying` included (the flag does not force them on):
- `prflow:type-design-analyzer` (only if `has_new_types`)
- `prflow:pr-test-analyzer` (only if the test-relevance predicate matches)

**Completeness-critic pass (Phase 3.1.5, forced when `detect_all_audit` is set):** when Phase 0.5 flags the diff as adding/changing a "detect-all" audit, the engine runs an extra pass that independently re-enumerates the audit's target population *by a signal other than the audit's own pattern* and emits a finding for any uncovered member (folded into the Phase 3 findings set with a `defect_signature` like any other). It **narrows, but does not close**, the circular-completeness gap — the independent enumeration is itself judgment and can share a blind spot. See `docs/shadow-review.md`.

**Mechanical corroboration:** findings are matched by a `defect_signature` (`file` + overlapping `line_range` + identical `kind`). Corroboration across agents is a stronger calibrator than any single agent's stated confidence.

**Dirty-tree backstop (Phase 3.1/3.2).** Phase 3 review/analysis agents are *advisory* and contractually must **never mutate the working tree** — all prohibit editing working-tree source files, the index, HEAD, or branch state. The five fan-out agents perform any mutation/half-revert verification on a temporary copy made with `mktemp`, never in place; the vendored `requesting-code-review` final pass runs under narrower profiles, uses granted read-only history commands, and reports a mutation-verification limitation instead of attempting `mktemp` or a worktree. Independently of agent compliance, the shared engine snapshots the tree with `git status --porcelain -z` immediately **before** the Phase 3.1 batch and compares **after** it returns. Snapshot and restore scratch use fixed repo-local `.prflow/tmp/` paths rather than `mktemp` captures, both because that head is withheld on the implement profile and because shell variables do not survive the Agent-tool boundary between Phase 3.1 and 3.2. On an agent-introduced **modification** it records an **Important** finding (attributed to the dispatch, never silently discarded) and restores only the *snapshot delta* — paths clean at snapshot time that became dirty during the dispatch window — (a rename/copy-only or status-byte-only divergence is surfaced in a breadcrumb rather than a formal finding) computed **by path column**, so a path the orchestrator had already modified is left to the human rather than clobbered. The `-z` capture is load-bearing: it emits **unquoted, NUL-delimited** paths, so a spaced or special-character filename is a real pathspec the restore (`git checkout HEAD -- <path>`, from HEAD so a *staged* mutation is undone) can act on rather than silently skip. Both snapshots are rc-checked and fail closed (a failed before-snapshot disables the backstop for that dispatch rather than restoring off an empty baseline; a failed after-snapshot is surfaced as a distinct breadcrumb, not misattributed as a mutation). Under `/prflow:review` the agents are contractually read-only and normally leave matching snapshots; the backstop still detects a contract violation and also earns its keep in the write-enabled `/prflow:review-and-fix` and `/prflow:implement` tiers (including the Step 2.6 shadow pass, which re-runs these phases verbatim). **Residuals it does NOT auto-restore:** a **true rename/copy** (status `R`/`C`, which needs index surgery to undo safely — surfaced in a breadcrumb, left for the human) and an agent's further edit to an **already-dirty path that does not change its status byte** (identical `-z` record → the divergence test cannot see it). See [`docs/shadow-review.md`](shadow-review.md).

### Phase 4: Aggregation & verdict
- **4.0** (PR mode) honor the Scope-Acknowledged Findings deferrals via `scripts/match-deferrals.py`.
- **4.1.5 Over-grade advisory annotation** (advisory for shapes 1/3 + non-inert shape 2; a deterministic verdict cap for behavior-inert prose): the **single source of truth** for the over-grade shape definitions (`/prflow:review-and-fix`'s Step 2.6 calibration gate consumes the same shapes rather than forking them). Before the verdict is computed, the engine scans the findings it will weigh and **flags** any that match an observable over-grade shape — a defect the suite catches RED or that fails closed, a diagnostic-or-cosmetic-only finding with no behavioral fail-direction, or an uncorroborated single-source `Critical`/`Important` from an empirical over-grader (`silent-failure-hunter` / `pr-test-analyzer`). A defect that fails **open** (admits a wrong value, corrupts state, or silently skips a guard on the triggering input) **never** matches shape 1 no matter that its limitation is disclosed in a source comment or its trigger input is contrived — "documented" and "contrived" are disclosure facts, not severity facts (a guard exists to catch contrived inputs), so only a suite-RED or fail-*closed* fail-direction supports the flag; this is single-sourced in Phase 4.1.5. Standalone `/prflow:review` has no fixer to record a calibration, so it appends an advisory "suspected over-grade" note to the flagged finding's report line and **leaves the verdict untouched**: it never demotes a finding, never alters its severity, and never clears or downgrades a REJECT. The note only helps a human reading a bare REJECT distinguish a genuine blocker from a diminishing-returns over-grade. The full flag-and-record gate (which *requires* a recorded `severity-calibrated` evaluation before a flagged finding may drive a shadow-promotion, and still never auto-demotes) remains fix-loop-only. **One deterministic exception to "leaves the verdict untouched":** shape 2's *behavior-inert prose* sub-case — a finding whose sole observable impact is the prose itself, on prose that cannot change what the program does — is a *classification* cap: it is set to Suggestion/Minor and Phase 4.2 does **not** REJECT on it, regardless of the agent's grade, and **whether the diff touched the line is not part of the keying**. **Phase 4.1.5 is the authoritative definition of behavior-inertness — its two limbs are not restated here.** It does not reopen the #195 lenient-verdict hole because the judgment decides the *inertness of the surface* from its stated consumers under the two limbs, never the merits or severity of the finding. `/prflow:review-and-fix`'s Step 2.6 honors the same cap by recording the required `severity-calibrated` evaluation deterministically, consuming the single-sourced 4.1.5 definition. Shape 2 also **excludes** a false-against-HEAD diff-added/modified doc line, comment, example, or command-form from the cosmetic-wording class: that is a truthfulness defect (a `documented_falsehood`), filed as a self-contradicting diff, not a demotable Suggestion — and it drives a non-demotable REJECT unless the two limbs hold, in which case the cap governs. The discriminator is single-sourced in 4.1.5 and mirrored by the shared `defect_signature` contract and the `comment-analyzer` / `code-reviewer` agents, so all six Phase-3 producers tag it from the dispatch itself.
- **4.1.6 Pre-verdict truthfulness sweep** — after the over-grade scan and **before** the verdict, this **promote-only** pre-verdict truthfulness sweep runs over **every** Phase-3 finding **regardless of severity chip** (it does *not* inherit the 4.1.5 over-grade *scan*'s Critical/Important/Major scope, because the mis-filed falsehood it closes lands at Suggestion; 4.1.5's cap already runs over every finding regardless of chip). For each finding whose subject is a diff-added/modified doc line, comment, example, or command-form, the engine verifies the flagged claim against HEAD; a **demonstrated** falsehood is routed into the Phase 4.2 self-contradicting-diff carve-out (**REJECT**) independent of the producing agent's framing and chip — unless the prose is behavior-inert, which the 4.1.5 cap governs and the carve-out's scope excludes, so the sweep never re-promotes a capped finding — while an **inconclusive** check leaves the finding exactly as filed (it promotes only on demonstrated falsity, never on suspicion). The sweep never demotes, downgrades, or clears anything, and a clean pass emits a visible `truthfulness sweep: no finding promoted` report line. Beyond the per-finding pass, the sweep also takes a **diff-scan input** (an *intra-diff contradiction scan*): independent of any finding, it cross-products the diff's added absolute claims (a universal — "every", "never", "is caught by the same rule") against its added-or-retained limitation notes about the **same symbol**, and files a contradicting pair as a non-demotable `documented_falsehood` — closing the PR #340 case where a diff published an absolute claim while retaining a limitation that contradicted it, and *no agent flagged it* so there was no finding to iterate over. Both standalone `/prflow:review` and the fix loop inherit it through the shared engine.
- **4.2 Verdict** (first match wins): any FAIL → **REJECT**; any INCONCLUSIVE → REJECT; any finding **at or above `prflow_review.verdict_severity_threshold`** (default `critical`) → REJECT; otherwise APPROVE (with caveats/notes as appropriate). The threshold moves **only** this REJECT line — a repo can set it to `important` (Important/Major also blocks) or leave it at the default `critical` (byte-identical to the historical behavior). Read through `config-get.sh` (PRFlow's config resolver) and enum-validated inline in the skill, falling back to the default with a breadcrumb on a bad/absent value (never aborts). Both standalone `/prflow:review` and the fix loop's Phase-3 pass inherit it. **A threshold-independent self-contradicting-diff carve-out sits above the numbered rules:** a finding that a doc/release-note line, a code comment, or a test **the PR's own diff added or modified** is untrue drives REJECT at **every** threshold value (including `critical`) and regardless of the finding's severity chip — it is a correctness principle, not a severity grade. It is non-demotable (Phase 4.0's deferral match cannot rescue it) and corroboration-independent, and it shares its definition of "contradicts the diff" with the `receiving-code-review` documented-falsehood carve-out. **Its scope excludes prose the Phase 4.1.5 behavior-inert prose cap covers** (4.1.5 is the authoritative definition of that keying), so how blocking an untrue prose line is depends on whether that prose can change behavior, never on whether the diff happened to touch it — prose that *can* change behavior keeps this path unchanged. When the threshold admits Important, rule 3 also gains an in-scope qualifier (an admitted finding does not REJECT if it is genuinely pre-existing behavior the diff does not touch), which the carve-out overrides. At the default `critical`, the only behavior change is that a self-contradicting-diff finding now drives REJECT instead of being demotable to a note.
- **4.4** (PR mode only, `/prflow:review`) records a formal GitHub review: **REJECT → `--request-changes`** (blocks merge), clean → `--approve`. GitHub forbids requesting-changes-on / approving **your own** PR, so the review agent must run under an identity distinct from the PR author. The cloud tier provides this with a **dedicated `DevFlow-Reviewer` GitHub App** (repository variable `DEVFLOW_REVIEWER_APP_ID` + secret `DEVFLOW_REVIEWER_PRIVATE_KEY`): every review path — the automated runner (`devflow-runner.yml`) and the manual `/prflow:review` command (`devflow.yml`) — runs under the `DevFlow-Reviewer` token when that variable is set, else `github-actions[bot]` (`GITHUB_TOKEN`), and **never** the primary `prflow-implementer` App token that authors PRs. Since implement authors PRs as the primary app (or `github-actions[bot]` when no app is configured), the review identity is structurally distinct from the author on every configured setup, so 4.4's formal review posts instead of failing self-review. See [`docs/cloud-setup.md`](cloud-setup.md) for setup and the single-app upgrade note.

### Per-subagent model & effort overrides
The `prflow_review.agent_overrides` config maps any of the **nine** review subagents (or a `default`) to a `{model, effort, iterations}`. The engine dispatches its subagents from an already-running session via the **Agent tool**, which carries a per-dispatch **`model`** override parameter but **no effort parameter**, and there is no per-dispatch `--agents` injection in an already-running session. That surface is **not closed at `model`**: the Agent tool also carries a per-dispatch **background/foreground** property, and it — not `model` — is the parameter that decides whether a dispatch returns a result at all. Upstream, subagents are **background by default** and a background dispatch's results arrive as a completion notification **in a later turn**, which a headless cloud run never reaches; the cloud engine steps therefore set `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS: "1"` to keep them in the foreground, and each engine root states the same requirement behaviorally for runtimes with no equivalent switch (issue #801). Forcing foreground also restores the full built-in tool set a background subagent would otherwise lose, so roster behavior can change independently of the stall. So a resolved per-agent **model** override IS delivered (as the Agent tool's `model` parameter), while a resolved per-agent **effort** override is **not** applied per-agent on this in-session path — the subagent inherits the session effort, and `scripts/resolve-review-overrides.py` reports this honestly as a `session-fallback` (a `::notice::` per resolve for the benign no-seam case, or a `::warning::` naming the model/provider for a capability-restricted one), never as an applied success (issue #554). The per-tier effort application-point matrix (`agent-definition` / `process-start-session` / `session-fallback` / `session-inheritance`) is documented in [review-agent-overrides.md](review-agent-overrides.md); a per-agent applied arm and its telemetry carrier are a spike-gated deferred follow-up. Effort enum: `low/medium/high/xhigh/max`. The optional `iterations` key (default-off; only value `first-only`) is a roster-scoping lever, not a dispatch parameter: an agent carrying it is excluded from the Phase-3 review roster on `/prflow:review-and-fix` fix-loop iterations ≥ 2 (a no-op in standalone `/prflow:review` and never applied to the Step 2.6 shadow) — see [review-agent-overrides.md](review-agent-overrides.md).

### The fix loop (`/prflow:review-and-fix`)
- **Thin root + reloadable step references (issue #530).** `skills/review-and-fix/SKILL.md` is a thin root (kept lean by authoring discipline) that retains the invocation contract, the run-scoped `### Schema`, `### Lifecycle`, the Main-Loop control pointer, a **Step-routing** table, a fail-closed **Reference-loading contract**, and the terminal verdict→chat mapping. The step procedures live in reloadable references under `skills/review-and-fix/references/` (`loop-control.md`, `pre-fix-gates.md`, `shadow-review.md`, `fixing.md`, `fix-delta-gate.md`, `convergence.md`, `loop-exit.md`, `error-handling.md`), each loaded at step entry behind a single ordered `# Reference:` / `<!-- END … -->` boundary; an unreadable **loop-step** reference takes a mapped fail-closed outcome (engine-gate/fixing → stop before mutation; shadow → `coverage: not_verified`; convergence → non-convergence; Loop Exit → persistence backstop + incomplete terminal state — none of those permits a clean approve; `error-handling.md` alone is best-effort contextual guidance, not a loop step — its absence degrades only guidance, per the root's failure map). The **durable state** that lets a compacted or resumed run recover its position — `current_step`, `current_substep`, `pending_dispatch` — is written into the run-scoped `iter-<N>.json`, and an always-resident root rule re-reads the active reference after every subagent/skill return rather than trusting recall (the record, not agent memory, is the step predicate). This mirrors the `skills/implement/` thin-orchestrator + `phases/*.md` split. The reliability of the split's routing + fail-closed wording was measured empirically (5 fresh-context samples + a budget-RED and a no-guidance control) in [`docs/review-and-fix-split-wording-study.md`](review-and-fix-split-wording-study.md).
- **Configurable iteration cap (default 5, `prflow_review_and_fix.max_iterations`).** Each iteration runs the full engine, then fixes findings one at a time (using `prflow:receiving-code-review` principles), runs tests, commits (`fix:`), and continues.
- **Configurable fix-severity threshold (`prflow_review_and_fix.fix_severity_threshold`, default `important`).** The loop routes to the fixer every finding **at or above** the threshold (`critical` > `important` > `suggestion`) and parks the rest as advisory; at the default it fixes Critical + Important/Major and parks Suggestion/Minor (the historical behavior). Set `suggestion` for a more aggressive fixer or `critical` for a conservative one. Its **effective fix set additionally includes every finding that drove the engine's REJECT** — whether at/above `verdict_severity_threshold` or via a threshold-independent REJECT class (e.g. the self-contradicting-diff carve-out), even below the fix threshold — so no configuration combination produces a REJECT the fixer is configured to ignore. Read through `config-get.sh` and enum-validated inline (same never-aborting fallback as the verdict threshold). A separate `receiving_review.fix_severity_threshold` (default `critical`) governs the re-open bar only when `/prflow:receiving-code-review` is invoked **directly**; the loop never consults it.
- **Pre-fix verification gate (Step 2.5):** single-source claims about external tools are **web-verified** (cap **5 WebFetches/iteration**), Confirmed → fix; Refuted → demote to advisory. This prevents the loop from "fixing" a hallucinated problem.
- **Pre-shadow parked-class sweep:** at both non-REJECT convergence entries, parked findings seed a bounded changed-surface enumeration before the shadow runs. The sweep registers every sibling in the triggering iteration's findings, promotes at-or-above-threshold siblings through the normal counted fix machinery, parks lower-severity siblings with a distinct marker, deduplicates by site overlap, and fails closed through a required Reflection sentinel when semantic enumeration cannot be verified.
- **Stale counted-prose post-commit pre-check (Step 3):** immediately after each fix commit, the loop runs the *same* `stale-prose-lint.py` the shared review engine runs in Phase 0.6 — here recomputing the full branch diff at the just-committed post-fix `HEAD` against the exact operand Phase 0.2 selected (`origin/$PR_BASE_BRANCH` normally or the retained `baseRefOid` after confirmed deletion in PR mode; `origin/$BASE`, the configured `base_branch` fail-closed to `main`, in current-branch mode), **not** the pre-fix diff Phase 0.2 cached. A stale claim a fix introduced under an earlier-added header is therefore caught (the earlier header is still an added line in the full-branch diff), and the invocation outcome (TSV rows, a `git diff` producer-failure note, or the helper's degradation arm) is stored in that iteration's `iter-<N>.json` under `stale_prose_check`. This item-6a pre-check is fail-closed via `set -o pipefail` + Phase 0.6 exit-code routing (it pipes straight to the lint helper — no cache to publish); the candidate/promotion/publication pipeline lives in Phase 0.2's cache producer, which checks the raw diff, filtered candidate, promotion write, and stdout publication, and on any failure or unreachable merge-base after the one-shot `--unshallow` retry removes every candidate and prior cache, becomes Blocked when observed by the wrapping run (or stop-and-report standalone), and never yields a silent `APPROVE`-eligible empty diff. A retargeted/stacked PR emits a warning naming its PR base and the different configured `base_branch`, making the residual leak observable. A fix-introduced stale counted claim is thus reconciled **within the same iteration** rather than at a later full-engine pass; it adds no new verdict or iteration-accounting rule (a surviving false-positive routes through the existing `fix_decisions` pushback shape; an unresolved STALE at the cap follows the existing unresolved-shadow-findings path).
- **Mechanism-scoped self-authored-claim re-sweep (Step 3, item 3a):** after a fix changes a *mechanism* (a guard, predicate, exclusion, or helper that comments describe), the loop re-dispatches the existing `prflow:comment-analyzer` (no new agent) over every comment describing that mechanism — located by the mechanism's identifiers across the touched files, not limited to the fix's own diff hunks — and treats a comment that still describes the pre-change mechanism as a finding. It covers the changed mechanism within touched files; it is **not** a repo-wide comment audit. See `docs/shadow-review.md`.
- **Fix-delta authoring-side sweeps re-anchored on the full §2.3 index (Step 3's item 3b):** on every iteration in which Step 3 applied fixes, the loop classifies the fix delta by implement Phase 2.3's "Sweep selection (run first)" preamble, resolved from the executing skill bundle rather than the consumer repository and selects **every** warranted Phase 2.3 authoring-side sweep — the trigger-gated sweeps the delta matches plus every always-on sweep the preamble names — with no hand-enumerated subset, so adding a sweep to that index needs no selection edit here (a new implement-only routing class still requires mapping/lint vocabulary maintenance). Readable definitions run against the fix delta. A durable `sweep_defs_read` read protocol bounds the context bill (full definitions read once per run, headings re-read each iteration, adjudicated against the record not recall; an unreadable or truncated §2.3 source records `sweeps: unrunnable …` and names Step 3.5 + the shadow as backstop rather than stalling). A drift-guarded **fix-loop mapping table** resolves the imported sweeps' implement-only routings (workpad notes, `(post-merge)` retags, Phase 4.1 deferrals, desk-lint claims, the `CLAUDE.md` rulebook) to standalone-loop destinations, and a `lib/test/run.sh` routing-marker lint turns PRFlow's desk RED when a **closed-vocabulary** routing marker present in a §2.3 sweep body loses (or lacks) its mapping-table row (a genuinely *new* routing marker outside that closed vocabulary is not caught — extending the vocabulary is a future change). Step 3 also runs the §2.3 **test-first gate** at fix-authoring time, with a tier-mapped ungranted-command degraded arm and the same Phase 2.4 taxonomy for un-drivable deliverables: adversarial dry-traces for logic-bearing or human-facing prose, and RED/GREEN/no-guidance subagent micro-tests for instructions that enter model context. Step 4.5's convergence conditions grade code-shaped sweep-driven fold-ins as any other fix. A sweep's **trigger** is scoped to the fix delta without exception; a **triggered** sweep's **enumeration** may exceed the delta only where that sweep's own Phase 2.3 definition states a repo-wide search domain (§2.3.0, §2.3.0a, §2.3.0b, §2.3.0d), every other sweep's enumeration staying delta-bounded. The authoritative statement of item 3b lives in `skills/review-and-fix/references/fixing.md` (Step 3, item 3b); the sweep definitions it imports live in `skills/implement/phases/phase-2-implement.md` §2.3.
- **Pushback tracking:** when a finding is skipped, it's tagged with a `skip_category` (e.g. `claim-quality`, `out-of-scope`, `already-tracked`, or `settled-by-disclosure` — a finding foreclosed by an already-shipped disclosure, §13). The same finding skipped twice → escalate and stop — **except** a `settled-by-disclosure` foreclosure, which is answered, not unresolved, so its repeat skip does not trip the escalation.
- **Fix-delta verification gate (Step 3.5):** after **every** iteration's fix commit, a **blinded subagent** re-reviews **only that iteration's cumulative fix delta** (prior findings/fix decisions/fixer reasoning withheld) to catch a fix-introduced regression — most often a #62/#98 guard whose accepted-input set is wider than its consumer's contract — in the **same** iteration. "Every iteration" means the gate is not gated on the *verdict*; it does **not** manufacture a delta where none exists — an iteration in which **Step 3 applied no fixes** has no delta, so the gate (and every check it carries) **skips** for that iteration. Its three checks are the #62/#98 operand-contract check, the adversarial input-shape matrix, and the **added-assertion attribution check**: for each assertion the fix delta adds, the blinded subagent identifies the regression that assertion's own name and description claim it catches and asks whether the assertion *as reported* singles that regression out — reporting an assertion that would not change state under the named regression, one that would change state under a different cause, or one whose reported identity is indistinguishable from a sibling arm; an assertion whose target cannot be read is reported **unestablished**, never clean. A surviving Critical/Important finding from the first two checks (after over-grade calibration) routes back into that iteration's fix step (capped at 2 inner attempts, then promoted); an added-assertion finding is not severity-routed but corrected in the same iteration (or recorded through the item 5 pushback flow), inheriting that same cap, promotion, and at-cap shadow carry. The gate and its inner attempts do **not** count toward the cap. Complements the shadow (which audits the whole diff at convergence, and on an `engine_self_modifying` PR also once after iteration 1 via the early trigger); the shadow + post-shadow gate are unchanged by it.
- **Convergence check:** exits early when fixes are small and no new corroborated Critical/Important finding appears.
- **Loop Exit:** runs a **widens-surface guard** and emits a run-scoped **deferrals manifest**; renders a `## Coverage` section and the run/effectiveness telemetry.

### Keeping prompt prose lean

PRFlow treats mandatory agent instructions as a runtime cost, and the policy that governs
them is a matter of authoring discipline: once an executable helper is the sole tested owner
of a workflow decision on every consuming path, the same change removes the superseded
mandatory prose, branch/enum mirrors, and obsolete prose pins. Policy, human decisions,
invocation and fail-closed contracts, and essential stop conditions stay in the skill;
rare-path explanation may move into a gated reference, but operative logic does not disappear
before tested helper ownership exists. This sole-owner discipline is stated as advisory
guidance in `CLAUDE.md`'s **Helper cutover** convention, with the lean-prose guidance in
`.prflow/prompt-extensions/implement.md` under **Keeping prompt prose lean**.

### Direct invocation of `prflow:receiving-code-review`: the Reception Preflight (issue #545)

The fix loop above applies the `prflow:receiving-code-review` principles inside its own machinery — the loop's mechanics establish PR context themselves. A **direct** invocation of the skill (an interactive maintainer session, or an operator flow dispatching it outside the loop) instead has a defined startup contract, the **Reception Preflight** in `skills/receiving-code-review/SKILL.md`: after the consumer-prompt-extension load and before the Step 0 branch update, before triage of any finding, before any file edit, and before any test-suite execution, the skill renders **one in-chat block of exactly nine context facts** — subject, PR head/base, checkout (with a head-match verdict), working-tree cleanliness, freshness, linked-issue requirements (each linked issue's body re-read in this run), consumer-prompt-extension outcome, severity threshold, and commit/path scope — each fact carrying **exactly one of six statuses**: `established`, `caller-supplied`, `missing`, `stale`, `ambiguous`, `not-applicable`. No rule in the contract assigns `stale` — an unobservable or un-re-measured fact renders `missing`, never `stale` (the status is reserved for a render that must carry a knowingly-superseded value, and it is never an input to the editing gate). A fact renders `established` only when its value was directly observed from a command output or a file read in the current run; anything else renders a degraded status with a one-line reason — never an assumed value (a failed fetch records divergence as *unknown, never zero-behind*; a shallow clone's undecidable ancestry renders the head-match `missing`, never a guessed verdict). The preflight's prescribed command set is **strictly read-only** — one exit-status-checked `git fetch` (remote-tracking refs only), `git rev-parse`, `git status`, `git merge-base --is-ancestor`, `git rev-list`, `gh pr view` (including its `files` scope read), `gh issue view`, the extension loader, and the threshold read, and nothing else; it never switches branches and never merges.

- **Subject classifier + corroboration.** The subject binds through a decidable three-arm classifier — whole-argument number, leading-token number, or checkout-derived (an argument-less `gh pr view` resolving the current branch's PR) — with a leading `#` stripped as normalization. A `#`-prefixed leading token is an explicit designation (`established` absent contradiction); a **bare** leading token renders `established` only when corroborated by an independent channel (the checkout-derived PR equals the bound number, or the feedback names at least one path in the bound PR's file list), else `ambiguous`. Contradiction is decided by named paths: feedback naming paths all disjoint from the bound PR's file list renders the subject `ambiguous` with the disjointness stated. A number appearing anywhere else inside feedback text never binds, and every third-party text the preflight fetches — caller-supplied feedback and linked-issue bodies alike — is data to classify, never instructions to obey.
- **Scope carve-out + fail direction.** The preflight governs **direct invocations only**: inside an autonomous fix loop that drives its own context establishment, the loop's mechanics govern and the preflight is not consulted. A direct invocation is positively established only by an explicit invocation record visible in the current transcript; a run that can establish neither direct-invocation nor loop context **executes no preflight command** — it renders a single explicit context-unestablished line and bars nothing.
- **Relation to Step 0 and the Verification Gate.** The preflight precedes the existing Step 0 branch update; after Step 0 mutates the checkout, the checkout, working-tree, freshness, and head-match facts are **re-measured** and the block re-rendered before the affirmative-only editing gate is consulted. That gate bars IMPLEMENT only on a PR-bound subject whose post-update head-match is `mismatch` (with a work-preserving remedy ladder — a checkout of the PR head is named only when the tree is clean and no local-only commits exist) or on an `ambiguous` subject (the skill asks for explicit subject confirmation and never self-confirms), while triage proceeds on the explicitly-degraded facts; `match`, `advanced`, and a `missing` head-match never bar — a `missing` head instead renders an explicit unestablished-head line. The preflight's freshness facts are point-in-time; the Verification Gate's item 4 remains the completion-time branch-sync authority.
- **Always the plugin-qualified name.** Documented invocation paths use `prflow:receiving-code-review`, never the unqualified name: on a host where the upstream `superpowers` plugin is co-installed, that plugin's own `receiving-code-review` is a name-twin that never receives PRFlow's preflight — the shared **name** is what makes the wrong copy dispatchable, whatever the two descriptions say — so a session that responded without rendering the preflight block dispatched the wrong copy.

---

## 9. Deep dive: shadow review

> **This is one of PRFlow's most distinctive ideas, a great "wow" moment for a video.** Before `/prflow:review-and-fix` declares a clean approval, it **audits its own approval** with a structurally-independent re-review.

**The problem.** A fix loop's iterations *share state* (prior findings, fix decisions, pushback). That shared context biases the loop toward accepting its own earlier conclusions. So a clean approval from the loop is suspect, it might just be agreeing with itself.

**The shadow pass (Step 2.6).** When the tentative verdict is **non-REJECT**, the engine runs **again** with the loop's accumulated state *withheld*. Topic-priming is a second, distinct leak channel beyond prior-findings leakage, so every shadow-pass subagent receives the engine's verbatim prompt, extension text classified for provenance, and the shadow engine's own full-diff artifacts — no orchestrator-added focus, priority, or scope. Provenance-failing extension text remains loaded for its quality value but is recorded as an addendum and cannot produce an attested clean result. The two results are compared. (A REJECT normally skips the shadow entirely.) On an `engine_self_modifying` PR — the highest-risk diffs in the repo — the shadow *also* fires on an **early trigger**: once after iteration 1, **regardless of that iteration's verdict (including REJECT)**, feeding any new blinded findings into iteration 2 via the same promotion machinery. Non-`engine_self_modifying` PRs keep the convergence-time trigger only. The early pass reuses the same blinded fan-out and is itself uncounted toward the iteration cap (a promoted iteration 2 it spawns counts, like any promotion); if iteration 1's `engine_self_modifying` flag cannot be read it **fails closed** and runs the early audit anyway. See `docs/shadow-review.md`.

**The hard structural constraint (a genuinely interesting engineering story).** A subagent **cannot dispatch its own subagents**: nested agent dispatch is unsupported by the harness. So a single "go run the whole engine" shadow subagent would silently collapse to a degraded single-agent self-check returning a plausible clean APPROVE, *the exact false-convergence the step is meant to prevent.* **The fix:** the *parent* orchestrator runs the shadow fan-out itself, re-running the engine's phases inline and launching every reviewer normally; independence is enforced per-reviewer-prompt instead.

**Honest degradation, coverage is a positive assertion.** A degraded pass must **never** clear a PR. The shadow's `coverage: "full"` is *proven*, not assumed on no-error: the parent computes the expected reviewer roster from the shadow's own diff classification and confirms every dispatched reviewer returned cleanly. Any shortfall → `coverage: "not_verified"` and the verdict is reported **unverified**. A single transient reviewer failure gets exactly **one** targeted re-dispatch; structural or multi-reviewer failures fail closed immediately.

**How the coverage guarantee is enforced.** Concrete guards make the shadow's clean signal *trustworthy* rather than assumed: a **dispatched-vs-collected 1:1 join**; a **block-presence read-back gate**; a **prompt-composition attestation** requiring persisted `prompt_addenda: "none"` beside pure roster `coverage: "full"` before outcome 1 or a clean render; a **render-time lock-step assertion** that keeps the `APPROVE WITH UNRESOLVED SHADOW FINDINGS` (AWUSF) headline, Coverage line, and post-shadow edit gate in lock-step (ordinary promotions read one iteration back; a parked-class sweep finding discovered at the cap reads the current triggering iteration); and a **too-narrow-classification tripwire** that widens the expected and dispatched roster. Attestation never discards outcome-2 findings or changes roster coverage: addenda on a promotion are reported as a caveat while the findings still promote. On the consumer side, `/prflow:implement` treats only `APPROVE`, `APPROVE WITH CAVEAT`, and `APPROVE WITH ADVISORY NOTES` as the clean approve-family, and routes AWUSF through one bounded fix+re-review that clears **only** on a verdict that is both clean *and* full-coverage. A non-clean bounded re-review no longer hard-blocks: Phase 3.3 applies a **severity-aware exit** — only a genuine unresolved Critical (or an unparseable/ungradeable verdict) takes the Blocked path, while a residual of advisory/Suggestion/`severity-calibrated` findings **soft-proceeds** (surfaced in the workpad and PR body, PR left review-ready, human merger decides). See `docs/shadow-review.md`.

**Honest calibration (important, don't overclaim).** A clean shadow **narrows** the gap between the loop's self-assessment and an independent review; it does **not close** it. It's one sample of the *same* engine and reviewer roster. The documented evidence: on PR #58, the in-loop shadow agreed with full coverage, yet a subsequent *standalone* `/prflow:review` still surfaced several hardening items. **A separate `/prflow:review` remains the default exhaustiveness check; a clean shadow raises confidence but never waives it.**

**Cost.** The shadow roughly **doubles** a converging run's cost (a full extra engine pass that yields no fixes when it agrees). Two 2026-07-11 R3-driven changes make that cost *measurable* and shave one component of it (the R3 baseline to re-measure against: **12.43M recorded shadow tokens; 115 shadow-attributable applied fixes across 32 of 69 runs; ~366k tokens per shadow-attributable Critical/Important fix**): (1) writing the shadow workpad block (with its `step_2_6` telemetry) is now a **single non-optional obligation fused to the pass's termination, covering both termination paths** — Parse-and-compare completion and the honest-degradation fail-safe (an outcome-3 pass writes its `not_verified` block before taking outcome 3), authored with the Write tool with the same force as the `iter-<N>.json` Layer-1 fused emit; and `lib/efficiency-trace.sh --persist` gains a **shadow floor** that synthesizes a minimal `shadow_synthesized: true` + promotion-linkage marker when promotion evidence survives with no `shadow` block (recovering **promoted** shadows only — attribution, not cost — never overwriting an agent-written block); (2) Phase 1's checklist-generator diff handoff moved **inline → by file reference** (see Phase 1 above), removing the redundant per-pass context transit the shadow re-paid on every iteration. Both narrow the cost/observability gap; neither closes it.

Issue #501 narrows that floor with `promotion_provenance`: `shadow` and
`park-calibration-post-shadow` license recovery with true and false linkage,
`park-calibration-pre-shadow` suppresses the pre-shadow false positive, unknown strings breadcrumb
without synthesis, and unestablished legacy values get a hedged marker. Park-gate promotion credit
never changes a surviving predecessor block; future producers must choose a defined provenance value
to opt into recovery.

**Evidence-aware post-shadow grading of parked findings (issue #557).** The Park-calibration gate no longer re-litigates a below-verdict-threshold shadow re-raise of a parked finding on **severity alone** — which burned promoted iterations (each a full re-shadow) re-parking findings the shadow merely *corroborated*. After the shadow block is recorded, the gate grades each re-raise↔parked-finding pair on **evidence**: the scoped sweep-sibling carve-out is evaluated **first** (a re-raise it claims never enters the classification); then each shadow finding pairing under Phase 3.2 to the **parking-time record** of a member of the **reconciled parked population** (the gate's three parked populations across all iterations, minus any member a later iteration applied or promoted-and-fixed) receives exactly one of five relations — *equivalent / strengthened / contradicted / materially different / ambiguous*. Parking is **preserved** only on positive evidence equivalence from well-formed operands (every paired re-raise equivalent, at or below the parked severity under a `major`≡`important`/`minor`≡`suggestion` label normalization, and — for a rationale-bearing row at or above `$FIX_THRESHOLD` — an anchored rationale); every other outcome, and every missing/malformed/unreadable operand, **fails closed to promotion** at the shadow re-raise's severity. Operands are read from additive structured workpad records — a `parking_evidence {basis, failing_input, source, finding_ref}` object on the rationale-bearing `fix_decisions` rows, one `park_calibration.evidence_comparisons[]` record per pair, and a new `tools_unavailable` value in the `step25_classification` enum — never from conversational memory. A single amendment to Step 2.6's novelty definition makes a paired re-raise count as **overlap, not new** (the survived-unfixed reconciliation keeps it from ever claiming a fixed member's re-raise as a preserved parking). Corroboration stays retrospective-clean via a note-kind preservation sentinel; a fail-closed degradation surfaces as friction. The shared `/prflow:review` engine is untouched. See `docs/shadow-review.md`.

---

## 10. Deep dive: the docs suite

PRFlow treats documentation as part of "done." `/prflow:docs` orchestrates three steps in one session, sharing context forward:

1. **`docs-sync-internal`**: ensures every code change on the branch has a corresponding internal-doc update (goal: 100% alignment). Proportional: major changes → comprehensive, trivial → none. Mandatory final step: **verify every factual claim against the codebase** (the single most common cause of inaccurate docs).
2. **`docs-sync-external`**: aligns customer-facing docs against the internal docs (the source of truth), removing confidential/internal-only content. Follows a detailed style guide (AP style, term conventions, etc.).
3. **`docs-release-notes`**: if the change is customer-visible, appends a brief entry (`- **[Category] Short Title**: description. (#PR)`); otherwise skips the release note. Either way, if a `chore: bump version` commit is present, it reconciles that version's CHANGELOG entry — taking the version from `.claude-plugin/plugin.json` (not the bump commit's subject) and no-opping if no matching `## [version]` section exists (Step 4b).

### Versioning (changesets)

PRFlow versions itself with **changesets** rather than an in-PR version bump. Each PR that reaches consumers adds a uniquely-named `.changeset/*.md` file (a `bump: patch|minor|major` frontmatter key plus Keep-a-Changelog prose) and never edits `.claude-plugin/plugin.json` or `CHANGELOG.md`. On merge to `main`, the `version-consolidate` GitHub Action (at `.github/workflows/version-consolidate.yml`; runs `scripts/consolidate-changesets.py`) consumes every pending changeset: it bumps `plugin.json`'s `version` by the **highest** pending bump type (patch < minor < major — one increment even when several are pending), keeps the supplementary version metadata in lockstep with that same value — `CITATION.cff`'s top-level `version` and the `marketplace.json` plugin entry's `version` (each rewritten only when present; absent → skipped, present-but-unrewritable → fails before any write) — prepends a single dated, PR-cited CHANGELOG entry assembled from all the pending prose, deletes the consumed files, and commits with a `chore: bump version` subject. A malformed changeset fails the Action loudly (naming the file); with none pending it is a clean no-op. Because each changeset has a unique filename, concurrent PRs never touch a shared line — the recurring version/CHANGELOG merge conflicts are eliminated while consumers still receive each change as a per-merge version increment. Contributors: see [`.changeset/README.md`](../.changeset/README.md); the operative policy for `/prflow:implement` lives in `.prflow/prompt-extensions/implement.md`.

Supporting skills:
- **`docs-verify <topic>`**: verifies internal docs for one topic against code (codebase = source of truth). Has a `--report-only` mode (no writes) used by `/prflow:create-issue` Step 1, its only programmatic caller. **The two modes carry separate identities.** Write mode is the documentation-accuracy pass described above, and its procedure — action paths, file operations, quality standards, scope constraints, completion criteria — lives in `references/write-mode.md`, loaded only on that path and **fail-closed** (a reference that cannot be read or whose boundary markers do not match stops the run rather than editing docs without its constraints). Report-only is a **docs-first code explorer**: its deliverable is a map of how the topic works in the code today, `[[INTERNAL_DOC_LOCATION]]` is its entry point and a source of **provisional evidence** rather than its subject, and documentation drift is something it observes in passing and reports briefly. A doc-derived claim is confirmed against the implementing code (a finding), contradicted by it (drift), or returned marked `doc-sourced, unconfirmed` — never silently promoted. It ships a **brownfield disposition** (assume non-obvious coupling; surface-level confirmation is an unfinished read) with the breadth/depth split stated explicitly: the duty floor bounds how *many* things are examined, never how *carefully*. In that mode the breadth bound is the **duty floor** rather than a whole-codebase search, the pass accepts an explicit **search-space operand** (which is how Step 1's deep arm gives each peer its own leg), it returns a status for **every** duty on the floor — discharged, unestablished, or judged-not-engaged, the last carrying a bearing observation — and it dispatches **no subagent of its own**, because nested dispatch is unsupported on some harnesses and on PRFlow's cloud tier. `discharged` requires being able to state the duty's answer *and* cite the tool output it was read from; a qualification that names something relied on but not read makes the status `unestablished` instead, while one that merely bounds a verified method's reach does not. Verdicts: `DOCS ACCURATE` / `DRIFT FOUND` / `DOCS MISSING`, ranging over documents **inside `[[INTERNAL_DOC_LOCATION]]` only** — a discrepancy outside that location is reported but never moves the verdict, so two runs over the same tree return the same token.
- **`docs-bootstrap-internal`**: stands up an internal-docs tree from scratch, organized **domain-first** (`orders/`, `customers/`) not code-layer-first, flat (one level), quality over quantity (5–10 thorough seed docs, not 50 stubs).
- **`docs-bootstrap-external`**: generates the initial external docs from the internal source of truth.

Doc paths are configurable (`docs.internal`, `docs.external`, `docs.release_notes_file`, `docs.changelog_file`); internal/external steps can be toggled off (`docs.internal_enabled`, `docs.external_enabled`).

**Consistent discipline across all docs skills:** branch diffs use `git diff origin/main...HEAD` (three dots, branch-only changes); bare source paths only (no line numbers, which rot); the generation skills leave committing to the caller.

---

## 11. Deep dive: `/prflow:create-issue`

Turns a rough user story / bug report / feature idea into a well-structured GitHub issue.

> **Core principle (a quotable line):** *"An issue is the output of resolved decisions, not a place to park unresolved ones."*

**A thin root plus marker-gated references (issue #614).** `skills/create-issue/SKILL.md` is a thin always-loaded root — the portable-anchor preamble, the extension load, the core principle, the completion checklist, Step 1, Step 3's drafting rules and no-options gate, a **routing table**, and four **non-degradable invariants** — down from a large single-file monolith. The per-step procedures and the conditional fallback arms live in `skills/create-issue/references/`, each loaded at its trigger behind an entry gate that checks the file's first-line/last-line boundary markers. The step procedures (`step-2-clarify.md`, `step-3-5-steelman.md`, `step-3-6-audit.md`, `step-4-present-create.md`) load at their step entry; `revision-delta.md` is a shared procedure loaded at every revision event; and the predicate-gated fallbacks (`fallback-no-task-tool.md`, `fallback-read-only-sandbox.md`, `fallback-audit-dispatch-arms.md`, `fallback-state-owner-unavailable.md`) a default-path run — task tool usable, writable filesystem, file-arm dispatch, state owner available — never loads at all. Divergences from the review engine's split are deliberate: there is **no identity-manifest or hash layer** on the entry gate, and a failed load **degrades best-effort** (an in-chat breadcrumb naming the file and the failure kind, then the routing row's named degraded behavior) rather than stopping — extending this skill's documented never-block-issue-creation ethos, so no routing row's failure arm can terminate the run. The four non-degradable invariants hold on every degraded arm. Keeping the root and the default path lean stays an authoring goal, not a mechanically enforced ceiling.

The skill exists to prevent "option-listing" issues. Steps:
1. **Assess (read-only) — right-sized into two arms (issue #749):** Step 1 grounds the issue in current behavior by dispatching `/prflow:docs-verify --report-only` as a **peer subagent**, so the survey's tool output stays in the peer's context and the orchestrator pays only the returned report. Its breadth is bounded by a stated **duty floor** — exact operand and population identity, code-versus-doc authority, reachability and writer classification, sibling consumer and output enumeration, coupled-doc and guard propagation, and reusable contradictions — rather than by a whole-repository search, so a topic engaging few duties pays for few. Before dispatching anything, the orchestrator judges which duty-floor duties the topic engages and selects the arm from that pre-pass judgement: a topic engaging few duties (including one engaging none) runs the **shallow arm** — a single peer over the union of the two legs; a topic engaging the full floor goes straight to the **deep arm** — two parallel peers over legs made disjoint by construction (the documentation surface resolved from `.docs.internal`, and the tracked tree with that subtree removed, both enumerated from the git index), whose returns the orchestrator reconciles. The **verdict token drives escalation** from shallow to deep — never arm selection — and escalation also fires on an unestablished duty and on a judged-not-engaged duty whose returned bearing observation is anything other than the producer's explicit `none-observed` token, which is the backstop for a topic judged narrower than it is. The orchestrator (never a peer) writes the returned evidence to the run-scoped **`.prflow/tmp/issue-step1-<slug>.md`**, which an escalating deep arm and Step 2's evidence bundle both read so an escalation warm-starts instead of re-deriving; that artifact is out of bounds to the Step 3.6 auditor. A failed, unavailable, rejected, or anchor-unresolvable pass takes the **degraded arm** — a bounded inline verification with a breadcrumb naming the failure kind, its evidence marked degraded — which never terminates the run and never presents a half-verification as a whole one. Step 1 is also where the run's kebab-case **slug** is bound — before anything is dispatched, and no later step binds one — so a single stem spans the Step 1 evidence artifact, the Step 2 derivation artifact, and the Step 4 draft file; Step 1 records it in the fixed, slug-independent pointer `.prflow/tmp/issue-run-slug` that later sites read when they no longer hold it (a pointer that is absent, unreadable, empty, whitespace-only, or not a single kebab-case slug on one line is recorded unestablished and routes to Step 4's retained title-derived fallback). Both `.prflow/tmp/` paths are deleted **on entry**, on every path including the degraded one, so a leftover from a prior run on the same deterministic slug cannot be read as this run's; both are anchored to the working directory rather than the main-root the draft file uses, and in a read-only sandbox the write degrades to a visible inline-in-chat block with the on-disk copies distrusted.
2. **Clarify until Definition of Ready:** an unconditional **independent-derivation pass runs first on every run** — the orchestrator re-derives the full Definition of Ready (problem/beneficiary, behavioral forks, edge/error cases, acceptance criteria) from the problem and the Step 1 findings *before* weighing the user's supplied criteria, then drives clarification from the delta plus conflicts; user-supplied acceptance criteria are challenged on completeness *and* correctness, so a comprehensive-looking story gets the same scrutiny a terse one does. The pass writes its derived list to an **observable, gitignored artifact** (`.prflow/tmp/issue-derivation-<slug>.md`, deleting any same-slug leftover first so the file can only be *this* run's) before any clarification round; a **gate** — anchored before the first clarification question and, unconditionally, before Step 3 drafting, with a per-round re-check mirroring it — confirms that artifact is present *and* holds this run's derivation (freshness, not mere presence), so a skipped pass is surfaced rather than silently waved through. In a read-only sandbox the write falls back to a visible inline-in-chat block (and on-disk files are distrusted as possible stale leftovers). The guarantee stays an **ordering-based self-check with an observable artifact, not subagent isolation**. The Definition of Ready itself: problem + beneficiary, single coherent scope, one decided behavior per fork, **solution-space expansion before convergence** (independently generate the mechanism space and surface a categorically stronger guarantee class than the user proposed), one implementation approach, concrete testable acceptance criteria. Uses the runner's user-question tool (`AskUserQuestion` on Claude Code, the canonical example; `ask_user` on runners like GitHub Copilot CLI), with batching conditional on the tool and clarification capped at a runner-neutral total-clarifying-question budget.
3. **Draft + no-options gate:** outside an explicit `## 🚫 Blocked` section, no unresolved-decision language ("or", "either", "TBD", "option", "approach A vs B"). Unresolvable decisions go into exactly one Blocked section, never invented defaults.
4. **Self-steelman (Step 3.5, mandatory — issue #304):** before the user sees the draft, the skill stress-tests it against the *actual code* — fresh targeted reads/greps, never the ambient context the draft came from. It verifies every load-bearing claim, file reference, and acceptance criterion; runs a **universal-quantifier sweep** (every "never/always/each/every/all/cannot" grounded — pinned per-arm, scoped, or removed — with a planted-defect positive-control obligation on detector-coverage claims); grounds every **occurrence count and coupled-site list** by an executed whitespace-normalized search or the cited evidence records, never recall; reads a "code does X" premise with its **enclosing gates/conditionals and their defaults**; hunts for missed ACs, missed edge cases, wrong assumptions, unstated scope, and an unreconciled multi-state contract (a within-text check that no summary or table form lists fewer causes for a state than the per-state ACs specify); it also flags an **AC mutual-consistency** conflict (no AC forbids a surface another AC's discharge must touch) and a **trust-boundary closure** gap (a protected executable-artifact set defined over the transitive source/exec/import closure of its entry points); binds every **stated-but-unbound input** (a mechanism input named only by role) to a named referent with a cited code reference or an implementer-obligation AC; revises the draft itself and re-runs the no-options gate on the revision; then — at every revision event, per the shared **Revision-delta verification** procedure (stated once, referenced by every revise-and-re-gate site) — walks the revision's edit-batch delta across six classes (mechanisms, lifecycle rules, execution-tier assumptions, dependencies, universal guarantees, and a total-making residual class) and verifies each non-empty class against the code, so audit rounds and the declined-re-audit filing path see delta that has been walked and verified rather than only language-gated; and reports a one-line outcome summary either way, including the universal-quantifier sweep's zero arm (a silent pass is indistinguishable from a skipped step). A genuinely new decision fork routes through the existing Step 2 question machinery, not a new path.
5. **Fresh-context audit (Step 3.6, mandatory — issue #443, extended by #522):** after Step 3.5 passes (which now also **self-checks the draft against the same audit dimension checklist** before any dispatch) and before the user sees the draft, the skill dispatches **one synchronous audit subagent** whose entire value is that it did **not** draft the issue — the mechanism is *information removal* (separated-context critics outperform same-session self-review on critical errors). On the normal **file arm**, the orchestrator writes the current rendered draft to the canonical `issue-draft-<slug>.md` before each round and the auditor **reads that file as the sole draft source** (closing the condensation-drift channel a hand-embedded copy opened) with a carriage/identity check; the drafting conversation, Step 1 findings, and the *reasoning* artifacts stay out of bounds while the draft file itself is the artifact under audit. When the write fails (read-only sandbox), a fallback **embed arm** carries the full body verbatim with its own sentinel carriage check, and the on-disk draft path stays out of bounds. The auditor runs an **adversarial pre-mortem** audit-prompt: a per-finding bar, scope exclusions at issue altitude, one assessed "Quiet Killer" slot, no cap on the number of findings paired with a per-finding length discipline, and a mandatory verdict line with three legal values — `VERDICT: FILE`, `VERDICT: REVISE`, or `VERDICT: DRAFT-UNREADABLE` (file arm only). On `REVISE` the orchestrator verifies each finding against the code, revises, re-runs the no-options gate, runs the shared **Revision-delta verification** procedure over the revision's delta (the same procedure the Step 3.5 and Step 4 revise loops reference), and re-audits **at most once** automatically — the audit informs, it never deadlocks filing. Past that automatic budget the skill **offers user-chosen rounds** (up to 3) via the question tool whenever the run is demonstrably unconverged — the user, not the skill, spends the tokens. Every accepted round's findings are **adjudicated** into must-revise / advisory / invalid; since issue #743 the advisory and invalid grades are no longer bare counts but carry a **durable per-finding record** — a one-line summary and rationale, an impact-class tag, and the auditor's returned finding block byte-preserved — recorded through the state owner (`record-adjudication --advisory-records-file/--invalid-records-file`, refused when a count and its records disagree), read back with `query-adjudication-records`, and rendered to the user **before** the approval election. A **calibration** layer (`query-calibration`, a `calibration=` sibling of the coverage boundary offer) surfaces an advisory grade on an impact-bearing finding (`implementation-correctness`/`scope`/`safety`/`verifiability`) that carries no recorded evidence, so an under-evidenced grade is named to the maintainer rather than silently converged past — disclosure only, **never a filing block**. Full evidence record: [`docs/advisory-adjudication-calibration.md`](advisory-adjudication-calibration.md).

**The lifecycle itself is owned by a tested state-owner CLI, not by prose (issue #546).** Every deterministic rule above — transition legality, round numbering, the automatic budget and the bounded retries, arm routing and its three embed markers, digest computation and comparison, sentinel generation and comparison, the offer triggers, override records, presentation eligibility, and the audit-summary field set — is executed by `scripts/issue-audit-state.py`; the skill records lifecycle events through it and **obeys its answers** rather than re-deriving them each turn. Its two-class contract is what the prose branches on: queries always exit 0 once the arguments parse (an argparse usage error still exits 2) with a decided answer line, except for the multi-line read-back queries `query-findings`, issue #704's `query-claim-baselines` / `query-finding-evidence`, `query-coverage`, and `query-adjudication-records`, which print one decided line per record, and issue #795's composite `query-boundary`, which prints one decided line per boundary component; all of them are strictly read-only, while mutations exit non-zero with a named breadcrumb on an illegal transition or an unpersistable state. Since issue #795 most subcommands print a second and final `next_call=` line naming the next legal invocation, with every state-derivable operand filled and every caller-supplied one bare in a `needs=` field; it is a generated suggestion the caller reviews before running, never an instruction, and the decided answer line is unchanged and stays first. The same issue lets the five subcommands whose round the state uniquely determines resolve an omitted `--round` from state, while every subcommand where the flag selects an operation or names a caller-chosen round keeps it required. Run state persists to a cwd/worktree-anchored `.prflow/tmp/issue-audit-state-<slug>.json`, replacing the markdown event log the offer used to read — the skill still writes the observable audit artifact (`.prflow/tmp/issue-audit-<slug>.md`, same gate/read-only-stand-in convention as the derivation artifact), and both state paths plus the **retired** `.md` leftover stay declared out of bounds so an auditor with repository read access cannot re-anchor on this run's prior verdicts. **Writes to that state document are serialized (issue #1040).** Every mutating subcommand runs inside an exclusive-create sentinel critical section — a `.lock` file beside the state document, created with `os.O_CREAT | os.O_EXCL` (standard-library only) — so two concurrent invocations for the same slug produce a document reflecting one of them entirely and then the other, never an interleaved mixture; each writer also persists through its own unique `tempfile.mkstemp` temporary path (with a bounded `os.replace` retry over `PermissionError`) so two writers never share and truncate one temp file. **Read-only subcommands acquire no sentinel and stay unserialized** (`query-*`, `emit-body`, `check-claim-staleness`), and a fail-closed transitive call-graph check proves `save_state` is unreachable from every read-only-classified subcommand. An **abandoned sentinel is recovered by age**, and the threshold that decides it is `stale_after_s` — *not* the longer `acquire_window_s` a contending writer is willing to wait: a sentinel whose mtime age exceeds `stale_after_s` is unlinked, and the exclusive create is then re-attempted exactly once before control returns to the ordinary acquire loop. Because the shipped `stale_after_s` is strictly shorter than the shipped `acquire_window_s`, a writer contending with an abandoned sentinel always reaches that break inside its own acquire window, which is what makes a crashed writer unable to wedge the slug permanently; the acquire-window expiry is the fail-closed arm for a host whose overrides invert that relation, and it refuses the mutation rather than proceeding. That relation is the load-bearing part — an override that sets `stale_after_s` above `acquire_window_s` trades permanent-wedge immunity for the refusal. This guarantee is **document integrity only**. The **decision channel is a distinct quantity with a named residual**: because `_emit_next_call` re-reads the state after the critical section has released, and every `query-*` reads unserialized, a batch of concurrent mutations renders each `next_call=` line and each query answer against whichever post-image that process happened to observe — so those answers are **not authoritative under concurrent invocation**, even though the persisted document they read is always internally consistent. §11 is the canonical home for this system contract; the skill's operational rule points here rather than restating it. Only the current draft counts as audited: eligibility is grounded on a completed clean-verdict round whose recorded identity still holds — byte-digest equality against the canonical file on file-arm epochs, revision ordering on the embed and inline arms where no trustworthy file exists — or on an explicitly recorded override that no later revision has invalidated, and every `eligible` answer carries a deterministic token bound to the answering digest or revision ordinal (matching the ground that answered) which the summary line quotes verbatim. That **narrows** the prose-compliance gap and makes a skipped eligibility check detectable in the transcript; it does not close it, since no in-process component can force an orchestrator that never invokes it. Where the tool cannot run at all, a named bounded fallback runs one round, asks once, and marks the summary line `state-owner unavailable` — distinct from `degraded`, which keeps its meaning of the inline audit arm.

**Runtime main-thread context (issue #767).** Separate from the skill's *structure* and *static shipped size* discussed above, a long create-issue run accumulates a large **runtime main-thread context** across its many turns. The behavioral instrument `scripts/create-issue-context-eval.py` (maintainer-run over a transcript corpus; never on the skill's runtime path, so no new tool grant) measures it, and the determination of which appended-content classes are authoritative versus safely-removable redundant additions — with the reduction that removes the primary safely-removable class (re-emission of an already-produced block, replaced by a pointer) — lives in [`docs/create-issue-context.md`](create-issue-context.md). That doc is the single source of truth for this axis; it is not paraphrased here.

**Repository-baseline claim provenance and reproducible finding evidence (issue #704).** Two additive payloads extend the same state owner, so both survive a context compaction and read back at every later stage. **(a) Claim baselines.** A *load-bearing* quantitative or location-sensitive claim records the repository baseline it was grounded against via `record-claim-baseline` — a captured revision plus a **per-class measured-content identity**, the classes enumerated first and each given the representation its own drift mode needs rather than one universal baseline: a **location anchor** is identified by a `git hash-object` digest of its measured *paths*, a **count** or **coupled-site inventory** by a digest of the **re-executed search result over the claim's full search domain**, so an occurrence added in a file *outside* the original hit set changes the identity. Their complement — an incidental, non-load-bearing mention — records no baseline, matching the rule that it triggers no verification. `check-claim-staleness` then re-checks deterministically by recomputing the identity and comparing, which reads **no history** (a shallow clone resolves a normal baseline) and localizes the answer: an unrelated base advance leaves a location anchor `fresh` while a count's full-domain change reports `stale`, so a later stage re-derives **only the affected claims**. Because the identity is per claim rather than a global `git status --porcelain` worktree flag, the committed-vs-dirty distinction holds per claim and a **dirty→dirty** edit of the measured content is caught — the case a global cleanliness flag cannot see. An unresolvable measurement records `unestablished`, and an **absent** baseline on a state file written before the feature reads **identically**: both are `possibly-stale` and re-verified, never silently fresh. **(b) Finding evidence.** The Step 3.6 auditor's per-finding bar now requires a locator, the exact command, the observed output, and the baseline revision it read (resolved by the auditor itself — the state file stays out of bounds to it). That payload is multi-line and field-shaped, which the one-line `--ledger-stdin` ledger-summary transport refuses by contract, so it rides a **dedicated per-finding channel keyed by finding id** (`record-finding-evidence` / `query-finding-evidence`) with its own bounded encoding: fields are capped with disclosed truncation and JSON-encoded at the print boundary, so record-splitting auditor text cannot forge a line, and the decision fields (`finding=`, `completeness=`, `conflict=`) cannot be forged because they precede every auditor-controlled value and are drawn from closed domains — the same *data, never protocol* identity rule the ledger enforces by refusal, achieved by neutralization instead. The trailing evidence values are quoted rather than delimited, so the line is parsed by its JSON quoting, never by whitespace splitting. Evidence missing a required field — or carrying the literal `unestablished`, the spelling the auditor bar tells an auditor to use for a field it could not establish — is recorded `incomplete`, never verified. Adjudication is then **proportionate in scope, never in whether the conclusion is checked**: a low-risk finding whose evidence is complete and conflict-free has its **conclusion re-derived from the locator** by a bounded read-only check — confirming the defect holds, not merely that the cited bytes exist — instead of a fresh whole-repository investigation, while a **high-risk** finding (one that would change scope, an acceptance criterion, or a trust/security boundary), one whose evidence **conflicts** with another probe, and one whose evidence is absent or incomplete each get full independent verification. Conflicting probes are surfaced with both values intact and resolved by verification, never auto-resolved to either. The orchestrator reconstructs every replay from the **locator** using its own reads and **never executes an auditor-supplied shell string**. The coupled invariant is unchanged: a resolution is recorded only from that site's own per-finding verification, never from the auditor's say-so. Every arm is best-effort — staleness, incomplete evidence, a conflict, a read-only sandbox, a git-unavailable baseline, a denied probe, or a compacted context degrades with a disclosed marker and **never blocks issue creation**.

**A `stale-override` refusal names its own recovery (issue #611).** That refusal is fail-closed and correct, but it used to state only the reason token, so an agent that hit it rediscovered the way out by trial — costliest at `emit-body`, where the creation epoch is already recorded. The tool now writes an arm-selected recovery breadcrumb to stderr beside the refusal at its **two refusal surfaces only** (`query-eligibility` and `emit-body`), never from the shared evaluation they both call and never on `query-summary`, which is a *rendering* surface and would otherwise grow an unplanned stderr line on every summary render of a stale-override-shaped state. The stdout token line stays byte-identical — the remedy is purely additive. The arm is selected by the **staling operand observed on the newest current-ordinal override, never by the epoch's query-time arm**: an override's digest binding is fixed at record time while the epoch arm is keyed at query time, so the two legitimately diverge (a file-write failure and embed retry landing between the record and the query leaves a digest-bound override on an embed-arm epoch), and keying on the epoch arm would name the wrong remedy on exactly that divergence. A current-ordinal override whose recorded digest differs from the draft leads with `record-revision` (the revision is not yet recorded); an already-recorded revision that invalidated an earlier override does **not**, since that would send the caller to re-record state it already holds; and every shape whose cause could not be established — an uncomparable digest binding, a future-ordinal or hand-edited record — makes no claim about the revision state at all. No arm names a bare `record-revision`-then-`record-override` pair: that sequence would re-arm a user election the user never made. Every arm therefore ends in the same clause — re-present the revised draft and record a new override only on a fresh explicit user election through the offer surfaces, a fresh clean audit round being the other eligibility ground.

**Axis-complete evidence bundle and finding actionability (issue #548).** Two additions gate approach recommendations on recorded evidence rather than inline judgment. **(a) The evidence bundle.** The Step 2 independent-derivation pass writes a read-only `## Evidence bundle` section into the derivation artifact on every run — one entry per axis on an effective list (a generic floor: producers, consumers, execution tiers, persistence, lifecycle states/termination paths, migration/coexistence surfaces, coupled tests/docs — extended by a consumer `## Evidence axes` extension section) in one of three forms (`Verified:`, `N/A — checked …`, or `unestablished — …`), opened by a self-describing header restating the rules and the pass-time axis list. A **bundle-coverage gate** fires at the same two sites as the derivation gate (before the first clarification question and unconditionally at the Step 3 drafting precondition), the per-round Definition-of-Ready re-check keeps it current against three triggers, and the implementation-approach fork question's `(Recommended)` marking must cite a bundle entry by axis name (in `Verified:`/`N/A — checked` form) while disclosing any unestablished axes — so an evidence-thin recommendation is visibly thin at approval time. The bundle rides inside the already-out-of-bounds derivation artifact, so the audit information diet and its pinned out-of-bounds lists are unchanged. **(b) Finding actionability.** After each accepted audit round, every finding is adjudicated into **must-revise** / **advisory** / **invalid-unverified**; the state owner records this via `record-adjudication`, accepting the payload only when the adjudicated verdict and unresolved-must-revise count agree (`VERDICT: FILE` may carry advisories; `VERDICT: REVISE` requires ≥1 verified unresolved must-revise finding). The **T1** offer trigger and a new **`query-convergence`** query consume that post-adjudication unresolved-must-revise count (a converged run = final adjudicated `VERDICT: FILE` with zero unresolved must-revise axis-attributable findings; an unestablished count is not converged — unknown is not zero) instead of the raw verdict token, while **T2**'s **other** fail-closed arms are unchanged (it gains one new `unadjudicated-round` arm preserving the offer the raw-REVISE T1 token used to fire — firing on a completed REVISE round whose post-adjudication unresolved-must-revise count is absent, whether un-adjudicated or adjudicated with an unestablished count). The Quiet Killer becomes one assessed slot (`Quiet Killer: none` is legal on `FILE`), and the Step 3.5 and Step 4 summary lines report axis coverage plus post-adjudication counts by actionability class. **(c) Post-revision finding resolution (issue #603).** The counts in (b) froze at round close, so a drafter who revised and verified every finding fixed still read `T1: hold` and `converged=no reason=unresolved-must-revise-remain` forever — the audit informed but deadlocked filing. Adjudicating a round `REVISE` with a settled count now additionally records a **per-finding ledger** under a required `--ledger-stdin` flag (one status-prefixed one-line summary per must-revise finding, piped through a quoted-delimiter heredoc so the shell never expands auditor-derived text, and refused when a summary forges a `<field>=` word of the tool's own printed protocol vocabulary — ledger text is identity data, never protocol). Three post-close channels then move an entry: `record-resolution` binds named entries to a recorded revision ordinal (cross-round, so a late fix clears the round that found the defect), `record-reopen` marks a resolved entry unresolved again when the fix did not land, and `record-invalidate` retires a misclassified finding with a mandatory reason rather than laundering it through resolution as a fix that never happened. `record-adjudication` is correspondingly **write-once** per round, with those three as the sole sanctioned post-close channels, and a FILE adjudication **supersedes** every prior unresolved entry (terminal), so an auditor-accepted clean round still converges the run exactly as it did before. T1 and `query-convergence` consume the **run-wide effective** count derived from those ledgers — derived by the tool rather than accepted from the caller, with one disclosed AC5 boundary: an earlier `REVISE` round that recorded no ledger contributes its at-close `--unresolved-must-revise` figure, which the caller supplied — `query-convergence`'s `unledgered_revise=` field names exactly those rounds so the gap is visible rather than silent — and convergence now reports its **basis and currency**: `basis=adjudicated` when the auditor's own FILE verdict vouches for the state, `basis=resolution` when the effective count reached zero through self-verified post-close changes, and `basis=resolution-stale` when any entry's settling provenance predates a later revision (judged per entry). The read-only `query-findings` prints one line per ledger entry — the first of the tool's multi-line read-back queries — and is the **durable** read-back the orchestrator reconciles a later round's findings against, never context recall, so the mechanism survives a context compaction. `query-summary` exposes the same two operands as `effective_unresolved=` and `convergence_basis=`, both placed **before** the contractually-trailing `attestation=` field so nothing follows it. Eligibility is deliberately untouched: revised bytes still refuse `approve` as `unaudited-revision`, so self-attested resolution never reaches the creation gate.

**(d) Positive per-dimension coverage evidence (issue #708).** A clean `VERDICT: FILE` with zero findings used to be structurally indistinguishable from a cursory read — carriage proves which draft *bytes* the auditor read, never the *scrutiny* those bytes received. So the audit now records a **positive, falsifiable, per-dimension coverage assertion**. The renderer gains an `enumerate-dimensions` mode emitting a canonical, keyed, count-stable effective-dimension list, which the **orchestrator** runs to hold the authoritative operand; **issue #729 made those keys first-class declared data rather than a scrape of the rendered prose** — each generic dimension declares its key on a `<!-- dim-key: <lowercase-kebab> -->` line above its checklist bullet (emitted `g:<declared-key>`, stripped from the auditor-facing prose, fail-closed on an undeclared bullet, an orphan declaration, a malformed key, or a duplicate), and a consumer dimension keys off its own declaration, else its bold-lead name slug, else a hash of its text (`c:<key>`), retiring the positional `c:<n>` that reshuffled whenever a consumer inserted a bullet mid-section. Rewording a **generic** dimension therefore leaves its key byte-identical; a consumer dimension gains the same guarantee only by carrying its own declaration, since the bold-lead-slug fallback rekeys on a name edit and the hash fallback on any text edit. Every declaration arm — template and consumer alike — fails closed on the render path as well as the enumeration path, so the two projections cannot drift apart silently. **Migration is a no-op:** the state owner treats coverage keys as opaque strings and checks a round's totality against the `coverage_expected` keyset persisted in that round, never against a fresh enumeration, so a run recorded under the previous derivation stays readable and keeps its backing without any rekeying step. The auditor runs the same deterministic render and returns, per dimension, one outcome from the closed set **`exercised`** / **`valid-N/A`** / **`unestablished`** / **`skipped`**, joined to the orchestrator's list by the shared key. The trust model splits by where the operand lives: the **auditor** self-reports outcomes and anchors as untrusted identity data; the **state owner** (`record-coverage`) enforces a text-only floor on the anchor alone (non-empty, no forged `<field>=` protocol token, no record-splitting byte, a hard per-anchor length cap — a floor-failing `exercised`/`valid-N/A` downgrades to `unestablished`, unknown never collapsed onto backed); and the **orchestrator** runs the two data-dependent checks (the anchor is not byte-identical to the dimension's rendered prompt text, and any quoted draft line provably appears in the digest-verified re-read of the draft it wrote) and adversarially adjudicates each anchor for substance exactly as it adjudicates findings (a generic or prompt-paraphrasing anchor becomes `skipped`). A run is **coverage-backed** only when every required dimension resolved to `exercised`/`valid-N/A` with adjudication-surviving evidence, derived from the final accepted clean round via `evaluate_coverage` / `query-coverage`. An unbacked **full-render** clean audit fires a new offer trigger — a sibling of T1/T2 (`query-triggers` now answers `coverage=hold|not-hold`) contributing to the **single** boundary offer, bounded by the same user-round cap, firing coverage-only **at most once per run**; a legitimately narrowed **degraded** render discloses but never fires. Coverage-backing is a **distinct axis from convergence** — it never redefines `evaluate_convergence` and never gates `emit-body`/`query-eligibility`; the offer is its only teeth, so **filing is never blocked**. The mandatory audit summary line carries `coverage_backing=` and `coverage_render=` on every arm and outcome. The honesty scope is bounded and stated: `coverage-backed` certifies per-dimension evidence of the required shape survived the structural floor and generic-adjudication — it does **not** certify genuine scrutiny, and the residual thin-but-plausible-anchor gap is disclosed, not implied away.

**(e) Final-byte audit coverage — did anyone audit the bytes we are about to file? (issue #792).** Coverage-backing (d) certifies the *scrutiny* an accepted round applied; it says nothing about whether the round that earned it saw the bytes that actually get **posted**. Three sanctioned paths file bytes no auditor has ever read: a `user-decline` override at the approval election, a run that converged on the drafter's own self-verified fixes (`basis=resolution`) rather than an auditor's clean verdict, and a creation attestation — whose comparand is deliberately the digest of the bytes actually posted, so a legitimate override filing attests `match` against bytes the audited round never covered. **The attestation proves identity; it never proved audit coverage.** So the lifecycle now reports coverage of the final bytes as its own axis: `evaluate_final_byte_coverage` answers `covered` / `uncovered` / `unestablished`, rendered on `query-summary` as `final_byte_coverage=` immediately before `bound_root=`. `covered` requires all four terms of the shipped clean test — the newest completed verdict-bearing round carries `VERDICT: FILE` (a newer completed `REVISE` revokes it), its recorded dispatch digest equals the current canonical-file digest, no recorded revision postdates it, and its steering-absence was **established** — because the axis reports what the engine would actually ground on. **Four things never set it**, and the complement of that set is what `covered` means: an attestation (tamper evidence, not coverage), a `cap-reached` override (a ceiling record, not a verdict), a `user-decline` override (a user's election, not an auditor's reading), and a clean round whose steering was never established. `unestablished` is **not** `uncovered` and covers exactly four states — no readable, owned lifecycle state exists at all; no completed file-arm verdict-bearing round exists; the canonical file could not be digested; or no draft digest was supplied — so a pass whose pre-dispatch write fails and lands on the embed arm cannot downgrade a known `uncovered` and consume the safety pass on a read-only host.

**The exact-byte pass, funded from its own slot.** Where coverage reports `uncovered`, an **exact-byte audit round** is offered at the last moment it can be true — immediately before the Step 4 approval election, when the bytes are final. It is answered on its **own** `query-final-byte`, deliberately not appended to `query-triggers`, whose boundary consumer applies *while any holds* at the **pre-presentation** pause where the bytes are not yet final. The pass draws on a **dedicated slot outside the user-round cap** (`record-final-byte-offer`), so a run that legitimately spent every discovery round — and a run carrying a `cap-reached` override — still gets its safety pass; `record-dispatch`'s funding test accounts for that slot, and the derived automatic-re-audit spend is suppressed for a pass so an accepted one cannot fund a phantom round. The slot is **spent per canonical digest**, not per run: a recorded revision that changes the bytes re-arms it (bounded by a per-run cap on **honoured** passes, whose exhaustion the summary line discloses, plus an absolute grant ceiling that stops a refund→re-arm loop on a host where every pass degrades), so a pass taken on bytes the user then edits never leaves the bytes actually filed unofferable. A pass that closes **without** a file-arm verdict — a failed pre-dispatch write, an unparseable verdict, an exhausted `DRAFT-UNREADABLE` retry — **refunds** the slot, because the offer's own precondition is that an accepted round could honour it. The pass is an **ordinary whole-draft round** through the existing file-arm machinery (no new dispatch vocabulary), but it is carved out of the iterate loop's return handling: on `REVISE` its findings are adjudicated with a ledger and disclosed at the election rather than forcing a revise-and-re-present cycle that would change the digest and re-arm the slot off the mechanism's own return. It is excluded from the coverage-round and calibration-round selectors, so an accepted pass retires neither axis. Like (d), this is a **distinct, non-gating axis** — off `query-triggers` and off `query-convergence`, and it never gates `emit-body` or `query-eligibility`. **Filing is never blocked:** the user's explicit election remains the documented path by which a determined filer files. What changed is that the lifecycle stops representing that path as equivalent to an audited one, and the one line the maintainer reads before approving says so.

**Tiered canonical-draft-root binding (issue #562).** The draft file the auditor reads (and the file-arm posting sources from) has always anchored to a *different* root than the three cwd/worktree-anchored reasoning artifacts (the derivation artifact, the audit report, and the state `.json`) — the draft is written under the **main** repo root via `resolve-main-root.sh` so its displayed path opens from a worktree editor, while the reasoning artifacts stay cwd/worktree-anchored; that divergence is deliberate and must not be unified. This PR lands the **state-owner half** of a tiered binding: on a run whose main root is unwritable while the active worktree is writable (an isolated/background session), a **successfully-writable** canonical draft root can be bound instead of the draft write degrading straight to the embed arm. The tool gains that capability here; the **skill-side tier-selection ladder** that will consume it — tier 1 the resolver's main root (taken only on a clean, non-empty resolver answer whose `.git` entry is a directory, a bash-builtin test), tier 2 the active-worktree root (`git rev-parse --show-toplevel`), tier 3 the existing embed fallback, with the **first landed write** binding that root for the rest of the run — is the paired follow-up (issue #569). Issue #569 lands the **binding-reuse half** of that ladder: the skill now records the immutable binding at its first landed canonical-draft write (`record-draft-binding … --tier main-root`), reads the bound root back from `query-draft-binding` at the write/display/overwrite sites that run in a **later turn** (never re-resolving or recalling it there; the same-turn presentation write keeps the root already in hand, and an unbound `bound=none` answer deliberately falls back to a fresh resolution), and forwards the bound canonical path to `record-dispatch --write-path`, which the state owner cross-checks against the recorded binding (`write-path-mismatch` on divergence). The full **tier-2 active-worktree / tier-3 embed selection** and the strict **binding-required** file-arm enforcement (fail-closed when a file-arm dispatch has no recorded binding, with its coupled reconciliation of every pre-binding file-arm test's bound-first reader setup) remain a further follow-up — a `main-root`-tier binding is what the skill selects today, so the bound root equals the resolved main root and the write still degrades to the embed arm on a write failure. The binding is recorded once through the state owner (`record-draft-binding`: the bound absolute path, a bound-tier token `main-root`/`worktree-root`, and the divergent non-bound root when both exist) and is immutable; the tool's digest, `approve`-eligibility, and body-emitting operations resolve the draft file from that recorded binding rather than a caller-supplied path a compacted context could drift, and a `query-draft-binding` query plus the `bound_root`/`bound_tier` summary fields expose it so a future display marker (`draft bound to worktree root` on a worktree-root binding) and the divergent-roots out-of-bounds enumerations can obtain their operands from the tool. A post-revision write-failure closure lands with it: revision records may carry the revised bytes' stdin digest, a write failure at the bound path is recorded, and the file-arm `approve` eligibility ground now refuses bytes a recorded revision has staled but that never landed (`unaudited-revision`) instead of waving them through on stale byte-identity — re-enabling once a fresh clean-verdict round that no revision postdates is recorded (the separate `latest_revision_landed` presentation flag clears independently, when a subsequent landed write at the bound path carries a digest equal to the revision's recorded stdin digest). The state `schema_version` is 3 (issue #709 bumped it from 2 for the additive steering and dispatch-instruction records).

**Durable staged canonical-draft write, and the #562 write-failure closure reached from the skill for the first time (issue #705).** The write-failure closure above shipped in `issue-audit-state.py` but was **inert in the skill** — no create-issue recipe recorded a revision's `stdin_digest`, called `record-write-failure`, or read `latest_revision_landed`, so `record-revision --stdin-digest` and `record-write-failure` were producers the skill never invoked. Issue #705 wires them in through **one shared *Staged canonical-draft write* procedure** every canonical-draft write site (Step 3.6's pre-dispatch write and its re-dispatches, Step 4's presentation write, and Step 4's iterate-on-feedback overwrite) references by name. A new bundled helper, `scripts/stage-draft-write.py`, owns three single-process modes: **stage** lands the intended title-and-body bytes atomically at a staging artifact keyed on this run's nonce **and, since issue #793, on the staged bytes' own digest** — `issue-draft-<slug>.<nonce>.<digest>.staged.md`, resolved by the helper from the caller's base path and reported back, since the digest is computed from stdin inside the helper and each shell fence is a fresh process (a temporary sibling plus a rename, so an interruption after the run's first staging write leaves a complete copy on disk); **emit** carries those staged bytes into `record-revision --stdin-digest` without a heredoc; and **apply** copies the staged bytes onto the canonical file via `os.replace` (never renaming the staging artifact, which therefore survives for the recovery arm), re-digests the canonical file, and reports whether it agrees with the caller's **declared** `--expect-digest` — the answer the run reports to `query-arm` as `--write-landed`. A disagreement after a revision write records `record-write-failure`, presents from the in-context revision bytes, and re-attempts the replace exactly once; a **cross-turn landed re-check** (canonical file re-digested against the latest revision's recorded `stdin_digest`) is what detects an interruption the in-process comparison cannot see, since a killed process leaves no in-process signal. The tool half is enforced: `record-revision` now **refuses** a file-arm-latest-round revision that carries no `--stdin-digest`, so the digest guarantee is owned by the tool rather than by prose a compaction can evict. A verified multi-finding revision wave applies as exactly one replace and one revision record, with per-finding traceability unchanged (`record-resolution --resolved-ids`). The staging artifact is added to both audit out-of-bounds enumerations (after a failed replace it holds bytes the canonical file does not), and a read-only sandbox arm degrades with a reduced-durability report — filing is never blocked. Nothing about the schema changes at that time: `schema_version` stayed **2** — the historical value it carried when #705 landed — and no new state key was added. (The current value is **3**, stated in the #562/#569 paragraph above; #709 bumped it after this change.)

The Step 4 presentation carries a one-line audit summary read from the tool's summary query (findings, revisions, verdict, rounds run, an embed-arm marker, `user declined further audit` when applicable, the eligibility token, and the word "degraded" whenever the attempt-first dispatch fell to its inline degraded arm), and a consumer `## Audit dimensions` prompt-extension section is re-loaded fresh at dispatch time and forwarded verbatim to the auditor. **Since issue #600 the audit prompt is rendered by `scripts/render-audit-prompt.py`, not hand-emitted:** the audit-prompt template, the generic dimension checklist, and the heading-extraction rule live in the committed template file `skills/create-issue/references/audit-prompt-template.md`, and on the normal path the auditor runs the renderer itself (a positional two-marker `render-status:`/`render-end:` delivery check, with a template-file Read fallback ladder). The information diet and out-of-bounds policy stay prose in the skill; the prompt *text* is renderer-owned.

**The dispatch instructions are generated and hash-verified too (issue #709).** #600 made the audit-*instruction* block observable and left the orchestrator composing the wrapping **preamble** freehand — an unobserved surface through which a parent could topic-prime the auditor (focus, prioritization, reassurance, scoping) and still reach a coverage-backed clean audit. The preamble is now generated by the same renderer's `dispatch-instructions` mode (deterministic, reading the draft **title from the draft file** — no drafter free text on a command line), written to `.prflow/tmp/issue-audit-dispatch-<slug>.md`, and the Agent-tool prompt is a generated pointer to that file and the draft file and nothing else. The auditor `git hash-object --no-filters`es the instruction file exactly as it already does the draft file and quotes the object ID; `issue-audit-state.py` **regenerates** the canonical instructions from the round's recorded closed inputs and compares — regenerating rather than re-reading its own write-time digest is what catches a hand-written steered file that bypassed the generator. The clean (`VERDICT: FILE`) eligibility ground now additionally requires that match **and** the auditor's `extra-dispatch-content: no` affirmation, and the state owner records the outcome as the round-bound `steering` / `steering_reason` pair, exposed by `query-summary` as two space-free tokens placed **before** the contractually-trailing `attestation=` field. **What this proves is scoped, and the summary line says so:** the file hash proves the instruction *content* was canonical; the Agent-tool prompt *string* is not a hashable artifact, so it is covered only by canonical generation plus the auditor's best-effort affirmation — a positive report withholds the clean ground, but its silence is not a proof. The mechanism **narrows** that one channel rather than closing it, the same withhold-then-disclose posture §11 already uses for a skipped eligibility check. On every non-established path — a mismatch, a reported extra-content flag, a generator failure, and the embed / inline / read-only-sandbox arms where no instruction file can be written, so the property is **unestablished by construction** — the audit summary line carries an `audit independence unestablished` marker (distinct from the reserved `degraded` token), a new `evaluate_triggers` arm fires the existing re-audit offer (so even a zero-finding `VERDICT: FILE` round is offered one unsteered re-dispatch rather than silently withheld), and **filing is still never blocked** — the user's explicit approval files through the same documented override election an unresolved `REVISE` already uses. The enforcement is always-on: no `.prflow/config.json` key gates it and no new workflow tool grant is involved. **The transport is named exactly (issue #768):** the orchestrator writes the generator's stdout to `.prflow/tmp/issue-audit-dispatch-<slug>.md` with a **shell redirect** (the redirect truncates the target before the generator runs, so no delete-first step exists; the write has landed when the generator exits zero and leaves a non-empty file), and obtains the generated `dispatch-pointer:` line **from the generator's own stderr** (issue #795): the standalone read-back extraction this paragraph used to prescribe is retired, because a line the generator folds onto stderr in the same invocation that writes the file needs no second extraction step at all — and the old recipe's own constraint (never `grep`/`sed`/`awk`, since the extracted line becomes the entire Agent-tool prompt and an emitted result must not depend on a tool outside the preflight-guaranteed set) is satisfied by construction once no extraction runs. The stderr line is asserted byte-identical to the `dispatch-pointer:` line inside the stdout the same invocation wrote. The instruction bytes therefore never traverse the orchestrator's context. This is a local/interactive-tier skill: no cloud profile grants these heads, so the cloud matcher's redirect-shape denial does not bind it, and the dispatch blocks on the completed result rather than arming any fallback wakeup.
6. **Review then create:** show the **complete rendered issue** in chat (never summarized), get **explicit confirmation**, then `gh issue create`. After creation, present a **gated** offer to start implementation — posting the bare `/prflow:implement <n>` comment only when the issue has no open dependencies/blocked decisions and the cloud tier is enabled, else printing a one-line reason (see the gated-offer hardening below).

**Tool-owned round KINDS, and the durable byte history they need (issue #793).** Every Step 3.6 round used to be the same round: a cold, whole-draft, whole-repository derivation. The state owner recorded an `arm` per round and nothing about what the round was *for*, so a later round re-established from scratch the repository facts an earlier one had established, over sections no revision had touched, while the findings it should have been re-checking sat untouched in the ledger. The round **kind** is now the second tool-owned per-round dispatch dimension beside the arm, resolved by the same query-then-obey-then-cross-check shape: `query-round-kind` answers one of exactly two kinds — `discovery` (a cold whole-draft round) or `targeted` (a claim-scoped re-check) — with the reason token that selected it, and `record-dispatch` **requires** `--kind` and refuses any kind other than the one the tool selects at that moment (`kind-mismatch`), exactly as it refuses a `write-path-mismatch`. The orchestrator never chooses a kind, because the context that would choose it is the anchored context the audit exists to remove. **Selection fails toward the expensive kind**: `targeted` requires all five of a revision postdating the last completed round, a `file`-arm latest attempt, dispatch bytes recoverable from the byte history with a matching digest, a non-empty enumerated claim set, and a non-empty computed changed-section set — and every other input, including every unestablished one, selects `discovery` and names the failing condition. An empty delta and a delta that errors both select `discovery`; neither is read as "nothing changed".

That delta has no operand without a byte history, so `stage --path` became a **base** the helper completes with the staged bytes' own digest, reporting the resolved path (`record-staged-write` records it durably; `query-staged-write` resolves it back). A second stage of different bytes lands beside the first instead of overwriting it, re-staging identical bytes resolves to the same path, and the nonce stays in the leaf so the write-failure recovery arm can still name its artifact after an interruption — it re-applies the artifact **that write recorded**, never the newest on disk. **A `targeted` auditor learns what to check, never what was concluded:** the enumerated claims (id plus one-line summary) and the changed-section set travel in **one dispatch-scope file whose path AND content digest both join the closed recorded regeneration tuple**, frozen at dispatch. That freezing is forced rather than tidy — the instruction file is regenerated and digest-compared over a closed tuple and a divergence is sticky, so a payload passed as an unrecorded render argument, or read from the live ledger, would make every scoped round diverge (post-close status mutations would give the return-time regeneration a different ledger than dispatch saw). The identity-data floor sits at the single state-owner write site, so the closed protocol-token vocabulary stays in one module; the renderer refuses an empty claim set independently, so a scoped round cannot pass vacuously. Absent/unreadable and tampered scope files take **distinct** named steering reasons, because they send a reader to opposite remedies.

**A clean `targeted` round is confirmed, not trusted.** It never grounds `evaluate_eligibility`'s clean scan, never backs the coverage axis, never wipes the calibration signal and never reports `basis=adjudicated` — `_last_discovery_round` was widened rather than duplicated, exactly as its own docstring said a second non-discovery kind should extend it. Teaching the scan to merely *skip* a clean scoped round would land it on the preceding `REVISE`, break, and refuse, so while the confirming budget remains the tool instead selects a **confirming whole-draft round** through a new `confirm-whole-draft` next-action token, funded from a **counter of its own**. That selection covers every `targeted` round closing `FILE`: a sweep in which every enumerated claim returned `addressed`, and equally a return that carried no per-claim block at all — the round is recorded UNUSABLE, and the confirming round is scheduled precisely *because* it established nothing. `record-dispatch` funds on the same predicate `next_action` schedules on, deliberately not on the narrower all-addressed sweep, so the error-recovery path can never be directed to open a round the tool then refuses as unfunded. That separation is forced too: the automatic pool is shared, and walking it at the shipped ceiling of one shows the confirming round already refused at any position. `_MAX_AUTOMATIC_REAUDITS` is therefore left alone — it has a second reader in `next_action`, so raising it would move a whole round out of the user's decision on every run, including the embed-arm, inline-arm and empty-delta runs that can never take a scoped round; issue #827, which proposed raising it, was closed as not planned in favour of that position. A scoped round records **no ledger of its own**: its per-claim return updates the existing entry each claim names (`not-addressed` reopens or leaves unresolved, `addressed` changes nothing, since resolution stays the drafter's own recorded verification), so a mechanism built to reduce rounds cannot inflate the very count that fires the offer for more of them. A claim the round dispatched but the return omits, and a claim returned outside the closed `addressed`/`not-addressed` set, are both recorded `not-addressed`. The Step 4 audit summary reads the same way: its verdict and class counts ground on the latest **whole-draft** round rather than `last_completed`, so a scoped re-check never renders as the run's verdict, and the scoped round is reported beside them under its own `scoped_round=` token rather than dropped — a reader sees that it ran without being told a whole draft came back clean. That selector differs from `_last_discovery_round` by exactly one clause: a final-byte exact-byte pass *is* whole-draft evidence here, whose verdict issue #792 renders on purpose.

The issue is created **only after the user explicitly confirms**: a pending confirmation is a valid waiting state, not a reason to create.

**Verified-or-obligation for mechanical claims (issue #380).** A mechanical prediction in an issue — an assertion of a concrete outcome such as "running X reports Y", "the extractor/grep/command emits Z", or "this must fail RED reporting W" — must take exactly one of two decided forms: **(a) verified** — the drafter actually ran the extraction/grep/command while drafting and cites its *observed* output, or **(b) an obligation** on the implementer ("the pin must cover X"), never a prediction of the specific result the drafter did not execute. An unverified mechanical prediction reads exactly like a decided requirement and sends the implementer to encode a falsehood; both the Step 3.5 steelman verification loop (`skills/create-issue/SKILL.md`) and the Testing Strategy guidance in `skills/create-issue/references/issue-template.md` enforce this. The same discipline governs `Relevant Classes/Files` line anchors — cite the symbol or section, not a `file:line` number that rots between drafting and implementation.

**Re-derivation handles for `Verified:` premises, re-checked at implement time (issue #868).** A `Verified:` bullet is what licenses an implementing run to **skip its own investigation** — and until this landed, nothing re-checked one after the issue was filed, so a premise that had since become false silently converted "go and check" into "this was already checked" (issue #857 is the worked case: three of its premises were false by the time #864 implemented it, and two acceptance criteria were unimplementable as prescribed). Both halves of the loop are closed. **Drafting side:** `/prflow:create-issue` requires every `Verified:` bullet to carry a **self-contained re-derivation handle** — the repository path in backticks plus the sentence quoted verbatim from it, or the exact command whose output grounded the claim — stated in `skills/create-issue/references/issue-template.md` (with a matching drafting-checklist row) and in the Step 3.5 steelman, and executed at Step 3.6's pre-dispatch canonical write, the first anchor at which the draft file exists; a handle-less bullet is rewritten before the user sees the draft, and like every arm of that skill the check is best-effort and never blocks issue creation. **Implement side:** `/prflow:implement` Phase 1.6 gains a **Verified-premise re-check** pass that re-derives each recognized bullet against the tree the run will build on. Both consume the same bundled helper, `scripts/check-verified-premises.py`, which classifies each bullet's handle (`path-quote` / `path` / `quote` / `command` / `none`) and adjudicates it as `holds` / `refuted` / `unestablished`. Its governing asymmetry: **refuting is the hardest verdict to reach**, because a refutation makes the implementing run discard the premise and file issue-accuracy feedback against the issue — so only a positively adjudicated claim refutes (a strongly-cited path absent from the tree, or a quoted sentence that no longer occurs in the file it cites) while a cited directory, a glob, a `::`/anchor/line locator, a filename-shaped identifier naming no directory, an elided quotation whose fragments do not resolve, an unreadable cited file, and a path resolving outside the repository all resolve to `unestablished` — which costs only an investigation the run would have done anyway. A refuted premise is discarded in favour of direct investigation but does **not** Block the run; an unestablished measurement is never read as a clean pass — every bullet is treated as unverified and re-investigated. **Security boundary:** the issue body is third-party text, so the helper performs read-only file reads and nothing else — it imports no `subprocess`, makes no network call, never executes a command drawn from the body (a `command` handle is reported for the caller to re-run under its own judgment), and refuses a cited path that is absolute or escapes the repository root. Per-arm detail is in [`implement-skill.md`](implement-skill.md); the helper's vendored literal is granted on the `implement` and `command` capability profiles, leaving the `review` lock unchanged.

**The `Documentation Needed` contract with `/prflow:implement`.** When an issue names specific files that must be documented, the create-issue template renders them under `## Implementation Notes` in a canonical `- **Documentation Needed** — …` bold-bullet list item. That block is the input to `/prflow:implement` Phase 4.1's deterministic path extractor (`scripts/extract-doc-needed-paths.sh`), which turns the named files into mandatory doc-pass deliverables. To keep a differently-rendered body from silently skipping that gate, the extractor accepts **three** scope-opening shapes — the canonical `- **Documentation Needed**` list item (issue #185), a bare blank-line-preceded `**Documentation Needed**` bold paragraph (issue #309), and a `### Documentation Needed` level-3 heading (issue #380) — all emitting the same paths. The template canonically emits the bold-bullet form; `lib/test/run.sh` pins the template literal and the extractor's accepted shapes as a coupled pair so the producer and consumer cannot drift. Within the scoped block, command and grant literals are **not** deliverables (issue #644): a backtick span yields a path only when its content is a single bare-path token or several extension-bearing / in-tree bare-path tokens, while a `:`/`*`/`(`-bearing span (`` `Bash(x.sh:*)` ``), a bare command word (`` `bash lib/test/run.sh` ``), an un-backticked `Word(...)` call group, and a fenced code block are treated as scope markers that contribute no tokens (a suppressed backtick *span* leaves a one-time stderr breadcrumb; `Word(...)` call groups and fenced blocks are removed silently). Because the extractor ships to consumers via the `prflow_version` vendor fetch, a consumer should normalize its open issues' Documentation Needed blocks to one bare backticked path per span before bumping, since a multi-token span authored under the older tokenization can otherwise be reclassified from a deliverable to a suppressed literal.

**A silent non-response is never disengagement.** During Step 2 clarification, a question-tool timeout (`No response after 60s`) or the user stepping away does **not** engage the draft-from-decided / Blocked path — the skill pauses and re-asks the unanswered question in its final chat message rather than proceeding, drafting, or guessing a default. Only an *explicit* reply ("just create it", "you decide", "I don't know") or an exhausted clarification budget of **answered** questions engages that path. This mirrors the Step 4 confirmation gate: with no response, the pipeline stays paused rather than moving on without the user. (The ~18-question budget counts *answered* questions, so silence never consumes it.)

**Visual specification for UI changes.** When Step 2 infers an issue involves user-visible UI changes, it checks the user-provided resources (pasted images, attached files, URLs, design-tool links such as Figma) for an existing screenshot or mockup and records it in a `## Visual Specification` section — embedded when a hosted URL exists, otherwise referenced with a note on how the implementer can obtain it. When none is provided it asks for one; and when the user has none, it **verbally verifies** the visual details — placement & layout, visual states, responsive behavior, design-system match, plus any task-specific dimension — before finalizing the draft. A screenshot is **preferred, not mandatory**: verbal verification is an accepted substitute, and an unresolved placement detail at disengagement flows to the existing `## 🚫 Blocked` section. Non-UI issues skip the whole path and gain no new questions. This is **prose guidance, not a new gate** — inline LLM inference in the same Step 2 clarification that already assesses scope and forks.

**Four authoring-pipeline hardenings (issue #446).** (1) **Cross-issue `## Dependencies`.** The issue template gains an optional top-level `## Dependencies` section, rendered above `## Problem Statement` and included only when a prerequisite is still open at drafting time; each entry is a `Blocked by #N — <reason>` line. Both the heading and the `blocked by #N` phrasing are forms `/prflow:implement`'s early Phase 1 dependency preflight already recognizes as a declared sequencing dependency, so the section feeds the existing implement gate with **no recognizer change** — giving create-issue-authored and human-authored issues a deliberate producer for a gate that previously had none. Step 2's Definition of Ready gains a known-prerequisites item that infers candidates from the story and Step 1 findings and confirms them with the user (no new question when none apply); and `/prflow:implement` Phase 4.0's deferred follow-ups render the same section with a `Blocked by #<parent>` line — a documented human-visible redundancy alongside the mandated `Follow-up to #N` opener that the early Phase 1 dependency preflight already recognizes. It stays distinct from `## 🚫 Blocked` (unresolved *decisions*) and the `Technical Context` → `Dependencies` bullet (service/module/library). **After creation, each prerequisite declared inside the `## Dependencies` section is additionally registered as a GitHub-native blocked-by dependency on the created issue (issue #1011), so the blocker shows in GitHub's own issue header, issue list, and project views without anyone reading the body.** Both post-creation producers stamp it — `/prflow:create-issue` Step 4 and `/prflow:implement` Phase 4.0's deferred follow-up — through the best-effort helper `scripts/apply-issue-dependencies.py`, the third member of the post-creation REST-stamp family beside `ensure-label.sh` / `apply-labels.sh`: it fetches the created issue's body itself (so it takes only the number), derives the prerequisites through the same **section-scoped** recognizer factored out of `scripts/preflight.py` (deliberately narrower than the reversible implement gate — a persistent GitHub write consumes only the reserved section, and any number that resolves to a pull request or to the issue's own number is skipped), always exits 0, never blocks or reverses the creation, and leaves a specific `apply-issue-dependencies.py:`-prefixed stderr breadcrumb on every path (a number it cannot resolve or link is named in that breadcrumb and reported in the run's final outcome; the remaining numbers are still linked). The POST is `POST /repos/{owner}/{repo}/issues/{n}/dependencies/blocked_by` with the blocker's database `issue_id`; a run in which every registration attempt was refused with the same status collapses to a single breadcrumb naming that status. (2) **Relied-on third-party docs ladder.** The never-assume discipline broadens from "an AC's mechanism" to every third-party behavior the issue *relies on* (load-bearing for the Desired Behavior, an AC, or the Implementation Notes Approach), with a decided fallback ladder — official docs via `WebFetch` → `WebSearch` → ask the user for documentation — terminating either in a `## 🚫 Blocked` vendor-behavior question (when nothing verifies it and no in-repo example proves it) or a flagged `— assumption, confirm before implementing` line citing an in-repo example; incidental third-party mentions stay light. Both the template and the Step 3.5 self-steelman carry the broadened class. (3) **Gated implement offer.** The post-creation implement-comment offer is presented only when the created issue has no `## Dependencies` entries and no `## 🚫 Blocked` section **and** `workflows.devflow` reads as exactly `true` from `.prflow/config.json` (mirroring the cloud gate's fail-closed `.workflows.devflow // false`, read through `config-get.sh` with a direct `python3`/`jq` fallback on classifier denial, compared with bash builtins); a withheld offer prints a one-line reason naming the failed condition (declared dependencies present, blocked decisions present, tier disabled/unconfigured, or config unreadable) instead of posting a comment that fires nothing on a tier-disabled repo. (4) **Step 1 completion-wait.** Step 1's `/prflow:docs-verify --report-only` carries the same synchronous completion-wait discipline as Step 3.6 — its findings report must be complete and captured before the first Step 2 clarification question (and, on a zero-question run, before Step 3 drafting), so users are never interrogated before the code findings that ground the questions exist.

**Three authoring-discipline rules (issue #462).** Class-level prevention of three defect shapes that PR #447 (issue #446) surfaced only as review round-trips. (1) **Value-comparison type-semantics pinning.** An AC or Testing-Strategy assertion that compares a produced value against a literal must state the comparison in the producing surface's **observed-output terms, in the AC's own language**, grounded either by a drafting-time probe cited in the issue (the *verified* arm — which requires the cited probe to exercise the **boundary fixtures the comparison distinguishes**, e.g. a JSON string `"true"` vs. a boolean `true`; a probe silent on the distinguishing axis does not ground it) or by a named implementer *obligation* stating the decided semantics or the exact fixture-and-observed-output command. A probeable fact whose direct probe is classifier-denied routes through the documented `python3 <path>` / `jq` fallback rung before the obligation arm is legal; a specification *choice* axis routes to Step 2's user-question machinery instead. Adjective-only language ("explicit `true`", "reads as exactly `true`") — including the #446 probe-present-but-silent-on-the-axis shape — is named non-conforming. (2) **Convention-matrix reconciliation.** When a Testing Strategy *enumerates* an input-shape or case matrix for a convention-governed surface, the issue carries the full convention matrix or an explicit named-and-justified narrowing, plus a one-line `governing conventions consulted: <sources by path, or "none found; searched <bounded list>">` discharge record whose search is bounded to `CLAUDE.md`, `CONTRIBUTING.md`, and the configured internal-docs path (the consumer prompt extension is the override point). The record is a claim the Step 3.6 auditor independently re-runs — flagging only a governing matrix at a path the line omits — not an attestation to accept (the degraded inline audit arm cannot deliver that verify-not-attest property, which its "degraded" summary marker signals). (3) **Unstated-mechanism-dependency sweep.** Step 3.5's steelman gains a mandatory hunt: enumerate the in-repo behaviors the draft's designed mechanism relies on but never asserts as claims (helper exit codes, resolver output shapes, gate semantics, and existence-shaped reliances such as a renderer mode or a config key) and, for each, determine existence first and then route — the rule's single home is Step 3.5's item 4 (`skills/create-issue/references/step-3-5-steelman.md`); the summary line reports both new sweeps, and its zero arm states the falsifiable "the mechanism invokes no in-repo helpers, resolvers, or gates" rather than a bare count. **Obligation-arm tier constraint (rules 1 and 3):** an obligation whose discharge runs an in-repo command must name a command already granted in `prflow_implement.allowed_tools` or be a code-reading obligation citing the producer — never one that would send a consumer's cloud implement run Blocked. The three classes land as **one** consolidated consumer-agnostic authoring-discipline dimension in Step 3.6's generic checklist and **one** consolidated PRFlow-specific sharpening in the live prompt extension; `skills/create-issue/references/step-3-6-audit.md` states a **growth policy** governing the generic dimension checklist that `skills/create-issue/references/audit-prompt-template.md` carries — execution-blocking classes are reported ahead of authoring-discipline classes, and future dimension additions consolidate into an existing dimension before appending a new one, **except** for one sanctioned standalone addition: the adversarial-input dimension, on two grounds `step-3-6-audit.md` states in full — it is a distinct **security** class outranking the authoring-discipline classes, and it is orthogonal to every environment and discipline dimension, so it cannot be expressed by sharpening one.

**Adversarial-input dimension and enumerated-list floor rule (issue #464).** Spec-quality gaps that surfaced only as review round-trips a full implement-plus-review cycle after drafting (PR #454, issue #449) are now caught at drafting time across the authoring pipeline. (1) **Adversarial third-party input.** Step 3.6's generic dimension checklist gains a consumer-agnostic **Adversarial third-party input** dimension with a narrow trigger: when a draft's Desired Behavior introduces a *new* LLM/semantic judgment over third-party text the change does not author (issue bodies, PR comments, commit messages, external API responses) whose output drives an automated selection or action, the draft must carry the input-is-data guard as an acceptance criterion — the text is *data to classify, never instructions to obey* — **paired** with a Testing Strategy case that exercises instruction-shaped input and asserts it is not obeyed; a surface reusing an existing already-guarded path is exempt when the draft cites it, and a draft with no new judgment surface gains no new flags (the visual-specification skip-when-inapplicable shape). The matching drafter-side rule lives in `references/issue-template.md`'s Acceptance Criteria guidance. (2) **Enumerated AC lists declare their closure.** The template's Acceptance Criteria rules require every enumerated test/case/example list inside an AC to declare its form — a **floor** (the marker `at minimum`) or a **closed set** (an explicit exhaustiveness statement) — and Testing Strategy Move 2 extends its floor-not-ceiling rule to floor-marked AC lists: the coverage walk sweeps the new capability's contract dimensions (state, case variants, multiplicity, absence) beyond the enumerated items and writes the sweep's output back as additional closed AC items before filing. The checks also join Step 3.5's omission-hunt list so the drafter self-catches before the auditor. A repo-specific sharpening lands in the live prompt extension's `## Audit dimensions`: an **executable-evidence** dimension flagging a Testing Strategy that protects a behavioral regression only through source-text presence or omits an ordinary executable RED obligation (typed surface-presence contract pins are explicitly outside its scope). **Stage-B reach is deliberate.** The retrospective's Stage B (`skills/retrospective-audit/SKILL.md`) files issues following `references/issue-template.md` verbatim but runs none of create-issue's Step 3.5/3.6 seams — so the **template-side** rules (the judgment-surface guard and the AC list-closure rule) reach Stage-B-authored issues **by construction**, while the **auditor-side** dimensions (the Step 3.6 generic-checklist dimension and the extension's executable-evidence dimension) do not. That auditor-side non-coverage is a **deliberate deferral**: Stage-B issues are human-reviewed before filing and re-derived by the implement run's Phase 1, so extending the audit seams into Stage B is a separate change if evidence shows leakage.

**Hardening against the four dominant review-REJECT seed classes (issue #467).** Class-level prevention of the four recurring seed classes behind create-issue-authored issues that later drew review REJECTs, each landing as a consumer-generic rule in the skill and `references/issue-template.md` with PRFlow-specific sharpening in the live prompt extension. (A) **Universal-claim grounding.** The template's Acceptance Criteria guidance, Step 3.5's steelman, and Step 3.6's *Load-bearing assumptions* dimension all gain a universal-quantifier rule: every "never/always/each/every/all/cannot" the body asserts about the system under change (outside `## 🚫 Blocked`) is grounded one of three decided ways — pinned per-arm/per-element (an accepted-loss/suppression claim pinned by a fixture in which the suppressed input is *present*), scoped to the mechanism's supported form, or removed — with only mandated-verbatim boilerplate and rule-text-shipped-as-artifact-content exempt (an AC or Desired-Behavior sentence is never exempt however imperative), and a detector/guard coverage claim additionally carrying a planted-defect positive-control obligation. (B) **Executed enumeration.** An in-repo occurrence count or coupled-site/mirror-site list is a premise class: grounded either by an **executed whitespace-normalized search** cited as a `Verified:` bullet with its command and hit list (where the tier grants one), or — for a count not derivable from a text search, or a denied search — by the specific evidence records consulted record-by-record; never a recall count. Step 3.5 adds a paired **AC mutual-consistency** check (no AC forbids a surface another AC's discharge must touch). (C) **Verification depth.** A "code does X" premise is verified with the enclosing gates/conditionals and their defaults on the path to X (a claim holding only under a non-default configuration states that precondition inside the claim); Step 3.5's unstated-mechanism-dependency sweep extends to **stated-but-unbound inputs** (a mechanism input named only by role is bound to a named referent with a cited code reference, or carried as an implementer-obligation AC); and a **trust-boundary closure** rule requires an AC protecting executable artifacts to define the protected set over the transitive source/exec/import closure of its entry points (or state the residual unprotected surface). (D) **New-parser matrix.** Testing Strategy Move 2a now fires on *introduction*, not only narrowing: an issue introducing a **reader of input the repo does not itself produce** (historical records, user/reporter-controlled text, an external structured format, agent/human-mutable markdown) enumerates that input's malformed/boundary shape matrix with at least one production-realistic fixture, and a blanket testing-scope waiver is non-conforming. The best-effort-parser convention is widened at its three lockstep sites (`CLAUDE.md` gotcha, implement Phase 2.4, review-and-fix fix-delta gate) to name parsers over agent/human-mutable markdown and readers of new external structured formats as governed surfaces — each under the malformed-shape matrix appropriate to *its* input type, with the six-shape set staying the config-JSON matrix — and the extension's authoring-discipline dimension is sharpened to flag a matrix narrowed below the governing matrix appropriate to the surface's input type.

**Code exploration, yes, just not the `code-explorer` subagent.** `/prflow:create-issue` *does* explore the codebase, that's precisely what lets it ask deep, well-grounded questions instead of generic ones. Step 1's `/prflow:docs-verify --report-only` surfaces current behavior and the **relevant files**, and the Step 2 clarification reads those (and adjacent code) to find **similar existing patterns and features** and understand **how the new feature would fit**: which is exactly how it surfaces real implementation forks ("where the codebase admits more than one way to build it") and recommends the best option. What it does **not** do is dispatch the heavyweight `prflow:code-explorer` subagent; the exploration is done inline by the orchestrator. The "do not re-explore the whole codebase" rule in Step 3 is a *draft-time* discipline, by then it works from what it already learned, doing only targeted confirming reads. The dedicated `code-explorer` deep dive is reserved for `/prflow:implement` **Phase 2.1**, where the goal shifts from *what/why* to *how*. The pipeline dispatches subagents at exactly two seams, and neither is a `code-explorer`. Step 1 dispatches its docs-verification **peers** (issue #749) — one on the shallow arm, two in parallel on the deep arm — so the survey's tool output stays in a peer's context and the orchestrator pays only the returned report. Step 3.6 dispatches the fresh-context **auditor** (issue #443) — the exact opposite of an exploration pass: deliberately information-starved (it sees only the rendered draft, never the drafting context), its whole value is *not* having explored the way the drafter did. In between, question-grounding clarification and drafting stay inline.

---

## 12. Deep dive: the retrospective loop

> **This is PRFlow's "it learns" story, the strongest differentiator for a keynote.** It is an **evaluator/optimizer** self-improvement loop for the `/prflow:implement` automation.

**The idea.** Every bot-authored PR leaves an evidence trail: review comments, post-bot human commits, CI signals, the workpad's final state, and the bot's own `## Devflow Reflection` friction notes. Once a week, `/prflow:retrospective-weekly` reads the accumulated trail, finds **patterns that recur**, and opens a **human-reviewed** PR proposing the smallest change that would prevent the next occurrence, a CLAUDE.md tweak, a skill rewrite, a missing doc, a new lint rule, a tightened issue template. Humans approve or reject.

**Detection (how a PR is selected).** `lib/scan.sh` selects a merged PR for retrospection via a **union predicate** — a PR qualifies when **any** of these holds, deduplicated by number:
- **(a) the reserved `PRFlow` provenance label, or its superseded `DevFlow` spelling** — PRFlow stamps the literal `PRFlow` label on every issue and PR it creates, and every selector accepts BOTH spellings so no pre-rename history is dropped (issue #1003; the API-side filter uses one `--search "… label:PRFlow,DevFlow"` qualifier, because `gh pr list --label A --label B` is an AND and would silently return zero candidates) (`/prflow:create-issue`, `/prflow:implement` at PR create, Stage B). The label is *created* via the idempotent best-effort `scripts/ensure-label.sh` (`/prflow:init` pre-creates the label at setup so it exists from day one) and *applied* via the shared best-effort `scripts/apply-labels.sh`. Both helpers transport through repo-scoped REST `gh api` calls — `POST /repos/{owner}/{repo}/labels` for creation and `POST /repos/{owner}/{repo}/issues/{n}/labels` for application (a PR is an issue, so the same endpoint applies labels to both) — rather than the GraphQL-resolving porcelain (`gh label create`, `gh issue edit`/`gh pr edit --add-label`) they replaced. The porcelain's org-scoped GraphQL repo resolution needs `read:org`, which repo-scoped tokens (GitHub App installation tokens, fine-grained `repo`-only PATs) lack, so under those tokens the porcelain silently dropped the label; the REST path needs only the `repo` scope. The `{owner}`/`{repo}` placeholders are what address the repository on **both** tiers — `gh` fills them from the git remote, so a helper or skill body that could run outside Actions never interpolates `$GITHUB_REPOSITORY` (empty there, collapsing the path to `repos//…` while `gh` writes the 404 body to stdout for a best-effort capture to mistake for a result — issue #664). Only Actions-only surfaces (`.github/workflows/`, `.github/actions/`), where a checkout-less job has no remote to resolve from, address the repo through the environment. `lib/test/lint-gh-api-repo-path.py` enforces the split over the tracked-and-unignored tree, minus those two Actions-only prefixes and minus the corpora that quote the rule's own text (`lib/test/`, `docs/`, `CHANGELOG.md`, `.changeset/`, `.prflow/logs/`, `.prflow/learnings/`) and minus `.claude/worktrees/`, whose sibling checkouts belong to another branch and which this scanner's *working-tree* population would otherwise sweep in (issue #711) — that scanner's module docstring is the authoritative exclusion list and gives each entry's reason. Each helper leaves a specific stderr breadcrumb on `gh` failure — and since issue #455 `apply-labels.sh` breadcrumbs on **success** too (`devflow: applied label(s) '…' to #N`), so a caller reading the tool result can tell the outcomes apart: applied → the success line, API failure → the warning line, a caller arg-slip (a missing/blank/non-numeric number, or an empty label list — the #480 review) → its own warning line naming the slip, and **refused by the permission matcher → no output at all** (a denied command prints nothing, so without the success line "applied" and "denied" would be byte-identical). `apply-labels.sh` **always exits 0 and has no silent path**, which is what makes that no-output inference sound; `ensure-label.sh` likewise always exits 0 and has no silent path — a missing/empty `<name>` emits its own arg-slip warning to stderr and still exits 0, so a harness refusal stays the only silent outcome. Its label list is derived with bash builtins only — never a `tr`/`sed`/`grep` pipeline — because a missing PATH tool would empty the set silently and a caller that reads silence as a denial would then record one that never happened. This path is **author- and branch-agnostic**, so it works in any repo with **zero branch-naming configuration**. **Cloud implement-tier coupling (issue #455).** On the read-write cloud `/prflow:implement` tier, actually *applying* these labels requires two halves that ship on **independently-updated artifacts** and must be upgraded together: the `devflow-implement.yml` workflow must grant `apply-labels.sh`/`ensure-label.sh` in the explicit vendored-literal leading-token form the implement-probe table proved PERMITTED (this half arrives by **re-running `install.sh`**), *and* the skill must emit permitted command *shapes* at all four label call sites (Phase 3.1's provenance apply, Phase 4.0/4.0.5's deferred applies, Phase 4.1's docs apply) — single leading-token agent-level calls, never a `for`/piped-`while read` loop or a `VAR="$(…)"` capture wrapping a label helper (this half arrives by **bumping `prflow_version`**). Take only one half and the applies are **silently denied** — the PR and filed deferred issues carry none of the configured labels and the retrospective's label-first detection arm goes dark on cloud-authored PRs (see [`install.md`](install.md) → *the cloud implement-tier label grants are a TWO-halves upgrade*); **The same two-halves coupling covers the Phase 4.0.5 deferral-discovery helper (issue #555):** `devflow-implement.yml` must grant `Bash(.prflow/vendor/prflow/scripts/discover-deferral-manifests.py:*)` (re-run `install.sh`) *and* the §4.0.5 fence must invoke that helper instead of the old multi-root `find` (bump `prflow_version`). Unlike the label class, a skew here fails **loudly**: with only the skill half the discovery statement is refused and produces no output, which the reader routes to its fail-closed `discovery=[]` exit — a `dropped-failed` reflection and nothing filed, rather than the masked-exit-status silent loss the `find` shape produced;
- **(b) a watched author that closes an issue** — a watched-author PR with a non-empty `closingIssuesReferences`. This is the branch-naming-independent fallback that makes detection work even when the label step was skipped (e.g. PRFlow's own `issue-<N>-<slug>` branches, which match no prefix);
- **(c) the configured `implementation_branch_prefix`** — *only* when it is set non-empty (an empty/unset prefix excludes nothing and never degrades to a match-all glob).

The label (a) and closes-issue (b) paths mean the loop can no longer silently no-op when an adopter's bot uses an unrecognized branch prefix.

If any candidate-source fetch or jq-reshape hard-fails while assembling the weekly candidate set (a `gh pr list` error or a reshape failure on the provenance-label or watched-author batch), the scan sets a degraded flag and **exits non-zero with an `::error::` breadcrumb naming the gh/jq cause** rather than substituting an empty batch and reporting a partial set as "0 new PRs to retrospect" — a partial GitHub outage must not masquerade as a clean no-op (the same fail-loud posture the idempotency read path takes below). In the operator-driven `--prs` ad-hoc mode, a per-PR predicate *evaluation failure* (the jq `select` aborting, e.g. on a non-array `labels` shape) is reported with a distinct `predicate evaluation failed` breadcrumb carrying the jq diagnostic, kept separate from the `matches no retrospection path` breadcrumb that means the PR was evaluated and legitimately excluded.

**The workpad lives on the issue.** `lib/fetch-pr-context.sh` reads the `<!-- prflow:workpad -->` comment from the **linked issue's** comments (where `/prflow:implement` writes it), not the PR conversation thread. From it the bundle derives `workpad_final_status` (stripping only a leading canonical 🚀/🎉/👎/💥/🛑 glyph — by the known glyph set, kept in sync with `workpad.py`'s `_STATUS_GLYPHS` — so a multi-word status such as `In Progress` survives intact) and a `reflections[]` array of the `## Devflow Reflection` bullets. The bullets are now grouped by kind under `### ⚠️ Action required` / `### 💡 Improvements` / `### ℹ️ Notes` sub-headings (see the workpad-sections note above); the parser captures every kind bullet — glyph, and the bold-label prefix on the labeled kinds (a glyph-only `note`/`improvement` bullet is captured identically; useful signal for the retrospective LLM) — excludes the `### ` sub-headings, and parses a legacy flat block identically, so the `reflections[]` array's **count and contents are unchanged**. Alongside it the parser now emits a top-level `reflections_friction_count` — how many of those bullets are **friction** (every reflection kind EXCEPT the informational `note`: an `ℹ️` bullet under `### ℹ️ Notes` is exempt, but an `issue-accuracy` `📝` bullet sharing that section, any `### ⚠️ Action required` / `### 💡 Improvements` bullet, and any bullet under an unrecognized or missing heading all fail closed to friction). The `### ℹ️ Notes` heading literal and the `ℹ️`/`📝` glyphs are a coupled invariant hard-copied from `workpad.py`'s `_REFLECTION_SUBSECTIONS`/`_REFLECTION_KINDS` (pinned by `lib/test/run.sh`). `lib/cheap-gate.jq` forces LLM analysis of any run that left **at least one friction reflection** — a run whose only reflections are informational `note`-kind bullets is treated as clean (the note is still recorded verbatim by `lib/clean-entry.jq` into the clean entry's `reflections` field, not dropped) — that self-reported friction is precisely what the loop exists to learn from. The gate **fails closed** when `reflections_friction_count` is absent (an older bundle, or a bundle whose emission failed): it falls back to the legacy "any reflection trips" count, and `fetch-pr-context.sh` substitutes a friction sentinel when the reflection block is present but unparseable, so a missing or broken signal over-analyzes rather than silently skipping a friction PR. The issue-sourced `workpad_final_status` makes a non-`Complete` run — `Blocked`, or a stall-backstop `Failed` (💥) — gate correctly instead of being mis-read as clean (`cheap-gate.jq`'s clean condition is `workpad_final_status == "Complete"`, so a dead run gates non-clean with reason `workpad status not Complete`).

**Absent-workpad fail-closed (issue #626).** The cheap gate's clean set is `workpad_final_status == "Complete"` **only** — an *absent* workpad no longer launders past analysis. `fetch-pr-context.sh` emits a non-empty sentinel on each absent path — `NoIssue` (no linked issue resolved) and `Absent` (the issue resolved but carried no `<!-- prflow:workpad -->` comment), mirroring the present-but-corrupt `Unparsed` sentinel — each with a `::warning::` breadcrumb, so all four producer paths emit a non-empty value; a leaked `""`/`null` still gates non-clean at the gate with the distinct reason `workpad absent or status unknown` (defense-in-depth), while any non-empty non-`Complete` word keeps `workpad status not Complete`. The bundle also gains a top-level boolean `pr_devflow_provenance` — `true` iff the `PRFlow` provenance label (or its superseded `DevFlow` spelling) is on the PR **or** the resolved linked issue. A suite-driven helper `lib/dispatch-disposition.jq` then makes a **mechanical pre-dispatch disposition** with **zero LLM cost**: a non-clean bundle is *skipped* only when the gate reason is a workpad reason, the status is a sentinel (`Absent`/`NoIssue`), and provenance is `false` (a foreign, non-PRFlow PR whose only non-clean signal is a missing workpad audit trail — note `Absent` means the linked issue *did* resolve but carried no workpad comment, so the skip is not restricted to issueless PRs) — otherwise it is *dispatched* to Stage A exactly as today, so a bundle non-clean on any non-workpad signal (REJECT, an unreadable review-verdict signal, CI failure, post-bot commits, review comments) is always analyzed. Stage A analyzes a dispatched sentinel bundle under a **workpad-absent analysis rule** (a PRFlow run that lost its audit trail is analyzed from the remaining evidence, the absence recorded as friction, default verdict `imperfect`) and re-keys its two defined skips (interim, `Cancelled`) to a top-level `"skip"` key the orchestrator recognizes **by that key alone**, distinct from a genuine `"error"`. Skips are recorded as one-line report records (never silent); a `kind: "skip"` marker entry is appended for the **permanently-terminal** skips (the mechanical no-provenance skip and `Cancelled`) so the processed-PRs filter sees them handled, while the **transient** interim skip appends no marker and is re-scanned inside the 7-day lookback.

**Review-verdict arm — the durable-review union (issue #895).** The cheap gate's first (most-blocking) arm reads `signals.review_reject_outstanding`, `true` when a review REJECT has not been superseded by a later APPROVE; the gate reports the reason `outstanding /review REJECT` when it fires. That signal is derived by `fetch-pr-context.sh` from the **union of two sources**: the PR conversation comments (the historical scrape) *and* the durable bot PR reviews already fetched into `pr_reviews`. Reading comments alone failed open — when a `/review` run leaves no progress comment its whole verdict lives only in the `gh pr review` body, so a PR that merged over an un-cleared REJECT read as clean and was silently dropped from analysis. Both legs recognize the verdict heading with the **same grammar** (1–6 `#`, an optional `/review —` wrapper, `Verdict:`, an optional `**` bold marker, then `APPROVE`/`REJECT`, case-insensitive), and the verdict token always comes from the body — never from a review's state. A review contributes an entry when its state is anything other than `PENDING` (a plain equality test) and its body carries a heading; a `DISMISSED` review still contributes (the retrospective deliberately inverts the merge gate's dismissal rule, because a merge over an overridden REJECT is what the loop exists to study — a REJECT a later APPROVE cleared is handled by that APPROVE ordering after it). The union entries carry `{verdict, createdAt, source}` where `source` is `pr_comment` or `pr_review`; timestamp-less entries can only raise non-cleanliness, never lower it. Separately, the gate now **fails closed** on an unreadable review-verdict signal: when `.signals` is not a JSON object, or `review_reject_outstanding` is absent/null/non-boolean (a truthy JSON string like `"false"` must not read as an outstanding REJECT), the gate reports the distinct reason `review-verdict signal unreadable`, evaluated **before** every other arm so the unreadability is named rather than masked by the workpad-absent reason a non-object `.signals` would otherwise trip. That reason is neither workpad reason literal, so `dispatch-disposition.jq` routes such a bundle to `dispatch` (and it now guards its own `.signals` index against a non-object shape). Note the sibling framing above: the clean set being `workpad_final_status == "Complete"` **only** scopes the *workpad* axis — the review-verdict, CI, post-bot-commit, review-comment, and friction-reflection arms are co-equal siblings, each able to gate a run non-clean on its own.

**The LLM/heuristic split (a key efficiency claim).** Deterministic scripts handle *all* scanning, fetching, signal computation, gating, pattern math, and git/PR/issue mechanics. The LLM is invoked at **only two genuine-judgment points**:
- **Stage A** (`/prflow:retrospective`), a per-PR retrospective, **only for PRs that fail a mechanical "clean gate."** Clean PRs are processed deterministically at **zero LLM cost.**
- **Stage B** (`/prflow:retrospective-audit`), per-pattern issue-spec drafting.

```
scan.sh
  → fetch-pr-context.sh  (per PR)
    → cheap-gate.jq
      [clean]  → clean-entry.jq   (deterministic, no LLM)
      [not clean] → Stage A: retrospective subagents (≤3–4 concurrent)
  → materialize-retrospectives.sh
  → pattern-state.sh  (migrate v1→v2→v3 + reconcile lifecycle vs live issue state)
  → actionable-patterns.sh  (uses compute-patterns.jq)
    → Stage B: retrospective-audit subagents (return a ranked findings[] array)
      → select-findings.sh (compose/alias/rank/cap: which findings become filings)
      → meta-issue.sh  (one issue per selected finding + overrides.json lifecycle record)
  → build-experiment-records.py  (best-effort; joins cost ↔ outcome per merged PR)
  → open-state-pr.sh
  → post-status.sh
```

**Stage A** classifies each non-clean PR into a **fixed category vocabulary** (never coins new slugs): `doc-accuracy`, `fabricated-claim`, `outstanding-reject`, `lenient-verdict`, `deferred-verification`, `unmet-acceptance-criteria`, `incomplete-edit`, `convention-violation`, `unverified-assumption`, `issue-quality`, `tooling-gap`, `other`. Categories drive pattern detection.

**Stage B** re-derives the root cause from primary sources (it does *not* trust Stage A's summary), does a counterfactual analysis (false positives / over-broad application), and returns **one JSON object carrying a ranked `findings` array of one to three sub-patterns** — each with its own `subslug`, `title`, `body`, `evidence_prs`, and `rationale`, dominant first (issue #893). It reads each occurrence's own `summary`/`descriptors`/`suggested_interventions` (now carried on the pattern object, handed to it by path on disk) to cluster the sub-patterns, and it makes **no** edits and runs **no** worktree. `lib/select-findings.sh` owns which findings become filings **on this path** (the bare-`{title, body}` coexistence path below never reaches it and derives its own cap verdict): it composes each finding's opaque `<category>-<subslug>` filing key through the #891 composer, aliases a churned subslug onto an existing lifecycle record of the same category (equal **subslug** token set — the signature is taken over the subslug, never the composed key, so a subslug repeating one of its category's own tokens stays distinct instead of merging onto that category's record), re-checks the final key against the `[A-Za-z0-9_-]+` grammar after aliasing, ranks by descending evidence-PR count and truncates to the top three — naming the pattern and the dropped count in the run report — and asks the shipped `devflow_filing_cap_verdict` for each finding's cap decision. The orchestrator then files **one GitHub issue per selected finding** via `meta-issue.sh` (stamping the `PRFlow` and `Retrospective` labels and recording a `filed` `overrides.json` lifecycle record keyed by the finding's filing key — see the lifecycle subsection below). A human triages each filed issue and runs it through the normal `/prflow:implement` → review pipeline. A deployed Stage B subagent that still returns a bare `{title, body}` is filed under the bare category key, the coexistence path.

**Propose, don't dispose (a self-governance safeguard).** Stage B never edits the repo. Each selected finding of an actionable pattern — whatever surface its fix would touch (a skill, an agent, `lib/`, `scripts/`, docs, CLAUDE.md, config, or application code) — becomes **one GitHub issue** filed via `meta-issue.sh`, carrying the `PRFlow` and `Retrospective` labels and a re-derived spec of create-issue quality. A human triages it and runs it through the same `/prflow:implement` → review pipeline every other change gets, so loop-proposed engine changes get the same review — not a weaker autonomous-edit path. (Earlier versions auto-opened intervention PRs on a fixed audit branch for "safe" surfaces and only filed issues for engine files; that split, its worktrees, and the old audit retrospection kind are all retired — #152.)

**Recurring intervention targets (report-only, issue #520).** The weekly report carries a **Recurring intervention targets** section that surfaces the files/areas the accumulated retrospectives repeatedly point at, independent of the pattern-tag clustering above. `lib/recurring-targets.sh` (a thin arg-taking wrapper over `lib/recurring-targets.jq`, resolving `jq` via `resolve-jq.sh` and emitting `[]` for an empty/absent store) reads `.prflow/learnings/retrospectives.jsonl`, groups every entry's `suggested_interventions[].candidate_targets[]` by **exact target path**, and emits `{target, pr_count, prs, representative_summary}` for each target named in **≥2 distinct PRs**, sorted by descending `pr_count` then target ascending (both `.suggested_interventions` and `.candidate_targets` are `// []`-guarded; non-string targets are dropped via `strings` and empty-string targets by the separate `select(. != "")`; the intervention `.summary` is likewise `strings`-guarded so `representative_summary` is always a string — a wrong-typed one would otherwise abort the consumer's `gsub` render). Step 9 of `/prflow:retrospective-weekly` wires that output into the report summary JSON under the `recurring_targets` key, and `lib/render-report.sh` renders it under the omit-when-empty idiom (no section when nothing recurs). This view is **purely diagnostic**: it files no issue and writes no `overrides.json` dismissal state, so it surfaces recurring targets **regardless of category cooldown/dismissal** — a target a human has dismissed as a pattern still shows here as long as it keeps recurring. It is a **local/interactive retrospective-tier** feature only — no cloud-tier change.

**The pattern lifecycle (issues #788, #891).** `.prflow/learnings/overrides.json` is `schema_version: 3` with two top-level maps: **`patterns{}`**, the *machine-owned* lifecycle map, and **`dismissed{}`**, the *human-owned* durable escape valve. **Each lifecycle record now carries an explicit `category` string field and its map KEY is an opaque filing key** (issue #891) — the key is no longer required to equal a category slug, so a single attribution category can be spread across several sub-pattern records under distinct keys. Every consumer that used to re-derive the category from the key now reads the stored `category` field instead: status derivation (`lib/compute-patterns.jq`), the per-category filing cap, and the run report. The **cooldown lookup is the deliberate exception**: `lib/actionable-patterns.sh` keys it on the entry's own opaque filing key and never reads the stored `category`, so cooldown suppresses re-filing per record, not per category — which is what lets several sub-pattern records under one category cool down independently. `lib/pattern-state.sh` (invoked in Step 6, before `actionable-patterns.sh`) migrates an older file forward on read — v1→v2 converts only the loop's own former `dismissed` entries into lifecycle records and preserves every hand-written key, and **v2→v3 stamps each record's `category` field** — then **reconciles** each pattern's `filed`/`fixed`/`declined` state against the live state of **every** meta-issue on its lifecycle record, deriving the record state from the resulting entry set: an open issue → `filed` (`fixed_at` cleared); closed `COMPLETED` → `fixed`; closed `NOT_PLANNED`/`DUPLICATE` → `declined`; every closed transition stamps `fixed_at` from the issue's `closedAt`. `lib/compute-patterns.jq` then derives each pattern's status through six ordered arms — **`dismissed` → `regressed` → `declined` → `filed` → `fixed` → `open`** — with the lifecycle record's `fixed_at` taking precedence over legacy audit rows, so a pattern whose issue was closed but that recurs afterward becomes `regressed` and re-enters the eligible pool. Lifecycle-derived suppression therefore lasts exactly as long as the fix it waits on; only a hand-written `dismissed{}` entry suppresses permanently.

**Opaque filing keys (issue #891).** Because the record key no longer has to be a bare category slug, `lib/compose-filing-key.sh` composes a **collision-resistant opaque filing key** from a `category` argument and a `subslug` argument: the result is always `≤40` chars and matches `[a-z0-9-]+`, and when the naïve `category-subslug` composition would exceed 40 chars it is truncated and given a `python3`/`hashlib` sha256 digest suffix (width 8) so distinct inputs stay distinct. Both `lib/compute-patterns.jq` and `lib/compose-filing-key.sh` resolve their `slugify` function from the shared **`lib/slugify.jq`** module (included by each), so slug normalization is single-sourced across the jq derivation and the shell composer. `lib/meta-issue.sh` takes a required `--category` argument (slug grammar `[a-z0-9-]+`) and records it on the `filed` lifecycle entry it appends.

The **machine writer** of `overrides.json` is `meta-issue.sh` (it appends a number-keyed `filed` lifecycle entry per filing) and `pattern-state.sh` (migrate + reconcile). No **filing** path writes a `dismissed{}` entry: the filing and first-run-stub paths only ensure the map exists (`meta-issue.sh`'s lifecycle write carries a `.dismissed = (.dismissed // {})`, and each writer's first-run stub seeds an empty one). The only machine path that alters entries is the one-time v1→v2 migration: it converts the loop's own former entries (`dismissed_by: retrospective-weekly`) into lifecycle records — **removing** them from the map in the process — and preserves every hand-written key verbatim. That map is the one **durable off-switch**: a maintainer adds a slug key there by hand to permanently stop a pattern the lifecycle would otherwise re-raise, and a pattern closed `NOT_PLANNED` that keeps recurring is re-raised (as `declined` → `regressed`) and named in the run report alongside this off-switch, so the won't-fix decision is re-raised visibly rather than overridden silently.

**Run-report structure.** `lib/render-report.sh` (`devflow_render_report`) is the **source of truth for the report's section list** — read it rather than transcribing the sections here, since a hand-copied enumeration of a mutable set rots. Beyond the summary counts, analyzed-PR and pattern views, and the recurring-targets section above, issue #894 added surfaces that answer "did anything regress?", "was any evidence truncated?" and "how full is the filing queue?" outright: a **Regressed patterns** section lists every pattern whose derived status is `regressed` (a cumulative `newest occurrence > last fix` state over the whole history, not a this-run event, derived from the same `.patterns` view), a **Stage B evidence truncated by the audit bundle cap** section lists every *dispatched* pattern for which Stage B was delivered fewer occurrence bundles than the pattern has occurrences (a pattern excluded by the no-dispatch floor is reported through its blocker instead, never as truncated evidence), and a **Filing queue** line reports the aggregate `filing queue: N/M open` state (N = open filed meta-issue entries via `devflow_open_filed_total`, M = resolved `max_open_issues`, ` — at capacity` when both are established and N ≥ M, followed by a note that the ceiling is not absolute — a `regressed` pattern bypasses it, so a run can file while at capacity). The queue line reports state, not blame — it deliberately does not say "blocked" and does not read the cap token, and an unestablished count renders `unavailable`, never `0`.

**Filing back-pressure & eligibility config.** `min_occurrences` (default 2) is the occurrence-count gate — a `regressed` pattern always bypasses it. `cooldown_days` (default 3) skips re-filing a pattern whose youngest open filed issue is younger than that. A set of cap keys bounds filing volume: `max_issues_per_run` (default 3), `max_open_issues` (default 10, counted from `filed` lifecycle entries across all records; a `regressed` pattern bypasses this ceiling), and `max_open_per_category` (default 2, counted by `lib/filing-decisions.sh`'s `devflow_open_filed_for_category`, which sums the `filed` meta-issue count across **every** record whose stored `category` matches — not just the single record keyed by this pattern's filing key, issue #891). Separately, `audit_bundle_cap` (default 10) bounds the **Stage B fetch, not the filing volume** (issue #894): for each actionable pattern, Step 8a fetches context bundles for at most this many occurrence PRs, most-recent-first by occurrence timestamp, and `lib/audit-bundle-selection.sh` owns the cap validation, the most-recent-N selection, and the no-dispatch floor. When the cap (or a fetch failure) leaves a *dispatched* pattern with fewer bundles than it has occurrences, the run records a truncation entry (pattern tag, delivered, total, selected) that the report surfaces under a dedicated section. When **no** bundle is delivered at all — or the selection itself fails — `devflow_audit_dispatch_ok` clears that pattern's `dispatch` carrier and Step 8a records a blocker: it is dispatched to no Stage B subagent and files nothing, rather than having Stage B re-derive a root cause from metadata alone and file an evidence-free issue. A `0`/negative cap is rejected because a bundle cap of zero would starve Stage B of all evidence. A liveness `::warning::` fires when nothing is eligible while a pattern has occurred at/above `min_occurrences` and is currently suppressed (`dismissed`/`declined`/`fixed`), so a silently-exhausted loop is caught on the run it breaks. `occurrence_count` is cumulative, so this reads as "has occurred", not "recurs": a suppressed pattern that genuinely recurred would derive `regressed` and be eligible.

**Data (all in git, append-only ground truth):**
- `.prflow/learnings/retrospectives.jsonl`, one JSON object per processed PR (every record carries a `pr` field).
- `.prflow/learnings/overrides.json`, the two-map lifecycle state (`schema_version: 3`): a machine-owned `patterns{}` lifecycle map (each record carries an explicit `category` field under an opaque filing key, issue #891) and a human-owned `dismissed{}` escape valve (see the lifecycle subsection above). Unlike the append-only stores, this file is rewritten in place by `pattern-state.sh`/`meta-issue.sh` and staged into the state PR.
- `.prflow/learnings/experiment-records.jsonl`, one JSON object per **merged** PR joining that PR's run cost to its review outcome (written by `scripts/build-experiment-records.py`, above; unlike the two stores above it is **rewritten**, not appended — a re-run replaces a PR's line, keyed by PR number). See [`docs/efficiency-trace.md`](efficiency-trace.md) for the schema.
- Pattern status (`dismissed`/`regressed`/`declined`/`filed`/`fixed`/`open`) is computed **on demand** by `lib/compute-patterns.jq` from the retrospectives corpus and the reconciled `overrides.json` lifecycle records.

All three files are staged by `lib/open-state-pr.sh` and land on the human-merged state PR, so `main` is clean entering Stage B. Because the corpus is **tracked and published**, `lib/materialize-retrospectives.sh` redacts operator home-directory prefixes (`/Users/<name>/`, `/home/<name>/`, `<drive>:\Users\<name>\`) to `~` on the merge write path before records are committed — a privacy backstop that preserves `/home/runner` CI-runner paths and every other string, and **fails closed** (aborts rather than commit an unredacted corpus if the redaction pass fails over valid JSONL). The primary guard is still the no-owner-identifying-data rule (see `SECURITY.md`), not this transform.

**Idempotent:** re-running processes only PRs not already recorded — `lib/scan.sh` reads `retrospectives.jsonl` from the base branch via the GitHub Contents API and subtracts the already-processed PR numbers from the candidate set. A `404` is the legitimate first-run case (the file isn't on the base branch yet) and leaves the processed set empty. Any *other* failure to decode the processed set under `HTTP 200` — an unparseable Contents-API envelope, a base64 decode miss, a `jq` parse failure, a body carrying neither inline content nor a `download_url`, a failed `download_url` fetch, or content that parses but yields zero `pr` records — **fails loud (exit 1) with a specific breadcrumb** rather than collapsing the processed set to empty. A silent collapse would re-queue the entire backlog and create duplicate retrospectives, so genuinely-corrupt state aborts the scan instead. The same guard (`_decode_existing`) covers both the inline `≤ 1 MB` content transport and the `> 1 MB` `download_url` fallback. **Never auto-merges and never auto-implements**: the maintainer merges the state PR manually and triages each filed issue manually — the loop never starts an implement run on its own filings.

---

## 13. The Scope-Acknowledged Findings contract

A structured handoff that prevents a deliberately-deferred Critical finding from being re-raised as a fresh REJECT by the next review run. The handoff, in order:

1. **`/prflow:review-and-fix` Loop Exit** runs a **widens-surface guard** (if the PR diff overlaps the deferred finding's file within ±10 lines, the deferral is disqualified, catches "refactor around a pre-existing bug then defer it"), and emits a **run-scoped** deferrals manifest.
2. **`/prflow:implement` Phase 4.0.5** discovers those run-scoped manifests with `scripts/discover-deferral-manifests.py` (per-root, status-bearing — see Phase 4.0.5 above; a failed or refused discovery files nothing and is recorded, never read as "no deferrals"), merges them into one slug-level aggregate, and files **one follow-up issue per source file** (with a `PR #<N>` cross-link).
3. **`/prflow:pr-description`** renders a Scope-Acknowledged Findings block in the PR body (a human-readable table + a hidden machine payload).
4. **`/prflow:review` Phase 4.0** validates each deferral against **three guards** and demotes matched findings to **Informational** before computing the verdict.

**The three guards (any failure rejects the deferral):** **trusted filer** (PR author in `devflow.allowed_bots`); **mutual cross-link** (the follow-up issue exists, is open, and references the current PR); **widens surface** (re-checked at review time). The contract is repo-agnostic.

**Settled-by-disclosure foreclosure (issue #621).** A non-blocking finding whose deliverable is an **already-shipped disclosure** — one below the run's `verdict_severity_threshold` and not a REJECT driver — can be recorded once with `skip_category: "settled-by-disclosure"` and a verifiable disclosure citation `{path, phrase}`, instead of being re-litigated every pass. A foreclosure files **no** follow-up issue (the disclosure is the deliverable), so it rides the manifest → PR-body block through the same implement-driven writers, and `match-deferrals.py` honors it through a **disclosure-verification guard** that **replaces the mutual-cross-link guard for this category only**: the guard passes when the PR's cached diff parsed to ≥1 hunk, the `disclosure.path` resolves to a file under the repo root, the `disclosure.phrase` is found in that file (whitespace-normalized), and `disclosure.path` is **not** a file the PR's own diff touched (a PR-authored disclosure never self-forecloses). It fails closed with reason `disclosure-unverified` (plus a `detail` naming the failed arm) on every degraded operand, so a disclosure that later drifts (reworded/moved/deleted) flips standing foreclosures back to a full-strength re-raise — accepted-and-surfaced, not mitigated. A honored foreclosure demotes a matched finding to Informational **only below the consuming run's `verdict_severity_threshold`** (there is no tracked follow-up behind it), and the honored report quotes the disclosure phrase for the human merge gate. **Disclosed limitations:** (1) cross-pass demotion applies only to foreclosures recorded during an **implement run's inline fix loop** (Phase 3.3), whose manifests Phase 4.0.5 merges in the same environment; a **standalone** `/prflow:review-and-fix` run's foreclosures are **in-run only** — they persist in an environment-local run-scoped manifest no later pass reads, a permanent limitation since the implement-side writers run once, before any post-PR fix cycle. (2) The locally-installed marketplace plugin and a consumer's pinned `prflow_version` are independently-versioned producer/consumer copies; that skew degrades visibly and fail-closed — an **old** vendored matcher rejects a new-shape foreclosure entry as `missing-follow-up-issue` until the pin is bumped.

---

## 14. The cloud tier: GitHub Actions architecture

Three PRFlow workflows remain in the tree — `install.sh` ships the first two into a
consumer repository (plus the repo's own `ci.yml`, whose **required** status check is the **`lib + python tests`** job, *not* `CI`, which is only the workflow `name:` and never resolves as a check — since issue #877 that job is an **aggregator** that recombines the pass/fail/skip tallies of a concurrent `shard` matrix (`monolith` + `python-pool` + `modules-*`) and fails the required check if any shard fails, is cancelled, is skipped, or is missing; the required-check name is unchanged):

| Workflow | `name:` | Purpose |
|---|---|---|
| `devflow.yml` | `DevFlow` | Light command listener: `/prflow:review`, `/prflow:review-and-fix`, `/prflow:pr-description` (event-driven only) — **shipped** |
| `devflow-implement.yml` | `DevFlow (implement)` | Runs `/prflow:implement` on a bare command comment — **shipped** |
| `devflow-runner.yml` | `DevFlow Runner (reusable)` | Reusable read-only runner. Its only caller was the withheld auto-review workflow, so nothing reaches it now; retained, not shipped |

`devflow-review.yml` — the auto-review caller that ran `/prflow:review` as a required PR
gate — was **withdrawn from this release (issue #936) and is not in the tree**. The
supported review path is a repository collaborator commenting `/prflow:review`. See
[Withheld from this release](#withheld-from-this-release-the-automatic-pull-request-triggered-review-tier).

**Key architectural facts (the engineering-deck details):**

- **The runner is split into its own file** because GitHub validates a called reusable workflow's permission ceiling against the caller's grant *across the whole called graph, before any `if:` runs*. Keeping the read-only runner separate from the high-privilege command job let the read-only reviewer call it without a `startup_failure`. That caller is withheld, so nothing calls the runner today; the split is why the file exists in its own right.
- **Coexists with Anthropic's Claude GitHub App.** PRFlow never creates or overwrites `claude.yml`. Every PRFlow trigger negates `@claude` so the two never double-fire (the *partition invariant*, enforced by tests). Anthropic's app owns plain `@claude` mentions, Q&A, and `/security-review`.
- **Triggers fire on real comments only, never descriptions.** A `/prflow:*` phrase in an issue/PR body or title must never start a run. Trigger text comes solely from comment/review bodies.
- **`devflow-implement.yml` is issues-only.** The heavy `/prflow:implement` listener subscribes to `issue_comment[created]` alone, and its gate `if:` requires `github.event.issue.pull_request == null` (with `scripts/resolve-implement-trigger.sh` re-checking via an `IS_PULL_REQUEST` backstop). Because a PR comment is *also* an `issue_comment` in GitHub's API, this filter is what keeps a comment on a pull request — including the weekly retrospective's audit-report comment, which quotes the literal `/prflow:implement` phrase in prose on the state PR — from ever starting an implement run. `/prflow:review` and `/prflow:pr-description` in `devflow.yml` stay PR-aware and are unaffected.
- **A light `/prflow:*` command fires only when *issued*, never when *quoted*.** The light path (`/prflow:review`, `/prflow:review-and-fix`, `/prflow:pr-description`) stays PR-aware by design, but a command merely quoted in prose (a human review that says "as `/prflow:review` flagged…", PRFlow's own review narrative) must not be mistaken for the command being issued — a quoted `/prflow:review` in a PR **review** body was the reported self-trigger vector. `scripts/resolve-command-trigger.sh` (the authoritative gate; the workflow `if:` stays a coarse `contains()` pre-filter) closes this two ways: (1) **anchoring** — a command triggers only when it is the sole content of its own line (≤3 leading spaces, not inside a fenced or indented code block, remainder at most an optional `#`-number), via a shared markdown-aware POSIX-`awk` scanner (`scripts/detect-standalone-command.sh`) that is CRLF-tolerant, most-specific-first, and **fail-closed on an unbalanced fence**; and (2) a **self-marker guard** that declines any body carrying a PRFlow self-comment marker (the `<!-- prflow:review-progress` progress-comment prefix or the `<!-- prflow:workpad -->` marker) before authorization. See [`docs/workflow-triggers.md`](workflow-triggers.md) for the full contract.
> [!IMPORTANT]
> **The `devflow-review.yml` tier described in the rest of this section is WITHHELD from this release (issue #936).** The workflow is not in PRFlow's tree and `install.sh` ships none of the three tier files, so a fresh installation has no automatic PR-triggered review — the supported path is a collaborator commenting `/prflow:review`. What follows describes the tier **as it behaved when it shipped**, and is retained as the reconstruction reference; a repository that installed it earlier still runs exactly this. See the withheld-tier note near the top of this document for the reasoning and the removal procedure.

- **`devflow-review.yml`** triggers on `pull_request` + `pull_request_target` `[opened, reopened, ready_for_review, synchronize]`, `check_run[rerequested]`, and — since issue #304 — the CI-completion re-trigger events `workflow_run[completed]` (Actions CI, which **must be named** in the trigger's `workflows:` list — a GitHub platform requirement, no wildcards; the list must cover **every** first-party workflow that runs on PR events, since `require_ci_green` waits on all of them but a deferred review re-fires only when a *listed* workflow completes — a gating workflow left off the list that finishes last strands the review at a neutral "waiting" check, issue #579; the `lib/test/check-review-retrigger-coverage.py` guard that enforced this was retired with the tier in issue #936, so a reconstruction must restore it too; consumer repos replace the list with their own PR-gating workflow names when installing) and `check_suite[completed]` (external, non-Actions CI apps; GitHub's recursion prevention means Actions-created suites never deliver this event), and — since issue #310 — the `status` event (legacy commit-status-only CI — classic Jenkins, legacy CircleCI — which reports via the commit-status API and emits neither `workflow_run` nor `check_suite`; the precheck filters to a green `state == 'success'` before a runner spins, and the route resolves the PR from the status head SHA since the payload carries no PR ref — it cannot self-trigger because this workflow posts check-runs, never statuses). It listens on `opened`/`reopened` (not just `ready_for_review`) because a PR opened directly non-draft never emits `ready_for_review`, without those events the required check would never run on such a PR. Bot actors route to `pull_request_target` (so secrets resolve); humans route to `pull_request`, runs exactly once.
- **Review-trigger preconditions (issue #304).** Before the first-review, `synchronize`, or CI-completion paths run the engine, the precheck evaluates two config-gated preconditions via `scripts/derive-review-preconditions.sh` (fail-closed on unverifiable queries — the check then says "preconditions unverifiable", never a condition the script did not observe; a consumer repo missing the vendored script fails **open** and reviews unconditionally; no hardcoded job names): `prflow_review.require_up_to_date` (the PR branch must not be behind the configured `base_branch`) and `prflow_review.require_ci_green` (every other CI signal on the head — non-self Actions runs, legacy statuses, external check runs — completed without failing; success/skipped/neutral count as green, and a head with **no** other CI is satisfied, so a CI-less repo is never wedged). The non-self Actions runs are first **collapsed to the latest run (highest `run_number`) per `(workflow_id, event)` group** (issue #351), so a superseded run — an approval-gated re-dispatch, a double-fire, a cancelled sibling — never gates the review once a newer run of the same workflow+event exists; a non-self run missing a numeric `workflow_id`/`run_number` or a string `event` makes the collapse unverifiable and fails closed. Signal sets (2)/(3) need no collapse — GitHub already returns the latest per name server-side. A surviving run awaiting manual approval (conclusion `action_required`, in either the Actions-runs or external-check-runs set via the shared green-gate) defers with the distinct reason `ci-approval-required`. On an unmet precondition the run **defers**: `create_check` posts the required `Devflow Review` check pre-completed **neutral** with a "waiting: branch behind base" / "waiting: other CI not green" / "waiting: CI approval required" title (each title is selected from the skip reason by `scripts/describe-skip-title.sh`, invoked in the `precheck` job and consumed by `create_check` via the `skip_title` output — the last is the `ci-approval-required` reason's own title), the engine never runs, and `finalize_check` is deliberately skipped (a skipped job check-run is excluded by the exactly-once gates — a finalize that ran would leave a `success` job check-run that reads as an already-run review and would wedge the re-trigger). Repeated deferrals are **de-duplicated**: a branch that stays behind base (or whose CI stays red) across several CI-completion events re-enters the deferral path each time, so instead of POSTing a fresh completed-neutral check per event, `create_check` looks up any existing neutral `Devflow Review` check for the **same head + same reason** (title) and PATCHes it in place (refreshing its details URL/summary), only POSTing when none exists — a lookup failure falls through to the POST path so the required check is never lost. The review then auto-re-triggers on the next `synchronize` or CI-completion event; the check's Re-run button forces a review past the preconditions (the `check_run` path is deliberately ungated). A neutral required check does not itself block merge — the freshness gate is a cost optimization; pair it with branch protection's "require branches up to date" if staleness must block. Setting either key to `false` restores the unconditional trigger for that precondition. When one of the script's `gh api` queries (the branch-freshness compare, the workflow-runs, combined-status, or check-runs fetch) fails, its fail-closed "query failed" stderr breadcrumb captures `gh`'s own stderr, so an operator debugging a permanently-deferred auto-review sees the real cause (rate limit, 403 token-scope, 5xx) rather than a bare "query failed". **Known limitation:** the deferral re-evaluation triggers are all head-scoped, so a `require_up_to_date` (behind-base) deferral is **not** re-evaluated when the *base* branch advances with the head untouched — it clears only on a `synchronize`, a CI-completion event, or a Re-run. The **producer-side mitigation** for PRFlow's own runs is the base-branch update checkpoints (`prflow_implement.update_branch_checkpoints`, on by default — see the config table below and [`docs/implement-skill.md`](implement-skill.md)): an `/prflow:implement` (and standalone `/prflow:review-and-fix --push-each-iteration`) run merges `base_branch` into its feature branch and pushes at its checkpoints — including pre-ready (Phase 4.3) — so it emits a fresh, non-behind head *before* the review fires — which in the common case avoids this behind-base deferral, and also satisfies branch protection's "require branches up to date" rule. It does not, however, re-clear a deferral that has *already* stranded on a base that advanced afterward — nor guarantee freshness when the base advances in the narrow window between the checkpoint push and the review firing — either of which still needs a `synchronize`/CI event or a Re-run. See [`docs/workflow-triggers.md`](workflow-triggers.md) for the full trigger + preconditions policy.
- **Third-party model provider routing (opt-in, §17 `providers`).** Each of the three model-running workflow sections — `devflow` (`devflow.yml`), `prflow_implement` (`devflow-implement.yml`), and `prflow_runner` (`devflow-runner.yml`) — can route Claude Code through an Anthropic-compatible endpoint instead of the default Anthropic OAuth path. A **single-sourced inline `jq` resolver** (delimited by `devflow-provider-resolver BEGIN/END` and kept **byte-identical** across all three workflows — `lib/test/run.sh` pins that identity; only the `--arg section` value differs) reads `.prflow/config.json` and emits a per-section decision: the named `providers.<name>` entry's `base_url`, `auth` (`bearer`\|`api_key`), `timeout_ms`, `effort_supported`, and `env` map, plus the resolved model. A `run:` step then injects `ANTHROPIC_BASE_URL` / `API_TIMEOUT_MS` / the provider `env` map into `$GITHUB_ENV` **only when a provider is active** (gated on `provider != ''`), so the default path carries no empty `ANTHROPIC_*` vars and renders today's OAuth wiring unchanged for a given `claude_model` (one deliberate change: an empty resolved model now fails loud instead of rendering `--model null`). The resolver **fails the job loud** on an incomplete provider entry (missing `base_url`, or `auth` not `bearer`/`api_key`); the `claude_args`-building step fails loud on an empty resolved model, on a flag-shaped (leading-dash) model value or one carrying any character outside a conservative model-id allowlist, and on an effort value outside the schema enum (the flag-injection guard — those values are spliced unquoted into the CLI string, which the action tokenises shell-style, and a positive allowlist stays closed even where a bytewise whitespace blacklist would miss Unicode spaces under a non-UTF-8 locale); the inject step fails loud when the fixed `DEVFLOW_PROVIDER_API_KEY` repo secret is empty, and it rejects an `env`-map key that is not a valid environment-variable name (the key is interpolated into the `$GITHUB_ENV` heredoc header, which the newline-safe value form does not protect) — never silently degrading. `--model` is always passed; `--effort` is dropped only for a provider whose `effort_supported` is `false` (the default path resolves `effort_supported=true`, preserving effort). On the provider path the action authenticates via `anthropic_api_key` (the fixed secret) with an empty `claude_code_oauth_token`; for `bearer` auth the same key is also exported as `ANTHROPIC_AUTH_TOKEN`. **Security:** `devflow-runner.yml` (the privileged reviewer, which runs on the PR head under a write token) resolves its provider decision from the **trusted base-ref config** — the same source as `provision_env` / `setup` / `allowed_tools`, never the PR head — so a malicious PR cannot add a rogue provider and redirect the review to an attacker endpoint to exfiltrate the API key; and on the runner the provider endpoint (including, for `bearer`, the key exported as `ANTHROPIC_AUTH_TOKEN`) is injected **after** the opt-in `provision_env` build step, so a `provider` + `provision_env` combination never exposes the key to PR-author-controlled build code. When that trusted base config is unreadable (fetch failure or malformed), the runner reverts to the Anthropic default with a loud warning that names the provider-routing revert (not just `provision_env`), and the OAuth-default guard reports the unreadable config rather than falsely claiming no provider is configured. The runner's `CLAUDE_CODE_OAUTH_TOKEN` secret is therefore `required: false` (it still fails loud when absent *and* no provider is configured), and its dead `model` input was removed. See §17 `providers` / `docs/cloud-setup.md`.
- **`finalize_check` job is named `Devflow Review`** so the required-status-check matcher resolves the ruleset context name to a workflow *job* name (otherwise the check never links and the PR's merge state stays BLOCKED).
- **Stall backstop (`prflow_implement.stall_backstop`).** A headless single-shot `claude-code-action` run can end mid-lifecycle yet report `success` — the SDK ends the session the moment the model emits a tool-call-free turn, so a run that stops at (say) the Phase 2→3 boundary leaves the workpad frozen at an interim `Status` while the job goes green. The agent-side terminal-status self-check cannot fire once the session has ended, so a **workflow-level backstop** runs after the `claude` step and keys on the issue workpad `Status` (via `workpad.py status`, **never** PR draft state): a terminal `Status` is no longer uniformly a no-op (issue #1025): 🎉 `Complete` remains a no-op (the job stays `success`), a stale 🛑 `Cancelled` read (on a non-cancelled job) is left green — never converted to a failure — while 👎 `Blocked` and 💥 `Failed` conclude the job **non-`success`**, the step emitting a `::error::` that names the issue number and the workpad `Status` and exiting non-zero, so `gh run list` plus the annotation distinguish a blocked/failed run from a completed one without opening the workpad (the workpad is left unchanged — its 👎/💥 is already truthful — and `workpad.py status` names each terminal glyph with its own decision class rather than collapsing them, so this split is decided on a parsed class, not a downstream glyph match); an interim `Status` (🚀) auto-resumes `/prflow:implement <n>` up to `stall_backstop.max_resume_attempts` (default `2`) with a distinct audit comment per attempt (the resumed run does **not** resume Phase 2 in place — the `code-explorer`/`code-architect` artifacts are non-persistent, so the fresh process re-enters Phase 1 and the **Phase 2 §2.0 resume-idempotency gate** builds on the committed `## Plan` instead of re-running discovery/architecture, per the Phase 2 section above), and an exhausted cap or an unreadable status fails the job loud with a distinct comment — "unreadable" covers a missing/empty `Status` line **and** a present `Status` word that isn't in the canonical vocabulary (`workpad.py status` exits 1 for either shape, exit 2 for no workpad, never misreading a corrupted word as a healthy in-progress stall). A distinct **`auth-failure`** class handles a `gh`-api/transport/auth failure reading the workpad (`workpad.py status` exit **3**, e.g. an expired App installation token, or a failed comment-list fetch): it fails loud with an auth-specific comment **without consuming a resume attempt** and is never mislabeled `unreadable`, so a healthy workpad behind an expired token is not misclassified as corrupt (issue #287). To keep that read from failing on a long run, the backstop mints a **fresh** App token just-in-time immediately before it runs, rather than reusing the token minted at the start of the (possibly >60-minute) `claude` job. `stall_backstop.enabled` (default `true`, safe-direction on any unrecognized value) is the master switch; disabled or absent, the job behaves exactly as before. The decision is a pure, unit-tested helper (`scripts/stall-backstop-decide.sh`) and the comments go through the best-effort repo-scoped REST `scripts/post-issue-comment.sh`, so the backstop can detect-and-fail-loud honestly rather than masquerading a stalled run as green. The thin `Stall backstop` step (`if: always()`, after the observability-persist backstop in the `claude` job) wires these together, counting prior attempts via the `<!-- prflow:stall-backstop-audit -->` marker each resume comment carries; only the resume comment carries the trigger phrase. Auto-resume additionally requires the optional `DEVFLOW_APP_ID` App token (a `GITHUB_TOKEN`-authored comment never re-triggers a workflow — a resume decided without the App token posts its comment and then fails the job loud rather than reading as green) and that App's bot login in `devflow.allowed_bots`; the fail-loud and audit-comment behavior works under either token. **Dead-run `Status` flip (issue #356).** On every fail-loud exit taken after successfully reading a genuinely interim `Status` — cap exhausted, the `mktemp` abort, the dropped-resume-comment abort, and the resume-posted-but-no-App-token abort — the step first best-effort-flips the workpad to the new terminal word **`Failed`** (glyph **💥**, added to `workpad.py`'s closed status model) with a note linking the dead run, then exits with its existing code, so a dead run stops lying at `🚀 Implementing`. The flip is guarded on the `interim` class (a terminal/unreadable/auth-failure `Status` is never clobbered) and never runs on the green resume path (a terminal `Failed` written before a resume would make the resumed run's own backstop read a decided terminal end — pre-#1025 a silent `terminal→noop` disarm, post-#1025 a spurious `fail-blocked` — so the flip must never precede a resume). It is best-effort — a failed flip emits a `::warning::` and never changes the exit code — and 💥 has no reaction equivalent. **Cancelled-run exclusion + flip (issue #498).** A cancelled run (job.status=cancelled) is a decided ending, not a stall: the backstop reads `job.status` and, only on the exact value `cancelled`, resumes nothing — an interim `Status` flips to the new terminal word **`Cancelled`** (glyph **🛑**, the sibling of 💥) with no comment and no resume attempt consumed, while terminal/unreadable/auth-failure classes log and exit green (no fail-loud diagnostic). Every other `job.status` value leaves the table above byte-identical (fail toward resume). 🛑 joins 💥 as a workpad-only glyph with no reaction equivalent; a fresh `/prflow:implement <n>` re-trigger on a `Cancelled` workpad resumes through Phase 1's terminal-`Status` re-trigger arm, exactly like a `Failed` one. **Prevention layer (issue #415).** The backstop above is the deterministic *convergence* net; a coordinated *prevention* layer reduces how often the early-quit fires in the first place, mirroring the review tier's #408/#410 fix. **(1) Headless-wait discipline (prose).** The always-resident cross-phase-rules section of `skills/implement/SKILL.md` — cloud-conditioned on `GITHUB_ACTIONS`, beside the *Non-interactive self-answer rule* — tells the orchestrator this is a headless run: ending the turn ends the process; never end the turn while any dispatched agent (a Phase-2 `code-explorer`/`code-architect`, the Phase-3 inline `review-and-fix` agents, the Phase-4.1 `prflow:docs` subagent, any Agent-tool subagent) has not returned; poll to keep the turn alive; treat `ScheduleWakeup`/future task-notifications as unavailable. Its always-resident placement is load-bearing — it survives nested-skill body eviction, so it governs every dispatch point including the Phase-3 inline review pass. A one-line mirror rides inside the stall-backstop resume comment (`devflow-implement.yml`), coupled with the skill rule in one commit, so a resumed run receives it even if it never re-reads the skill prose. **(2) Probe-verified `ScheduleWakeup` denial.** `.github/workflows/matcher-probe.yml` carries a `schedulewakeup-probe` job that runs a `claude-code-action` session with `--disallowedTools ScheduleWakeup`, has the model attempt one `ScheduleWakeup` call (bracketed by two positive controls, with the tool granted in `--allowed-tools` so the flag under test is the only removal cause), and derives a deterministic DENIED/AVAILABLE/REMOVED/INCONCLUSIVE verdict from the execution file (never the model's text). The verdict gates whether `devflow-implement.yml`'s `claude` step ships `--disallowedTools ScheduleWakeup`: a tool-removed/denied verdict ships the flag plus a `lib/test/run.sh` pin; a tool-still-available verdict ships no flag and records the omission rationale on the PR — the same probe-before-grant discipline the matcher-probe corpus already uses. Local/interactive runs are untouched: the rule is cloud-scoped and the flag is added only to the cloud `claude` job. **Executed (issue #418):** the probe measured **AVAILABLE** across real cloud runs 29140791165 and 29138117625 (both recorded a `ScheduleWakeup` `tool_use` that was not denied; a third run, 29139012320, hit the documented compliant-model false-positive — presumptive REMOVED with both controls run — and the two positive observations are dispositive over it), so per the tool-still-available arm above no flag or `--disallowedTools`-flag `lib/test/run.sh` pin shipped (the unrelated #408/#415 ScheduleWakeup prose/verdict-helper pins are untouched). At that point the early-quit prevention rested on the headless-wait prose alone; **issue #801 added a deterministic harness floor beside it** — each cloud engine step (`devflow-runner.yml`, `devflow-implement.yml`, `devflow.yml`) now sets `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS: "1"`, which the vendor documents as keeping subagents in the foreground, so a dispatch's results are in hand before the turn continues rather than arriving on a later turn a headless run never reaches. Unlike the `--disallowedTools` flag above it ships **unconditionally rather than probe-gated**, a deliberate divergence recorded as such: that flag *removed* a tool, so shipping it on an unconfirmed premise risked breaking a working run, whereas this variable is **inert when ignored** — a runner that does not honor it leaves today's behavior exactly as it is. **Its documented scope is wider than subagents:** upstream it disables *all* background task functionality, which includes the `Bash` tool's `run_in_background`. No engine surface asks for a backgrounded `Bash` today, so that breadth is inert here — but a future step that wants one would find it blocked on the cloud tier, and the remedy is a scoped design decision on this variable, not a local workaround. Beside it, each engine root now states the requirement **behaviorally** (a dispatch blocks until the completed result is in hand; a launch acknowledgment is never the return), with the environment variable named as a current example rather than the definition, so the requirement survives a parameter rename and holds on runtimes that expose no equivalent switch. **Executed (issue #812):** whether the variable takes effect inside `claude-code-action` is now **observed**, not assumed. `matcher-probe.yml`'s `background-tasks-probe` job runs a `claude-code-action` session carrying `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS: "1"`, dispatches one subagent, and derives a FOREGROUND/BACKGROUNDED/NOT_DISPATCHED/INCONCLUSIVE verdict from the execution file (`scripts/background-tasks-probe-verdict.py`; the model's text is never the measurement). It measured **FOREGROUND** across real cloud runs 30210679122 and 30211584731: in each, the top-level session echoed the subagent's own returned marker back through Bash in the same turn — harness-recorded evidence, under the probe's cooperative-model assumption, that the completed result was in hand before the turn continued — with both bracketing positive controls run and no `permission_denials`. So the harness floor is **observed effective** on this action version, and the early-quit prevention no longer rests on the headless-wait prose alone. The run also recorded the dispatch tool under the name `Agent` rather than `Task` — which the probe's both-names grant already covered, and which its name-agnostic input match is designed for. **Both** verdicts in this bullet are **version-dependent** — each is a dated observation of one `claude-code-action` version, not a platform contract — so **re-probe the ScheduleWakeup result via the `schedulewakeup-probe` job, and this one via the `background-tasks-probe` job, after a `claude-code-action` upgrade before trusting either**. An additional sibling job in the same `matcher-probe.yml`, `implement-probe` (issue #450), applies the same execution-file measurement to the read-write `devflow-implement` tool profile — a separate allowlist from the read-only `review` profile the existing `probe` job measures, so a command shape or grant form proven on one tier is unproven on the other — establishing the human-dispatched implement-tier evidence of record for the label-helper grants; like the rest of `matcher-probe.yml` it is repo-internal and not shipped by `install.sh`.
- **Local-tier Stop-hook backstop (`lib/implement-stop-guard.sh`, issue #362).** The stall backstop above is cloud-only — **not** because `Stop` hooks are unavailable there (`claude-code-action` removes `.claude/` and then **restores it from the base branch**, so a base-registered `Stop` hook executes inside the action: observed **`FIRED`** by probe run `29224205805`, recorded in [`docs/execution-file-shape.md`](execution-file-shape.md) and relied on by the Stop-hook trusted-source floor below), but because the cloud net must read the workpad `Status` *after* the `claude` step ends, which no hook inside the session can do — and because this guard is repo-local and ships to no consumer. So an unattended *local* run that dies mid-phase has no deterministic net. This repo wires a second `Stop` hook that is **marker-gated**: Phase 1.3 writes a gitignored `.prflow/tmp/implement-active-<issue>` marker and the always-resident *Outcome reaction* block removes it at every terminal `Status` transition. With no marker present the guard exits on a pure-bash glob, having spawned no interpreter and made no network call (only the one local `git rev-parse` its repo-root resolver runs), so ordinary sessions are unaffected; with one, it reads that issue's live workpad `Status` (`workpad.py status`, the source of truth; the marker only gates *whether* to ask) and, solely on an `interim` class, exits **2** (the documented Stop-hook blocking code) with a stderr instruction naming the issue and status word. A `session_id`-keyed sentinel bounds it to at most one block per session, and every ambiguous path (unreadable workpad, `gh` transport failure, unparseable hook input, failed sentinel write) fails **open**. A stale marker self-heals: a live status that reads terminal deletes it. The guard is **repo-local by design** and ships to no consumer repo. It complements three always-resident cross-phase rules in `skills/implement/SKILL.md` that prevent the death rather than catch it — a generalized mid-phase re-anchor after every Skill-tool return, a non-interactive self-answer rule for a nested skill's user-facing question, and a subagent-dispatch path for convention-mandated *interactive* skills (a mid-phase Skill invocation is a tail call: the run ends on the nested skill's final approval step). Full treatment: [`docs/implement-skill.md`](implement-skill.md).
- **Resume detects an existing PR (`phase-1-setup.md` §1.4, issue #362).** Before the linked-worktree signal, a run reads the workpad `**Branch:**` line and queries the issue's open PRs (by head branch *and* by body reference), then continues that PR's head branch — inside an existing linked worktree when one holds it — instead of forking a duplicate branch and PR. With no workpad `Branch` line and no open PR, §1.4 is unchanged.
- **Stale-checkout guard for adopted branches (`phase-1-setup.md` §1.4/§1.6, `phase-2-implement.md` §2.1, issue #429).** A run that *adopts* a pre-existing branch (the worktree/`USE_CURRENT` path) used to skip the base fetch, so every later verification read a tree that could be days behind the base — the #325 incident falsely refuted a *true* "already shipped in PR #319" claim against a 43-hours-stale checkout and re-implemented merged work into a dirty merge. Four bounded prose rules close it (no helper, workflow, allowlist, or config change; consumers inherit through the shared skill): a **freshness guard** on §1.4's adopted-branch arm fetches the base, records how far behind `origin/$BASE` the tree is (behind-by-0 included, so freshness is *checked* not assumed), and on a fetch failure records a freshness-unverified reflection and continues; a **read-target rule** (§1.6 + §2.1 coupled mirrors) points shipped-work verification reads at `origin/$BASE` state when behind, when unverified, or when no freshness record exists at all (the workpad write is best-effort, so a missing record fails closed as unverified rather than reading as behind-by-0); a **cross-pass coherence rule** (same two mirrors) refuses to REFUTE a "shipped in PR #N" claim on tree reads unless a read-only `gh pr view` shows PR #N MERGED *and* `git merge-base --is-ancestor` confirms the merge commit is in the checkout — MERGED-but-absent or any indeterminate outcome yields "checkout stale — refresh and re-verify", never "code wins"; and a **sibling-PR annotation rule** (§4.0) requires a composed already-shipped annotation to name the sibling PR and its merge state at filing time.
- **Ahead-of-base branch-state preflight — Verdict B (`phase-1-setup.md` §1.4.0.5, `scripts/preflight.py branch-state`, issue #576).** The freshness guard above derives only the *behind*-by count, so a branch that is not behind base can still carry unrelated **ahead-only** history that every downstream step treats as the run's own — §1.5 publishes those foreign commits into the PR diff (the PR #524 incident: four unrelated files forked from an unpushed local-`main` commit that read "behind-by-0 / up to date"). On the adopted-branch arm (`USE_CURRENT`) and — since issue #780 — the landed-resume arm (`LANDED`, the population #779 deliberately left unwidened even though the checkpoint below it was already arm-independent), after the freshness record on the adopted arm and, on either arm, **before** the end-of-§1.4 update-branch checkpoint and the §1.5 push, §1.4.0.5 writes the state it holds to `.prflow/tmp/branch-state-$ISSUE_NUMBER.json` (Write tool) and invokes the `scripts/preflight.py branch-state` subcommand, which derives the ahead-of-base count (shallow unshallow-once-then-rederive), recorded-branch existence, and published-tip reachability, then emits **one verdict token + matching exit code** (mirroring `update-branch-checkpoint.sh`'s one-token-stdout contract): `FRESH`/`VALIDATED_RESUME` → 0 (proceed), `AMBIGUOUS`/`DECISION_BLOCKED` → 2 (needs a human decision — flip the workpad `Blocked`), `UNAVAILABLE` → 3 (an unestablished measurement — fail closed to `Blocked`). Any non-zero exit stops the run before the end-of-§1.4 checkpoint invocation and §1.5. The subcommand is **read-only w.r.t. git history** (rev-list/rev-parse/check-ref-format/merge-base plus a single shallow deepen; it never resets, rebases, checks out, commits, merges, pushes, or deletes), so a stop verdict makes no history mutation. **Ahead history may be vouched for by more than one provenance source (issue #780):** the **workpad** (`provenance_established`), and the **open-PR linkage** — an open PR in *this* repository whose head branch is the working branch, which is not cross-repository, and which is tied to this issue either by closing it or by having been selected by the pre-check's head-branch query. The second is what makes the landed-resume arm classifiable at all, since that arm has ahead history by definition while its workpad provenance is unestablished for a cloud run whose §1.3 `HANDOFF` is `unknown` and for a local resumed run that created no workpad of its own — a workpad-only gate turned each of those populations into a terminal stop. The workpad wins wherever the two sources overlap; on the PR-vouched path the untrusted workpad is **neutralized, not consulted**; and a partial gather of the PR operands is refused rather than read as a refutation. The canonical statement of the admission and its threat model — including the honest population-overlap caveat and the narrower scope the screen has on the landed-resume arm — is [`docs/implement-skill.md`](implement-skill.md)'s *Two provenance sources for ahead history* section; this bullet is its coupled summary. Adds the `preflight.py` subcommand and the §1.4.0.5 prose only — no workflow, allowlist, or config surface; consumers inherit through the shared skill and vendored helper.
- **Review-progress died-flip (issue #356).** The review engine seeds a run-keyed `<!-- prflow:review-progress run=<id>-<attempt> -->` comment at `🚀 Reviewing`; the skill flips it to `❌ Review failed` on an *agent-side* fatal abort, but when the *job* dies (claude step failure, cancellation, or a success whose verdict resolves incomplete because the engine ended `is_error`) the agent never acts. A workflow-level backstop mirrors the agent's flip: the best-effort helper `scripts/flip-review-progress-failed.sh <pr_number> <marker> <cause>` locates *this run's* comment (the run-keyed marker matches only the current run, so earlier runs' comments are never touched), and — solely when its `**Status:**` line still begins with 🚀 — rewrites it to `**Status:** ❌ Review failed` and appends a one-line cause with the run link, routing all GitHub access through `workpad.py` (so no bare `gh` caller is added). It always exits 0 with an arm-naming stderr breadcrumb (e.g. flipped / comment-absent / read-failure / already-terminal / patch-failure — a failed comment lookup is reported as a read failure, never as "comment-absent"), so a flip hiccup never fails the required `Devflow Review` check. Both call sites cover the **same three** non-success arms: `devflow-review.yml`'s `finalize_check` job (`if: always()`, survives even a review-job runner death) invokes it on `REVIEW_RESULT` of `failure`, of `cancelled`, and on the engine-error incomplete arm; `devflow.yml`'s comment-triggered `claude` job invokes it from a new `always()` step keyed on `steps.claude.outcome` being `failure` or `cancelled`, **or on `steps.engine.outputs.is_error` being `true`** — a sibling `Surface review-engine execution result` step parses the engine result with `scripts/parse-engine-error.sh` (mirroring `devflow-runner.yml`), because the `claude` step can exit `success` while the engine's final message carries `is_error`. The `❌ Review failed` literal and the marker shape are a coupled contract with `skills/review/SKILL.md` (pinned in `lib/test/run.sh`).

- **Review no-verdict auto-resume backstop (`prflow_review.stall_backstop`, issue #408).** The died-flip above makes a dead review *visible* but leaves it a dead-end — a human still has to re-trigger. A headless review run can end `success` with **no verdict**: the SDK session ends the moment the model emits a tool-call-free turn (e.g. after a `ScheduleWakeup` while a Phase-3 agent is still pending), so the required `Devflow Review` check fails "incomplete — re-run needed". Two coordinated layers fix this. **(1) Headless-wait discipline (prose).** Each of the engine's cloud-conditioned prompt surfaces — the `skills/review/SKILL.md` section and the injected grounding block (`scripts/render-grounding-block.sh`, rendered once) — tells the engine this is a headless run — ending the turn ends the process; never end the turn while a dispatched agent has not returned; poll to keep the turn alive; treat `ScheduleWakeup`/future task-notifications as unavailable. This reduces the frequency of the early-quit. **(2) Bounded auto-resume backstop (deterministic).** The **auto-review path** (`devflow-review.yml`'s `finalize_check`) derives the verdict for the head via `derive-review-verdict.sh` and, when it concludes the run incomplete **with no verdict positively observed for the head** (exactly the success-with-no-verdict early-quit above), invokes `scripts/request-review-backstop.sh` — the pure decision helper that owns the whole fire/no-fire choice (config read, verdict guard, per-head attempt count, App-token guard, marker construction), so `lib/test/run.sh` drives every arm — to decide whether to fire. The **manual `/prflow:review` comment path** (`devflow.yml`) has no verdict-derivation step, so it invokes the same helper on the **`#356` dead-run signal** it already computes — the engine ending `is_error` or the `claude` step ending `failure` (a hard death), **not** a clean success-with-no-verdict. So a manual-path run that early-quits benignly is covered only by Layer 1's headless-wait prose, not the deterministic backstop; the auto-review path — which handles the vast majority of reviews and is the one the early-quit was diagnosed on — is fully covered. (Closing the manual-path success-with-no-verdict case deterministically would need a verdict-derivation step ported into that comment-triggered job; deferred as a follow-up.) On a fire, the workflow posts a `/prflow:review` re-trigger comment carrying a `<!-- prflow:review-backstop head=<sha> attempt=<n> -->` marker, authored by a **freshly minted App token**, so the review re-runs without human action. Each workflow path posts and annotates through the shared `scripts/post-review-backstop-comment.sh` helper (extracted from the two near-identical inline blocks, issue #414): it composes the marker + re-trigger body, POSTs it via `post-issue-comment.sh`, and selects the fired-`::notice::`-vs-failed-`::warning::` annotation on the POST success breadcrumb — so `lib/test/run.sh` drives that fail-closed selection instead of only presence-pinning a YAML literal. The cap is `stall_backstop.max_resume_attempts` (default `2`) per head, counted from the marker comments for the current head; `stall_backstop.enabled` (default `true`, safe-direction on any unrecognized value — a real JSON `false` disables it) is the master switch. When the cap is exhausted, or no App token is configured (`DEVFLOW_APP_ID` unset — a `GITHUB_TOKEN`-authored comment never re-triggers a workflow), the backstop reports **no-fire** with a breadcrumb naming why, and the run degrades to exactly the dead-end flip above. Because the re-trigger re-enters the same manual `/prflow:review` comment gate, auto-resume also requires the minting App's bot login to be in `devflow.allowed_bots` (the same prerequisite the implement backstop carries) — otherwise the comment posts but the gate declines it. The backstop never fires when a verdict exists (APPROVE or REJECT), never fires beyond the cap, and never fires when disabled — it is purely additive. This reverses the earlier "no auto-retry backstop" decision, which predates the transcript evidence characterizing the residual failure. **That residual is not a timing race (issue #801).** Run `30138268273` established it as the harness's *documented default dispatch mode* meeting a headless runner: subagents are background-by-default upstream, a background dispatch's results arrive in a **later turn**, and a headless `claude -p` session ends at the first tool-call-free turn — so all eight dispatches returned only launch acknowledgments and the run ended `end_turn` with no verdict after a full-fleet spend. A race is a scheduling coincidence a re-run wins; this is the documented default dispatch mode meeting a headless runner, which run `30138268273` reproduced on a full fleet. The prevention layers are correspondingly deterministic rather than probabilistic — `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS: "1"` on each cloud engine step, plus the runner-agnostic barrier statement in each engine root. It is the review-side sibling of `prflow_implement.stall_backstop`.

- **Long-run credential refresh (issue #487).** A GitHub App installation token expires 60 minutes after minting and cannot be renewed, so a writer-job run that outlives the hour used to spend its remainder on dead credentials (`git push` and agent-side `gh` both 401). Both writer jobs — `devflow-implement.yml`'s `claude` job and `devflow.yml`'s `command` job — now start a detached refresher (`scripts/refresh-app-credentials.sh`) after checkout that, on a 45-minute cadence, re-mints a fresh installation token and rewrites the two repo-controlled credential surfaces in place: the checkout-persisted `http.<server>/.extraheader` credential the in-run `git push` authenticates with, and a mode-0600 token file that the `gh` wrapper (`scripts/gh-fresh.sh`, installed ahead of `gh` on `PATH` by the checked-in, seven-output-validated `scripts/install-gh-wrapper.sh` — which publishes `DEVFLOW_GH_REAL` but deliberately **no** process-global `DEVFLOW_GH`, so the override seam never leaks into later steps such as the repo test suite; issue #533) resolves at call time. **`mode-0600` holds only where POSIX mode bits apply: on Windows they constrain neither that token file nor the installer's sibling fingerprint file, so the installer's mode gate relaxes there with a stderr breadcrumb and access is left to the filesystem's ACLs (issue #690 — see [`docs/cloud-setup.md`](cloud-setup.md#windows-posix-mode-bits-do-not-constrain-the-credential-files)).** An `if: always()` step retires it via `scripts/stop-refresher.sh`, which kills the refresher by pidfile, tails its detached log, and re-emits one live `::warning::` when the refresher was defeated. The whole mechanism is gated on `vars.DEVFLOW_APP_ID != ''` — unconfigured, it is a byte-identical no-op — and the `/prflow:review` read-only path (which never pushes) is excluded. See [`docs/cloud-setup.md`](cloud-setup.md).

### Vendoring / runtime materialization
- **Why a workspace path, not a marketplace install?** Inside the `claude-code-action` runner, `${CLAUDE_SKILL_DIR}` is unset, the bash sandbox can't read `~/.claude`, and `$`-expansion is blocked, so workflows reference helpers at the literal path `.prflow/vendor/prflow/scripts/…`. The plugin must physically be there when a job runs.
- **Why `.prflow/vendor/` and not `.claude/`?** On every PR, `claude-code-action` runs a security step that `rm -rf`s sensitive paths (including `.claude`) and restores them from the *base* branch, which would wipe a plugin vendored under `.claude/`. `.prflow/vendor/prflow/` is outside every sensitive path and survives.
- **Thin install (default):** the bulky plugin tree is **not** committed; the `vendor-plugin` composite action fetches it at runtime, pinned to `prflow_version` in `.prflow/config.json`. A thin install **refuses to run without a pinned `prflow_version`** (it never silently tracks mutable `main`).
- **Workflow grants arrive via `install.sh`, not `prflow_version`.** `install.sh` copies `.github/workflows/devflow-*.yml` into the consumer repo; `prflow_version` fetches only the plugin tree (`skills/`, `scripts/`, `lib/`). A grant wave on the implement/review profiles therefore reaches an adopter by **re-running `install.sh`** — bumping `prflow_version` alone leaves the older workflow copy without the grants. The #484 wave grants the helpers used by cloud implement runs: Phase 3's inline review engine calls `stale-prose-lint.py`, `match-lint-adjudications.py`, and `load-prompt-extension.sh`, while the implement-owned surfaces call `react-to-trigger.sh` in the trigger-reaction fence and `extract-doc-needed-paths.sh` in Phase 4.1. The exact issue-mandated grant set also contains `dismiss-stale-rejections.sh`; that helper appears in the shared review source's standalone-only Phase 4.4, which inline implement runs skip after Phase 4.3. The normal inline flow therefore does not invoke it, although the grant makes the capability available to the inline session; the source guard deliberately over-approximates the shared fenced source and requires the grant for parity. The wave also grants `cmp` and `git hash-object` for the inline review engine, plus `gh pr checkout` in `devflow.yml`. Without re-running `install.sh`, the Phase 3 stale-prose gate and the four other runtime helpers stay silently denied. The `lib/test/run.sh` #484 head guard pins the implement-profile surface.
- **Vendored install (`DEVFLOW_VENDOR=1`):** commits the full tree; nothing fetched at runtime.

### Runtime provisioning (the `setup` block)
Before Claude runs, the runner provisions the toolchain in order **Python → Node → PHP → service containers → `install` lines**. Languages are gated by version keys (empty = skipped). Service containers (databases/caches) start via `docker run` and are reachable on `127.0.0.1:<host-port>`. Node dependency caching is automatic when a lockfile is present. `/prflow:init` auto-fills the deterministic parts from detected language markers.

### Selecting the runner (`DEVFLOW_RUNNER`)
Every job in the two consumer-shipped workflows (`devflow.yml`, `devflow-implement.yml`) resolves its `runs-on` from an optional GitHub **repository/organization variable** `DEVFLOW_RUNNER` — infrastructure (which machine runs the job), set in GitHub Settings (Actions → Variables), deliberately **not** in the versioned `.prflow/config.json`. It accepts three shapes: **unset or empty** → `ubuntu-latest` (byte-for-byte the previous behavior); a **bare single label** (e.g. `windows-latest`) → that runner; a **JSON array** (e.g. `["self-hosted","windows","PRFlow"]`) → a runner matching that label set. A value that begins with `[` but is not valid JSON fails the job **loud** at evaluation time (a visible `fromJSON` error), rather than silently degrading to `ubuntu-latest`. Each workflow also declares a top-level `defaults: run: shell: bash`, forcing bash for `run:` steps on a non-Linux runner. **`setup.services` Docker caveat:** the service containers above run via `docker run`, and Docker is **preinstalled on `ubuntu-latest`** but **not** on a self-hosted non-ubuntu runner — so `setup.services` and any `Bash(docker:*)` path can break there unless Docker is installed on the runner. **Dispatch-enabled, not certified:** this variable makes a self-hosted / Windows runner *selectable* and forces bash, but does **not** certify that every inline bash body runs correctly on a Windows filesystem — an adopter must run at least one full consumer-shipped workflow end-to-end on the target runner before treating it as production-ready. Full prerequisites (toolchain, the `python3` shim, `DEVFLOW_GH`/`DEVFLOW_JQ`/`DEVFLOW_BASH`, the queue-forever label-match gotcha, the smoke-test boundary) are in [`docs/cloud-setup.md`](cloud-setup.md).

---

## 15. Security model

A strong slide for security-conscious buyers, PRFlow is explicit about its threat model.

- **One secret by default.** The cloud tier needs only `CLAUDE_CODE_OAUTH_TOKEN` (plus the built-in `GITHUB_TOKEN`) — no GitHub App is **required**. Routing a workflow section through an **optional** third-party model provider (§17 `providers`) adds exactly one more secret, the fixed, greppable `DEVFLOW_PROVIDER_API_KEY`; with no provider configured the cloud tier keeps the OAuth-only default (unchanged for a given `claude_model`). An **optional** App (`DEVFLOW_APP_ID` variable + `DEVFLOW_APP_PRIVATE_KEY` secret, with `Contents: write` + `Workflows: write` + `Pull requests: write` + `Issues: write` + `Actions: read`) does two things: it lets the cloud writers edit `.github/workflows/` files (which the built-in `GITHUB_TOKEN` is hard-blocked from), and it puts **the non-review user-visible cloud posts under the App identity** — the trigger reactions and the notice comments (the workpad comment is marker-detected by design, so its authorship never matters) — each site minting its own short-lived token downscoped via `permission-*` inputs to exactly what that site does. The **review** agent's posts (`devflow-runner.yml`'s progress comment, verdicts, approvals, and rejections) run instead under the separate **`DevFlow-Reviewer`** App (`DEVFLOW_REVIEWER_APP_ID` + `DEVFLOW_REVIEWER_PRIVATE_KEY`, `contents: read` so the review path cannot push), never this primary App — that separation is what keeps Phase 4.4's formal review from being a forbidden self-review (see 4.4 above). Unset, behavior is unchanged. See `docs/cloud-setup.md`.
- **Authorization gate.** A run only starts if the sender is an allowed bot (`devflow.allowed_bots`) **or** a human in `devflow.allowed_users` (default `*` = any collaborator) **who also holds write/admin/maintain access**. Resolvers fail **closed**.
- **Base-ref trust boundary.** The automated reviewer reads the `provision_env` flag, the `allowed_tools` list, the `setup` block, the pinned **`prflow_version`**, **and** its own appended **prompt extensions** (`.prflow/prompt-extensions/review.md` and `requesting-code-review.md`) **only from the trusted base branch**, never the PR head. A malicious PR therefore cannot enable provisioning for its own review, grant itself tools, inject install commands, choose which plugin commit reviews it, or write instructions into the reviewing agent's own prompt. The last two arrived together in issue #874: the review job checks out the PR head, so a repo-root read of an extension would have appended PR-author-editable bytes to the merge-gating reviewer's prompt — a strictly more powerful lever than the tool grants this boundary already covered. The job now truncates the workspace copy of each protected extension and exports `DEVFLOW_PROMPT_EXTENSION_ROOT` **unconditionally**, then populates that `$RUNNER_TEMP` closure from the base ref inside the fetch-success branch alone; the arms on which population does not happen — a failed base-ref fetch, an empty base ref, no trusted source for the materialization helper, a per-name read failure or unwritable target, a helper usage defect, a traversal-shaped protected name, and a non-blob object at a protected path — therefore each degrade to an empty closure rather than to the PR-head path. **Residuals, stated rather than glossed:** the plugin tree itself stays PR-selectable through `.claude-plugin/marketplace.json` and the PR-head composite actions under `.github/actions/` (filed separately); **the manual `/prflow:review` path in `devflow.yml` is NOT covered** — its `command` job also checks out the PR head and runs the same engine, but carries no truncation step and no `DEVFLOW_PROMPT_EXTENSION_ROOT`, so a bare `/prflow:review` comment on a PR still appends `.prflow/prompt-extensions/review.md` from the PR head to the reviewing agent's prompt, and that verdict is likewise posted as a formal PR review (this boundary is scoped to the **automated** review runner, `devflow-runner.yml`); and the added bytes still reach the reviewer through the *reviewed diff*, where the engine-ground-truth block's untrusted-data framing is the compensating control.
- **Deny-list floor (authoritative, enforced at consume-time).** Regardless of config, the runner strips catastrophic-tier tools before appending the build allowlist: tree-mutation tools (`Edit`, `Write`, `MultiEdit`, `NotebookEdit`) and raw-shell/eval/privilege Bash (`bash`, `sh`, `zsh`, `eval`, `exec`, `source`, `sudo`, …). The tree-mutation tools are matched by tool **name** — the token before the first `(`, compared case-insensitively — so a **parameterized** entry (`Write(**)`, `Edit(src/**)`) is stripped exactly like the bare name, not just the bare form. Legitimate entries whose *subcommand* is a deny word are kept (`Bash(docker exec:*)`), and read-only file tools (`Read(src/**)`) are kept. The filter lives in the suite-driven helper `scripts/filter-runner-tools.sh`, and the workflow executes it **only from a trusted source** — the review job checks out the PR head, so a floor whose code the PR can edit is no floor at all: the `baseprovision` step materializes the helper from the **trusted base ref** (`git show FETCH_HEAD:…` into `RUNNER_TEMP`, outside the PR-writable workspace — trying the committed-vendor path first, then the repo's own `scripts/` copy gated on the base ref actually being the PRFlow plugin repo), and when the base ref carries none, the vendored copy is accepted **only when `vendor-plugin` reports it was freshly fetched this run** at the pinned `prflow_version` (official-repo content — a PR can at most select an official-repo commit). A committed or self-copied vendor tree — PR-head content — is never consulted for floor code, and when no trusted source resolves the workflow fails **closed** (appending nothing, with a warning naming the rule). Each strip emits a per-entry warning naming the entry; the review continues. **The floor is as current as the base ref's helper (or the pinned fetch):** a consumer must land a **re-vendor on the base branch** for a later tightening (e.g. the parameterized file-tool strip) to take effect on reviews; an *absent* trusted helper fails closed (nothing appended), while a *present-but-stale* base-ref copy enforces its own older rules.
- **Stop-hook trusted-source floor (issue #458).** The deny-floor above covers *tool grants*; a second, parallel channel bypasses it entirely — **base-branch `.claude/settings.json` `Stop` hooks execute inside `claude-code-action`** (confirmed FIRED by run `29224205805`). `claude-code-action` restores `.claude/` (the hook **configuration**) from the base branch, so the hook *commands* are trusted — but those three commands (`bash lib/efficiency-trace.sh --persist`, `bash lib/implement-stop-guard.sh`, `bash …/scripts/stop-hook-probe.sh`) exec **script files under `lib/` and `scripts/`, not under `.claude/`**, which the review job's **PR-head checkout** (`devflow-runner.yml` checks out `ref: inputs.ref` = the PR head SHA) supplies. A PR that edits any of those three targets would otherwise obtain unmediated shell at session end inside a secrets-bearing CI job — the exact `#404` class ("a floor the PR controls is no floor"), reached through hooks rather than tool grants. **Hardening only the three entry scripts is not enough:** each of them `source`s / `exec`s / `python3`-runs further PR-head-editable files under `lib/`+`scripts/` (and `source` resolves relative to the sourcing script's own path in the PR-head workspace), so a base-copy entry would still pull in the PR-head copy of its dependency — the hole is one `source`/`exec` hop deeper. The fix therefore hardens the **full transitive source/exec closure** of the entries (thirteen files: the three Stop-hook entries plus the PreToolUse guard `scripts/pretooluse-shape-guard.py`, `lib/resolve-jq.sh`, `lib/config-source.sh`, `lib/resolve-bin.sh`, `lib/telemetry-branch.sh`, `scripts/config-get.sh`, `scripts/config_fingerprint.py`, `scripts/workpad.py`, and the guard's importlib closure `lib/test/extract-command-shapes.py` + `lib/test/extract-command-heads.py`), mirroring the deny-floor: **before** `claude-code-action` runs, `devflow-runner.yml`'s *Harden Stop-hook script sources* step overwrites each closure target in the PR-head workspace with the **trusted base-ref copy** (`git show FETCH_HEAD:…`), and where no base copy exists overwrites it with a **fail-closed no-op stub** — so the PR-head copy is not executed **through the base-hook channel this floor closes** (a scope the residuals below make precise; the floor closes the checkout-supply channel, not every path by which PR-head code could run). Fail-closed treatment differs by file class so a missing copy never breaks a legitimate hook: an **inline-sourced library** (`resolve-jq.sh`/`config-source.sh`/`resolve-bin.sh`/`telemetry-branch.sh`) runs *inside* the sourcing entry, so a missing trusted copy neutralizes the **entries** to stubs rather than installing a mid-`source` `exit 0` that would break them; an **entry** or a subprocess-**exec'd** dep is safe to stub directly. The installer is the suite-driven helper `scripts/harden-stop-hooks.sh` (whose `HOOK_TARGETS` closure a `lib/test/run.sh` drift-guard — the shared walker `scripts/detect-hook-closure-edges.py` — walks: a future added `source`/exec of a new helper turns the suite RED, including a **command-position** source edge such as a negation-guarded `if ! . "$dep"` or a brace-grouped `{ . "$dep"; }`, and a positive-control test asserts each such form is reported), run **only from a trusted source** (rank 1: base-ref materialized copy; rank 2: the vendored copy gated on `vendor_source == fetch`), and when no trusted helper resolves — **or when the helper reports a wholly-unwritable target it could neither trusted-copy nor stub (a non-zero exit)** — the step fails **closed** by stubbing every target inline (trusted workflow shell); and if even that inline stub write cannot land (a wholly-unwritable target), the step **fails the job** (`exit 1`) **before** `claude-code-action` runs, so no PR-controlled hook ever fires — the last-resort arm is genuinely fail-closed, never a warn-and-proceed. **Residuals (out of scope, not hardened — disclosed so the "closed channel" scope is not read as "no PR-head code can ever run"):** (1) the jq *program* `lib/efficiency-trace.jq`, fed to `jq -f`; `jq` is sandboxed (no shell/exec/arbitrary-write), so a PR-head `.jq` is not a shell/RCE vector, and it lies outside the `source`/`.`/`exec`/`python3` edge set this floor closes. (2) **In-session restore of the PR-head copies.** The review profile grants `Bash(git checkout:*)` and `Bash(tee:*)` (the Phase 3.2 dirty-tree backstop uses `git checkout`), so a *prompt-injected* review session could re-materialize the PR-head hook scripts (`git checkout HEAD -- lib/ scripts/`) after this step and before the Stop hooks fire. The floor closes the checkout-**supply** channel, not this agent-mediated one; the review token being read-only bounds the *GitHub-API-write* damage, but **not** secret exfiltration — the restored PR-head hook runs at Stop time inside the CI job, whose process environment carries the model API key and any other job secrets, so that exfiltration surface is the residual this channel genuinely carries. (3) **Reviewer-fidelity for a PR that edits a closure file (issue #504).** The step reverts the closure files to base bytes *before* the engine reads them, so a PR that legitimately edits one is reviewed against the base version of that file while `gh pr diff` still shows the head version. The refinement this issue ships surfaces the displaced set to the engine so those paths' HEAD verification no longer reads the base-ref/stub working-tree copy: the harden step publishes the displaced-path set (the `HOOK_TARGETS` members) plus a disposition token (`displaced` on every displacement arm, `skipped` + empty on the relevance-gate arm) as step outputs; a new `Compose CI summary` step runs *before* harden (so `summarize-ci-checks.sh` — which sources the closure member `lib/resolve-jq.sh` — runs pre-displacement, never against an `exit 0` stub); and the slimmed `Compose review prompt` step runs *after* harden, forwarding the displaced paths to `scripts/render-grounding-block.sh` as `HARDENED_PATHS`. The rendered engine-ground-truth block then carries a displaced-paths section stating the working-tree copy is base-ref/stub bytes (not the reviewed head) and that a HEAD claim about a listed path routes through `git show $PR_HEAD_SHA:<path>` and the Phase 0.2 cached diff, never a working-tree read — with a `git cat-file -e` → INCONCLUSIVE fail direction that is fetch-free on the review tier. The engine's seven claim-verification surfaces (Phase 2.1a lite-probe, Phase 2.1b `checklist-verifier` dispatch, the shared `defect_signature` truthfulness contract, Phase 4.1.6 sweep, and the `code-reviewer`/`comment-analyzer`/`checklist-verifier` agent mirrors) carry the routing rule; Phase 0.1 attributes displaced-path `git status --porcelain` output (content and mode-only deltas) to the floor instead of the generic uncommitted-changes warning. The displaced list is re-derivable in-session (Phase 0.1.5 persists it to `.prflow/tmp/`), so a compacted long run keeps the routing at the far end where the sweep executes; a run with no displaced list (local tier, manual `devflow.yml` path, consumer relevance-gate skip, fix-loop iteration) behaves exactly as today. The floor's displaced working-tree copies stay in place through session end — verification is read-only via `git show`, and neither the skill nor the workflow restores a displaced path's PR-head bytes (that would re-arm PR-head Stop-hook scripts inside the secrets-bearing job). **A newly widened reviewer-fidelity exposure (issue #805).** Since the PreToolUse guard joined the closure, that closure reaches into `lib/test/` for the first time — `lib/test/extract-command-shapes.py` and `lib/test/extract-command-heads.py` are the guard's importlib dependencies. Unlike the pre-#805 members (stable resolver/config helpers edited rarely), these two are **test helpers edited routinely**, including by the very pull requests that change the shape rules, so the displacement-to-base-ref-bytes described above now fires on a materially larger share of pull requests. The routing rule handles it correctly — a HEAD claim about a displaced path goes through `git show $PR_HEAD_SHA:<path>` — but the *frequency* of that route, not just its existence, is now the operative fact. The alternative, having the guard vendor its own arm predicates rather than importing a test helper at runtime, would trade this exposure for a duplicated predicate chain (the very duplication the one arm table exists to remove) and is deliberately not taken. The floor's unconditional `chmod +x` also surfaces a mode-only `100644`→`100755` delta on every closure member tracked non-executable (`lib/resolve-jq.sh`, `lib/resolve-bin.sh`, `lib/telemetry-branch.sh`, and — since the issue-#805 guard closure — `lib/test/extract-command-shapes.py` and `lib/test/extract-command-heads.py`) every run, even on a PR that touches none of them; Phase 0.1 attributes that mode-only delta to the floor too, so the engine no longer reports it as an uncommitted change. **Consumer relevance gate (issue #460 review):** `install.sh` ships `devflow-runner.yml` to consumers, but PRFlow's `.claude/settings.json` Stop hooks do not; the step therefore **no-ops** when the trusted base `.claude/` does not wire these hooks (decided via the trusted helper's tested `--wired-check` mode, keyed on the base ref, reading `.claude/settings.json` **and** `.claude/settings.local.json` — the two base-tracked files that can wire a Stop hook — so a wiring split across them cannot silently un-gate the floor), so a consumer's review never has the PRFlow-layout closure paths stubbed or created over same-named files. **One disclosed residual (FP-S1):** the gate lives on the *fetch-success* path, so a transient base-ref **fetch failure** in a consumer repo bypasses it and the step falls through to fail-closed stubbing — stubbing/creating the PRFlow-layout closure paths over any same-named consumer files during that (read-only, nothing-persisted) review. This is the deliberate *fail-closed-over-consumer-fidelity* trade: a fetch failure must never drop **PRFlow's own** protection, and it is far rarer than the common success path the gate covers. **A second disclosed assumption (Obs B):** the gate's correctness rests on *gate base == the base `claude-code-action` restores `.claude/` from*. `BASE_REF` is `github.event.pull_request.base.ref || github.event.repository.default_branch` (mirroring `baseprovision`); on the secrets-bearing CI-completion re-triggers (`workflow_run`/`status`/`check_suite`) the `pull_request` payload is absent, so it falls back to the **default branch**. The Stop-hook wiring is therefore assumed to live on the **default branch** (it does for PRFlow — the three hooks are wired on `main`); a repo that wired these hooks on a *non-default* target branch but not on the default could have the gate read "not wired" (default branch) and skip while `claude-code-action` restored the wiring from the actual PR base — the hooks would then fire from PR-head scripts. Not reachable for PRFlow or any consumer following the default-branch convention; documented so a future settings split does not silently un-gate. **Reachability & scope (verified against the workflows):** the exposure is confined to the **review runner** — the sole PR-head-checkout `claude-code-action` job — and is reachable by an untrusted PR chiefly via the secrets-bearing CI-completion re-trigger (`workflow_run`/`status`/`check_suite`), which runs in the default-branch/secrets context yet still checks out the PR head. The **implement** job needs no such floor: it checks out the **default branch** (never a PR head) and is authorization-gated, so its Stop-hook scripts — and its writable App token — are already trusted and never in reach of PR-author code. (Live-probe caveats, documented as unverified boundaries: that `claude-code-action` leaves the base hooks active in the review *profile* specifically, and that the pre-run workspace overwrite survives into the Stop-hook execution. On the *helper-resolution* axis the floor fails closed — no trusted source resolves ⇒ stubs, never the PR-head copy. The *survival* boundary is different in kind: if `claude-code-action` were to reset `lib/`/`scripts/` from the PR head after this step, the overwrite would be undone — but the action restores only sensitive paths (`.claude/`), not the general worktree, so survival is the expected behavior.)
- **Capability policy is generated from one versioned manifest, with the reviewer boundary locked (issue #561).** The five hand-maintained allowlist literals that scattered across the cloud workflows and the matcher-probe baselines are now **generated** from a single source of truth, `lib/capability-profiles.json` (an integer `manifest_version`, named token groups, and the `review`/`implement`/`command` profiles). `python3 lib/generate-capability-profiles.py` compiles the manifest into exactly five regions — the `devflow-runner.yml` review `TOOLS`, the `devflow.yml` command `TOOLS`, the `devflow-implement.yml` `--allowed-tools` base list, and the `matcher-probe.yml` `REVIEW`/`IMPLEMENT` baselines — each stamped with a banner comment carrying `manifest_version` + the sha256 of that region's resolved token list (the skew diagnostic in a support question). A `--check` mode wired into `lib/test/run.sh` (the required `lib + python tests` CI job) turns any manifest↔literal drift RED before merge, with a token-level directional diff so a grant hand-added to a workflow is never silently reverted by a blind regenerate. Because the generated review literal **is** the read-only reviewer allowlist (the deny floor above filters only appended consumer extras, never the base), the review profile is a security boundary: `lib/review-profile.tokens` locks its exact resolved token list, the generator never writes it, and any manifest edit — including to a shared group — that would widen the resolved review list fails generation and `--check` closed until that lock is updated in the same PR, so widening the reviewer always requires a deliberate, visible diff. The generator is python3 stdlib-only, reads no git history, and has no runtime footprint — generation happens at desk/CI time on the repo's own tree; consumer runs still resolve their baked literal shipped by file-copy, so no runtime workflow ever compiles policy from a reviewed PR's checkout. The probe's candidate rows, verdict tables, and command-shape verdicts stay hand-maintained — the manifest states policy, never measurement.
- **Read-only by default.** With `provision_env` off (the default), the reviewer is byte-for-byte read-only, it inspects the diff and cannot compile/lint/test. Turning it on is a documented opt-in that accepts running untrusted PR build code under a write token.
- **Self-trigger guard.** The implement workpad quotes the literal `/prflow:implement` phrase; the resolver declines any trigger text containing the workpad marker so PRFlow can't trigger itself in a loop.
- **Duplicate-run dedupe.** A thread-scoped dedupe ensures only the oldest concurrent `/prflow:implement` run on a thread proceeds. A parallel gate covers the command path: `devflow.yml`'s `review_dedupe` job suppresses a duplicate standalone `/prflow:review` while a review of the same **commit** is already in flight — detected from the review engine's seeded `prflow:review-progress` live-progress comment (`🚀 Reviewing`, bot-authored, liveness-bounded) via the bundled `scripts/dedupe-review-command.sh` helper (issue #989). The scope is the commit (issue #1010): the engine stamps the head it is reviewing into that comment at seed time as a distinct machine-only producer key, `<!-- prflow:review-seeded-head <sha> -->` — distinct because the comment's `Reviewed HEAD:` line means "a review *finished* at this head" and two consumers depend on that meaning — and detect mode requires an exact match against the head the requesting job resolves, so a review requested after a mid-review push proceeds. The recorded value is the API `headRefOid` captured before any caller head-override, which preserves the second of the two accepted costs `docs/workflow-triggers.md` enumerates; an in-flight comment carrying no such key (an installed copy predating the change) fails open. It fails open in every direction, never suppresses a `/prflow:review-and-fix` or a `prflow:review-backstop` auto-resume, and no-ops when the live-progress comment is disabled. See `docs/workflow-triggers.md`.

---

## 16. Observability: efficiency traces & telemetry

PRFlow instruments its own review runs so teams can see which reviewers actually earn their cost.

- **Per-iteration workpads** (`.prflow/tmp/review/<slug>/<run-id>/iter-<N>.json`) record each Phase-3 agent's findings, corroboration counts, and fix decisions, plus per-phase cost telemetry.
- At **Loop Exit**, `/prflow:review-and-fix` derives a per-subagent **effectiveness trace** and classifies each reviewer with a deterministic 4-way taxonomy: **unique-effective** (found a defect no one else did, and it was fixed), **corroborating** (found a fixed defect ≥2 agents agreed on), **noise** (raised findings, none applied), **null** (silent / out-of-scope only).
- One **durable** JSON record per run is persisted to a dedicated **telemetry branch** (`prflow-telemetry`, configurable via `telemetry.branch` — issue #441) at `.prflow/logs/efficiency/<slug>-<run-id>.json`, keyed by the run's `<run-id>` (the same discriminator that scopes the workpad directory), so it is one file per run and parallel writers never collide. The write goes through git plumbing to a long-lived orphan branch that shares no history with `main` — **never touching the current branch, `HEAD`, or the working tree** — so a local run no longer diverges local `main`, and durability no longer depends on whichever branch the run sat on being pushed and merged. The run-id key (not a fresh timestamp) is also what lets the persistence backstop be idempotent, tested by record presence **on the branch** (next bullet).
- **Non-droppable persistence (layered).** The per-iteration `iter-<N>.json` emit is a **non-optional obligation on every iteration, regardless of how the loop was executed** — whether `/prflow:review-and-fix` ran as a `Skill` invocation or was hand-run via direct `Agent` dispatch on a degraded path (a cloud `claude-code-action` permission/sandbox denial is never license to leave the instrumented loop) — written with the Write tool (the dependable authoring path into `.prflow/tmp` from this loop's profile, and the one this emit must use), and **fused to the fix-commit moment** (Layer 1: capture the fix commit's SHA, then Write, as one step — the one mechanical point every fix iteration passes through, so an inline-driven loop has no seam in which to lose the emit). On top of that emit, the record and the durable workpad copy survive even when the loop is driven inline by an orchestrator that skips the Loop Exit bookkeeping: a warn-only **self-check** at Loop Exit flags a dropped persist (Layer 2), and a deterministic `lib/efficiency-trace.sh --persist` backstop re-derives the artifacts from the on-disk `iter-<N>.json` workpads and persists them to the telemetry branch (Layer 3). And when even the workpads are gone — a run that left **zero** `iter-*.json` — `--persist` **synthesizes** minimal iteration records from the branch's `fix: address review findings (iteration N)` commits (Layer 3+, the synthesis floor): `iter` / `fix_commit_sha` / `fix_files` / `loop_role` / `synthesized: true`, guarded against double-counting and misattribution, telemetry-gated, and marked `synthesized` in the derived record so a reconstructed floor is never mistaken for an agent-written record. The floor recovers only the effectiveness skeleton — never license to skip the emit, which alone carries the checklist / findings / cost detail. This makes the **effectiveness** half of the telemetry (dispatch counts, findings, verdicts, fix decisions) recoverable; the **token/wall-clock cost** half is captured *live* by the loop. Issue #437 observed that the cloud `execution_file` carries the tokens, wall-clock, the subagent dispatch roster, and cost with **zero agent cooperation**, and — on the local tier — that the `Stop`-hook transcript's per-message token counts are **real** figures, not streaming placeholders (wall-clock and the dispatch roster were *not* measured locally; see [`docs/execution-file-shape.md`](execution-file-shape.md)), so an agent-independent cost floor is buildable. **Issue #475 builds the cloud half (Layer 4, the harness-side cost floor):** on each writable cloud workflow, `--persist` reads the harness-written `execution_file` (via `scripts/extract-execution-cost.py` + `scripts/prepare-harness-floor.sh`) and lands its cost as a per-run `harness_cost` record field — the first floor NOT fed by an agent-volunteered operand, so a cloud run that dropped every telemetry emit still contributes a cost record. Two boundaries remain: a hard-death run that never produced an execution file stays uncovered (announced by a named breadcrumb, never silent), and the read-only auto-review tier is cost-unmeasured by this floor (no persist path there yet). On the **local** tier the cost half is still captured only by the live loop. See [`docs/efficiency-trace.md`](efficiency-trace.md).
- **Auto-review telemetry relay (cross-workflow, consumer-shipped — issues #489, #502).** The read-only auto-review tier runs on the PR head with `contents: read`, so it cannot push: instead its `devflow-runner.yml` collect step **stages** its observability records and uploads them as a workflow artifact, and a separate **trusted** workflow — `telemetry-push.yml`, triggered by `workflow_run` off the auto-review's completion so its own code comes from the default branch — downloads that artifact, validates it as untrusted PR-influenced input, and pushes the records to the telemetry branch. This is the GitHub-secure pattern for handling data a PR-triggered run produced: the auto-review job never gains a write credential. The relay **ships to consumers** — `install.sh` copies `telemetry-push.yml`, and both the collect step and the pusher resolve their bundled helpers at the vendored `.prflow/vendor/prflow/scripts/…` path (materialized by the `vendor-plugin` action, with a repo-root fallback for PRFlow's own checkout) rather than a repo-relative `scripts/` path that would be absent in a consumer's vendored install.
- A configurable `efficiency_cut_candidate_min_dispatch` (default 3) governs when a persistently unhelpful agent is flagged as a candidate to cut (consumed by a follow-up cross-run analyzer).
- **Live progress comment:** in PR mode, `/prflow:review` authors a single run-keyed comment that updates incrementally, a blueprint up front, then per-phase results as they land.

All telemetry is gated by config (`prflow_review_and_fix.efficiency_telemetry_enabled`, `prflow_review.live_progress_comment_enabled`, both default `true`) and is **best-effort**: a telemetry failure never aborts the loop.

**The measurement substrate: the unified experiment record.** A run's *cost* (tokens, iterations, agent verdicts) lands on the `prflow-telemetry` branch under `.prflow/logs/efficiency/`, while its *outcome* (the first independent review's verdict and Important-finding count) lives in GitHub's review history — two stores with no per-PR join, so a before/after comparison of a config change could not be measured. `scripts/build-experiment-records.py` (invoked by `/prflow:retrospective-weekly` between Materialize and the state PR, on the local/interactive tier only, after it fetches the telemetry branch) assembles the join: one tracked line per merged PR in `.prflow/learnings/experiment-records.jsonl`, joining **all** of the PR's efficiency records — read as a `(slug, run-id)`-keyed **union** of the telemetry branch and any legacy tracked `.prflow/logs/`, branch-wins — (both slug families, as a per-run cost list — never newest-wins) to its retrospective entry, its shape-selected review **verdict** (with a progress-comment fallback and a null-verdict arm), the **Important-finding count** (parsed from the run-keyed progress comment via the engine's own `review.commit_id` ↔ `Reviewed HEAD:` join), the **permission-denial count** (made durable and API-retrievable by including it verbatim in the `Devflow Review` check-run summary — `unavailable` stays `unavailable`, never coerced to `0` — with a positive-count-only annotation fallback for historical PRs), and a **config fingerprint** naming the config variant that produced the run. A `telemetry_complete` flag on each entry in `efficiency_runs[]` lets analyses exclude degraded runs rather than silently averaging them, and a `provenance` map keeps a `null` field distinguishable from an unqueried one. The assembler is idempotent (keyed by PR), incremental (never a full-history sweep), and missing-source-tolerant. See [`docs/efficiency-trace.md`](efficiency-trace.md) for the store schema and the abandoned-run cost-side bias.

**Local workflow flight recorder.** For interactive performance R&D, Claude's native project JSONL is the transcript source of truth. A fail-open `UserPromptSubmit` observer writes metadata-only start manifests under `.prflow/tmp/workflow-manifests/`; a read-only inventory selects only sessions whose first authoritative user message invoked a registered workflow, including approved short aliases and corroborated embedded invocations; and an explicit session-ID import creates or refreshes the sensitive, byte-verified bundle under `.prflow/tmp/workflow-runs/`. Restart active Claude Code sessions after changing the local hook configuration. Generalized `.prflow/tmp/workflow-runs/` and legacy `.prflow/tmp/implement-runs/` bundles remain readable, while Claude owns native transcript retention. Analysis is read-only; recurrence requires at least two distinct sessions with the same workflow, mode, and prompt fingerprint, never pools two occurrences from one session as independent evidence, and never files issues automatically. See [`docs/workflow-flight-recorder.md`](workflow-flight-recorder.md).

**Verification-launch baseline (Wave 1, issue #527).** An offline analyzer
(`scripts/verification_baseline.py`) extends this recorder foundation into a
read-only, source-provenanced baseline of actual verification launches from local
native transcript events, plus a local + cloud lifecycle census (eligibility +
source missingness) that is independent of transcript survival. It is pure Python
standard library with no subprocess, no network, and no model/provider call;
`workspace_state` coverage comes from explicit source-event results, not
analyzer-time inspection. Repeated launches are classified conservatively as
`single`, `candidate_transport_retry`, `intentional_rerun_evidence`,
`independent_lifecycle`, or `unclassifiable` — never as automatically proven
duplicates — and a deterministic SHA-256-seeded manual-review sample selects
relationship groups for human adjudication. Cloud launch analysis is excluded in
Wave 1; cloud rows are census/missingness-only from an explicit Actions snapshot
(`scripts/export-workflow-lifecycle-census.py`, the sole networked step). Output
is local and gitignored under owner-only `0700`/`0600`. See
[`docs/workflow-flight-recorder.md`](workflow-flight-recorder.md#verification-launch-baseline-wave-1).

---

## 17. Configuration reference

The local tier needs **no config**. To customize, `/prflow:init` scaffolds `.prflow/config.json` (JSON, read by a single python3-based resolver, no `yq`/PyYAML/Node prerequisite for config) and a `config.schema.json` your editor uses for autocomplete. Top-level keys:

| Key | Purpose |
|---|---|
| `base_branch` | Review/merge base (default `main`). |
| `claude_model` | Default model (default `claude-opus-5`). |
| `providers.<name>` | Cloud-tier (opt-in): Anthropic-compatible third-party endpoints — `base_url`, `auth` (`bearer`\|`api_key`), `timeout_ms`, `effort_supported`, and an `env` map. The API credential is never named in config — it is always the fixed `DEVFLOW_PROVIDER_API_KEY` repo secret. See §14 / `docs/cloud-setup.md`. |
| `devflow.provider` / `prflow_implement.provider` / `prflow_runner.provider` (+ each section's `claude_model`) | Cloud-tier (opt-in): route that workflow section through a named `providers` entry and/or override its model, independently per section. Unset → today's Anthropic-OAuth default. |
| `prflow_version` | Cloud-tier: git ref the workflows fetch the plugin from (thin install). |
| `devflow.allowed_bots` / `allowed_users` | Trigger authorization (also the trusted-filer allowlist). |
| `devflow.workpad_marker` | Workpad comment marker. |
| `devflow.effort` / `allowed_tools` | Light command path settings. |
| `devflow.execution_diagnostics_enabled` | Gates cloud-tier surfacing of a `claude-code-action` run's execution diagnostics — the run summary (`is_error`, `num_turns`, `duration_ms`, `total_cost_usd`, `permission_denials_count`) plus permission-denial detail — to the job log and `$GITHUB_STEP_SUMMARY` via `scripts/surface-execution-diagnostics.sh`. A read-only diagnostic: never changes a job's pass/fail result, adds no token scope, uploads no artifact. Default `true`. (Read by the `Surface execution diagnostics` step in each cloud-tier workflow.) |
| `devflow.attribute_commits_to_triggerer` | Opt-in (default `false`): on the cloud-tier **writer** runs (`/prflow:implement`'s `claude` job and `/prflow:review-and-fix`'s `command` job), author the agent's git commits as the human who triggered the run, so `git blame`/history show the responsible human — parity with local runs. Read at TRIGGER time from the trusted default-branch checkout (never the PR head), so its effect is **post-merge-only**. Humans only, fail-safe: identity is emitted only for a `.type == "User"` login without the `[bot]` suffix; any other type, a `[bot]` login, or an unestablished type falls back to current authorship with a warning. Fail-open — advisory, never gates the run — and needs no new credential (commit author/committer is git metadata, independent of the push token). The read-only review tier never commits and is untouched. Resolved by `scripts/resolve-committer-identity.sh` via the `Resolve committer identity` step in each writer workflow. See §14 / [`docs/cloud-setup.md`](cloud-setup.md). |
| `prflow_implement.effort` / `allowed_tools` | `/prflow:implement` settings. |
| `prflow_implement.update_branch_checkpoints` | Base-branch update checkpoints (boolean, default `true`; disabled exactly when the value serializes to the string `false` via `config-get.sh` — an explicit JSON `false`, the JSON string `"false"`, or `[false]`; anything else leaves them enabled — issue #312 valid-falsy). When on, `/prflow:implement` brings its feature branch up to date with `base_branch` at four checkpoints — the end of Phase 1.4, pre-draft-PR (Phase 3.1), each fix iteration + Loop Exit of the review-and-fix loop under `--push-each-iteration`, and pre-ready (Phase 4.3) — through the shared `scripts/update-branch-checkpoint.sh`, so every state the merge gate or an auto-review consumes (including the terminal pushed state) is current. Since issue #779 the Phase 1 checkpoint is **arm-independent**: it is the last step of §1.4 and runs on the new-branch, adopted-branch, and landed-resume arms alike (so Phase 1 reconciles with the base on **every** path reaching Phase 1.5 — a resumed run can no longer proceed on a stale base), while §1.4's freshness record **remains adopted-arm-only** (§1.4.0.5's Verdict B classification was widened to the landed-resume arm by issue #780). Correspondingly, Phase 4.3 gates publication and the `Complete` flip on a clean checkpoint-4 token — see [`docs/implement-skill.md`](implement-skill.md). This key **also governs the checkpoint inside a standalone `/prflow:review-and-fix --push-each-iteration` run.** See §14 and [`docs/implement-skill.md`](implement-skill.md). |
| `prflow_runner.provision_env` / `effort` / `allowed_tools` | Automated-reviewer build-environment opt-in + tools. |
| `prflow_review.live_progress_comment_enabled` / `agent_overrides` | Review engine: live comment + per-subagent model/effort. |
| `prflow_review.verdict_severity_threshold` | Moves **only** the REJECT line of Phase 4.2 (enum `critical/important/suggestion`, default `critical`): a finding at or above it, excluding deferral-demoted ones, drives REJECT; every other Phase 4.2 rule and verdict label is untouched. Both standalone `/prflow:review` and the Phase-3 pass of `/prflow:review-and-fix` inherit it. A bad/absent value falls back to the default with a breadcrumb (never aborts). Threshold-independent carve-outs sit above the numbered rules and are unaffected by it — see §8 (and the Phase 4.1.5 behavior-inert prose cap, which fixes a covered finding's severity at Suggestion so the default threshold does not REJECT on it). |
| `prflow_review.require_up_to_date` / `require_ci_green` | Auto-trigger preconditions (default `true`): defer the review — a neutral "waiting" `Devflow Review` check — while the PR branch is behind base / other CI on the head is pending or red; `false` restores the unconditional trigger. `require_ci_green` collapses the non-self Actions runs to the latest per `(workflow_id, event)` group before gating (a superseded run never wedges the review), and a run awaiting manual approval (`action_required`) defers with the distinct `ci-approval-required` reason. See §14. |
| `prflow_review.stale_prose.enabled` / `severity` | Phase 0.6 deterministic stale counted-prose lint (`enabled` default `true` — only an explicit `false` disables; `severity` default `important`, enum `critical/important/suggestion`). Each STALE row becomes a Phase 4.2 finding at `severity`; a refused/absent/errored/disabled helper degrades to a recorded note, never a stall or silent skip. |
| `prflow_review.stall_backstop.enabled` / `max_resume_attempts` | No-verdict auto-resume backstop (default `enabled: true`, `max_resume_attempts: 2`): when a cloud review ends with no verdict for the head, post a bounded App-token-authored `/prflow:review` re-trigger so it re-runs without a human; degrades to the dead-end flip when the cap is exhausted, disabled, or no App token is configured. The review-side sibling of `prflow_implement.stall_backstop`. |
| `prflow_review_and_fix.fix_severity_threshold` | The `/prflow:review-and-fix` loop routes to the fixer every finding at or above this severity (enum `critical/important/suggestion`, default `important`); findings below it stay advisory. Independent of `prflow_review.verdict_severity_threshold`, except that every REJECT-driving finding is always fixable regardless of this key — so a Phase 4.1.5 capped Suggestion still reaches the fixer at `suggestion` while driving no REJECT at the default verdict threshold. A bad/absent value falls back to the default with a breadcrumb (never aborts). |
| `prflow_review_and_fix.efficiency_telemetry_enabled` / `efficiency_cut_candidate_min_dispatch` | Telemetry. |
| `receiving_review.fix_severity_threshold` | Consulted **only** by a direct invocation of `/prflow:receiving-code-review` (the `/prflow:review-and-fix` loop governs its own routing via `prflow_review_and_fix.fix_severity_threshold` and does not read this section). When the verdict is already non-blocking, the diff is re-opened for a finding at or above this severity (enum `critical/important/suggestion`, default `critical`). The demonstrable-correctness-defect / documented-falsehood carve-out re-opens the diff at every threshold value — a correctness principle, not a severity grade — with behavior-inert prose excluded from its scope (graded by severity like any other finding). A bad/absent value falls back to the default with a breadcrumb (never aborts). |
| `telemetry.branch` | Name of the dedicated orphan branch every writable run persists observability artifacts to (default `prflow-telemetry`, issue #441); auto-created on first use, verified logs-only before appending. Keep workflow `push:` triggers `main`-filtered so a push to it runs no CI. |
| `setup.*` | Cloud-tier runtime provisioning (versions, services, install lines). |
| `docs.*` | Doc paths, enable flags, release-notes file, CHANGELOG file, labels. |
| `prflow_retrospective.*` | Weekly loop settings (watched authors, min occurrences, cooldown, etc.). Detection is by the reserved `PRFlow` label (its superseded `DevFlow` spelling is still accepted) + a closes-issue fallback (see §12); `implementation_branch_prefix` is an **optional** extra match path, not the detection mechanism, and may be left empty. |
| `workflows.*` | Per-workflow enable/disable toggles. |

`/prflow:init` auto-detects languages (Node, Go, Rust, Java, Ruby, PHP, .NET, Make, Docker) and merges matching build/test/lint tools into three independent allowlists, plus the `setup` block, idempotently (your values always win).

Re-running `/prflow:init` (or `install.sh`) also **backfills** newly-added keys into an existing `.prflow/config.json` without clobbering your values. Backfill is add-only, so it cannot propagate a key *removal*; for the one case where that matters — a `prflow_review.agent_overrides` entry pinning Claude Haiku must not carry an `effort` key, which Haiku rejects with HTTP 400 — re-scaffold runs a separate idempotent cleanup that strips `effort` from any Haiku-pinned override (see [review-agent-overrides.md](review-agent-overrides.md)). An already-clean config is left byte-identical.

After scaffolding and the dependency preflight, `/prflow:init` runs one final **advisory project-memory check**: if the repo root has no `CLAUDE.md` it nudges you toward the built-in `/init` (project memory measurably improves PRFlow's review/implement results), and it points any agent-instruction files you already keep for other tools (`.github/copilot-instructions.md`, `AGENTS.md`, `GEMINI.md`, `.cursorrules`) at `CLAUDE.md` `@`-import reuse. The check is strictly advisory — it never writes or edits any file and never blocks init (which has already succeeded), and stays silent when nothing is actionable.

---

## 18. Installation & updates

**Local tier (one line):**
```bash
claude plugin marketplace add The01Geek/prflow \
  && claude plugin install prflow@devflow-marketplace
```
PRFlow declares **zero companion-plugin dependencies** (every external asset it once dispatched is now first-party — see §6), so `/plugin install` resolves on its own with no `claude-plugins-official` prerequisite. PyYAML is a separate, manual extra (`python3 -m pip install PyYAML` — by package name; a relative `-r requirements.txt` resolves against the user's working directory, not the plugin cache); `/plugin install` never runs `pip`. On the local tier it is advisory rather than a hard prerequisite — a missing PyYAML degrades one runtime helper and `bash lib/preflight.sh` reports it but exits 0 (it stays required for the test suite, CI, and the cloud tiers).

The plugin install above runs **no installer script** — `install.sh` belongs to the optional cloud tier only, and a local-tier-only user never runs it.

**Cloud tier (optional, from repo root)** — download, read, then run, with both refs pinned to a release tag:
```bash
curl -fsSL https://raw.githubusercontent.com/The01Geek/prflow/v2.30.9/install.sh -o devflow-install.sh
# review devflow-install.sh, then:
DEVFLOW_REF=v2.30.9 bash devflow-install.sh
```
The URL ref fixes which installer bytes you review and run; `DEVFLOW_REF` (default `main`; a tag, SHA, or branch) fixes which ref the installer clones its payload from — pinning the URL alone leaves the payload on `main`. Substitute a newer tag in both places to move the pin; every version is tagged, so the [Tags page](https://github.com/The01Geek/prflow/tags) names the current one, while the [Releases page](https://github.com/The01Geek/prflow/releases) announces the feature releases — see [`docs/install.md`](install.md#pinning-the-installer). Piping the download straight to `bash` works but forfeits the review step. Thin by default (installs workflows, actions, a local marketplace, a config scaffold, and pins `prflow_version`). `DEVFLOW_VENDOR=1` commits the tree instead.

**Updates:** local tier, `/prflow:init` provisions the project `.claude/settings.json` — it registers `devflow-marketplace` under `extraKnownMarketplaces` with `autoUpdate: true` and enables the plugin under `enabledPlugins`, so Claude Code keeps the plugin updated (additive and non-clobbering, idempotent on re-run); it never sets `permissions.defaultMode`. Selectable `auto` mode is provisioned **separately, at user scope, only with explicit consent, and only on a third-party model provider**: `CLAUDE_CODE_ENABLE_AUTO_MODE` is honored only from user scope (`~/.claude/settings.json`) or managed settings, so the project provisioner skips it (writing it there is a silent no-op) and a dedicated helper (`scripts/provision-auto-mode.sh`, run by `/prflow:init`) merges it into `~/.claude/settings.json` after asking the user — making `auto` **selectable, never on** (no `permissions.defaultMode`, plan/model/admin gates still apply), preserving a deliberately-disabled `"0"`, idempotent/atomic/fail-closed, and printing the one-line setting instead of writing if the user declines. The env var has **no effect on the Anthropic API** (auto mode is already available there by default) and only does anything on Amazon Bedrock / Google Vertex AI / Microsoft Foundry, so the whole step is gated on the provider: it runs only when one of `CLAUDE_CODE_USE_BEDROCK`/`VERTEX`/`FOUNDRY` is truthy and is skipped entirely on Anthropic-direct. The gate is two-layer — the skill pre-checks the provider and skips the prompt silently, and `provision-auto-mode.sh --apply` enforces the same check as a deterministic backstop (it leaves the settings file unchanged and exits 0 with a breadcrumb on Anthropic-direct). This is local-tier only — the cloud tier neither needs nor receives a `.claude/settings.json`. Cloud tier, bump `prflow_version` or re-run `install.sh` (re-running only re-stamps `prflow_version` itself when eligible — a hand-set non-SHA value is preserved; see `docs/cloud-setup.md`).

---

## 19. Repository layout

```text
.claude-plugin/
├── plugin.json          # plugin manifest (declares dependencies)
└── marketplace.json     # this repo is its own marketplace
skills/                  # one SKILL.md per skill
├── implement/phases/    #   /prflow:implement's per-phase reference files
├── implement/references/ #  /prflow:implement's predicate-gated references
└── review/phases/       #   the review engine's gated per-phase references (§8)
agents/                  # checklist-generator / -deduper / -verifier
scripts/                 # branch-for-issue.py, config-get.sh, ensure-label.sh,
                         #   apply-labels.sh, file-deferrals.py, match-deferrals.py, parse-acs.py,
                         #   workpad.py, …
lib/                     # retrospective-loop helpers (*.sh, *.jq), preflight.sh, test/
.github/                 # cloud tier: workflows + composite actions (incl. vendor-plugin)
.prflow/                # config.example.json + config.schema.json (+ learnings/, logs/)
docs/                    # cloud-setup.md, implement-skill.md, workflow-triggers.md,
                         #   efficiency-trace.md, shadow-review.md, review-agent-overrides.md
install.sh               # one-command cloud-tier install/update
```

Skills reference bundled helpers via the portable single-statement anchor (`$CLAUDE_SKILL_DIR` preferred, runner-reported base directory fallback — see §6) so they resolve from any install location and runner. The complete suite runs with `bash lib/test/run.sh` (CI runs it on every PR). For local iteration, cohesive test blocks may also be registered under `test_modules` in `scripts/workflow-flight-recorder-registry.json` and run explicitly with `bash lib/test/run-module.sh <module-id>`.

**Cloud-writer reachability contract (issue #543).** `lib/test/cloud_writer_contract.py` is a machine-auditable source of truth for the three cloud execution roots (implement / light-command / review) and their transitive skill/phase closure. Its `check_closure()` guard fails when a root or dispatch edge reaches an asset that is not classified (or a classified asset that is missing on disk), and its `verify` CLI — driven by the suite — pins the checked-in `devflow-cloud-writer-contract-v1` runtime manifest (`scripts/devflow-cloud-writer-contract.json`, which SHA-256-pins every reached skill asset — `SKILL.md`, `phases/*.md`, `references/*.md`, and reviewer prose — plus every required helper) against that same closure, so the manifest can never silently drift from the closure it describes. This makes the manifest a coupled invariant: regenerate it in the same commit with `python3 lib/test/cloud_writer_contract.py generate` whenever you edit a reached `skills/**`, `scripts/**`, or `lib/**` asset it lists, or the required `lib + python tests` check goes red. A second guard, `check_grant_sync()` (exposed as the `grant-sync` subcommand and driven by the suite), maps every helper literal reachable in that closure to the three current cloud profiles — implement, light-command, and review — and fails when a reachable literal lacks an explicit vendored grant, or when any other grant *covering* a reachable helper widens the executable trust boundary beyond that literal — an absolute or repo-root path, a basename or directory wildcard, a PATH-resolved bare name, or any other shape that still reaches the helper (the guard's own docstring is the authoritative class list; deliberate exceptions are registered **per profile** in `SANCTIONED_WILDCARD_GRANTS`, since a globally-scoped exemption would re-open the widening class for whichever profile does not carry the exempted grant). The grant source it reads is scoped to each profile's own grant-bearing region — `devflow-implement.yml`'s `--allowed-tools` block, the `TOOLS='…'` line elsewhere — located with `lib/test/extract-command-heads.py`'s scopers, so a vendored literal named only in a `run:` echo or a doc string cannot satisfy the granted arm for a helper the profile does not actually grant; a region that cannot be located fails closed as an unavailable grant source rather than falling back to the whole file. Its remaining documented scope limits — interpreter/wrapper heads, which every live profile legitimately grants, and grants spliced in by consumer config — are recorded at the guard, which is the authoritative enumeration. A third guard, `check_shape_conformance()` (exposed as the `shape-conformance` subcommand and driven by the suite), applies `lib/test/extract-command-shapes.py`'s probe-anchored rule tables to every fenced command in that closure, keyed by each profile whose own reach includes the asset — so a denied command shape in a reached asset is caught at the desk even when no file-glob scan names it. The profile→table mapping is explicit: a profile with no probe baseline of its own (`light-command`) is declared as carrying no table rather than borrowing another tier's evidence, and a profile with no declaration at all is reported, never silently unaudited. A fourth guard, `check_helper_boundary()` (issue #701; built on `extract-command-heads.py`'s `helper_boundary_violations`), requires the vendored helper path to be the first executable token of every cloud-reached fenced command that names a per-helper-granted bundled helper — rejecting, by classified reason, an unexpanded anchor, an absolute or repo-root path, a helper behind any other prefix, or a helper behind a granted launcher head (`env`/`xargs`/interpreter/process-wrapper) whose broad grant would otherwise mask the per-helper vendored grant; the launcher table is generated from each profile's parsed grants so it can never drift from the tier it governs. The decision record — including why AC2/AC3 were restated against the emission-time surface rather than amending the portable-anchor convention — is [`docs/cloud-writer-boundary.md`](cloud-writer-boundary.md). `scripts/validate-cloud-writer-contract.py` is the companion pre-agent manifest validator whose rejection matrix is closed at exactly seventeen classes; its runtime pre-agent wiring is deferred to follow-up work.

**Focused review-and-fix iteration.** For the local review-and-fix contract loop, run `bash lib/test/run-module.sh review-and-fix-contract`. Selection is explicit: consulting the coverage map (`lib/test/modules/coverage-map.json`) to identify a candidate module is part of explicit selection — record the entry consulted and confirm the ID in the registry — while changed files never auto-route to a module. Cloud runs use `lib/test/run-module.sh <module-id>` when the tier grants it and a registered module covers the fix; otherwise they use the already-permitted complete suite. Focused verification is the iteration default: a focused pass covering the changed surface is sufficient for an intermediate commit or push. Two tiers of focused test qualify (issue #789): a registered shell module, and — for a `scripts/*.py`/`lib/*.py` unit — the `lib/test/test_*.py` file its coverage-map entry names in a `focused_test` field, invoked as a direct leading token (`lib/test/test_python_scripts.py`) rather than `python3 <path>`, the interpreter-head shape the cloud matcher denies, so the same command runs on both tiers. The complete suite runs mid-iteration only for a surface no focused test covers, and then only on its first cycle: a second mid-iteration cycle on that same uncovered surface extracts a durable module instead. A run that takes the complete suite mid-iteration records a `## Devflow Reflection` bullet naming which closed-set case applied, and a mid-iteration issue-#434 stale-prose `blocking-gate` skip on a dirty tree is expected rather than a reason to re-run. The final gate is preserved and, on the local/interactive and reception/shepherd tiers, parallelized: before a completion or PR-ready claim, push to trigger CI and start the complete suite plus every required lint gate locally at the same time — the push is not gated on the local run finishing, but the completion claim is — the run reads that local run's summary before claiming, and a nonzero failure tally, a nonempty skip tally, or a run that never started is not a completion. The local run remains the authoritative local signal because its failure detail is richer than CI's. Skips are not clean. The cloud `/prflow:implement` in-env gate (issue #405) is unchanged: such a run verifies in its own environment and never waits on, polls, re-checks, or cites CI for its own progress.

**Disposable verification-rig reuse (issue #754).** The focused-module iteration default above covers *pre-registered* test modules, and Phase 2.2.4's *Reuse & Altitude* plan gate covers *production* code. A third case falls between them: a throwaway rig a run builds mid-iteration purely to exercise code in isolation — a scratch repo to drive a git-consuming helper, a fixture config to drive a config reader, an interpreter/CLI wrapper that calls a helper with crafted argv (an illustrative floor, not a closed list). Three verification/fix-iteration surfaces now name that case in per-surface-adapted wording: `skills/implement/phases/phase-2-implement.md` §2.3, `skills/review-and-fix/references/fixing.md` Step 3, and the vendored `skills/receiving-code-review/SKILL.md` verification gate (whose copy is strictly repo-agnostic). Each says: keep the rig under an already-ignored scratch path (`.prflow/tmp/…` internally; a consumer-ignored scratch path in the vendored body) so the terminal `git add -A` never stages it — a nested `git init` rig left elsewhere lands as a gitlink — record its location on the channel that surface actually has (a workpad `--note` when implement-driven, the run-scoped `.prflow/tmp/review/<slug>/<run-id>/…` record on a standalone review-and-fix run, a run-persisted channel where the consumer flow offers one), and reuse it on the next iteration instead of rebuilding it — but **only after confirming it still exercises the current code shape**. When that shape has changed, rebuilding is the correct move: a rig keyed to a superseded shape drives paths that no longer exist and yields a false GREEN. This is advisory prose at the same altitude as the two rules it sits beside; it adds no gate, command, config key, or tool grant.

**Focused create-issue iteration.** For the local `/prflow:create-issue` contract loop, run `bash lib/test/run-module.sh create-issue-contract`. It carries the extracted Step 3.6 audit, state-owner cutover, authoring-discipline, and revision-delta contracts (with a provenance map in `lib/test/modules/create-issue-contract.inventory.md`). The same explicit-selection and focused-default-plus-parallelized-final-gate discipline applies as for review-and-fix above.

**Focused capability-profiles iteration.** For the local #561 capability-profile-generator loop, run `bash lib/test/run-module.sh capability-profiles`. It carries the extracted `lib/generate-capability-profiles.py --check` coverage — the manifest and region adversarial matrices, planted-defect controls, idempotency/determinism, no-runtime-read, and the PR #588 hardening rows (provenance in `lib/test/modules/capability-profiles.inventory.md`).

**Focused installer/workflow-wiring iteration (issue #695).** For the local installer and workflow-wiring loop, run `bash lib/test/run-module.sh installer-wiring`. It carries the `install.sh` and cloud-workflow wiring coverage extracted as a syntactic unit from `lib/test/run.sh` — the gh-wrapper/token-refresher workflow wiring and its step ordering, the installer's output validation and guard recipes, fingerprint-comparison symmetry, workflow-token and secret-file permission pins, and the Windows mode-probe arms (provenance in `lib/test/modules/installer-wiring.inventory.md`). The same explicit-selection and focused-default-plus-parallelized-final-gate discipline applies as for the modules above.

**Focused harness Python-guard iteration (issues #707 and #810).** For the monolith-only Python guards whose subject is a single code unit and whose verification is self-contained, run `bash lib/test/run-module.sh harness-python-guards`. It carries the driver blocks extracted from `lib/test/run.sh` for the `#600` create-issue audit-prompt renderer, the `#527` verification-launch baseline analyzer, the `#528` single-flight verification ledger, the `#668` reception-identity producer, and the `#591` coverage-map ratchet guard — the last as both its live-tree invocation and its unit test, plus a planted coverage-map drift as a positive control that the module goes RED when that guard breaks. It also drives the focused `pin-corpus-lint.py` unit suite: typed declaration parsing, path-aware complete-site scoping, helper/raw wording-pin parity, classification-preserving moves, registry population closure, and injected fail-closed setup failures. The raw-presence coverage includes positive fixed-and-quiet shell `grep` guards over repository files and direct file-text assertions in tracked or untracked `lib/test/test_*.py` leaves; an uninspectable typed target is a finding, not an exemption. The production pin scan remains a whole-tree required gate in `run.sh`; the focused module tests its logic without running the maintainer census or reading its inventory (provenance and deliberate exclusions are in `lib/test/modules/harness-python-guards.inventory.md`). The guards that test the module system itself (`lib/test/test_module_runner.py`, `lib/test/test_module_harness.py`) remain unextracted because a module running them would be circular. The same explicit-selection and focused-default-plus-parallelized-final-gate discipline applies as for the modules above.

**Focused workflow-flight-recorder iteration (issues #563/#566).** For the local workflow-flight-recorder loop, run `bash lib/test/run-module.sh workflow-flight-recorder`. Authored natively alongside the selectable-module machinery rather than carved out of `lib/test/run.sh`, it drives `test_workflow_flight_recorder.py` and `test_workflow_analyzer.py` through `devflow_run_focused_python_test` (provenance in `lib/test/modules/workflow-flight-recorder.inventory.md`). The same explicit-selection and focused-default-plus-parallelized-final-gate discipline applies as for the modules above.

**Focused regenerate-artifacts iteration (issue #619).** For the local generated-artifact regeneration loop, run `bash lib/test/run-module.sh regenerate-artifacts`. A new module (not an extraction), it covers `lib/test/regenerate-artifacts.py` — building each per-assertion fixture from the git index alone (see *Tracked-only module fixtures* below) and pairing its bash builder with an independent `python3` oracle (provenance in `lib/test/modules/regenerate-artifacts.inventory.md`). The same explicit-selection and focused-default-plus-parallelized-final-gate discipline applies as for the modules above.

**Focused iteration over the first extraction tranche (issue #746).** Four further modules were carved out of `lib/test/run.sh` as a measured tranche, chosen by dependency cost rather than line span: `review-trigger-helpers` (eleven consecutive sections covering the review/implement trigger helpers, from the `#249` verdict deriver through `resolve-command-trigger.sh`), `experiment-records` (the `#431` unified experiment-record join), `review-stall-backstop` (the `#408` no-verdict auto-resume backstop and the `#414` post-and-annotate helper), and `prompt-extension-reader` (the consumer prompt-extension reader). Run each with `bash lib/test/run-module.sh <module-id>`; provenance is in the paired `lib/test/modules/<module-id>.inventory.md`. The `experiment-records` extraction is **deliberately partial** — the section's trailing `#431 producer pins` tail stays in `lib/test/run.sh` because it asserts against files that helper does not own, so the `#431` coverage-map label correctly remains `unmodularized`. Some contract points generalize from this tranche. A module's `minimum_assertions` floor is an **equality** check against the extraction-time executed count (a floor seeded below the real count lets assertions vanish silently), and a module re-deriving a repo root must spell it `REPO_ROOT="$LIB/.."` rather than the monolith's command-substitution form, because `lib/test/pin-corpus-lint.py`'s resolver cannot see through a substitution and every pin targeting an unresolved path is silently exempt from the meta-guards while the suite still reads clean. `lib/test/module-harness.sh` carries the spelling requirement as an authoring note, and `devflow_module_build_bundle` lives there too — the shared bundle builder that reports each unusable member as its own named RED. The same explicit-selection and focused-default-plus-parallelized-final-gate discipline applies as for the modules above.

**Failure recap (issue #789).** On a run with one or more failures `lib/test/run.sh` prints a named `Failure recap` after its terminal summary, re-listing each failing assertion's identifier from an on-disk sibling record (`<results>.names`) that every tally-writing site appends to — including a module or pooled worker, whose private record is folded into the parent's. That record is what makes the recap cover both streams — most of run.sh's FAIL sites write their detail to stderr — so recovering *which* assertion failed reads the recap plus the stderr-merged capture (the issue-#719 `2>&1` log locally, the Actions runner log on cloud) instead of relaunching a ~10-minute suite. On zero failures no recap prints and the terminal summary is byte-identical to the issue-#456 renderer's output; the suite's exit status is preserved through the recap, which `scripts/verification-flight.py` reads to record the single-flight terminal state.

**Coverage map and ratchet (issue #591).** `lib/test/modules/coverage-map.json` records the owning module for every git-tracked depth-1 code unit under `lib/` and `scripts/` (the literal `unmodularized` marks units no *shell module* covers; an optional `focused_test` field, issue #789, additionally records the `lib/test/test_*.py` file that covers such a unit, which the guard validates as git-tracked, `test_*.py`-named, and executable in the index — the exec bit being what makes it invocable as a direct leading token on the cloud tier), for the guard-derived `run.sh` assertion-name blocks (keyed by issue label), and lists the non-code depth-1 files and the exempt subtree (`lib/test/`). A coverage guard (`lib/test/coverage_map_guard.py`, driven by the complete suite through `git` and `python3` only) turns the suite RED when a new depth-1 unit ships without a coverage decision — at any depth, with an out-of-set extension, in a new subdirectory, or misfiled as non-code — and when the map or the registry is stale, misfiled, or wrong-shape. The `run_sh_blocks` half is **derived and enforced by the guard**, not hand-maintained: it derives the issue labels asserted by `lib/test/run.sh` and by every `lib/test/modules/*.sh` — anchored on assertion-name position, so a label appearing only in a comment derives nothing — and fails RED on a `run.sh` label with no map entry, and on a **fully extracted** label (carried by a module and asserted nowhere in `run.sh`) whose entry is absent or still names `unmodularized`. A **partially extracted** label, one a module carries while assertions remain in `run.sh`, correctly keeps `unmodularized`, because a single `owner` string cannot describe split coverage. The remedy is the guard's own hand-invoked `--fix` mode (`python3 lib/test/coverage_map_guard.py . --fix`), never a hand-transcribed label list; it is deliberately not wired into the batched generated-artifact pass, where the map stays a `by-hand` judgment row the pass leaves byte-unchanged. So every PR that adds an assertion named for a new issue owes that label a map entry — see [`CONTRIBUTING.md`](../CONTRIBUTING.md)'s *Coverage-map block ownership*. When you register a new focused module, follow the module-authoring checklist in [`CONTRIBUTING.md`](../CONTRIBUTING.md) (which also records the coverage-map ownership update), so the map keeps every future extraction ticket a ranked to-do list.

**Shared harness-helper contract.** `lib/test/module-harness.sh` exposes a namespaced static-pin API — `devflow_module_pin_count` (a fixed-string occurrence counter), `devflow_module_pin_unique` (an exactly-one presence pin), and `devflow_module_pin_present` (an at-least-one presence pin, for values that legitimately recur) — so a sourceable module carries no private copy of the pin machinery. Behavioral regressions use ordinary executable tests; the former mutation-taking harness helper is retired. Alongside the pin API the harness owns the shared execution helpers the tier runners reuse: `devflow_run_full_suite_module` (supervise one sourceable module in its own process group, fold its private tally into the shared one), `devflow_run_focused_python_test` (run one standalone `python3` suite with `PYTHON_COLORS=0`, capturing and pure-bash-indenting any traceback on failure, and asserting `rc == 0`), `devflow_run_sharded_python_test` (issue #870 — its concurrent sibling: run ONE `python3` unittest file as many bounded-concurrency selector processes and fold every one of them into a **single** `assert_eq`, so a module's emitted tally stays independent of the host's `cpu_count` and the registry/`run.sh`-operand/tally equality triple is unaffected; it enumerates the file's tests by collection, schedules them through a dynamic work queue bounded by the same `_devflow_pool_resolve_width` the pool uses, parses each unit's executed count from that unit's **stderr** capture alone, and fails closed on every arm — an unestablished enumeration, an enumeration establishing zero tests, a unit that records no exit status, a non-zero unit, a unit reporting anything other than exactly one executed test, a dispatched/executed total short of the enumerated one, or (issue #890) an unrecognized value of its optional fourth argument, the **population mode**: `full` — the default when the argument is absent or empty — enumerates every test, `smoke` enumerates only the first test of each class the loader produced a test for, and any other value is refused before anything is enumerated or dispatched. A `smoke` run states the bound in the same statement as its tally, so a bounded run and a full one are never byte-identical; `lib/test/run-module.sh` and `devflow_run_full_suite_module` each *assign* that mode unconditionally rather than defaulting it off the environment, so `smoke` is only ever selected by `run-module.sh`'s explicit `--heavy-units full|smoke` flag and never acquired from an ambient variable), `devflow_fold_module_failures` (add the boundary-failure channel into the terminal failure count), `devflow_module_allocate_owned_directory` (allocate a validated private scratch root), and the bounded concurrent Python-suite pool (`devflow_pool_open`/`devflow_pool_join`, described below). The counter runs a **checked** `python3`: it returns an established non-negative count only after a successful readable scan and otherwise returns `unestablished` (never `0`), so a failed count surfaces as a RED assertion instead of a vacuous pass. The harness is also the single home of the shared fixture helpers `mint_blk`, `probe_tmp` and `probe_assert` — promoted out of `lib/test/run.sh` (issue #695) so exactly one definition of each exists tree-wide, with the monolith obtaining them by sourcing the harness. On entry the harness clears an inherited `DEVFLOW_GH` (announcing it on stderr) before any module body is sourced, so a focused run started with that override exported gets the same fixture isolation the complete suite's preamble already guaranteed; tests of the override contract set their own value per invocation, which the clear does not affect.

**Bounded concurrent Python-suite pool (issue #720).** The complete suite runs its long-tail Python suites through a bounded concurrent pool rather than strictly serially. Two suites — `test_module_runner.py` and `test_python_scripts.py` — are launched into a pool whose in-flight limit is `min(os.cpu_count() or 1, 4)` (`devflow_pool_open`/`devflow_pool_join` in `lib/test/module-harness.sh`). Their membership, tally modes, and self-tally reconciliation have exactly one definition — `devflow_python_suite_pool_open`/`devflow_python_suite_pool_join`, also in `lib/test/module-harness.sh` — because two drivers consume it: `lib/test/run.sh` (a local full run, and the overlap described next) and `lib/test/run-python-pool.sh` (the `python-pool` CI shard, described under the shard matrix below). On a local run the pool opens at the `test_module_runner.py` driver site — after every preceding `devflow_run_full_suite_module` call (those boundaries are complete, so no pooled suite races the main shell on them) — stays open across the last module boundary (`harness-python-guards`) and the intervening main-shell assertions, and joins **before** the `RESULTS_FILE` tally is counted, so the long pole overlaps both the last module and the shell tail. The pooled `test_module_runner.py` itself drives `harness-python-guards` through its own `run-module.sh` subprocess — since issue #890 with `--heavy-units smoke`, so that end-to-end proof no longer re-runs the module's heaviest unit in full — and that boundary therefore runs in the main shell and in the pooled suite concurrently; the overlap is safe because each execution allocates its own isolated owned scratch root, not shared mutable state. Pooling overlaps the long-pole suite with the last module boundary and the shell tail, measurably shortening wall-clock on a multi-core host. In CI the overlap is no longer how these suites are paid for at all: profiling the `monolith` shard (`lib/test/profile-suite.py`) measured the shell sitting **idle** at the join for about a fifth of that shard's wall-clock, having run out of assertions to hide the Python work behind — so the shard runner sets `DEVFLOW_SKIP_PYTHON_POOL=1` on the monolith and the same pool runs concurrently, over the same membership, on its own `python-pool` shard. Neither the assertions nor their count change; only which shard counts them does. The width is overridable by the single named environment variable `DEVFLOW_POOL_WIDTH` (a positive integer takes precedence over the `cpu_count` probe); because the cap decides a selection it is derived through the preflight-guaranteed `python3` (never a non-preflight PATH tool), and a non-positive-integer probe falls back to width 1. The cap of 4 bounds oversubscription on a cgroup-throttled CI container, where `os.cpu_count()` reports host CPUs and ignores the enforced quota. Each pooled suite runs with its own `TMPDIR` under a private scratch root allocated through `devflow_module_allocate_owned_directory`, writes its verdict(s) to a private tally validated and appended to `RESULTS_FILE` after the suite is reaped (a self-tally suite like `test_python_scripts.py` emits one `PASS`/`FAIL` line per assertion), and `test_module_harness.py` and its `--signal-matrix-capability` probe stay serial on the main shell — the supervisor forks its worker with job control disabled and that suite asserts on the inherited `SIGINT` disposition. `_devflow_full_suite_signal` is generalized from a single scalar child slot to a run-wide registry of live children, so one delivered signal terminates every in-flight child's process group before the handler exits, and a supervisor PID-rendezvous timeout under pool saturation is absorbed by re-running that suite serially rather than recorded as a failure. The suite reports byte-identical tallies whether the pool runs at its core-derived width or is forced to width 1.

**Memoized per-source parses (issue #881).** `lib/test/pin-corpus-lint.py` and `lib/test/mutation-pin-census.py` hold process-global `functools.lru_cache` memos over their per-source parses, so a source re-presented within one process is reused rather than re-parsed, for as long as it stays inside each memo's bound (those bounds are sized in the two modules, against the working set each one actually repeats over; an evicted entry is recomputed, never answered wrongly). That matters here because `lib/test/test_pin_corpus_lint.py` is dispatched twice concurrently — once on the main shell's `harness-python-guards` boundary, in full, and once inside the pooled `test_module_runner.py` real-runner meta-test, since issue #890 as a bounded `smoke` subset rather than a second full population — and its heaviest class is sharded across bounded-concurrency selector processes, so a memo that captured repository state would make an outcome depend on ordering. The two-limb argument for why none of them does — key purity for the per-source memos, module statelessness for the argument-less `_load_mutation_census_module` — is stated once in `lib/test/test_pin_corpus_lint.py`'s module docstring and mirrored at the shard-dispatch site in `lib/test/modules/harness-python-guards.sh`, which are a coupled pair; it is not restated here. It is executable rather than prose: `MemoizedParseContractTests` and the `StaticPinWorktreeCompositionTests.test_leaked_*` probes are named there as the tests that hold it.

**Single-EXIT-trap registry contract.** `lib/test/run.sh` installs exactly one `trap _suite_cleanup EXIT` over an append-only registry of temporary files and directories; `_suite_cleanup` removes every registered entry on exit. Helpers in `lib/test/module-harness.sh` — the per-module boundary and the concurrent pool included — install **no** `EXIT` trap of their own: they only save, install, and restore the temporary `HUP`/`INT`/`TERM` handlers, and clean their own scratch roots and private tallies inline on every return path. Re-registering a longer `trap … EXIT` would replace the sole handler rather than extend it (the failure mode PR #539 hit, losing `SKIPS_FILE`), so the pool adds no second `EXIT` trap and leaves `_suite_cleanup` the only one installed.

**Tracked-only module fixtures (issue #714).** A module that needs a repository image builds it from the **git index** — every tracked blob `git ls-files -s -z` reports, reproduced file by file at its own relative path, with each file's mode taken from the index rather than from the working tree — never by `cp -R`-ing a whole top-level directory. The directory form is the trap: one tracked file inside an otherwise-untracked directory drags the entire directory in, and because `.claude/settings.json` is tracked the `regenerate-artifacts` module used to copy the whole untracked `.claude/` tree — including any `git worktree` checkouts under `.claude/worktrees/` — into every per-assertion fixture copy, which on a developer checkout was the dominant cost of a full local suite run (CI, behind a fresh `actions/checkout`, never carried the payload and is unaffected). Untracked state cannot enter such an image by construction, so no build-cache prune step is needed; three skip arms — the two non-blob index modes (a gitlink `160000` and a symlink `120000`) plus a blob the working tree does not carry — are each taken with their own named stderr breadcrumb and subtracted from the completeness denominator by name, a copy or mode failure is counted on its own channel rather than vanishing into that gap, and unmerged paths contribute once rather than once per stage. `regenerate-artifacts` pairs its bash builder with an independent `python3` oracle that re-reads the index itself — a deliberate coupled mirror, edited together — and both fail closed on an unestablished measurement rather than reporting a vacuous zero.

**Selectable-module interruption contract.** On POSIX hosts with signal and process-group support, both `lib/test/run-module.sh` and the complete-suite boundary supervise a selected module in a dedicated process group. Their temporary `HUP`, `INT`, and `TERM` handlers forward the signal, escalate resistant helpers within a bound, reap the group, and remove the boundary-owned tally and scratch root; the full-suite boundary restores the caller's signal traps after a normal return without replacing its `EXIT` trap. Modules nest ordinary `TMPDIR` allocations under the validated boundary root, while `create-issue-contract` reuses that owned root and keeps idempotent signal/exit cleanup as its fallback. `lib/test/test_module_harness.py` exercises each signal against parent-only, module-only, and process-group delivery for both boundaries, including launch-window and resistant-helper paths; `lib/test/run.sh` records a visible `host-capability` skip when the host cannot express that matrix.

A module run through the focused runner may not self-skip: `lib/test/run-module.sh` overrides `skip` to a fatal `exit 1` inside the module worker, so a skippable gate must stay in the complete suite (which owns the `#456` skip accounting) rather than be smuggled into a focused module that would silently neither pass nor fail.

**Bounded heavy units on the focused runner (issue #890).** `lib/test/run-module.sh` takes `--heavy-units full|smoke`, the only channel that ever selects a bounded population for a module's heaviest unit (the mode's meaning is defined once at `devflow_run_sharded_python_test`, above). The runner *assigns* `full` unconditionally rather than defaulting it off the environment and applies `export -n`, so an inherited `MODULE_HEAVY_UNIT_MODE` can neither shrink what a run executes nor leak a bound into anything launched underneath it; the flag is refused when repeated, when its value is anything but `full` or `smoke`, and when its value is missing, so a typo can never read as a bounded pass. Because the reduction is deliberate, the runner also makes it visible in both directions. When `full` was requested it scans the module's own log — with a bash `case`, never a non-preflight `grep`, since the result decides the emitted failure tally — and **fails** the run if the log nevertheless carries a bound, which is the last link no earlier guard can see: a module that forwards a literal `smoke` or defaults to one would otherwise drop a full population from CI while every tally stayed green. When a bound *was* requested it prints a separate notice line naming the mode, deliberately not folded into the `Module <id>: N passed, M failed` summary, whose shape is a machine-consumed contract (`lib/test/shard-tally.py` anchors a regex on it, and the step-8 real-runner meta-tests assert it as an exact `splitlines()` member). The notice reports what was *requested*, and says so: only a module that reads the mode bounds anything, so whether a unit actually bounded its population is the driver's own tally line above it in the same log. The recombined gate summary cannot express a bound at all — the unrequested-bound failure is what makes an unintended reduction gate-visible, the same "a reduced run is never a clean pass" rule issue #456 established for skips.

**The one accounted exception, and it is tier-asymmetric (issue #838).** A module may declare that *this host* cannot express a condition — the `host-capability` kind alone — through `module_host_capability_skip <name> <reason> <assertions-covered>` in `lib/test/module-harness.sh`. It is a wrapper, not a second producer: it delegates to the same `skip` helper, so the reserved `  NOTE ` emit still has exactly one writer. Under the **complete suite** the boundary binds the module child a *private* skip tally plus a credit record (the `RESULTS_FILE`/`.names` pattern) and folds them back after `wait`, folding only `host-capability` records and crediting each arm's declared assertion count against the module's `minimum_assertions` floor via a computed effective minimum — so a host that cannot express the condition reports a **visible skip** instead of tripping the floor with a count mismatch that reads like a regression. Every degraded shape fails closed: a malformed or floor-meeting credit grants zero, and a skip record that never reached the shared tally forfeits every credit so the raw floor stands. Under the **focused runner** the same call still hits that runner's fatal override by design — the raw helper stays unreachable there, and the fatal message names the wrapper so the stop is not misread as a module contract violation. The reachability answer is therefore "yes on the complete suite, through the accounted wrapper; no on the focused tier", and a host taking such an arm runs the complete suite to have the skip folded.

Each mapping declares its source path and a positive `minimum_assertions` floor. Selection and whole-registry validation finish before the module body is sourced; unknown or invalid selections fail closed before any module body runs, and an executed module falling below its assertion floor fails the run afterward; and every successfully selected invocation writes a unique persistent log (by default under `.prflow/tmp/test-module-logs/`; overridable with `--log-dir`; logs accumulate without automatic pruning — clear the directory or point `--log-dir` elsewhere during heavy iteration) with a terminal summary and a failure recap whenever an assertion or module boundary fails. Focused runs are the iteration default; they do not replace the parallelized final gate — the complete run plus CI. The complete suite executes the same sourceable module through `lib/test/module-harness.sh`, enforcing the same floor. Its missing, crashing, malformed-tally, and assertion-shortfall failures use a separate boundary tally that is added to the terminal failure count. Each module writes assertions to a private tally which is validated before being appended to the shared suite tally, so an over-broad module write cannot erase an earlier verdict.

**Suite routing is asserted against the tree, not against its own lists (issue #867).** `lib/test/test_module_runner.py` classifies every `lib/test/test_*.py` suite into exactly one of `POOLED_SUITES`, `SERIAL_BY_EXCLUSION_SUITES`, or `MODULE_DRIVEN_SUITES`. Total-and-disjoint membership was previously the whole guarantee, so a suite could sit in `MODULE_DRIVEN_SUITES` while `lib/test/run.sh` also drove it serially and the run stayed green while executing it twice — the defect issue #865 fixed, latent for nearly a year. The two membership tuples are now executable claims about where the tree actually drives each suite: a `MODULE_DRIVEN_SUITES` member must occur zero times in `lib/test/run.sh` and in exactly one file across `lib/test/modules/*.sh` plus `lib/test/module-harness.sh`, and a `SERIAL_BY_EXCLUSION_SUITES` member must occur at least once in `lib/test/run.sh` — so deleting a driver block without reclassifying is caught too. The matcher is the `$LIB`-anchored quoted invocation shape `"$LIB/test/<name>"`, not a bare basename: a module file can mention a suite's path in comments without driving it — `lib/test/modules/create-issue-contract.sh` does — so a basename scan would be red against a correct tree, and it would let a comment satisfy the presence direction. Whole-line comments are stripped before matching either way, so a commented-out driver cannot satisfy a presence claim. The module-side claim counts **distinct files**, never occurrences, because one owning module legitimately carries several occurrences for a suite it drives; that also avoids introducing any suite-to-owning-module mapping, which does not exist. `POOLED_SUITES` is deliberately excluded — an existing pin already asserts set equality against the parsed `devflow_pool_open` triples in `module-harness.sh`'s `devflow_python_suite_pool_open` (the pool's single membership definition, which `run.sh` and `run-python-pool.sh` share), a stronger guarantee than a name scan. The scanning helper takes the `run.sh` path and the module directory as parameters (defaulting to the real tree, a single-level directory listing via `iterdir()`, no repository-root-anchored walk), so each direction is proven RED against a planted violation in a scratch copy, with a planted bare-basename comment as the positive control. Retiring the per-file `#810` guard this generalizes lowers `harness-python-guards`' coupled assertion-count triple from 39 to 38.

**The suite tallies three outcomes — passed, failed, and *skipped* (issue #456).** A check can **self-skip**: it neither passed nor failed because the environment could not run it or express its condition. The terminal summary makes skips visible so `0 failed` is never mistaken for "everything ran": with nothing skipped it prints `N passed, M failed` (byte-identical to the historical format); with `K` skips it prints `N passed, M failed, K skipped`, followed by one line per skipped check naming the check, its **kind**, and the reason. The `[ "$FAIL" -eq 0 ]` pass/fail predicate is unchanged — a skip never fails the suite (a run whose pass/fail/skip tallies cannot even be *derived* aborts fail-closed before that predicate, by design — unknown is never reported as zero). Each skip carries a **kind** — `blocking-gate` (a real gate that *should* have run here but could not — e.g. the `#434` stale-prose self-scan when `origin/main` is unresolvable or the working tree is dirty) and `host-capability` (the host cannot express the condition — e.g. the `#423 T6b` strict-ASCII-stdout probe on a build that won't downgrade stdout to ASCII). Every self-skip routes through a single `skip <name> <kind> <reason>` helper (a comment-aware meta-assertion turns the suite RED if a `printf '  NOTE ` emit — the contiguous emit shape a maintainer would actually write; an echo-based or variable-assembled emit is a disclosed non-goal — appears in `lib/test/run.sh` outside that helper), and the renderer lives in `lib/test/summary.sh` (added to the CI shellcheck scope explicitly, since `lib/test/` is otherwise excluded). CI checks out full history (`fetch-depth: 0`) so `origin/main` resolves and the `#434` gate runs live there. **A skipped check is never a clean pass:** `/prflow:review-and-fix` records any skips in `verification_evidence.skipped_checks` (distinct from `result: skipped`, which means the whole suite run was skipped), and a run with a non-empty `skipped_checks` is not reported by the loop as a clean pass.

**CI shell-lint scope for `lib/test/` (issue #745).** `.github/workflows/ci.yml`'s `lint` job lints the repo's shell with `git ls-files '*.sh' | grep -v '^lib/test/' | xargs -r shellcheck --severity=warning -e SC1091` — the `lib/test/` exclusion exists because that tree carries deliberately-malformed `gh`-stub and adversarial fixtures. The excluded-but-shipped files are re-added by a hand-maintained explicit file list in the same job, and `lib/test/run.sh` gets a **dedicated step** because it is the only file that needs `--extended-analysis=false`: ShellCheck's dataflow pass allocates on the order of 15 GB on a file this size and evicts the 16 GB runner mid-analysis, while the flag brings it to roughly 1.15 GB and ten seconds. The flag alone is not sufficient — `--extended-analysis` landed in ShellCheck **0.10.0**, and on the 0.9.x that `ubuntu-latest` ships the flag errors while the equivalent `# shellcheck extended-analysis=false` directive has no effect — it is reported as an unknown directive (SC1107) and ignored — so the lint would OOM exactly as if the flag were absent. The job therefore installs a **pinned** ShellCheck (≥ 0.10.0) onto `PATH` ahead of every ShellCheck step rather than trusting the runner image's version, which drifts with the image; `lib/test/run.sh` asserts that floor, the flag, and the pin. The measured memory/time figures live in the `ci.yml` pin step's own comment as a dated past-time snapshot to re-measure after a ShellCheck upgrade — not an invariant. The two sides of the carve-out are reconciled mechanically by `lib/test/lint-carveout-guard.py` (driven from `lib/test/run.sh`), which derives the set of `lib/test/**/*.sh` files CI actually lints from `ci.yml` and fails RED, naming the path, when a tracked `lib/test` script is neither in that set nor under the single declared exempt prefix `lib/test/fixtures/`. It is a best-effort reader of a human-maintained YAML file and fails **closed** on every shape it cannot interpret (unreadable or non-YAML `ci.yml`, no locatable `shellcheck` invocation, a changed `grep -v '^lib/test/'` exclusion, or a `git ls-files` enumeration returning zero rows — an unestablished population, never an empty one), because a red guard forces human attention rather than reporting coverage it never established; its two known limitations — a pipeline restructured so the glob and the `shellcheck` literal are no longer co-located, and a step gated inactive by an `if:` condition it does not evaluate — are enumerated in its module docstring.

---

## 20. Glossary

| Term | Meaning |
|---|---|
| **Workpad** | The single marker-tagged GitHub issue comment `/prflow:implement` maintains as the run's durable progress surface. |
| **Verification checklist** | The list of every verifiable claim a diff makes, generated and then verified against source by the review engine. |
| **`defect_signature`** | The `file` + `line_range` + `kind` tuple used to mechanically corroborate findings across reviewers. |
| **Shadow review** | A structurally-independent re-review run before declaring a clean approval, to audit the loop's self-agreement. |
| **Scope-Acknowledged Findings** | The contract that lets a deliberately-deferred finding be tracked in a follow-up issue instead of re-raised as a REJECT. |
| **Retrospective loop** | The weekly evaluator/optimizer pass that reads merged bot-PR evidence and proposes interventions. |
| **Clean gate** | The mechanical filter that lets clean PRs be processed with zero LLM cost in the retrospective loop. |
| **Thin install** | A cloud-tier install that doesn't commit the plugin tree; it's fetched at runtime, pinned to `prflow_version`. |
| **Vendoring / materialization** | Placing the plugin at `.prflow/vendor/prflow/` so the CI sandbox can reach its helpers. |
| **Partition invariant** | The rule (test-enforced) that PRFlow triggers always negate `@claude`, so PRFlow and Anthropic's Claude app never double-fire. |
| **Local tier / cloud tier** | Skills run in your editor (no infra) vs. autonomous GitHub Actions automation. |

---

## 21. Messaging guide

**Primary positioning.** *PRFlow is the workflow layer that makes agentic coding work on real codebases*, it doesn't just write code, it ships it: spec → plan → code → test → review → fix → document → review-ready PR, with a self-improving loop on top. Where out-of-the-box agents demo well on pet projects and stall on a real ticket in a large production codebase, PRFlow carries that ticket to the finish line.

**Best-fit user.** A developer or team working in a **large, business-grade codebase** (production/enterprise software) who has tried agentic coding and hit the wall where it works on toy projects but can't complete a real ticket, and who is already on Claude Code + GitHub. The angles below also resonate with adjacent audiences.

**One-liner (StoryBrand elevator pitch, customer is the hero, PRFlow is the guide).** *We help developers drowning in half-finished AI pull requests turn a single request into a complete, review-ready PR, so they ship real features on a real codebase without cleaning up after the agent.*

**Three pillars (use as the deck's spine):**
1. **Works on real codebases, not just pet projects.** A one-line feature request → a codebase-grounded ticket → a complete PR ready for your final review, the full-round implementation out-of-the-box agents can't finish on production code. End-to-end, not just code; the steps a one-shot agent skips (tests, review, docs) are exactly the ones PRFlow won't.
2. **Review that fixes what it finds.** A review-and-fix loop that applies the fixes and re-reviews until it approves, on top of independent verification checklists, a panel of specialized reviewers, mechanical corroboration, and a shadow pass that audits its own approval.
3. **It learns.** A weekly retrospective reads its own track record and proposes the smallest fix that prevents the next mistake, humans approve.

**Differentiators worth naming explicitly:**
- "Ship the PR. Not the cleanup." (the hero tagline)
- "Agentic coding that works on real codebases, not just pet projects."
- "Committing code is the halfway point, not the finish line."
- Shadow review, *it audits its own audit*, with honest calibration (narrows the gap, never closes it).
- Self-improvement loop with an LLM/heuristic split (LLM only at two judgment points; everything else is zero-token deterministic).
- Two tiers: works locally with **zero config**, scales to **autonomous** cloud automation with one secret by default.
- Built on Claude Code's plugin system; ships its full review/discovery/authoring toolchain first-party (hard-forked from Anthropic's `pr-review-toolkit` + `feature-dev` agents and the `superpowers` skills, upstream licenses retained) — **zero companion-plugin dependencies**.
- Security-explicit: base-ref trust boundary, deny-list floor, read-only-by-default reviewer.

**The sales narrative (the argument arc, use it in a pitch, a landing page, or a talk):**

- **Problem.** You've adopted an AI coding agent. It's dazzling on a demo repo, and then you point it at a real ticket in your actual production codebase, and it comes back half-done: wrong patterns, missing tests, stale docs, acceptance criteria unmet. Your engineers now spend *more* time fixing and reviewing the agent's output than the agent saved.
- **The old way.** Babysit the agent prompt-by-prompt, or hand the whole ticket to a senior engineer who does spec → plan → implement → test → review → fix → document by hand, slowly, expensively, and inconsistently, on every ticket.
- **Why now.** AI has made *writing* code cheap. The bottleneck moved to everything around it, planning against real architecture, rigorous review, keeping docs in sync, at scale, on every change. That's precisely where out-of-the-box agents stall.
- **The new way.** PRFlow takes a one-line request, turns it into a codebase-grounded issue through a few sharp clarifying questions, then runs the full `/prflow:implement` lifecycle, plan, architect, implement, auto-generate the test automation it needs, review-and-fix iterations with a shadow pass that audits its own approval, and docs, and hands you a complete PR that meets every acceptance criterion. Then it improves itself every week.
- **Proof.** Independent verification checklists; a panel of specialized reviewers with mechanical corroboration; shadow review (on PR #58 it agreed with full coverage, yet a standalone `/prflow:review` still surfaced hardening items, calibration kept honest); the weekly retrospective that opens its own improvement PRs.
- **The ask.** `claude plugin install devflow`, runs locally with zero config; add one secret (by default) to go fully autonomous in CI.

**Honest-claims guardrails (keep marketing accurate):**
- The in-loop shadow review **narrows** the gap to an independent review; it does **not** replace a standalone `/prflow:review`. Don't claim it "guarantees" completeness.
- A human still does the final review and merge, PRFlow gets the PR *ready*, it doesn't auto-merge.
- The retrospective loop proposes interventions; **humans approve or reject**. It never auto-merges its own changes.
- The local tier needs `git`, `gh`, `jq`, and Python 3.11+ on PATH (PyYAML is advisory on this tier — reported but not gated by preflight); the cloud tier needs `CLAUDE_CODE_OAUTH_TOKEN` by default (an optional third-party model provider adds `DEVFLOW_PROVIDER_API_KEY`).

**Audiences & angles:**
- **Engineering leaders:** consistency, auditability, reduced review burden, telemetry on reviewer effectiveness.
- **Individual developers:** turn a rough idea into a merged PR without context-switching; runs in your editor with zero setup.
- **Security/platform teams:** explicit threat model, base-ref trust boundary, read-only-by-default automation, one secret by default.
- **AI/ML audience:** the evaluator/optimizer architecture, independent verification, structural-independence in self-review.

**Demo beats for a video (in order):** rough idea → `/prflow:create-issue` interview → confirmed issue #42 → comment `/prflow:implement 42` → watch the workpad update live (🚀) → draft PR appears → review-and-fix loop + shadow pass → docs updated → PR flips to ready (🎉) → the review-gate check posts APPROVE → human merges. Optionally close with a `/prflow:retrospective-weekly` run filing an improvement issue for the next cycle, "it just got better."
```