Kernel: acceptance evidence from the right reporter, against the approved contract

Merged
DO
4d ago
+3257-238

Closes #108.

Acceptance evidence is now read against the contract a person approved, and only from the reporter configured for each criterion's kind. Before this, the criteria came from the head, and any App's result counted. The rulings, with the Maintainer's three decisions, are on #108.

What changes

  • The approved contract:

    • facts.acceptance becomes {approved, head, results}.
    • The criteria and their kinds come from the contract a person approved, at approved.commit.
    • A sha256: digest of 64 hex characters covers the contract and the tests it names.
    • approved.commit must be held by the approver's own review on that commit: a person with write, in state approved, not dismissed by a person.

  • Two new Holds, both needs_you:

    • contract_not_approved: no approval, an approval that isn't a person's, or one with no matching review.
    • contract_changed: the head's digest differs from the approved one, including deletion and a change to a test the contract names.

    Both are read after foreign_checks and before mergeable. A queued item leaves the queue under either.

  • acceptance: null now means the linked issue asks for no contract, read in full. Reading the issue waits on adapters/; the Maintainer accepted an issues: read grant for the Controller.

  • Reporters:

    • A new acceptance_reporters setting maps each criterion kind to a required deterministic Lens. Only test → verify is filled. human never has a reporter.
    • A result from another App, workflow file or check name is acceptance_unreadable (from_another_app, from_workflow, from_another_check), reusing #60's pin.
    • A missing or misshapen setting defers as acceptance_reporters_unreadable.

  • A human criterion passes only on an approving review of this content by a person with write. One such review covers every human criterion (the Maintainer's call). A dismissal ends it only when a person dismissed it. That departs from the ruling's word "undismissed" to follow #61: "what a person placed, only a person ends". 0025's Why records it.

  • Readability: a review missing its commit, content id or a dismissal field is review_unreadable, so nothing crashes on a short read.

  • Lifecycle: verifying → converged by a person, when the person confirms a human criterion. It is bounded, because no cycle can depend on it without a person.

  • Simulator:

    • A push can edit or delete the contract, and settling puts a deleted one back.
    • A person approves or withdraws it.
    • Other Apps, workflows and checks give results.
    • The simulator asserts that only a person passes a human criterion.

  • Records:

    • Decision 0025: acceptance, new.
    • Decision 0026: replaces 0022 and restates it, with two rows corrected: the contract is read at the approval's commit, and whether one exists comes from the linked issue. Two of 0022's waiting rows now name their tests.
    • Design: trial P-38.

Verified on a plain git archive export with PATH=/usr/bin:/bin, at 4a58fc3, rebased onto #149:

  • make verify passes (527 tests).
  • python3 -m tools.mutants kills 446 of 446. Four check_decisions mutants timed out on the loaded Mac and were killed on a rerun two at a time. CI's shards are the final word.
  • Each new mutant fails its own test, and check_decisions is clean.

Reviewed by: a fresh-context Claude review and a security pass. All five findings are fixed:

  • 0022 made false, so it is replaced;
  • a crash on a review missing a field;
  • a crash on a missing reporter setting;
  • the contract's approval taken on the port's word;
  • a digest of any length.

AGY (Gemini 4 Argon) on 87bfc2f: approve, no findings. Muse was unavailable (quota) until 2026-10-19.

CodeRabbit: four points were answered by Auto-fix in 16f0926:

  • decision 0025's Status no longer recounts history;
  • the design names the newest person's approval as the baseline;
  • the simulator keeps a contract's criteria across re-approval;
  • the port's choice of approval is clarified.

The fifth point, a mutant that was killed by a crash, now produces a wrong decision and is killed by its own test's assertion (4a58fc3).

🤖 Generated with Claude Code

Summary by CodeRabbit

  • New Features

    • Acceptance criteria are tied to a human-approved contract that must match the pull request’s current content. Missing approval or contract changes hold the item for review and prevent work from starting.
    • Check-based criteria require results from the configured reporter and its matching App and workflow. Human criteria require approval of the current content.
    • Reporter settings specify which checks can report each criterion type; unset reporters make those results unreadable.
    • People can move an item from verifying to converged without a time limit.

  • Documentation

    • Added guidance on acceptance contracts and check identity, and expanded platform trials to cover how dismissed reviews are recorded.