docs: rewrite the README around a verified researcher quickstart

[Brad-Edwards]

Objective

Make the repository front door useful to AI security researchers who want to run or adapt a simulator study, without requiring them to understand adapter architecture first.

Reader path

The README should:

• explain in plain language what RAES adapters let a researcher do and what they do not prove;
• show the shortest supported install and CAGE-2 example run from a clean environment;
• show the expected concise result and where the portable scenario, run, evidence, and report artifacts are written;
• explain how to change an agent, seed, trial length, or environment pack;
• link to the example pack, a full reproduction recipe, current limitations, citation/provenance, and troubleshooting;
• list supported adapters/profiles with honest maturity and evidence status; and
• route adapter implementers and maintainers to separate developer documentation.

Move build, CI, repository layout, release, governance, and contributor mechanics out of the main reader flow and into a clearly linked developer index. Preserve authoritative ADRs and records; do not present them as the user tutorial.

Acceptance criteria

• A researcher with Python but no RAES internals can reach a successful short run by following the README verbatim.
• The quickstart is exercised from the published distribution in a clean environment.
• Every shown command and expected output is checked in CI or a documentation smoke test.
• The README distinguishes scenario validity, adapter conformance, run completion, and research claims.
• Limitations cover simulator abstraction, stochasticity, source pins, unsupported facts, compute cost, and non-production scope.
• Developer material remains available outside the README and is reachable from CONTRIBUTING/docs navigation.
• The prose is technical and neutral, with no roadmap or promotional claims presented as evidence.
• Tests are updated for the implemented behavior and the relevant targeted/native plus canonical verification commands are actually run and pass before acceptance.

Reference

Use the task-first structure and progressive disclosure of the RAES README as the local model; adapt it to an installed simulator workflow rather than copying it.

[Brad-Edwards]

🛠️ Picked up by /implement - driver codex, branch 23-researcher-quickstart, 2026-08-14T17:37:20.847Z.

[Brad-Edwards]

