No .gitattributes, so a Windows or WSL clone gets CRLF and a byte-exact doc test blames the action catalogue

[vladimirrott]

Re-measured 2026-09-07 at adab560, and half of this issue is done. The
committed CRLF artifact was renormalised by #361 on 3 September, before you
were pointed here. Nothing tracked is CRLF or mixed today:

$ git ls-files --eol | grep -E '^i/(crlf|mixed)'; echo "grep rc=$?"
grep rc=1
$ grep -c $'\r' tests/evidence/workspace-tests.json
0

What is left is the prevention half, which nobody has touched: the missing
.gitattributes, the guard, and the CONTRIBUTING.md paragraph. The trap
named under "Tests first" has inverted. The guard now passes on its first
run, so a contributor who adds it and sees green has learned nothing about
whether it works. Prove it bites before you believe it.

Three line references below have moved and one figure is gone:

$ grep -n 'json.dumps' scripts/record_test_baseline.py
160:        json.dumps(doc, indent=2, sort_keys=True) + "\n", encoding="utf-8"
$ sed -n "154p;156p" crates/sysknife-daemon/tests/action_reference_doc.rs
    }
    let committed = std::fs::read_to_string(&path).unwrap_or_default();
$ wc -c tests/evidence/workspace-tests.json
193 tests/evidence/workspace-tests.json

