Optimize spec-driven workflow: gates, metrics, lessons, complexity triage

.gitattributes

@@ -0,0 +1,50 @@
+# Line-ending policy. Normalize all text to LF in the repo; check shell and PowerShell scripts out
+# as LF on every platform so shebangs and heredocs parse and cross-platform parity holds (SW-21).
+# PowerShell 5.1 reads either; pinning LF is cheap consistency and is unaffected by the pure-ASCII
+# rule for *.ps1 (CLAUDE.md). With core.autocrlf=true (the Git default on Windows and on the
+# windows-latest CI runner) an unpinned *.sh checks out CRLF, putting a trailing CR on the
+# `#!/usr/bin/env bash` shebang (bad interpreter) and mis-parsing heredocs and `[[ ... ]]`.
+* text=auto
+
+*.sh  text eol=lf
+*.ps1 text eol=lf
+
+# Byte-comparison fixtures must keep LF on every platform.
+#
+# scripts/aggregate-lessons.{ps1,sh} deliberately render LF and compare the
+# result against tests/lessons/fixtures/expected-lessons.md byte for byte. With
+# core.autocrlf=true (the Git default on Windows, and on the windows-latest CI
+# runner) that fixture would be checked out as CRLF, and the comparison would
+# fail for a reason that has nothing to do with the code under test.
+#
+# The `* text=auto` default above normalizes to LF in the repo but still yields a
+# native (CRLF) checkout on Windows, so these fixture trees keep an explicit eol=lf pin.
+tests/lessons/** text eol=lf
+
+# tests/task-format/** are field-grammar fixtures (SW-11). They assert how a
+# reader splits a task block into fields; a CRLF checkout on Windows would make
+# any byte-level or line-ending-sensitive reader disagree with the same file on
+# Linux. Pinned for the same reason as the lesson fixtures above.
+tests/task-format/** text eol=lf
+
+# tests/revision-log/** are revision-log integrity fixtures (SW-14). The
+# valid-revision case proves the original plan prose stays byte-intact while a
+# revision is appended below it; a CRLF checkout on Windows would break any
+# byte-level comparison. Pinned for the same reason as the fixtures above.
+tests/revision-log/** text eol=lf
+
+# tests/hooks/fixtures/**/_metrics/events.jsonl are pre-seeded rotation inputs
+# (SW-15). The rotation trigger compares the file's raw byte size against
+# maxSizeKb*1024, so a CRLF checkout on Windows would change the seed's size.
+# The seed clears the 1 KB cap by a wide margin either way and the conformance
+# comparison is JSON-normalized, so correctness does not depend on this - but
+# pin LF anyway so the byte size is identical on every platform. Same reasoning
+# as the fixture pins above.
+tests/hooks/fixtures/**/_metrics/events.jsonl text eol=lf
+
+# tests/metrics/** is the /sd:status verification corpus (SW-16). The command
+# counts events by exact substring over an LF-terminated log, and the malformed
+# fixture asserts an exact skipped count - a CRLF checkout on Windows would
+# change both the line contents under test and the well-formed-line test that
+# anchors on a trailing '}'. Pinned for the same reason as the fixtures above.
+tests/metrics/** text eol=lf

.github/workflows/ci.yml

@@ -40,6 +40,82 @@ jobs:
         shell: pwsh
         run: ./scripts/smoke-hooks.ps1
 
+      # --- Lesson privacy validator, both directions. The clean fixture passing
+      # proves the grammar is accepted; the leaky fixture FAILING is what proves
+      # the checks still fire. Only the second one catches a validator that has
+      # rotted into a no-op ---------------------------------------------------
+      - name: Lesson validator (bash)
+        if: runner.os == 'Linux' || runner.os == 'macOS'
+        shell: bash
+        run: |
+          bash scripts/validate-lessons.sh tests/lessons/fixtures/clean-lessons.md
+          if bash scripts/validate-lessons.sh tests/lessons/fixtures/leaky-lessons.md; then
+            echo "::error::leaky fixture passed the validator - checks are not firing"
+            exit 1
+          fi
+
+      - name: Lesson validator (PowerShell)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          ./scripts/validate-lessons.ps1 tests/lessons/fixtures/clean-lessons.md
+          if ($LASTEXITCODE -ne 0) { throw "clean fixture failed the validator" }
+          ./scripts/validate-lessons.ps1 tests/lessons/fixtures/leaky-lessons.md
+          if ($LASTEXITCODE -eq 0) { throw "leaky fixture passed the validator - checks are not firing" }
+          # The leaky fixture is EXPECTED to exit non-zero; without this reset, the
+          # implicit "exit $LASTEXITCODE" GitHub Actions appends to every pwsh step
+          # would fail the step on its own correctly-detecting assertion.
+          exit 0
+
+      # --- Lesson aggregator: pin the rendered output against a committed
+      # expected file, then assert idempotence via --check. Both implementations
+      # must land on the SAME bytes; the expected file is what makes a
+      # culture-aware sort or a CRLF write fail loudly instead of drifting -----
+      - name: Lesson aggregator (bash)
+        if: runner.os == 'Linux' || runner.os == 'macOS'
+        shell: bash
+        run: |
+          bash scripts/aggregate-lessons.sh \
+            --spec-dir tests/lessons/fixtures/corpus \
+            --out tests/lessons/fixtures/expected-lessons.md --check
+          bash scripts/validate-lessons.sh tests/lessons/fixtures/expected-lessons.md
+
+      - name: Lesson aggregator (PowerShell)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          ./scripts/aggregate-lessons.ps1 -SpecDir tests/lessons/fixtures/corpus `
+            -Out tests/lessons/fixtures/expected-lessons.md -Check
+          if ($LASTEXITCODE -ne 0) { throw "PowerShell aggregator output differs from the expected fixture" }
+          ./scripts/validate-lessons.ps1 tests/lessons/fixtures/expected-lessons.md
+          if ($LASTEXITCODE -ne 0) { throw "generated lessons file failed the privacy validator" }
+
+      # --- Docs-consistency self-test: the validator above proves the docs are
+      # right; this proves the validator would NOTICE if they were wrong. Without
+      # it, a Check 7 that rotted into a no-op would still report green ---------
+      - name: Docs-consistency self-test (bash)
+        if: runner.os == 'Linux' || runner.os == 'macOS'
+        shell: bash
+        run: bash scripts/selftest-docs.sh
+
+      - name: Docs-consistency self-test (PowerShell)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: ./scripts/selftest-docs.ps1
+
+      # --- Cross-impl hook conformance: pipe each golden fixture into BOTH
+      # implementations (bash + pwsh); normalized decisions must match the
+      # golden and each other. Runs under pwsh on every OS: ubuntu/macos get
+      # bash natively + pwsh preinstalled, windows gets pwsh natively + Git
+      # Bash. A divergence in only one impl fails with a three-way diff ----
+      - name: Hook conformance (bash vs PowerShell)
+        shell: pwsh
+        run: ./tests/hooks/run-conformance.ps1
+
+      - name: Hook conformance self-test (divergence detection)
+        shell: pwsh
+        run: ./tests/hooks/run-conformance.ps1 -SelfTest
+
       # --- Install -> uninstall round-trip (CLAUDE.md sandbox recipe) --------
       - name: Install -> uninstall round-trip (bash)
         if: runner.os == 'Linux' || runner.os == 'macOS'