ci(replay-soak-gate): scope to #264-touching paths only

[yoshi280]

Summary

Adds a paths: filter to .github/workflows/replay-soak-gate.yml so the gate fires only on PRs that touch the derivation-contract surface (the actual #264 risk surface), the soak fixture, the runner/streak scripts, or the soak workflows themselves.

Why

The gate's own docstring says it gates "#264-touching merges" but the trigger had no path filter, so every open PR shows a red consecutive-green ≥ 7d check — including six unrelated PRs in flight today (#426, #428, #429, #430, #431, #432) covering retrieval, BM25F, edge rerank, contradiction detector, UX, and docs. None of those touch the derivation contract; the gate firing on them is noise.

The check is not in the branch ruleset's required_status_checks list (verified via gh api .../rules/branches/main), so the red state is advisory rather than blocking. But it's misleading to reviewers and makes mergeStateStatus: BLOCKED appear in gh pr view.

Path scope

Files where a change can plausibly affect replay_full_equality:

• src/aelfrice/derivation.py — derive() itself
• src/aelfrice/derivation_worker.py — synchronous worker after each batch
• src/aelfrice/replay.py — replay logic
• src/aelfrice/ingest.py — ingest entry points that write to ingest_log
• src/aelfrice/scanner.py — onboard path that calls record_ingest
• tests/replay_soak_runner.py — the harness invoked by the cron
• tests/corpus/replay_soak/** — the v0.1 fixture
• scripts/replay_soak_run.py / scripts/replay_soak_streak.py
• .github/workflows/replay-soak.yml / replay-soak-gate.yml

This PR itself is in scope (it edits replay-soak-gate.yml), so the gate fires on it — and currently the streak is 0 so the check fails. That is fine: the failure is advisory, not blocking, since the check is not in required_status_checks.

Residual risk

Additive edits to store.py / models.py that do affect the derivation contract aren't soak-gated by this filter. Mitigations:

1. The regular pytest matrix runs replay_full_equality tests on every PR via the replay_full_equality probe shipped at v1.6.0 ([v2.x] Implement replay_full_equality — flip-readiness probe #262 / feat: replay_full_equality probe — flip-readiness gate for #262 #304). That catches schema and write-path drift before merge.
2. The daily cron on main appends a new entry every 04:00 UTC. Drift introduced by a store.py change surfaces within 24h on the next entry; subsequent PRs see streak reset to 0.

If a particular store.py PR is high-risk for derivation drift (e.g. record_ingest rewrite), the operator can manually invoke the gate by pushing a no-op edit to one of the in-scope files alongside the change.

Out of scope

• The Replay Soak cron workflow itself — keep firing daily on main regardless of touched paths; the cron is the source of streak truth.
• Lowering the 7d threshold — separate question; this PR doesn't touch the threshold.
• Adding the gate to required_status_checks — explicitly deferred per replay-soak-gate.yml docstring ("admin step, separate from this PR"). Not relevant until the threshold is operationally satisfiable.

Test plan

• YAML syntax-checked locally — yaml.safe_load parses cleanly.
• Conventional-commits prefix (ci:) — passes the commit-msg-prefix check.
• Commit SSH-signed (git log --format=%G? → G).
• Once merged: verify the gate stops appearing on PR pages of out-of-scope PRs (docs(readme): v1.7 row → shipped (BM25F default-on; others opt-in) per #154 #426, feat(bm25): Porter stemming on the BM25F lane (#154) #428, feat(edge_rerank): edge-type-keyed rerank consumer (#421) #429, feat(retrieval): flip use_bm25f_anchors default-on at v1.7.0 (#154) #430, feat(retrieval): semantic contradiction detector v3 — typed-slot value-comparison gate (#422) #431, feat(upgrade UX): #427 — banner reword, /aelf:upgrade-cmd rename, deprecated CLI alias #432).

Refs

• Workflow shipped at [v2.x] Tighten replay-soak gate — operationalize #262's '≥1 week green' as actual CI probe #403 deliverable C (commit 94ac68a).
• Gate's stated intent: [v2.x] Derivation worker — beliefs become materialized state #264 (derivation worker) — not all merges.

Summary by Sourcery

CI:

• Restrict the replay-soak-gate workflow trigger to specific derivation, ingest, replay, soak fixture, runner scripts, and workflow paths so the gate only runs on relevant PRs.

Summary by CodeRabbit

• Chores
  • Updated the Replay Soak Gate testing workflow to include more targeted execution configuration for pull requests targeting main.

[sourcery-ai]

Reviewer's Guide

Scopes the Replay Soak Gate GitHub Actions workflow so it only runs for pull requests that touch the derivation-contract / soak-related paths, and documents the new path scope and residual risk in the workflow header comments.

Sequence diagram for conditional triggering of Replay Soak Gate on PRs

sequenceDiagram
  actor Developer
  participant GitHub
  participant ReplaySoakGateWorkflow as Replay_Soak_Gate_workflow

  Developer->>GitHub: open or update pull request to main
  GitHub->>GitHub: check changed_paths against configured_paths
  alt any changed_path in derivation_contract_or_soak_paths
    GitHub->>ReplaySoakGateWorkflow: dispatch pull_request event
    ReplaySoakGateWorkflow->>ReplaySoakGateWorkflow: run gate jobs
    ReplaySoakGateWorkflow->>GitHub: report consecutive_green_status
  else no changed_path in derivation_contract_or_soak_paths
    GitHub->>Developer: do not show Replay Soak Gate check on PR
  end

Loading

File-Level Changes

Change	Details	Files
Restrict the Replay Soak Gate workflow to only fire on PRs that touch derivation-contract or soak-related files via a pull_request.paths filter and document the scope and residual risk in comments.	Expanded the workflow header comment to describe the path scope, list examples of out-of-scope PR categories, and call out residual risk around store.py/models.py affecting the derivation contract. Added a paths: block under the pull_request trigger so the workflow only runs when changes affect specific derivation, replay, ingest, scanner, soak runner/fixture, soak scripts, or soak workflow files. Kept existing trigger types (opened, synchronize, reopened) and permissions configuration unchanged while adding the path filter.	.github/workflows/replay-soak-gate.yml

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[coderabbitai]

Warning

Rate limit exceeded

@robotrocketscience has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 54 minutes and 26 seconds before requesting another review.

To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 053e25fd-2100-4a70-854d-e7b4061a5737

📥 Commits

Reviewing files that changed from the base of the PR and between 8dc6517 and 3be58be.

📒 Files selected for processing (1)

• .github/workflows/replay-soak-gate.yml

📝 Walkthrough

Walkthrough

The replay-soak-gate workflow trigger is configured to run only for PRs targeting main that modify derivation contracts, replay/ingest/scanner components, soak runner scripts, relevant tests, or the soak workflows themselves.

Changes

Replay Soak Gate Trigger Configuration

Layer / File(s)	Summary
Workflow Trigger & Documentation .github/workflows/replay-soak-gate.yml	Pull request trigger now includes a paths allowlist to restrict the gate job to PRs affecting derivation contract files, replay/ingest/scanner components, soak runner/streak scripts, relevant tests, and soak workflows. Inline comments are added to document scope boundaries.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~5 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately reflects the main change: adding path filtering to the replay-soak-gate workflow to scope it to #264-touching files only.
Description check	✅ Passed	The description comprehensively covers all required sections: detailed summary, rationale, specific path scope with file listings, residual risk analysis, out-of-scope items, and test plan with verification steps.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch ci/issue-403-soak-gate-paths-filter

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[github-actions]

This PR is now behind main. Rebase locally so your commit signatures stay intact:

git fetch origin && git checkout 'ci/issue-403-soak-gate-paths-filter' && git rebase origin/main
# resolve conflicts if any, then
git push --force-with-lease

Auto-rebase was removed because the bot has no signing key; rebasing as the bot strips author signatures and the required_signatures rule on main then blocks the merge. See #341.

[yoshi280]

[claim:review:Toug:2026-05-05T17:23:55Z]

[yoshi280]

[release:review:Toug:2026-05-05T17:32:33Z]