This repository was the fleet's standby consumer. Since 2026-09-04 it is also the home of the research programme: the place where the programme's state is published, where its artifacts are read, and where the owner is reached.
| Path | What it is | Who writes it |
|---|---|---|
research-program/STATUS.md |
Live programme status: units done, queued, parked; capacity; open questions | The engine, every worker tick |
research-program/CHECKPOINT.md |
Append-only log of every claim, completion, question and repair | The engine |
research-program/QUESTIONS.md |
Parked questions, each with the default being followed in the owner's absence | The engine |
research-program/queue.jsonl |
The unit queue itself | The engine |
research-program/artifacts/dossiers/ |
One verified dossier per fleet repo, each with a verification table, plus the fleet index and Word versions | Research units, verified adversarially |
research-program/artifacts/research/ |
The research briefs, gap analysis, interoperability architecture, skill curriculum and programme plan | Research units |
research-program/artifacts/work-bundle/ |
The redacted bundle prepared for the owner's work colleagues, the information request, and the answers that came back | Research units, redaction-checked |
research-program/artifacts/sweeps/ |
Unblock sweeps: frozen issues repaired, stalled work re-routed | The recurring sweep |
| Issue #553 | The owner inbox. Commands: answer <qid>: …, pause, resume, resume <unit>, stop phase <n>, note: … |
Owner and engine |
Everything under research-program/ is machine-owned. It is a published mirror of a local engine directory, synchronised with deletion enabled: a file you add or edit there is silently removed or overwritten on the next tick. If something in that tree is wrong, the fix belongs upstream in the engine at ~/.codex/automations/research-program/, not here. Do not hand-edit artifacts, and do not open pull requests against that tree.
Everything outside research-program/ is ordinary repository code and is yours to change through the normal issue and pull-request flow.
Two defect classes have already reached this tree and both are invisible on a casual read: a scan once printed token prefixes into a working file, and a batch of issue bodies carried a drafting agent's private working-directory paths, which made the issues unactionable. The work bundle in particular is prepared to be handed to colleagues, so a leaked path or credential fragment here is a real disclosure rather than an untidiness. That is what the publication guard exists to prevent.
Run python scripts/check_publication_safety.py with Python 3.12 or later before
publishing. It scans bytes in every file under research-program/, including
binary files, and separately scans the selected allowlist exactly once. JSON and JSONL string
values and keys are also scanned after decoding escapes once, with findings
attributed to their physical source lines. Diagnostics contain
the relative file, line, and rule, never the matched content. Missing or empty
trees, unreadable entries, and symlinks fail the check. The final line reports
files scanned, unallowed hits for every rule (including zeros), allowed hits,
and errors. This mechanical check does not establish that proprietary content is
safe to publish.
For an intentional example, manage the policy in the upstream engine that
publishes research-program/.publication-allow; do not hand-edit that generated
mirror, because the next refresh overwrites it. Alternatively, keep reviewed
policy in the preserved repo-root .publication-allow fallback (when no local
policy is published) or pass an explicit --allowlist file. Entries name an exact
path relative to research-program/, in the
form example.md:credential # Synthetic example reviewed for publication. Each
entry needs a reason and one of home-path,
credential, private-key, scratch-path, or internal-host. Wildcards and
paths outside the research tree are rejected. An exception covers only that
file and rule; it does not suppress other rules or files. No findings are automatically allowlisted.
An explicit --allowlist path takes precedence. Otherwise the scanner uses
<root>/.publication-allow when present, then the repo-root .publication-allow
as a compatibility fallback only for the default research-program/ root.
Custom scan roots require a local policy or an explicit --allowlist; they do
not inherit exceptions from their parent directory.
This repository retains that fallback outside the
machine-owned tree so publication refreshes preserve its reviewed policy. The
policies are never combined: an invalid or linked local policy fails rather than
falling back to a permissive parent policy. The selected policy is scanned for
findings but does not count as publication content; a policy-only tree fails the
zero-files check.
Preparation is an explicit operator step; CI runs only the scanner and does not
redact files. On a separate staging copy, run
python scripts/prepare_publication.py --staging-root <staging-copy> followed by
python scripts/check_publication_safety.py --root <staging-copy> --allowlist <reviewed-allowlist>.
Publish only after both commands succeed. Preparation replaces private path,
credential and host references with explicit redaction markers. Local evidence
is preserved. Affected JSON and JSONL must remain parseable; ambiguous keys, invalid structured
data requiring redaction, unreadable files and links stop preparation. Clean
historical process captures retain their original bytes. Binary files remain intact
and must pass the byte scanner. This export step is not a confidentiality review
and never substitutes for the guard. Correct the source or export policy when
a finding remains; subsequent publication must not restore it.
The Publication guard workflow runs on PRs and pushes to main. The required
Gate also calls it unconditionally, including for documentation-only changes;
a failed, cancelled, or skipped scan prevents a successful Gate / gate status.
Existing published findings must be removed or individually justified before
the guard can pass. python -m pytest tests/test_publication_safety.py tests the
scanner and Gate aggregation against synthetic trees without exposing real hits.
External exporters must install both scripts and their shared
scripts/publication_patterns.py module together, then explicitly run preparation
and the guard on the staging copy. This repository does not establish that an
external engine has that integration. Keep original evidence outside the staging
copy. Complete PEM private-key blocks (including PKCS#8, encrypted, RSA, OpenSSH,
EC and DSA forms) are removed in full; incomplete or mismatched blocks stop
preparation. Redaction markers identify local evidence references; they are not
repository paths to use for edits.