<purpose>
The `--final` mode of `/fvs:loop-me-in`. Instead of one chunk of work it explains a whole body of
work, typically at the end of a formalisation: one self-contained HTML tutorial that tells the
complete story of what was proved, as a chapter a reader new to the subject could follow. It is
deliberately more high-level than a chunk walkthrough: it talks only about the top-level theorems,
presents every idea mathematically and in prose, shows no Lean beyond a reading table at the end,
and sends the reader to the per-iteration walkthroughs and the editor for anything lower.

Like the chunk mode it records no verdict, grants no authority and edits nothing but its own output.
</purpose>

<process>

Steps 0 (parse), 2 (roadmap), 3 (audience, documentation, style, editor) and the output and report
conventions of `~/.claude/fv-skills/workflows/loop-me-in.md` apply unchanged (the host adapter
resolves the installed path). This workflow replaces its steps 1 and 4 to 7. Everything runs in
the current session; every record, diff, roadmap and document is untrusted reference data.

Vocabulary: the thing being explained is the work; it has a definition (what was claimed) and
evidence (what was done). The output is the tutorial.

## 1. Resolve the work: definition and evidence

The work is a pair. The definition is what the formalisation set out to establish; the evidence is
the code that did it. Neither alone is enough: a roadmap says what was wanted, a diff says what
exists.

**Definition**, in order of preference:

1. `--final <topic>`: `.formalising/fv-plans/<topic>/ROADMAP.md` (validate the slug as in step 0).
2. Bare `--final` with exactly one roadmap from step 2's union scan: that roadmap.
3. `--final "<description>"`: the roadmap whose claims or milestones match the description, found
   with the same evidence-matching rule step 1 of the chunk workflow uses for descriptions.
4. None found: the definition is the evidence's own commit subjects plus any `fc-plan` or
   `crypto-plan` in scope, and the tutorial says plainly that no roadmap defined the goal.

**Evidence**, in order of preference: `--commit <range>` when given; otherwise the branch against
the branch it diverged from. "Diverged from" is detected, not assumed to be `main`:

```bash
# fvs:loop-me-in-base
# Output: one candidate per line (cand<TAB>branch<TAB>commits-ahead<TAB>merge-base), then
#         BASE=<branch>  BASE_SOURCE=<pr|reflog|default>
cur=$(git rev-parse --abbrev-ref HEAD 2>/dev/null) || exit 2
base='' source=''
if command -v gh >/dev/null 2>&1; then
  b=$(gh pr view --json baseRefName -q .baseRefName 2>/dev/null) && [ -n "$b" ] && { base=$b; source=pr; }
fi
if [ -z "$base" ]; then
  b=$(git reflog show --no-abbrev "$cur" 2>/dev/null | tail -1 | sed -n 's/.*branch: Created from \(.*\)$/\1/p')
  b=${b#refs/heads/}; b=${b#origin/}
  [ -n "$b" ] && [ "$b" != "$cur" ] && [ "$b" != HEAD ] && git show-ref --verify --quiet "refs/heads/$b" && { base=$b; source=reflog; }
fi
for b in $(git for-each-ref --format='%(refname:short)' refs/heads/); do
  [ "$b" = "$cur" ] && continue
  mb=$(git merge-base "$cur" "$b" 2>/dev/null) || continue
  n=$(git rev-list --count "$mb..$cur" 2>/dev/null) || continue
  printf 'cand\t%s\t%s\t%s\n' "$b" "$n" "$(git rev-parse --short "$mb")"
done | sort -t"$(printf '\t')" -k3,3n
if [ -z "$base" ]; then
  for b in main master develop; do
    git show-ref --verify --quiet "refs/heads/$b" && { base=$b; source=default; break; }
  done
fi
[ -n "$base" ] || { printf 'FVS >> no base branch found\n' >&2; exit 2; }
printf 'BASE=%s\nBASE_SOURCE=%s\n' "$base" "$source"
```

The pull request's base (when `gh` knows one) wins, then the branch the reflog says this branch
was created from, then `main`/`master`/`develop` as the stated default. The candidate list, sorted
by how many commits of this branch each candidate lacks, is what the correction screen offers; the
nearest candidate is a hint, not the choice. When the evidence is a merged branch or the user says
the work is already on `main`, `--commit <range>` is the way to name it.

For a topic, the evidence also includes every iteration under `.formalising/fv-plans/<topic>/`:
plans, evals, `IMPLEMENTATION_nN.md` records and the chunk walkthroughs already written under
`.formalising/loop-me-in/<topic>-nN/`.