gc workflow phase recorded: preflight (issue #23). 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.

[Brad-Edwards]

gc workflow phase recorded: plan (issue #23). 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

The executable front door will be the installed CAGE-2 hermetic conformance run. It succeeds without native CybORG, produces bounded portable adapter evidence, and will be labelled explicitly as neither a simulator episode nor a research result. Native smoke/study remains fail-closed while RAES cannot validate the packaged task's evidence witness.

1. Drive the documentation contract with tests (Path A). Add tool tests for an explicitly marked README quickstart contract: one closed argv shape, exact bounded JSON output, and the expected relative artifact tree. Reject shell metacharacters, extra commands, absolute/traversing output paths, and missing/duplicate markers.
2. Implement the safe documentation smoke (Path A). Add a repository tool that parses only the marked quickstart blocks, validates their closed shape without a shell, and can execute the admitted command with a caller-supplied installed runner in an isolated directory. Extend the existing distribution session to run it against the built wheel and validate the emitted inventory/report artifacts.
3. Rewrite the researcher front door (Path D, covered by the executable smoke). Replace architecture-first README material with purpose/non-claims, a clean Python 3.12 install, the verified CAGE-2 conformance command, exact output/artifact locations, interpretation of scenario validity vs conformance vs run completion vs research claims, constrained variation guidance, a current support/evidence table, limitations, and stable links to the example pack, full reproduction recipe, provenance/citation, troubleshooting, and developer docs.
4. Preserve developer material outside the reader path (Path D). Add a maintainer/developer index for build, CI, layout, packaging/release, governance, and adapter contribution mechanics; link it from CONTRIBUTING, the documentation home, and MkDocs navigation. Preserve existing ADRs and the current user-owned documentation changes.
5. Check both publication boundaries (Path A). Extend the existing post-PyPI release smoke to run the same CAGE-2 conformance command from the exact published version and assert the bounded output plus artifact tree. Extend the existing project-services policy assertions so CI cannot silently drop this release check.
6. Verify proportionately. Run the new tool tests first, then the targeted CybORG CLI and project-services tests, the built-distribution smoke, strict docs, and the canonical requirement-free verification graph.

Acceptance/TDD mapping

• Successful short run without RAES internals → Path A: built-wheel and exact-version public-index conformance smoke.
• Published distribution in a clean environment → Path A: existing distribution and release-smoke gates, extended rather than duplicated.
• Every displayed command/output checked → Path A: closed marked-block parser plus installed-run execution.
• Four claim levels distinguished → Path D: README interpretation table, reviewed alongside the executable evidence assertions.
• Six limitation classes covered → Path D: README limitations section linked to detailed researcher guidance.
• Developer material retained and navigable → Path D: maintainer index + CONTRIBUTING/docs/MkDocs links.
• Neutral, evidence-bounded prose → Path D: support rows derive from existing manifests, qualification, pack, and conformance records; no maturity registry or roadmap claims.
• Tests and canonical commands pass → Path A: targeted tests, distributions, docs, and canonical verify.

Design checks

• Security: the smoke uses argument-vector execution only, clears Python path influence, accepts no credentials or source/profile overrides, confines output to an isolated relative directory, and rejects shell syntax/traversal before execution.
• Maintainability: reuse the current CLI, _distributions(), release smoke, project-services policy, MkDocs, and existing researcher/ADR records; add no workflow, schema, backend registry, or evidence format.
• Extensibility: parameterize only the installed runner and isolated working root. Future backend quickstarts can add another closed selection without changing RAES contracts or inventing a README-owned catalog.
• Whole repository: account for README-as-PyPI-description rendering, wheel/sdist content, CI distribution/docs/policy jobs, the release workflow, MkDocs navigation, CONTRIBUTING, environment-pack facts, qualification records, and native-leakage/claim-integrity boundaries.

[Brad-Edwards]

gc_codex_review — cycle 1 of 1 (pre-push) on issue #23 (branch 23-researcher-quickstart)
Diff mode: inline — the complete diff was supplied in one prompt

Core review

Verdict: ship

This is shaped correctly. It separates the researcher-facing evidence path from maintainer material, keeps RAES as the semantic authority, and places the design seam at a closed, machine-checked README contract exercised against both the built wheel and the published distribution. The checker is repository verification plumbing rather than a competing schema or policy surface, and the focused CAGE-2 contract does not foreclose adding another documented adapter route later. The tests and release smoke cover the user-visible command, bounded output, and artifact layout.

No blocking findings.

Security review

Verdict: ship

This change is shaped correctly: it separates researcher-facing documentation from maintainer guidance and adds a closed, argv-based quickstart verifier at the documentation-to-installed-artifact seam. The verifier admits only the fixed conformance route, confines output to one relative directory, avoids shell execution, uses a stripped environment, and checks the exact output and artifact inventory. The release smoke independently uses hardcoded arguments in a fresh temporary directory. No concrete exploitable security issue is introduced by the diff.

No blocking findings.

[Brad-Edwards]

gc_codex_review pre-push cycle 1 of 1 complete for issue #23 on branch '23-researcher-quickstart'. 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.

[Brad-Edwards]

Review decision record — codex cycle 1 (issue #23)

Reviewer: codex
Cycle: 1

Architectural read:

Core reviewer: This is shaped correctly. It separates the researcher-facing evidence path from maintainer material, keeps RAES as the semantic authority, and places the design seam at a closed, machine-checked README contract exercised against both the built wheel and the published distribution. The checker is repository verification plumbing rather than a competing schema or policy surface, and the focused CAGE-2 contract does not foreclose adding another documented adapter route later. The tests and release smoke cover the user-visible command, bounded output, and artifact layout.

Security reviewer: This change is shaped correctly: it separates researcher-facing documentation from maintainer guidance and adds a closed, argv-based quickstart verifier at the documentation-to-installed-artifact seam. The verifier admits only the fixed conformance route, confines output to one relative directory, avoids shell execution, uses a stripped environment, and checks the exact output and artifact inventory. The release smoke independently uses hardcoded arguments in a fresh temporary directory. No concrete exploitable security issue is introduced by the diff.

Blocking findings: 0 (clean run)

[Brad-Edwards]

gc_test_quality_review cycle 1 of 1 — issue #23

Reviewer: test-quality (claude-sonnet-5 via gc_test_quality_review)
Branch: 23-researcher-quickstart
Cycle: 1 / 1
Findings: 2

Finding 1 — [critical] tools/tests/test_project_services.py::ProjectServicesPolicyTests::test_repository_configuration_satisfies_policy

Problem: The only test of validate_repository asserts that scanning the real, currently-compliant repository produces zero errors. None of the ~15 individual policy/security branches inside validate_repository — CodeQL fail-closed, GitHub Pages/routing-fallback retirement, devmain's restricted-command recipe, forbidden PyPI credential/skip-existing settings, exact dependency pinning, the CI PR Gate required-jobs contract — has a fixture that violates the rule to prove detection still works. Only validate_action_pins (via a separate test method) gets genuine violate-and-detect coverage.
Why it matters: Deleting a _require/forbidden check, inverting a condition in a way that happens not to trip on the current repo content, or otherwise weakening one of these governance rules would not be caught by this suite — it would only be caught if someone also happened to edit the tracked config file into a matching bad state. This is exactly the 'tested only by existence' pattern for security/governance-enforcing logic: the test proves the current file is fine, not that the rule fires when the file isn't.
Fix: Add fixture-driven negative tests (temp-directory repos, similar to the existing test_action_refs_must_be_full_commit_shas pattern) that construct a minimal repo violating each rule class — e.g. a release workflow containing PYPI_API_TOKEN, a devmain recipe containing git push, a CodeQL workflow with continue-on-error:, a docs/requirements.txt with an unpinned dependency, a .ground-control.yaml containing default_fallback: — and assert validate_repository/the relevant helper returns the expected error for each. Keep the existing real-repo happy-path test as one case among these, not the only one.

Finding 2 — [warning] tools/tests/test_project_services.py::ProjectServicesPolicyTests::test_hygiene_bulk_commands_do_not_log_the_repository_file_list

Problem: This test never calls the _hygiene nox session; it slices noxfile.py's source text and asserts a substring count (log=False appears exactly 7 times) and that certain label strings appear. It verifies the source text looks a certain way, not that running the hygiene commands actually suppresses file-list logging.
Why it matters: A refactor that keeps log=False appearing 7 times for unrelated reasons (or moves the flag to a helper while preserving the literal count coincidentally) would pass this test even if actual log suppression regressed, since the behavior itself is never exercised.
Fix: Either accept this as a lightweight config-drift guard and rename/scope it as such, or invoke the _hygiene session function against a fake nox.Session and assert on the actual log= argument passed to each session.run(...) call instead of counting a literal substring in the source text.

[Brad-Edwards]

gc_test_quality_review cycle 1 of 1 complete for issue #23 on branch '23-researcher-quickstart'. 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_review invocation to count cycles.

[Brad-Edwards]

Review decision record — test-quality cycle 1 (issue #23)

Reviewer: test-quality
Cycle: 1

Architectural read:

Both files back CI governance gates, and the README-quickstart suite is shaped correctly: it unit-tests parse_quickstart_contract's pure parsing/validation logic directly, with genuine adversarial fixtures (shell-injection payload, path-traversal, absolute-path escape) that drive the actual security boundary and assert ContractError is raised — and it correctly leaves the subprocess-executing execute_quickstart untested here because that function is exercised as a real integration step via the nox --runner session, not faked in a unit test. test_project_services.py is shaped differently and more weakly: validate_repository encodes roughly fifteen independent governance/security rules (CodeQL fail-closed, retired GitHub Pages/routing fallback, devmain's restricted merge recipe, forbidden PyPI credential and skip-existing settings, exact dependency pinning, the CI required-jobs aggregator), and the suite proves only that today's real repository files happen not to trip any of them. There is no fixture per rule that intentionally violates it to prove the rule still fires — so most of this governance logic could be weakened, miscoded, or deleted and the suite would still pass as long as no one also edits the tracked config to trigger it. Given the file's own comments stress how load-bearing the CI gate contract is, that's a real coverage gap on the persuasion-critical part of the change, not a stylistic nit.

Blocking findings: 2

Finding 1 — class (7 instances)

• ID: F1
• Title: (no title)
• Decision: fix
• Rationale: Addressed by next cycle
• Instances:
  • tools/check_project_services.py:92-93 (.ground-control.yaml routing.default_fallback retirement)
  • tools/check_project_services.py:62-63 (_validate_devmain restricted-command recipe)
  • tools/check_project_services.py:140-141 (CodeQL continue-on-error fail-closed check)
  • tools/check_project_services.py:153-161 (CI PR Gate required-jobs/fail-closed contract)
  • tools/check_project_services.py:244-256 (release workflow forbidden PyPI credential/skip-existing settings)
  • tools/check_project_services.py:262-263 (GitHub Pages publishing retirement)
  • tools/check_project_services.py:66-78 (_validate_docs_requirements exact pinning)

Finding 2 — one-off

• ID: F2
• Title: (no title)
• Decision: fix
• Rationale: Addressed by next cycle

[Brad-Edwards]

Execution obligation OBL-23-TQ-CAP-1 — Opened

Category: quality
Observed state: The capped test-quality cycle found two test gaps; both were fixed locally and the post-fix completion and policy gates pass, but the reviewer cap prevents a confirmation cycle.
Impact: The branch cannot advance to publish until the enforced review-cap decision is resolved.
Current obligation: Obtain explicit authorization for one over-cap test-quality review cycle to confirm the fixed test gaps.

Evidence

• docs: rewrite the README around a verified researcher quickstart #23 (comment)
• docs: rewrite the README around a verified researcher quickstart #23 (comment)
• Post-fix gc_implement_mechanical verify completed successfully with completion and policy passed.