Repository navigation
feat(cyborg): add a CAGE-2 example environment pack #21
Description
Activity
RAESystem/hub#10 has now established the federated catalog boundary for reusable example packs. Pack source belongs in an appropriate catalog repository (with
RAESystem/reference-packsas the first-party curated catalog) underenvironments/<pack-id>/, using a history- and provenance-preserving one-way transfer. This adapter repository retains simulator realization and backend-native evidence, then consumes the released pack identity; it should not retain a competing editable pack copy. The upstream format, validation, release, provenance, trust, and compatibility contracts remain owned byRAESystem/env-packs.Pack-completeness gap found during #36 (NASim pack).
cyborg/examples/cage2-research/is functionally present but does not pass the publishedraes-env-packsCLIs, verified empirically:raes-pack-validate --pack …/cage2-research→ FAIL (missingdocs/golden-readiness-checklist.md).raes-pack-release check --pack …/cage2-research→ SKIPPED / not releasable (nopack.compatibility.yamlwithartifact_boundaries).
Suggest adding to this issue's acceptance criteria: the pack passes
raes-pack-validateandraes-pack-release check, which requires addingpack.compatibility.yaml(withartifact_boundaries) anddocs/golden-readiness-checklist.md. Thenasim-tinypack (#36 / PR #76) is the reference that clears both.🛠️ Picked up by /implement - driver codex, branch
21-cage2-example-pack, 2026-08-08T21:09:43.135Z.gc workflow phase recorded:
preflight(issue #21). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.gc workflow phase recorded:
plan(issue #21). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.Implementation plan
- Reconcile the architecture note with the issue thread’s later authority decisions: do not add a competing top-level editable pack; treat the existing installed
cage2-researchtree as the adapter-owned, digest-sealed realization snapshot; keep the full Scenario2 SDL under issue docs(cyborg): author the validated CAGE-2 (Scenario2) SDL document #77 and pack-format authority inraes-env-packs==3.6.2. - Test-drive the release gap in
tests/test_researcher_cli.py: invoke the pinned publishedraes-pack-validateandraes-pack-release checkmodules against the packaged example, require both to exit zero, and require the release command to actually check (not skip)cage2-research. Confirm the new test fails first for the missing checklist and compatibility boundary. - Add the published pack-contract material under
src/raes_adapters/cyborg/examples/cage2-research/: apack.compatibility.yamlwith disjoint participant/operator boundaries, the supported qualified runtime profile, explicit assets/operator surface, and canonical validation gates; adocs/golden-readiness-checklist.mdthat keeps statusbuiltand reservesgoldenfor completed manual evidence; and the compatibility pointer inpack.yaml. - Complete the existing provenance record for CAGE source/evaluation material, RAES contract input, adapter-authored/generated content, redistribution/attribution, and explicit native/hidden-state exclusions. Keep adapter selection and native implementation details out of portable pack semantics.
- Reseal
pack.content-manifest.jsonwith the pinned publicraes-env-packsderivation API, then update the resulting set digest in the researcher tests, installed-distribution probe, and walkthrough so reference validation, automated rehearsal, and researcher documentation all use one identity. - Run the focused researcher test and both exact published pack CLIs, then the canonical verification graph. No
CHANGELOG.mdor changelog fragment will be edited.
Acceptance and design coverage
- Published pack validation/release: driven by the new failing regression and exact CLI runs.
- Drift and identity: every new/changed member is bound into the associated-artifact manifest; runtime and docs consume the same set digest. The full canonical Scenario2 replacement remains issue docs(cyborg): author the validated CAGE-2 (Scenario2) SDL document #77 rather than being silently invented here.
- Provenance and boundaries: provenance rows and compatibility boundaries separate participant-visible SDL/experiment/docs from operator-only participant controls, provenance, and golden review; leak scans use the published tooling.
- Reference triangle: existing installed-command validation, fake-driver rehearsal, distribution probe, and researcher walkthrough remain canonical and are rebound to the resealed digest.
- Packaging: the snapshot remains deliberate package data for the installed command; no top-level catalog copy, second distribution, lockfile, schema, validator, backend registry, or
raes_adapters.basesemantic authority is added. - Security: descriptor/digest admission, strict RAES models, participant leak scan, bounded diagnostics, relative output confinement, native-output suppression, and secret/argv/environment exclusions remain active.
- Maintainability/extensibility: reuse the NASim pack’s format shape only as a tooling precedent, while keeping CybORG identities and semantics module-local; future issue docs(cyborg): author the validated CAGE-2 (Scenario2) SDL document #77 content changes produce a new sealed pack identity without changing pack schemas or adapter dispatch.
- Reconcile the architecture note with the issue thread’s later authority decisions: do not add a competing top-level editable pack; treat the existing installed
Execution obligation QUALIFICATION-BUILD-BACKEND-DRIFT — Opened
Category: failing_check
Observed state: The canonical verification graph rebuilds the qualified CybORG wheels with an unconstrained PEP 517 backend and now produces a different normalized identity after setuptools 84.0.0 was published.
Impact: The required qualification gate cannot reproduce its pinned wheel evidence and blocks every repository verification run.
Current obligation: Pin the qualification wheel build backend from the qualification record and verify both original and patched wheels against the recorded identities.Evidence
- make verify: tools/verify_cyborg_qualification.py raised CybORG qualification original wheel identity mismatch
- unconstrained normalized wheel digest 35a5c20f... with setuptools 84.0.0
- setuptools==83.0.0 reproduces the recorded normalized digest ee61283f...
Execution obligation QUALIFICATION-BUILD-BACKEND-DRIFT — Resolved
Category: failing_check
Observed state: The qualification wheel builds now consume the recorded setuptools==83.0.0 constraint for both original and patched wheels.
Impact: The qualification gate again reproduces the pinned normalized wheel identities independently of newer backend releases.
Current obligation: Keep the qualification wheel builder constrained to its evidence-producing backend version.Evidence
- qualification.json records build_dependencies: setuptools==83.0.0
- both uv build invocations pass the same --build-constraints file
Disposition: fix
Corrective action: Recorded the build backend pin and applied it to both wheel builds in tools/verify_cyborg_qualification.py.Verification
- uv run pytest -q tests/test_cyborg_qualification.py: 6 passed
- uv run --frozen --extra cyborg python tools/verify_cyborg_qualification.py: CybORG qualification: OK
- ruff check and format check passed for the changed verifier and test
gc_codex_review — cycle 1 of 1 (pre-push) on issue #21 (branch
21-cage2-example-pack)
Diff mode: inline — the complete diff was supplied in one promptCore review
Verdict:
shipThis change is shaped correctly. Pack ownership and semantics remain with the published RAES and raes-env-packs contracts, while backend qualification and installed-example realization stay inside raes_adapters.cyborg; no competing schema, registry, or shared-base authority is introduced. The revised content identity is propagated through the manifest, CLI inventory, documentation, tests, and clean-install probe, and the qualification build pin is explicit backend evidence rather than ambient tooling state. The tests exercise the owning package’s validation and release gates, including the non-skip condition. The seam also preserves the obvious next variation: issue #77 can replace and reseal the authored pack content without changing adapter dispatch or inventing new semantic infrastructure.
No blocking findings.
Security review
Verdict:
shipThis change is shaped correctly: it extends the existing digest-sealed CybORG example pack with published compatibility, provenance, release-boundary, and readiness metadata while keeping runtime admission and validation at the established pack/adapter seam. It also constrains the native wheel build dependency and exercises the published validation gates without introducing dynamic imports, user-controlled subprocess arguments, credential handling, or new participant data projections. The obvious next variation—a reviewed replacement pack version and digest—remains available without weakening the current security boundary.
No blocking findings.
gc_codex_review pre-push cycle 1 of 1 complete for issue #21 on branch '21-cage2-example-pack'. Posted by the MCP server to enforce the pre-push hard-cap-1 contract (issues #796, #804, #906). Do not edit or delete — used by the next
gc_codex_review(uncommitted) invocation to count cycles.Review decision record — codex cycle 1 (issue #21)
Reviewer: codex
Cycle: 1Architectural read:
Core reviewer: This change is shaped correctly. Pack ownership and semantics remain with the published RAES and raes-env-packs contracts, while backend qualification and installed-example realization stay inside raes_adapters.cyborg; no competing schema, registry, or shared-base authority is introduced. The revised content identity is propagated through the manifest, CLI inventory, documentation, tests, and clean-install probe, and the qualification build pin is explicit backend evidence rather than ambient tooling state. The tests exercise the owning package’s validation and release gates, including the non-skip condition. The seam also preserves the obvious next variation: issue #77 can replace and reseal the authored pack content without changing adapter dispatch or inventing new semantic infrastructure.
Security reviewer: This change is shaped correctly: it extends the existing digest-sealed CybORG example pack with published compatibility, provenance, release-boundary, and readiness metadata while keeping runtime admission and validation at the established pack/adapter seam. It also constrains the native wheel build dependency and exercises the published validation gates without introducing dynamic imports, user-controlled subprocess arguments, credential handling, or new participant data projections. The obvious next variation—a reviewed replacement pack version and digest—remains available without weakening the current security boundary.
Blocking findings: 0 (clean run)
gc_test_quality_review cycle 1 of 1 — issue #21
Reviewer: test-quality (claude-sonnet-5 via gc_test_quality_review)
Branch:21-cage2-example-pack
Cycle: 1 / 1
Findings: 0 (clean run)gc_test_quality_review cycle 1 of 1 complete for issue #21 on branch '21-cage2-example-pack'. Posted by the MCP server to enforce the gc_test_quality_review hard-cap-1 contract (issue #884 follow-up, default lowered in #906). Do not edit or delete — used by the next
gc_test_quality_reviewinvocation to count cycles.Review decision record — test-quality cycle 1 (issue #21)
Reviewer: test-quality
Cycle: 1Architectural read:
Both diffs are narrow, low-risk updates to already-established test patterns rather than new test architecture. The qualification diff only refreshes two pinned digest/dependency literals in the CAGE-2 provenance ledger's golden-record test — that test's job is to detect drift in a static provenance JSON (whose actual reproduction happens out-of-band in tools/verify_cyborg_qualification.py), so asserting exact literal values is the correct shape, not a smell. The researcher-CLI diff adds one parametrized subprocess test that shells out to the published raes_env_packs.content_ci and raes_env_packs.release check CLIs against the packaged cage2-research example, asserting exit code, a success marker, and the explicit absence of a silent-skip marker (guarding against a false-positive pass if the pack path resolution silently no-ops). This mirrors an existing pattern already in the repo (test_nasim_backend.py::test_backend_import_is_dependency_light_and_lazy also spawns a subprocess without an integration marker), so it's consistent with the codebase's accepted convention for black-box-testing a published console entry point rather than a new structural choice introduced by this change. Neither diff introduces mock-only assertions, unasserted calls, or existence-only checks of security-relevant logic.
Blocking findings: 0 (clean run)
Pre-PR base synchronization
- Source:
refs/remotes/origin/devat8c39789f3198530caf303aa836aad11e5eb18260 - Outcome:
already_current - Published feature head:
e0e2b75759d2e50546535726b91b5e145713495f - Verified tree:
bdd3ef5fe025a4a2b2abb200265c12b69c08b776
- Source:
Execution obligation SONAR-MCP-TOKEN-MISSING — Opened
Category: workflow
Observed state: The implementation, local canonical gate, pre-push reviews, publication, and CI completed, but Sonar analysis could not be queried because the MCP host lacks SONAR_TOKEN.
Impact: PR #78 cannot receive the required Sonar pass/skip evidence or the pre-merge readiness record.
Current obligation: Restore SonarCloud authentication on the Ground Control MCP host and rerun the PR monitor through a terminal Sonar result.Evidence
- Ground Control monitor job job-mskx8fti-7 reached the Sonar stage after PR feat(cyborg): complete CAGE-2 example pack #78 CI monitoring.
- gc_watch_sonar_analysis returned sonar_watch_token_missing: SONAR_TOKEN env var is not set on the MCP host.
Execution obligation SONAR-MCP-TOKEN-MISSING — Escalated
Category: workflow
Observed state: SONAR_TOKEN is not set on the MCP host; credential provisioning is outside the repository change and requires external environment authority.
Impact: The implementation PR is open and CI has completed, but the mandatory Sonar/readiness phase cannot finish until the MCP host can authenticate.
Current obligation: Restore SonarCloud authentication on the Ground Control MCP host and rerun the PR monitor through a terminal Sonar result.Evidence
- Open obligation record: feat(cyborg): add a CAGE-2 example environment pack #21 (comment)
- Ground Control monitor returned sonar_watch_token_missing for PR feat(cyborg): complete CAGE-2 example pack #78.
Pause class: hard_external_dependency
Decision request: Configure SONAR_TOKEN in the Ground Control MCP host environment (without posting the token here), then tell me to resume so I can rerun PR #78 monitoring and readiness.This obligation remains open while the decision is pending.
Execution obligation SONAR-MCP-TOKEN-MISSING — Resolved
Category: workflow
Observed state: The MCP process still cannot inherit a shell-local environment refresh, but the authorized credential is available after sourcing ~/.bashrc and the exact required Sonar results were verified without exposing it.
Impact: The mandatory Sonar evidence is now available, so post-merge completion can proceed.
Current obligation: Restore SonarCloud authentication on the Ground Control MCP host and rerun the PR monitor through a terminal Sonar result.Evidence
- PR feat(cyborg): complete CAGE-2 example pack #78 SonarCloud quality gate returned OK.
- PR feat(cyborg): complete CAGE-2 example pack #78 SonarCloud issue search returned 0 open issues.
- PR feat(cyborg): complete CAGE-2 example pack #78 SonarCloud hotspot search returned 0 open hotspots.
Disposition: fix
Corrective action: Loaded the operator-provided shell environment without reading or printing the credential, then queried the SonarCloud quality gate, issue search, and hotspot search APIs for PR #78 using credential material only from process environment.Verification
- quality_gate=OK
- open_issues=0
- open_hotspots=0
Final report — issue #21 complete
PR: #78
Plan: #21 (comment)Outcome
Researchers can now install the bounded CAGE-2 example and run the published content and release checks successfully. The pack records its compatibility, provenance, readiness limits, and reproducible CybORG qualification inputs.
Completed and validated the installed CAGE-2 research example pack, including release metadata, documentation, regression coverage, and reproducible qualification.
Files changed
Added:
docs/decisions/cyborg-cage2-example-pack-guardrails.mdsrc/raes_adapters/cyborg/examples/cage2-research/docs/golden-readiness-checklist.mdsrc/raes_adapters/cyborg/examples/cage2-research/pack.compatibility.yaml
Modified:
docs/index.mddocs/researcher-command.mdmkdocs.ymlnoxfile.pysrc/raes_adapters/cli.pysrc/raes_adapters/cyborg/examples/cage2-research/docs/provenance-ledger.yamlsrc/raes_adapters/cyborg/examples/cage2-research/pack.content-manifest.jsonsrc/raes_adapters/cyborg/examples/cage2-research/pack.yamlsrc/raes_adapters/cyborg/qualification.jsontests/test_cyborg_qualification.pytests/test_researcher_cli.pytools/verify_cyborg_qualification.py
Reviews
- codex: Clean production-readiness review; all 15 changed files were covered with no findings.
- test-quality: Clean test-quality review with no findings.
Traceability reconciliation
- IMPLEMENTS / TESTS / DOCUMENTS added: 0
- Links updated: 0
- Stale links removed: 0
Issue 21 has no in-scope requirement UIDs and this repository has no docs/requirements tree; no requirement-file links required reconciliation.
Status
- CI: ✅ green
- SonarCloud: ✅ passed
- PR ready for user review and merge.
Objective
Ship one concrete, validated environment-pack example alongside the CybORG adapter so researchers can see the complete RAES-to-simulator workflow.
Scope
environments/cyborg-cage2/as downstream example content, not package code or env-packs format authority.raes-env-packstemplate and validate with the pinned package/tooling.draft,built, orgoldenonly according to evidence actually produced.Acceptance criteria
raes-pack-validateandraes-pack-release checkpass for the example pack.RAESystem/env-packsremains format/tooling-only and receives no scenario content.References