Summary

I've completed a thorough investigation of the Entire CLI repository's documentation structure. Here are my findings:

1. README.md Structure & Purpose

File:/Users/pfleidi/entire/cli/.worktrees/agent-fallback-instructions/README.md

Exists: Yes (596 lines)

Purpose: User-facing introduction and operational guide for the Entire CLI. Targets both end users and developers who want to integrate Entire with their repositories.

Top-level section structure:

• Why Entire
• Table of Contents
• Requirements
• Quick Start
• Release Channels
• Typical Workflow
• Key Concepts (Sessions, Checkpoints, How It Works, Strategy, Git Worktrees, Concurrent Sessions)
• Local Device Auth Testing
• Commands Reference
• Configuration
• Security & Privacy
• Troubleshooting
• Development
• Getting Help
• License

Audience: Both user-facing and developer-facing, with heavy emphasis on setup and operational guidance.

2. AGENTS.md Symlink

Result:AGENTS.md is a symbolic link pointing to CLAUDE.md

lrwxr-xr-x@ 1 pfleidi  staff      9 Jul  1 13:35 AGENTS.md -> CLAUDE.md

This means AGENTS.md and CLAUDE.md are the same document—the .md symlink is a convenient alias.

3. CLAUDE.md Content Organization

File:/Users/pfleidi/entire/cli/.worktrees/agent-fallback-instructions/CLAUDE.md

Size: ~634 lines

Primary Purpose: Developer-facing architectural documentation for CLI contributors and maintainers.

Key section where "Agent-Safe CLI Fallbacks" would naturally fit:

The most natural location is under the ## Code Patterns section (line 331). This section currently contains:

• ### Error Handling (line 333)
• ### Settings (line 369)
• ### Logging vs User Output (line 407)
• ### Git Operations (line 417)
• ### Control-Plane Core Resolution (line 478)
• ### Session Strategy (line 502)
• ###entire review Command (line 561)

Important context found in CLAUDE.md:

• Line 63-80: Detailed discussion of agent-help command which emits --json output for agent-facing, machine-readable usage—this is where agents discover what commands are available
• Line 243-268: Section titled "Spawning subprocesses in tests (TTY detection)" which covers interactive.CanPromptInteractively(), /dev/tty probing, ENTIRE_TEST_TTY env var, and execx.NonInteractive() for spawning non-interactive children
• Line 581-634: "Accessibility" section documenting how to handle interactive TUI prompts and the ACCESSIBLE=1 environment variable

4. Docs Under docs/architecture/

Files present:

• agent-guide.md — Agent implementation patterns
• agent-integration-checklist.md — Integration validation criteria
• attribution.md
• checkpoint-scenarios.md — Checkpoint phase state machine
• checkpoint-signing.md
• claude-hooks-integration.md — Claude Code hook specifics
• commit-hook-perf-analysis.md
• copilot-token-validation.md — Copilot-specific patterns
• external-agent-protocol.md — For custom agents without built-in support
• external-commands.md — kubectl-style external commands (lines 1-60); includes discussion of environment variables passed to external commands (no TTY handling documented)
• logging.md — Debug logging configuration
• review-command.md — Profile-based review execution
• sessions-and-checkpoints.md — Domain model and storage layout
• upstream-host-resolution.md

Relevant to CLI conventions/TTY/interactivity:

• external-commands.md (line 33-60) documents environment filtering but does NOT discuss TTY detection or fallback behavior
• review-command.md (line 62) mentions "A bare non-interactive entire review does not auto-run a profile" but provides minimal context

5. Current Documentation of Non-Interactive Behavior

Findings:

Currently documented:

• CLAUDE.md (lines 243-268): TTY detection logic for tests (interactive.CanPromptInteractively(), /dev/tty probe, ENTIRE_TEST_TTY, execx.NonInteractive)
• CLAUDE.md (lines 583-634): Accessibility mode with ACCESSIBLE=1 env var and how to use NewAccessibleForm() for non-interactive TUI elements
• CLAUDE.md (lines 63-80):agent-help command with --json output for machine-readable agent discovery
• CLAUDE.md (line 74):entire status --json for JSON output
• KNOWN_LIMITATIONS.md (line 11): Non-interactive amend behavior with /dev/tty unavailability
• security-and-privacy.md: Non-interactive context handling for OPF (OpenAI Privacy Filter) at push time

