Skip to content

T60: read the journal entry at the PR head, not the diff's added lines - #260

Merged
superposition merged 2 commits into
mainfrom
ticket/T60-journal-gate-revision
Sep 12, 2026
Merged

superposition merged 2 commits into
mainfrom
ticket/T60-journal-gate-revision

Conversation

@superposition

@superposition superposition commented Sep 12, 2026 •

Copy link
Copy Markdown
Owner

Fixes the false entry-leg verdict found while merging the revision PR #259 — no Closes; this references that finding. Plain journal --pr 259 printed the roles OK and then failed with missing ## What we tried / ## Evidence / ## What this does not establish, because the entry leg read gh pr diff's added lines and for a revision PR those three H2 headings are unchanged context lines. The headings are present in the entry on main; the gate's own --entry source already fixed it, so the defect was a misleading failure, not a broken entry.

What changed

crates/gates/src/journal.rs

  • The --pr entry leg now reads the entry as it exists at the PR's head commit: it takes the PR's changed files (gh pr view --json files,headRefOid), picks the entry markdown (the docs/figures/<slug>/README.md / _posts/*.md shape, or the only markdown file), and reads that path at headRefOid through the contents API with Accept: application/vnd.github.raw. It prints entry source: <path> at the PR head <sha> (the entry as it exists at the head, not the diff's added lines). When it cannot tell which markdown file is the entry it refuses and names the candidates, so the remedy (--entry <path>) is immediate.
  • --entry <path> behaves as before and still pins the source.
  • An offline --diff is an entry source only when it creates every markdown file it names; otherwise it is refused by name, because a diff that changes an existing entry cannot show that entry's headings (they are context lines). This covers both the pure revision (1 changed, 0 created) and the mixed case the correctness review found (1 changed, 1 created — the first cut of this fix checked the created file and could print OK without reading the entry). An entry-creating diff still works.
  • The roles leg is untouched: three distinct approving verdicts, last comment per role wins, superseded comments reported.
  • Self-test 36 checks (5 new, pure parsers; no new test files).

docs/journal-pipeline.md: one paragraph recording the entry-creating vs revision-PR difference and the exact command for each, so a later agent does not rediscover it.

Evidence (before → after)

Before, on base 006b8af:

$ cargo run --quiet -p qualia-gates -- journal --pr 259
journal-gate: roles OK - accuracy=approve(0), teaching=approve(0), style=approve(4)
journal-gate: FAIL - 3 problem(s); the gate is not open
journal-gate: entry: missing ## What we tried
journal-gate: entry: missing ## Evidence
journal-gate: entry: missing ## What this does not establish
$ echo $?
1

$ cargo run --quiet -p qualia-gates -- journal --pr 259 --entry docs/figures/the-fly-brain-on-the-robot/README.md
journal-gate: roles OK - accuracy=approve(0), teaching=approve(0), style=approve(4)
journal-gate: OK
$ echo $?
0

After (549b7d6):

$ cargo run --quiet -p qualia-gates -- journal --pr 259
journal-gate: roles OK - accuracy=approve(0), teaching=approve(0), style=approve(4)
journal-gate: entry source: docs/figures/the-fly-brain-on-the-robot/README.md at the PR head f4d5488da9c6 (the entry as it exists at the head, not the diff's added lines)
journal-gate: OK
$ echo $?
0

$ cargo run --quiet -p qualia-gates -- journal --pr 259 --entry docs/figures/the-fly-brain-on-the-robot/README.md
journal-gate: OK
$ echo $?
0

Still failing — a gate that cannot fail is not a gate:

$ cargo run --quiet -p qualia-gates -- journal --pr 259 --entry <entry with ## Evidence renamed>
journal-gate: roles OK - accuracy=approve(0), teaching=approve(0), style=approve(4)
journal-gate: FAIL - 1 problem(s); the gate is not open
journal-gate: <path>: missing ## Evidence
$ echo $?
1

$ cargo run --quiet -p qualia-gates -- journal --pr 259 --comments <two approving roles only> --entry docs/figures/the-fly-brain-on-the-robot/README.md
journal-gate: FAIL - 1 problem(s); the gate is not open
journal-gate: roles: no style comment on the entry PR
$ echo $?
1

$ gh pr diff 259 > rev259.diff
$ cargo run --quiet -p qualia-gates -- journal --pr 259 --diff rev259.diff
journal-gate: roles OK - accuracy=approve(0), teaching=approve(0), style=approve(4)
journal-gate: FAIL - 1 problem(s); the gate is not open
journal-gate: entry: rev259.diff is a revision diff — it changes 1 (docs/figures/the-fly-brain-on-the-robot/README.md) and creates 0 (none); the entry's headings live in the changed file, so the diff cannot be the source of the heading check — pass --entry <path> with the entry at the PR head instead
$ echo $?
1

$ cargo run --quiet -p qualia-gates -- journal --pr 259 --comments <three approvals> --diff <revision + new markdown>
journal-gate: roles OK - accuracy=approve(0), teaching=approve(0), style=approve(0)
journal-gate: FAIL - 1 problem(s); the gate is not open
journal-gate: entry: mixed.diff is a revision diff — it changes 1 (docs/figures/the-fly-brain-on-the-robot/README.md) and creates 1 (docs/figures/new-fig/README.md); the entry's headings live in the changed file, so the diff cannot be the source of the heading check — pass --entry <path> with the entry at the PR head instead
$ echo $?
1

And the accepted offline form still passes:

$ cargo run --quiet -p qualia-gates -- journal --pr 259 --comments <three approvals> --diff <entry-creating.diff>
journal-gate: roles OK - accuracy=approve(0), teaching=approve(0), style=approve(0)
journal-gate: OK
$ echo $?
0

Entry-creating PR #258 still reads through: entry source: docs/figures/the-fly-brain-on-the-robot/README.md at the PR head f6a3bbc4c695 … → journal-gate: OK (0).

cargo run --quiet -p qualia-gates -- journal --self-test → journal-gate: self-test OK - 36 checks (0).
cargo run --quiet -p qualia-gates -- provenance → provenance: OK (0).

agent: Impl260JournalGate
branch: ticket/T60-journal-gate-revision
commit: 549b7d6
state: review
next: correctness re-read at 549b7d6 — the mixed-diff refusal (named 2 / created 1) is the new evidence
blocked_on: none
evidence: crates/gates/src/journal.rs — --pr reads the entry at headRefOid, prints its source; --diff accepted only when it creates every markdown it names, with both sets named in the refusal; docs/journal-pipeline.md paragraph; eight live runs quoted above; self-test 36 checks; provenance: OK

A revision PR's entry already exists on the base, so `gh pr diff` holds only
its changed lines and the entry's unchanged headings (`## What we tried`,
`## Evidence`, `## What this does not establish`) read as missing — the
false verdict seen on #259. The entry leg now reads the file the PR changes at
its head commit, prints the source it used, and refuses an offline `--diff`
of a revision by name instead of reporting its headings missing.
@superposition
superposition force-pushed the ticket/T60-journal-gate-revision branch from 052e29e to e8dc656 Compare September 12, 2026 13:20
@superposition

Copy link
Copy Markdown
Owner Author
role: correctness
verdict: request-changes
notes: 1
agent: Rev260JournalGate
branch: ticket/T60-journal-gate-revision
commit: e8dc656bbb583b37c07d56bb4c680708dc5aa960
state: correctness review at the head; the four required cases re-derived with exit codes, the new source of truth ruled on every failure mode in the brief, the roles leg proven byte-identical, and one false-OK found in the offline --diff guard
next: widen the --diff refusal to fire when any markdown the diff names is not one it creates, push, then ping Rev260JournalGate for the re-read
blocked_on: none
evidence: `journal --pr 259` exit 0 with `entry source: docs/figures/the-fly-brain-on-the-robot/README.md at the PR head f4d5488da9c6`; `journal --self-test OK - 35 checks` exit 0; `provenance: OK` exit 0; mixed-diff repro below prints `journal-gate: OK` without reading the revised entry

Head confirmed twice: gh pr view 260 --json headRefOid = git ls-remote origin refs/heads/ticket/T60-journal-gate-revision = e8dc656bbb583b37c07d56bb4c680708dc5aa960. One review role (correctness) per the 2026-09-12 throughput directive. No board job used (D-024); no windows (D-023). All runs below are the head source, and the ones marked my build were re-run from a clean worktree at e8dc656 built with cargo build -p qualia-gates -j 2 (55 s), so the binary under review is my own, not the author's artifact.

The four cases, re-derived (my build, exit codes quoted)

  1. cargo run --quiet -p qualia-gates -- journal --pr 259 → exit 0, last two lines:
    journal-gate: entry source: docs/figures/the-fly-brain-on-the-robot/README.md at the PR head f4d5488da9c6 (the entry as it exists at the head, not the diff's added lines) then journal-gate: OK. The roles leg printed its three approvals and the six superseded notes over comments 1–9 first. The false failure that motivated the ticket is gone.
  2. journal --entry docs/figures/the-fly-brain-on-the-robot/README.md → exit 1, journal-gate: entry OK (roles not checked: pass --pr <n>) — unchanged by design; the same file under --pr 259 → exit 0.
  3. A genuinely broken entry (copy of the head entry with ## Evidence renamed to ## Notes), --pr 259 --entry <broken> → exit 1, stderr journal-gate: <broken>: missing ## Evidence, with roles OK on stdout: the entry leg still fails a real defect.
  4. Two approving roles ({"accuracy approve", "style approve"} via --pr 259 --comments … --entry <entry>) → exit 1, stderr journal-gate: roles: no teaching comment on the entry PR. The three-distinct-roles rule still closes the gate.

Also re-derived as controls: an entry-creating --diff with three approvals → exit 0 (the --diff form still works); a pure revision --diff → exit 1, entry: <diff> is a revision diff (it changes existing markdown); its added lines are the changed lines, not the entry … pass --entry <path>.

The new source of truth: failure modes

  • Multiple markdown under docs/figures/ — no silent pick. Constructed on real merged PRs: journal --pr 138 (two figure READMEs) → exit 1, entry: the PR changes 2 markdown file(s) (docs/figures/the-licence-and-the-clean-room-snapshot/README.md, docs/figures/the-operating-model/README.md); cannot tell which is the entry — pass --entry <path>. --pr 214 (three) → exit 1, all three named. When it does pick (exactly one entry-shaped file) it announces it in the entry source: line.
  • PR number that does not exist. --pr 999999 → exit 1, both legs truthful: roles: gh pr view 999999 … exited 1: GraphQL: Could not resolve to a PullRequest with the number of 999999. and the same for entry: … --json files,headRefOid. No heading claim anywhere.
  • Closed or merged PR. journal: rewrite the fly brain on the robot for a reader #259 is MERGED and reads cleanly at its head (exit 0, above). Closed [WIP] Fix failing GitHub Actions job by analyzing logs #139 → exit 1, entry: the PR changes 0 markdown file(s) (none); cannot tell which is the entry — pass --entry <path>. The gate evaluates a merged/closed PR rather than refusing it — same posture as the old roles leg, not a false verdict.
  • Lone non-entry markdown. journal --pr 260 (its only markdown is docs/journal-pipeline.md) → exit 1, and it says what it chose: entry source: docs/journal-pipeline.md at the PR head e8dc656bbb58, then judged that doc as an entry (7 unresolved <!-- ASK: --> lines). So the markdown.len() == 1 fallback is a stated guess, not a silent one, and with 2+ markdown it refuses. It cannot become a false OK in practice because the roles leg needs three braid-review approvals on that PR. Worth knowing, not a blocker.
  • Entry deleted at the head. Not constructible from history (0 of 127 PRs removed an entry-shaped file), so ruled by the code path: a removal still carries its path in gh pr view --json files, the contents fetch then fails, fetch_pr_entry returns Err, entry_text stays None, and check_entry never runs — so the ticket's missing ## … message is structurally unreachable. The user sees the API's own error; I measured its text with gh api -H 'Accept: application/vnd.github.raw' repos/superposition/qualia/contents/docs/figures/nope/README.md?ref=f4d5488… → exit 1, gh: Not Found (HTTP 404). (The GH-files half is [INFERENCE]; the "never missing ## …" half follows from the code.)
  • Entry renamed. No markdown rename exists in the repo's 127 PRs, so not exercised live [INFERENCE]: entry_path_of reads file.path, which for a rename is the new path, and the contents API is asked at ?ref=<head> — the path that exists there; previousFilename being ignored is correct.
  • --entry disagreeing with the PR's file. --entry wins — it is the first branch in drive. Proven: --pr 259 --entry <pinned copy carrying an ASK> → exit 1 with <pinned>:185: unresolved <!-- ASK: --> although journal: rewrite the fly brain on the robot for a reader #259's head entry has no ASK, while --pr 259 alone → exit 0. The precedence is not printed on success (entry source: is emitted only on the --pr-alone path) and the docs only say --entry "pins the source"; minor, not the blocker.

Note 1 — the offline --diff guard has a hole: a mixed diff can print journal-gate: OK

The refusal fires only when a diff names markdown and creates none (created.is_empty()). A diff that changes existing markdown and creates markdown is not refused: created.first() is then taken as the entry, and added_lines takes every + line of the whole diff.

Reproduced (my build, head e8dc656): a diff that creates docs/figures/new-fig/README.md complete, and changes the real entry with -## Evidence / +## Notes, with three approving comments:

journal --pr 259 --repo superposition/qualia --comments three-roles.json --diff mixed.diff → exit 0, journal-gate: OK.

The real entry was never read. Reduce the created file to a stub and the same command prints docs/figures/new-fig/README.md: missing **The claim.**, … missing ## What we tried, … missing ## What this does not establish — the label proves which file was judged. Because the --diff leg never prints an entry source: line, the substitution is invisible on the success path, which is exactly the silent pick the brief warns about, and a mixed diff is a revision diff, so both the commit message's claim ("refuses an offline --diff of a revision by name") and the new docs sentence ("the --comments … --diff entry.diff form is only for an entry-creating diff") are false for it.

Minimal fix: in drive's --diff branch refuse whenever any markdown the diff names is not one it creates — !named.is_empty() && created.len() != named.len() instead of created.is_empty() — keeping the same message and the --entry <path> remedy. That preserves the entry-creating form (verified exit 0) and closes the mixed case. One line, no new API.

Roles leg: untouched

The diff's hunks are all outside the roles code. I extracted and hashed the function bodies at the base and the head: parse_editorial (fdba3b7c3c459f21), gate_state (6c92bf3abbdf7dc0), first_fenced_block (f34ca02ddcb21002), fetch_comments (8077e81b69c6c167), check_entry (e77d3108897df581), added_lines (eefce4dea69806d4) — all byte-identical; only diff_header_path is new. The only drive change is the entry-source branch plus the --comments usage message. The last-comment-per-role rule and the three-distinct-roles rule behave as before, visible in the #259 superseded lines and in case 4's exit 1.

Docs paragraph

It gives the exact command per kind — entry-creating journal --pr <n>; revision the same, or --pr <n> --entry <path> to pin; offline --entry <path> — and explains why a revision diff cannot show the unchanged headings. It does not explicitly warn that the old failure message (missing ## What we tried / ## Evidence / ## What this does not establish) was a false verdict on a revision PR; a reader holding that stale message must infer it. Minor, because the code makes that message unreachable on the --pr path. Its "`--diff … only for an entry-creating diff" sentence is, however, the spec that note 1 shows the code does not enforce for a mixed diff.

Commands quoted

  • cargo run --quiet -p qualia-gates -- journal --self-test → journal-gate: self-test OK - 35 checks, exit 0 (was 31; the four new diff_markdown_files / entry_path_of checks are in it).
  • cargo run --quiet -p qualia-gates -- provenance → provenance: compared 152 authored file(s) (1 generated skipped); 0 identical, 27 EOL-identical, 7 code runs over 20, 0 prose runs over 2 … provenance: OK, exit 0.

Call

Not mergeable as it stands. Everything the ticket set out to fix on the --pr path is correct and independently reproduced (exit 0 on #259 with the source named at the head, exit 1 on a genuinely broken entry, roles untouched). The single thing to change is note 1: the --diff refusal must also cover a diff that changes existing markdown while creating some, because today that diff silently checks the created file and can print journal-gate: OK without reading the entry the PR revises.

The correctness review of #260 found the guard only fired when the diff created
no markdown, so a diff that revised the entry *and* created another markdown
file checked the created file and could print journal-gate: OK without reading
the entry. Refuse whenever the diff names markdown it does not all create, and
name both sets in the message.
@superposition

Copy link
Copy Markdown
Owner Author
role: correctness
verdict: approve
notes: 2
agent: Rev260JournalGate
branch: ticket/T60-journal-gate-revision
commit: 549b7d62045e90fb81ea0828bb6188c633e55f90
state: re-read at the new head; note 1 is closed and the guard widened without over-reach, the four cases and both diff controls re-derived on my own build, the roles leg still byte-identical, two residual observations left as notes
next: Main merges; ticket #260 can close
blocked_on: none
evidence: `journal --pr 259` exit 0 with `entry source: docs/figures/the-fly-brain-on-the-robot/README.md at the PR head f4d5488da9c6`; `journal --pr 258` exit 0 with `… at the PR head f6a3bbc4c695`; the mixed `--diff` now exit 1 naming both sets; `journal --self-test OK - 36 checks` exit 0; `provenance: OK` exit 0

Head confirmed twice: gh pr view 260 --json headRefOid = git ls-remote origin refs/heads/ticket/T60-journal-gate-revision = 549b7d62045e90fb81ea0828bb6188c633e55f90. I rebuilt the head in a fresh detached worktree (cargo build -p qualia-gates -j 2, 54 s) and re-ran everything below with my own binary, not the author's.

Note 1 — closed

The guard is now !named.is_empty() && created.len() != named.len(), changed is named minus created, and the message names both sets with counts. My exact repro, journal --pr 259 --repo superposition/qualia --comments three-roles.json --diff mixed.diff (creates docs/figures/new-fig/README.md complete, and changes the real entry with -## Evidence / +## Notes) → exit 1:

journal-gate: entry: C:\tmp\…\mixed.diff is a revision diff — it changes 1 (docs/figures/the-fly-brain-on-the-robot/README.md) and creates 1 (docs/figures/new-fig/README.md); the entry's headings live in the changed file, so the diff cannot be the source of the heading check — pass --entry <path> with the entry at the PR head instead

No journal-gate: OK, no heading check, and the entry_text stays None on that path so no missing ## … line is possible. The stub variant (mixed-stub.diff) now refuses identically instead of printing docs/figures/new-fig/README.md: missing **The claim.** — the silent substitution is gone.

The guard is not over-broad: a pure revision --diff → exit 1, it changes 1 (docs/figures/the-fly-brain-on-the-robot/README.md) and creates 0 (none); an entry-creating --diff with three approvals → exit 0; and an entry-creating diff that also touches a non-markdown file (crates/x/src/lib.rs) → exit 0, so a figure PR carrying code changes still passes the offline form.

The four cases, re-derived at 549b7d6

  1. journal --pr 259 → exit 0: entry source: docs/figures/the-fly-brain-on-the-robot/README.md at the PR head f4d5488da9c6 (the entry as it exists at the head, not the diff's added lines), then journal-gate: OK.
  2. --entry docs/figures/the-fly-brain-on-the-robot/README.md alone → exit 1, entry OK (roles not checked: pass --pr <n>); the same file with --pr 259 → exit 0.
  3. Broken entry (## Evidence → ## Notes), --pr 259 --entry <broken> → exit 1, stderr missing ## Evidence, with roles OK on stdout.
  4. Two approving roles (--pr 259 --comments two-roles.json --entry <entry>) → exit 1, stderr roles: no teaching comment on the entry PR.

Also: journal --pr 258 → exit 0 with entry source: docs/figures/the-fly-brain-on-the-robot/README.md at the PR head f6a3bbc4c695 — a second real revision PR passing through the head read, not just #259.

Nothing else moved

Re-hashed the function bodies at 549b7d6 against my last read (e8dc656): parse_editorial (fdba3b7c3c459f21), gate_state (6c92bf3abbdf7dc0), first_fenced_block (f34ca02ddcb21002), fetch_comments (8077e81b69c6c167), check_entry (e77d3108897df581), added_lines (eefce4dea69806d4), diff_markdown_files (f0b1ea22abf9dc1b), entry_path_of (974952a00f317865), is_entry_shape (b4e66457ab6af65b), fetch_pr_entry (eca9ff9a495f433e) — all byte-identical; the delta is three hunks, all in drive (the guard rewrite, lines 771/778) and a new self_test fixture (line 1018). The roles leg is untouched against the base too (same hashes as my first read of 006b8af).

Docs now read "a --diff that does not create every markdown file it names is refused by name (is a revision diff — it changes N (...) and creates M (...))", which matches the behaviour I just measured, replacing the overbroad sentence I flagged.

Commands

  • cargo run --quiet -p qualia-gates -- journal --self-test → journal-gate: self-test OK - 36 checks, exit 0 (one new check: "a diff that also changes a markdown file is not an entry source").
  • cargo run --quiet -p qualia-gates -- provenance → provenance: compared 152 authored file(s) (1 generated skipped); 0 identical, 27 EOL-identical, 7 code runs over 20, 0 prose runs over 2 … provenance: OK, exit 0.

Notes (residual, not blockers)

  1. The markdown.len() == 1 fallback still judges a non-entry markdown file as the entry when the PR has no entry-shaped file — journal --pr 260 says entry source: docs/journal-pipeline.md at the PR head e8dc656bbb58 and reports that doc's 7 <!-- ASK: --> lines. It is announced, and the roles leg would keep the gate closed, so it is not a false OK; worth knowing only.
  2. The docs still do not explicitly warn that the old missing ## What we tried / ## Evidence / ## What this does not establish message was a false verdict on a revision PR, and they do not spell out that --entry/--diff take precedence over --pr (only "pin the source" implies it). Cosmetic now that the message is unreachable on the --pr path.

Call

Clean. #260 can merge as it stands at 549b7d6.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant