infra(freshness-gate): CI gates for generated artifacts (copy-docs + openapi.json + types.ts)

[SoundMindsAI]

Summary

Ships infra_generated_artifact_freshness_gate end-to-end (both phases together). CI now catches every "developer edits a source file but forgets to regenerate the committed artifact built from it" failure mode for the three generated surfaces in the repo:

• docs/08_guides/*.md → ui/public/docs/*.md (Phase 1)
• backend FastAPI route table → ui/openapi.json (Phase 2)
• ui/openapi.json → ui/src/lib/types.ts (Phase 2)

The single canonical fix command for all three: bash scripts/regen-generated-artifacts.sh.

Spec: feature_spec.md. Plan: implementation_plan.md. The standalone Phase-2 record at 02_mvp2/infra_openapi_types_freshness_gate/ is retired at finalization since both phases ship together.

Phase 1 — copy-docs freshness gate (Stories 1.1 + 1.2)

• ui/scripts/copy-docs.mjs refactored to export DOCS, pruneStale, getDestDir, runCopyDocs + added an ESM entry-point guard so importing the module is a no-op. Adds an FR-9 prune step that deletes any *.md in ui/public/docs/ outside {README.md} ∪ {DOCS[].dest} — a renamed entry never leaves a stale public copy behind.
• .github/workflows/copy-docs-freshness.yml (new) — runs on every PR with NO paths-ignore filter (FR-3 escape from pr.yml's docs/** filter, mirroring secrets-defense.yml's own-workflow precedent) so docs-only PRs still get the check.
• scripts/ci/verify_copy_docs_fresh.sh + test_verify_copy_docs_fresh.sh — bash guard + self-test (clean / source-drift / untracked AC-9 cases against disposable mktemp git fixtures).

Phase 2 — OpenAPI export + types gate (Stories 2.1 / 2.2 / 2.3 / 2.4)

• backend/app/openapi_export.py (new) — offline deterministic CLI exporter. Module docstring records the FR-4 import-graph spike resolution (path (a) — *_FILE dummy stand-ins). build_openapi() + serialize(sort_keys=True, compact, ensure_ascii=False, trailing newline). The unit test runs against a deliberately non-resolvable REDIS_URL host to prove no live clients are instantiated at import or app.openapi() time.
• ui/openapi.json (new, 149KB, 52 paths) — canonical snapshot, byte-stable across runs.
• ui/scripts/gen-types.mjs — refactored to use the lockfile-pinned node_modules/.bin/openapi-typescript (no npx fallback, fails loudly if pnpm install was skipped) + imports a buildBanner() from the new pure module ui/scripts/gen-types-banner.mjs (the banner names the COMMITTED snapshot path, not the live OPENAPI_URL, so a local-dev regen + a CI-snapshot regen produce byte-identical banners — FR-5 source-invariance). ESM entry-point guard added.
• .github/workflows/pr.yml — new generated-artifacts-fresh job mirroring license-inventory's shape (uv + Python + pnpm + node). Runs the snapshot guard, the types guard, AND an AC-7 clean-tree determinism step that calls the real scripts/regen-generated-artifacts.sh end-to-end and asserts the working tree stays clean (catches a regenerator that is itself non-deterministic across runs).
• scripts/regen-generated-artifacts.sh (new) — one-paste chained fix for all three artifacts. Respects REGEN_NO_STAGE=1 so the CI determinism step can inspect the working tree directly.
• ui/.prettierignore (new) — generated files are NOT prettier-formatted. src/lib/types.ts + public/docs/*.md are listed: the generator is the source of truth, and reformatting them would make the gates flap between local-prettier-formatted bytes and CI-canonical openapi-typescript bytes.

Tangential inline fix (per CLAUDE.md tangential-discoveries rule)

• ui/src/__tests__/components/studies/studies-table-ceiling-badge.test.tsx — fixture omitted trial_count, which the backend marks required (int = 0 at backend/app/api/v1/schemas.py:902, shipped with PR docs(research): complementary-architecture one-pager (three-layer handoff) #421). The freshness-gate regen of types.ts surfaced the pre-existing schema/test drift. One-line fix (trial_count: 0) with the rationale documented in a block comment.

Test coverage

48 new test cases total:

Layer	File	Cases
Backend unit	backend/tests/unit/test_openapi_export.py	10
UI vitest	ui/src/__tests__/scripts/copy-docs.prune.test.ts	11
UI vitest	ui/src/__tests__/scripts/gen-types-banner.test.ts	6
Shell guard self-test	scripts/ci/test_verify_copy_docs_fresh.sh	7
Shell guard self-test	scripts/ci/test_verify_openapi_snapshot_fresh.sh	7
Shell guard self-test	scripts/ci/test_verify_types_fresh.sh	7

Plan §3.2 (integration), §3.3 (contract), §3.5 (E2E), §3.6 (migration) are explicitly N/A for this CI-tooling feature.

Cross-model review (so far)

• Epic 1 phase gate (GPT-5.5): 3 findings — 1 accepted-and-fixed (finding chore(pipeline): add project-wide priority-ordered status mode #3, "Three CI gates" wording overstated Phase 1 scope), 2 rejected with cited counter-evidence (docs: reorganize into numbered IA, add pipeline skills and feature templates #1 prune-set-derivation false-read of the code; docs: MVP1 architecture + 12 feature specs + GPT-5.5 review fixes #2 cwd-robustness coverage already complete via two existing tests).
• Epic 2 phase gate (GPT-5.5): 5 findings — all 5 rejected with cited counter-evidence (docs: reorganize into numbered IA, add pipeline skills and feature templates #1+docs: MVP1 architecture + 12 feature specs + GPT-5.5 review fixes #2 false positives caused by the slim diff GPT-5.5 received, in which I excluded the bot-generated openapi.json + types.ts for review clarity — both files ARE in the PR; chore(pipeline): add project-wide priority-ordered status mode #3+infra(foundation): bootstrap MVP1 stack — Docker + FastAPI + /healthz + Alembic + CI (#3) #4 the test override patterns are explicitly plan-authorized in Story 2.2/2.3 plan text + end-to-end coverage exists via the AC-7 clean-tree determinism step; chore(deps): Bump actions/checkout from 4 to 6 #5 the tangential trial_count fix is the textbook inline-fix case per CLAUDE.md).

Test plan

• make test-unit → test_openapi_export.py 10/10 green
• pnpm --dir ui test → 1025/1025 (140 files; baseline was 1019, +6 from buildBanner test)
• bash scripts/ci/test_verify_copy_docs_fresh.sh → 7/7
• bash scripts/ci/test_verify_openapi_snapshot_fresh.sh → 7/7
• bash scripts/ci/test_verify_types_fresh.sh → 7/7
• make lint → 0 errors
• make typecheck → clean
• pnpm --dir ui typecheck → clean
• .venv/bin/ruff format --check backend/ → 565 files clean
• AC-7 clean-tree determinism: REGEN_NO_STAGE=1 bash scripts/regen-generated-artifacts.sh against the committed tree leaves git status --porcelain empty
• Operator-path verification: bash scripts/ci/verify_copy_docs_fresh.sh + verify_openapi_snapshot_fresh.sh + verify_types_fresh.sh all emit "OK: …is fresh."
• CI green on the new generated-artifacts-fresh job + the new copy-docs-freshness workflow

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request implements the infra_generated_artifact_freshness_gate feature, introducing CI freshness gates to ensure committed generated artifacts (OpenAPI snapshot, TypeScript types, and public documentation) do not drift from their sources. It adds an offline OpenAPI schema exporter, verification scripts with self-tests, a unified regeneration script, and refactors existing documentation-copying and type-generation scripts to be deterministic and robust. Feedback on the changes suggests cleaning up temporary directories and files in the OpenAPI exporter to prevent resource leaks, and enabling shell: true on Windows platforms in gen-types.mjs to ensure cross-platform compatibility when executing the pinned binary.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The temporary directory created by tempfile.mkdtemp() is not cleaned up, which can lead to a resource leak over time during repeated executions or test runs. Registering an atexit handler ensures that the directory and its contents are automatically removed when the process exits.

    tmp_dir = Path(tempfile.mkdtemp(prefix="relyloop-openapi-export-"))
    import atexit
    import shutil
    atexit.register(lambda: shutil.rmtree(tmp_dir, ignore_errors=True))
    os.environ.setdefault("RELYLOOP_OPENAPI_EXPORT_TMP", str(tmp_dir))

[gemini-code-assist]

If an exception occurs during the file write or sync operations inside the with block, the temporary file created with delete=False will be leaked on disk. Wrapping the block in a try...finally statement ensures that the temporary file is cleaned up if the atomic replacement fails or is interrupted.

    tmp_path = None
    try:
        with tempfile.NamedTemporaryFile(
            mode="w",
            encoding="utf-8",
            dir=str(path.parent),
            prefix=f".{path.name}.",
            suffix=".tmp",
            delete=False,
        ) as tmp:
            tmp.write(content)
            tmp.flush()
            os.fsync(tmp.fileno())
            tmp_path = Path(tmp.name)
        os.replace(tmp_path, path)
        tmp_path = None
    finally:
        if tmp_path is not None:
            try:
                tmp_path.unlink(missing_ok=True)
            except OSError:
                pass

[gemini-code-assist]

On Windows, executing .cmd or .bat files directly via execFileSync without shell: true will fail with ENOENT or EACCES because Windows cannot natively execute batch files without cmd.exe. Setting shell: process.platform === 'win32' ensures compatibility for Windows developers while preserving shell-free execution on POSIX platforms.

Suggested change

	execFileSync(bin, [SOURCE_URL, '-o', OUTPUT], {
	stdio: 'inherit',
	cwd: UI_ROOT,
	});
	execFileSync(bin, [SOURCE_URL, '-o', OUTPUT], {
	stdio: 'inherit',
	cwd: UI_ROOT,
	shell: process.platform === 'win32',
	});

[SoundMindsAI]

Review adjudication (Gemini Code Assist + GPT-5.5 phase gates)

Commit landing accepted fixes: b0579fb7

Gemini Code Assist (3 findings — all accepted)

#	Sev	Location	Verdict	Notes
1	Medium	backend/app/openapi_export.py:91	Accepted	tempfile.mkdtemp() leaked the dummy-*_FILE tmpdir at every CLI invocation (~100 bytes). Registered atexit cleanup via shutil.rmtree(..., ignore_errors=True). Inline citation in b0579fb7.
2	Medium	backend/app/openapi_export.py:_write_atomic	Accepted	A raise between NamedTemporaryFile(delete=False) write/flush/fsync OR an os.replace failure would leak the .tmp next to the destination. Wrapped in try / finally with tmp_path = None after a successful replace (tells the finally block "the rename took ownership; don't try to delete the now-renamed file") and a best-effort unlink(missing_ok=True) cleanup that never masks the original exception.
3	Medium	ui/scripts/gen-types.mjs:execFileSync	Accepted	Real Windows bug — Node's execFileSync can't invoke .cmd shims without shell: true (cmd.exe is required to interpret batch files; see child_process docs). Gated shell: true to process.platform === 'win32' so POSIX stays shell-free.

GPT-5.5 phase-gate Epic 1 (3 findings)

#	Sev	Verdict	Notes
1	Medium	Rejected	"prune set diverges from planned interface" — ui/scripts/copy-docs.mjs:137 literally reads const expected = new Set(['README.md', ...docs.map((d) => d.dest)]);, exactly per plan's Key Interfaces. copied is a return-value-only array, never feeds the prune set.
2	Medium	Rejected	"cwd-robustness DoD not fully covered" — proven transitively via copy-docs.prune.test.ts:55-65 (getDestDir() cwd-invariance) + copy-docs.prune.test.ts:163-189 (runCopyDocs two-cwd test asserting identical output). Running the unparametrized script in vitest would mutate ui/public/docs/ on every test run (bad hygiene).
3	Low	Accepted	Fixed in f49531f5 — softened "Three CI gates" lede in testing.md to "A family of CI gates" + added explicit Phase 1 / Phase 2 sentence.

GPT-5.5 phase-gate Epic 2 (5 findings — all rejected)

#	Sev	Verdict	Notes
1	High	Rejected (false positive)	"ui/openapi.json not in diff" — IS committed at 1a0151e8 (Story 2.2 a). False positive from the slim diff I sent to GPT-5.5 (I excluded the 149KB bot-generated artifact for review clarity).
2	High	Rejected (false positive)	"types.ts not in diff" — IS committed at 42b0b3b0 (Story 2.3) + re-regenerated at 3da3896e (Story 2.4) to the canonical non-prettier form. Same slim-diff false-positive cause. AC-7 clean-tree check confirms committed bytes match canonical regen output.
3	Medium	Rejected	"types-guard self-test uses an override instead of the real pnpm types:gen" — the TYPES_FRESH_REGEN_SCRIPT override is plan-authorized in Story 2.3 Task 4 ("the guard supports a test-only generator override … fallback"). End-to-end coverage of the real chain exists via the AC-7 clean-tree determinism step in pr.yml (Story 2.4) which runs the real scripts/regen-generated-artifacts.sh on every PR.
4	Medium	Rejected	"snapshot-guard self-test uses an override instead of the real exporter" — same plan authorization (Story 2.2 plan: "fallback: the guard supports a test-only generator override"). End-to-end exporter coverage exists via (a) test_openapi_export.py no-service-containers smoke (10 tests); (b) AC-7 runs the real uv run python -m backend.app.openapi_export on every PR.
5	Low	Rejected	"studies-table-ceiling-badge.test.tsx is unrelated to Epic 2 — split into a separate PR" — per CLAUDE.md "Tangential discoveries — fix inline by default": pre-existing schema/test drift surfaced by this PR's regen of types.ts is the textbook inline-fix case. One-line fix, same subsystem, zero design fork, rationale documented in both the commit body and a code comment. Splitting would violate "One branch per session — don't stack PRs."

Outcomes

• Applied fixes (4): Gemini docs: reorganize into numbered IA, add pipeline skills and feature templates #1, docs: MVP1 architecture + 12 feature specs + GPT-5.5 review fixes #2, chore(pipeline): add project-wide priority-ordered status mode #3 + GPT-5.5 Epic 1 chore(pipeline): add project-wide priority-ordered status mode #3
• Rejected with cited counter-evidence (7): GPT-5.5 Epic 1 docs: reorganize into numbered IA, add pipeline skills and feature templates #1, docs: MVP1 architecture + 12 feature specs + GPT-5.5 review fixes #2 + GPT-5.5 Epic 2 docs: reorganize into numbered IA, add pipeline skills and feature templates #1–chore(deps): Bump actions/checkout from 4 to 6 #5
• Deferred as non-regression follow-ups (0): none

Final cross-model review will follow once CI is green on b0579fb7. Ready for human review + merge after that.

[SoundMindsAI]

Final cross-model review

GPT-5.5 final review against the complete PR diff (vs main) passed clean — 0 findings. The rejection log fed from the Epic 1 + Epic 2 phase-gate adjudications worked as designed; no previously-rejected findings were re-raised and no new ones surfaced.

Waiting on CI green on b0579fb7; then ready for human review + merge.