[HugoXK]

Fixes #1973

Owner: Dev-2
Reviewer: Birfy
Written-by: Dev-2
Claim-Id: 29bd7aaba56f45cba058dd4fca5b7833
Branch: dev/2-arch-docs-win-guard
Base: 2dfc1c3
Tip SHA: 307a3b1
Tree: b751a4df993590b50118e8a9f385a281f6eb3e18

Verified commit a9aa56d4c2f6340265d0e9d7690cb6ee1742819a (tree b751a4df…); the pushed head 307a3b1a… was rebuilt from that same tree by the fork push, so the checks describe that tree, not that commit sha.

Docs-not-needed: test-only platform guard; install.md's "Tests for the gate" row still describes core/test/check-arch-docs.test.js and the gate's own behaviour is unchanged (#1973).

What changes

One line of the case, and its mirror: core/test/check-arch-docs.test.js:68 (base 2dfc1c3a; :73 in this tree, after the four comment lines added here) becomes

test('the gate never runs git through a shell', { skip: process.platform === 'win32' }, async () => {

No other assertion, fixture, shell script, product file or patch source changes. patches/ds-bot/files/test/check-arch-docs.test.js is the mirror generate writes from that file, and changelog.d/1973-arch-docs-win-guard.fixed.md is the entry.

1. Why skip, and not a fake git that works on both platforms

The case asserts that the gate never hands git's argv to a shell, and that property is only observable by running the gate with a fake git that records its parent process. The fake has to be an executable script with an interpreter line (:82 writes #!/bin/sh, :98 sets mode: 0o755, :106 reads the marker it wrote). Windows cannot launch a #! script through CreateProcess, and a file named plain git with no .cmd/.exe is not what PATH lookup resolves, so on Windows the fake never runs, the marker never appears, and :106 throws. There is no cross-platform form of this fixture that still observes the same property; asserting it from the source instead would no longer be this test. A platform guard on this one case is therefore honest, not a bypass.

2. What still covers Windows

The guard silences one local unit case; it does not silence the platform. nightly.yml's weekly job runs on windows-latest (:140), and its Lint step (:162) runs the real core/scripts/check-arch-docs.mjs there — that is exactly the step #1954/#1969 existed for, where a ^ eaten by cmd.exe made every scheduled row report cannot diff against origin/main. Windows behaviour of the gate stays observed by that step.

3. What the guard costs elsewhere

Nothing new is introduced: process.platform === 'win32' is already how this repository handles a POSIX-only assertion (core/test/state-journal.test.js:13, const posix = process.platform !== 'win32'). The option is node:test's own second argument, so the case reports as skipped in the Tests step rather than as passed — the log still shows the capability is not exercised on Windows, and the Lint step above is where it is. A probe confirms that shape: a case with { skip: true } prints ok 1 - … # SKIP and the summary counts # pass 0 / # skipped 1.

4. Evidence this is a real red today

Reproduced on this tree by dropping only the exec bit ({ mode: 0o644 }), which is all Windows changes for this fixture:

not ok 1 - PROBE gate never runs git through a shell
  error: "ENOENT: no such file or directory, open '/tmp/arch-shell-sxf06z/parent.txt'"
  code: 'ENOENT'

On the real job it has not been seen yet, because it could not be reached: the last nightly run 41238672148 (job 124647780373, 2026-10-31T20:23:36Z) stopped at Lint and never ran Build/Tests. #1969 fixed that Lint failure, so the next weekly run (2026-11-07 17:00Z) is the first that would reach Tests — which is what this PR prevents from failing.

5. Red first is not available in the usual shape

The case is already green on Linux, so this change has no failing-test-first step to show: the fix is a platform guard, and the red it prevents is only reachable on Windows. The Linux run below exercises the case unchanged (it still runs there, 7 tests, 7 pass).

Ran

On the committed tree with a clean git status, once: TZ=UTC ARCH_DOCS_BASE=2dfc1c3a90f25de8b58a6f8e968aacded101a782 npm run verify — exit 0.

• core 2371 pass / 0 fail — the same count as base 2dfc1c3a, as expected: no case is added and the guard changes nothing on Linux
• social 541 (540 pass, 1 skip) · tree 127 (126, 1) · timeline 135 (134, 1) · workflow 336 · .github/scripts 563 · interop 37 · live-e2e 24, all 0 fail
• arch-docs OK (3 changed file(s)); lint 73 core + 36 social + 9 timeline + 2 tree + 16 workflow warnings, 0 errors; interop lint 1 warning (dev/interop/isolation/probe.mjs:130), live-e2e lint 0 warnings, 0 errors
• node scripts/ds-bot-patches.mjs generate → no diff; check → ds-bot/ = Fei2411/DeepSeek-Bot@2b10c70, 10 patches apply cleanly in order, core/ equals ds-bot/ + patches/ds-bot/; canonical → generate is a no-op
• node .github/scripts/changelog.mjs check → 9 fragment(s) in changelog.d/ are well formed
• cmp core/test/check-arch-docs.test.js patches/ds-bot/files/test/check-arch-docs.test.js → byte-identical

Not run: the Windows job itself (it cannot be dispatched from here), the CI package job, typecheck and actionlint. No manual browser check was needed — this change touches no runtime code.

Checkpoint

{
"pr": 1974,
"claim": "Dev-2",
"issue": 1973,
"summary": "The arch-docs shell-guard case added in #1969 can only observe its property by running a fake git that must be an executable script with an interpreter line, which Windows cannot launch and whose bare name PATH does not resolve, so the weekly Compatibility job would fail it with ENOENT. It now carries node:test's { skip: process.platform === 'win32' }, so the Tests step reports it as skipped rather than passed, while the same job's Lint step still runs the real gate on windows-latest. No product code changes; the patches mirror and a changelog fragment go with it.",
"files": [
"core/test/check-arch-docs.test.js",
"patches/ds-bot/files/test/check-arch-docs.test.js",
"changelog.d/1973-arch-docs-win-guard.fixed.md"
],
"checks": {
"ran": "TZ=UTC ARCH_DOCS_BASE=2dfc1c3a90f25de8b58a6f8e968aacded101a782 npm run verify; node scripts/ds-bot-patches.mjs check; node .github/scripts/changelog.mjs check",
"result": "green",
"at": "307a3b1ad7b1a8e6949022b6c20610ba5c67f69d"
},
"next": "none — ready for review"
}

[HugoXK]

@Birfy review request — PR #1974 at 307a3b1ad7b1a8e6949022b6c20610ba5c67f69d (base 2dfc1c3a90f25de8b58a6f8e968aacded101a782).

Test-only, 3 files: one case in core/test/check-arch-docs.test.js, its patches/ds-bot/files/ mirror, one changelog fragment. No product code, no .github/, no 000N-*.patch.

What it does: the shell-guard case #1969 added (:68 on base) can only observe its property by running a fake git that has to be an executable script with an interpreter line (#!/bin/sh + mode: 0o755), which Windows cannot launch through CreateProcess, so the weekly Compatibility row would fail it with ENOENT at :106. The case now carries node:test's { skip: process.platform === 'win32' }.

The body argues, in this order: 1) why a platform guard is honest here rather than a bypass; 2) that Windows behaviour is still exercised by nightly.yml:162's Lint step running the real gate on windows-latest; 3) that process.platform === 'win32' is already the repository's convention (core/test/state-journal.test.js:13); 4) the real red evidence (dropping only the exec bit reproduces ENOENT … parent.txt, and the last nightly 41238672148 never reached Tests because Lint failed first). It also states that the case reports as skipped, not passed, and that red-first is not available in its usual shape.

Ran: TZ=UTC ARCH_DOCS_BASE=2dfc1c3a… npm run verify once on a clean tree — exit 0 (core 2371 = base, social 541, tree 127, timeline 135, workflow 336, .github/scripts 563, interop 37, live-e2e 24; arch-docs OK (3 changed file(s)); generate no-op, check 10 patches clean, canonical no-op; changelog 9 fragments well formed; mirror cmp byte-identical).

Requested: the formal Verdict: at this tip. Owner: Dev-2 · Reported by: FlyBot Lead.