So record_test_baseline.py:65 is now 159-160 (#393 moved it),
action_reference_doc.rs:154 is 162 (156 on 2026-09-07; #384 moved it again on 2026-09-09), and the "450 bytes of LF over 467 bytes
of CRLF" sentence describes a file that #393 replaced with a 193-byte schema.
The reasoning around each of them still holds; only the numbers moved.

The repository has no .gitattributes, and core.autocrlf is whatever the contributor's machine set. A Windows or WSL clone with autocrlf=true therefore gets CRLF in the working tree, and a commit back from that clone puts CRLF into the index. Nothing in the repo prevents either half, and nothing tells the contributor it happened.

Both halves have now happened. At 60af0ad:

$ git ls-files --eol | grep -E '^i/(crlf|mixed)'
i/crlf  w/crlf  attr/    tests/evidence/workspace-tests.json

That file arrived CRLF in 60af0ad, and it is LF in every earlier commit that touched it:

$ for c in 60af0ad 0640818 5867807 5a9450a; do
    echo "$c $(git show $c:tests/evidence/workspace-tests.json | grep -c $'\r')"
  done
60af0ad 17
0640818 0
5867807 0
5a9450a 0

scripts/record_test_baseline.py:65 writes the file with json.dumps(...) + "\n", so the generator never produces those bytes. They came from somebody's checkout.

Why it matters

It cost two contributors a day, in the same 24 hours.

crates/sysknife-daemon/tests/action_reference_doc.rs:154 compares the file on disk against a generated string byte for byte:

let committed = std::fs::read_to_string(&path).unwrap_or_default();
assert_eq!(committed, generated, "docs/action-reference.md is out of date ...");

The generator emits \n. A CRLF working tree fails on line endings alone, and the message blames the action catalogue. #341 reported it as a pre-existing failure on clean main, and it passes on Linux:

PASS [ 0.017s] sysknife-daemon::action_reference_doc action_reference_doc_is_current

The same PR carries three sed -i 's/\r$//' calls against files it copies out of the repo, which is the same symptom being worked around one file at a time.

Neither contributor did anything wrong. The repo let a mangled checkout look like a broken catalogue.

The committed artifact costs something separate, and quietly. scripts/check_evidence_claims.py still passes, because a carriage return is legal JSON whitespace:

$ python3 scripts/check_evidence_claims.py
Published figures match the evidence artifacts.

So no gate goes red. The next contributor who runs UPDATE_TEST_BASELINE=1 scripts/test_baseline.sh gets a whole-file diff instead of a one-line one, because the generator writes 450 bytes of LF over 467 bytes of CRLF.

Scope

• Renormalise tests/evidence/workspace-tests.json to LF. Done in fix(evidence): restore LF line endings in workspace-tests.json #361 on 3 September; there is nothing left to renormalise.
• Add .gitattributes with * text=auto eol=lf, plus -text for the binary paths already marked as such (icons, .ico, .png, cassette fixtures if any are binary).
• Mark the executable shell scripts explicitly, since a CRLF shebang line makes bash report bad interpreter: /usr/bin/env bash^M, which is the next thing this bites.
• Say in CONTRIBUTING.md what to run after cloning on Windows or WSL: git config core.autocrlf false, then git rm --cached -r . && git reset --hard to renormalise an already-mangled tree.

Tests first

git ls-files --eol is the assertion. A guard in tests/release/ that fails when any tracked file is i/crlf or i/mixed pins it, and it costs one git call:

git ls-files --eol | grep -E '^i/(crlf|mixed)' && exit 1

The trap in this issue has inverted since it was written. That grep matched tests/evidence/workspace-tests.json when this was filed; #361 renormalised the file, so the guard now goes green the moment you add it. A guard that has only ever been observed passing is the defect this tracker keeps meeting. Commit a CRLF file on a scratch branch, watch the guard go red, drop the branch, and say in the PR that you did.

Prove it bites by committing a CRLF file in a scratch branch, not by trusting the grep.

Difficulty

easy. The whole change is one new file, one docs paragraph and one guard.

Getting started

CONTRIBUTING.md has the build and test commands. No CLA and no copyright waiver. The project is MIT.

[vladimirrott]

@raul-cgk you starred this repo, so in case you are looking for somewhere to start: this one is small, self-contained, and needs no Linux host, no daemon and no LLM key.

There is no .gitattributes in the tree. A clone on Windows or WSL gets CRLF line endings, and action_reference_doc_is_current compares two generated documents byte for byte, so the first thing a Windows contributor sees is a failing test that blames the action catalogue rather than their checkout. The fix is a .gitattributes that pins the text files, plus something that keeps it honest.

The build and test commands are in CONTRIBUTING.md, and docs/developer-guide.md was rewritten today with the setup steps and how to run each gate locally. No CLA, MIT.

Entirely optional, and no hard feelings if you would rather not. Say the word and I will label it claimed.

[vladimirrott]

@iamjaeholee this one is yours if you want it, and it is the same shape as the #349 you landed this morning.

#349 made five hygiene guards print their diagnostic instead of dying at a grep and saying nothing, so the contributor sees the real cause. #342 is that defect with the blame misdirected rather than missing. A CRLF working tree fails action_reference_doc_is_current on line endings alone, and the message it prints says the action catalogue is out of date. Two contributors lost time to that in the same 24 hours, and neither of them had done anything wrong.

I have just rewritten the body, because it had gone stale in the way that costs you an evening. It claimed every tracked text file was LF in the index. That stopped being true this afternoon:

$ git ls-files --eol | grep -E '^i/(crlf|mixed)'
i/crlf  w/crlf  attr/    tests/evidence/workspace-tests.json

60af0ad committed that file with 17 CRLF endings. Every earlier commit touching it has zero, and scripts/record_test_baseline.py:65 writes the file with json.dumps(...) + "\n", so the generator did not produce those bytes. A contributor's checkout did, on a repo whose own issue tracker predicts exactly that.

Nothing goes red over it. check_evidence_claims.py passes, since a carriage return is legal JSON whitespace, and cargo nextest run --workspace --locked is green at 1837. The cost falls on the next person to run UPDATE_TEST_BASELINE=1 scripts/test_baseline.sh, who gets a 17-line diff where one line changed.

The trap, which is why I am saying it here rather than letting you find it. The guard the issue proposes:

git ls-files --eol | grep -E '^i/(crlf|mixed)' && exit 1

matches that file on main right now. Add the guard first and it goes red on its first run against a clean tree. Renormalise the file, then add the guard.

Difficulty is honest at easy: one new .gitattributes, one file renormalised, one guard, one paragraph in CONTRIBUTING.md. The interesting half is proving the guard bites, and you have already done that once this week.

No rush and no obligation. Say the word and I will label it claimed.

Separately, with nothing attached: you clearly run Linux, or #349 would have been a harder patch to write than it was. If you ever want to point sysknife doctor at a machine you actually care about, I would rather have one report from a real host than another green CI run. That surface is read-only and leaves the system alone.

[vladimirrott]

@LunaMeerkats reserved for you as a follow-up to your recent work; the why is on your PR thread. No pressure and no deadline. Reply here and it is formally yours.

[vladimirrott]

Three of you were pointed at this one issue by me, on three separate days, and none of you were told about the other two. That is entirely my error. offers reported how many issues were free to offer and never which ones, so every round picked by hand and collided; it names them now, and this thread is one of seven it turned up.

@LunaMeerkats you have the wizard half of #337 assigned and in progress, so I am releasing this rather than leaving you holding two.

@iamjaeholee this is the one I regret. You landed #349 and I offered you this because it was the same shape. It carries good first issue and easy, though, and the third person I offered it to has no merged PR here yet and was invited to this repository through it. Handing a starter issue to somebody past their start, over somebody at theirs, is the wrong way round. So I have put #367 aside for you instead, which is closer to #349 than this is and worth more of your time. Details on that thread.

Neither of you is losing anything you had started, as far as I can see. If either of you has a branch going, say so here and this is yours instead: work already done beats my tidying.

[vladimirrott]

@raul-cgk checking in, with nothing attached to it. I pointed you at this on 3 September and have not seen a branch, which is fine; the issue is not going anywhere.

Two things in case either is what stalled it.

Half the premise was already done when you read it. #361 renormalised the committed CRLF file on 3 September, so nothing tracked is CRLF today and the guard this issue asks for goes green on its first run. That inverts the warning under "Tests first": break something on purpose and watch the guard fail before you believe it. What remains is prevention, which nobody has touched: the missing .gitattributes, the guard, and the CONTRIBUTING.md paragraph.

Three line numbers moved, twice, the last of them today. action_reference_doc.rs is at 162 rather than 154, and record_test_baseline.py at 159-160. The body now carries the current figures with the commands that produced them, so you are not chasing my stale numbers.

It stays yours. I have dropped the claimed label, since you never claimed it and the label said otherwise to everybody reading the tracker. That takes nothing away from you. If you would rather hand it back, say so and it costs you nothing.

[vladimirrott]

@raul-cgk freeing this one, with nothing owed.

I pointed you at it on 3 September and have not heard back, which is completely fine and needs no explanation. Seven days is the point where I stop holding an issue quietly, because a reservation nobody can see is worse for the next person than an open issue.

It is yours again the moment you say so, and the offer does not expire in any way that matters. I re-checked the finding today at f5dffd8 and it still stands: there is no .gitattributes in the tree, so a Windows or WSL clone still gets CRLF and the byte-exact doc test still blames the action catalogue for it.

[vladimirrott]

@ITSMERNB holding this for you, offered as part of a batch on #408.

Released from @raul-cgk this morning with nothing owed, and I re-checked today at f5dffd8: still no .gitattributes in the tree.

The failure mode is the part that fits you. A Windows or WSL clone gets CRLF, the byte-exact doc test fails, and it blames the action catalogue: a confident wrong answer pointed at the wrong file, which is what you fixed the reverse of in #410 when an unreadable staged blob stopped being reported as a credential finding.

Take it or leave it, and no is a complete answer.

[ITSMERNB]

I will take this one. Windows is a good fit for me to prove the failure mode directly rather than only adding the guard. I will first make the guard fail against a deliberately CRLF-tracked scratch file, then restore the tree and keep the production change scoped to .gitattributes, the release guard, and the contributor guidance. Thanks for re-checking it before offering it.