Public project readiness: OpenSSF integrations and approachable documentation

[Brad-Edwards]

Outcome

Make RAES ready for a broader public audience by adding honest OpenSSF project-health integrations, establishing a hard publication boundary between public and developer documentation, rewriting the README and public documentation as approachable user-facing material, and standardizing the repository community documents.

This is one coding-agent unit of work. Complete all sections together and follow the resulting PR through green CI and documentation publication checks.

Context

RAES is the Reproducible Agentic Environments System, formerly the Agentic Cyber Environments System (ACES). It originated from the Heron AI Security Fellowship agent-environments work, including RFCs and a draft open-source scenario definition language, and was subsequently broadened and renamed to reflect uses beyond cyber environments.

The public explanation should present RAES as a system for defining reproducible environments and the agents or other participants within them. AI security and CTFs are strong examples, but the framing must also remain legible for uses such as disaster-recovery environment capture, product testing, software-configuration evaluation, and research. These are examples, not an exhaustive market narrative or claims that every workflow already has a production backend.

Current problems

• OpenSSF Scorecard is not integrated; Add OpenSSF Scorecard workflow and README badge #839 contains the earlier narrow request.
• The project is not enrolled and represented honestly on bestpractices.dev.
• The Read the Docs configuration points Sphinx at the entire docs/ workspace.
• The public navigation explicitly includes project notes, migrations, research working files, audits, and issue/preflight documents.
• Sphinx currently has no meaningful public-source exclusion boundary.
• The README and several entry pages read like internal architecture/governance documents: they front-load caveats, use repeated abstract language such as “surface,” “boundary,” “authority,” and “bounded,” and do not quickly help a new reader understand or try RAES.
• The existing community documents need a consistency and completeness pass against an established open-source project template.

Work

1. OpenSSF Scorecard and Best Practices

• Add the official OpenSSF Scorecard GitHub Actions integration using SHA-pinned actions, least-privilege job permissions, SARIF/code-scanning upload, published results, and a README badge.
• Prefer the workflow GITHUB_TOKEN and GitHub repository rules visible to it. Do not add a long-lived PAT merely to improve a score without explicit authorization.
• Enroll the repository on bestpractices.dev and work toward the appropriate honest Passing/Baseline level.
• Answer badge criteria truthfully. Record genuinely unmet criteria as unmet and use N/A only where the criterion actually permits it.
• Do not game Scorecard or badge results, claim independent review that did not occur, or impose governance the project does not currently have.
• Preserve a workable single-maintainer model. The sole maintainer must remain able to merge their own work after required automated checks; do not introduce an independent-approval requirement that makes maintenance impossible.
• Preserve release-please operation, including its GITHUB_TOKEN-created release PR, release tagging/publishing flow, and main to dev synchronization. Repository rules and required checks must not deadlock bot-authored release PRs or the maintainer’s authorized release operation.

2. Separate public documentation from developer documentation

Establish a deliberate source and publication boundary. Public and developer documentation must be independently understandable and maintainable.

• Use an explicit public-doc source root or deterministic allowlist. Do not rely only on a growing blacklist of internal filenames.
• Read the Docs production builds, search indexes, sitemaps, and pull-request previews must contain only public documentation.
• Keep developer, implementation, workflow, issue-preflight, migration-working, audit, search-log, and internal research material in the repository, but outside the public build.
• Provide a clear developer-documentation index from the contributing/development path.
• Curate durable accepted architectural decisions and academically useful evidence into public explanations where they add reader value; do not publish every issue note merely because it exists under docs/.
• Preserve stable public URLs where practical and add redirects where a published page moves.
• Retain warning-strict Sphinx validation and locked/reproducible Read the Docs installation.

At minimum, the public build must not expose raw collections such as:

• issue and preflight working notes under docs/decisions/
• docs/lessons/
• internal migration working notes
• dated audits and search logs
• Ground Control/requirement status snapshots
• implementation current-state assessments intended for maintainers

3. Rewrite the README and curate public documentation

Rewrite rather than lightly rearrange the current prose.

