Kernel: what each check conclusion means #35

Activity

1. don-petry

   added a parent issue on Oct 11, 2026

   • Epic: nine gaps in the Kernel, found in review #29
2. don-petry commented on Oct 14, 2026

   

   don-petry

   on Oct 14, 2026

   ContributorAuthor

   More actions

   Advice from the Solution Architect persona, not a ruling. Asked while revising the pull request "Context for the Factory's authors: lessons, standards, decisions and the checks that hold them".

   neutral on a required check is not passed. That much is settled: I-27 admits a model Lens only on content that "has passed" the deterministic Lenses, and the lesson "Could not check was read as nothing to check" forbids reading silence as a pass. The proof of concept's rule, that neutral does not block, is right for a check that is not required and wrong for one that is: a required Lens that says nothing has not judged the content.

   Open is which of the other three it is:

   • Failed, today's code: anything but success and pending is check_failed, and that admits a fix Run with nothing to fix.
   • Pending: waits for ever, in silence.
   • Unreadable: a deferral with its own reason, and a Hold at the state's staleness limit.

   Recommended: unreadable. A required Lens that is neutral by design should change the required set, not the rule. Not verified: how the facts port will map skipped, cancelled, timed_out and stale onto the schema's four values.

   A fresh agent given only "a neutral required check is not counted as a failure" read it as passed. That reading is the one advised against here.
3. don-petry commented on Oct 14, 2026

   

   don-petry

   on Oct 14, 2026

   ContributorAuthor

   More actions

   #35 Kernel: what each check conclusion means

   Working ruling (Solution Architect, delegated). The Maintainer may overturn it in review.

   Question. For each conclusion GitHub can give a required check, is it passing, failing, pending or unreadable?

   Options.

   1. Map each conclusion as data:
      • Passing: success only.
      • Failing: failure and timed_out.
      • Pending: the queued and in-progress states, and a check that is absent.
      • Unreadable: neutral, skipped, cancelled, stale, action_required, startup_failure, error, and any value the map does not know. Unreadable means the Kernel defers, and the item becomes stale at its limit (Kernel: when waiting becomes the Maintainer's to see #36).
   2. Today's rule: everything except success and pending fails. This admits a fix Run with nothing to fix.
   3. The proof of concept's rule: neutral, skipped and cancelled pass. A Lens that did not judge is then read as having passed (L-07).
   4. Everything except success is pending. The item waits for ever, and nobody is told.

   Ruling: 1.

   • I-27 admits a model Lens only on content that "has passed".
   • L-07, C-1 and I-13 say that what could not be checked yields a deferral, never an admission.
   • timed_out counts as failing because a hung test usually belongs to the content (L-39), and attempts bound it.
   • A required Lens that is neutral by design should leave the required set for that class or scope (§5.3), not bend this rule.
   • GitHub treats a skipped required check as passing. The Kernel is stricter on purpose, and L-36 already bans the path filters that cause skips.

   Acceptance criteria.

   1. The facts carry GitHub's own conclusion; the port maps nothing. config/defaults.json gains check_conclusions, which maps each conclusion to passing, failing, pending or unreadable, and schemas/config.schema.json describes it. A value missing from the map is unreadable. Counter-example: examples/invalid/config.conclusion-mapped-to-nothing.json.
   2. These tests are written first:
      • test_a_neutral_required_check_defers, covering neutral, skipped, cancelled, stale and an unknown value: outcome defer, reason check_unreadable, no Run.
      • test_a_timed_out_required_check_goes_back_to_the_author.
   3. Three mutants: neutral read as passing, neutral read as failing, and an unmapped value read as passing.
   4. Documents: design §3.3 checks and §4.2 item 1; L-07.

   Confidence. Medium to high. I would rule otherwise only for the scope, not the map: if code scanning reports neutral on documentation-only changes, that Lens's scope should be narrowed and the map left as it is.

   Needs the Maintainer? No.
4. don-petry

   closed this as completedin #86on Oct 15, 2026