Skip to content

The local NOW preview says OK where the required check context says FAIL -- two conditions previewed by nothing #2994

Description

@gHashTag

The local NOW preview says OK where the required check context says FAIL

docs/now/README.md documents three conditions — presence, freshness, and
"at least one Markdown heading and at least one bullet" — and then says:

The same three conditions are previewed locally by scripts/verify.sh and
enforced before commit by .githooks/pre-commit, scripts/pre-commit,
t27c check-now, and tri hooks now-gate.

tools/check_now_entry_shape.py enforces two more, and it is run by the
required check context (check-now-freshness.yml):

  • the first line must be # NOW -- <title> (YYYY-MM-DD)
  • there must be a ## section heading

Both are documented in the script's own docstring (lines 29–33) and in no file a
contributor reads.

Measured

A docs/now/ entry committed in the wrong shape — a plain # Title first line
and one long bullet, which satisfies every condition the README lists:

instrument exit says
tri hooks now-gate 0 NOW gate PASSED: 2026-08-30-a-self-referencing-struct-…
t27c check-now 0 ✅ NOW synced … build authorized
scripts/verify.sh gates:OK (now-in-diff:yes | now-date:fresh | ascii:clean)
tools/check_now_entry_shape.py 1 FAIL: 1 of 3 entr(y/ies) do not say anything checkable

Note the second column of the first two rows: they name a different entry than
the one the change adds.
They answer is the newest entry by filename date
fresh
, which is a question about the tree; the blocking gate asks is the entry
this diff ADDS well formed
, which is a question about the change. Two
populations, one label.

Cost, paid

This made check red on #2991 — a required context, on a pull request whose
NOW entry satisfied every condition its own README states. The repair was to
copy the shape out of a neighbouring entry, which is not what a documented gate
should require.

Two repairs, and they are not the same

  1. Cheapest and honest: docs/now/README.md states all five conditions and
    says which instrument enforces which. The sentence claiming the local tools
    preview "the same three conditions" comes out, because they do not preview
    the two that block.
  2. Better: the local preview asks the blocking gate's question — the entry
    the diff ADDS, in the shape the required context requires — so a green
    scripts/verify.sh means the same thing as a green check. That is the
    difference between a preview and a different check with a similar name.

Neither is mine to choose: (2) changes what four local tools do, and this
repository's own log records that a preview which disagrees with its gate is
worse than no preview.

Refs #2961

Activity

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions