feat(hygiene): lint check for git merge-conflict markers in committed files — Aaron 2026-04-26 ask

[AceHack]

Summary

Aaron 2026-04-26: "maybe we should hygene for <<<<<<< HEAD and >>>>>>> ======= things like that in our files incase we ever accidently botch a merge, happens to the best of us humans too."

Substantive structural fix preventing a class of bug at the substrate-integrity layer.

Why this matters

• Per Otto-339 (anywhere-means-anywhere): conflict markers in committed files would shift weights wrongly when read by AI — the marker tokens are real text that enters cognition substrate.
• Per Otto-341 (mechanism-not-vigilance): catching botched merges via CI is the right shape; relying on each agent / human / harness to remember to remove markers fails statistically over time.
• "Happens to the best of us humans too" — Aaron names this as universal failure mode, not AI-specific.

Three changes

1. tools/hygiene/check-no-conflict-markers.sh — searches all git ls-files tracked files for the three marker patterns at line-start (avoids false positives in inline prose). Reports first violations with file + line. Self-allowlist: this script itself + Otto-341 substrate file (which legitimately documents the markers as part of merge-resolution discipline).

2. .github/workflows/gate.yml lint-no-conflict-markers job — wires the check into CI. Fast (2-minute timeout).

3. Composes with existing tools/hygiene/check-tick-history-order.sh pattern — same architectural shape: detection at commit/push time via CI, no relying on agent vigilance.

What this DOES NOT do

• Does NOT auto-resolve conflicts — the fix is the committer's responsibility (CI is detection, not auto-correction)
• Does NOT check untracked files — only committed/staged matters
• Does NOT prevent the conflict from happening — it catches the unresolved result post-commit

Self-tests

• shellcheck --severity=style: pass
• actionlint .github/workflows/gate.yml: pass
• check script on current repo state: 0 violations (clean)

Composes with

• Otto-339 (mechanism layer this prevents drift on)
• Otto-341 (CI gate as discipline-mechanism; same shape as check-tick-history-order.sh)
• Otto-238 (allowlist mechanism is itself retraction-safe — false positives can be added explicitly with stated reason)

Test plan

• Self-tests above pass locally
• CI lint-no-conflict-markers job runs and passes on this PR
• Existing CI lints continue to pass

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a new hygiene lint that fails CI when tracked files contain unresolved git merge-conflict markers, preventing accidental conflict-marker leakage into committed substrate and CI artifacts.

Changes:

• Add tools/hygiene/check-no-conflict-markers.sh to scan tracked files for conflict-marker lines at column 1.
• Wire the new check into .github/workflows/gate.yml as a dedicated lint-no-conflict-markers job.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
tools/hygiene/check-no-conflict-markers.sh	New bash script to detect unresolved merge-conflict markers in tracked files.
.github/workflows/gate.yml	Adds a CI job that runs the new conflict-marker check.

[Copilot]

P1: ALLOWLIST contains a hard-coded path to a memory file that isn’t present in the repo. This dead entry makes it unclear what is actually exempt; either remove it until the file exists or replace it with the correct existing path that legitimately contains marker examples.

Suggested change

	# Substrate / research files documenting merge-conflict resolution
	# discipline. They legitimately contain the marker tokens as
	# examples. Allowed because the file body is meta-discussion not
	# accidental marker leakage.
	"memory/feedback_otto_341_lint_suppression_is_self_deception_noise_signal_or_underlying_fix_greenfield_large_refactors_welcome_training_data_human_shortcut_bias_2026_04_26.md"

[Copilot]

P1: This runs grep separately for every tracked file, which will also scan large/binary tracked artifacts (e.g., the PDFs under docs/). Consider using git grep with binary ignored or otherwise skipping known-binary/large files so the check stays reliably fast under the 2-minute CI timeout.

Suggested change

	while IFS= read -r file; do
	if is_allowed "$file"; then
	continue
	fi
	if [[ ! -f "$file" ]]; then
	continue
	fi
	# Use grep -E with line numbers; binary files quietly skipped.
	if hits=$(grep -nE "$PATTERN" "$file" 2>/dev/null); then
	while IFS= read -r line; do
	violations=$((violations + 1))
	if [[ -z "$first_hit" ]]; then
	first_hit="$file:$line"
	fi
	echo "VIOLATION: $file:$line" >&2
	done <<< "$hits"
	fi
	done < <(git ls-files)
	git_grep_args=(git grep -nI -E "$PATTERN" -- .)
	for allowed in "${ALLOWLIST[@]}"; do
	git_grep_args+=(":(exclude)$allowed")
	done
	git_grep_args+=(":(exclude)references/**")
	# Search tracked text files in one pass; `-I` skips binary content.
	if hits="$("${git_grep_args[@]}" 2>/dev/null)"; then
	while IFS= read -r hit; do
	violations=$((violations + 1))
	if [[ -z "$first_hit" ]]; then
	first_hit="$hit"
	fi
	echo "VIOLATION: $hit" >&2
	done <<< "$hits"
	fi

[Copilot]

P2: The doc says “Untracked files — only committed/staged matters”, but the implementation reads the working tree content of git ls-files paths (so it won’t necessarily reflect what’s staged in the index for partial stages). Suggest rewording to “tracked working tree files” or explicitly scanning the index if staged-only detection is intended.

[Copilot]

P1 (repo convention): This comment adds direct contributor-name attribution on a current-state code surface. docs/AGENT-BEST-PRACTICES.md requires role-refs in code/workflows and reserves names for the closed list of history surfaces; please rewrite these references accordingly.

Suggested change

	# Why this exists (Aaron 2026-04-26):
	# Why this exists (human contributor note, 2026-04-26):

[Copilot]

P1 (repo convention): This workflow comment introduces direct contributor-name attribution (“Aaron …”) on a current-state CI surface. Per docs/AGENT-BEST-PRACTICES.md “No name attribution…”, please rewrite to role-refs (e.g., “human maintainer request (2026-04-26)”) and keep names to the enumerated history surfaces only.