Download AGENTS.md from SNAPKITTYWEST/montrepol: direct link, hf CLI and curl.
- Browser
- Download file 5.04 kB
-
https://huggingface.co/SNAPKITTYWEST/montrepol/resolve/main/AGENTS.md
- Command line
-
hf download hf://SNAPKITTYWEST/montrepol/AGENTS.md
-
curl -L -o AGENTS.md https://huggingface.co/SNAPKITTYWEST/montrepol/resolve/main/AGENTS.md
AGENTS
The standing brief for anyone, human or otherwise, changing this repository.
Read README-project.md for the shape of it, then VERIFICATION.md for which gate
discharges what.
The rules
Every violation mp-gate reports names the rule it breaks, so a red gate says
which promise failed rather than merely that something is wrong. Nothing else
in the repository defines an R-number.
| Rule | What it says | Enforced by |
|---|---|---|
| R1 | The model is the single source. Every claim lives in model/*.toml; CONFORMANCE.md is generated from it. IDs are unique, well formed and name a real package. |
mp-gate |
| R2 | Levels are load-bearing. An ID is build or some-true, never open or proved. some-true cites an authority that exists. A proved ledger claim names an Agda file and lemmas that exist. No build or open claim uses asserting words ("proves", "guarantees", ...). Every authority is cited. |
mp-gate |
| R3 | Every ID is tagged on a test in its own package, and every test tag is a registered ID. | mp-gate |
| R4 | Nothing is deferred: no deferral markers, no stubs; in Agda, no postulate, holes or checker-disabling pragmas or flags. |
mp-gate |
| R5 | Everything is total: no partial Prelude functions (head, fromJust, maximum, !!, error, ...), nothing unsafe, warnings are errors. Every Agda module is --safe and imported by formal/Everything.agda. |
mp-gate, GHC -Wall -Werror, Agda --safe |
| R6 | Nothing arrives from outside GHC and this repository, except in liquid/, which has its own cabal.project and may use Hackage and Z3; the root build may not include it and no core package may depend on it. Boot packages carry both version bounds; every package directory is in cabal.project; no package repository is enabled; every Haskell source starts with -- SPDX-License-Identifier: AGPL-3.0-or-later, and every .cabal file has it straight after cabal-version. |
mp-gate, active-repositories: :none |
Adding a capability
In this order, because the order is the discipline:
- A row in
model/ids.toml, with its level, its claim and what it is checked against. - A test tagged with the ID (
unit "XX-00" ...,prop "XX-00" ...) that fails without the implementation. - The implementation.
- At least one entry in
model/mutants.toml: a defect planted in the implementation and the IDs that must catch it. cabal run mp-gate -- write, thencabal test all,cabal run mp-gateandcabal run mp-gate -- mutants.
Adding a proof
- The module under
formal/Montrepol/, starting with the SPDX line and{-# OPTIONS --safe --without-K #-}, using only whatformal/defines. - An
importof it informal/Everything.agda, or the gate fails: an unimported module is a proof nothing checks. - A ledger row at level
proved, evidenceformal/Montrepol/File.agda: lemma, ..., stating exactly what the lemma's type says, and what is not proved. - A mutant in
model/mutants.tomlwithpackage = "formal": a false variant of the statement that Agda must reject, withexpectnaming the file the error must be located in.
Adding a refinement
- The
{-@ f :: ... @-}spec next tofin the core source. Neverassume,lazyorignore: the gate refuses them. - The module in
liquid/mp-liquid.cabal'sexposed-modules, with the coresrc/directory in itshs-source-dirs, or the spec is a comment nothing checks, and the gate says so. - A ledger row at level
refined, evidencepackages/.../File.hs: f, .... - A mutant with
package = "liquid"that Liquid Haskell must reject with an error located in the file.
Choosing an oracle
A test is only as good as what it compares against. Prefer, in order:
- An independent algorithm for the same quantity (Leibniz for Bareiss, the definition for Strassen, Floyd–Warshall for min-plus powers, brute force for Berlekamp–Massey).
- A theorem that does not depend on the code under test (von Staudt–Clausen,
e^psi(x) = lcm(1..x), Euler's formula forzeta(2k)). - A published table, cited in
model/authorities.tomland committed underoracles/when it is data.
Never compare a function with itself, and never let a table be an input and its own check.
Writing a gate
A gate that cannot fail is worse than no gate, because it reads as evidence.
Before relying on one, plant the defect it exists to catch and confirm it
fires. For the rules that is mp-gate-test (GT-01..GT-07). For the
mathematics it is model/mutants.toml. A mutant that only breaks the build
does not count as caught.
A gate that reads source must survive reading its own. MP.Gate.Scan spells
its forbidden names in halves for that reason; exempting the file would leave a
hole exactly where a defect parked in the gate would sit.
Comments
Explain why, not what. A comment earns its place by recording why a decision went one way when it could plausibly have gone another.