forgeax-engine-debug
Skill70 starsChanged 18 days agoApache-2.0View on GitHub
ForgeAX troubleshooting router with RHI Debug first for difficult rendering failures. Use when rendering is wrong, CI is slow or flaky, tests fail, asset hot reload fails, or a clean worktree behaves differently.
- Installs packages
In this repository25 other files it gives its agents.
- AGENTS.mdAGENTS.md
- templates/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- forgeax-engine-appSkill
- forgeax-engine-assetsSkill
- forgeax-engine-audioSkill
- forgeax-engine-cliSkill
- forgeax-engine-debug-drawSkill
- forgeax-engine-ecsSkill
- forgeax-engine-evolveSkill
- forgeax-engine-materialSkill
- forgeax-engine-mathSkill
- forgeax-engine-modelingSkill
- forgeax-engine-navigationSkill
- forgeax-engine-performanceSkill
- forgeax-engine-physicsSkill
- forgeax-engine-render-pipelineSkill
- forgeax-engine-rhi-debugSkill
- forgeax-engine-rhiSkill
- forgeax-engine-sdkSkill
- forgeax-engine-shaderSkill
- forgeax-engine-stateSkill
- forgeax-engine-vfxSkill
- forgeax-engine-wechatSkill
- forgeax-scriptable-pack-reviewSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
58 rules. About 0 are common, 40 are distinctive, and 18 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈40
Distinctive · estimate
This author's own choices. Worth a look.
18
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 26
Keep its rule unchanged. Native publication follows strict job failure policy.
- Very specific: line 64
Check its explicit nightly_full_profile input as well as the reused Dawn step: Nightly retains full frames and browser-owned unit …
- Very specific: line 98
Run pnpm check:runtime-boundaries, pnpm test:runtime-boundaries and the dist check after normal package production.
- Distinctive: line 162
If a long exclusive compiler starts near the parent deadline, inspect its admission headroom as well as total weights.
- Distinctive: line 179
Keep local single-job coverage usable: placement cannot move work to a peer job when none exists.
- Distinctive: line 245
When DevKit and Render halves accumulate after Modeling on a cancelled lane, enforce the broad-partition ceiling across projects as well as …
- Distinctive: line 289
Use the same-head CI-profile Linux Focus diagnostic.
- Very specific: line 293
When a material comparison fails late in a native/reference/replay parent, retain its exact failing frame and full case roster.
- Distinctive: line 322
Keep compiler-state call-count cases in their compiler observing realm, apart from unrelated publication state, while preserving all target …
- Distinctive: line 327
Follow the same execution-owner contract above.
- Distinctive: line 339
Follow the CI fixture budgets and native replay owners.
- Distinctive: line 425
Keep quota-derived worker caps and all original acceptance bounds.
- Distinctive: line 466
Keep the 85% floor, inherited costs and retained cases.
- Distinctive: line 542
Check the disjoint App/Bevy source roster and actual metric consumers before adding a cache or scheduler rule.
- Distinctive: line 579
Check new files against the measured cost table: the maximum-file fallback can strand a lane even when the new file itself is short.
- Distinctive: line 590
Check serial Dawn's Mesa worker count against the admitted heavy CPU budget.
- Distinctive: line 604
Check newly discovered files against the same cost table: its largest-file fallback can reserve minutes for a short new test.
- Very specific: line 654
Do not install an extra shell or replace a failed child with an exit-zero receipt.
- Distinctive: line 691
Keep the source-key admission and original timeout.
- Very specific: line 698
If Windows Rapier preparation stalls after compilation, inspect the declaration producer and its exact tsup entry.
- Distinctive: line 716
Keep the actual failed frame and distinguish Browser evidence from diagnostic Dawn replay.
- Distinctive: line 720
If a template smoke inherits on-demand production, inspect its owned Vite child's readiness policy: native imports belong to the existing …
- Distinctive: line 779
When the admitted worker-count policy changes, replace stale placement costs with complete receipts from the current policy.
- Distinctive: line 796
Check the scan's entry set too: declared Runtime Pack secondary exports can introduce dependencies outside App's main graph.
- Distinctive: line 823
Keep initial polling with the World receive system and reproduce delayed Host activation on the real browser path without expanding the …
- Very specific: line 861
If the CI install-entrypoint contract fails, run prepare-pnpm-workspace.mjs before each filtered frozen pnpm install on the same workflow …
- Distinctive: line 878
Keep new-evidence rejection and the complete product checks.
- Distinctive: line 895
Check deletion history and retain the shared budgets and four-job matrices while keeping genuine new feature and lifecycle coverage.
- Very specific: line 902
Use pnpm ci:focus --kind <kind> --select <selector> (also bun fx ci) for source reproduction.
- Distinctive: line 919
Use the CI operating guide.
- Distinctive: line 921
Every matrix stays within four actual jobs, including platform entries.
- Distinctive: line 929
Keep source-run provenance, distinguish amortized group costs from independent file timings, and preserve the coverage threshold without …
- Distinctive: line 949
If a full-lane retry of the same head hits the same deadline, refresh completed file and owner costs before another attempt.
- Distinctive: line 953
When fixed reservations and observed tails diverge, redistribute complete owners within the existing four lanes and let the same sequencer …
- Distinctive: line 972
When a completed file within an interrupted owner already exceeds that owner's reservation, the old forecast is disproven even though no …
- Distinctive: line 984
If a new complete observation exceeds its existing forecast while other lanes finish early, replay the actual current discovery with the …
- Distinctive: line 1015
If a broad DevKit/Render half starts late behind fine-partition waves, admit that complete half first on its job and model the same order …
- Distinctive: line 1018
If repeated within-wave ranks still cluster on a job, spread those cohorts too.
- Distinctive: line 1019
Place each complete fine wave atomically across the same four jobs to avoid a greedy dead end.
- Distinctive: line 1021
Keep complete-child observations and retained maxima in the coverage child-cost ledger.
- Distinctive: line 1026
When splitting a complete long project into native partitions, keep those halves on different jobs through both initial placement and …
- Distinctive: line 1049
Keep the seeds, events, pixel checks and real replay falsifiers.
- Distinctive: line 1074
Keep cube-face completion, recovery windows and every pixel/replay falsifier.
- Very specific: line 1078
Remove report-only GPU benchmarks without a cost bound.
- Very specific: line 1092
Read the failed head's logs and separate preparation, execution, teardown and transport.
- Distinctive: line 1112
Keep local/current-job locks and the foreign-Git-directory rejection intact.
- Very specific: line 1128
Keep native preparation off the successful restoration path.
- Very specific: line 1133
If Getting action download info stalls before a composite starts, its unused cold-path actions can still be the cause.
- Very specific: line 1159
Use --filter-prod for both positive and negative selectors.
- Very specific: line 1178
Never derive shard membership from a particular Runner's quota.
- Distinctive: line 1219
If standalone SSAO or Vite manifest assertions recompile the full fleet, inspect that preparation before changing their assertions.
- Very specific: line 1246
If an adopted Play is hidden before its document arrives, inspect presentation CSS: Chromium suspends native iframe rAF under …
- Distinctive: line 1252
Keep four shards and complete JS/TS publication chains.
- Distinctive: line 1259
After deliberate View target retirement, assert the lost state and use guarded workspace reopen before mounting Scene on the new target.
- Very specific: line 1317
If a replay passes its pixel assertions but crashes during native shutdown, trace the bootstrapDawn disposal lease through every caller.
- Very specific: line 1342
Check captured dimensions when a scene omits quality fields: shared test reduction must also bound engine defaults.
- Very specific: line 1356
If identical work is much slower in a full shard than in Focus, compare runner-cpu-pressure counter deltas and the distinct container/host …
- Very specific: line 1384
Run python3 scripts/forgeax/check-agent-docs-english.py after changing agent instructions.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
forgeax-engine-debug
For green main pushes with skipped runtime owners, inspect post-merge qualification. Reuse requires identical Git trees and the latest matching PR CI success; unchanged main alone is insufficient after an early admin merge. Pending/failed/cancelled runs and missing API evidence retain full CI. Follow post-merge qualification reuse.
For failed PR matrices, inspect the first failed child before cancelled siblings.
PR matrices release their remaining runner capacity on failure; push/manual
runs retain complete diagnostic results. Interrupted owners provide no timing
samples. Recover the original owner with ci:focus, then complete the full
workflow including all cancelled siblings before qualification. See
failed PR matrix admission.
For a primary manual-override stance failure, inspect the named workflow field
and run node apps/hello/triangle/scripts/ac-08-grep-gate.mjs on the exact source.
Keep its rule unchanged. Native publication follows strict job failure policy;
core preflight rejects policy drift before expensive preparation and matrices.
For Rapier setup cache ECONNRESET followed by source rebuilding, use the
source-keyed release fallback before optional cache transfer. The unchanged
producer owns both dimension keys and final byte/inventory verification. For a
Linux inventory mismatch after Mac packaging, inspect the archive's AppleDouble
members and regenerate it without host metadata; never relax the inventory. Keep
rollback, locked source fallback and all runtime/sixty-frame owners; follow
CI input recovery.
For FBX/Basis setup delayed by optional cache, use the shared preparation owner in main, Focus and SDK. Release readiness precedes cache admission; strict complete-file checks retain the locked source fallback. Preserve the real FBX parse, Basis encode/transcode and all runtime owners. Follow CI input recovery.
For UI Blitz or wgpu-wasm setup delayed by optional cache transport, verify the current local/release payload before cache admission. Preserve source/byte verification, source-keyed cache fallback and the locked native build. Follow CI input recovery.
For Candidate checkout Unable to replace auth placeholder in .git/config,
inspect standalone View and Modeling Git directories before recursive checkout;
follow Modeling source preparation.
For public-source export-source-missing naming packages/modeling, prepare
that exact gitlink in the screening checkout before export; follow Modeling
source preparation.
Package READMEs and AGENTS.md own design contracts. Diagnose current source and actual failure evidence; historical lane numbers and old run narratives are not operating instructions.
For Nightly coverage cancellation at the job deadline after successful Dawn,
follow Nightly Linux ownership.
Linux calls the same-commit full CI graph, including four coverage shards and
the global threshold aggregate; do not restore a serial unsharded fallback.
Check its explicit nightly_full_profile input as well as the reused Dawn
step: Nightly retains full frames and browser-owned unit workloads, while
PR/main keep their bounded profile. Consistency gates follow that call edge.
Preserve hosted probes, Metal and every acceptance bound. Timeout cancellation
must remain visible in tracking issues; only a complete Nightly run qualifies it.
For a capture-timing integration failure comparing hot and cold wall times, inspect the phase report contract and actual rebuild parameter trace. A warm Worker can legitimately take longer. Retain measured durations, environment identity and the separate performance tier gates; follow coverage execution.
For long collision scans, profile the complete owner and check nearest-triangle query work while retaining the full motion report and negative controls. Follow CPU preparation.
For runner communication loss, join command-window memory PSI and raw cgroup OOM event deltas by kernel fingerprint before assigning a cause. Historical OOM totals and later host pressure do not establish an incident-time kill; preserve the failed run and every interrupted child's qualification boundary.
For slow Pack checks, time the complete original builds and their actual operation journals before editing. Reject strictly disjoint bounds before exact geometry predicates while preserving closed contacts, error order and complete output bytes. Falsify sampled function attribution with phase timing, then compare matched ordinary windows; profiling is not a throughput result.
For slow native case tests, separate material/source production and Catalog adoption from actual draw/readback. A backend-specific fixture target needs portable-producer parity and complete native pixel controls. Keep fresh consumer state and original frames, assertions and bounds; phase timing is diagnosis.
For runtime-tool-*, runtime-host-* or runtime-test-export, fix
the named owner using the runtime boundary contracts.
Run pnpm check:runtime-boundaries, pnpm test:runtime-boundaries and the dist
check after normal package production. Do not hide a runtime dependency with
a consumer define, development-mode fallback or violation baseline.
For cube/plane contact-matrix timeouts, run the Forward and Deferred Browser owners separately; each retains all 36 cases, its cold renderer and original frame/pixel/deadline bounds. A buffered log ending at dependency scanning does not establish a scanner stall. Inspect completed case timings or capture live process/page evidence before assigning the cause; follow Browser gates.
For a workflow stance failure, fix the named job configuration. Auxiliary publication must report its own verification and publication failures; bounded optional transport steps do not authorize a job-level override.
For an instrumented coverage child failure, use ci:focus --kind coverage
with its exact maintained child label or isolated file. Keep all cases and V8
instrumentation; ordinary unit success is insufficient. The four-shard merge
still owns full-roster thresholds and final-head acceptance. Prepare the pinned
real asset checkout before full local coverage. For same-size watcher fixture
failures, inspect stat timestamps; establish a distinct initial fixture timestamp
before observing instead of adding sleeps or extending deadlines.
For repeated whole-job timeouts with uneven completed child loads, retain complete observations as distinct run scenarios instead of replacing the prior cohort with a partial or unusually fast sample. Compare every retained replay, keep larger reservation bounds, full process overhead and interrupted-owner forecasts, and move only whole children/files. Use a completed compiler cost only in its matching scenario. Do not add an all-run-maxima capacity constraint that excludes placements satisfying the actual scenarios; retain their execution windows and original job deadlines. Bound each job to at most one child above its even roster share, so optimistic estimates cannot collect a long serial tail on one runner. Complete all four local V8 shards and their threshold merge before pushing a replacement after a repeated coverage-parent timeout. Follow complete-run placement scenarios. For native single-receiver direct-light deadlines, capture the full RHI interval before changing its optional occlusion profile. Shadow/clearcoat fixtures keep their default occlusion path; preserve all HDR/reference/shadow assertions and 24/60 completed frames. Focused Linux success still requires final-head CI.
For a Three material-output first-completion timeout, retain its failed RHI tape
and inspect the actual fragment entry and View slot. A fog-free view must carry
its admitted viewFog fact through both hidden preparation and visible recording
to select the existing unfogged entry. Keep active analytic fog and finite
atmosphere on their composition paths, unknown helper contexts conservative,
all cases, sixty-frame windows, pixels, fresh replay devices and deadlines.
For View tape replay losing its browser Instance, keep the captured tape, failing
page and device-loss facts. Compare the shared software launch with Vitest's
watchdog policy and inspect retained pw:browser stderr before naming a native
crash cause. A shortened watchdog diagnostic is a controlled falsifier, not proof
of the original runner's exit. Re-run the unchanged real tape and complete View
diagnostics with sandboxing and all replay/pixel/frame deadlines intact.
For coverage parent cancellation with idle peer jobs, inspect cross-project
partition placement as well as sibling separation. Broad project halves must
span the existing jobs together; retain whole children, all instrumented files,
coverage thresholds and original deadlines. Only complete child receipts update
timing measurements; a cancelled child's elapsed window is not a sample.
Stamp each completed observation with its run. A partial timing-table refresh
must not optimize against older peer samples: retain their larger forecasts
until complete observations from the current run are available.
A complete refresh stamps every current row. Test stale-sample handling with
an explicit partial receipt rather than a mutable entry in the live table.
If a long exclusive compiler starts near the parent deadline, inspect its
admission headroom as well as total weights. Spread cost-ranked fine-partition
waves while the longest fifteen-minute exclusive forecast reserves its job
before placement and keeps other exclusive owners off its serial tail. A fine-
partition quota alone can move the bottleneck into ordinary project backfill.
Raise each complete partition forecast independently, retaining larger inherited
reservations. Preserve broad-half separation, complete roster membership and
every original deadline. Replays
guide placement; only complete final-head CI qualifies it.
Refresh complete-child observations from every successful child of the same
four-job run, including current groups without earlier samples. Keep larger
reservedSeconds and source forecasts while recording the latest observation
separately. A tighter replay bound does not certify the job's execution target;
include setup, transfer and cleanup in final-head acceptance.
Freeze completed receipts in replay regressions, so a live timing-table refresh
cannot replace the failure oracle. An interrupted compiler supplies no sample;
retain its source forecast and all original job, file and assertion bounds.
Keep local single-job coverage usable: placement cannot move work to a peer job
when none exists; its execution barriers still serialize every exclusive owner.
For dual-host Standard parity capture preparation deadlines, keep its complete
pixel/compositor/falsifier owner in the existing short-bootstrap exclusive lane.
Initialize the hosts concurrently, then complete their cold scene pictures in
sequence so a peer's real GPU frame cannot retain a pending preparation barrier.
Preserve both hosts, the 15-second ready-frame bound and the 90-second case bound;
qualify the same-head Linux owner and the full Browser roster.
For its single-cube lighting benchmark, keep optional GPU occlusion disabled
while retaining GPU visibility and indirect draws. The Browser owner also
enables default occlusion on both devices and requires byte-identical pictures;
retain that control, light restoration and the 30-second benchmark startup bound.
For apparently empty GBuffer work, inspect the selected material pass as well
as published WGSL entries. fs_gbuffer in a Forward module does not certify a
GBuffer draw. Only complete current-device contributor proof may omit lighting;
retain attachment loads/clears and full SceneData rejection for missing coverage.
For Three texture/flat-shading deadlines with repeated reference device creation, use the maintained upstream reference fixture: a fresh Renderer/node cache per comparison on its independent file-owned device. Preserve all nine fresh replay devices, original pixels and frames. Keep each flat-shading material in its own 120-second Browser and Dawn case so all three complete material matrices remain within their individual deadlines; the Browser work guard enforces eleven device requests. Follow the CI fixture budgets.
For independent-view readiness or Three texture/flat-shading deadlines beside another native/replay owner, reproduce the complete file with the same-head CI-profile Linux Focus diagnostic. These owners drain competing Browser groups through existing exclusive admission. Preserve all cases and original bounds; local hardware and focused passes do not qualify full-shard CI. Follow the Browser gates.
For Standard material first-submit timeouts, capture the actual frame before changing shaders. Separate cold submission from warm replay and inspect the selected fragment Surface discard override. Direct draws use the shared mask with GPU LOD coverage absent and camera clipping preserved; programs without the declaration keep their original constants. Retain clipping pixel controls, sixty completed frames and original bounds. Qualify the complete Linux CI-profile file and full Browser gate; local replay timing alone is insufficient.
For IES Browser process deadlines, inspect retained case screenshots before assigning a startup stall. Ordinary and publication owners run separately with all four cases, 19 independent live/replay devices, original deadlines and exclusive admission. Follow the Browser gates.
For native or coverage parent timeouts after successful children, compare all four ordinary Dawn ledgers or all sixteen Modeling partitions before changing placement. Completed children retain their full file costs even when a later GI owner reaches the parent deadline; exclude interrupted owners. Rotate the latest complete snapshot into the previous slot when admitting a new window. Freeze outgoing replay fixtures so timing refreshes cannot erase the failure oracle. Retain larger costs, complete owners, four jobs and original deadlines. Follow the Dawn placement ledger and coverage execution owners below.
For a coverage lane stranded behind isolated source production, compare its ordinary project forecast with the actual excluded files. Charge the moved source work once, retain completed child evidence and keep all coverage owners and deadlines; follow coverage execution. For Modeling coverage overruns, refresh all completed partition file ledgers, including process overhead. Derive placement reservations from that same ledger after excluding separately owned and performance-only files; retain larger observed file costs and every partition. Spread each consecutive set of four Modeling partitions across the four jobs; an equal per-partition forecast must not cluster similarly ranked costly files. When DevKit and Render halves accumulate after Modeling on a cancelled lane, enforce the broad-partition ceiling across projects as well as within each project. Use completed slow-lane samples; equal CPU quotas do not establish equal elapsed time. Keep the original job bound and qualify final-head CI.
For a coverage job deadline after uneven Modeling partitions, refresh file costs from complete successful child receipts, including skipped-file overhead, and derive partition reservations from the same retained table. Preserve every file, exclusive owner and deadline; a planning replay still requires final-head CI.
For live-daemon recovery or ordinary App Worker build timeouts under coverage, qualify the complete files in exclusive CPU children before changing deadlines. Preserve HTTP recovery, module identity and graphics falsifiers; nested native cases retain their own GPU admission. Follow the coverage execution owners.
For Vite shader coverage stalled in full source production, retain the resampling, Surface ABI and direct DFG files in the existing exclusive source owner. Publication checks inherit the runner compiler budget; call-count and mock-bound checks retain their observing realm. See the execution-owner contract above. Three Browser readiness failures retain native tapes through the failure artifact selector; verify uploaded bytes before claiming the failed frame is available. CI Focus retains the same Three/IES tape and pixel roots. Full and focused uploads derive literal source/test directories from tracked owners before globbing; a dependency exclusion or wildcard package depth cannot bound traversal. A timed-out optional upload leaves frame evidence missing; keep the originating failure and recover an actual capture before shader edits. Synthetic native recording contexts must carry the required camera snapshot, even when their witness shader does not consume View uniforms. Use the existing frame-snapshot producer; preserve native depth, material Pass and clipping assertions.
For Bevy completed-frame smoke failures, distinguish preparation receipts, the first ready GPU completion and later ready frames. Cold native pipeline work has a bounded first-ready allowance inside the unchanged total completed-frame budget; pending and steady receipts retain their tighter bound. Verify stalled cold/steady receipts still fail and count only completed ready frames.
For a native job cancellation, inspect the actual test-step verdict and setup cost before changing test membership or timing forecasts. Optional artifact transport loss can trigger a complete source rebuild. Dawn keeps a 40-minute test-step limit and a 50-minute job bound for setup/cleanup; the total 30-minute CI target is separate and must not be reported as achieved by extending a bound.
For a Browser command stall before Vitest prints RUN, inspect the
browser-startup owner/phase/heap observation before assigning a Renderer cause.
Use the same-head CI-profile Linux Focus diagnostic; preserve the original
failure when it does not reproduce. A focused pass is not complete PR CI and
is not evidence that the failure was an external transport error.
When a material comparison fails late in a native/reference/replay parent, retain its exact failing frame and full case roster. Bound the process lifetime with complete case partitions, preserving pixel controls, fresh replay devices, all sixty frames and the original readiness/case/process deadlines. A local Focus pass alone neither diagnoses transport nor qualifies the new ownership. For the directional Three shadow owner, keep the baseline, authored-filter and layer/variance phases sequential in one renderer so the sixty-frame warmup and fresh replay roster remain shared while each phase retains the original case deadline.
For a cold Preview template Catalog stall, separate source cooking from browser readiness using its named preparation timings. Long watcher-snapshot diagnostics belong to Vite Pack's revision observer. Its bounded path inspections retain every root, the construction baseline and drain/close freshness fences. The maintained Catalog-startup option is independently bounded at 180 seconds; if a CI caller uses it instead of the 90-second default, record that preparation allowance explicitly. Do not change or relabel the browser/GPU/case/job bounds or claim a runtime speedup.
For sky/IBL preparation deadlines inside a long native test parent, inspect the named resource and qualify the complete consumer in a fresh native lifetime. Preserve cue/pixel controls, completed frames and readiness budgets. Balance fixed native reservations before ordinary backfill; include complete process overhead and retain larger forecasts when updating timing inputs. A balanced native reservation does not compensate for stale ordinary-file costs: compare all four completed ordinary children and refresh their full file ledgers before repartitioning. Keep the original job deadline and all discovered files. Admit reserved complete capture journeys before their ordinary backfill; keep original case deadlines, pixel controls and all sixty frames. An interrupted capture is not a timing sample. Keep compiler-state call-count cases in their compiler observing realm, apart from unrelated publication state, while preserving all target contexts and artifact equality. If independent schema transitions overload one case, keep them as sequential falsifiers in the same cooker and verify the cached Standard return after each; preserve the full portable matrix and per-case budget. Follow the same execution-owner contract above.
For production CSP fixture timeouts, distinguish Worker initialization from Preview teardown. Close the Vite Preview owner so unfinished HTTP connections cannot retain the fixture. Keep both real inline/external WASM cases and their deadlines; qualify the actual unfinished-request cleanup budget in the existing CI contract job before rerunning the complete Browser gate.
For Browser/Dawn fixture overhead, audit both reachable source graphs, including conditional shadow flags. Inspect actual shadow resources and replay queue work before reducing a fixture. Keep performance/precision profiles, independent publication and falsifier devices, selected-work provenance and every frame. Follow the CI fixture budgets and native replay owners.
For an independent-run SDK UI color mismatch, inspect the retained PNG and the status footer at the actual CI viewport before assigning a Renderer cause. A full version can wrap into an authored UI color oracle. Preserve exact color and solid-patch assertions while reserving the fixture's minimum UI height; follow SDK consumers.
For instrumented global-probe partial-write recovery timeouts, keep the complete
file in the existing exclusive GI coverage child rather than competing with broad
DevKit coverage. For a Dawn lane cancellation, compare completed ordinary children
and complete native-owner costs across all four lanes before adjusting owner
reservations. Preserve cases, pixels and original deadlines. Interrupted or
cancelled owners supply no completion sample; include skipped files in their
completed ordinary child's process overhead. Follow
GI coverage and material publication.
An interrupted later owner does not invalidate an earlier successful ordinary
child. Refresh its measured file costs in scripts/ci/dawn-file-seconds.json
while retaining larger inherited forecasts and the complete native roster.
For large GPU snapshot or reference-oracle costs, inspect actual matcher traversal before changing native work. Follow native payload and startup work; keep full payload equality, provenance and independent negative controls. A byte work-budget failure requires fixing the oracle, not exempting the test.
For tape transport costs, separate lossless gzip work from GPU execution. RHI Debug selects native zlib only in Node and keeps its portable browser/Worker codec through a package condition. Qualify real codec-call budgets, complete cross-codec bytes, corrupt-input failures and browser packaging before full Dawn timing; retain every capture, replay and digest check.
For wire interning costs, inspect the actual artifact byte path in Pack's codec. Preserve complete bytes, ordinary metadata and publication identities through the shared program contract.
For slow material-publication fixtures, retain validated artifact byte views until
the real publication digest and wire encoding; apply the existing Pack numeric
projection once before native JSON encoding. Storage WebGPU-only fixtures can
declare the qualified cooker target; GI/ray requires webgpu-storage-ray to
retain both ray-hit and Card programs. Keep actual output-context work guards,
full compiler byte parity and portable/constrained/fallback coverage; see
material fixture production.
A preliminary JSON roundtrip makes the publication digest traverse every byte
as an ordinary numeric array. Preserve the real source/decode/adopt path and its
artifact-integrity checks.
For material-parity timeouts, inspect binary comparison overhead before changing compiler concurrency or deadlines. Keep exact byte and metadata equality, concurrent cooks, diagnostics and crash recovery.
For Modeling Dawn collection or stale-frame guards, retain the self-contained default TG scene and the native validation/recovery falsifier; an external TG_CASE_DIR is optional. After shader template edits, keep the probe SH work test on the actual production preblend block, regardless of let/var spelling. See Modeling admission.
For a Modeling R-internal-C failure, rename the marked internal member and its typed callers in the kernel owner, run the complete candidate gate, merge the kernel PR, then bump the Engine pin. Preserve the naming gate; source preparation describes candidate admission.
For a Modeling coverage long tail, check the eight native project partitions across four jobs and their exact manifest membership. Preserve every test, aggregate threshold and deadline. For C-410 region-query timeouts, retain the complete brute-force connectivity oracle and original geometry falsifiers. For S7 playback timeouts, profile label inspection and preserve the complete animation case and its 600-second bound. For capture heap mismatches, verify the budgeted Node host: inherited V8 flags override Worker resource limits. See coverage execution.
For declared-material publication timeouts in an already exclusive coverage child, check whether a file-wide spy setting disabled the normal Node material Worker route. Only Naga call-count cases need the observing realm. Keep every authored material, real cook, publication assertion and original deadline; see the coverage guide.
For absolute Modeling tier failures, record the failed clock, case and runner class before changing execution placement. Use the nominal heavy CPU pool for that uninstrumented owner; keep every runtime/offline case, sample, attempt and budget. Cross-host timing is diagnostic, never an algorithm speedup or a reason to retry a failed measurement. See the tier contract.
For a first-picture preparation timeout, correlate the pending receipt with native pipeline requests and queue completion. A pending reason names that receipt's first blocker, not necessarily the longest later operation. Keep the shared ready-frame driver at frame cadence rather than flooding the GPU queue; retain its readiness bound and every required completed picture. Dense IES capture/replay uses the existing exclusive Browser admission route, with its complete file and original deadlines.
For an SDK source job that finishes its consumers but expires in its integrity
tail, inspect verifySdkArtifactInventory and verifyImmutableSdkStore. Reuse
the SDK's bounded file-I/O owner, reread all current bytes, and preserve the
SQLite-only mutable-store exception. See the consumer contract.
For concurrent CI slowdowns, compare the affinity receipts' kernel fingerprints, CPU masks and execution intervals. Equal masks alone do not prove a shared host. Quota-only containers must retain kernel placement when their available physical core set exceeds their CPU budget; a runner-name hash cannot reserve host cores. Keep quota-derived worker caps and all original acceptance bounds. See the runner resource contract.
For Bun portability source-scan timeouts, compare visible CPUs with the admitted
cgroup CPU/memory budget and actual concurrent scan owners. The complete
Math/ECS canary uses one Vitest worker through the existing runner CPU-affinity
owner: an admitted six-worker CPU quota still let live-tree reads contend in
run 41572730945. Preserve every case, source-scan negative control, type check
and original deadline; a local serial pass is not Linux runner acceptance. See the
CI recovery route.
For SDK bootstrap or publication failures, compare the actual Node, npm and pnpm
versions with .nvmrc, .npm-version and .pnpm-version in the
CI guide. PR, Candidate and Promotion use the same
toolchain. Repair the owning operation while retaining sealed source, version
and immutable package bytes.
For cookbook missing-export diagnostics, repair the independently owned Harness recipes and compile the full cookbook against the current Engine. Then update the explicit Preflight documentation pin through the input contract.
For a Pack draft that retains a source-declaration error after repair, compare the source digest with the draft revision. Explicit reopen uses Pack's serialized source refresh and preserves edits; verify the native authoring recovery gate before changing View waits or runtime parameter controls.
For Render's No test suite found on managed-asset benchmark .test.mjs files,
run their native node:test owner in primary-pnpm; the Render Vitest project
must retain its source tests and exclude only those benchmark contracts.
See CI reproduction.
For an empty-frame smoke result, compare the sampled coordinates with the full GPU readback before assigning a Renderer fault. A visible subject can lie outside two background probes. Keep the actual pixel threshold and lifecycle controls. Full local Smoke also needs the selected fixture producers; follow CI reproduction for the LOD input directory.
For native UI control failures, inspect the paired snapshots in artifacts/ui-*/ before assigning a layout cause. Verify the UI WASM provenance and browser version, and use the Host platform's native edit modifier. Reproduce the exact file through CI Focus Browser with the ci profile; preserve geometry, pixel and lifecycle assertions. See failure recovery.
For a Browser measured-roster coverage failure, refresh missing file costs from completed successful exact-child observations through Browser gates. Keep the 85% floor, inherited costs and retained cases; skipped or interrupted work does not establish a measured cost.
For opposite native-UI geometry failures on different runners, compare their actual Chrome versions before changing the portable owner again. Host reuse and cached installation must both satisfy the existing Browser version policy. Preserve the original native assertions; repair stale toolchain admission rather than alternating implementations or retrying until a compatible runner is selected.
For a Worker-policy browser failure at replacement-epoch, preserve the execution report and reproduce real termination. Check render-credit waiting before changing the source frame deadline; retain stale/duplicate phase fencing and the real recovery assertions. Follow split Worker admission recovery.
For Dawn native-lane cancellations, preserve the original job and recover its
unfinished complete owner through ci:focus. Placement may use only complete
successful child receipts, with skipped-file overhead included and larger inherited
forecasts retained. Keep all four lanes, native lifetimes and deadlines; follow
complete-owner placement before another full CI run.
For Three browser group timeouts, compare each complete native/reference/replay
journey with its planner weight. Shadow/filter mutations, manual-update replay, loading, material-output,
environment, transmission, output, rendering and texture comparisons must
not fall back to the unknown-file five-second weight; follow
Browser gates. Preserve cases, frames,
pixel/replay assertions and deadlines when correcting scheduling estimates.
The directional, point and spot shadow/filter journeys each own a separate
Browser process through shadow.fixture.ts; run the corresponding
shadow-<kind>.browser.test.ts owner rather than recombining their deadlines.
For the directional journey, retain its existing exclusive admission when
reproducing the complete native/reference/replay timeout; follow the CI guide.
The managed-material runtime pixel owner retains its original short case bound
and uses the existing exclusive bootstrap process set to drain neighboring work.
The complete 24-case Three material-output owner also drains neighboring Browser
groups after run 39457755532 exhausted its original process bound beside a
long GPU group. Keep its measured receipt, cases, pixels and deadlines intact.
For the complete Three render/reference/replay case, distinguish native readiness,
capture and cold fresh-device replay receipts before changing scheduling. Its two
bounded replay slots retain independent devices and immutable tapes, drain before
renderer teardown and propagate replay failures. Preserve all original pixels,
sixty-frame windows and the 120-second case limit; see the
repeated GPU work policy.
For View texture channels, source mip/slice or environment projection failures,
run tools/view/scripts/verify-texture-preview-integration.mjs and inspect its
PNG/pixel evidence under artifacts/texture-preview. It uses the real browser
Pack path and the existing exact-target capture. One-level Equirect sources do
not expose Renderer-owned IBL roughness mips. Follow RHI Debug first for an
unexplained rendering failure; see the View texture gate.
For View UV layouts or material primitive/navigation failures, run
tools/view/scripts/verify-resource-preview-lifecycle.mjs and inspect its UV and
material PNGs plus exact target diagnostics. The maintained workspace shard owns
this real-browser journey. A script syntax error routes to the View probe owner;
preserve its runtime assertions while repairing startup. Follow RHI Debug first
for unexplained rendered output.
For a blank MCP View with React error #527, run its emitted frontend startup gate through the View contracts owner. The MCP builder resolves React and React DOM from View's installed dependencies; inspect that owner before changing startup deadlines. Continue through the full game-3d/Play/Stop gate after repair.
For a View shard reaching its job deadline, inspect emitted stage seconds before changing a timeout. Keep Game 3D's stdio and native workspace journeys together in its own lane; contracts/plugin/TS share another. Preserve complete JS/TS live/cold chains, four actual jobs and all assertions; see the Engine/View integration roster. An artifact-only transport failure requires a same-source rerun, not a weaker success aggregate.
For a View startup Host disconnect, read the failed probe's Backend diagnostics
under artifacts/view-integration/<probe>/ before assigning a renderer cause.
The CI owner matches native daemon spawn records to the failed child and retains
its stderr after cleanup. Preserve the original timeout and failed exit; follow
the failure recovery route.
For repeated app builds, slow metric aggregation or successful diagnostic uploads, follow one build and one metrics execution owner. Check the disjoint App/Bevy source roster and actual metric consumers before adding a cache or scheduler rule. Keep all retained Bevy cases at 60 completed frames and preserve metric producer failures through the required aggregate. For Bevy input tails that stop before release, use the existing ready-receipt frame driver; RAF callbacks are not completed App frames. Preserve authored simulation horizons when reducing ECS fixture submissions.
For native template movement timeouts after Runtime Vase regeneration, inspect
the producer/recovery render boundary before changing input waits. The shared
probe requires its original submitted prefix to complete ready, including
recovery; CPU adoption and submitted-only frames do not qualify the picture.
For Bloom device-loss recovery with an empty pre-loss graph, inspect completed
ready receipts before triggering the crash. Submitted warming frames and HUD
pixels do not establish a rendered scene. Follow the Bloom recovery gate in the
CI guide; preserve its deadlines and pixel thresholds.
Measure complete Runner minutes and the critical path without queue time.
For a shared shader producer exiting 134 with V8 heap exhaustion, compare its
parent heap with the shared build-shaders step's limit before changing shader
variants or worker admission. Follow shared shader budgets
and retain the cold-source failure and verified publication receipt.
For compiler sourceContentKey mismatches during input restoration, compare the
actual wgpu/Blitz checkouts with the Engine gitlinks before rebuilding. The shared
input entry must synchronize existing public source checkouts too; Cargo.toml
presence is not pin admission. Retain compiler source and byte verification.
For frozen-install ERR_PNPM_PACKAGE_MANAGER_NO_IMPORTER, check whether the named
package exists in target HEAD. A removed submodule left by checkout routes to
prepare-pnpm-workspace.mjs; follow Build inputs
and retain the checkout warning and original install error.
An independent nested checkout can have an embedded .git directory and no
root submodule config. Prove its exact historical gitlink from the local HEAD
reflog before pruning; preserve unrelated repositories and changed commits.
For repeated native fixture startup, compare actual device requests and replay
submissions before changing placement. Follow native fixture workload budgets: reuse renderer/device preparation across independent World/asset owners, retain constrained/publication hosts and fresh falsifiers, and restore redundant work as a failing control. Never bind one asset registry to multiple Worlds. Alpha Hash keeps its cold live hosts and batches only replay work; aggregate counters still check every original texel. Furnace readiness must belong to the current ready receipt, and multiview GI reuses staging storage while retaining every frame and owned readback snapshot.
For a Dawn overall job cancellation with passing groups, compare complete group
costs, ordinary-file backfill and lane headroom in dawn-gate-roster.mjs; follow Build inputs
while preserving the full roster, native process isolation and existing deadlines.
Check new files against the measured cost table: the maximum-file fallback can
strand a lane even when the new file itself is short. Admit only complete-child observations.
For independent-view lighting readiness, read preparation-failure.json and
its original pending reason before assigning native compilation or shader ownership.
Compare complete child costs with their placement forecasts before changing lane
membership; refresh stale file and owner costs first, then replay ordinary
backfill. Keep an interrupted owner at its inherited forecast.
The job result and native child result are separate: a child that passed with
its complete emitted roster can supply costs even when the overall job later
times out during cleanup. Include that cleanup headroom when qualifying all four
lanes; do not treat passing groups as a successful job or raise the job deadline.
Check serial Dawn's Mesa worker count against the admitted heavy CPU budget;
CI and Dawn Focus use eight workers, while concurrent Browser processes retain
four each. Preserve capacity admission and the single native Vitest worker.
For a Linux nightly failure in Build shared shader inputs, inspect the Node heap
limit separately from the Dawn shard. The source producer needs the same explicit
4 GiB V8 heap as its downstream Dawn command; the 2 GiB default can exhaust while
assembling the full reflected shader publication.
For Bevy Skybox's missing Chrome Beta after a passing Dawn smoke, repair the
fleet's browser preparation through the shared installation action. Its composite
smoke retains the real WebGL2 journey; see failure recovery.
For guide-form input scroll-width mismatches, compare native client widths and
outer rectangles before assigning layout overflow. Follow the UI owner's
control parity contract;
retain ancestor extents, external geometry and the complete input journey.
Check newly discovered files against the same cost table: its largest-file
fallback can reserve minutes for a short new test. Admit costs only from complete
successful children, retain process overhead and larger inherited forecasts, and
exclude interrupted owner tails before running the final full matrix. Distribute
ordinary-process overhead across emitted skipped files too; a missing file result
keeps its inherited forecast. When all
groups complete but one job exceeds its envelope, a complete owner can move from
a lane with measured headroom to the overrun lane; replay ordinary-file backfill
for all four lanes before keeping that placement.
For Linux software validation, use pnpm ci:graphics setup and the
isolated graphics contract.
For a native Rust GPU-owner crash, retain the failed process evidence and use
the workflow's serial test entry, matching the upstream GPU suites. Preserve
the complete target roster and required Ray Query admission; SIGSEGV is not
an artifact transport failure or a passing GPU result.
The pinned official archive snapshot retains package bytes after moving mirrors
remove old releases; retain download/hash errors rather than bypassing setup.
Basic source initialization and ordinary tests do not require Dawn. pnpm test
retains its DevKit browser journeys; Dawn GPU testing is a local opt-in. For a missing
carrier on macOS/Windows, explicitly run
pnpm --filter @forgeax/engine-dawn-node build:native before pnpm test:dawn;
follow the carrier contract. Do not add
native compilation to installation or ordinary builds, skip missing GPU evidence,
or substitute Dawn for the native wgpu Ray Query backend.
On Windows, run pnpm test:browser / pnpm test:dawn through the
Node suite entry.
It preserves the full roster and owner deadlines while passing environment
values directly; no POSIX assignment or package-manager upgrade is required.
For Smoke roster drift or exit-zero shell controls without a receipt, inspect
the Windows repository shell route.
Retain the real child assertions and canonical frame evidence; exit zero alone
does not qualify the command.
For a Windows multi-project Vitest failure, verify that CLI exclusion globs reach
the resolved project with forward slashes. The actual workspace regression in
scripts/ci/__tests__/run-vitest-projects.test.mjs requires ordinary tests and
rejects the excluded file; retain the separately leased DevKit native groups.
For the Windows Nightly Build opt-in Dawn native carrier step, separate CMake
generator/configuration from the later MSVC source compile. A CMake log that
selects Visual Studio 18 2026 proves generator selection only; the native
build must finish and publish its verified output. Check the build worker cap
when MSVC is still compiling DXC/LLVM at the cold-build deadline. The CI guide
owns the cold-build budget and content-keyed output cache; never cache or
restore the CMake build tree.
Package-script environment prefixes use the workspace's pnpm shellEmulator;
direct child launchers must use pnpmCommand, including composite Smoke gates.
Do not install an extra shell or replace a failed child with an exit-zero receipt.
For a cold package build that imports an unbuilt workspace compiler, inspect its
forgeax.buildDependencies selection and declared devDependencies; the package
build graph owns ordering and cache invalidation for these build-only tools
(CI guide). Do not add the compiler to a player import.
For workflow ShellCheck failures, follow the CI shell transport contract
and retain the original file roster and preparation failure exits.
For a missing descendant PID in gate-process-lifecycle.test.mjs, inspect fixture
startup and parallel Node admission before assigning a cleanup failure. The
complete owner runs serially after the bulk regression batch; keep its original
1.5/2-second command deadlines and every readiness, escalation and exit assertion.
See the owned process route.
For a leaked Vite port or a completed browser smoke that never exits, follow
the owned server lifetime route.
Inspect descendants that retain inherited output, use the shared owned
process-tree cleanup and its actual TCP regression, and never terminate
unrelated Node processes. For Import
sidecar EPERM, compare the actual destination bytes: only an equivalent
publication succeeds; mismatches retain the structured failure and rollback.
For a View integration owner failure, use CI Focus kind=view with its exact
run-view-integration.mjs --list-groups name (for example game3d). This retains
the complete owner, real transport and capture assertions; a focused pass still
cannot replace complete final-head CI. Preserve CLI timeout failures even when
a fallback page screenshot is healthy.
For a full Browser gate failure that passes CI Focus, select browser_profile=ci
in the maintained workflow before attributing the difference to renderer code.
Its default local workload differs from the full gate; keep the original
lifecycle, pixel assertions and deadlines. See the CI guide.
For SSR recovery compilation near its 20-second deadline, inspect the actual
pipeline labels and admitted specs. Standard uses the material cache and exact
LKG recovery requests; do not reintroduce the generic bootstrap matrix or widen
the deadline. The tree-shake owner builds missing production output through
the maintained source builder and still fails if the actual bundle is absent.
For Node paths containing spaces, that builder starts Node directly without a
shell; preserve its actual hello-cube production-bundle regression.
For cold bundle preparation under coverage, verify that the tree-shake test
forwards FORGEAX_SHARED_APP_INPUTS_MANIFEST to the maintained app builder.
Keep the source-key admission and original timeout; repeated shader preparation
inside the fixture is not a reason to widen its deadline.
For direct-DFG manifest boot timeouts under coverage, retain the Renderer's
ordinary shared/packaged manifest selection. The shader-owner producer test
still forces source compilation; the boot consumer keeps JSON publication,
fit/LUT and material-admission checks within its original deadline. See the
shader coverage preparation.
If Windows Rapier preparation stalls after compilation, inspect the declaration
producer and its exact tsup entry; retain the real junction-mounted regression in
scripts/__tests__/rapier-wasm-declarations.test.mjs before rebuilding the payload.
For Runtime Pack's Windows wgpu-webgl2 assertion, follow Windows Runtime Pack WebGPU admission. Keep the backend, pixel and sixty-frame assertions.
For Mesh I/O adapter-unavailable on Windows CI, check whether Linux-only
Vulkan/SwiftShader flags reached Chromium. For its sRGB source-color oracle,
inspect the real linear readback and RHI live/replay/missing-draw triptych;
native format conversion precision is separate from the unchanged authored
linear HDR budget. Retain the twenty cases and gamma/UV falsifiers.
For native artifact producer scheduling, follow Windows native Ray Query artifact producer. Windows hosted producers use explicit maintainer dispatch in the nightly lane; daily PR and post-merge checks retain self-hosted runners and strict artifact admission.
For the upstream Linux Naga producer, a Vulkan SDK tar failure naming missing
xz belongs to archive-tool setup. Install xz-utils before the pinned SDK action
and rerun the original WGSL/SPIR-V snapshots; setup failure is not a snapshot pass.
For slow isolated native GI imports, prepare the source-bound shared shader inputs and pass FORGEAX_SHARED_APP_INPUTS_MANIFEST through the ordinary shader builder, as the native CI group does. Retain the full GPU roster and its falsifiers; never point the consumer at an unchecked old manifest.
For late Preview or Capability Lab readiness, follow failure recovery.
Keep the actual failed frame and distinguish Browser evidence from diagnostic
Dawn replay. Separate Catalog preparation, payload decoding and completed-frame
readiness before assigning a renderer cause. Source-byte reuse must retain digest
and size admission; a faster decoder alone does not qualify startup.
If a template smoke inherits on-demand production, inspect its owned Vite child's
readiness policy: native imports belong to the existing before-consume Catalog
barrier, before browser admission. Preserve the browser and completion deadlines.
For SDK contracts that cannot import built Engine subpaths on a clean runner, inspect build inputs and the seed's production outputs before its producer-owned contracts. For a missing native binding after npm installation, reproduce with the exact package bytes and installation flags. Preserve the published bundle layout and external peer edges in DevKit run snapshots; a successful install is not a successful native run. Compact shader source fragments and receipt tables must survive transport and materialization without replacing source identity with table indices.
For ERR_PNPM_TASK_CYCLE, inspect the exact producer build closure. Preserve an
existing deliberate-cycle setting only on the owning build step; other filtered
commands must continue to reject unexpected cycles.
For Preview Catalog timeouts or Windows DDC publication EPERM, inspect the
producer-readiness option, native watcher and destination bytes before assigning
a shader or renderer cause. For template startup failures, preserve native Error
fields through console transport and inspect the named cause. Follow the
SDK failure route: visible terminal
errors fail promptly, healthy startup retains its allowance, and backend stop
requires its own retirement evidence. Preview keeps separate Catalog and
completed-frame deadlines; an inspection connection or capture is not readiness.
For Screen Probe motion, noise or receiver-sequence failures, follow RHI Debug and inspect actual probe and pixel work before changing history budgets. Keep whole-scene quality and physical timing separate from kernel controls. Download current-source motion tapes, pixel bytes and typed replay reads while CI artifacts remain available; metadata or older tapes cannot qualify missing current evidence. Native Ray Query remains a separate backend from Dawn. Diagnostic uploads never admit a failed gate.
For VFX Mesh lighting failures, inspect artifacts/ci-focus/vfx-mesh-lighting/.
An in-flight frame retains its unavailable-capture result; diagnose its recorded
renderer/device owner before requesting a later frame. For WebSocket status 1009
or WS_ERR_UNSUPPORTED_MESSAGE_LENGTH, preserve the original error, tape bytes
and transport budget. For Topology Browser failures, read
artifacts/ci-focus/topology/failure.json: Catalog startup belongs to its named
producer; frame or PNG failures use RHI Debug. Follow failure recovery
and retain the original oracle and timeout.
For an oversized Three feature Browser file, keep the shared feature callback
and its initial/edited captures intact, then inspect all four partition entries
and the external-texture file. Refresh their existing Browser cost-table entries
from complete successful children, including startup/cleanup, so normal grouping
does not recreate the timeout. Label local timing separately from CI receipts;
retain the 120-second case and 300-second process deadlines.
For a Dawn lane canceled at the job deadline, inspect complete process receipts,
exact file rosters and the GitHub job annotation: even a native PASS can exceed the job budget
during cleanup. Preserve the failed gate and use completed children only for cost
observations; final-head CI must still pass after a placement refresh.
Refresh only dawn-file-seconds.json placement forecasts. An interrupted
owner contributes no completion sample. Keep the four-lane sequencer and original
native deadlines; a cost refresh alone is not proof of a faster complete gate.
A new isolated owner inherits conservative per-file costs until its first complete
child receipt. Replace that fallback with the measured complete-owner cost,
including startup and cleanup; do not infer a cost from an interrupted lane.
When the admitted worker-count policy changes, replace stale placement costs
with complete receipts from the current policy. Keep the prior estimate for any
interrupted owner, and require the complete final-head CI gate after recalculating.
For a cold Preview capture interrupted by Vite full-reload, inspect optimizer
logs for late dependencies. A literal dynamic import remains eligible for Vite
pretransform even with @vite-ignore; Node-only transports must load only on
their native execution path. Preserve native remote-server and real cold-browser
regressions when correcting that boundary.
For the learn-render 4.10 MSAA paired proof, a cold Vite optimizer scan followed
by the app's 30-second page.goto timeout has one signature-bound retry through
the Browser gate guide. Keep the
real OFF/ON captures and P2 assertions on both attempts; a repeated timeout stays
red.
For Play startup ERR_OUTDATED_OPTIMIZED_DEP, check the frozen plugin graph's
preparation order. Vite optimizer init() starts its scan asynchronously;
plugin capture must await that initial scan before freezing module URLs. Keep
the cold-start Play, same-project lock, cache-reuse and renderer-failure checks.
Check the scan's entry set too: declared Runtime Pack secondary exports can
introduce dependencies outside App's main graph. Resolve those entries through
the executing client before optimization; retain native Engine module identity.
For paired replay work-index divergence, compare each consumer's selection
against the tape's swapchain provenance and trailing probe work. The shared
application selector owns both defaults and explicit work-index transport;
retain the same-artifact, backend and pixel oracles.
For Dawn partition roster drift, compare actual Vitest titles with the
case-sensitive patterns in scripts/ci/run-dawn-partitions.mjs. VFX depth's
standalone Player MeshFilter belongs to the mesh partition in both modes;
follow the Dawn gate roster and retain
unique coverage, original assertions, and failed-result rejection.
For run 38488147135 at 9ef74f951, follow
artifact sharing and adopted Play readiness.
Separate live WeakRef sharing from collection/refetch, and distinguish hidden
fatal markup from an actual startup failure. MCP Backend logs belong to the
spawning CLI child; keep the original 120-second readiness/cleanup bound.
For 7a25ead8e initial MCP connection or mobile input failures, use
first workspace connection and concurrent validation.
Inspect the owned Backend stages and complete pointer-event evidence. A reduced
compiler invocation count does not qualify the original Browser deadlines.
For Snake late-join ACK retry budget exhausted, follow
multiplayer startup and baseline ACK admission.
Keep initial polling with the World receive system and reproduce delayed Host
activation on the real browser path without expanding the game ACK budget.
Cold compiler and graphics admission
For clearcoat publication timeouts in declared-standard-material.integration.test.ts,
use the existing exclusive coverage file owner in
CI operations. Keep all material/compiler assertions
and original test deadlines; verify the file has one owner and no competing
instrumented child before changing runtime code. Ordinary publication checks
use the existing storage-WebGPU profile and file-owned cooker; the independent
cold composition/cache contracts retain all portable backends. Verify actual
program selections and the instrumented coverage path before claiming recovery.
For a Three render/reference/replay timeout, retain its complete fresh Browser process and exclusive runner admission. Verify the native, reference and replay journeys at their existing frame counts and deadlines; do not relax pixel or capture assertions to absorb competing graphics work.
Rendering: RHI Debug first
For difficult or unexplained rendering failures, use forgeax-engine-rhi-debug before speculative shader or material changes. Capture the real failing frame and inspect its work, bindings, resources and pixels. This covers missing output, wrong lighting or shadows, flicker, post-processing artifacts and backend divergence. A concrete startup, asset or schema error goes directly to its named owner. If capture is unavailable, preserve the structured failure and use the RHI Debug recovery path.
A broken demo may expose an Engine gap. Trace the owner instead of introducing placeholder assets, manual frame loops or demo-side fetch workarounds.
A camera-free World is valid. Do not add a Camera to repair empty startup:
trace any render-system-no-camera event to the renderer owner. Template Browser
smokes reject that event rather than exempting empty scenes from console checks.
CI diagnosis and iteration
If the CI install-entrypoint contract fails, run
prepare-pnpm-workspace.mjs before each filtered frozen pnpm install on the
same workflow entrypoint, retain the package filter, then rerun the focused
prepare-pnpm-workspace.test.mjs contract.
Core preflight runs that original entrypoint check before native preparation;
the complete primary lifecycle batch remains required. For macOS compiler-cache
path mismatches, canonicalize the fixture's temporary root before deriving its
expected paths; keep exact source-isolation and artifact assertions.
For check-no-assets-load, inspect the named Pack production dependency.
AssetRegistry.load is the supported game runtime API; the guard belongs to
Pack's offline source/evidence boundary. Keep runtime imports out of Pack and
retain the executable allowed-game/rejected-Pack regression cases.
For a manual run that rejects evidence already on the PR target branch, inspect
the guard's comparison base. Follow manual CI comparison base
and dispatch with the actual target comparison SHA through comparison_base.
Keep new-evidence rejection and the complete product checks; do not delete
unrelated baseline files to compensate for a missing PR event base.
For a synthetic merge that schedules eight Dawn lanes while checked-out product source accepts four, align the workflow and executable selectors during main integration. SDK ZIP/npm groups and their receipt aggregate must likewise match the four consumers. When native owner arrays are shortened, map retained cost samples by their original files before assigning the new numeric group labels. Preserve original native, pixel, lifecycle and seed identity checks; a selector failure before execution is not a backend failure.
For [function-complexity] or [dependency-vulnerabilities] failures, follow
source quality ratchets: split the
named function by owner or upgrade the owning dependency declaration; accept a
baseline increase only with a reviewed reason.
For CI code reduction, follow CI code ownership.
A sudden roster or fixture-cost increase after a merge may restore retired work.
Check deletion history and retain the shared budgets and four-job matrices while
keeping genuine new feature and lifecycle coverage. Follow the
SDK consumer mapping: the npm
diagnostics install must also run the shipped Game 3D Play helper, while ZIP
project retains TypeScript live/cold coverage. A local Engine View success does
not qualify the installed Play snapshot. Inspect the failing owner's stage log
before changing a deadline or splitting the four-consumer matrix again.
Use pnpm ci:focus --kind <kind> --select <selector> (also bun fx ci) for source reproduction;
the local Actions emulator and workflow-string snapshot suites are retired.
Actionlint checks workflow syntax and complete final-head CI checks execution.
Artifact bytes and source admission remain enforced at their actual consumers;
do not recreate timingRoster or a second expected workflow graph.
Smoke schema 3 has scalar oracles and manifest-owned commands; retain exact gate
membership and reject mixed-schema receipts. Bun consumes core/shared artifacts
directly and tests its own install/build/runtime path; repeat source scans stay
with the primary owner. The optional real-GPU timing workflow validates the
producer report in one job; its retired host-contention admission report is no
longer a qualification claim.
The workflow and executable rosters are the scheduling authority. Do not restore
the retired terminal-SLO projection, cost ledger, DDC relay or feature-branch
attestation jobs. Node/pnpm setup has one shared Action; Smoke receipt validation
remains with its required aggregate. Inspect that job's log after success and the
original shard evidence after failure.
Use the CI operating guide. It owns the current
four Browser lanes, four Dawn lanes, core Smoke roster and four SDK consumers.
Every matrix stays within four actual jobs, including platform entries.
Compare focused and full CI CPU admission before treating a diagnostic pass as
reproduction. The shared material-edit fixture keeps one complete-case budget
across Browser and Dawn; all lifecycle, pixel and error assertions still run.
For interrupted dpkg state, use the existing system-dependency installer. A
skipped target-repair step is missing recovery evidence, even when its job is green.
For measured Browser roster coverage failures, refresh missing costs from completed
process receipts using the Browser cost formula.
Keep source-run provenance, distinguish amortized group costs from independent
file timings, and preserve the coverage threshold without counting startup twice.
For all-zero TAA Dawn readbacks, inspect native pipeline validation in the actual
RHI capture and use validated async pipeline creation in the fixture. Nearest
samplers paired with unfilterable float textures require non-filtering layouts.
For resize equivalence failures, compare the frozen reference and production
attachments before changing WGSL. Keep texel-boundary witnesses away from exact
interpolation ties and retain a GPU falsifier for the physical-lattice guard.
The suite deliberately retains representative core coverage. Keep unique browser
transport, Worker, media and recovery cases; shared numerical fixtures can have
one real-backend owner. Do not restore deleted duplicate tests or historical
scheduling guards just to reproduce the former inventory.
For live-dev-client startup-deadline teardown ENOENT, retain the 500 ms project
deadline and three-second case bound. The detached fixture child may still be
starting without a published session file. Stop the actual spawned child and
await its exit before deleting the project; keep the owner-liveness assertion.
For a Dawn job cancelled at its 27-minute limit during or after native execution,
inspect the job annotation, complete owner costs and runner variation through the Dawn cost table.
Preserve the cancelled receipt and qualify the refreshed placement with full final-head CI.
If a full-lane retry of the same head hits the same deadline, refresh completed
file and owner costs before another attempt; do not attribute the repeated delay
to transient contention without evidence.
Refresh the existing file/owner table from multiple completed native rosters.
When fixed reservations and observed tails diverge, redistribute complete owners
within the existing four lanes and let the same sequencer place ordinary files.
For a cancelled run, admit only individually completed owners and ordinary-file
receipts; never treat a partial owner or an unstarted tail as complete. Retain
per-file observation provenance in the investigation artifact. For a deadline
recovery, retain the larger of the inherited forecast and each newly completed
observation; unobserved files keep the sequencer's conservative fallback. Include each ordinary file's
share of native process overhead and each fixed owner's complete child-process
and cleanup costs. Nearly equal file counts can hide unequal work when many
new files receive the maximum-file fallback. Report measured-cost coverage
alongside the replay before attributing the entire delay to runner variation.
A completed ordinary process from a cancelled job remains a cost observation;
the interrupted owner and unstarted tail do not. Verify complete file identity
when a process-start line is absent before admitting an emitted file set.
For a native worker exit, compare the selected ordinary roster with emitted
file results to identify the missing owner. Verify its complete capture/replay
test in a fresh process, then use the existing isolated-owner route when shared
native lifetime is implicated. Keep every file, assertion and original deadline;
the failed process supplies no completed cost sample.
When a completed file within an interrupted owner already exceeds that owner's
reservation, the old forecast is disproven even though no new complete duration
exists. The CI guide documents a reservation estimate using that file's slowdown
against complete matching rosters. Keep the estimate, its assumption and original
failure separate from measured owner durations; full final-head CI remains required.
Ordinary work automatically moves when costs change. Replay
actual current discovery across all four lanes before moving complete groups,
show missing historical costs as forecasts, and keep job setup and runner
variation separate from new CI measurements. Preserve all four jobs, the
27-minute deadline, frame windows and backend assertions. When upstream removes
duplicate wrappers, reconcile explicit owners against actual discovery and remap
heavy-group cost samples by file identity rather than their old numeric labels.
If a new complete observation exceeds its existing forecast while other lanes
finish early, replay the actual current discovery with the conservative maximum
before moving complete owners. A single heterogeneous-runner observation cannot
justify lowering costs. Keep interrupted owners on their historical forecasts;
report those unmeasured tails separately and require a complete final-head run.
Account for complete transmission, shadow, Screen Probe and multi-view GI owners
rather than concentrating their serial native processes on one lane. Separate
Surface, VFX depth and Direct Light too; updated ordinary costs must share that
same placement. Core flow self-tests belong to the existing
primary regression batch; keep source admission and actual output production
on the core producer.
For a slow shared-input producer, separate cache admission, cold shader
compilation and catalog preparation. It uses the existing heavy pool with the
shared cgroup capacity check; never size workers from the physical host count.
Compare identical cold outputs and CPU work before attributing gains to resource
allocation, and keep cache-hit timing separate from compilation speed.
For ERR_INPUT_TYPE_NOT_ALLOWED in a declaration Worker, reproduce with the
actual Dawn preload. Start the fixture from a file instead of forwarding an
eval-only argument into tsup Workers; retain declaration content assertions.
For a slow Coverage tail, inspect coverage execution:
ordinary children must fill available slots before the exclusive phase. Refresh
existing project costs from complete runs rather than adding worker exceptions.
Render and Vite Pack retain independent ordinary children; avoid binding their
large import costs to unrelated packages.
Include type preflight and each exclusive owner in the complete lane estimate;
stale exclusive costs can concentrate the serial tail on one shard.
For Browser placement, retain the larger historical or complete-child amortized
cost when calibrating across different runners. Include the actually completed
Runtime Pack Worker and Mesh tails before assigning groups; unstarted tails
retain their earlier forecasts. A failed parent can supply successful child
timings, but never a full-CI success. Report setup and queue time separately.
If a broad DevKit/Render half starts late behind fine-partition waves, admit that
complete half first on its job and model the same order in placement. Keep the
exclusive barrier and full roster; an interrupted child is not a timing sample.
If repeated within-wave ranks still cluster on a job, spread those cohorts too.
Place each complete fine wave atomically across the same four jobs to avoid a
greedy dead end; preserve exact file discovery and exclusive source headroom.
Keep complete-child observations and retained maxima in the coverage child-cost
ledger. Refinement may balance completed work only within the retained capacity
envelope. Verify the real CLI typecheck override: runtime coverage children must
not duplicate the unchanged central declaration-test owner. Update both locks
when changing the existing Vitest project-override patch.
When splitting a complete long project into native partitions, keep those halves
on different jobs through both initial placement and refinement; two parallel
slots must not reunite them on one runner. Prove exact file conservation with
actual discovery and the configured sequencer, while retaining exclusive owners,
ordinary non-coverage routing, concurrency, heaps and original deadlines.
Type-test roots retain selected tests, imported source and ambient declarations;
core/primary own ordinary source checks. For the runtime-vase browser tail, verify
the shared canvas budget applies before UI edits, while full UI screenshots and
both 60-frame execution routes remain intact. A View diagnostic resume must wait
for the real buffer resize as well as frame completion; an old-size completion
is not resize evidence.
For Play capture followed by an extent-mismatch pick, verify that the completed
receipt's output mapping still matches the current drawing buffer. A later
canvas resize must not turn an old ready completion into a valid screenshot.
Coverage placement estimates its parallel phase and serial exclusive tail separately;
keep that shared plan independent of each Runner's execution resource limit.
For Browser placement, use complete child costs (including startup/cleanup) from
browser-file-seconds.json and measured serial tails. Do not add another fixed
startup surcharge to those costs; validate longest-lane forecasts in complete CI.
For a group timeout after several passing files, inspect the complete serial
batch cost. Ordinary batches use the same measured table with a 150-second
target inside the unchanged five-minute deadline; keep isolated owners intact.
For large capture transfers, reuse the shared lossless compactTape fixture.
Keep the seeds, events, pixel checks and real replay falsifiers; omit duplicate
work/resource JSON only when it is reconstructible from the retained tape and
has no downstream consumer.
Smoke placement uses current complete gate times plus post-roster tails; remove
retired work from estimates as well as execution. For an idle App build slot,
inspect start order: the existing input inventory prioritizes larger closures
without adding another cost table or increasing concurrency. Live-sync uses the
shared disposable-project reducer; retain the real CLI/daemon/browser journey
and report fixture size reduction separately from measured elapsed-time effects.
Mesh keeps sixteen distinct routes and all real capture/replay/falsifier checks.
Successful CI retains every offline analyzer input while omitting duplicate
control tapes, geometry dumps and previews. Run the full Mesh verify package
command; the browser script alone does not qualify its source numeric oracles.
For GI load, use the shared ray budget and the smaller two-level multi-view grid.
Edit/rebuild convergence, movement signal/noise, Screen Probe history and multi-view
fairness keep 64-ray overrides on both backends. Validate shared reductions on Dawn
and native Ray Query; a failed lower-sample oracle never justifies looser thresholds.
Volumetric fog has one required Smoke owner; its removed Dawn wrapper repeated
that same script and its extra byte-difference assertion now belongs to the script.
For Dawn duration, distinguish static setup from temporal acceptance. Reuse
render-quality.json's static frame count in unchanged material/color fixtures;
Surface optical/MSAA, Forward/Deferred parity, clipping, lighting-channel
baselines, material MRT and framebuffer preparation use that same budget.
Shadow-field comparisons also use its map size and a distinct half/twice-size
pair; retain all twelve assertions, fresh hosts and varied/held pixel controls.
Keep cube-face completion, recovery windows and every pixel/replay falsifier.
Lens samples override the default to six frames and retain their composition
window to preserve the 60-frame fixture lifetime. Keep convergence, asynchronous
readiness and canonical 60-frame smoke budgets.
Remove report-only GPU benchmarks without a cost bound. GI pass-presence checks
reuse renderer-irradiance-field.fixture.ts's consecutive-frame observation;
keep per-frame absence checks, numerical thresholds, replay and falsifiers.
Direct-light regression and HDRP producer scopes are disjoint: pnpm test:dawn
owns regressions, required color-lighting metrics owns the four native captures
joined with Browser URP. For a producer failure, run
FORGEAX_DAWN_PARTITION_SCOPE=producer node scripts/ci/run-direct-light-dawn.mjs;
reuse each live capture for artifact checks instead of rendering it again.
Mesh interchange keeps distinct format/material/camera/skin routes; repeated
OBJ/GLB performance samples belong to its opt-in fidelity benchmarks. Optional
Mesh, lighting-channel/GI and Wave 1 captures upload only after failure. Inspect
the successful check logs rather than treating an absent optional artifact as
missing acceptance; required producer artifacts and receipts remain mandatory.
Read the failed head's logs and separate preparation, execution, teardown and
transport. Reproduce with the owning package or pnpm ci:focus. Keep the real
backend and failure assertion. Fix the owner, run its relevant checks, then
qualify complete CI and SDK on the final commit. Retained 60-frame smokes, pixel
thresholds, negative controls and coverage thresholds remain unchanged.
For FBX skin exit 139 after a logged pass, inspect the standalone smoke's native
teardown. Retire Renderer, World context and its offscreen target, then drain the
shared Dawn owner before the receipt. Verify both the real 60-frame smoke and
FALSIFY=static; a local non-reproduction does not qualify the failed CI job.
Missing outputs require source build or verified producer artifacts.
CI artifact consumers restore and verify first; only a real source-build miss
provisions the wgpu, Rapier, Blitz UI and Codec owners through the shared
preparation Action. For SDK Candidate UI contract failures, inspect parsed YAML
conditions for both the verified shared-artifact branch and source fallback;
retain receiver cleanup, source/byte verification and preparation-before-build.
A clean
worktree needs pinned submodules before frozen installation. A retained assets
shallow.lock routes to prepare-assets-checkout.mjs: only an exclusive matching
Actions workspace may recover a lock older than the current source checkout.
Keep local/current-job locks and the foreign-Git-directory rejection intact.
Native payloads must pass their source/recipe and byte checks. CI Focus prepares Rapier before the
Engine build even for browser selectors. Chromium always runs sandboxed. Use
the local GPU lease and existing process cleanup rather than adding retries,
longer deadlines or per-test scheduler exceptions.
For Rapier cache misses, compare build-rapier-native.mjs <2d|3d> --key with
the cache entry and --verify; the producer content key owns the input closure.
For a Rapier post-step upload stall after successful verification, inspect the
verified payload cache and follow Build inputs.
Rapier reuses that payload across runs; it does not upload a second Cargo target archive.
For fetch 401/exit 128, inspect URL-matched checkout HTTP configuration: temporary
Git repositories receive it through git-http-environment.mjs and the existing
bounded fetch. Never print or persist the authorization header.
For simultaneous input-preparation failures, inspect the core producer first.
Its upload must succeed before fanout. The shared prepare-ci-inputs Action
verifies restored bytes before provisioning wgpu/Rapier for a genuine source miss.
Keep native preparation off the successful restoration path. A filtered pnpm
install still runs root lifecycle hooks unless --ignore-scripts is set; inspect
Harness-clone postinstall costs before blaming Rust or the package cache.
Distinguish action-download stalls from actual artifact transfer using the last
executed producer log entry.
If Getting action download info stalls before a composite starts, its unused
cold-path actions can still be the cause. The wgpu fallback uses the same GitHub
cache Action as its payloads, avoiding a separate Rust-cache Action resolution.
For cold dependency installation, compare downloaded package platforms with the
actual host. Ordinary CI keeps PNPM_CONFIG_SUPPORTED_ARCHITECTURES consistent
across install and run/exec; one-off install flags cause pnpm 12 to reinstall
the broad closure. prepare-pnpm-workspace.mjs --install avoids --force and
root postinstall hooks. Filtered frozen installs use the same preparer with
--filter <package> so cleanup precedes dependency resolution without widening
the package closure. SDK PR preflight and benchmark installs use that same
preparation, including SDK source-rebuild reinstalls; a retired workspace importer is not a reason to
regenerate its lockfile. SDK publication
still requires its complete installed platform closure; keep that preparation
with the distribution owner rather than changing the global workspace policy.
For Snake browser ACK exhaustion, check that the process fixture disables the
server's automatic clock before owning its ACK-paced World updates. Two clocks
bypass backpressure; retain real socket recovery and the original retry bounds.
For cold Rapier preparation stalls after Rust finishes, inspect wasm-opt and
cgroup cpu.stat. The shared Rapier Action derives BINARYEN_CORES from
runnerResources() with a four-thread ceiling; Cargo's worker limit does not
control Binaryen. Reproduce with an actual CPU quota, not only affinity, and
compare payload hashes while keeping the existing optimizer flags.
Shared catalog/shader preparation does not need Runtime or Rapier: its empty
Vite entry never loads Runtime's dev transport. Keep Runtime and both Rapier
dimensions outside its production build selection and native preparation with
actual runtime owners. Codec remains in that closure and needs preparation.
Use --filter-prod for both positive and negative selectors; mixed selector
families can unintentionally include unrelated workspaces.
For LOD FORGEAX_E03_INPUTS_DIR failures, check the CI step's existing importer
producer preparation against the hydrated app shader manifest.
For DevKit native unit queues, keep new-project-workers CPU preparation outside
an outer GPU lease; its native-unit-owner acquires the lease for prepared work.
scene-bootstrap uses WebGPU directly and retains its outer lease. The split-unit
runner schedules both complete journeys last from one shared file-set definition.
For Windows GPU timing lifecycle child imports, convert the built fixture path
with pathToFileURL before passing it to ESM import. Retain the real-device
receipt GC, destroy count, child-exit assertions and their original deadlines.
CI resource detection and concurrency budgets belong to
runner-resources.mjs; ordinary fixture
sizes belong to render-quality.json.
For Coverage contention, compare child compiler budgets with container capacity:
parallel children share CPU/memory; exclusive work retains the full budget.
Never derive shard membership from a particular Runner's quota.
For multiplayer Browser ACK stalls, inspect the session error, drawing-buffer
size and presentation viewport. browser-canvas-budget.mjs bounds App canvases;
Snake also derives its presentation and screenshot size from that shared budget
to bound software Chromium composition. Keep the real network journey and finite
ACK policy. Startup admission waits for App's first completed frame before the
next client, not only the join command. Keep each client's Chromium process
independent: separate contexts still share a GPU process, so one device's startup
can stall another client's frame-driven ACKs. For Pack inventory coverage
timeouts, keep the oversized-cache boundary but use the existing small-input
snapshot owner for mutation checks.
Reuse these owners and the CI guide's disposable-project reducer when fixing
overload instead of introducing another probe or per-consumer patch.
For Dawn import costs, use the builder's prepared JSON serialization through the
shared manifest URL fixture. Do not expand and republish already verified blocks
or replace source validation with a path-only cache. Preserve native isolation;
passing assertions followed by worker termination warnings do not qualify a
shared-module experiment. The CI guide names the retained Browser/Dawn owners
for expensive shared fixtures and the explicit high-quality subsurface control.
For core upload stalls, distinguish CreateArtifact retries from blob transfer.
The CI guide owns the bounded PR upload and source recovery; retain independently
verified shared inputs when only core transport fails. Core transfer maps omit
embedded source text, not JavaScript mappings needed for coverage attribution.
Declarations are built from source without a remote declaration cache.
Lighting-channel Browser files use ordinary bounded batches; the Dawn
shadow-fields owner retains its twelve assertions in three native processes.
For Browser startup stalls, inspect Pack and authored material preparation: explicit groups
use their workspace owners and declared shared source roots, including material
contracts imported through shared test fixtures. Keep the original
deadline and first failure; do not restore whole-group automatic retries.
For core/shared-input stalls, inspect the shared native shader steps in ci.yml,
profile fingerprint and portable receipt before comparing cold compilation with
cache reuse. Cache restore/save have one-minute step deadlines; the segment
download timeout does not bound metadata lookup. A cache timeout must still reach
mandatory source/byte verification and source fallback, and must not start another
save request. Shared catalog timing must include the preceding profile preparation;
its explicit shader input is admitted before reuse and rebuilds when missing. The source producer
validates restored bytes and rebuilds misses; do not restore a second local receipt
or skip admission on an Actions cache hit. The CI guide names the retained
single-texture and standalone-manifest coverage owners.
Coverage prepares both base-SSAO and point-SSAO from admitted core/shared products.
If standalone SSAO or Vite manifest assertions recompile the full fleet, inspect
that preparation before changing their assertions. Cold source production and
worker lifecycle retain their focused owners.
SDK package verification owns the default production build; the custom-base
empty-project build retains direct CLI coverage. Do not rebuild the same unchanged
project immediately before packaging it.
For SDK subprocess failures, run pnpm test:sdk:contracts before the installed consumers.
For public-source View device loss, keep its Playwright browser-process output,
original tape and selected work index. Verify fresh-device disposal and real
captured-frame pixels; a local pass does not qualify the failed SDK consumer.
For npm-consumer ERR_HTTP_HEADERS_SENT, inspect the upstream body read before
response headers are committed. The SDK registry regression in sdk-lib.test.mjs
executes the build, preflight and publication listeners against an interrupted
HTTP response; preserve the 502 outcome and the next successful request.
For SDK packing, compare the shared archive writer's compression time and bytes;
its deterministic level 6 policy is shared by every npm carrier. Source build
work is serial and uses ordinary process priority inside the Runner's cgroup.
SDK doctor, tests, build and Browser share one disposable consumer copy; its
256-square shadow map retains the authored three cascades. The archive stays unchanged. Installed View retains JS/TS publication and cold reopening;
Game 3D build/input/rendering belongs to SDK Project and its complete Play/restart
journey belongs to Engine/View integration, without a second installed View run.
View Game 3D imports the reducer from the paired Engine checkout.
For its preparation Stop timeout, follow
Play preparation cancellation.
Retain the real Play gesture, matching request cancellation and original
30-second recovery; a previously observed Preparing label cannot classify a
later adopted Stop. Keep native readiness and cleanup as separate required evidence.
If an adopted Play is hidden before its document arrives, inspect presentation CSS:
Chromium suspends native iframe rAF under visibility:hidden. Keep it transparent
and pointer-inert until Engine cleanup acknowledgment; preserve the 120-second
bound and real frame/cleanup assertions.
MCP Host response contracts wait for actual query admission and drain native response events under the existing 500 ms reply bound. Preserve the three blocked queries, four exact successful replies and asynchronous service work when diagnosing timing failures.
For View tail latency, use the per-owner timings from run-view-integration.mjs.
Keep four shards and complete JS/TS publication chains; diagnostics and plugin
each own a shard, TS shares contracts/Game 3D, and Engine-only/JS share lifecycle/workspace. Preserve the real
post-profile game-state assertion and failure capture when removing redundant
diagnostic observations. Run the projectless no-WebGPU probe after backend restart,
before any project intent can start another GPU-owning game.
Diagnostics use the shared canvas budget; distinguish CSS layout from drawing
buffer size, and retain a real reallocation across hidden/resumed presentation.
After deliberate View target retirement, assert the lost state and use guarded
workspace reopen before mounting Scene on the new target. Do not navigate the
retired target and try to drain its asynchronous notices before tab clicks.
Select the RHI Debug tab explicitly after reload or service restart; the default
page is Scene. Preserve guarded target identity and the independent-run checks.
For replay device-limit failures, compare the capture and replay browser channels
and adapter limits. View's Linux default follows the shared browser configuration.
For Learn Render observation stalls, measure the complete quiet window with the
monotonic clock and restart it on new errors within the existing five-second
bound. Nine-light uses the existing exclusive Browser admission. Boss Lightning's
baseline/field and SDF commands keep separate Smoke receipt owners. See the
CI guide's Browser and managed VFX sections for these shared boundaries.
Full SDK Candidate retains four parallel consumer owners after source-producing
jobs; retain their full-scene profile window and require a complete seal. An
isolated consumer pass cannot qualify Promotion. For npm visibility or publication
transport failure, follow SDK release recovery:
rerun failed jobs in the completed Promotion instead of repeating successful
qualification and publication jobs. Distinguish submitted/staged npm bytes from
public metadata, exact tarball bytes and the fresh-consumer result.
For Candidate seed transport failures before verification, follow the
SDK consumer guide: reuse the bounded
downloader and keep exact artifact counts and source/byte checks. Retry failed
jobs only while the unchanged-source run's required artifacts remain complete;
source repairs, expired inputs or a cancelled run need a new Candidate. Retained
failed-run artifacts never authorize Promotion: the controller requires a
successful completed Candidate as well as the complete seal.
For an external transport-only failure, rerun failed jobs only. A passing test prefix, cancelled tail or missing artifact is not success. Compare measured job time and total runner occupation; queue time is reported separately. Keep new run evidence in the delivery PR, not appended to this skill.
Multithread frame-p95 comparison is an explicit bench:production diagnostic;
ordinary CI retains capability, Worker recovery and raw-kernel speedup in
shared-inputs-browser, reusing its setup without changing build dependencies.
GPU timing refusal, null-backend and artifact-validator unit assertions belong
to Render coverage; do not recreate their duplicate standalone job. Keep short
consumer probes out of core/shared, artifact and metrics producers. Use stable
benchmark conditions for end-to-end performance claims. CPU capacity and affinity
alone do not qualify them, and raw-kernel success is narrower evidence.
Copy timestamp envelopes include marker and synchronization overhead. Use the existing
60-frame gpu-pass-timing-copy.dawn.test.ts for ordering, bytes, query retirement and
recovery; a larger independent copy need not have a longer envelope. Do not restore
the duplicate copy-size comparison as a correctness gate.
Specular AA keeps its image reference and G-buffer replay falsifier. Do not restore
its deleted repeated cost report, which had no performance threshold. For a Dawn
lane cancellation, compare completed processes and the unfinished tail; an equal
container CPU budget does not establish equal runner speed or a passing estimate.
For managed scene-SDF failures, use the CI guide and its linked real-carrier evidence. Missing Pack indexes or field/program artifacts belong to app-shard preparation; prepare them before GPU admission.
For SDK dirty-source errors, inspect the named paths. Post-checkout cleanup of
retired submodules belongs only in disposable CI workspaces before preparation;
never clean a contributor checkout or disable source admission. For backend-stop
deadlines, keep the owner log and native disposal trace; a healthy game or complete
replay does not prove retirement. Follow the CI guide's build and recovery routes.
If a replay passes its pixel assertions but crashes during native shutdown,
trace the bootstrapDawn disposal lease through every caller. Await replay
disposal and the native owner; calling optional destroy on an opaque RHI
device does nothing. Follow the CI guide's native cleanup ordering, including
replacement timestamp devices, before treating the process as a pass.
The textures bootstrap retains its existing exclusive short-renderer owner and
original deadlines; an isolated passing run cannot replace complete CI.
For Browser Catalog HTTP failures, inspect the bounded failed-source response observation before investigating rendering. The observer retains the original scoped Catalog response without another request; unobserved bodies remain unverified. Preserve the original failed check and its producer error.
For a Preview Catalog startup timeout, distinguish a listening Vite server from accepted Pack production. Inspect the existing startup stage timings and native cooker admission; dev wrappers must retain explicit concurrency declarations. ScriptablePack only batches opted-in reentrant outputs, at most four, preserving authored result order and failure draining. Keep the Catalog deadline and full source closure; an isolated startup pass does not qualify the browser gate.
For native startup overhead or Preview first-frame timeouts, use the
CI guide. Inspect real frame
resources before reducing a smoke fixture. CI uses bounded native batches and
the shared test workload and
project reducer for ordinary fixtures.
Check captured dimensions when a scene omits quality fields: shared test reduction
must also bound engine defaults. Follow literal new URL Worker bootstraps
when auditing fixture quality; an ordinary geometry fixture must declare its
shadow map and cascade workload too. Include the existing DevKit runtime-browser
companion: Node filenames can own real Playwright drawing buffers. Keep explicit overrides for quality/capacity
owners, complete assertions and the original deadlines. For native replay cost,
check whether individual reads reset and replay the same GPU prefix. Batch
independent selected-work reads while retaining exact provenance, intermediate
bytes and fresh devices for independent falsifiers.
For authored Three shadow timeouts, join three-shadow-measure and
three-render-replay by the light/mutation label. Their milestonesMs are
cumulative from each operation's start, so subtract adjacent milestones to
locate capture, upstream rendering or cold replay cost. A scheduled replay is
not completed evidence. Keep the original case deadline and fresh replay devices.
If identical work is much slower in a full shard than in Focus, compare
runner-cpu-pressure counter deltas and the distinct container/host PSI scopes
over those phase windows. Preserve unavailable counters; cumulative throttling
totals and host pressure alone cannot assign a cause. Test partitioning is not
evidence that the complete original journey became faster.
Shadow phases must drain their own replay slots before passing. A successful
live/reference phase with queued replays is incomplete validation; leaving all
drains to the 60-second teardown can fail after every phase appears green.
For Nested Discard cost, retain its shared ordinary pixel assembly and bounded
shadow declaration. Temporal captures and replays stay independently owned; the
fixture's actual device and shadow inspections guard those boundaries.
For native Host failures, follow the CI guide's
build-input,
Rapier, and
Codec
owners. Check explicit Host initialization, the forgeax-native condition,
source identity and complete generated inventories before runtime diagnosis.
Preserve retryable initialization and real native tests; never intercept global
WebAssembly to hide a missing Host boundary. Actual simulator/device evidence
remains separate from Node qualification. UI fixtures without external Packs
use explicit Browser source selection while mixed selection retains its closure.
For compact manifest failures, inspect v4 source fragments and resolved receipt
facts; matching numeric indices are not matching ABI values. Frame-based probes
wait for the submitted receipt's completed-frame signal, not animation callbacks.
English-only guidance gate
Run python3 scripts/forgeax/check-agent-docs-english.py after changing agent
instructions. Preserve command/API identifiers and update links when headings
change. Localized ordinary README files remain permitted.
Symptom index
| Symptom | Likely cause | Reference |
CPU profiling needed on a Linux/CI host without a GPU; requestAdapter() returns null or only a software adapter | No usable GPU; software WebGPU would spend the measured CPU on emulation. | WebGPU stub |
| Textured demo shows a white square without texture or lighting gradient | Texture paramValues contain unresolved GUID strings instead of Handles. | White textures |
| spawn-data-unknown-field or invisible/gray entities | Misspelled/stale data field, such as MeshRenderer.material instead of materials. | Spawn fields |
| register MaterialAsset reports shader not registered | Stale shader identifier in pack.json. | Shader identifiers |
| CI fails despite all assertions passing | Unhandled rejection during teardown sets exit 1. | Exit status |
| Fresh worktree alone fails with ENOENT/unresolved package | Submodule initialization or build missing. | Worktree setup |
| Texture disappears after warm HMR | vite-plugin-pack DDC loses sourcePath or writes to source tree. | Pack HMR |
| Windows-only failures or CRLF diffs | Missing LF attributes or path-separator handling. | Windows |
| Upside-down cubemap | Redundant V-flip in skybox.wgsl. | Skybox V-flip |
| All CSM shadows fully lit despite valid matrices and running cascades | Negative viewZ compared to positive splitPlanes selects the near cascade; distant projections leave the tile and return 1.0. | CSM depth sign |
| Meshes do not cast shadows although castShadow is enabled | Hand-authored materials omit ShadowCaster and never enter the shadow depth pass. | ShadowCaster |
| Standard material black during cold startup or without IBL | Asynchronous Skylight cubemap is the only ambient source. | Ambient readiness |
| Multi-mesh glTF nodes bind every mesh's materials | Bridge fails to filter by meshIndex. | glTF materials |
One mesh missing while the rest of the frame renders; onError rhi-descriptor-invalid names a missing @location(N) | The material's vertex stage reads an attribute the mesh layout lacks; the renderer skips that draw instead of creating an invalid pipeline. Author the attribute (MeshBuilder completes normal/uv/tangent for triangle lists) or use a material that does not read it. | packages/render/src/vertex-input-guard.ts |
| pbr-skin pipeline fails with missing binding/vertex slot 5 | Skin shader reuses standard PBR layout; JOINTS_0/WEIGHTS_0 are not uploaded. | Skin pipeline |
| Browser skin black but Dawn passes; VBO 768 instead of 1152 bytes | Break in parser, bridge, mesh-loader, render-data, pipeline context, or extraction. | Attribute chain |
| hello-skin dev Fox black with asset-not-imported while smoke passes | Missing build/submodule or sibling using the port. | Fox dev loading |
| Skin remains in bind pose while clip/world matrices advance | Palette allocator/dynamic-offset/extract wiring, MAX_JOINTS overflow, or async instantiation before SkinAsset registration. Skin.joints.length=0 and JointCountMismatchError identify the latter; e5e68b35 added SceneAsset.skinGuids and fail-fast skin-asset-unresolved. | Static skin |
| Distorted/flipped FBX skin animation in historical SDK implementation | Removed binding.cc misread Euler degrees as quaternions and sampled one axis; ufbx bridge.c uses ufbx_evaluate_transform. | Historical FBX deformation |
| FBX parity snapshot fails | bridge.c drift in axis conversion, material classification, node filtering, or animation extraction. | FBX parity |
| FBX WASM ENOENT | Contributor checkout lacks generated pkg payloads. | FBX WASM |
| FBX WASM initializes in browser but fails in Node | ENVIRONMENT flags or Node version mismatch. | Node WASM |
| SkinPaletteOverflowError needs=16384 cap=16320 at first frame | MAX_JOINTS=256 exceeds the pbr-skin group-2 binding-1 capacity established by PR #361. | Palette overflow |
| Edge adapter-unavailable and black output | Browser settings disable hardware GL. | Edge configuration |
| Startup/release reports only WebGPU, adapter-unavailable, or object Object | Flattened diagnostics or only one backend channel observed; insufficient to declare the machine unsupported. | Capability diagnosis |
| WebGL2 fallback validation panic: storage/uniform mismatch or VIEW_FORMATS | Missing capability gates in variant keys, graph viewFormats, or texture reinterpretation. | Fallback gates |
| WebKit reports mesh SSBO ceiling 0 B and black scene | Downlevel defaults report maxStorageBufferBindingSize=0, incorrectly consumed as a real ceiling. | SSBO ceiling |
| WebKit black/GPU loss after submit without onError | wgpu error-sink failures never reach JS. | Submit errors |
| WebKit probe panics Surface does not exist while hello-triangle works | Probe main returns after a finite loop without retaining Renderer; GC finalizes the WASM Surface. | Probe lifetime |
| CI job, cache or skip behavior differs from old troubleshooting notes | Workflow layout has changed; verify the failing commit before applying historical advice | CI operating guide |
| GPU buffer/texture/cubemap counts grow throughout long sessions | Missing symmetric release in store eviction, instance buffers, transient resize, or handle-keyed WeakMaps. | Resource growth |
Open the relevant linked recipe; verify its hypothesis against the current failing frame or process. Package contracts remain the design authority.
For release-source-not-on-main or release-source-not-on-stable after a successful resolve step, follow shallow release ancestry. Compare complete branch history before assigning source drift; the release-policy owner must fetch sufficient history and still reject outsiders. Keep the sealed Candidate bytes and all publication guards.
For explicit Dawn preparation on a shared host, set CMAKE_BUILD_PARALLEL_LEVEL=1 to cap native compilation without changing the pinned source, device lease or gate budgets; see the Dawn carrier contract.
For green MCP checks with a black Scene or fatal Play screenshot, follow the
consumer acceptance gate.
Inspect the real screenshots, visible native fatal details and console errors;
old completed-frame counters and an empty pageerror array are insufficient.
Preserve the failing frame through RHI Debug. For local Vite cold-start delay,
check and prepare the packaged shader inputs after the last package build before
retrying the original browser deadline.
For a minimum-limit WebGPU PBR pbr-view-bgl binding mismatch, retain the first
native validation message before its invalid-bundle/submit cascades. Compare the
selected cooked program context with the actual View topology; storage buffers
do not imply the extended sampled-texture budget. Re-cook obsolete publications
through the Shader compiler owner, then verify the same browser and pixels.
For a required Runtime Pack plugin stuck in dependency retention, compare the same publication through native HTTP and the actual MCP iframe bridge. Preserve the first blocked stage and cancellation cause. Inspect resource sizes, MIME-independent wire compression and chunk counts before changing startup deadlines. A fast native read is an isolation control, not an MCP or GPU acceptance pass. For incompressible resources, verify the broker's 192 KiB window and the shared document/Worker/Node decoder: stride comes from the first actual chunk, with at most four reads in flight. Preserve full byte comparisons and response/cache bounds; rerun the nested consumer under the maintained runner CPU affinity. When raw artifact-cache misses repeat already installed material reads, inspect the existing material artifact owner before adding another cache or shrinking the publication. Capture may borrow its bytes by the frozen artifact digest, but must still verify the complete publication and reject altered bytes.
For an embedded Runtime Pack failure mentioning CacheStorage or ServiceWorker, read the structured game-operation error and inspect the native frontend's borrowed PackProgramHost capability. Preserve the sandbox and the executing Engine namespace identities. Reuse the real template interaction/recovery probe; frames and a healthy startup barrier do not prove the operation succeeded.
For an MCP renderer crash during Runtime Pack module import, preserve CDP crash
evidence and native browser stderr. Check runtime-import.mjs before attributing
heap growth to assets: remote compilation must not rewrite the adapter's captured
native importer into itself. Local UI generation must use ordinary button events
with native input validation; opaque documents have no form-navigation permission.
For a first Host timeout with a restoring-project header, inspect the recorded
nativeViewConnected value. Test native transport connection within 60 seconds;
project restoration shares the first Editor's 180-second frame deadline. Do not
measure the two owners through one temporarily overridden header label.
For MCP document failed with a transport request timeout after native View
connection, inspect document compilation separately from project restoration.
The presentation owns pending compilation; short document queries poll its
completed resource reference. Preserve RPC/source-read deadlines, bounded tasks,
replacement cancellation, terminal source failures and the complete native Scene,
Play/Stop and Backend recovery journey. See the MCP consumer gate.
For a direct-light attachment timeout after cold renderer creation, retain the complete file's existing lighting comparison before the attachment contract. The comparison admits cold preparation through its original budget; the separate attachment capture keeps its fresh World, completed-frame count, assertions and 15-second bound. Preserve the failed timing and require the complete Browser owner plus final-head CI; a local phase trace alone is diagnostic.
For a coverage tail with completed slow children and unfinished owners, keep completed receipts distinct from explicit reservations. Balance retained maxima after all admitted replay windows fit; do not optimize them away using an older fast cohort. Keep complete four-way waves, broad halves and source isolation; numeric modulo-rank spread is not an additional workload constraint. Verify all retained windows locally before pushing, with the original job deadlines, concurrency, coverage ownership and thresholds unchanged. For a Dawn step timeout, compare each complete native owner and ordinary child with its lane forecast. A final owner starting near the step deadline indicates placement exhaustion; refresh the completed-child receipts before rerunning. Retain complete startup/import/cleanup overhead across ordinary files, including skipped files, and every older independent snapshot. An interrupted multi-phase owner keeps its full forecast even when an early phase passed; add no partial timing sample. Require the same local red/green placement replay and final-head native execution.
If a Standard nonreceiver stalls in its first native GPU completion, retain the actual failing tape and inspect its declared shadow reception before changing budgets. The direct draw may project that source fact into the declared fragment specialization; mixed or unknown batches keep the conservative default. Verify receiver/nonreceiver lookup separation, unchanged pixels and positive dynamic shadow controls, then run the complete Browser owner with its original frames and deadlines.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