NOT currently documented:

• A cohesive "Agent-Safe CLI Fallbacks" section covering when/how to use --json, --no-pager, non-interactive mode fallbacks, or guidance for commands that need to degrade gracefully when running in agent environments
• TTY detection patterns for agent-run code (only test-specific patterns are documented)
• Guidance on detecting CI/agent execution environments beyond interactive.CanPromptInteractively()

Recommendation for "Agent-Safe CLI Fallbacks"

Based on the analysis, the new section should be added under ## Code Patterns in CLAUDE.md, after the existing subsections but before or alongside the "Accessibility" section (which already touches on non-interactive behavior). The location would be approximately after line 561 and before the "Important Notes" section at line 567.

This placement groups all command/interface pattern guidance together and pairs naturally with the existing "Accessibility" content, since both deal with graceful degradation when standard interactive features are unavailable. <subagent_tokens>49640</subagent_tokens><tool_uses>23</tool_uses><duration_ms>56169</duration_ms>

2w ago·3.9s

I have the doc structure findings. Waiting for the other two agents (code issues verification and good-pattern verification).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// cmd/entire/cli/interactive/interactive.go

// CanPromptInteractively reports whether interactive confirmation prompts
// (huh forms, yes/no questions, etc.) can be shown. Returns false in CI,
// agent subprocesses that inherit a TTY but can't respond to prompts,
// and other environments without a controlling TTY.
func CanPromptInteractively() bool

// UnderTest reports whether the process is running in a test context — either
// inside `go test` (testing.Testing()) or with EnvTestTTY explicitly set.
func UnderTest() bool

// IsTerminalWriter reports whether w is an *os.File backed by a terminal.
// Use for deciding on color, pager, progress bars, or other writer-scoped
// TTY formatting. For "can I prompt the user?" use CanPromptInteractively.
func IsTerminalWriter(w io.Writer) bool

// ShouldStyle reports whether ANSI-styled output (color, bold, rendered
// markdown) should be written to w.
func ShouldStyle(w io.Writer) bool

2w ago·7.7s

Two of three done. Waiting on the good-pattern verification agent.

1
2
3
4

// NonInteractive returns an *exec.Cmd detached from the parent's controlling
// TTY. In the child, /dev/tty cannot be opened, so
// interactive.CanPromptInteractively() returns false — no env var required.
func NonInteractive(ctx context.Context, name string, args ...string) *exec.Cmd

2w ago·2m·8 calls

Done with the doc section. Here's the answer on the runner configs.

Doc section — added

### Agent-Safe CLI Fallbacks now lives under Code Patterns in CLAUDE.md (which AGENTS.md symlinks to), right after the entire review subsection. All commands it cites were verified to exist as described. Docs-only, no code changes — the four flagged code issues (review/fix.go truncation, and the missing non-TTY guards in rewind.go/sessions.go/clean.go) are left as follow-up work.

