ADR-0009 stress coverage claims exceed what stress.yml actually runs

[dichovsky]

docs/adr/0009-fault-injection-and-concurrency-hardening.md:47-49 promises the full 500-iteration stress matrix "nightly, on release, and whenever concurrency-critical paths change … on both operating systems at the minimum supported Node version", and docs/design/product-spec.md:129 says "on Linux and macOS". Reality: .github/workflows/stress.yml runs only on ubuntu-latest at Node 24.18.0 (not the 24.15 floor from src/node-floor.ts), triggered by schedule/dispatch/stress-full label only — no macOS leg, no on-release or path-change trigger. Even stress.yml's own header comment claims it runs "at the Node floor".

Impact: the concurrency-hardening evidence the ADR relies on is weaker than documented (single OS, non-floor Node, fewer triggers).

Acceptance: either the workflow matrix is extended (macOS leg, floor-Node leg, release/path triggers), or the ADR, product-spec passage, and stress.yml header are rewritten to match the actual coverage.

[dichovsky]

Assessment: re-verified against main @ 97d7f88. All three cited passages confirmed, and the scope is wider than filed — two further locations carry the same drift, and one of them is a closed release gate.

Confirmed as filed

• docs/adr/0009-fault-injection-and-concurrency-hardening.md:46-50 reads "a job that runs nightly, on release, and whenever concurrency-critical paths change runs the full count (500 per case) on both operating systems at the minimum supported Node version".
• .github/workflows/stress.yml contradicts every clause of that: runs-on: ubuntu-latest (:26) — one OS; node-version: '24.18.0' (:33) against NODE_FLOOR = '24.15.0' (src/node-floor.ts:10) — not the floor; triggers are schedule (:11-12), workflow_dispatch (:13), and pull_request: types: [labeled] gated on stress-full (:18-19, :25) — no release trigger, no path filter.
• docs/design/product-spec.md:130 — "a repeatable forced-contention suite on Linux and macOS".
• stress.yml's own header claims the floor twice: :4 ("at the Node floor") and the inline comment at :31-32 ("Node floor: the lowest supported runtime").

There is no macOS runner anywhere in the repository. grep -rn "runs-on" .github/workflows/ returns ubuntu-latest seven times across all six workflows and nothing else.

Two deltas against the body (noted here; body left as written)

1. docs/design/srs.md:237 carries the same claim, at authority rank 2. FR-A10's traceability line is "Verify: analysis — CI matrix (Ubuntu + macOS)." That matrix does not exist. The body names ADR-0009 and product-spec but not the SRS, which outranks product-spec.
2. .github/workflows/ci.yml:36-37 repeats the trigger claim: "The full hundreds-of-iterations matrix runs in stress.yml (nightly + release + concurrency-critical paths)." Same two false clauses as the ADR, in a second workflow file.

Also worth recording, because it narrows the fix: docs/design/testing-strategy.md:129-130 is already accurate — "the full 500 per case nightly and on manual dispatch during release prep, at Node 24.18.0". It states the real triggers and the real Node version, and simply does not mention OS. It is the one document that never drifted, and it is evidence that the actual coverage was understood correctly somewhere.

The consequential finding

docs/design/product-spec.md:113 states "The SQLite-stress and Security-review gates are closed", in what :107 calls "the canonical release-gate list" that "[o]ther documents reference … and must not keep a separate copy". The evidence criterion that closes that gate is :130 — "a repeatable forced-contention suite on Linux and macOS". The macOS half has never run. So the gate is recorded as closed against evidence that was never produced, and 0.1.0/0.1.1 shipped on that record.

That is not a wording problem. It is a release-status statement, and docs/README.md's "Current readiness" section is the single source of truth for release status.

Verdict: PLAN-ONLY

• Blast radius — docs/adr/0009-*.md (authority level 1), docs/design/srs.md FR-A10 (level 2), docs/design/product-spec.md (the canonical release-gate table, plus a closed-gate statement), docs/design/testing-strategy.md, .github/workflows/stress.yml, .github/workflows/ci.yml, and CONTRIBUTING.md:49-51. Nothing under src/, bin/, tests/, web/, or docs-site/ — but CI configuration is the gate that guards all of them, so a wrong edit degrades every subsequent PR's evidence rather than any single behavior. Nothing currently guards workflow content: grep -rln "workflows\|stress.yml" over tests/ returns only tests/helpers/stress.ts and tests/spawn/agents.test.ts (both CREW_STRESS_ITERS consumers), and collectAdrs/collectCommands in tests/unit/docs-facts.test.ts read ADR H1s, package.json, and vitest.config.ts — never a workflow. So this drift is unguarded in both directions.