The README must function as the project front door for a reader with no RAES context:

• explain RAES in plain language within the opening paragraph;
• show what problem it solves and what an authored environment looks like;
• provide a short, tested installation and first-use path;
• include a small concrete SDL example and the command or API used to validate it;
• direct scenario authors, researchers, backend implementers, and contributors to distinct next steps;
• explain current maturity and limitations without front-loading defensive disclaimers;
• present AI security, CTF, disaster recovery, product testing, configuration testing, and research as illustrative uses without narrowing RAES to one domain or overstating delivered capabilities;
• link to the hosted documentation, examples, API reference, contributing guide, security policy, citation information, releases, and package installation;
• show only useful, accurate badges.

Create a public information architecture oriented around reader needs, including:

• overview and core concepts;
• quickstart and tutorials;
• SDL authoring and validated examples;
• Python and CLI use;
• backend contracts and conformance;
• academic/research material: conceptual model, formal semantics, methodology, evidence, limitations, reproducibility, lineage, and citation;
• contributing and support.

Apply a plain-language editorial pass across public entry pages:

• prefer concrete verbs and examples over strings of abstract nouns;
• define specialized terms once;
• remove duplicated caveats and repeated project-positioning paragraphs;
• split exhaustive inventories into focused reference pages or tables;
• distinguish normative specifications, explanatory guidance, academic evidence, and implementation status;
• remove issue-management and implementation-process language from user-facing prose;
• avoid promotional claims, personal adoption history, event announcements, or future-work hype.

Where a brief project history is useful, keep it factual and concise: acknowledge the Heron AI Security Fellowship origins, the ACES name, and the later RAES rename without turning the README into a personal or promotional narrative.

4. Standardize community documents

Audit and revise the repository’s community-health files using the CNCF Project Template as the primary structural reference, adapted to RAES rather than copied blindly. Cross-check the result against OpenSSF Best Practices Passing/Baseline criteria and GitHub’s community-profile expectations.

Review at least:

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• SECURITY.md
• issue templates
• pull-request template
• support/reporting guidance
• maintainer/governance information where useful for the current project

The resulting documents must:

• give contributors an accurate setup, test, review, and submission path;
• distinguish public contribution guidance from internal agent/Ground Control instructions;
• state how bugs, feature requests, support questions, and vulnerabilities are reported;
• provide a coordinated vulnerability-disclosure path and expected response handling without inventing staffing guarantees;
• describe the actual single-maintainer decision model honestly;
• document release-please ownership of versioning and CHANGELOG.md without exposing internal workflow clutter to ordinary users;
• avoid requirements that the current project cannot honestly satisfy.

Acceptance criteria

• The official OpenSSF Scorecard workflow runs successfully, publishes results, uploads SARIF, uses least privilege, and has a working README badge.
• The bestpractices.dev project entry exists and accurately reflects the repository’s achieved status; its badge is shown only when valid.
• Single-maintainer merges and release-please remain operational under the resulting rules and checks.
• Public and developer documentation have separate, explicit source boundaries and navigation.
• Read the Docs output and previews contain no internal preflight, working-note, audit, migration-work, or project-status pages.
• Developer documents remain available in the repository through a clear developer index.
• The README gives a new reader a comprehensible explanation and a tested path to first success without requiring architecture or governance knowledge.
• Public documentation has clear paths for users, academics/researchers, backend implementers, and contributors.
• The public prose no longer reads like an issue plan, requirements ledger, or exhaustive internal design inventory.
• Community documents follow a coherent established template, are customized for RAES, and satisfy all honestly applicable OpenSSF Passing/Baseline documentation criteria.
• Existing normative specifications, contracts, schemas, and implementation behavior are not changed merely to support the editorial migration.
• Documentation builds warning-free, links are checked, examples and quickstart commands are tested, and the complete repository CI remains green.

Non-goals

