Skip to content

No justfile and no AGENTS.md: the org's pre-commit gate cannot be run here #28

Description

@CameronBrooks11

gerberdiff is the only code member of this org with neither a justfile nor an AGENTS.md.

Measured

$ for r in partspec netspec slicelab orlab prusaslicer-py gerberdiff; do
    printf '%-16s justfile=%s AGENTS.md=%s\n' "$r" \
      "$([ -f $r/justfile ] && echo y || echo n)" \
      "$([ -f $r/AGENTS.md ] && echo y || echo n)"; done
partspec         justfile=y AGENTS.md=y
netspec          justfile=y AGENTS.md=y
slicelab         justfile=y AGENTS.md=y
orlab            justfile=y AGENTS.md=y
prusaslicer-py   justfile=y AGENTS.md=y
gerberdiff       justfile=n AGENTS.md=n

grep -rn 'just ' CONTRIBUTING.md README.md docs/*.md .github/workflows/*.yml returns
one hit, and it is the English word inside a comment in docs.yml.

Why it matters

Org contract section 8 makes just check && just test the pre-commit gate for every
member. Here neither command exists, so the gate cannot be run at all -- not skipped,
not weakened, absent. What a contributor runs instead is the four commands in
CONTRIBUTING.md, typed by hand:

uv run ruff check gerberdiff/ tests/
uv run ruff format gerberdiff/ tests/
uv run mypy gerberdiff/ tests/
uv run pytest tests/ -q

Three gaps between that list and what ci.yml actually enforces:

  • ruff format (mutating) versus CI's ruff format --check. Running the documented
    command makes the working tree pass; it does not tell you whether it would have
    failed.
  • No coverage gate. CI runs pytest --cov=gerberdiff --cov-fail-under=90; the
    documented command runs pytest tests/ -q. A change that drops coverage below 90
    passes locally and fails in CI.
  • No ASCII check. CI has a grep -rP '[^\x00-\x7F]' gerberdiff/ tests/ *.md *.toml
    step, and CONTRIBUTING.md documents the rule with a 12-row table of banned
    characters and a here-doc Python script to check it. Nothing runs that script; the
    only enforcement is the CI step, i.e. after the push.

So "ran the documented checks locally" and "will pass CI" are different claims in this
repo, and the difference is silent in the direction that reads as success.

And there is no AGENTS.md

The exit-code contract this repo settled in 0685cde (A3) -- 0 identical, 1
different, 2 indeterminate, 4 environment fault, 64 usage, with 2 spelled as a
third diff outcome rather than a verdict -- is currently recorded only in a
docstring in gerberdiff/cli.py, in DiffOutcome in gerberdiff/geometry/types.py,
and in docs/schema.md. There is no repo-level file telling an agent that this is
settled and not to relitigate it. Nor that planning/ is gitignored working material
rather than a plan, that docs/DECISIONS.md does not exist here, or that
geomdiff can return 2 and the raster diff cannot.

Done when

  • a justfile exists whose check recipe runs the same four things ci.yml
    runs (lint, format-check, ASCII, typecheck) and whose test recipe carries the
    --cov-fail-under=90 gate, so just check && just test is CI-equivalent rather
    than a shorter list with the same name
  • an AGENTS.md exists naming the org contract as the floor and carrying what is
    specific to gerberdiff
  • CONTRIBUTING.md points at the recipes instead of listing commands that drift
    from CI

Deriving the recipes from ci.yml rather than copying a sibling's justfile is the
point: partspec and netspec typecheck with pyright, this repo uses mypy, and no
sibling has the ASCII step.

No activity

Activity on this issue will appear here.

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

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions