fv-skills-baif 2.0.0 → 2.0.1

package/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to FVS (Formal Verification Skills) will be documented in th
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [2.0.1] - 2026-07-01
+
+Documentation polish. No code or behavior changes.
+
+### Changed
+- README "How It Works" now documents the Aeneas extraction repair loop, the trust audit, and the paper track's crypto loop -- previously only the v1.x five-stage functional-correctness flow was described; the tagline and Prerequisites now cover both the code and paper tracks
+- `/fvs:help` documents the crypto loop's `--codex` single- vs dual-runtime flag (which stages accept it, what it swaps, and the no-silent-fallback behavior), and Quick Start / Core Workflow now surface the extraction and crypto-loop entry points
+- Install screenshot (`assets/terminal.svg`) version label updated to the v2.0 line
+
 ## [2.0.0] - 2026-06-30
 
 Structural cleanup and bundle architecture. Updating from v1.3 applies all renames, moves, and removals automatically (deleted and renamed commands/agents self-heal on install); the installer prints a one-time summary of the changes below.

package/README.md

@@ -2,7 +2,7 @@
 
 # FORMAL VERIFICATION SKILLS
 
-**Formal verification of Rust code with AI-assisted specification and proof. Multi-framework, multi-runtime.**
+**Formal verification in Lean 4 with AI-assisted specification and proof — for Rust code (via Aeneas) and for maths/crypto papers. Multi-runtime.**
 
 [![npm version](https://img.shields.io/npm/v/fv-skills-baif?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/fv-skills-baif)
 [![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
@@ -54,9 +54,10 @@ Verify with `/fvs:help` inside your chosen runtime.
 
 ### Prerequisites (Lean 4 / Aeneas)
 
-- A Lean 4 project with `lakefile.toml` and `lean-toolchain`
-- Aeneas-generated output (`Types.lean`, `Funs.lean`) from your Rust source
-- Lean 4 toolchain installed and working
+- A working Lean 4 toolchain, and a Lean project with `lakefile.toml` and `lean-toolchain`
+- **Functional-correctness track:** Aeneas-generated Lean (`Types.lean`, `Funs.lean`). Produce it from a Rust crate with `/fvs:aeneas-extract`, or supply the output of an existing Aeneas run.
+- **Paper track:** no Rust or Aeneas needed — bring your paper/source material (PDF, LaTeX, images).
+- **Optional:** the Codex CLI, to run the crypto loop's thinking stages dual-runtime (`--codex`).
 
 ### Recommended: Lean LSP MCP Server
 
@@ -150,7 +151,9 @@ Commands are grouped into five bundles. Each bundle has a **router** command tha
 
 ## How It Works
 
-FVS follows a five-stage workflow. Each stage builds on the previous.
+### Functional-correctness track (Rust → Lean 4)
+
+This track verifies Rust that Aeneas has lowered to Lean 4. Starting from a Rust crate, `/fvs:aeneas-extract <path>` drives it through the bounded **extraction repair loop** — pin audit → classify → auto-apply / bisect / gate / escalate → reversible records — until you reach a clean build or a documented escalation. It writes reversible source records (`src-modifications.diff` plus a derived `.json`/`.md` and `src-assumptions.md`) at the crate root and never edits generated Lean. Once you have `Types.lean` / `Funs.lean`, the five-stage verification workflow begins:
 
 ### 1. Map
 
@@ -172,6 +175,23 @@ FVS follows a five-stage workflow. Each stage builds on the previous.
 
 `/fvs:lean-refactor <spec_path>` — Refactor, simplify, and decompose verified proofs. Applies tiered heuristics (dead code removal, simp sharpening, tactic golf, smart automation) while verifying compilation after every change. Three modes: safe, balanced (default), and aggressive.
 
+### 6. Audit
+
+`/fvs:trust-audit <target>` — Build-backed audit of the trust surface. Runs a green-build precondition, then uses `#print axioms` to classify every in-scope declaration as verified / `sorry` / axiom. The classical trio (`propext`, `Classical.choice`, `Quot.sound`) is auto-noted as Lean/Mathlib-standard; any project-custom axiom must be justified or the gate reports NOT-CLEAN. Produces a re-runnable, dependency-ordered table under `.formalising/audits/`.
+
+### The paper track (maths / crypto)
+
+The paper track formalises papers directly into Lean 4 — no Rust, no Aeneas. Two entry points:
+
+- **One-shot:** `/fvs:lean-formalise` reads your PDFs / images / LaTeX (optionally grounded in a NotebookLM knowledge base via `/fvs:kb-setup`) and produces Lean definition and spec files in a single pass.
+- **Iterative crypto loop:** for larger crypto formalisations, a topic-based, restartable loop of four stages:
+
+  `/fvs:crypto-plan` → `/fvs:crypto-execute` → `/fvs:crypto-eval` → `/fvs:crypto-followup` → repeat
+
+  A high-effort thinker authors each bounded plan; the executor runs it under a green-build guard; an adversarial eval tries to refute the spec, proof, and assumptions and ends in exactly one of ACCEPT / FOLLOWUP / HUMAN_RULING / BLOCKED; follow-up turns findings into the next plan (halting for a human ruling on modeling decisions).
+
+  **Single- vs dual-runtime (`--codex`).** By default the loop is single-runtime — the thinking stages (`crypto-plan`, `crypto-eval`, `crypto-followup`) run the in-runtime `fvs-crypto-thinker`. Pass `--codex` to hand a stage's thinking to an independent **Codex CLI** thinker instead, so the adversarial planner/evaluator runs on a *different engine* than the executor and blind spots don't correlate. `crypto-execute` is the runtime-neutral executor and takes no `--codex`. Without the Codex CLI installed, a `--codex` stage stops with an install hint rather than silently falling back.
+
 ---
 
 ## Uninstalling

package/commands/fvs/help.md

@@ -23,18 +23,25 @@ Commands are grouped into five bundles. Each bundle has a router command (e.g. `
 
 ## Quick Start
 
-1. `/fvs:map-code` - Analyze project, build dependency graph
-2. `/fvs:fc-plan` - Select verification targets
-3. `/fvs:lean-specify <function>` - Generate spec with sorry
-4. `/fvs:lean-verify <spec_path>` - Attempt proof interactively
-5. `/fvs:lean-refactor <spec_path>` - Golf and clean up verified proofs
-6. `/fvs:lean-formalise` - Formalise paper/math content into Lean specs
+**From a Rust crate — functional-correctness track:**
+1. `/fvs:aeneas-extract <path>` - Extract Rust → Lean 4 via the bounded Aeneas repair loop
+2. `/fvs:map-code` - Analyze project, build dependency graph
+3. `/fvs:fc-plan` - Select verification targets
+4. `/fvs:lean-specify <function>` - Generate spec with sorry
+5. `/fvs:lean-verify <spec_path>` - Attempt proof interactively
+6. `/fvs:lean-refactor <spec_path>` - Golf and clean up verified proofs
+7. `/fvs:trust-audit <target>` - Audit the sorry/axiom trust surface
+
+**From a paper — paper track:**
+- `/fvs:lean-formalise` - One-shot formalisation of paper/math content, or
+- `/fvs:crypto-plan <topic>` - Start the multi-iteration crypto loop (see Formalise below)
 
 ## Core Workflow
 
 ```
-/fvs:map-code → /fvs:fc-plan → /fvs:lean-specify → /fvs:lean-verify → /fvs:lean-refactor → repeat
-Paper track:    /fvs:lean-formalise → /fvs:lean-verify → /fvs:lean-refactor
+Code track:  /fvs:aeneas-extract → /fvs:map-code → /fvs:fc-plan → /fvs:lean-specify → /fvs:lean-verify → /fvs:lean-refactor → /fvs:trust-audit
+Paper track: /fvs:lean-formalise → /fvs:lean-verify → /fvs:lean-refactor
+Crypto loop: /fvs:crypto-plan → /fvs:crypto-execute → /fvs:crypto-eval → /fvs:crypto-followup → repeat
 ```
 
 ## Bundles
@@ -188,24 +195,28 @@ Refactor, simplify, and decompose verified Lean proofs while preserving compilat
 
 Usage: `/fvs:lean-refactor Specs/Backend/Field/Sub.lean`
 
-The crypto formalisation loop (plan -> execute -> eval -> follow-up) is a topic-based, multi-iteration alternative to the one-shot `lean-formalise`. Its four stages share the artifact tree under `fv-plans/<topic>/` and the loop is restartable from those records. The loop is runtime-neutral (it runs as a same-runtime pair by default).
+The crypto formalisation loop (plan -> execute -> eval -> follow-up) is a topic-based, multi-iteration alternative to the one-shot `lean-formalise`. Its four stages share the artifact tree under `fv-plans/<topic>/` and the loop is restartable from those records.
 
-**`/fvs:crypto-plan <topic>`**
+**Single- vs dual-runtime (`--codex`).** By default the loop is *single-runtime*: the high-effort thinking (planning, adversarial eval, follow-up) is done by the in-runtime `fvs-crypto-thinker`. The three *thinking* stages — `crypto-plan`, `crypto-eval`, `crypto-followup` — also accept `--codex`, which hands that stage's thinking to an independent **Codex CLI** thinker instead. That makes the loop *dual-runtime*: the adversarial planner/evaluator runs on a different engine than the executor, reducing correlated blind spots. `crypto-execute` is the runtime-neutral executor and takes no `--codex`. Pass `--codex` without the Codex CLI installed and the stage stops with an install hint (never a silent fallback) — re-run without it to stay single-runtime.
+
+**`/fvs:crypto-plan <topic> [nN] [--codex]`**
 Author the next bounded, runtime-neutral executor plan for a topic, grounded in the paper via the NotebookLM knowledge base (answers cached under `sources/`).
 
 Usage: `/fvs:crypto-plan "CKA from KEM"`
+Usage: `/fvs:crypto-plan "CKA from KEM" --codex`   # hand the planning think-step to Codex
 
 **`/fvs:crypto-execute <topic> nN`**
-Run the current iteration's bounded plan under the green-build guard; a failed proof triggers a short interactive redirect early.
+Run the current iteration's bounded plan under the green-build guard; a failed proof triggers a short interactive redirect early. (Executor stage — takes no `--codex`.)
 
 Usage: `/fvs:crypto-execute "CKA from KEM" n1`
 
-**`/fvs:crypto-eval <topic> nN`**
+**`/fvs:crypto-eval <topic> nN [--codex]`**
 Adversarially evaluate the iteration; ends in exactly one decision (ACCEPT / FOLLOWUP / HUMAN_RULING / BLOCKED).
 
 Usage: `/fvs:crypto-eval "CKA from KEM" n1`
+Usage: `/fvs:crypto-eval "CKA from KEM" n1 --codex`
 
-**`/fvs:crypto-followup <topic> nN`**
+**`/fvs:crypto-followup <topic> nN [--codex]`**
 Convert eval findings into the next bounded follow-up plan; HALTs for a human ruling on a modeling decision.
 
 Usage: `/fvs:crypto-followup "CKA from KEM" n1`

package/fv-skills/VERSION

@@ -1 +1 @@
-2.0.0
+2.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fv-skills-baif",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Formal verification skills for Claude Code, Codex, OpenCode, and Gemini. Rust -> Lean 4 via Aeneas.",
   "bin": {
     "fv-skills-baif": "bin/install.js"