agent-preflight: surface check-only mode for formatting gates

Context

A commit/PR lane on 2026-07-01 hit a concrete preflight-contract surprise: plain npm run agent-preflight mutated touched files by running check-block-alignment --fix, even though the operator mental model and the command name read like a preflight check. That mutation was not unsafe, but it created extra diff-review and staging cost while trying to prove that a PR was already ready.

Verify-before-assert evidence:

• package.json defines agent-preflight as node ./buildScripts/util/agent-preflight.mjs.
• buildScripts/util/agent-preflight.mjs exposes .option('--no-fix', 'Skip the check-block-alignment --fix pass.').
• The default path calls check-block-alignment.mjs --fix when options.fix is true, then calls check-block-alignment.mjs --staged.
• .agents/skills/pull-request/references/pull-request-workflow.md tells authors to run npm run agent-preflight -- [files...], but does not mention the mutating default or the --no-fix check-only mode.
• Live latest-open sweep: checked latest 20 open issues at 2026-07-01T17:42:49Z; no equivalent open ticket found.
• Duplicate sweep: checked GitHub searches for agent-preflight check-block-alignment no-fix mutates files, repo resources/content / resources/content/issues / resources/content/discussions, and Neo Knowledge Base ticket search. Closest prior is closed #13813, which created the standalone preflight bundle; no open duplicate covers surfacing --no-fix or separating check-only semantics.
• A2A in-flight sweep: checked latest 30 messages; no overlapping [lane-claim] or [lane-intent] for this scope.

The Problem

agent-preflight currently mixes two distinct operator intents behind one default command:

1. Repair mode: normalize block alignment before commit, accepting mechanical edits.
2. Check-only mode: prove that the staged/worktree state is ready without modifying it.

Both modes are useful. The problem is discoverability and contract clarity. A command named "preflight" and documented in the PR workflow as a gate reads like a validation step. When it silently performs a formatting write first, an author can misclassify the resulting diff as new logical drift, restage more files than expected, or spend time manually undoing/reapplying formatting that the hook would have required anyway.

This also obscures which command should be used in different moments:

• Before polishing a branch: mutating repair is fine.
• Before validating a PR body or post-rebase state: check-only is often the safer mental model.
• In docs/skills: agents need the mode split explicitly, because they execute commands literally and report evidence from command names.

The Architectural Reality

The substrate already has most of the machinery:

• buildScripts/util/agent-preflight.mjs owns the bundled author preflight surface.
• check-block-alignment.mjs already has explicit check and --fix modes.
• agent-preflight already exposes --no-fix; the missing piece is command-contract surfacing and tests/docs that keep the mode split intentional.
• pull-request-workflow.md is the main consumer-facing authority that tells agents when to run the command.

This is not a request to remove auto-fix. The existing repair default may remain correct, but the workflow must make it explicit and provide a check-only recipe at validation boundaries.

The Fix

Make the agent-preflight repair-vs-check contract explicit and mechanically covered.

Possible implementation shape:

• Update agent-preflight CLI help/output so mutating mode is obvious, e.g. command description or startup line names check-block-alignment --fix when active and names --no-fix as check-only.
• Update the PR workflow to distinguish repair preflight from final validation preflight, with examples for:
  • npm run agent-preflight -- <files> when the author wants auto-fix repair.
  • npm run agent-preflight -- --no-fix <files> when the author wants a non-mutating validation pass.
  • npm run agent-preflight -- --pr-body <draft.md> for PR-body-only lint where no source gates are in scope.
• Add or adjust unit coverage for agent-preflight argument parsing / run orchestration so --no-fix skips the check-block-alignment --fix gate while still running the staged/check gate.

Contract Ledger Matrix

Decision Record impact

none. This is developer/agent workflow clarity around an existing build-script surface.

Acceptance Criteria

• agent-preflight --help or command output makes the default mutating alignment-repair behavior discoverable.
• The PR workflow documents when to use default repair mode and when to use --no-fix check-only mode.
• Tests prove --no-fix does not invoke check-block-alignment --fix.
• Tests prove default mode still invokes the repair gate before the staged/check gate.
• Existing PR-body lint behavior remains unchanged.
• No new workflow or CI job is added; this stays in the existing build-script / workflow-doc substrate.

Out of Scope

• Replacing check-block-alignment with another formatter.
• Removing the default repair behavior without a separate architecture decision.
• Changing husky/lint-staged pre-commit behavior.
• Broad PR-review or lifecycle workflow rewrites.

Related

• #13813 — closed predecessor that created the standalone preflight bundle.
• #13720 — closed staged-scope block-alignment hook work.
• #14212 — closed block-alignment overreach/regression work.
• buildScripts/util/agent-preflight.mjs
• buildScripts/util/check-block-alignment.mjs
• .agents/skills/pull-request/references/pull-request-workflow.md

Origin Session ID: c0dfa949-22de-4daf-bbd2-1e093383fefc

Handoff Retrieval Hint: "agent-preflight no-fix check-only default mutates check-block-alignment --fix PR workflow"