v0.0.2 phases 7-13: OS-invariant cross-OS cache sharing, Windows CI reuse, read-only Actions-cache backend

.fallowrc.jsonc

@@ -25,6 +25,11 @@
     // cannot infer it. Resolves the mirrored asset through the real Releases reader
     // behind a pathToFileURL(main) guard.
     "packages/github-cache/src/roundtrip/read-back.ts",
+    // Cross-OS hash-parity gate entry: ci.yml's hash-parity-compare job invokes it
+    // as dist/hash-parity/assert-parity.js via node; never imported, so reachability
+    // analysis cannot infer it. Reads both legs' records and calls compareHashParity
+    // behind a pathToFileURL(main) guard (CORR-03, D-19).
+    "packages/github-cache/src/hash-parity/assert-parity.ts",
     // Consumer JS action entry: esbuild.action.mjs bundles it to
     // start-cache-server/index.js, which the runner invokes as action.yml's `main`;
     // it is never imported, so reachability analysis cannot infer it (D-09, Phase 6).
@@ -35,6 +40,11 @@
     // npm tarball file-list guard: the `pack:check` package script + the ci.yml
     // pack-check job invoke it as a standalone node bin; never imported (T-06-01-01).
     "packages/github-cache/pack-check.cjs",
+    // Nx task-hash capture instrument: the `capture:hashes` package script + the
+    // ci.yml hash-parity capture job invoke it as a standalone node bin; never
+    // imported, so reachability analysis cannot infer it. Deliberately NOT an Nx
+    // target -- a cached capture would replay instead of measure (D-01b).
+    "capture-hashes.mjs",
     // Integration vitest config: consumed by the `integration` target's
     // `vitest run --config` command (project.json), not by any import. fallow
     // auto-credits vitest.config.mts but not the .integration. variant, so declare it.
