fix(docs-hygiene): audit-noise silently skips uncommitted paths git quotes or renders with an arrow

[kyle-sexton]

Summary

audit-noise's default-target router parses git status --porcelain v1 output. Two classes of path survive that parse incorrectly and are silently dropped from the target list, so the run reports a clean tree while real findings sit in the working tree.

This is the same defect class as #3126 (fixed for audit-comment-residue in #3151). It was found while fixing that one: audit-noise's parse was initially ported into audit-comment-residue as the mature, proven implementation, and review on #3151 showed it is not.

Observed in docs-hygiene@0.18.3, current at dff0942. Confirmed against git 2.55.

The two cases

Input	v1 renders as	parse yields
café.md (default core.quotePath)	?? "caf\303\251.md"	caf\303\251.md — literal escape sequence, names nothing
left -> right.md (an ordinary file)	?? "left -> right.md"	right.md" — arrow split misfires, names nothing

audit-noise strips the surrounding quotes and unescapes \" (scripts/detect.sh, the porcelain branch), but does not decode C-style octal escapes. It also splits on -> unconditionally, so an ordinary filename containing that substring is mistaken for a rename.

Reproduction

A git repo containing two untracked files, café.md and left -> right.md, each with a line matching the citation shape (The helper was renamed to newName in a later revision.):

$ git status --porcelain
?? "caf\303\251.md"
?? "left -> right.md"

$ detect.sh                                    # default target
Summary total: files=0 T1=0 T2=0 T3=0

$ detect.sh "café.md" "left -> right.md"       # control, explicit paths
Summary total: files=2 T1=2 T2=0 T3=0

The findings exist. Only the default-target path misses them.

Why it matters

A false negative in an audit tool is worse than an error. An error prompts a retry; a confident files=0 ends the investigation. The caller gets no signal that anything was skipped.

Suggested fix

Read the NUL-delimited --porcelain -z form, which git documents as performing no quoting or backslash-escaping. This is what #3151 landed for audit-comment-residue after review rejected patching the v1 parse — writing a full C-style decoder (\303\251, \t, \n, \\) is avoidable surface area when a format with no escaping exists.

One detail worth carrying over, since it is the reverse of the v1 display order: under -z a rename emits the new path first and the original as a following record.

v1:  R  plain.md -> "renamed one.md"
-z:  R  renamed one.md\0plain.md\0

The second record must be consumed and discarded, or the audit targets a path that no longer exists.

Note audit-noise's router also handles --paths-file and offset/limit pagination, neither of which is affected — the change is confined to the porcelain branch. Worth regression fixtures for all three cases (spaced, non-ASCII, arrow-bearing) plus the discarded rename original; see audit-comment-residue's detect.test.sh case 9/10 in #3151 for the shape.

[kyle-sexton]

[kyle-sexton]

[kyle-sexton]

Status note: #3171 (0.19.1) landed a partial fix. What remains is narrower than this issue's body implies.

Covered by #3171 — the rename split is now gated on the R/C status letter, so an ordinary file named left -> right.md is no longer misparsed as a rename, and \\ is unescaped alongside \".

Still open — the octal-escape case. scripts/detect.sh:145 still reads the v1 form:

done < <(git status --porcelain 2>/dev/null)

The -z option is mentioned at L141, but only in a comment noting it "would close the class outright". So café.md still arrives as "caf\303\251.md" and resolves to nothing, and the same holds for a tab or any other control byte.

So of the two cases in the table above, the second is fixed and the first is not.

For reference, #3151 took the -z route for audit-comment-residue rather than extending the unescaper, on the reasoning that a full C-style decoder (\303\251, \t, \n, \\) is avoidable surface area when a format that performs no escaping already exists. That PR also moved the skill's SKILL.md preview parser in the same change, because the two parsers have a parity test that would otherwise diverge silently — audit-noise is worth checking for the same coupling before its fix lands.

---

Generated by Claude Code

[kyle-sexton]

Worker melo-lap-001-worker-202608230449 — durability checkpoint. Branch pushed, PR not yet open.

