From 6a4a8cd4c6e92ca0f4cc29032d1296cf41862ab2 Mon Sep 17 00:00:00 2001
From: Baptiste LAFOURCADE <baptiste.lafourcade@gmail.com>
Date: Sun, 11 Oct 2026 22:08:29 +0200
Subject: [PATCH 1/4] test(lefthook): reproduce the Windows pre-commit failure
 in CI

Lefthook on Windows runs each job through a command line it builds by hand,
`"sh" -c "<script>"`, with nothing escaped (internal/run/controller/exec/
exec_windows.go in 2.1.14). Every job that fails in #948 holds both a line
break and a double quote, so the report cannot tell which one breaks it.

The Windows job now probes the three shapes on their own, a multiline run with
no quote, a one-line run with a double quote and one with a single quote, and
reports each exit code without failing. It then runs this repository's own
pre-commit over every file, leaving out the three jobs that need cli/'s
dependencies, and fails only on a shell syntax error, so a Windows bug in a
check itself (#881) stays that check's.

Refs #948

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VE16AxC1V9wAMGmGgefe4z
---
 .github/workflows/cli-ci.yml | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/.github/workflows/cli-ci.yml b/.github/workflows/cli-ci.yml
index 072eb4439..5cc0924f8 100644
--- a/.github/workflows/cli-ci.yml
+++ b/.github/workflows/cli-ci.yml
@@ -520,6 +520,42 @@ jobs:
       - name: Plugin suite
         run: node scripts/check-tests-leave-git-alone.js -- node --test 'scripts/__tests__/**/*.test.js'
 
+      # Lefthook on Windows hands each job to `sh -c` through a command line it builds by hand,
+      # with nothing escaped (#948). Three probes isolate what breaks that: a line break, a
+      # double quote, a single quote. They report, they never fail the job.
+      - name: Hooks - probe what lefthook's sh -c survives on Windows
+        run: |
+          cat > "$RUNNER_TEMP/probe.yml" <<'YML'
+          probe:
+            commands:
+              multiline-no-quotes:
+                run: |
+                  if true; then
+                    echo multiline-ok
+                  fi
+              oneline-double-quote:
+                run: echo "double-quote-ok"
+              oneline-single-quote:
+                run: echo 'single-quote-ok'
+          YML
+          for c in multiline-no-quotes oneline-double-quote oneline-single-quote; do
+            out=$(LEFTHOOK_CONFIG="$RUNNER_TEMP/probe.yml" LEFTHOOK_VERBOSE=1 pnpm exec lefthook run probe --command "$c" --no-auto-install --no-tty 2>&1) && code=0 || code=$?
+            echo "::group::$c exit $code"; echo "$out"; echo "::endgroup::"
+            echo "probe $c: exit $code"
+          done
+      # The repository's own pre-commit, every job but the three that need cli/'s dependencies.
+      # Only lefthook's own breakage fails this step: a check that runs and finds a problem
+      # on Windows is that check's bug, not this one's.
+      - name: Hooks - the pre-commit runs on Windows without a shell syntax error
+        run: |
+          LEFTHOOK_EXCLUDE=cli-biome,cli-architecture,cli-typecheck \
+            pnpm exec lefthook run pre-commit --all-files --no-auto-install --no-tty > "$RUNNER_TEMP/pre-commit.log" 2>&1 || true
+          cat "$RUNNER_TEMP/pre-commit.log"
+          if grep -n "syntax error" "$RUNNER_TEMP/pre-commit.log"; then
+            echo "::error::lefthook handed sh a broken command line (#948)"
+            exit 1
+          fi
+
       - run: cd cli && pnpm install --frozen-lockfile
       # A real global install, not `node dist/cli.js` by path: nothing else proves `aidd`
       # resolves on this platform's PATH. Built here, ahead of the suites below, so this is

From 293be4cc8daa65ffaf858940ba5e1a4296d8ebaa Mon Sep 17 00:00:00 2001
From: Baptiste LAFOURCADE <baptiste.lafourcade@gmail.com>
Date: Mon, 12 Oct 2026 04:41:44 +0200
Subject: [PATCH 2/4] fix(lefthook): keep double quotes out of every hook run
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Windows CI job reproduced #948: 17 pre-commit jobs failed with
`node: -c: line 3: syntax error: unexpected end of file`. Lefthook 2.1.14 on
Windows builds `"sh.exe" -c "<script>"` and escapes nothing, so a double quote
in a run closes the argument, and a space after it cuts the script in two: the
`node` in that error is the word after `echo "❌`. The probes ruled out line
breaks, since a multiline run with no quote passed, as did a single quote.

No run in lefthook.yml holds a double quote any more. Messages use single
quotes, variables that never hold a space lose theirs, and the two jobs that
need nested quotes moved into scripts the run line only names:
`scripts/summarize-plugin-catalogs.sh`, verbatim, and
`scripts/session-trailer-delegate.sh`. The trailer's run line still names
`aidd-session-trailer.sh`, which is how `aidd telemetry` finds the job.

A guard fails on any double quote in a run, red on 16 jobs before this change.
The Windows job keeps its pre-commit step, drops the probes, and also runs
prepare-commit-msg.

Refs #948

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VE16AxC1V9wAMGmGgefe4z
---
 .github/workflows/cli-ci.yml                  | 32 +++-------
 lefthook.yml                                  | 61 +++++++------------
 ...lefthook-runs-hold-no-double-quote.test.js | 23 +++++++
 scripts/session-trailer-delegate.sh           |  5 ++
 scripts/summarize-plugin-catalogs.sh          | 17 ++++++
 5 files changed, 74 insertions(+), 64 deletions(-)
 create mode 100644 scripts/__tests__/lefthook-runs-hold-no-double-quote.test.js
 create mode 100755 scripts/session-trailer-delegate.sh
 create mode 100755 scripts/summarize-plugin-catalogs.sh

diff --git a/.github/workflows/cli-ci.yml b/.github/workflows/cli-ci.yml
index 5cc0924f8..9daea7245 100644
--- a/.github/workflows/cli-ci.yml
+++ b/.github/workflows/cli-ci.yml
@@ -521,35 +521,17 @@ jobs:
         run: node scripts/check-tests-leave-git-alone.js -- node --test 'scripts/__tests__/**/*.test.js'
 
       # Lefthook on Windows hands each job to `sh -c` through a command line it builds by hand,
-      # with nothing escaped (#948). Three probes isolate what breaks that: a line break, a
-      # double quote, a single quote. They report, they never fail the job.
-      - name: Hooks - probe what lefthook's sh -c survives on Windows
-        run: |
-          cat > "$RUNNER_TEMP/probe.yml" <<'YML'
-          probe:
-            commands:
-              multiline-no-quotes:
-                run: |
-                  if true; then
-                    echo multiline-ok
-                  fi
-              oneline-double-quote:
-                run: echo "double-quote-ok"
-              oneline-single-quote:
-                run: echo 'single-quote-ok'
-          YML
-          for c in multiline-no-quotes oneline-double-quote oneline-single-quote; do
-            out=$(LEFTHOOK_CONFIG="$RUNNER_TEMP/probe.yml" LEFTHOOK_VERBOSE=1 pnpm exec lefthook run probe --command "$c" --no-auto-install --no-tty 2>&1) && code=0 || code=$?
-            echo "::group::$c exit $code"; echo "$out"; echo "::endgroup::"
-            echo "probe $c: exit $code"
-          done
-      # The repository's own pre-commit, every job but the three that need cli/'s dependencies.
-      # Only lefthook's own breakage fails this step: a check that runs and finds a problem
-      # on Windows is that check's bug, not this one's.
+      # with nothing escaped (#948): a double quote in a `run` truncates the script.
+      # The repository's own pre-commit, every job but the three that need cli/'s dependencies,
+      # then the prepare-commit-msg trailer job. Only lefthook's own breakage
+      # fails this step: a check that runs and finds a problem on Windows is that check's bug,
+      # not this one's.
       - name: Hooks - the pre-commit runs on Windows without a shell syntax error
         run: |
           LEFTHOOK_EXCLUDE=cli-biome,cli-architecture,cli-typecheck \
             pnpm exec lefthook run pre-commit --all-files --no-auto-install --no-tty > "$RUNNER_TEMP/pre-commit.log" 2>&1 || true
+          echo "# lefthook subject" > "$RUNNER_TEMP/msg"
+          pnpm exec lefthook run prepare-commit-msg "$RUNNER_TEMP/msg" message --no-auto-install --no-tty >> "$RUNNER_TEMP/pre-commit.log" 2>&1 || true
           cat "$RUNNER_TEMP/pre-commit.log"
           if grep -n "syntax error" "$RUNNER_TEMP/pre-commit.log"; then
             echo "::error::lefthook handed sh a broken command line (#948)"
diff --git a/lefthook.yml b/lefthook.yml
index 00d136edb..155bcf943 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -7,7 +7,7 @@ pre-commit:
         - "cli/tests/fixtures/**"
       run: |
         if ! command -v node >/dev/null 2>&1; then
-          echo "❌ node not available; cannot validate JSON"
+          echo '❌ node not available; cannot validate JSON'
           exit 1
         fi
         node scripts/validate-json.mjs {files}
@@ -17,7 +17,7 @@ pre-commit:
         - "plugins/*/skills/*/assets/**"
       run: |
         if ! command -v node >/dev/null 2>&1; then
-          echo "❌ node not available; cannot validate YAML"
+          echo '❌ node not available; cannot validate YAML'
           exit 1
         fi
         node scripts/validate-yaml.mjs {files}
@@ -25,14 +25,14 @@ pre-commit:
       glob: "{scripts,plugins,cli/src}/**"
       run: |
         if ! command -v node >/dev/null 2>&1; then
-          echo "ℹ️  node not available; skipping scripts-tests"
+          echo 'ℹ️  node not available; skipping scripts-tests'
           exit 0
         fi
         # `node --test <dir>` fails on a directory, so a glob is required — and a glob
         # matching nothing exits 0 in silence, so a renamed folder must be caught by a count.
         found=$(ls scripts/__tests__/*.test.js 2>/dev/null | wc -l | tr -d ' ')
-        if [ "$found" -eq 0 ]; then
-          echo "❌ no test files under scripts/__tests__/; the runner is not wired"
+        if [ $found -eq 0 ]; then
+          echo '❌ no test files under scripts/__tests__/; the runner is not wired'
           exit 1
         fi
         # Wrapped: a suite writing into this repository's own .git/hooks passes every
@@ -43,13 +43,13 @@ pre-commit:
       glob: "plugins/*/skills/*/SKILL.md"
       run: |
         for f in {files}; do
-          [ -f "$f" ] || continue
-          if ! head -10 "$f" | grep -q "^name:"; then
-            echo "❌ missing 'name:' frontmatter: $f"
+          [ -f $f ] || continue
+          if ! head -10 $f | grep -q '^name:'; then
+            echo '❌ missing name: frontmatter:' $f
             exit 1
           fi
-          if ! head -10 "$f" | grep -q "^description:"; then
-            echo "❌ missing 'description:' frontmatter: $f"
+          if ! head -10 $f | grep -q '^description:'; then
+            echo '❌ missing description: frontmatter:' $f
             exit 1
           fi
         done
@@ -57,7 +57,7 @@ pre-commit:
       glob: "plugins/*/skills/**"
       run: |
         if ! command -v node >/dev/null 2>&1; then
-          echo "ℹ️  node not available; skipping check-skill-argument-hints"
+          echo 'ℹ️  node not available; skipping check-skill-argument-hints'
           exit 0
         fi
         node scripts/check-skill-argument-hints.mjs
@@ -65,7 +65,7 @@ pre-commit:
       glob: "plugins/*/{skills,agents}/**/*.md"
       run: |
         if ! command -v node >/dev/null 2>&1; then
-          echo "ℹ️  node not available; skipping architecture-rules"
+          echo 'ℹ️  node not available; skipping architecture-rules'
           exit 0
         fi
         node scripts/check-architecture-rules.js {files}
@@ -76,7 +76,7 @@ pre-commit:
         - "**/{CLAUDE,AGENTS,copilot-instructions}.md"
       run: |
         if ! command -v node >/dev/null 2>&1; then
-          echo "ℹ️  node not available; skipping context-imports"
+          echo 'ℹ️  node not available; skipping context-imports'
           exit 0
         fi
         node scripts/check-context-imports.js
@@ -89,7 +89,7 @@ pre-commit:
         - "plugins/aidd-context/hooks/update_memory.js"
       run: |
         if ! command -v node >/dev/null 2>&1; then
-          echo "ℹ️  node not available; skipping context-reference-form"
+          echo 'ℹ️  node not available; skipping context-reference-form'
           exit 0
         fi
         node scripts/check-context-reference-form.js
@@ -97,7 +97,7 @@ pre-commit:
       glob: "{*.md,docs/**,aidd_docs/memory/**}"
       run: |
         if ! command -v node >/dev/null 2>&1; then
-          echo "ℹ️  node not available; skipping referenced-paths"
+          echo 'ℹ️  node not available; skipping referenced-paths'
           exit 0
         fi
         node scripts/check-referenced-paths.js
@@ -106,7 +106,7 @@ pre-commit:
       glob: "**/*.md"
       run: |
         if ! command -v node >/dev/null 2>&1; then
-          echo "ℹ️  node not available; skipping doc-duplication"
+          echo 'ℹ️  node not available; skipping doc-duplication'
           exit 0
         fi
         node scripts/check-doc-duplication.js
@@ -115,33 +115,18 @@ pre-commit:
       glob: "**/*.md"
       run: |
         if ! command -v node >/dev/null 2>&1; then
-          echo "ℹ️  node not available; skipping markdown-links"
+          echo 'ℹ️  node not available; skipping markdown-links'
           exit 0
         fi
         # Both ignored trees hold deliberately unresolvable targets — fixture paths and
         # `@src/foo.ts` agent mentions — not links a reader is meant to follow.
         node scripts/check-markdown-links.js --ignore cli/tests/fixtures --ignore cli/aidd_docs/tasks
     summarize-plugin-catalogs:
-      run: |
-        [ -d plugins ] || exit 0
-        if ! command -v node >/dev/null 2>&1; then
-          echo "ℹ️  node not available; skipping summarize-plugin-catalogs"
-          exit 0
-        fi
-        for plugin in plugins/*/; do
-          name=$(basename "$plugin")
-          node scripts/summarize-markdown.js "$plugin" "${plugin}CATALOG.md" \
-            --depth=4 \
-            --fields=description \
-            --title="$name catalog" \
-            --tagline="Auto-generated index of skills, agents, references and assets shipped by the \`$name\` plugin." \
-            >/dev/null
-          git add "${plugin}CATALOG.md" 2>/dev/null || true
-        done
+      run: sh scripts/summarize-plugin-catalogs.sh
     summarize-telemetry-prompts-doc:
       run: |
         if ! command -v node >/dev/null 2>&1; then
-          echo "ℹ️  node not available; skipping summarize-telemetry-prompts-doc"
+          echo 'ℹ️  node not available; skipping summarize-telemetry-prompts-doc'
           exit 0
         fi
         node scripts/summarize-markdown.js plugins/aidd-telemetry docs/prompts-documentation.md \
@@ -152,7 +137,7 @@ pre-commit:
     sync-readme-counts:
       run: |
         if ! command -v node >/dev/null 2>&1; then
-          echo "ℹ️  node not available; skipping sync-readme-counts"
+          echo 'ℹ️  node not available; skipping sync-readme-counts'
           exit 0
         fi
         node scripts/sync-readme-counts.mjs >/dev/null
@@ -174,7 +159,7 @@ pre-commit:
       glob: "{cli/src/**,cli/tests/**}"
       run: |
         if ! command -v node >/dev/null 2>&1; then
-          echo "ℹ️  node not available; skipping cli-type-honesty"
+          echo 'ℹ️  node not available; skipping cli-type-honesty'
           exit 0
         fi
         node scripts/check-cli-type-honesty.mjs
@@ -198,6 +183,4 @@ commit-msg:
 prepare-commit-msg:
   commands:
     aidd-session-trailer:
-      run: |
-        delegate="$(git rev-parse --git-common-dir)/hooks/aidd-session-trailer.sh"
-        if [ -f "$delegate" ]; then sh "$delegate" {1} {2}; fi
+      run: sh scripts/session-trailer-delegate.sh aidd-session-trailer.sh {1} {2}
diff --git a/scripts/__tests__/lefthook-runs-hold-no-double-quote.test.js b/scripts/__tests__/lefthook-runs-hold-no-double-quote.test.js
new file mode 100644
index 000000000..2261905da
--- /dev/null
+++ b/scripts/__tests__/lefthook-runs-hold-no-double-quote.test.js
@@ -0,0 +1,23 @@
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const path = require("node:path");
+const test = require("node:test");
+const yaml = require("js-yaml");
+
+const root = path.resolve(__dirname, "../..");
+
+// Lefthook on Windows hands each job to `sh -c` through a command line it builds by hand,
+// escaping nothing (#948): a `"` in a `run` closes the argument, and sh gets a truncated
+// script. A `'` is safe, and so is a script file the run line only names.
+test("no run in lefthook.yml holds a double quote", () => {
+  const config = yaml.load(fs.readFileSync(path.join(root, "lefthook.yml"), "utf8"));
+  const offenders = [];
+
+  for (const [hook, def] of Object.entries(config)) {
+    for (const [name, command] of Object.entries(def?.commands ?? {})) {
+      if (String(command.run ?? "").includes('"')) offenders.push(`${hook}/${name}`);
+    }
+  }
+
+  assert.deepEqual(offenders, []);
+});
diff --git a/scripts/session-trailer-delegate.sh b/scripts/session-trailer-delegate.sh
new file mode 100755
index 000000000..47629f414
--- /dev/null
+++ b/scripts/session-trailer-delegate.sh
@@ -0,0 +1,5 @@
+#!/bin/sh
+# A file, not a lefthook run: its quotes would break Windows' hand-built sh -c line (#948).
+delegate="$(git rev-parse --git-common-dir)/hooks/$1"
+shift
+if [ -f "$delegate" ]; then sh "$delegate" "$@"; fi
diff --git a/scripts/summarize-plugin-catalogs.sh b/scripts/summarize-plugin-catalogs.sh
new file mode 100755
index 000000000..4a7561e9b
--- /dev/null
+++ b/scripts/summarize-plugin-catalogs.sh
@@ -0,0 +1,17 @@
+#!/bin/sh
+# A file, not a lefthook run: its quotes would break Windows' hand-built sh -c line (#948).
+[ -d plugins ] || exit 0
+if ! command -v node >/dev/null 2>&1; then
+  echo "ℹ️  node not available; skipping summarize-plugin-catalogs"
+  exit 0
+fi
+for plugin in plugins/*/; do
+  name=$(basename "$plugin")
+  node scripts/summarize-markdown.js "$plugin" "${plugin}CATALOG.md" \
+    --depth=4 \
+    --fields=description \
+    --title="$name catalog" \
+    --tagline="Auto-generated index of skills, agents, references and assets shipped by the \`$name\` plugin." \
+    >/dev/null
+  git add "${plugin}CATALOG.md" 2>/dev/null || true
+done

From 7c89122b25f7f209bc559a08e6eaee9946522abe Mon Sep 17 00:00:00 2001
From: Baptiste LAFOURCADE <baptiste.lafourcade@gmail.com>
Date: Mon, 12 Oct 2026 05:08:36 +0200
Subject: [PATCH 3/4] fix(lefthook): make the two checks that fail on Windows
 pass there

With the shell fixed, the Windows CI log showed two checks of their own failing
on every commit, hidden by a step that only looked for a syntax error.
`check-skill-argument-hints` reported 58 skills without an argument-hint: the
Windows checkout ends lines with CRLF, so no frontmatter starts with `---\n`.
`sync-readme-counts` read `D:\D:\a\...\README.md`, a root taken from a URL's
pathname, and the hook dropped its exit code.

The hint check normalises CRLF before parsing, and the counts script resolves
its root with `fileURLToPath`. A CRLF skill test was red before the change; the
counts test runs the script where the suite runs, Windows CI included.

The Windows step is now strict, failing on any hook that fails as well as on a
syntax error. The no-double-quote guard also fails when it scans no run, and
lefthook.yml says why the trailer's run line names its delegate.

Refs #948

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VE16AxC1V9wAMGmGgefe4z
---
 .github/workflows/cli-ci.yml                  | 25 ++++++++++---------
 lefthook.yml                                  |  1 +
 ...lefthook-runs-hold-no-double-quote.test.js |  4 +++
 .../__tests__/skill-argument-hints.test.js    | 10 ++++++++
 scripts/__tests__/sync-readme-counts.test.js  | 14 +++++++++++
 scripts/check-skill-argument-hints.mjs        |  7 +++---
 scripts/sync-readme-counts.mjs                |  4 ++-
 7 files changed, 49 insertions(+), 16 deletions(-)
 create mode 100644 scripts/__tests__/sync-readme-counts.test.js

diff --git a/.github/workflows/cli-ci.yml b/.github/workflows/cli-ci.yml
index 9daea7245..daabb3ee2 100644
--- a/.github/workflows/cli-ci.yml
+++ b/.github/workflows/cli-ci.yml
@@ -520,23 +520,24 @@ jobs:
       - name: Plugin suite
         run: node scripts/check-tests-leave-git-alone.js -- node --test 'scripts/__tests__/**/*.test.js'
 
-      # Lefthook on Windows hands each job to `sh -c` through a command line it builds by hand,
-      # with nothing escaped (#948): a double quote in a `run` truncates the script.
-      # The repository's own pre-commit, every job but the three that need cli/'s dependencies,
-      # then the prepare-commit-msg trailer job. Only lefthook's own breakage
-      # fails this step: a check that runs and finds a problem on Windows is that check's bug,
-      # not this one's.
-      - name: Hooks - the pre-commit runs on Windows without a shell syntax error
+      # What a Windows contributor's commit runs: the pre-commit, every job but the three that
+      # need cli/'s dependencies (Biome there is #881), then the trailer job. Lefthook hands
+      # each job to `sh -c` through a command line it builds by hand, with nothing escaped, so
+      # a double quote in a `run` truncates the script (#948); a check that only fails here is
+      # a Windows bug of its own, and both fail the step.
+      - name: Hooks - a commit's hooks pass on Windows
         run: |
-          LEFTHOOK_EXCLUDE=cli-biome,cli-architecture,cli-typecheck \
-            pnpm exec lefthook run pre-commit --all-files --no-auto-install --no-tty > "$RUNNER_TEMP/pre-commit.log" 2>&1 || true
           echo "# lefthook subject" > "$RUNNER_TEMP/msg"
-          pnpm exec lefthook run prepare-commit-msg "$RUNNER_TEMP/msg" message --no-auto-install --no-tty >> "$RUNNER_TEMP/pre-commit.log" 2>&1 || true
-          cat "$RUNNER_TEMP/pre-commit.log"
-          if grep -n "syntax error" "$RUNNER_TEMP/pre-commit.log"; then
+          status=0
+          LEFTHOOK_EXCLUDE=cli-biome,cli-architecture,cli-typecheck \
+            pnpm exec lefthook run pre-commit --all-files --no-auto-install --no-tty > "$RUNNER_TEMP/hooks.log" 2>&1 || status=1
+          pnpm exec lefthook run prepare-commit-msg "$RUNNER_TEMP/msg" message --no-auto-install --no-tty >> "$RUNNER_TEMP/hooks.log" 2>&1 || status=1
+          cat "$RUNNER_TEMP/hooks.log"
+          if grep -n "syntax error" "$RUNNER_TEMP/hooks.log"; then
             echo "::error::lefthook handed sh a broken command line (#948)"
             exit 1
           fi
+          exit $status
 
       - run: cd cli && pnpm install --frozen-lockfile
       # A real global install, not `node dist/cli.js` by path: nothing else proves `aidd`
diff --git a/lefthook.yml b/lefthook.yml
index 155bcf943..9feae1aa7 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -180,6 +180,7 @@ commit-msg:
 
 # lefthook owns prepare-commit-msg here and regenerates it on install, so `aidd telemetry on`'s
 # delegate is called from a job instead. Absent delegate, nothing runs — opt-in per machine.
+# The run line names `aidd-session-trailer.sh` itself: that name is how `aidd telemetry` finds this job.
 prepare-commit-msg:
   commands:
     aidd-session-trailer:
diff --git a/scripts/__tests__/lefthook-runs-hold-no-double-quote.test.js b/scripts/__tests__/lefthook-runs-hold-no-double-quote.test.js
index 2261905da..ab1066fe2 100644
--- a/scripts/__tests__/lefthook-runs-hold-no-double-quote.test.js
+++ b/scripts/__tests__/lefthook-runs-hold-no-double-quote.test.js
@@ -12,12 +12,16 @@ const root = path.resolve(__dirname, "../..");
 test("no run in lefthook.yml holds a double quote", () => {
   const config = yaml.load(fs.readFileSync(path.join(root, "lefthook.yml"), "utf8"));
   const offenders = [];
+  let scanned = 0;
 
   for (const [hook, def] of Object.entries(config)) {
     for (const [name, command] of Object.entries(def?.commands ?? {})) {
+      scanned++;
       if (String(command.run ?? "").includes('"')) offenders.push(`${hook}/${name}`);
     }
   }
 
+  // Zero means the hooks moved to a form this guard does not read, such as `jobs:`.
+  assert.ok(scanned > 0, "no `commands:` run found in lefthook.yml");
   assert.deepEqual(offenders, []);
 });
diff --git a/scripts/__tests__/skill-argument-hints.test.js b/scripts/__tests__/skill-argument-hints.test.js
index 90902e92f..019c0654d 100644
--- a/scripts/__tests__/skill-argument-hints.test.js
+++ b/scripts/__tests__/skill-argument-hints.test.js
@@ -64,3 +64,13 @@ test("a skill whose actions take no input needs no argument-hint", () => {
 
   assert.equal(clean.status, 0, clean.output);
 });
+
+// A Windows checkout turns every line ending into CRLF, and the guard must read the same skill.
+test("a skill checked out with CRLF line endings still reads its argument-hint", () => {
+  const clean = runOn({
+    [SKILL]: frontmatter(["argument-hint: a file path or a ticket"]).replaceAll("\n", "\r\n"),
+    "plugins/aidd-probe/skills/01-thing/actions/01-do.md": "## Input\r\n\r\nA path.",
+  });
+
+  assert.equal(clean.status, 0, clean.output);
+});
diff --git a/scripts/__tests__/sync-readme-counts.test.js b/scripts/__tests__/sync-readme-counts.test.js
new file mode 100644
index 000000000..33775029e
--- /dev/null
+++ b/scripts/__tests__/sync-readme-counts.test.js
@@ -0,0 +1,14 @@
+const assert = require("node:assert/strict");
+const { spawnSync } = require("node:child_process");
+const path = require("node:path");
+const test = require("node:test");
+
+const SCRIPT = path.resolve(__dirname, "..", "sync-readme-counts.mjs");
+
+// Run where the pre-commit runs it, Windows included: a root built from a URL's pathname
+// reads `D:\D:\…\README.md` there, and the hook swallows the failure.
+test("the README counts check finds the README and agrees with the tree", () => {
+  const result = spawnSync(process.execPath, [SCRIPT, "--check"], { encoding: "utf8" });
+
+  assert.equal(result.status, 0, `${result.stdout}${result.stderr}`);
+});
diff --git a/scripts/check-skill-argument-hints.mjs b/scripts/check-skill-argument-hints.mjs
index 258f1b136..f5b65e5f7 100644
--- a/scripts/check-skill-argument-hints.mjs
+++ b/scripts/check-skill-argument-hints.mjs
@@ -67,7 +67,7 @@ function argumentHint(content) {
 async function takesInput(actionFiles) {
   for (const file of actionFiles) {
     const body = await readFile(file, "utf8");
-    if (/^## Input$/m.test(body)) return true;
+    if (/^## Input\r?$/m.test(body)) return true;
   }
   return actionFiles.length === 0;
 }
@@ -75,8 +75,9 @@ async function takesInput(actionFiles) {
 const breaches = [];
 for (const dir of await skillDirs()) {
   const skillPath = path.join(dir, "SKILL.md");
-  const content = await readFile(skillPath, "utf8").catch(() => null);
-  if (content === null) continue;
+  // A Windows checkout ends every line with CRLF, which the frontmatter parse would miss.
+  const content = (await readFile(skillPath, "utf8").catch(() => null))?.replaceAll("\r\n", "\n");
+  if (content == null) continue;
 
   // Named the way the contract and every other guard name a path, whatever the host separator.
   const relative = path.relative(ROOT, skillPath).split(path.sep).join("/");
diff --git a/scripts/sync-readme-counts.mjs b/scripts/sync-readme-counts.mjs
index d3165acf4..2356f316a 100644
--- a/scripts/sync-readme-counts.mjs
+++ b/scripts/sync-readme-counts.mjs
@@ -4,8 +4,10 @@
 // `N skill(s)` code-span after that plugin's heading. `--check` reports instead of writing.
 
 import { readFileSync, writeFileSync, readdirSync, existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 
-const ROOT = new URL("..", import.meta.url).pathname;
+// fileURLToPath, not URL.pathname: on Windows the pathname keeps a leading slash before the drive.
+const ROOT = fileURLToPath(new URL("..", import.meta.url));
 const README = ROOT + "README.md";
 const PLUGINS = ROOT + "plugins";
 

From 95d56b4eca1f35471c4263d5ca2b7216425dbd2f Mon Sep 17 00:00:00 2001
From: Baptiste LAFOURCADE <baptiste.lafourcade@gmail.com>
Date: Mon, 12 Oct 2026 05:19:15 +0200
Subject: [PATCH 4/4] refactor(lefthook): keep only the comments the code
 cannot say

Drop the comments that restated their code or their test's name. Three stay, one
line each: why a run holds no double quote, which name `aidd telemetry` finds
the trailer job by, and what the Windows hooks step runs.

Refs #948

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VE16AxC1V9wAMGmGgefe4z
---
 .github/workflows/cli-ci.yml                                | 6 +-----
 lefthook.yml                                                | 2 +-
 .../__tests__/lefthook-runs-hold-no-double-quote.test.js    | 5 +----
 scripts/__tests__/skill-argument-hints.test.js              | 1 -
 scripts/__tests__/sync-readme-counts.test.js                | 2 --
 scripts/check-skill-argument-hints.mjs                      | 1 -
 scripts/session-trailer-delegate.sh                         | 1 -
 scripts/summarize-plugin-catalogs.sh                        | 1 -
 scripts/sync-readme-counts.mjs                              | 1 -
 9 files changed, 3 insertions(+), 17 deletions(-)

diff --git a/.github/workflows/cli-ci.yml b/.github/workflows/cli-ci.yml
index daabb3ee2..bb7dea8a8 100644
--- a/.github/workflows/cli-ci.yml
+++ b/.github/workflows/cli-ci.yml
@@ -520,11 +520,7 @@ jobs:
       - name: Plugin suite
         run: node scripts/check-tests-leave-git-alone.js -- node --test 'scripts/__tests__/**/*.test.js'
 
-      # What a Windows contributor's commit runs: the pre-commit, every job but the three that
-      # need cli/'s dependencies (Biome there is #881), then the trailer job. Lefthook hands
-      # each job to `sh -c` through a command line it builds by hand, with nothing escaped, so
-      # a double quote in a `run` truncates the script (#948); a check that only fails here is
-      # a Windows bug of its own, and both fail the step.
+      # A Windows commit's hooks (#948), less the three cli jobs that need cli/'s dependencies.
       - name: Hooks - a commit's hooks pass on Windows
         run: |
           echo "# lefthook subject" > "$RUNNER_TEMP/msg"
diff --git a/lefthook.yml b/lefthook.yml
index 9feae1aa7..df11272be 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -180,7 +180,7 @@ commit-msg:
 
 # lefthook owns prepare-commit-msg here and regenerates it on install, so `aidd telemetry on`'s
 # delegate is called from a job instead. Absent delegate, nothing runs — opt-in per machine.
-# The run line names `aidd-session-trailer.sh` itself: that name is how `aidd telemetry` finds this job.
+# `aidd telemetry` finds this job by the delegate name in its run line.
 prepare-commit-msg:
   commands:
     aidd-session-trailer:
diff --git a/scripts/__tests__/lefthook-runs-hold-no-double-quote.test.js b/scripts/__tests__/lefthook-runs-hold-no-double-quote.test.js
index ab1066fe2..4717bcf30 100644
--- a/scripts/__tests__/lefthook-runs-hold-no-double-quote.test.js
+++ b/scripts/__tests__/lefthook-runs-hold-no-double-quote.test.js
@@ -6,9 +6,7 @@ const yaml = require("js-yaml");
 
 const root = path.resolve(__dirname, "../..");
 
-// Lefthook on Windows hands each job to `sh -c` through a command line it builds by hand,
-// escaping nothing (#948): a `"` in a `run` closes the argument, and sh gets a truncated
-// script. A `'` is safe, and so is a script file the run line only names.
+// Lefthook on Windows passes a run to `sh -c` unescaped, so a `"` truncates it (#948).
 test("no run in lefthook.yml holds a double quote", () => {
   const config = yaml.load(fs.readFileSync(path.join(root, "lefthook.yml"), "utf8"));
   const offenders = [];
@@ -21,7 +19,6 @@ test("no run in lefthook.yml holds a double quote", () => {
     }
   }
 
-  // Zero means the hooks moved to a form this guard does not read, such as `jobs:`.
   assert.ok(scanned > 0, "no `commands:` run found in lefthook.yml");
   assert.deepEqual(offenders, []);
 });
diff --git a/scripts/__tests__/skill-argument-hints.test.js b/scripts/__tests__/skill-argument-hints.test.js
index 019c0654d..fd394701b 100644
--- a/scripts/__tests__/skill-argument-hints.test.js
+++ b/scripts/__tests__/skill-argument-hints.test.js
@@ -65,7 +65,6 @@ test("a skill whose actions take no input needs no argument-hint", () => {
   assert.equal(clean.status, 0, clean.output);
 });
 
-// A Windows checkout turns every line ending into CRLF, and the guard must read the same skill.
 test("a skill checked out with CRLF line endings still reads its argument-hint", () => {
   const clean = runOn({
     [SKILL]: frontmatter(["argument-hint: a file path or a ticket"]).replaceAll("\n", "\r\n"),
diff --git a/scripts/__tests__/sync-readme-counts.test.js b/scripts/__tests__/sync-readme-counts.test.js
index 33775029e..a7068127e 100644
--- a/scripts/__tests__/sync-readme-counts.test.js
+++ b/scripts/__tests__/sync-readme-counts.test.js
@@ -5,8 +5,6 @@ const test = require("node:test");
 
 const SCRIPT = path.resolve(__dirname, "..", "sync-readme-counts.mjs");
 
-// Run where the pre-commit runs it, Windows included: a root built from a URL's pathname
-// reads `D:\D:\…\README.md` there, and the hook swallows the failure.
 test("the README counts check finds the README and agrees with the tree", () => {
   const result = spawnSync(process.execPath, [SCRIPT, "--check"], { encoding: "utf8" });
 
diff --git a/scripts/check-skill-argument-hints.mjs b/scripts/check-skill-argument-hints.mjs
index f5b65e5f7..cfc498c02 100644
--- a/scripts/check-skill-argument-hints.mjs
+++ b/scripts/check-skill-argument-hints.mjs
@@ -75,7 +75,6 @@ async function takesInput(actionFiles) {
 const breaches = [];
 for (const dir of await skillDirs()) {
   const skillPath = path.join(dir, "SKILL.md");
-  // A Windows checkout ends every line with CRLF, which the frontmatter parse would miss.
   const content = (await readFile(skillPath, "utf8").catch(() => null))?.replaceAll("\r\n", "\n");
   if (content == null) continue;
 
diff --git a/scripts/session-trailer-delegate.sh b/scripts/session-trailer-delegate.sh
index 47629f414..dd23394a7 100755
--- a/scripts/session-trailer-delegate.sh
+++ b/scripts/session-trailer-delegate.sh
@@ -1,5 +1,4 @@
 #!/bin/sh
-# A file, not a lefthook run: its quotes would break Windows' hand-built sh -c line (#948).
 delegate="$(git rev-parse --git-common-dir)/hooks/$1"
 shift
 if [ -f "$delegate" ]; then sh "$delegate" "$@"; fi
diff --git a/scripts/summarize-plugin-catalogs.sh b/scripts/summarize-plugin-catalogs.sh
index 4a7561e9b..0863bbb89 100755
--- a/scripts/summarize-plugin-catalogs.sh
+++ b/scripts/summarize-plugin-catalogs.sh
@@ -1,5 +1,4 @@
 #!/bin/sh
-# A file, not a lefthook run: its quotes would break Windows' hand-built sh -c line (#948).
 [ -d plugins ] || exit 0
 if ! command -v node >/dev/null 2>&1; then
   echo "ℹ️  node not available; skipping summarize-plugin-catalogs"
diff --git a/scripts/sync-readme-counts.mjs b/scripts/sync-readme-counts.mjs
index 2356f316a..6c47ae300 100644
--- a/scripts/sync-readme-counts.mjs
+++ b/scripts/sync-readme-counts.mjs
@@ -6,7 +6,6 @@
 import { readFileSync, writeFileSync, readdirSync, existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
-// fileURLToPath, not URL.pathname: on Windows the pathname keeps a leading slash before the drive.
 const ROOT = fileURLToPath(new URL("..", import.meta.url));
 const README = ROOT + "README.md";
 const PLUGINS = ROOT + "plugins";