@@ -60,6 +70,7 @@
   // string match (not glob); exempts each from BOTH unused-dependency and
   // unlisted-dependency detection. Removing any of these breaks the build.
   "ignoreDependencies": [
+    "@nx/eslint", // Nx plugin that INFERS the `lint` target via nx.json (D-01)
     "@nx/vitest", // Nx plugin that INFERS the `test` target via nx.json
     "@swc-node/register", // SWC transpile hook for the test runner
     "@swc/helpers", // SWC runtime helpers

.github/workflows/windows-regression-detector.yml

@@ -0,0 +1,120 @@
+name: Windows regression detector
+
+# The scheduled --skip-nx-cache windows-11-arm run (XOS-05/D-08). This is a
+# SEPARATE scheduled workflow, never a job inside ci.yml: adding a schedule
+# trigger to ci.yml would fire EVERY ONE of its jobs on a calendar cadence
+# unless every one of them grew an `if:` gate, and cleanup.yml's own header
+# already records why a scheduled concern lives in its own file. (This line used
+# to say "all nineteen of its jobs". ci.yml declares 21 job keys at HEAD -- 18
+# before XOS-04 added three -- so the number was wrong on the day this file was
+# authored and wrong again three jobs later. The ARGUMENT never depended on it,
+# so the count is dropped rather than restated: an unguarded number in a comment
+# rots, and a comment carrying a false claim is a documented argument for undoing
+# the work it explains.)
+#
+# WHY IT EXISTS, in XOS-05's own words, because the job below is unreadable
+# without them: the success signal for O4 -- every target reporting
+# [remote cache], wall time collapsing to sidecar overhead -- is the IDENTICAL
+# observation to a Windows-only regression being invisible forever. A green O4
+# leg IS a Windows leg that did not run the code. Reading a green O4 CI as
+# evidence that the targets are PORTABLE is circular, and REQUIREMENTS.md's Out
+# of Scope table names it as such: a restored task does not execute.
+#
+# So once XOS-04 lands, this workflow is the ONLY path in the repository that
+# EXECUTES build, typecheck or test on a Windows runner. That is its whole
+# justification, and it is why it HARD FAILS rather than warning. It is NOT the
+# "tripwire that fires on correct work" class OBS-04 records disabling: a red
+# leg here means a genuine Windows-only regression in the code under test,
+# never correct work.
+on:
+  # Once daily, off the top of the hour: GitHub delays scheduled runs under
+  # top-of-hour load, and this check has no deadline, so an off-peak minute is
+  # fine. Both fields differ from cleanup.yml's '17 3 * * *' so the two
+  # scheduled workflows do not contend.
+  schedule:
+    - cron: '23 4 * * *'
+  # workflow_dispatch is how the detector gets re-run ON DEMAND AFTER merge.
+  # It does NOT close the "does this go green on a real runner" question before
+  # merge, and must never be documented as if it could: GitHub only dispatches a
+  # workflow whose file exists on the DEFAULT branch, so a brand-new file on a
+  # feature branch does not appear in the UI at all and the API rejects it.
+  # cleanup.yml, the shape precedent, carries a schedule trigger ONLY -- so this
+  # addition is deliberate, and its justification is post-merge re-runs.
+  workflow_dispatch:
+
+# Least privilege: this job checks out, installs and runs four targets, and
+# writes nothing -- no Releases asset, no Actions-cache entry, no package. It
+# therefore does not copy cleanup.yml's write scope (cleanup needs one because
+# it DELETES release assets), and it requests no Actions scope either.
+permissions:
+  contents: read
+
+# No concurrency group here, deliberately. cleanup.yml needs single-writer
+# serialization because concurrent DELETEs are unsafe; this job deletes nothing
+# and writes nothing, so two overlapping runs are harmless and the mechanism
+# would be unrequested.
+
+jobs:
+  detect:
+    runs-on: windows-11-arm
+    # 20 rather than the 15 the ci.yml jobs carry: this is the only job in the
+    # repository whose wall time is FULL cold execution of all four targets
+    # rather than a cache restore, so it needs more headroom than a leg that
+    # HITs. `lint` joined the set without raising this: it is the cheapest of
+    # the four and the ceiling was already sized for the three expensive ones.
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: '.node-version'
+          cache: 'npm'
+      - run: npm ci
+      # NO sidecar block and no remote-cache client variable, deliberately
+      # (D-08). --skip-nx-cache skips the remote READ and the remote WRITE at
+      # Nx 23.1.0 -- source-traced: doNotSkipCache gates the read AND is passed
+      # as postRunSteps' shouldCache argument -- so a cache server here would be
+      # dead weight and an extra cache producer this milestone does not want.
+      # With no remote-cache client variable in the environment there is no
+      # remote tier at all, regardless. No separate build step either: the
+      # run-many invocation below IS the build.
+      #
+      # Exit 0 is NOT sufficient, and that is the whole reason this is a
+      # scripted step rather than a bare `- run:`. nx run-many with no matching
+      # target ANYWHERE prints "NX No tasks were run" and exits 0 (measured in
+      # this repo). Worse for a four-target run: source-traced at
+      # node_modules/nx/dist/src/tasks-runner/life-cycles/formatting-utils.js:37
+      # Nx FILTERS the printed target list down to targets that actually
+      # resolved a task, so a needle matching only the singular prefix still
+      # PASSES when three of the four ran. The needle below therefore names all
+      # four, in -t argument order. The trade: it pins the -t ARGUMENT ORDER
+      # too, so reordering the flags reddens a CORRECT run -- and the fix for
+      # that is to update the needle and its clause in
+      # windows-regression-detector.spec.ts in the SAME commit, never to
+      # shorten the needle.
+      #
+      # One invocation rather than four single-target steps: one graph load on
+      # the slowest runner in the fleet, and Nx already names the failing target
+      # in its own output.
+      #
+      # NO_COLOR is MORE load-bearing here than in ci.yml's lint job, not less.
+      # Nx bolds each target name INDIVIDUALLY while the ", " separators are
+      # not, so with colour on the combined line carries four escape-sequence
+      # pairs interleaved with the commas and a plain-text match cannot fire. A
+      # gate that always fails gets deleted just as fast as one that never
+      # fires.
+      #
+      # shell: bash is REQUIRED, not stylistic: the default shell on
+      # windows-11-arm is pwsh, which fails on set -euo pipefail, on the pipe
+      # and on tee. The grep is runner-side POSIX inside a workflow body and is
+      # correct -- this project's never-use-grep rule governs the agent's own
+      # shell, not workflow bodies, and ci.yml's lint job already uses grep -q
+      # for exactly this purpose.
+      - name: Execute build, typecheck, test and lint on Windows with the Nx cache bypassed
+        shell: bash
+        env:
+          NO_COLOR: '1'
+        run: |
+          set -euo pipefail
+          npm exec -- nx run-many -t build typecheck test lint --skip-nx-cache 2>&1 | tee detector.log
+          grep -q 'Successfully ran targets build, typecheck, test, lint for project' detector.log

.gitignore

@@ -44,12 +44,66 @@ Thumbs.db
 # fallow dead-code analysis cache (self-ignored via .fallow/.gitignore too)
 .fallow/
 
+# capture-hashes.mjs measurement records, written at the workspace ROOT by the
+# hash-parity CI job and by a local `npm run capture:hashes` / `assert:graph-premise`.
+# Ignored so they never dirty the working tree the NEXT record measures: both modes
+# record `workingTreeClean`, which exists to reveal an uncommitted nx.json edit, and
+# an untracked sibling record would peg the field to false and destroy that signal.
+# The COMMITTED copies of these records live under .planning/, never here.
+/hash-parity-*.json
+/graph-premise-*.json
+
+# O3 probe records, written at the workspace ROOT by ci.yml's integration and
+# o3-witness steps and by a local `node read-integration-hash.mjs`. Ignored for the
+# same reason as the records above -- an untracked sibling would dirty the tree the
+# next `workingTreeClean` measurement reads -- and because integration-hash.txt's
+# contents become a cache key, so it must never be committed and mistaken for one.
+/integration-nx.log
+/integration-hash.txt
+/o3-witness.log
+
+# The remaining workspace-ROOT logs the CI jobs tee, for the SAME reason as the two
+# above and completing that set: `build-nx.log`, `typecheck-nx.log` and `test-nx.log`
+# (the three Windows reuse legs' runtime cache observation), `lint.log`,
+# `hash-parity.log` (the `^hash-parity: PARITY OK` grep target) and `detector.log`
+# (windows-regression-detector.yml). Only the two O3 logs were listed, which made the
+# rule look like an O3 special case rather than what it is: a `tee` at the workspace
+# root leaves an UNTRACKED file, and `capture-hashes.mjs` records `workingTreeClean`
+# from `git status --porcelain`, so any of these sitting beside a capture pegs that
+# field to false and destroys the signal it exists to carry. Latent today only because
+# no job both tees and captures in one checkout -- which is a scheduling accident, not
+# a guarantee, and the hash-parity job already tees `hash-parity.log`.
+/build-nx.log
+/typecheck-nx.log
+/test-nx.log
+/lint.log
+/hash-parity.log
+/detector.log
+
+# The OPERATOR-side counterpart to the list above, for the identical reason. AGENTS.md's
+# "Capturing test-battery output" section tells a human (or an agent) to tee each battery
+# iteration to `test-<epoch>-<i>.log` at the workspace root so a failing run's output
+# survives -- Nx caches terminal output for SUCCESSFUL runs only, so the re-run destroys the
+# evidence. Those logs are untracked by construction and would peg `workingTreeClean` to
+# false in exactly the way the paragraph above describes. A glob rather than an enumeration
+# because the iteration suffix is unbounded; it subsumes `/test-nx.log`, which is kept above
+# so the CI-teed set stays readable as a complete list.
+/test-*.log
+
 # op-nx/github-cache act test harness (test-only, never a runtime dep)
 .act-cache
 .act-artifacts
 .cursor/rules/nx-rules.mdc
 .github/instructions/nx.instructions.md
 
+# GSD research-tool response cache (hash-named JSON, written by the `research-*`
+# query handlers). Generated, never authored, and worthless as history -- but it is
+# NOT merely noise: it lands untracked under `.planning/`, and `capture-hashes.mjs`
+# records `workingTreeClean` from `git status --porcelain`, so a research probe run
+# in the same checkout as a hash capture pegs that field to false and destroys the
+# signal, exactly as the workspace-root logs above would. Same rule, new writer.
+.planning/research/.cache/
+
 .claude/worktrees
 .claude/settings.local.json
 .nx/polygraph