git-workflow — pre-validator-self-audit

Detail page of the git-workflow recipe card.

The pre-validator self-audit — one pass to avoid N BLOCK cycles

Why (measured, umbrella #286)

Across 9 docs PRs landed in one session, 6 FIRST pushes BLOCKed; 17 validator runs total. Every block was one of five classes, each detectable BEFORE the first push. A BLOCK cycle costs a full charly/pr-validator run plus a re-review; a pre-push self-audit removes it. The one PR that PASSed first try had done this pass; the ones that did not, blocked.

The five classes (root causes)

1. Body claims the diff does not carry (body-truthfulness): a pasted command output that cannot reproduce (a CLAUDE.md sweep returning (none) while a non-excluded file still held the token); a placeholder command (<org-map check>) instead of the executed one; a title advertising a change absent from the diff.
2. Change-class / tier misclassification: documentation-only / documentation reviewed claimed while a non-.md code/config file changed.
3. A1 incomplete rule accounting: only some rules answered; a bare N/A. with no reason.
4. Surfaced-failure parking (R2/B14b): a failing check pasted with “pre-existing / unrelated / environmental” framing and neither fixed nor routed to a named batch.
5. Split cutover (B15/R2): content removed from surface A in this PR while its replacement home on surface B is deferred.

The preflight (run BEFORE the first push)

1. git fetch origin; if BEHIND, gh pr update-branch BEFORE writing the body, so the diff is against current origin/main.
2. Class the diff from git diff --stat $(git merge-base origin/main HEAD)..HEAD — NEVER from intent. docs-only iff EVERY path is *.md/comment-only/all-doc-submodule; else code/config, and documentation reviewed is forbidden. Pick a tier the pasted evidence supports.
3. Paste ONLY commands you executed on THIS head, with their REAL output. No placeholders. Show every filter/pathspec. If a known survivor exists (a deliberately deferred reference), name it — never imply the sweep is complete when it is not.
4. Account for EVERY applicable rule (the repo’s numbered rules AND R1–R10) with a one-line HOW or N/A — <reason>; never a bare N/A.
5. NEVER surface a failure you cannot own. Either fix it (including the coupled pin/migrate, not just the manifest) or omit it and paste only the repo’s authoritative gate. If it is genuinely separate, name the EXACT owning batch/task id — “pre-existing/unrelated” with no exit is a BLOCK.
6. One cutover = remove AND place in the SAME change. If the replacement home does not exist yet, land the home first, or name a DISTINCT immediate-next batch cutover with a stated non-blocking rationale (the pointer must not be empty).
7. Guardrail / validator-spec edits (a validator’s own prompt, a FORBIDDEN_* list, a gate) are T4 self-modifying-security changes: they need a maintainer-account sign-off or must be split into their own signed-off change. Never WEAKEN a marker without pasted proof; prefer strengthening.
8. The PR title must match the diff.
9. Arm the watcher (marketplace/scripts/pr_state_watch.sh <owner>/<repo> <pr>), read every verdict IN FULL, fix ALL blocks in ONE commit, and push a NEW commit — never re-dispatch the same head, never push again while at the auto-close block limit.

For the delegating parent

A parent brief that spawns a worker MUST include this preflight, AND: (a) the worker reads the LATEST skill from origin/main (the worktree’s marketplace/ may be a stale gitlink), (b) it checks upstream origin/main and updates the base before writing the body, (c) it reports the FULL final verdict (not a paraphrase). The measured result: briefs carrying this pass produced first-try PASSes; briefs without it produced BLOCK→BLOCK→PASS.