graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
Document native formal learning integration
Rach Pradhan4e08c05ede9b
diff --git a/formal/README.md b/formal/README.mdindex 36d9d2c5..ad29451b 100644--- a/formal/README.md+++ b/formal/README.md@@ -23,9 +23,9 @@ counterexamples, and runtime regressions.See the [ranked extension plan](roadmap.md) for the next ownership, retry,budget, and session properties to model.-The [DGM integration design](dgm-integration.md) separates formal admission-from task correctness and measured fitness, and identifies the native promotion-paths that need their own integration.+The [DGM integration guide](dgm-integration.md) separates formal admission+from task correctness and measured fitness, covers the optional Python and+native learning gates, and identifies the remaining ungated promotion path.## Scopediff --git a/formal/dgm-integration.md b/formal/dgm-integration.mdindex 3fef1ede..566e438e 100644--- a/formal/dgm-integration.md+++ b/formal/dgm-integration.md@@ -86,25 +86,26 @@ checks the signature, prompt/report hashes, original held-out hash, preflightreceipt, pinned identity and archived checker evidence. It also runs the currentpinned model checks; their raw output need not match an earlier successful log.-## Other native promotion paths--The repository also has native learning and persona promotion paths. Integrating-the Python example alone does not gate all of them:--- `src/learn_tournament.zig` selects one primary winner and applies holdout- eligibility. Formal evidence belongs in admission and final eligibility,- without allowing it to rescue a primary or holdout rejection.-- `src/learn_run.zig` persists checkpoints and comparison records. A resumed run- needs the same checked identity; a receipt from an earlier source cannot be- reused merely because the prompt genome matches.-- `src/learn_receipt.zig` signs aggregate learning evidence. Adding a formal- receipt to this path requires a versioned signed schema and validation.-- `src/fleet.zig` promotes local archive champions. Historical scores without- formal evidence cannot be represented as formally checked evaluations.--These are separate integration points, not properties established by the-Python gate. A rollout must identify which entry points enforce formal mode,-and preserve explicit distinction between unchecked and checked archives.+## Native learning and remaining promotion paths++Native `graff learn` has a separate opt-in `formal_check` configuration; see+[local learning](../docs/local-learning.md) for setup and its trust boundary.+`src/learn_formal.zig` checks the pinned baseline before mutation and binds+evidence to the parent or selected prompt. The existing tournament and holdout+rules still decide candidate eligibility.++Formal-enabled runs use pending-record version 2 and run-record version 4.+Resume and both manual and automatic promotion recheck the stored evidence and+pinned identity. Legacy records remain readable but cannot satisfy formal-mode+promotion. The manifest's executable must also be a pinned input and argument+to both learning adapters; this records the adapter contract, not a proof that+an arbitrary adapter executes that argument.++Native formal-enabled runs stay local: explicit submission is rejected, and+automatic learning omits contribution. The signed aggregate receipt format+does not yet bind formal evidence. The separate `src/fleet.zig` persona archive+promotion path remains ungated. Historical scores must not be presented as+formally checked merely because a newer evaluation enables this option.## Performance evidence remains separate