fix: repair CRLF working trees that .gitattributes cannot reach (#1793)

[bradygaster]

Closes #1793. Working as EECOM (Core Dev).

The residual, not the fix

#1790 added *.mjs text eol=lf. That rule governs checkout. Git only rewrites a working file when a pull also changes that path's index content — and these files are already stored LF. So the merge is a no-op on disk, and every pre-#1790 Windows checkout stays CRLF indefinitely. Pulling the fix does not repair your tree.

I verified the mechanism rather than assuming it. In this state the file is content-clean: git's checkin filter normalizes the CRLF away, so git hash-object --path equals git rev-parse :<path> exactly and git diff is empty. Git has nothing to restore, which is why the condition is so durable — and why git checkout -- <path> is not a reliable remedy for it.

The failure is silent. A CRLF shebang survives Vite's shebang stripping as a bare #, the module fails to parse, and vitest reports no tests — a zero that reads as green (#1788).

What this adds

npm run fix:crlf	The one documented command. Repairs from the index with git checkout-index -f, which writes unconditionally. Gated on "no content difference" — a file with real uncommitted edits is skipped and reported, never overwritten. Re-measures after writing rather than trusting the write.
squad doctor → working tree line endings	Flags any eol=lf-pinned file still CRLF on disk, names up to 5 plus a +N more, and cites the fix. Returns not applicable outside a git repo or when nothing is pinned.
Shared detection	listWorktreeCrlf / listContentModified exported from scripts/check-shebang-eol.mjs, which already owns this invariant family — not a third parallel implementation.
CONTRIBUTING.md	Documents the class, the symptom, the repair, and why the two obvious wrong fixes are wrong.

Two things I deliberately did not do

No git add --renormalize . — that rewrites the index, the opposite side of the defect; the blobs are already correct, the disk is what's wrong. It would also sweep nearly every CRLF-storing .ts blob in the repo into one churn commit, an exclusion .gitattributes documents on purpose. The repair correctly produces no commit at all. Diff here is 7 files.

No CI gate — CI always has a fresh checkout, so a working-tree assertion there could never observe the failure it exists to catch. That is a permanently-green gate, which is equivalent to no gate (.squad/decisions.md, 2026-08-20 test bar; the shared root cause of #1824/#1812/#1801/#1822/#1827). This condition is local-only by nature, so it belongs in squad doctor, which runs on the developer's actual disk. The omission is documented in-comment in check-shebang-eol.mjs so nobody "fixes" it later.

Proof the check can fail

A check that only passes on a clean tree proves nothing. I forced the three files from the issue to CRLF and measured.

Before — known-bad input:

$ git ls-files --eol -- <the three files>
i/lf    w/crlf  attr/text eol=lf        packages/squad-cli/scripts/patch-esm-imports.mjs
i/lf    w/crlf  attr/text eol=lf        scripts/check-changeset-drift.mjs
i/lf    w/crlf  attr/text eol=lf        scripts/promote-insider-tag.mjs

$ squad doctor
❌  working tree line endings — 3 of 174 LF-pinned file(s) still have CRLF on disk
    (packages/squad-cli/scripts/patch-esm-imports.mjs, scripts/check-changeset-drift.mjs,
     scripts/promote-insider-tag.mjs). A .gitattributes eol=lf rule does not rewrite files
     that were already checked out, so pulling the fix does not repair an existing checkout.
     A CRLF shebang makes a vitest suite silently load zero tests.
     Run 'npm run fix:crlf' to repair, then re-run 'squad doctor' to confirm. To inspect
     the raw state: 'git ls-files --eol' -- every entry whose attr includes eol=lf should
     read w/lf (the pin is not limited to *.mjs, and neither is this check).
Summary: 12 passed, 1 failed, 0 warnings, 0 info

The three suites in that state — the original symptom, reproduced:

Test Files  3 failed (3)
     Tests  5 failed | 1 passed (6)        ← 29 expected

The remediation:

$ npm run fix:crlf
Repaired 3 file(s) from CRLF to LF on disk:
  packages/squad-cli/scripts/patch-esm-imports.mjs
  scripts/check-changeset-drift.mjs
  scripts/promote-insider-tag.mjs

Verified: re-measured after the repair and no LF-pinned path reports CRLF on disk.
To inspect the raw state: git ls-files --eol   (every entry whose attr includes eol=lf
should read w/lf -- the pin is not limited to *.mjs).

After:

$ git ls-files --eol
w/crlf count: 0 of 174 LF-pinned (42 of them .mjs)

$ squad doctor
✅  working tree line endings — 174 LF-pinned file(s) all LF on disk
Summary: 13 passed, 0 failed, 0 warnings, 0 info

Test Files  3 passed (3)
     Tests  29 passed (29)

Acceptance criteria

1. ✅ One documented command → every one of the 174 eol=lf-pinned paths reports w/lf, the 42 .mjs among them included.
2. ✅ check-changeset-drift 8 + promote-insider-tag 15 + patch-esm-imports 6 = 29, none reporting no tests.
3. ✅ squad doctor flags any w/crlf .mjs, proven to fail on known-bad input and pass after repair. The check is in fact wider than the criterion asks: it covers every eol=lf-pinned path, not just .mjs.

Tests

14 new in test/scripts/crlf-worktree-repair.test.ts, driving real temp git repos (core.autocrlf=false, committed *.mjs text eol=lf) — not mocks. Coverage includes:

• The fail→pass doctor test asserts fail first, so a stuck-green check cannot pass it.
• repair() never overwrites a file with real uncommitted edits.
• The git ls-files --eol record shape is pinned on both sides, since the attr value contains a space and cannot be whitespace-split.

43 passed (14 new + the 29 restored). npm run lint clean, npm run build clean, node scripts/check-shebang-eol.mjs clean (46 shebanged files pinned to LF, 174 LF-pinned files all storing LF blobs).

Review follow-ups (FIDO)

The remediation hint was scoped narrower than the check. Both doctor.ts and fix-crlf-worktree.mjs printed git ls-files --eol "*.mjs", but the check counts every eol=lf-pinned path — 174, only 42 of them .mjs. A pinned non-.mjs file left CRLF would have verified all-clear. That is the same defect class this PR fixes, so it needed fixing rather than waving off. Both hints widened; a test now asserts the message does not re-narrow, mutation-proven against the old text.

Spaced-path coverage for checkWorktreeEol. It has its own record parser, separate from listWorktreeCrlf, so the two could silently diverge. The new test asserts the check names the spaced file rather than merely failing — mutation-testing showed a truncating parser still returns fail and still counts 1 of 1, so a status-only assertion would have passed it while reporting a filename that does not exist on disk.

Batching comment no longer over-promises. It bounds file count, not argv length. Measured rather than assumed: longest tracked path is 80 chars, so a full 200-file batch is ~16K against the 32767 limit, and overflowing would take a ~164-character mean path. Length accounting deliberately declined, and the comment now says so.

Stopped pinning drift-prone counts. The CRLF-storing .ts blob figure is now described rather than hardcoded — it measures 94 today, and .gitattributes still says 95. Left that file alone; correcting its comment is unrelated churn.

Full suite: 9 failures, all confirmed pre-existing on dev. Two doctor tests failed only under parallel load and pass in isolation; the other 5 I verified by stashing this branch's edits and re-running — they fail identically without my changes. None relate to EOL handling.

Note for review

parseEolRecord is intentionally duplicated between scripts/check-shebang-eol.mjs and doctor.ts. The repo script is not published inside packages/squad-cli, so dist/ cannot import it without breaking every installed CLI. Documented in-comment on both sides, with the parse shape pinned by tests on both sides.

I hit this exact bug while building the fix: the editor wrote scripts/fix-crlf-worktree.mjs with CRLF, it wasn't in the index yet so .gitattributes never smudged it, and the new suite reported no tests with SyntaxError: Invalid or unexpected token. Good confirmation the class is real and easy to reintroduce.

#1788 and #1790 stay open on their own merits — this is the residual, not a duplicate.

[github-actions]

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit f294111

PR Scope: 📦🔧 Mixed (product + infrastructure)

⚠️ 2 item(s) to address before review

Status	Check	Details
✅	Single commit	1 commit — clean history
✅	Not in draft	Ready for review
✅	Branch up to date	Up to date with dev
❌	Copilot review	No Copilot review yet — it may still be processing
✅	Changeset present	Changeset file found
✅	Scope clean	No .squad/ or docs/proposals/ files
✅	No merge conflicts	No merge conflicts
✅	Copilot threads resolved	1 active Copilot thread(s) resolved (2 outdated skipped)
❌	CI passing	1 check(s) failing: test

Files Changed (7 files, +548 −3)

File	+/−
.changeset/doctor-worktree-eol-check.md	+5 −0
CONTRIBUTING.md	+30 −0
package.json	+1 −0
packages/squad-cli/src/cli/commands/doctor.ts	+99 −0
scripts/check-shebang-eol.mjs	+74 −3
scripts/fix-crlf-worktree.mjs	+126 −0
test/scripts/crlf-worktree-repair.test.ts	+213 −0

Total: +548 −3

---

This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

[github-actions]

🟡 Impact Analysis — PR #1831

Risk tier: 🟡 MEDIUM

📊 Summary

Metric	Count
Files changed	7
Files added	3
Files modified	4
Files deleted	0
Modules touched	4
Critical files	1

🎯 Risk Factors

• 7 files changed (6-20 → MEDIUM)
• 4 modules touched (2-4 → MEDIUM)
• Critical files touched: package.json

📦 Modules Affected

root (3 files)

• .changeset/doctor-worktree-eol-check.md
• CONTRIBUTING.md
• package.json

scripts (2 files)

• scripts/check-shebang-eol.mjs
• scripts/fix-crlf-worktree.mjs

squad-cli (1 file)

• packages/squad-cli/src/cli/commands/doctor.ts

tests (1 file)

• test/scripts/crlf-worktree-repair.test.ts

⚠️ Critical Files

• package.json

---

This report is generated automatically for every PR. See #733 for details.

[Copilot]

🟢 Approval recommended

The changes implement the stated remediation and diagnostics with good safety checks and integration test coverage, with only minor output/test-hardening nits noted.

Pull request overview

Adds a local-only remediation for the “LF in index, CRLF on disk” residual after introducing eol=lf rules, and surfaces detection/repair guidance via squad doctor and a single documented npm script.

Changes:

• Introduces npm run fix:crlf (scripts/fix-crlf-worktree.mjs) to rewrite LF-pinned files from the index while skipping real content edits.
• Extends scripts/check-shebang-eol.mjs with shared working-tree CRLF detection (listWorktreeCrlf) and a safety gate (listContentModified).
• Adds a new squad doctor check (checkWorktreeEol) plus documentation and tests covering real temp git repos.

File summaries

File	Description
test/scripts/crlf-worktree-repair.test.ts	New integration tests validating detection, doctor behavior, and safe repair in real git repos.
scripts/fix-crlf-worktree.mjs	New repair script that forces checkout from index for LF-pinned paths that are CRLF on disk.
scripts/check-shebang-eol.mjs	Exports shared helpers to detect LF-pinned files with CRLF in worktree and detect true content modifications.
packages/squad-cli/src/cli/commands/doctor.ts	Adds working tree line endings doctor check and wires it into runDoctor.
package.json	Adds fix:crlf npm script entry point.
CONTRIBUTING.md	Documents the failure mode, symptom, correct repair, and why common “fixes” don’t work.
.changeset/doctor-worktree-eol-check.md	Changeset documenting the new doctor check and repair command.

Review details

Suppressed comments (1)

scripts/fix-crlf-worktree.mjs:106

• This verify hint is currently scoped to *.mjs, but repair() operates on every tracked path pinned to eol=lf (per listWorktreeCrlf). Printing a verification command that matches that broader scope makes the output more accurate.

  console.log('\nVerify with: git ls-files --eol "*.mjs"   (every entry should read w/lf)');

• Files reviewed: 7/7 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[bradygaster]

Verdict: APPROVE WITH NITS

Independent FIDO repro passed. I built the PR worktree with npm run build, then verified the local-only failure mode CI cannot exercise:

• Baseline doctor: 174 LF-pinned file(s) all LF on disk; Summary: 13 passed, 0 failed.
• Forced these three LF-pinned files to CRLF on disk without changing the index: packages/squad-cli/scripts/patch-esm-imports.mjs, scripts/check-changeset-drift.mjs, scripts/promote-insider-tag.mjs.
• git diff --name-only -- <files> showed no content diff, while git ls-files --eol showed i/lf w/crlf attr/text eol=lf for all three.
• Poisoned doctor reported the right failure and named all three files: 3 of 174 LF-pinned file(s) still have CRLF on disk; Summary: 12 passed, 1 failed.
• npm run fix:crlf repaired all three and exited 0; post-repair .mjs count was 0 of 42 with w/crlf; doctor returned to Summary: 13 passed, 0 failed.
• Guard check held: after adding a real content edit plus CRLF to scripts/promote-insider-tag.mjs, npm run fix:crlf skipped it, exited 1, and preserved my FIDO_PRECIOUS_GUARD marker. No clobber.

Targeted tests also ran with the claimed collection counts: check-changeset-drift 8, promote-insider-tag 15, patch-esm-imports 6. I also ran the new repair suite: 13. Total targeted run: 42 passed. node scripts/check-shebang-eol.mjs still passes, so the refactor did not weaken the original index/blob gate.

The two deliberate non-actions hold. git add --renormalize . would attack the wrong side of this defect and cause unrelated line-ending churn; I measured 94 CRLF-storing .ts blobs in this worktree, so the documented 95 is stale by one but the argument is still correct. Not adding a CI gate is also correct: a fresh checkout makes the working-tree check permanently green, which is decoration rather than a gate.

Nits only: my local totals are 174 LF-pinned files / 42 .mjs files, not EECOM's 173 / 41. That appears explained by the added repair script and is not a blocker.