.entire/runners/*.json — yes, we can, and there's a clean place for it

The seven runners split into two kinds:

• Finding-raisers / focus-pickers (prompt-driven, produce review output): trail-review.json (raises actual code-review comments) and trail-review-focus.json (flags areas for a human reviewer). Both already carry a domain-specific checklist — trail-review.json has a "Pay extra attention to these high-risk surfaces" list, trail-review-focus.json has a "Look for" list. These are the right insertion points.
• Scoring monitors (emit a single 0–100 number): trail-risk.json, trail-security.json, trail-drift.json, trail-confidence.json, trail-summary.json. Adding review-checklist text here would distort their rubrics — I'd leave them alone.

One caveat for trail-review.json: its prompt explicitly forbids commenting on test coverage, style, refactoring, and docs. An interactive-only command is not a style nit — it's a missing guard / functional regression for non-interactive callers, which fits its allowed categories ("broken invariants… missing guards"). So the instruction must be phrased as a real defect, not a preference, or the model will correctly suppress it.

Proposed bullet to append to the high-risk-surfaces list in trail-review.json:

• Interactive-only output paths — a command whose useful result is reachable only through a TUI, picker, confirmation, wizard, or stdin prompt (look for huh, Bubble Tea, CanPromptInteractively, direct stdin reads) with no non-interactive way for an agent to get the same information (no --json, no list+show pair, no selector flag/arg, no non-TTY text fallback). Treat this as a missing guard, not a style issue.

And a lighter "Look for" bullet in trail-review-focus.json:

• Commands gated behind a TUI/picker/confirmation prompt with no non-interactive (--json, flag, or text-fallback) path for agents.

Want me to apply both? I'd recommend just those two files — the finding-raiser and the focus-picker — and leave the five scoring monitors untouched. These are shared review-behavior configs, so I held off editing until you confirm.

Let's apply both and see what's flagged in reviews.

2w ago·2m·8 calls

Both runner configs are edited and valid. But before we push anything, there's a mechanics reality worth flagging, because it determines whether we'll actually see the new rule fire.

How these runners actually run

• trail-review and trail-review-focus are trail runners (automation.kind: trail_prompt, trigger_types: [push]). They execute server-side in the Entire core sandbox when the branch is pushed, not locally. entire runner only has a setup subcommand — there's no entire runner run <id> to invoke one locally.
• Both prompts review git diff origin/main...HEAD — i.e. only the branch's changes, not the whole repo.

The catch for this branch

This branch's diff is only three files — the two runner JSONs and CLAUDE.md (nothing is even committed yet):

 M .entire/runners/trail-review-focus.json
 M .entire/runners/trail-review.json
 M CLAUDE.md

None of that introduces an interactive-only command. The commands the rule targets (rewind, sessions stop, clean) already live on main, so they're outside the diff — a diff-scoped reviewer won't see them. If we commit and push this branch as-is, the new fallback rule will correctly flag nothing, and we won't learn whether it works.

To actually exercise the rule

We need a branch whose diff adds an interactive-only path with no fallback. Two realistic ways:

1. Real demonstration — put a small throwaway commit that adds a huh-gated command (or reverts one of the existing guards), push it, and watch the trail (entire trail …). Expect trail-review to raise a finding and trail-review-focus to list it. Then drop the commit.
2. Fold in the actual fix — implement the rewind.go/sessions.go/clean.go non-TTY guards on this branch. Then the diff contains those files and the reviewer exercises the rule against real, intended changes (and you get the fixes too). This is the "Docs + code fixes" scope you earlier deferred.

Pushing is outward-facing and there's nothing committed yet, so I didn't want to do it unprompted.

How do you want to proceed?

Can you ask me the same question again? I wanted to submit something else and didn't get a good look at the options

2w ago·7.1s·1 call

No problem — here are the same options again.

Conitnue

2w ago·55.0s·4 calls

Good — that's the key thing I needed to confirm: .entire/runners/*.json are this repo's tuned configs, deliberately diverged from the embedded defaults in runnerdefaults/runners/ (different prompts, tabs vs spaces). There's no drift test forcing them equal, so editing the active configs is correct and I don't need to touch the embedded defaults. No Go changed, so no build/lint relevant to this diff.

Committing the three files, then pushing.

Can you commit the changes separately?

2w ago·49.6s·3 calls

Split into two commits, nothing pushed:

• d271f14064 — docs: add agent-safe CLI fallback guidance (CLAUDE.md only)
• ed6ea4c273 — chore(runners): flag interactive-only commands in review (both trail-review.json and trail-review-focus.json)

Both are local only — I stopped at the push after you interrupted it. Want me to push now, or hold?

Base directory for this skill: /Users/pfleidi/.agents/skills/pfleidi/skills/review

Code Review

1. Determine Diff Against origin/main

Always review changes against origin/main directly. Do not use local main, git merge-base, a PR base branch, or a user-specified alternate base.

Get the CURRENT diff — never use cached results from earlier in the conversation. Include both committed and uncommitted changes (staged + unstaged):

1
2

BASE=origin/main
git diff $BASE --stat

Note: git diff origin/main (not origin/main...HEAD) diffs origin/main against the working tree, capturing committed changes, staged changes, and unstaged changes in one pass.

Show the user the file list and total count. If there are 0 changed files, report that to the user and stop — there is nothing to review. Otherwise, immediately proceed to the review agents. Do NOT wait for confirmation.

Before launching agents, build a concise review context and pass it to every agent. Show the context as a table before launching agents so assumptions are visible:

• The user's request and any implementation plan, design notes, or acceptance criteria provided in the conversation.
• Branch commit messages from git log --oneline origin/main..HEAD.
• PR title/body when a PR exists for the branch.
• The changed-file list and any obvious intended behavior changes inferred from commits, tests, docs, or user-facing text.

Treat this context as the statement of intent. If no implementation plan or PR context exists, say that intent is inferred from the diff and commits only.

2. Spawn Parallel Review Agents

Review Philosophy

Pass these rules to every agent:

• It is OK to find nothing. A clean review is a valid outcome. Do NOT manufacture findings to justify the review. Only flag issues you are confident are real problems.
• Be opinionated and consistent. If a pattern is acceptable, don't flag it. If you flag something, commit to that position — don't suggest the opposite approach on a re-review.
• Don't flag trade-offs with no clear winner. If there are two reasonable approaches and neither is clearly better, don't flag it. The author already made a choice.
• High confidence only. Every finding must pass the bar: "I am confident this is a problem, and I can explain specifically what goes wrong if it's not fixed." Vague unease is not a finding.
• Permission-friendly reads. Avoid shell pipelines, command separators, subshells, and output filters for read-only investigation because they create extra permission prompts and block background review agents. Do not run commands like git show HEAD:path | sed -n '10,40p'. Use workspace file range reads, rg with path limits, path-scoped git diff $BASE -- <path>, or one standalone git show <rev>:<path> only when the output is acceptably small.
• Intent-aware review. Review changed code against the review context, not against the old behavior alone. Do not classify an intentional behavior change as Required merely because it differs from origin/main. A Required finding must either contradict stated intent, break an existing contract that the intent did not change, introduce a concrete bug/security issue, or leave the intended behavior unverified in a way that would likely fail.

Launch four baseline sub-agents in parallel using the Agent tool. Pass each agent origin/main as the base ref, the full list of changed files, the review context, and the review philosophy above.

When the repository is a Go project and the diff includes Go-related files (*.go, go.mod, or go.sum), also launch Agent 5 in the same batch. Do not run the Go-specific agent for non-Go diffs.

Agent 1: Security & Adversarial

Review git diff $BASE with fresh eyes for:

• Injection — command injection, SQL injection, path traversal
• TOCTOU and race conditions — check-then-act patterns, concurrent access without synchronization
• Unvalidated input at system boundaries — user input, API parameters, external data
• Auth/authz gaps — missing permission checks, privilege escalation paths
• Secrets or credentials — hardcoded tokens, leaked keys, credentials in code or config

For EACH finding: read the actual source file and trace whether the code path is reachable in production. Discard any finding you cannot confirm with a concrete code reference.

Agent 2: Correctness & Quality

Review git diff $BASE for:

• Logic errors — off-by-one, wrong comparison, inverted conditions
• Nil/null handling — unchecked nil dereferences, missing error checks (especially unchecked errors in Go)
• Edge cases in concurrency — goroutine leaks, missing locks, channel misuse, deferred unlock ordering
• Redundant state — state that duplicates existing state, cached values that could be derived
• Production test seams — mutable function variables, package-wide settings, reset hooks, or exported knobs added only so tests can swap behavior instead of using dependency injection or a higher-scope test
• Parameter sprawl — adding new parameters instead of restructuring
• Leaky abstractions — exposing internal details, breaking existing abstraction boundaries
• Stringly-typed code — using raw strings where constants or typed values already exist in the codebase
• Test coverage and scope gaps — changed behavior, edge cases, or error paths not exercised by meaningful tests; tests that prove implementation details instead of behavior; or unit tests used where integration/e2e coverage is the right confidence boundary
• Test helper over-abstraction — helpers that hide the behavior, expected values, or assertions and make the test harder to understand than a small amount of duplication

For EACH finding: verify the claim by reading the source. Check call sites to confirm the issue is real, not hypothetical.

Agent 3: Simplification & Efficiency

Review git diff $BASE for:

• Dead code — unreachable branches, unused functions, struct fields that are never read
• Code reuse — search for existing utilities and helpers that could replace newly written code; flag duplicated functionality
• Copy-paste with variation — near-duplicate blocks that should be unified
• Unnecessary abstractions — wrapper types, indirection, or overly defensive fallbacks that mask errors
• Unnecessary work — redundant computations, repeated file reads, duplicate API calls, N+1 patterns
• Missed concurrency — independent operations run sequentially when they could be parallel
• Hot-path bloat — blocking work added to startup or per-request paths
• Unnecessary existence checks — pre-checking file/resource existence before operating (TOCTOU anti-pattern); operate directly and handle the error
• Unnecessary comments — comments explaining WHAT the code does (well-named identifiers already do that); keep only non-obvious WHY

For EACH suggestion: verify it does not break existing behavior by checking call sites and usages. Discard cosmetic-only suggestions (renames, formatting).

Agent 4: Readability & Go Idioms

Review git diff $BASE for code that is hard to read, maintain, or reason about:

• Poor factoring — functions doing multiple jobs, tangled control flow, or missing helper extraction where a small local helper would clarify behavior
• Mixed abstraction levels — high-level orchestration mixed with low-level IO, parsing, protocol, or data-structure details; low-level helpers that also make workflow or policy decisions
• Generated-code smell — repetitive pasted logic, shallow wrappers, generic names, or code that reads like it was assembled without domain intent
• Data-flow opacity — values transformed across too many steps, unclear ownership, hidden mutation, pass-through helper chains, or state threaded through unrelated code
• Control-flow complexity — deeply nested conditionals, boolean flag plumbing, early returns used inconsistently, or error paths that obscure the main path
• Naming clarity — names that hide domain meaning or force callers to inspect implementation to understand usage
• Go API readability — ambiguous (result, bool) returns outside clear comma-ok/presence checks, oversized interfaces, unnecessary pointer indirection, or cleverness where explicit Go would be clearer
• Error readability — errors that lose operation/context, wrap inconsistently, or make call sites branch on strings/booleans instead of clear errors or typed status

For EACH finding: explain the readability cost in concrete maintenance terms. Prefer small, local refactor suggestions. Discard formatting-only, gofmt-only, or personal taste comments.

Agent 5: Clean Go & Modern Go (Go diffs only)

Use the local pfleidi:clean-go skill as the source of truth: skills/pfleidi/clean-go/SKILL.md.

Review only changed Go code plus surrounding source, tests, interfaces, and call sites needed to verify findings. Apply the skill's Clean Go checks and version-gated Modern Go checks. This includes the modern-go guidance incorporated from JetBrains' use-modern-go skill: detect the relevant go.mod target version, only suggest features available for that version, and do not perform blanket modernization.

Focus on concrete changed-code findings around composable functions, abstraction level, function size/signatures, errors, pointers, small interfaces, any/interface{}, testing guidance from skills/pfleidi/testing/SKILL.md, and modern standard-library helpers. Discard findings that would merely restyle existing code or require a broad rewrite unrelated to the current diff.

Second-Pass Coverage Sweep

After the first-pass agents complete, run a second independent review pass before synthesis. The goal is recall: catch high-confidence findings that the lens-specific agents may have missed.

Launch one fresh coverage agent with origin/main as the base ref, the full list of changed files, the review context, and the review philosophy above. Do not pass the first-pass findings to this agent.

Ask the coverage agent to:

• Re-read the changed files and the surrounding code needed to understand each changed path.
• Trace changed behavior through callers, callees, tests, configuration, migrations, generated interfaces, and user/API entry points where relevant.
• Search the repository for related patterns, duplicated logic, and existing helpers that affect the changed code.
• Look across all lenses together: security, correctness, tests, simplification, readability, performance, and Go cleanliness when applicable.
• Prioritize missed Required findings over optional improvements.
• Return only high-confidence findings with concrete file:line evidence and a short explanation of the traced path.

Then compare the second-pass findings with the first-pass findings. Deduplicate overlaps, verify any new claim by reading source yourself, and discard anything that cannot be confirmed.

3. Synthesize Report

After all launched agents complete:

1. Collect findings from both the first-pass agents and the second-pass coverage sweep
2. Deduplicate — merge findings from different agents that point to the same underlying issue
3. Verify — for any finding where the agent did not cite a specific file:line with evidence, read the source and confirm or discard it
4. Group by file
5. Sort by severity within each file: Critical > High > Medium > Low

Severity Definitions

• Critical — Must fix before merge. Bugs, security vulnerabilities, data loss risk, race conditions with observable impact.
• High — Should fix before merge. Missing error handling, meaningful test gaps, performance issues on hot paths.
• Medium — Worth fixing. Code reuse opportunities, unnecessary complexity, readability problems that make future changes error-prone, minor efficiency improvements.
• Low — Optional. Minor readability improvements or cosmetic suggestions.

Relevance Classification

For each finding, classify as:

• Required — The change does not work correctly without this fix in light of the review context. Bugs, missing error handling that causes failures, security vulnerabilities, race conditions, contradictions of stated intent, or missing tests for intended behavior that would likely fail. The branch should not merge without addressing these.
• Improvement — Valid finding, but the change works correctly without it. Better factoring, clearer Go APIs, using existing helpers, code reuse, unnecessary complexity, style. Worth addressing in a follow-up, not in this branch.

Autofix Eligibility

Mark each Required finding as Autofix eligible or Needs decision:

• Autofix eligible — source-backed, high confidence, minimal fix is clear, no new dependencies, no shared/public interface change, no product/design choice, no broad refactor, and the directly related verification path is clear.
• Needs decision — any Required finding that fails one of the autofix checks, including intentional behavior questions, API shape changes, cross-cutting refactors, or fixes where multiple reasonable approaches exist.

Present findings as compact tables, not prose blocks. Use one summary table for scanning and one details table for evidence and fixes.

Summary table format:

Details table format:

Keep table cells short and scannable. Put the smallest useful quote or evidence in the table rather than full paragraphs. Escape | characters inside code or text so the table remains valid Markdown. Use n/a for Autofix on Improvements. The Sources column lists the agents that independently found or confirmed the issue, such as security, correctness, readability, clean-go, or coverage.

If no findings exist at a severity level, omit that section.

If there are 0 findings across all agents, report that the review is clean and stop.

4. Present Report and Proceed With Default Fixes

Present findings in two sections:

Required

Table of findings classified as Required, sorted by severity. Include the Autofix value for each finding. Follow it with the details table for those same Required findings.

Improvements (follow-up)

Table of findings classified as Improvement, continuing the numbering. These are presented for awareness but are NOT included in the fix cycle by default. Follow it with the details table for those same Improvement findings.

End with a one-paragraph summary: total required vs improvement findings, overall merge-readiness assessment, and any patterns across files.

Before editing, present a planned-autofix table for Autofix eligible Required findings:

Do not ask the user to choose a mode. Immediately proceed to Step 5 for Autofix eligible Required findings after showing the planned-autofix table. Do not fix Improvements by default.

If there are Required findings but none are Autofix eligible, stop after the report and list the exact decisions needed.

5. Fix Cycle

Scope Rules

• Make the MINIMAL change that addresses the finding
• Keep the diff limited to files and lines directly required by the finding
• First decide whether the finding is local or systemic. Fix at the narrowest correct level; do not add a local workaround that hides a shared/root-cause bug.
• If the finding requires a behavior-changing code fix, add or update the directly related test in the same fix step. Prefer TDD, but complete the focused red-to-green cycle before stopping: write/update the failing test, confirm it fails, implement the fix, confirm the focused test passes. Do not stop after only adding the failing test unless the user explicitly asks.
• Do NOT rename variables, reformat code, or touch lines outside the finding scope
• Do NOT refactor adjacent code, even if it looks related
• Do NOT create any git commits — code changes only

Default Batched Fixes

Fix all Autofix eligible Required findings in report order by default. Do not ask which findings to fix.

Choose an artifact directory using the AGENTS.md temporary artifact rule with agent name pfleidi-review:

• Use ./tmp/pfleidi-review/ only when ./tmp/ already exists and is already ignored.
• If no project-local artifact directory is available, do not create file artifacts by default; keep ledger/log/cache information in the response and mark file paths n/a. Ask before using /tmp/pfleidi-review/ or modifying ignore files.

When an artifact directory is available, create a temporary fix ledger at <artifact-dir>/review-<repo-name>-<timestamp>.md before editing. If no artifact directory is available, keep the same ledger fields in the final summary table instead. Update the ledger after each finding with:

• Finding number, status, and source location.
• Files touched.
• What changed and why.
• Related tests or verification commands.
• Rollback notes sufficient for the user to understand how to revert the finding-specific change manually.

For each Autofix eligible finding:

• Read the relevant code to confirm the fix approach
• Re-check eligibility before editing; if the fix is no longer clearly eligible, mark it Needs decision and continue to the next finding
• Implement the fix — ONLY the code changes for that single finding
• Add or update the directly related test in the same diff when the fix changes behavior; if using TDD, complete red-to-green before moving on; if no test is added, state why
• Keep the diff limited to files and lines directly required by that finding
• If a fix would require changing a function signature in a shared interface, adding a dependency, expanding scope outside the finding, or making an ambiguous product/design choice, skip that finding as Needs decision and continue
• Track the exact files changed, what changed, and why the change addresses the finding

If a skipped finding has partial edits, remove only your own partial edits for that finding before continuing. If you cannot safely isolate those partial edits, stop and explain the conflict.

After all eligible fixes are applied, proceed directly to Step 6 (Verify Fixes). Do NOT show a diff yet.

6. Verify Fixes

Run the project's compile/build, lint, and test commands scoped to only the changed files and their directly related tests. Use safe background batches for independent validators instead of running every command sequentially.

When selecting verification commands, reuse <artifact-dir>/verification-<repo-name>.md if an artifact directory is available and the cache is fresh under the cache rules from pfleidi:pr; otherwise discover the smallest relevant lint/test/build commands. Update the cache only when an artifact directory is available.

• Build / compile — run a relevant compile/build command when one is discoverable for the changed production code.
• Lint / static analysis — run the project's documented lint task, scoped to the files that were modified by the fixes when the task supports scoping. Prefer lint-specific task wrappers such as make lint or mise run lint over invoking linter binaries directly. Do not use aggregate check, ci, or verify tasks unless you have confirmed they only run lint/static analysis. If the documented lint task cannot be scoped, run the smallest relevant project lint task.
• Tests — run only the test files that cover the modified code (same package, same module, co-located test files). Do NOT run the full test suite.

If no compile/build command or project lint task exists, state that explicitly instead of assuming an unavailable command.

Run formatters, generators, snapshot updates, or other mutating commands alone before validators that depend on their output. Run independent read-only validators concurrently when they do not require the same exclusive service, port, database, fixture directory, or generated output. Keep integration/e2e/service-backed commands separate unless the project documents that they are parallel-safe.

For each background batch, start every command from the same working-tree state, capture stdout/stderr/exit status from the tool, do not edit files while the batch is running, and wait for every command to finish. Run each selected validator directly, for example mise run lint, go test ..., or npm test -- .... Do not wrap validators in sh -c, shell redirection, tee, command separators, or pipelines solely to write logs; that defeats command-prefix approvals and causes extra permission prompts. If an artifact directory is available and file logs can be written after the command completes without rerunning through a shell wrapper, save them under <artifact-dir>/logs-<repo-name>-<timestamp>/; otherwise mark the full-log path as n/a. If files change after a failed batch, none of that batch's successful results count as current verification.

Show verification as a compact table:

For failures or short outputs, show complete output in the relevant-output column or immediately below the table. For long successful outputs, show the relevant excerpt and log path.

On Failure: Auto-Fix

If compile/build, lint, or tests fail due to issues introduced by the review fixes:

1. Read the error output and identify every failure
2. Fix all issues — apply the minimal changes needed
3. Re-run the failing commands using the same safe batching rules
4. Show the complete output again

Cap at 2 fix attempts. If still failing after 2 rounds, present the remaining failures to the user with full output. Do not describe the work as done or commit-ready while compile/build status is failing or unknown for changed production code.

7. Present Results

Once verification passes (or the user has seen the remaining failures), present a summary table. If compile/build did not pass for code changes, say the work is not commit-ready before the table. Do NOT show a diff — the Edit tool already showed each change inline.

Also present a rollback/traceability table and the ledger path:

Ledger: <artifact-dir>/review-<repo-name>-<timestamp>.md, or n/a when no project-local artifact directory was available.

STOP and wait. The user decides what to commit.

8. Post-Fix

• If the user asks for changes, apply them
• If the user asks to revert specific fixes, revert ONLY those changes using surgical git checkout of the affected lines
• Do NOT commit. The user handles commits on their own terms.

2w ago·1m·4 calls

Three review agents running in parallel. Waiting for results before the second-pass coverage sweep.