Add governed repository security reviews with versioned context

[rory-opanai]

Summary

Add Govern repository security reviews with versioned context, a runnable
tutorial for a security-review control plane. It binds repository ownership
and exact revisions to versioned threat context, bounded work admission,
authenticated evidence and named human decisions.

Draft for technical and editorial review; not ready to merge. Confirmation
of implementation contribution rights/licensing, relevant-team review and
Developer Experience approval remain outstanding. The implementation-licence
notice and all third-party notices are retained unchanged; this PR does not
assert that those approvals have been granted.

Motivation

The tutorial shows how to decide whether a repository review may run, whether
previous evidence can be reused, and which changes require fresh human review.
Developers can inspect the complete workflow without credentials, a hosted
model request or access to a real repository.

Related examples already cover Codex SDK code review
and Codex CLI security fixes on GitLab.
This contribution focuses on revision-bound authority, inherited context with
repository-specific deltas, repeat-safe admission and authenticated review
evidence. It does not propose a new vulnerability-detection technique.

What changed

• A 12-code-cell notebook, fictional fixtures, configuration, dependencies and
  an operator guide under examples/codex/governed_repository_security_reviews/.
• Organisation and workload-archetype context with separate per-repository
  deltas and bespoke high-risk context acceptance.
• Bounded scheduling, exact approval binding, retry accounting, authenticated
  evidence, changed-context revalidation and human disposition.
• Optional restricted-Docker workers, two finite-supervisor topologies and
  adversarial tests for refusal, failure, restart and evidence integrity.
• A pinned public Codex Security CLI 0.1.20 command/schema contract. Commands
  remain inert plans; recorded version/help checks are not scanner execution.
• Editable SVG/Mermaid architecture and context diagrams, plus a registry
  entry credited to rory-opanai.

The separate automated-development tutorial is not included.

Observed verification

Check	Result
Independent fresh clone and new virtual environment	Exact source identity verified; checkout unchanged
First unmodified Docker verifier in that clone	503 tests, zero skips: 129 fleet, 198 recipe and 176 stress
First recipe cycle	Four distinct jobs, four attempts, zero retries and three successful isolation receipts
Unchanged restart	Zero new jobs, attempts, retries or isolation receipts
Both finite-supervisor topologies	Initial runs and same-state restarts passed
Two fresh-state soaks	Each passed the same 27 scenarios with 23 scanner attempts and 19 proven container starts
Isolation and cleanup per soak	15 verified isolation receipts, three explicit instruction refusals and one observed-running timeout cleaned up; no surviving owned containers
Separate Python 3.12 and 3.14 checks	Each passed the same 503 tests with zero skips and 12 ordinary-Jupyter cells with Docker enabled

The independent ordinary-Jupyter check was separate and offline: all 12 cells
passed, with a retained non-fatal macOS sandbox shutdown warning. Its first
Docker command did not request Jupyter. The combined Docker/Jupyter results
above are separate runs. The independent walkthrough was AI-operated on the
same host and cached image, not an unfamiliar human or new customer machine.

An earlier candidate incorrectly asserted that four repository jobs must mean
exactly four attempts. The replacement accepts additional attempts only when
exact typed retry evidence and policy limits match; unexplained duplicates,
exhausted failures, worker crashes and incomplete isolation evidence still
fail. In an explicitly injected synthetic-timeout probe, recovery completed
four jobs in five attempts; exhausted clean and hostile fixtures failed their
intended contracts. The
original failed result is retained; its precise low-level transient was not
recorded and is not claimed to have been identified.

Interpreter repeats and overlapping test layers are not additional unique
coverage. The 2,000-record exercise is metadata-only: zero of those generated
records are scanned. Actual execution uses seven fictional fixture types.

How to test

Use Python 3.11+ on macOS or Linux. Native Windows is not supported by the POSIX
locking and private-file checks. The core example uses the standard library
and requires no API key or employee-only plugin.

• From the example directory, run the workflow and included verifier:

cd examples/codex/governed_repository_security_reviews
python3 -B scripts/run_security_review_cookbook.py --cycles 2
python3 -B scripts/evaluate_threat_context.py
python3 -B scripts/execute_notebook.py governed_repository_security_reviews.ipynb
python3 -B scripts/verify_cookbook_example.py

Without Docker, real-container tests are explicitly skipped. Nominal first and
restart attempt counts are [4, 0]; additional first-cycle attempts require
bounded retry evidence. Unchanged restarts must always produce zero new work.

• With an approved local daemon and already-cached image, require Docker
  isolation and run a fresh bounded soak:

docker image inspect python:3.12-alpine --format '{{.Id}}'
python3 -B scripts/verify_cookbook_example.py --docker
python3 -B scripts/run_security_stress_soak.py --cycles 2

The example uses --pull never; requested isolation cannot silently fall back
to the host. Inspect attempts, proven starts, isolation receipts and cleanup
separately. Follow local/README.md to reproduce the two supervisor topologies.

• Install optional pinned tools outside the checkout, then use an ordinary
  Jupyter kernel and validate the source diagrams:

python3 -m venv /tmp/governed-cookbook-venv
/tmp/governed-cookbook-venv/bin/python -m pip install -r requirements.txt
/tmp/governed-cookbook-venv/bin/python -B scripts/verify_cookbook_example.py --jupyter --docker
python3 -B scripts/build_cookbook_diagrams.py --check

Dependency installation contacts the configured Python package registry;
example execution remains offline.

• From the Cookbook root, run the repository notebook validator and inspect
  the proposed registry entry against .github/registry_schema.json:

cd ../../..
/tmp/governed-cookbook-venv/bin/python -B .github/scripts/check_notebooks.py
git diff --check
git diff --cached --check

• Before merge, complete the repository's docs-editor review for changed
  Markdown and notebook Markdown cells, resolving any remaining P0/P1 issues.
• Only after an approved merge/publication, verify the live page at slug
  governed-repository-security-reviews. Website deployment is not claimed.

Figures and source

The editable architecture
and threat-context hierarchy
include text alternatives and local Mermaid sources. Local notebook previews
were checked at desktop and narrow widths; no live website rendering is claimed.

Limits and review checklist

The scanner is a deterministic fixture adapter. The example makes zero live
product scans, hosted-model requests or provider writes, and does not access
customer repositories. It demonstrates governance and isolation controls, not
vulnerability precision/recall, entitlement, fleet throughput, cost savings or
production readiness. The separate public metadata planner does not inspect
repository contents.

Approval files use fictional identities, not enterprise authentication. Local
HMAC state does not protect against a malicious writer controlling the same
host account and key; power-loss durability is not established. Real repository
acquisition, scanner execution, provider writes, merge and deployment require
separate implementation, evaluation and human authority.

• Registry entry added with the notebook path, date, unique slug and tags.
• Author credit confirmed as rory-opanai; no custom authors.yaml entry.
• Relevance and uniqueness explained with related Cookbook examples.
• Prerequisites, commands, expected outcomes and limits documented.
• Exact candidate tested; source/notebook/registry checks and local patch
  application verified without changing the tested implementation.
• Confirm implementation contribution rights/licensing before merge;
  retain the bundled Apache 2.0 notices and provenance.
• Obtain relevant-team technical review and Developer Experience approval.
• Maintainer quality-rubric review and final correctness/completeness
  acceptance remain outstanding.