• Reversibility — asymmetric, which is the crux. The documentation half is a text revert. The workflow half is not: a macOS leg and a floor-Node leg cannot be validated from here (this routine has no macOS runner and cannot execute the nightly), and if either turns red it does so on a suite whose own header says "A flaky failure here is a release failure, not a candidate for a blind retry" (stress.yml:8-9). A cross-platform difference in node:sqlite locking is exactly the class of failure that would surface, and it would land as a permanently red nightly on main rather than a revertable PR. Separately, the documentation branch is not cheaply reversible either, because it would amend an accepted ADR and restate a closed release gate.

• Contract impact — this is why the verdict is PLAN-ONLY rather than IMPLEMENT. ADR-0009 is authority level 1 and the release-gate table is canonical, so by the authority order in docs/README.md the workflow is the side that is wrong, not the ADR. That makes the Acceptance's second branch — "the ADR, product-spec passage, and stress.yml header are rewritten to match the actual coverage" — a reversal of an accepted decision dressed as a documentation fix. .github/ISSUE_TRIAGE.md routes exactly that case away from the routine: an accepted ADR is not corrected downward to match what CI happens to do, and "we have decided single-OS stress is sufficient evidence" is a wontfix-adjacent judgment the routine may not make. No FR-*/NFR-* id is added or renumbered and CURRENT_SCHEMA_VERSION stays 7 — but FR-A10's Verify line changes meaning under either branch, and NFR-POR-01 (srs.md:1191, "crew shall run on macOS and Linux") is the requirement whose CI evidence is at stake.

I am confident I could execute either branch. Choosing between them is the part that is not mine.

---

The decision a human must make first

Does the SQLite-stress release gate require macOS evidence, or not?

Everything below follows mechanically from the answer. Two sub-questions ride along with Branch A: whether a macOS leg on the nightly is worth its runner time, and whether the SQLite-stress gate should be recorded as reopened until that leg is green (given 0.1.0/0.1.1 shipped against the current record).

---

Branch A — extend CI to match ADR-0009 (the authority-order-preserving branch)

.github/workflows/stress.yml