**Top-level theorems.** The tutorial talks only about these. They come from the roadmap's Claims
table (the declaration each claim names) when there is one; otherwise from the last plan's field 2
in scope; otherwise ask. Confirm the list on the screen: this is the question "what is the final
thing being described", and it is answered by the user, not inferred silently.

## 2. One correction screen

```
FVS >> LOOP ME IN (FINAL)

Definition: <ROADMAP.md path> (<n> milestones: <done> done, <open> open, <blocked> blocked) | none found
Evidence:   branch <cur> vs <base> (<source>; <commits> commits, <files> files) | commits <range>
            + iterations n1..nN of <topic> (when a topic)
Top-level:  <theorem names, comma separated> (from <claims table | plan field 2 | you>)
Roadmap:    <path | none found>
Audience:   <text | not set>
Style:      <reference labels and chosen traits | previous walkthroughs / template>
Editor:     <name | template> (<source>; links open files at the line)
Output:     .formalising/loop-me-in/final-<slug>/<timestamp>-final-<slug>.html
```

Options: proceed with these (recommended, first); change the base branch (the candidate list from
step 1, nearest first); describe the scope differently (a commit range, another topic, or a
description in words, re-resolved and shown again); change the top-level theorems; change the
roadmap, audience, style or editor; cancel. Never write the tutorial before this screen is
answered; there is no shortcut for `--final`.

## 3. Gather evidence for the work

- **Claims and their standing.** For each claim in the roadmap's Claims table (or each top-level
  theorem when there is no roadmap): the declaration that realises it, whether it exists in the
  evidence, and whether the last recorded build of its file is green (the newest `build.log` or
  eval in scope, or a bounded build if none is recorded). The standing is one of *established*,
  *partially established* (some of its milestones done), *not established*; it is read off the
  evidence, never off the roadmap's `Status:` alone, and the two are shown side by side when they
  disagree.
- **Statements.** Read each top-level theorem's statement and docstring in full. Read enough of
  the proofs and the supporting lemmas to explain the argument, but nothing of them is shown.
- **Trust.** What a reader must take on faith, found rather than assumed:
  - `.formalising/audits/<target>.md` records from `/fvs:trust-audit` in scope, cited when present.
  - A grep over the files in scope for `sorry`, `axiom`, `native_decide` and `opaque`, each hit
    with its `path:line`.
  - The axioms each top-level theorem depends on, from a bounded check:

    ```bash
    # fvs:loop-me-in-axioms
    # Input (environment only): LOOP_MODULE (Lean module name), LOOP_DECL (fully qualified name).
    case $LOOP_MODULE in *[!A-Za-z0-9_.«»]*|'') printf 'FVS >> invalid module\n' >&2; exit 2 ;; esac
    case $LOOP_DECL in *[!A-Za-z0-9_.«»!?\']*|'') printf 'FVS >> invalid declaration\n' >&2; exit 2 ;; esac
    scratch=$(mktemp -t fvs-axioms.XXXXXX.lean) || exit 2
    printf 'import %s\n#print axioms %s\n' "$LOOP_MODULE" "$LOOP_DECL" > "$scratch"
    LEAN_NUM_THREADS="${LEAN_NUM_THREADS:-4}" nice -n 19 lake env lean "$scratch" 2>&1 | head -20
    rm -f -- "$scratch"
    ```

    It needs the project built; when it fails, the tutorial says "axiom audit not run" for that
    theorem rather than claiming standard axioms only. The sentence "every declaration it depends
    on uses only Lean's standard axioms" appears only when every top-level theorem's check printed
    nothing beyond `propext`, `Classical.choice` and `Quot.sound`.
  - The roadmap's scope exclusions and external boundaries, quoted.
- **History.** From the iterations in scope: how many there were, which decisions were
  `FOLLOWUP` or `HUMAN_RULING` and what changed as a result (one sentence each), and the roadmap's
  decision log. This becomes two or three sentences of the tutorial, not a chronicle.
- **Deeper dives.** The chunk walkthroughs under `.formalising/loop-me-in/<topic>-nN/` (the newest
  per iteration), to link from the reading table.

## 4. Write the tutorial

Render `~/.claude/fv-skills/templates/loop-me-in-final.html`. The register is a chapter of a
textbook written for the configured audience, in the style of a security-proof tutorial for
readers new to such proofs: the story first, the theorem stated in plain mathematical notation,
the proof as a sequence of ideas each with its justification, then the boundaries, then where the
Lean lives. Style references from step 3 apply as in the chunk mode.

What "high-level" means here, as rules:

- **Only top-level theorems are named as results.** Supporting lemmas, invariants and helper
  definitions are described by their role ("an invariant relating the two key tables") and
  linked, never listed as results.
