Repository navigation
docs(cyborg): complete the pinned CAGE-2 source ledger and loss disclosures #13
Description
Activity
🛠️ Picked up by /implement - driver codex, branch
13-complete-source-ledger, 2026-07-30T02:27:53.059Z.gc workflow phase recorded:
preflight(issue #13). 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 #13). 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
- Keep the preflight guardrail note and its docs navigation updates. Preserve
qualification.jsonas the single source/profile/legal authority and extend only itsselected_filesclosure for action, observation, reward, and turn/admissibility sources actually consumed by the ledger. - Write failing tests first for strict JSONL parsing, closed row fields, duplicate IDs, both required coverage axes (source families and semantic fact facets), source/profile/path/digest joins, selector reachability in a detached source tree, schema-bundle target resolution, disposition rules, and exact multi-tier loss/disclosure agreement. Include negative cases for changed pins/digests, missing categories/facets, unclassified facts, unresolved selectors/targets, orphan losses, and native payload leakage.
- Add a module-local immutable evidence selection and validator under
raes_adapters.cyborg. Reuseload_qualification(),importlib.resources,schema_bundle(), and the qualification driver’s confined source-tree handling. Resolve targets generically from published schema-bundle keys and JSON pointers; parse upstream YAML/Python/text selectors without importing or executing upstream code; return bounded row/field/reason problems. Do not add sharedbasesemantics, RAES schemas/vocabulary, registries, exception hierarchies, persistence, or a new CI/policy gate. - Replace the placeholder ledger and disclosures with atomic rows covering every required source family and fact facet: topology, hosts, services, accounts, privileges, roles, participants, initial knowledge, visibility, hidden truth, actions, admissibility, turn order, trial lengths, termination, red variants, seeds/stochastic controls, reward components, objectives, derived measures, and provenance/licensing. Each row will join the qualified commit/path/digest, use a verifiable selector, have exactly one disposition, and map only to published RAES surfaces. Existing runtime, seed, wrapper, source-defect, and evaluator-policy losses will state the exact authored-source, contract, execution-control, state/observation, and/or outcome/evaluation claims they weaken; a complete ledger will not change the profile’s
not-admissibledecision or claim equivalence. - Update the mapping README to document the machine-checked row contract, coverage axes, claim limits, and reusable legal/attribution references. Add
.codex/to.gitignoreas requested, without stashing or deleting the local directory. - Run focused CybORG ledger/qualification tests during red-green-refactor, then the canonical verification graph:
uv tool run --from 'nox[uv]==2026.4.10' nox -f noxfile.py -s verify. Ground Control parsed this issue with no formalRequirementssection, so the workflow will use its explicit requirement-free binding while preserving the issue’s REP-003/ADR-069 references. Keep the single distribution/lock, do not touchCHANGELOG.md, and publish with a Conventional Commit title.
- Keep the preflight guardrail note and its docs navigation updates. Preserve
gc_codex_review — cycle 1 of 1 (pre-push) on issue #13 (branch
13-complete-source-ledger)
Diff mode: inline — the complete diff was supplied in one promptCore review
Verdict:
ship-with-fixesThe change is architecturally well placed: CybORG-specific evidence and validation remain inside
raes_adapters.cyborg, published RAES schemas remain the target authority throughschema_bundle(), qualification remains the source-pin owner, and the existing verification driver is extended rather than replaced.EvidenceSelectionis an appropriate seam for another reviewed source revision without introducing shared backend semantics. The blocking issue is in the primary evidence artifact: several rows make claims beyond the file and selector they cite, defeating the promised independently reviewable source-to-mapping join even though the structural validator passes them.Blocking findings (1):
- [class] Ledger claims are not bounded by their cited source selectors —
src/raes_adapters/cyborg/mapping/cage2-source-ledger.jsonl:27
This row cites onlyMeander.pyandRedMeanderAgentbut classifies B-line, Meander, and Sleep as condition variants. The same evidence-integrity problem recurs where the port-mismatch row relies on an uncited successor source and where the BlueLoadAgent row citesget_actionwhile asserting evaluator wiring and constructor/fallback behavior from other locations. Because validation proves only that each declared selector exists, all three rows pass while their material claims cannot be reviewed from their coordinates. Split the facts into rows tied to the qualified files and exact symbols that establish them; where a claim is qualification-owned, bind it through a resolvable qualification reference.
Security review
Verdict:
shipThis change is shaped correctly: it adds backend-local, immutable source-ledger evidence and composes it with the existing qualification boundary without introducing an endpoint, authentication surface, persistence layer, dynamic execution, or new semantic authority. The security-relevant seam is the detached-checkout validator, which confines resolved paths beneath the checkout root, verifies qualified SHA-256 identities, parses Python selectors through AST without execution, and emits bounded errors. The explicit EvidenceSelection also leaves the obvious next variation—a separately qualified source revision—with a data-driven extension point. I found no concrete, exploitable security issue introduced by the diff.
No blocking findings.
- [class] Ledger claims are not bounded by their cited source selectors —
gc_codex_review pre-push cycle 1 of 1 complete for issue #13 on branch '13-complete-source-ledger'. 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 #13)
Reviewer: codex
Cycle: 1Architectural read:
Core reviewer: The change is architecturally well placed: CybORG-specific evidence and validation remain inside
raes_adapters.cyborg, published RAES schemas remain the target authority throughschema_bundle(), qualification remains the source-pin owner, and the existing verification driver is extended rather than replaced.EvidenceSelectionis an appropriate seam for another reviewed source revision without introducing shared backend semantics. The blocking issue is in the primary evidence artifact: several rows make claims beyond the file and selector they cite, defeating the promised independently reviewable source-to-mapping join even though the structural validator passes them.Security reviewer: This change is shaped correctly: it adds backend-local, immutable source-ledger evidence and composes it with the existing qualification boundary without introducing an endpoint, authentication surface, persistence layer, dynamic execution, or new semantic authority. The security-relevant seam is the detached-checkout validator, which confines resolved paths beneath the checkout root, verifies qualified SHA-256 identities, parses Python selectors through AST without execution, and emits bounded errors. The explicit EvidenceSelection also leaves the obvious next variation—a separately qualified source revision—with a data-driven extension point. I found no concrete, exploitable security issue introduced by the diff.
Blocking findings: 1
Finding 1 —
class(3 instances)- ID:
F1 - Title: [core] Ledger claims are not bounded by their cited source selectors
- Location:
src/raes_adapters/cyborg/mapping/cage2-source-ledger.jsonl:27 - Decision: fix
- Rationale: This row cites only
Meander.pyandRedMeanderAgentbut classifies B-line, Meander, and Sleep as condition variants. The same evidence-integrity problem recurs where the port-mismatch row relies on an uncited successor source and where … - Instances:
src/raes_adapters/cyborg/mapping/cage2-source-ledger.jsonl:10src/raes_adapters/cyborg/mapping/cage2-source-ledger.jsonl:27src/raes_adapters/cyborg/mapping/cage2-source-ledger.jsonl:32
- ID:
gc_test_quality_review cycle 1 of 1 — issue #13
Reviewer: test-quality (claude-sonnet-5 via gc_test_quality_review)
Branch:13-complete-source-ledger
Cycle: 1 / 1
Findings: 1Finding 1 — [critical]
tests/test_cyborg_source_ledger.py::test_mapped_out_of_scope_and_loss_disclosed_shapes_fail_closedProblem: validate_source_ledger's disposition-consistency rules are only half-tested: 'mapped row requires target' and 'out-of-scope row cannot map a target' are exercised, but the sibling 'mapped row cannot declare a loss' (source_ledger.py:441-444) and 'out-of-scope row cannot declare a loss' (source_ledger.py:450-457) branches have no corresponding negative test anywhere in the file.
Why it matters: This module's stated purpose (per docs/decisions/cyborg-cage2-source-ledger-guardrails.md) is to fail closed against an 'ambiguous row' that mixes disposition semantics -- e.g. a row marked mapped (implying a clean target join) that also smuggles a loss_disclosure/equivalence_tiers, or an out-of-scope row that carries an unaccounted loss reference. If those two guard clauses were deleted or weakened in a future edit, this test suite would still pass in full, silently reopening exactly the ambiguous-row failure mode the guardrails doc calls out by name.
Fix: Extend test_mapped_out_of_scope_and_loss_disclosed_shapes_fail_closed with two more cases: take the mapped scenario-topology row and set loss_disclosure/equivalence_tiers, asserting a loss_disclosure problem surfaces; take the out-of-scope legal-root-license row and set loss_disclosure, asserting the same.gc_test_quality_review cycle 1 of 1 complete for issue #13 on branch '13-complete-source-ledger'. 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 #13)
Reviewer: test-quality
Cycle: 1Architectural read:
This is a well-shaped test suite for a new fail-closed evidence validator. It follows the established repo pattern (the ADR explicitly points at
cyberbattlesim.scenario_ledger's strict-JSONL/coverage/negative-test style): pure functions (parse_ledger_rows,resolve_raes_target,resolve_qualification_ref,_selector_shape_is_valid) are unit-tested directly with no mocking, and the compositevalidate_source_ledger/validate_source_checkoutfunctions are exercised by mutating one field at a time off real committed ledger rows (via a shared_row/_validatehelper) and asserting the specificLedgerProblem.fieldthat must surface.tmp_pathis used for the genuinely filesystem-touching selector/path-confinement checks rather than mockingPath/osinternals, which is the right call for that boundary. The seam is correct and doesn't foreclose the obvious next variation (a new source family, fact facet, or loss tier). The one real gap is a coverage hole inside the disposition-consistency rule set, not a shape problem with the harness.Blocking findings: 1
Finding 1 —
class(2 instances)- ID:
F1 - Title: (no title)
- Decision: fix
- Rationale: Addressed by next cycle
- Instances:
src/raes_adapters/cyborg/source_ledger.py:441-444 (mapped row cannot declare a loss — untested)src/raes_adapters/cyborg/source_ledger.py:450-457 (out-of-scope row cannot declare a loss — untested)
- ID:
Pre-PR base synchronization
- Source:
refs/remotes/origin/devat36678c76b23d24f08ce569ed4f51657550ec7c08 - Outcome:
already_current - Published feature head:
5182015b889371aaa25c1cd7476fc75dc9cef7b9 - Verified tree:
2d2aff0ee00230dc575a346dc23beb487a47ed85
- Source:
Pre-PR base synchronization
- Source:
refs/remotes/origin/devat36678c76b23d24f08ce569ed4f51657550ec7c08 - Outcome:
already_current - Published feature head:
c426b76a95814cfa0f1b2eb54c1b5220d92b70f6 - Verified tree:
37dee8bedb1b5a8b8c073c4623b83ca603fc5e3f
- Source:
Pre-PR base synchronization
- Source:
refs/remotes/origin/devat36678c76b23d24f08ce569ed4f51657550ec7c08 - Outcome:
already_current - Published feature head:
9fc2894328e0b262808d65b4fa15362a4b1bb75b - Verified tree:
a29f183bfd5ac7ad94ebf906c6be67fbd445be55
- Source:
Ready for review — issue #13
PR: #57
Plan: #13 (comment)Outcome
Maintainers can now audit every consumed CAGE-2 fact against immutable upstream bytes, a verifiable selector, and a published RAES target or explicit scope boundary. Loss disclosures bound the permitted replication claims by equivalence tier.
Pinned CAGE-2 source evidence is machine-verifiable and claim-limited.
Files changed
Added:
docs/decisions/cyborg-cage2-source-ledger-guardrails.mdsrc/raes_adapters/cyborg/source_ledger.pytests/test_cyborg_source_ledger.py
Modified:
.gitignoredocs/index.mdmkdocs.ymlsrc/raes_adapters/cyborg/mapping/README.mdsrc/raes_adapters/cyborg/mapping/cage2-loss-disclosures.mdsrc/raes_adapters/cyborg/mapping/cage2-source-ledger.jsonlsrc/raes_adapters/cyborg/qualification.jsontools/verify_cyborg_qualification.py
Reviews
- codex: Cycle 1 found a source-fact citation consistency class; every instance was split or rebound to exact qualified sources, selectors, or qualification records. The user directed proceeding without an over-cap cycle.
- test-quality: Cycle 1 found missing negative coverage for two disposition/loss guards; both cases were added and the canonical graph passed. The user directed proceeding without an over-cap cycle.
- SonarCloud: Two analysis repair cycles cleared all initial and residual findings; the quality gate is OK with zero open issues and zero hotspots.
Traceability reconciliation
- Pending — requirement status transition and IMPLEMENTS/TESTS reconciliation run in Phase E once the PR merges.
Status
- CI: ✅ green
- SonarCloud: ✅ passed
- PR ready for user review and merge. Ground Control reconciliation (requirement status + traceability) runs on merge (Phase E).
gc workflow phase recorded:
traceability_reconciled(issue #13). 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.no in-scope requirements; touched-files audit clean.
gc workflow phase recorded:
traceability_reconciled(issue #13). 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.no in-scope requirements; touched-files audit clean.
Final report — issue #13 complete
PR: #57
Plan: #13 (comment)Outcome
Maintainers can now audit every consumed CAGE-2 fact against immutable upstream bytes, a verifiable selector, and a published RAES target or explicit scope boundary. Loss disclosures bind the permitted replication claims by equivalence tier.
Pinned CAGE-2 source evidence is merged, machine-verifiable, and claim-limited.
Files changed
Added:
docs/decisions/cyborg-cage2-source-ledger-guardrails.mdsrc/raes_adapters/cyborg/source_ledger.pytests/test_cyborg_source_ledger.py
Modified:
.gitignoredocs/index.mdmkdocs.ymlsrc/raes_adapters/cyborg/mapping/README.mdsrc/raes_adapters/cyborg/mapping/cage2-loss-disclosures.mdsrc/raes_adapters/cyborg/mapping/cage2-source-ledger.jsonlsrc/raes_adapters/cyborg/qualification.jsontools/verify_cyborg_qualification.py
Reviews
- codex: Cycle 1 found a source-fact citation consistency class; every instance was split or rebound to exact qualified sources, selectors, or qualification records. The user directed proceeding without an over-cap cycle.
- test-quality: Cycle 1 found missing negative coverage for two disposition/loss guards; both cases were added and the canonical graph passed. The user directed proceeding without an over-cap cycle.
- SonarCloud: Two analysis repair cycles cleared all initial and residual findings; the quality gate is OK with zero open issues and zero hotspots.
Traceability reconciliation
- IMPLEMENTS / TESTS / DOCUMENTS added: 0
- Links updated: 0
- Stale links removed: 0
No formal requirement UIDs were in scope; the post-merge touched-file orphan-link audit passed with no drift.
Status
- CI: ✅ green
- SonarCloud: ✅ passed
- PR ready for user review and merge.
Objective
Replace the placeholder mapping files with the reviewable evidence bridge required by REP-003 and RAES ADR-069.
Scope
Using the runtime/source profile selected in this milestone:
Acceptance criteria
References
docs/decisions/cage-2-replication-design.md