Branch: fix/3164-audit-noise-porcelain-z @ ca2d466f6 (rebased onto e64ed12be).

Disposition finding: this issue is NOT a duplicate of #3143

This item was dispatched on the premise that merged PR #3171 had already delivered both of #3164's path classes, making it a zombie. That premise is wrong, and the evidence is in #3171 itself.

#3171 (0.19.1) delivered two of the three classes:

• the [RC] gate on the rename split, so left -> right.md is no longer mis-split;
• the \ unescape alongside \", so back\-slash.md resolves.

#3171 explicitly recorded the third as an open residual — in its PR body and as a comment at the parse site in detect.sh:

Known residual, recorded at the parse site: git's octal escapes (\NNN) for control and non-ASCII bytes are still not decoded, so those paths continue to miss.

That residual is exactly #3164's café.md case, and it was still live on main. Reproduced against git 2.55 in a repo holding café.md and plain.md, each with one citation-shape line:

$ detect.sh                       # default target
Summary total: files=1 T1=1 T2=0 T3=0     <- café.md silently missing

$ detect.sh café.md plain.md      # control, explicit paths
Summary total: files=2 T1=2 T2=0 T3=0

What the branch adds

Only the residual. detect.sh's porcelain branch reads git status --porcelain -z — no quoting, no backslash-escaping, every byte verbatim — which closes the whole escape class instead of extending the string parse a third time. This is the fix #3164's own "Suggested fix" section proposes. Rename handling becomes structural: under -z the new path is in the record and the original follows as a second record, consumed and discarded. No arrow is matched anywhere, so this subsumes #3171's gate rather than re-delivering it.

--paths-file and --offset/--limit pagination are untouched.

Corrections to stale cross-references

• fix(docs-hygiene): audit-noise silently skips uncommitted paths git quotes or renders with an arrow #3164's body says fix(code-tidying): read porcelain -z so escaped paths reach the audit #3151 "landed" the -z fix for audit-comment-residue. It did not — fix(code-tidying): read porcelain -z so escaped paths reach the audit #3151 is still open; fix(code-tidying): parse porcelain by slicing so spaced paths survive discovery #3140 landed the string-parse version.
• The dispatch brief said PR feat(docs-hygiene): negation-without-positive detector on audit-noise, wired to the findings relay (0.20.0) #3180 also edits audit-noise/scripts/detect.sh. It does not — it touches detect.test.sh, SKILL.md, CHANGELOG.md, plugin.json, evals.json, and lib/noise-shapes.sh.
• Version target moved twice mid-flight as feat(docs-hygiene): audit-noise gains three residue shapes (0.20.0) #3162 (0.20.0) and fix(docs-hygiene): unbreak audit-noise's SKILL.md preview for quoted paths (0.20.1) #3187 (0.20.1) merged. This branch is 0.20.2.

Adjacent findings for triage (not in this branch)

1. SKILL.md preview still shows escaped names. fix(docs-hygiene): unbreak audit-noise's SKILL.md preview for quoted paths (0.20.1) #3187 (0.20.1) changed the Uncommitted .md files: preview grep to -E '\.md"?$', so quoted records are no longer dropped — but they are still displayed octal-escaped ("caf\303\251.md"), because that line previews via grep rather than the parse. Left alone deliberately: that surface belongs to fix(docs-hygiene): unbreak audit-noise's SKILL.md preview for quoted paths (0.20.1) #3187's author and sits outside fix(docs-hygiene): audit-noise silently skips uncommitted paths git quotes or renders with an arrow #3164's porcelain-branch scope. No issue tracks it.
2. Untracked directories are still skipped. git status collapses them to ?? sub/, which fails detect.sh's *.md filter, so markdown inside an untracked directory is silently missed — the same false-negative class this issue is about. The repo's own plugins/claude-config/skills/audit-pass/reference/determinism-tiers.md already states --untracked-files=all "is required, not a preference". Not in fix(docs-hygiene): audit-noise silently skips uncommitted paths git quotes or renders with an arrow #3164's scope; worth its own issue.