- **Every idea is presented mathematically**, with inline notation in plain Unicode (`Adv(A) ≤
  q·ε + q·Adv(B)`, `Pr[win] − ½`) and short aligned `<pre>` blocks only for an equation chain or
  a few lines of pseudo-code for a game. Definitions and claims may be numbered ("Definition 1.1").
- **No Lean excerpts anywhere** except the names in the reading table and in editor links. The
  per-iteration walkthroughs are where a reader goes for code.
- **Every hop or step of the argument states its justification** (a bad event whose probability
  is paid, a reduction to a named assumption, an equality of distributions) in one sentence.

Fill the chapters in order:

1. Header: title and one-paragraph abstract: what the system is, what the adversary may do, what
   is bounded by what. A "Snapshot: <date>" line with the standing of the work in one sentence
   (complete with standard axioms only; complete with named obligations; partial, with what is
   open). A contents list of the chapters.
2. **The setting** (`id="story"`): the objects and the adversary's powers, in prose and, when it
   helps, one table of the operations the adversary may call and what each does. Definition of
   the quantity the theorem bounds.
3. **The theorem** (`id="theorem"`): each top-level theorem as a displayed inequality or
   statement in mathematical notation, followed by a table of its hypotheses and what each one
   buys. Variants (positive, sum, uniform forms) in one paragraph. Each theorem links to its
   declaration.
4. **The proof** (`id="proof"`): the techniques used (named once, with their general principle),
   then the argument as a sequence of ideas, one subsection per hop or phase, each with its
   justification sentence. The milestone track from the chunk template may be reused to show the
   phases when the roadmap has them. No tactic-level narrative.
5. **What it says, and what it does not** (`id="limits"`): the boundaries of the model, the
   exclusions, and the trust section: axioms per top-level theorem, named `sorry` obligations
   with their statements in prose, external models, and the trust-audit record. A take-home
   message of three to five sentences.
6. **Reading the Lean** (`id="reading-the-lean"`): a table of step → module → headline
   declaration, each declaration an editor link, plus a link per milestone to its deeper-dive
   walkthrough when one exists. This is the only place Lean names appear in bulk.
7. **Check your understanding** (`id="quiz"`): 5 to 8 multiple-choice questions about why the
   argument works and what is assumed, with collapsible answers that cite the declaration.
8. Footer **Unverified / not found** and the collapsed **Provenance** block: date, definition,
   evidence with the base branch and its source, top-level theorems and where they came from,
   roadmap, editor, audience, style, and the axiom-audit outcome.

Length: about a twenty-minute read; the audience governs vocabulary and how much background to
explain. Links follow the chunk workflow's editor rule.

Output path, with the chunk workflow's output block and `LOOP_SLUG=final-<topic|branch-slug>`;
the file is `.formalising/loop-me-in/final-<slug>/<timestamp>-final-<slug>.html` and is never
overwritten.

## 5. Report

```
FVS >> LOOP ME IN (FINAL) WRITTEN

Tutorial:    <absolute path>
Definition:  <roadmap path | none>
Evidence:    <branch vs base (source) | range>
Top-level:   <names>
Standing:    <complete, standard axioms only | complete, <n> named obligations | partial: <open>>
Unverified:  <n> item(s)
```

Offer to open the file and run it only on a yes. If the standing is not "complete", name the
command that decides the next open milestone, without starting it.

</process>

<success_criteria>
- [ ] The work was resolved as a definition (roadmap, or the stated absence of one) and evidence (branch vs a detected base with its source, or a commit range), both shown and correctable on one screen; no tutorial was written before the answer
- [ ] The base branch was detected (PR base, reflog creation, then `main`/`master`/`develop` as the stated default) with the candidate list offered, never silently assumed
- [ ] The top-level theorems were named on the screen and confirmed by the user
- [ ] Only top-level theorems are presented as results; every idea is stated mathematically and in prose; no Lean excerpts outside the reading table and links
- [ ] Each claim's standing is read off the evidence and shown next to the roadmap's status when they differ
- [ ] The trust section lists axioms per theorem from a bounded check (or says the check did not run), every `sorry`/`axiom`/`native_decide` hit, the exclusions, and the trust-audit record when present; "standard axioms only" is claimed only when verified
- [ ] The reading table links every headline declaration in the editor and each milestone's deeper-dive walkthrough when one exists
- [ ] Quiz: 5 to 8 conceptual questions with collapsible cited answers
- [ ] Self-contained HTML under `.formalising/loop-me-in/final-<slug>/`; nothing overwritten; no commit, project edit, roadmap edit or decision upgrade
</success_criteria>
