Metadata-Version: 2.4
Name: epsiloneridani-progress
Version: 0.1.0
Summary: Decide, generate, and publish per-roadmap progress reports for EpsilonEridani.
License: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# EpsilonEridaniProgress

Progress reporting for [EpsilonEridani](https://github.com/eic/EpsilonEridani): what has actually
been achieved on each roadmap, written for a human to read in a minute.

Each roadmap directory in
[EpsilonEridaniRoadmaps](https://github.com/eic/EpsilonEridaniRoadmaps) carries two generated files:

- **`STATUS.md`** — a snapshot, rewritten whole on each update. It says which parts of the roadmap
  are done and sketches the frontier, headed by the commit it describes.
- **`PROGRESS.md`** — an append-only log. Each section covers one window of merged PRs as a few
  holistic paragraphs, emphasising named theorems rather than listing every PR.

New `PROGRESS.md` sections are announced in the **EpsilonEridani > Progress logs** Zulip topic.

## Why this repo exists

The rubrics-and-machinery split of
[EpsilonEridaniReview](https://github.com/eic/EpsilonEridaniReview), applied to reporting: the
prompts and the tooling live here, the output lands in EpsilonEridaniRoadmaps, and
[EpsilonEridaniWorker](https://github.com/eic/EpsilonEridaniWorker) drives it.

The design rule is that **a model only ever writes prose**. Every decision — whether an update is
due, which roadmap it covers, which PRs are in the window, and what mathematics actually landed —
is made by tested Python before any model starts, and the git and pull-request work afterwards is
done by tested Python too.

## The commands

```
epsiloneridani-progress due                      is an update due? (one API call, no clone)
epsiloneridani-progress plan   --roadmap-dir DIR pick the roadmap and the PR window
epsiloneridani-progress facts  --plan FILE       what declarations actually landed in the window
epsiloneridani-progress apply  --plan FILE ...   write the files, open the PR (resumable)
epsiloneridani-progress announce --section FILE  post a new section to Zulip (idempotent)
```

`due` is the only one that runs often; it exits 75 ("no progress") when nothing is due, matching
the worker's convention. `plan` runs at most once a day.

## The window cursor is a SHA, on the docs-tracking branch

A window is the half-open commit range `(from_sha, to_sha]` on EpsilonEridani's **`docgen`** branch, where
`from_sha` is the `to_sha` of the previous `PROGRESS.md` section.

`docgen` nominates the most recent commit on `main` whose API documentation has been published, and
the window ends at **the commit the published documentation actually reports** — read from the site
itself, since the deploy is independent and the branch can sit ahead of it. Ending at the branch tip
instead would record a cursor covering work the report never described, and because the next window
starts after that cursor, the work in between would never be reported at all.

The cost is latency: a report describes the project as of the last published docs build rather than
the tip. That is the right trade for a document whose whole purpose is to be read, and the header
records the exact commit, so nothing is misdated.

Links are not computed by this project at all, and neither are declaration names. Both are read from
doc-gen4's own published output — the declaration index and each module page, which carry the exact
name, kind, source file and line range — so a link resolves because it was read from the page it
points at. `git blame` over those line ranges is what decides whether a declaration belongs to the
window.

There is deliberately no Lean parser here. Qualifying a name correctly means resolving `namespace`
against `section`, `end`, `open ... in` and `_root_`, and many real declarations (projections,
constructors, `deriving` output) are never written in the source at all. An approximation gets most
names right, which is the worst outcome available: the wrong ones are indistinguishable from the
right ones, and a link built from a wrong name is a plausible dead link. PR numbers come from the squash-merge commit
subjects in that range and are attributed by their `roadmap/<Area>` label.

Wall-clock time is used only for display. A cursor made of timestamps would be wrong: a worker
clock running fast advances it past PRs whose merge times then fall *before* the stored cursor, and
those PRs are never reported at all.

## The coverage header

A status snapshot may carry a second machine header beside `epsiloneridani-status:v1`:

```text
<!--epsiloneridani-status:v1 {"roadmap":"EllipticCurves","to_sha":"…","ts":"…"}-->
<!--epsiloneridani-coverage:v1 {"layers":[{"id":"Layer 0","remaining":"Weil reciprocity","state":"partial"},{"id":"Layer 1","state":"done"},…],"readme_sha":"…","roadmap":"EllipticCurves","to_sha":"…"}-->
# Status: EllipticCurves
```

It is the report's verdict on each layer of the roadmap, in a form a script can read; the prose
says the same things, but nothing can aggregate prose across forty roadmaps. The consumer is the
EpsilonEridani site's Progress page (`scripts/roadmap_progress.py` in the EpsilonEridani repository).

**Wire schema.** `roadmap` is the status header's area, or `Area/Child` for a sub-roadmap (below);
`to_sha` equals the status header's; `readme_sha` is the SHA-256 of the README the layers were read
from; `layers` is a non-empty list (at most 64) of `{"id", "state", "remaining"?}` with `id` a short
label (`Layer 3`, `Lane G`, `L0A`), `state` one of `done`, `partial`, `untouched`, `unassessed` (the
material said nothing), and `remaining` an optional one-line note of at most 200 characters with no
angle brackets. No other keys anywhere. Keys are sorted and the JSON is compact;
`files.require_coverage` is the one definition, and both the worker and the gate run it.

**Trust boundary.** The model supplies only the assessments, as JSON inside a fenced
```` ```coverage ```` block at the end of its status prose. Code supplies everything else: `plan`
records the README's layer headings (`Layer` / `Lane` / `Part` / `Stage`, or `L0A`-style labels)
and `readme_sha` in the plan; `apply` removes the block, validates the payload against the schema,
checks it names every listed layer exactly once and nothing else, and writes the header; the gate
treats the headers as part of the canonical prefix (the lines after the status header, nowhere else)
and re-validates them. The gate proves the header's shape, never its truth, and cannot check
`readme_sha` (it never checks out the roadmap repository): the header is a claim, not a certificate.

**Missing block.** A README with no layer headings gives a plan with no layers and a report with no
header. When the plan lists layers, the worker refuses a body with no block, just as it refuses a
block that is malformed, not JSON, or does not fit the plan: a new report changes the report hash,
which retires the site's hand transcription of the old report, so publishing it headerless would
turn assessed layers into unassessed ones. The model always has `unassessed` for a layer it cannot
judge. The gate is deliberately more lenient and still accepts a status file without the header,
which is what every report written before the header existed looks like.

**README hash.** `readme_sha` binds an assessment to the specification it was made against: layer
ids alone do not, since a layer's requirements can change under an unchanged heading. The consumer
refuses a header whose hash does not match the README it reads and shows those layers as
unassessed with that reason.

**Umbrella areas.** An area whose directories include sub-roadmaps (RepresentationTheory's twelve)
is one labelled area with one report, so that report is the only account of its children. A
sub-roadmap is a directory directly below the area with a `README.md` and a `Suggested.lean`, the
consumer's rule. `plan` lists each one with layer headings under `sub_roadmaps`, with its
`Area/Child` id, its README path and its own `readme_sha`; the model reads those READMEs and answers
with a JSON object keyed by roadmap id instead of an array; and `apply` writes one coverage header
per sub-roadmap, each bound to its own README, after the area's own header (if its README has
layers) and in ascending order of name. The gate holds each to the same schema, requires
`Area/Child` with an alphanumeric child directly below the status file's own area, caps them at 32,
and treats all of them as part of the canonical prefix. A consumer that does not know sub-roadmap
headers ignores them: their `roadmap` never equals a row's own name.

**Rollout.** Merge here, then bump the two pins in EpsilonEridaniRoadmaps's `progress-*.yml` workflows and
the worker's `PROGRESS_REF` to the same SHA, together: the generator and the gate must run one
version. Reports written before the bump simply have no header.

**Leaving the hand transcriptions.** Today the site reads layer states from a hand-transcribed
file in the EpsilonEridani repository (`scripts/roadmap_coverage.json`), each entry bound to the exact
report it was read from. Nothing is backfilled: an area's transcription stays valid until its next
report, which after the bump carries the headers (the worker refuses one without them when there
are layers), and the site then reads those instead and the transcription is retired. That holds
for the RepresentationTheory children too, all at once, at the umbrella's next report, provided
the site reads sub-roadmap headers by then. Each entry can be deleted from the transcription file
once its roadmap's report carries a header.

## Trust boundary

`STATUS.md` and `PROGRESS.md` are **machine-owned, and their prose is not security-validated**.

The merge gate proves the *shape* of a generated update — its paths, its cursor, that it is a
byte-exact append, and that the head being merged is the head that was validated. It cannot prove
that the prose is true. Anyone may open a EpsilonEridani PR whose description contains prompt-injection
text; once that PR merges legitimately, its description reaches the writing model.

The mitigations reduce the risk and are not claimed to remove it: the model is grounded in
mechanically-extracted declaration names rather than author prose, PR bodies are delimited and
size-capped, reserved `epsiloneridani-*:v1` markers are rejected in model output, and Zulip mentions are
defused. Read these two files as a machine's summary, not as reviewed roadmap content.

**The blast radius is two markdown files AND a Zulip message.** Every merged section is posted to
**EpsilonEridani > Progress logs** automatically, so accepted prose reaches an audience outside the
repository. The post is treated as data -- mentions and bare `#123` linkifiers are defused, the
message is size-capped, it links both the appended log and the current roadmap status, and it is
idempotent on a stable per-window id -- but it is a second sink and the threat model has to say so.

## Licence

Apache-2.0.