• Deleting internal developer or research records from the repository.
• Claiming Silver/Gold badge criteria, a multi-maintainer bus factor, or independent review before those facts exist.
• Adding mandatory external approval that blocks the current maintainer.
• Replacing release-please or hand-editing release-owned versions or CHANGELOG.md.
• Expanding RAES runtime or backend functionality solely to make documentation claims true.
• Publishing personal context, adoption anecdotes, event announcements, or speculative roadmap claims.

Related work

• Add OpenSSF Scorecard workflow and README badge #839 — existing narrow OpenSSF Scorecard request; this issue incorporates that remaining scope.
• Add OSS community docs: README, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY #137 — earlier community-document request; files now exist, and this issue governs their current standardization pass.
• Reframe RAES documentation around reproducible agentic environments #884 — completed RAES domain-neutral reframing; this issue performs the reader-oriented editorial and publication cleanup that remains.
• Migrate documentation hosting to Read the Docs #925 — completed initial Read the Docs migration; this issue corrects the public-content boundary and completes the audience-facing migration.

References

• OpenSSF Scorecard and official Scorecard Action
• OpenSSF Best Practices Badge Passing/Baseline criteria
• CNCF Project Template
• GitHub community-profile guidance
• Read the Docs configuration and reproducible-build guidance

Requirements

• DOC-928 — Curated public documentation and enforced reader-first style

[Brad-Edwards]

🛠️ Picked up by /implement - driver codex, branch 928-public-project-readiness, 2026-07-27T01:35:13.321Z.

[Brad-Edwards]

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

Requirement: DOC-928 — Curated public documentation and enforced reader-first style (DRAFT, MUST).

1. Lock the behavior with tests first

• Add focused policy tests for the positive public source root, symlink/include/download containment, generated route/search inventory, required public information architecture, and executable quickstart examples.
• Add Vale provisioning tests for the pinned version, platform asset selection, checksum verification, safe extraction, cache reuse, and bounded failures.
• Add verification-plan tests proving that public-source, Sphinx, Vale, publication-tooling, and docs-workflow changes select the canonical docs graph.
• Begin with failing tests, confirm that each failure represents the intended missing behavior, then implement. Keep tests deterministic and network-free through temporary repositories and mocked downloads.

2. Establish one curated public documentation source

• Create docs/public/ as the sole hosted Sphinx source root and move/curate public material beneath it. Keep hosted routes stable where practical, including /api/, by preserving paths relative to the new root.
• Point .readthedocs.yaml, docs/Makefile, docs/public/conf.py, .github/workflows/docs.yml, and the nox docs session at that root. Preserve the frozen uv environment, strict warnings, installed-package version metadata, and output outside the source tree.
• Add a focused tools/check_public_docs.py policy evaluator using existing PolicyFailure, containment helpers, bounded loaders, and standard text/JSON rendering. Derive allowed output/search routes from files under the positive root; reject symlinks and include/literalinclude/download escapes, and reject unexpected generated documents.
• Make PUBLIC_DOCS_ROOT in noxfile.py the local source of truth. Update tools/verification_plan.py so the full fallback and all documentation-related changes run the docs graph.
• Keep developer, decision, migration, audit, and research-working records in the repository but outside the public root. Add docs/README.md and update docs/DEVELOPMENT_WORKFLOW.md as the developer index/workflow target required by documentation coverage.
• Migrate every repository-relative reference, governed source_ref, positioning/lineage path, catalog entry, formal-spec link, and test affected by public source moves; do not retain duplicate compatibility copies.

3. Rewrite entry documentation around first success

• Rewrite the root README.md—also the PyPI long description—with a plain one-line purpose, a tested install-and-validate path, a small SDL scenario, the expected result, audience routes, honest maturity/limitations, use cases, and useful project links.
• Build a compact public information architecture covering overview/concepts, quickstart/tutorials, SDL and examples, Python/CLI, backends/conformance, academic/research context, limitations, citation, contributing, support, security, and API reference.
• Put a task and outcome first; present prerequisites briefly; show exact commands or code; explain placeholders at the point of use; show expected results immediately; place cautions where they matter; then offer deeper reference links.
• Use the current public Python parser for first validation. Do not invent a generic validation command or change runtime behavior to fit the prose.
• Store a canonical minimal scenario under the public root and execute it with the current parser in tests. Extract/compare any README copy so examples cannot silently drift.

