Skip to content

Document the local checks and index the example packs (closes #31, closes #34) - #62

Merged
kikashy merged 1 commit into
mainfrom
contributor-docs
Aug 15, 2026
Merged

Document the local checks and index the example packs (closes #31, closes #34)#62
kikashy merged 1 commit into
mainfrom
contributor-docs

Conversation

@kikashy

@kikashy kikashy commented Aug 15, 2026

Copy link
Copy Markdown
Contributor

Closes #31. Closes #34.

Two onboarding documents, on separate files, neither touching code.

CONTRIBUTING.md — a Local checks section

The Python version CI currently uses (3.12, stated as what the workflow uses rather than a declared project minimum), the dependency install, and the test command — taken from .github/workflows/conformance.yml rather than restated from memory.

It also carries a warning I earned rather than invented:

Install the dependencies even if the suite appears to run without them. requirements-dev.txt pins jsonschema[format-nongpl], and the format keyword is only checked when those extras are present. Without them, jsonschema silently ignores format, so conformance cases that exist to prove a malformed URI or timestamp is rejected come back valid and the suite passes while checking less than it says it does.

I spent most of a working session treating 2 failed, 45 errors as ambient environment noise before finding the cause. structural-relative-pack-id and structural-invalid-created-at were returning valid. That is precisely the confusion a first-time contributor hits with no way to diagnose it, and it is worth four sentences in the contributor guide.

examples/README.md — an index of the five packs

A compact table linking each example once, naming its synthetic domain and one feature genuinely worth opening that file for. These were derived by reading the documents, not guessed:

Example Why open it
data-request-intake-triage the only optional evidence requirement, and the only attestation evidence
minimal-expense-approval clearest ordered comparisons — in, greater-than, less-than-or-equal — plus a nested not
records-disposition-review evidence-light by design, so rule structure carries the decision
software-change-review two independent evidence-present conditions inside one all
supplier-invoice-approval an exception alongside a not, worth reading together because they are not the same thing

With links to TESTING.md, docs/field-guide.md and the schema, and the standing notice: synthetic and non-operational, not authorization or proof any decision is safe, no real or sensitive data, and no fetching of example source locators during ordinary validation.

Suite: 64 passed, 529 subtests.

🤖 Generated with Claude Code

@kikashy
kikashy force-pushed the contributor-docs branch 2 times, most recently from 15556b5 to 0014a97 Compare August 15, 2026 01:02
…oses #34)

CONTRIBUTING.md gets a Local checks section: the Python version CI currently
uses, the dependency install, and the test command, taken from the workflow
rather than restated from memory.

It also carries a warning I earned rather than invented. requirements-dev.txt
pins jsonschema[format-nongpl], and the format keyword is only checked when
those extras are installed. Without them jsonschema silently ignores format, so
the two corpus cases that exist to prove a malformed URI and a malformed
timestamp are rejected come back VALID and the suite passes while checking less
than it claims. I spent this session treating that as ambient environment noise
before finding the cause, which is exactly the confusion a first-time
contributor would hit and have no way to diagnose.

examples/README.md indexes the five synthetic packs. Each row names its domain
and ONE feature genuinely worth opening that file for, derived by reading the
documents rather than guessing: the only optional evidence requirement and the
only attestation evidence; the clearest ordered comparisons plus a nested not;
the evidence-light pack where rule structure carries the decision; two
independent evidence-present conditions inside one all; and an exception
alongside a not, which are worth reading together because they are not the same
thing.

Both carry the standing notice: synthetic and non-operational, not
authorization or proof that a decision is safe, no real or sensitive data, and
no fetching of example source locators during ordinary validation.

Signed-off-by: kikashy <kikashy@hotmail.com>
@kikashy
kikashy merged commit 99948f2 into main Aug 15, 2026
5 checks passed
@kikashy
kikashy deleted the contributor-docs branch August 15, 2026 01:04
@github-actions

Copy link
Copy Markdown

🎉 Thank you for your contribution to Judgment Pack!

If you’d like another task, choose a path that interests you:

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.

Add a GitHub-facing index for the example packs Document the local contributor test workflow

1 participant