ci: parallelize selected PR checks and simplify contributor docs

[thomasklemm]

Why

Reduce PR feedback latency without dropping coverage or running every target unnecessarily. At the same time, replace the historical development/CI documentation sprawl with concise contributor guidance and executable contracts owned by the code.

Changes

• Start selected producers and comparisons when their inputs are ready, rather than after Unit. Build a same-run debug compiler independently for Campfire consumers.
• Split all integration targets across three bounded Unit shards, retaining library/binary tests, the debug bench gate, failure propagation, and complete target coverage. Run the three Campfire GC comparisons concurrently; allow all seven selected extra comparisons to start in parallel.
• Preserve change-based job selection. Unlabeled drafts retain the fixture/Unit floor; ci:full also expands drafts. Keep publication permissions and gates separate from PR validation.
• Reuse compiled gems for archive smoke while still extracting fresh archives and executing every README command. Key uv's download cache to the emitted Python dependency template instead of nonexistent repository manifests.
• Standardize active Node workflows and generated prerequisites on Node 24; update compatible Actions. Centralize CI MRI selection and the local Ruby minimum, leaving JRuby and exact reproduction pins separate.
• Isolate both Active Storage roots for parallel interpreted Campfire files, with unchanged Ruby launch arguments, identity, environment, and deterministic results. Keep Spinel execution serial and fall back to serial when mount isolation is unavailable.
• Simplify and reorganize contributor documentation. Development guidance owns the local loop; the CI handbook explains coverage, results, and publication boundaries. Remove redundant internal prose specifications and keep implementation contracts beside their owners.

Verification and limits

The previous exact-head hosted run completed successfully in 12:17, with no failed underlying steps. Both independent Thermos reviews and their follow-up checks found the material review findings resolved.

The subsequent seven-way comparison fan-out, uv cache-key correction, and integration of current canonical main have passed local combined checks. Their fresh hosted run is still pending; the owner explicitly requested merging before it completes, with post-merge verification to follow.

Known limits:

• The under-ten-minute goal and lower aggregate runner usage are not yet demonstrated.
• Hosted runners refuse the current unprivileged mount probe, so Campfire correctly uses the serial fallback there; local parallel timings are not a hosted speedup claim.
• The latest stable Swift setup action still declares Node 20 and emits the runner's migration warning. No stable Node-24 replacement exists yet; do not downgrade Node or adopt an unreleased action just to silence it.
• The hosted ci:full label-event test remains a follow-up. Compiler/modeling warnings and platform-dependent Campfire floors were not suppressed or blindly regenerated.

Integration

Includes the unchanged documentation foundation from #351. Current canonical main was merged into this branch, preserving contributor commits; the Spinel guide retains both upstream asset/OCRAN guidance and the Node 24 prerequisite. GitHub also marked #351 as merged automatically when its unchanged head became part of canonical main; no manual closure or branch deletion was performed.

No release, deployment, or manual Full validation dispatch is included.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: e395ed96-05fb-4939-b668-c43da1462fb0

📥 Commits

Reviewing files that changed from the base of the PR and between 71a5ee5 and 85f1a6e.

📒 Files selected for processing (14)

• .github/workflows/ci.yml
• .ruby-version
• bin/rh
• docs/ci/README.md
• docs/development/README.md
• docs/guide/targets.md
• scripts/campfire-suite
• scripts/ci-plan.py
• src/project.rs
• tests/ci_campfire_optimization_test.py
• tests/ci_plan_test.py
• tests/ci_policy_workflow.rs
• tests/ci_toolchain_workflow.rs
• tests/rh_verify_test.rb

🚧 Files skipped from review as they are similar to previous changes (2)

• src/project.rs
• docs/guide/targets.md

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 7 remain after this review.

---

📝 Walkthrough

Walkthrough

CI now shards unit tests, builds a shared debug binary for Campfire jobs, and updates job concurrency and caching. Campfire Ruby runs can use isolated parallel workers. Tool checks and generated instructions require Node.js 24. Contributor and CI documentation has been reorganized.

Changes

CI and Contributor Workflow

Layer / File(s)	Summary
Unit sharding and shared binary .github/workflows/ci.yml, scripts/ci-unit-tests.py, scripts/ci-plan.py, tests/ci_unit_tests_test.py, tests/ci_plan_test.py, tests/ci_policy_workflow.rs, tests/workflow_yaml_parses.rs	Unit integration targets run in three shards, with library and binary tests limited to shard 0. A separate build-roundhouse job publishes the debug binary used by Campfire consumers. CI selection and result checks cover the updated job plan.
CI lanes and action updates .github/workflows/ci.yml, .github/workflows/release.yml, tests/ci_policy_workflow.rs, tests/workflow_yaml_parses.rs	The workflows update action versions, job dependencies, and matrix concurrency. Ruby and JRuby archive smoke jobs prepare and reuse Bundler dependencies.
Isolated Campfire Ruby runs scripts/campfire-suite, tests/ci_campfire_optimization_test.py, tests/ci_policy_workflow.rs	Ruby test files run in parallel only when namespace and bind-mount checks succeed. Workers use separate storage paths, and results are tallied in file order. Tests cover isolation and serial fallback.
Node.js 24 minimum and smoke counts bin/rh, src/emit/typescript/package.rs, src/project.rs, scripts/smoke, scripts/campfire-archive-files, docs/guide/*, tests/ci_smoke_test.py, tests/ci_policy_workflow.rs	doctor checks installed versions against minimum requirements. Node.js 24 is the minimum for the Node prerequisite, emitted Node types, and generated project instructions. Smoke parsing accepts two Node test pass-summary formats.
Contributor documentation and references AGENTS.md, DEVELOPMENT.md, README.md, docs/README.md, docs/ci/*, docs/development/*, docs/data/*, docs/guide/*, docs/pipeline/*, docs/env-gates.md, docs/ci-reuse.md, scripts/ci-reuse.py, tests/docs_references.rs	Contributor setup and task guides are added or reorganized. CI and verification documentation describes coverage selection and evidence limits. Links and documentation reference checks are updated.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to 85f1a

No actionable regression remains from this review. The GC reporting issue predates the change, so it does not prevent this PR from merging after normal checks.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 85f1a

Earlier execution and parallel workers retain the inspected validation and publication controls. No introduced security vulnerability was established. Risk remains low rather than minimal because interruption handling and some affected surfaces are not fully verified.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The inspected authority changes are bounded to validation runners, their artifacts, and the local caller's execution context. Storage isolation is not a general sandbox: workers retain the application's working tree, launch environment, and access outside the two mounted storage roots.

Trust Boundaries and Controls

• observed — Publication requests are restricted to the canonical repository, main branch, and scheduled or manually dispatched full caller. Earlier producer execution does not remove the compact validation gate or grant deployment permissions to PR validation.
• observed — The existing publication policy permits failed extra-target results to be exposed as reproduction evidence, not successful validation certification, after archive-byte verification. Campfire conformance remains in the required compact floor. This policy predates the PR and is not an introduced concern.

Resilience and Maintainability Implications

• observed — Isolation failure does not silently enable unisolated parallel execution, and absent worker status cannot produce a passing file row. These controls preserve failure visibility despite tolerated worker-command failures.

Hardening Proposals

• proposed — Make worker cancellation and join-before-cleanup ownership explicit, and validate parent-only and process-group interruption. Document exclusive ownership of a reused emit, or enforce it if independent concurrent invocations are intended. These address unresolved lifecycle coverage, not an established vulnerability.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 28.36% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 67 functions across 14 files. (7 skipped:…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main CI parallelization work and the contributor documentation changes.

Full details: Docstring Coverage

Explanation

Docstring coverage is 28.36% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 67 functions across 14 files. (7 skipped: 7 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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