4. Make Stripe Documentation the explicit editorial exemplar

• Extend the repository documentation style guide with an explicit, linked Stripe Documentation exemplar section and RAES-specific before/after examples. Document the transferable patterns—task-first titles, outcome-led openings, short prerequisites, progressive steps, working examples, placeholder explanations, expected results, contextual cautions, progressive disclosure, and direct language—without copying Stripe prose, branding, theme, or semantic claims.
• Add .vale.ini, a repository-owned styles/RAES/ ruleset, and a small RAES vocabulary. Enforce low-ambiguity rules such as sentence-case/non-punctuated headings, direct plain-word substitutions, dismissive-language avoidance, promotional-claim avoidance, repeated words, and readable sentence/document metrics. Scope rules to README, public docs, and public community entrypoints; exclude code, URLs, literal blocks, API identifiers, normative/internal records, and legitimate RAES technical terms to avoid broad false positives.
• Pin Vale in tools/tool_versions.py and provision it through a checksum-verified tools/vale_tool.py cache modeled on the existing OSV/gitleaks tools. Do not fetch third-party Vale packages during gates.
• Run the public boundary checker and Vale as named SessionReporter stages in the canonical nox docs graph before warning-strict Sphinx HTML and link checks.

5. Add accurate public-project integrations and community routes

• Add the official OpenSSF Scorecard workflow with commit-SHA-pinned actions, deny-by-default/least-privilege permissions, non-persistent checkout credentials, GITHUB_TOKEN, SARIF upload, and published Scorecard results. Add the README Scorecard badge only for the real repository endpoint. Keep release-please and the sole-maintainer merge model unchanged.
• Add an honest .bestpractices.json proposal using only verifiable Passing criteria and explicit unmet criteria for the current single-maintainer/two-person-review limitations. Verify the live bestpractices.dev entry before adding its badge; enrollment remains a provider-authenticated administrative action, never a hermetic build dependency.
• Refresh CONTRIBUTING.md, SUPPORT.md, SECURITY.md, CODE_OF_CONDUCT.md, issue/PR templates, and add concise GOVERNANCE.md/MAINTAINERS.md where useful, using CNCF/OpenSSF templates as checklists without inventing teams, elections, approval requirements, SLAs, or labels.
• Move the dated authorship-anomaly record out of the public security policy into the developer record index without deleting history.
• Validate Read the Docs configuration and the public source locally; verify production/search/sitemap/preview behavior where the provider connection permits. Do not publish internal records through Pages or Read the Docs and do not add claims/badges before external status exists.

6. Governance, safety, and whole-repository fit

• Add DOC-928 to the existing documentation-surfaces ownership phase and extend it only to the new public/style policy, tests, workflows, community entrypoints, and moved documentation paths. Keep Ground Control IMPLEMENTS/TESTS/DOCUMENTS links aligned and transition DOC-928 only after the implementation and evidence are complete.
• Security layers: preserve existing secret/private-key gates; parse YAML/TOML/MyST/RST/Vale with their owning tools; use bounded repository-relative paths and reject traversal/symlink escape; run fixed argv; checksum Vale before execution; keep tokens out of argv, logs, pages, and artifacts; use only official least-privilege workflow permissions.
• Maintainability: reuse nox, SessionReporter, PolicyFailure, policy rendering, safe paths, tool-version/cache patterns, existing SDL parser/example validators, Sphinx, release-please, and Dependabot rather than creating parallel runners, error types, parsers, or authorities.
• Extensibility: placement under PUBLIC_DOCS_ROOT is the curation seam so a future page automatically enters build, search, sitemap, preview, and Vale coverage; internal records remain outside it; only a real hosted route change extends an explicit redirect map.
• Whole-repo validation includes project-positioning/lineage checks, agent guidance, example catalogs, package README metadata, API autodoc, public workflows, policy ownership, source references, and internal developer links.
• No SDL/schema/contract/runtime/API/backend behavior, application authorization/logging/persistence, package version, CHANGELOG.md, or changelog fragment changes. The PR title will use a valid Conventional Commit subject.