• Add strategy: matrix: os: [ubuntu-latest, macos-latest] and set runs-on: ${{ matrix.os }} (:26). Add fail-fast: false so one OS failing still yields evidence from the other.
• Change node-version (:33) to the floor. Verify before pinning that 24.15.0 resolves in actions/setup-node@v6; if it does not, pin the lowest 24.x that does and say which, in the step comment — do not silently leave 24.18.0 while the comment at :31-32 claims the floor.
• The tmux install at :38 is apt-get-only and will fail on macOS. It must become two OS-conditional steps (if: runner.os == 'Linux' → apt-get; if: runner.os == 'macOS' → brew install tmux). CREW_REQUIRE_TMUX: '1' (:44) then turns any install failure into a hard failure rather than a silent skip, which is the intended behavior — do not weaken it for the macOS leg.
• Add the two missing triggers: release: types: [published], and a pull_request/push paths: filter naming the concurrency-critical paths. Derive that list from what the suite actually exercises rather than guessing — at minimum src/store/**, src/io.ts, and tests/spawn/**. The if: condition at :25 must be widened in the same edit, or the new triggers will be filtered straight back out by the existing github.event_name != 'pull_request' || ... 'stress-full' guard.
• Artifact upload (:49-56): name: stress-artifacts collides across matrix legs on actions/upload-artifact@v7. Make it stress-artifacts-${{ matrix.os }}-${{ matrix.node }}.

.github/workflows/ci.yml — :36-37 becomes true as written; no edit needed. Confirm rather than assume.

docs/design/testing-strategy.md:129-130 — currently correct about single-OS-by-omission and about 24.18.0; both become stale. Restate as the matrix that lands.

CONTRIBUTING.md:49-51 — describes stress.yml as triggered by "the stress-full label" only; name the release and path triggers.

No ADR, SRS, or product-spec edit. srs.md:237's FR-A10 Verify line and product-spec.md:130 become true, which is the point of this branch.

Tests. Add a drift guard — nothing currently asserts workflow content. tests/unit/docs-facts.test.ts is the established home for "authoritative module vs. prose" guards, but a workflow guard is a different shape; a new tests/unit/ci-facts.test.ts is cleaner. It must assert that stress.yml's node-version equals NODE_FLOOR from src/node-floor.ts, and that the os matrix covers the platforms NFR-POR-01 names. How it fails before the fix: on current main the first assertion fails 24.18.0 !== 24.15.0 and the second finds no matrix key at all. Note that this guard is what makes Branch A durable — without it the same drift returns the next time the pinned Node moves.

---

Branch B — narrow the documented promise to actual coverage

Only viable if the human answers "macOS evidence is not required". It is the larger change, not the smaller one, because it amends an accepted ADR.

docs/adr/0009-*.md:46-50 — the "Stress tests run in two CI tiers" paragraph. Do not silently rewrite the body. An ADR records the decision as it was made; #36 and #93 are actively settling the amendment-marker convention for exactly this situation, and PR #91 is where the form is being decided. This edit must either wait on that convention or be a new superseding ADR. That dependency is a reason to prefer Branch A, not a detail.

docs/design/product-spec.md — :130 drop "and macOS" from the SQLite-stress evidence criterion; then re-examine :113's "are closed" in the same change, because narrowing the criterion is what makes the closed status true retroactively. State explicitly in the PR body that this is what the edit does.

docs/design/srs.md:237 — FR-A10's Verify line: "CI matrix (Ubuntu + macOS)" → the real matrix. Leave NFR-POR-01 (:1191) and FR-A09 (:233) alone: crew still supports macOS; only the CI evidence claim is narrowed. Do not let this edit bleed into the support statement.

.github/workflows/stress.yml:4 and :31-32 — "at the Node floor" → the actual pinned version, phrased so it does not re-drift (e.g. name it as CI's pinned version, distinct from the floor).

.github/workflows/ci.yml:36-37 — "(nightly + release + concurrency-critical paths)" → "(nightly + manual dispatch + the stress-full label)".

docs/design/testing-strategy.md:129-130 — add the single-OS fact, so the one accurate document stays the accurate one.

Tests. Same tests/unit/ci-facts.test.ts guard, asserting the narrowed claims instead. Under this branch the Node-floor assertion is inverted: assert that the workflow comment does not claim the floor while pinning something else.

---

Out of scope, either branch

• docs/design/testing-strategy.md's package-verification list — Docs: testing-strategy.md's package-verification list claims checks pack-smoke does not perform #77 and Tests: testing-strategy.md's package-verification list names three checks the pack-smoke never makes #80, a different list in the same file.
• Release evidence files — Release evidence files mandated by three docs were never committed #39.
• The ADR amendment-marker convention itself — Stale ADR cross-references: ADR-0014 amendment marker, ADR-0011 path, decisions.md range #36 (PR docs: signpost ADR amendments and fix stale ADR cross-references #91 open) and ADRs: the amendment marker introduced for ADR-0014 covers only that one ADR, while two others are also superseded #93. Branch B consumes that convention; it must not redefine it.
• launch-e2e.yml, ui-e2e.yml, pages.yml, publish.yml — all ubuntu-latest too, but no document promises otherwise for any of them. Only ci.yml and stress.yml have a claim to contradict.
• Whether ci.yml's fast tier should also gain a macOS leg — FR-A10's Verify line says "CI matrix", not "stress matrix", so a reader could argue it points at ci.yml. Resolving that reading is part of the human decision above, not something to settle unilaterally.

Label note

documentation alone undersells this. The stress.yml:4/:31-32 and ci.yml:36-37 passages are source comments contradicting the configuration directly beneath them — outside docs/, and the class .github/ISSUE_TRIAGE.md routes to bug (same shape as #58's release-smoke.test.ts half, #68, and #60). I have not added bug myself: #37 was not in this run's Phase A sweep set, and Phase B's action limits name only the triage/* labels. Flagging it for whoever picks this up.

Label applied: triage/plan-ready. No code written.

---

Generated by Claude Code