7. Verification and delivery

• Run targeted red/green tests throughout, then public boundary checks, Vale, Sphinx warning-strict HTML/link builds, executable example tests, workflow/config parsers, repository policy, governance, and focused regression suites.
• Before completion, run with RAES_REQUIREMENT_UID=DOC-928 because the branch lacks a UID:
  • implementations/python/.venv/bin/python tools/check_repo_policy.py
  • implementations/python/.venv/bin/python tools/check_requirement_governance.py
  • implementations/python/.venv/bin/python tools/verify_all.py
  • the canonical completion command uv tool run --from 'nox[uv]==2026.4.10' nox -f noxfile.py -s verify
• Run the required pre-push implementation and test-quality reviews, stage only issue-928 changes, pass pre-commit, push the feature branch, open a PR against dev, and monitor CI/Sonar. External enrollment or provider connection that requires interactive owner authentication will be reported explicitly rather than simulated or overstated.

[Brad-Edwards]

gc_codex_review — cycle 1 of 1 (pre-push) on issue #928 (branch 928-public-project-readiness)
Diff mode: inline — the complete diff was supplied in one prompt

Core review

Verdict: ship-with-fixes

The positive docs/public publication boundary, canonical nox integration, and reuse of PolicyFailure are the right architectural seams: public and developer records are cleanly separated, and adding another public page remains straightforward. The migration is not production-ready yet because it drops established hosted routes without a compatibility mechanism, and the canonical docs graph omits the executable quickstart checks that are supposed to protect the new reader-first surface.

Blocking findings (2):

1. [class] Preserve existing hosted documentation routes — tools/check_public_docs.py:25
   Changing the Sphinx source root makes prior docs/* routes disappear unless the same relative path exists beneath docs/public. Several reader pages are replaced at different routes—for example, explain/getting-started.html becomes quickstart.html, explain/sdl/index.html becomes sdl/index.html, and explain/sdl/limitations.html becomes limitations.html—while the publication checker derives allowed output solely from the new sources and defines no redirect contract. Existing README versions, external references, and bookmarks will therefore lead to 404s. Preserve the established relative paths or add an explicit redirect map that is generated and validated by this checker.
2. [one-off] Run executable quickstart checks in the docs graph — noxfile.py:920
   The canonical docs session runs source containment, Vale, Sphinx, output inventory, and link checking, but never invokes the new quickstart parsing and README-fixture checks. Because .github/workflows/docs.yml runs only this session, a documentation-only change can publish an invalid scenario or let the README drift from the checked-in example while the advertised docs gate remains green. Add a focused executable-example stage to _run_docs and pin that stage in the docs-graph test.

Security review

Verdict: don't-ship

The change is shaped around a positive public-documentation root and a single nox verification graph, which is the correct seam for publication containment. It also crosses CI authorization and executable-tool bootstrapping. The docs placement model remains extensible, but the new Vale bootstrap lacks an independent trust anchor, making documentation verification depend on mutable upstream release assets.

Blocking findings (1):

1. [one-off] Vale executable and its checksum share the same mutable trust source — tools/vale_tool.py:90
   Attacker model: an attacker who compromises the upstream Vale repository or its release credentials. The installer downloads both the executable archive and its expected checksum from assets attached to the same mutable GitHub release. The attacker can replace both assets, so the comparison succeeds and _extract_binary installs an attacker-controlled executable that the nox docs gate subsequently runs on CI and developer machines. Pin the expected SHA-256 values in this repository, or verify an independently rooted signed provenance record, before extracting and executing the archive.

[Brad-Edwards]

gc_codex_review pre-push cycle 1 of 1 complete for issue #928 on branch '928-public-project-readiness'. 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 #928)

Reviewer: codex
Cycle: 1

Architectural read:

Core reviewer: The positive docs/public publication boundary, canonical nox integration, and reuse of PolicyFailure are the right architectural seams: public and developer records are cleanly separated, and adding another public page remains straightforward. The migration is not production-ready yet because it drops established hosted routes without a compatibility mechanism, and the canonical docs graph omits the executable quickstart checks that are supposed to protect the new reader-first surface.

Security reviewer: The change is shaped around a positive public-documentation root and a single nox verification graph, which is the correct seam for publication containment. It also crosses CI authorization and executable-tool bootstrapping. The docs placement model remains extensible, but the new Vale bootstrap lacks an independent trust anchor, making documentation verification depend on mutable upstream release assets.

Blocking findings: 3

Finding 1 — class (4 instances)

• ID: F1
• Title: [core] Preserve existing hosted documentation routes
• Location: tools/check_public_docs.py:25
• Decision: fix
• Rationale: Changing the Sphinx source root makes prior docs/* routes disappear unless the same relative path exists beneath docs/public. Several reader pages are replaced at different routes—for example, explain/getting-started.html becomes `qu…
• Instances:
  • tools/check_public_docs.py:25
  • docs/public/quickstart.md:1
  • docs/public/sdl/index.md:1
  • docs/public/limitations.md:1

Finding 2 — one-off

• ID: F2
• Title: [core] Run executable quickstart checks in the docs graph
• Location: noxfile.py:920
• Decision: fix
• Rationale: The canonical docs session runs source containment, Vale, Sphinx, output inventory, and link checking, but never invokes the new quickstart parsing and README-fixture checks. Because .github/workflows/docs.yml runs only this session, a d…

Finding 3 — one-off

• ID: F3
• Title: [security] Vale executable and its checksum share the same mutable trust source
• Location: tools/vale_tool.py:90
• Decision: fix
• Rationale: Attacker model: an attacker who compromises the upstream Vale repository or its release credentials. The installer downloads both the executable archive and its expected checksum from assets attached to the same mutable GitHub release. The…

[Brad-Edwards]

gc_test_quality_review cycle 1 of 1 — issue #928

Reviewer: test-quality (claude-sonnet-5 via gc_test_quality_review)
Branch: 928-public-project-readiness
Cycle: 1 / 1
Findings: 0 (clean run)

[Brad-Edwards]

gc_test_quality_review cycle 1 of 1 complete for issue #928 on branch '928-public-project-readiness'. 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 #928)

Reviewer: test-quality
Cycle: 1

Architectural read:

This is a policy/config-verification surface, and the new and touched test files stay in that idiom correctly: each test drives a real pure function (validate_project_positioning, evaluate_public_sources/evaluate_public_output, evaluate_repo_policy, evaluate_adr_immutability, plan_for_changes, vale_tool's checksum/extraction helpers) and asserts on the concrete PolicyFailure rule_id/path/message it returns, or on real command tuples captured by a FakeSession — never on "was a mock called." The docs-graph test (test_docs_graph_uses_curated_root_and_reader_style_gate) correctly exercises the new noxfile._run_docs wiring end-to-end against real constants (PUBLIC_DOCS_ROOT, PUBLIC_DOCS_ENTRYPOINTS, PUBLIC_DOCS_EXAMPLE_TESTS) rather than stubbing the assertions away, and the security-adjacent static-config tests (scorecard workflow permissions/pinning, .bestpractices.json honesty, readthedocs/docs.yml build-source restriction) assert on the actual enforced values (full-SHA pin regex over every uses: line, exact permission blocks) rather than mere presence. Boundary-escape and symlink-rejection tests for the public docs root plant the actual bypass (a symlink, an out-of-tree literalinclude) and assert it is caught, which is the right bar for this category. I don't see a structural problem with the shape of this change; it fits the repo's existing policy-check-plus-behavioral-test pattern.

Blocking findings: 0 (clean run)

[Brad-Edwards]

Pre-PR base synchronization

• Source: refs/remotes/origin/dev at d8937cbf7e92356ca8678bb6a01ff88baa050531
• Outcome: already_current
• Published feature head: 40a13bbbb6cdcc1ab0c02ea62219577010ce3768
• Verified tree: e4e6bee1fcfb4eb7dba4391561b152bf37041117