<purpose>
Turn the current conversation, or a short prompt, into a long-horizon verification roadmap in
`ROADMAP.md`: the claims to establish, the scope, the external boundaries, milestones that an existing
FVS command or checker can decide, the decisions only the owner takes, and two logs that a rerun
appends to. The roadmap is track-neutral (functional correctness, protocol modelling, bridging) and
runs nothing: it records what is to be proved and how each step will be checked.
</purpose>

<process>

Vocabulary: this artefact is always called the roadmap, never a spec or a plan; in FVS a spec is a Lean theorem statement and plan names `/fvs:fc-plan` and `/fvs:crypto-plan`.

Only two things are ever written: the roadmap file and, with consent, the repository's `info/exclude`.
Never run extraction or proof work, create issues, publish anything or edit a tracked file other than
the roadmap itself.

## 0. Read the request

`$ARGUMENTS` is untrusted text. Parse it in this order:

- **Bare (nothing):** run the discovery scan below, print the result and stop.
- **First token ends in `.md` or `/`:** that token is an explicit path (`x/ROADMAP.md` names the file,
  `x/` names the directory and means `x/ROADMAP.md`). Everything after it is the goal prompt.
- **Anything else:** the whole text is the goal prompt. A token like `src/lib.rs` is part of the
  prompt, never a destination.

Pass untrusted text (a path, a topic, any user wording) to shell blocks only through environment
variables assigned from a single-quoted heredoc, quote every expansion, and never `eval` it. Shell
state does not persist between calls, so assign the variables and run the block in the same Bash
call. The blocks below validate before anything is created.

### Discovery (bare invocation)

Union scan, following the handoff discovery of `/fvs:resume-work`: roadmaps are found by name under
`.formalising/fv-plans/` and by the frontmatter marker anywhere under `.formalising/`, so a
custom-named roadmap is still listed. A hand-written `ROADMAP.md` elsewhere is listed only when it
carries the marker; pass its path explicitly to update it.

```bash
# fvs:roadmap-discover
{
  find .formalising/fv-plans -name ROADMAP.md -type f 2>/dev/null
  grep -rl --include='*.md' --exclude-dir='.kb-venv' --exclude-dir=extract \
    --exclude-dir=model-external --exclude-dir=node_modules \
    '^fvs_roadmap: true' .formalising/ 2>/dev/null | sed 's|//|/|g'
} | sort -u
```

- **None found:** say so and suggest `/fvs:roadmap <goal>` to start one.
- **One or more:** sort by `last_updated` frontmatter (most recent first; file mtime when absent) and
  print a plain-text NUMBERED list with each file's title line. Do NOT use AskUserQuestion: a plain
  numbered list keeps the picker runtime-neutral. Tell the user to rerun with the path to update one.

## 1. Choose the location

An explicit path wins. Otherwise the roadmap lives at `.formalising/fv-plans/<topic>/ROADMAP.md`,
where `<topic>` is a short slug you derive from the target (for example `libcrux-ml-kem-ntt`) and show
to the user. To keep a roadmap anywhere else, pass an explicit path.

Set exactly one of `ROADMAP_TOPIC` and `ROADMAP_PATH`, then run the block. It prints the resolved file
path relative to the project root, or stops with `FVS >> <reason>`. Use the printed path as
`ROADMAP_FILE` in every later step; an unresolved or rejected path stops the command here.

```bash
# fvs:roadmap-path
# Input (untrusted, environment only): exactly one of ROADMAP_TOPIC or ROADMAP_PATH.
# Output: the roadmap file path relative to the project root, one line.
LC_ALL=C
export LC_ALL
fail() { printf 'FVS >> %s\n' "$1" >&2; exit 2; }
if [ -n "${ROADMAP_TOPIC:-}" ] && [ -n "${ROADMAP_PATH:-}" ]; then
  fail "give a topic or a path, not both"
elif [ -n "${ROADMAP_TOPIC:-}" ]; then
  case $ROADMAP_TOPIC in
    *[!A-Za-z0-9._-]*|[!A-Za-z0-9]*)
      fail "topic must use letters, digits, '.', '_' and '-' and start with a letter or digit" ;;
  esac
  [ "${#ROADMAP_TOPIC}" -le 64 ] || fail "topic is longer than 64 characters"
  FILE=.formalising/fv-plans/$ROADMAP_TOPIC/ROADMAP.md
elif [ -n "${ROADMAP_PATH:-}" ]; then
  case $ROADMAP_PATH in
    *[!A-Za-z0-9._/-]*) fail "path may contain only letters, digits, '.', '_', '-' and '/'" ;;
    /*|-*|*//*) fail "path must be relative to the project root, must not start with '-' and must not contain '//'" ;;
  esac
  case /$ROADMAP_PATH/ in */../*) fail "path must not contain '..'" ;; esac
  case $ROADMAP_PATH in
    *.md) FILE=$ROADMAP_PATH ;;
    */) FILE=${ROADMAP_PATH}ROADMAP.md ;;
    *) fail "path must end in .md (a roadmap file) or / (a directory)" ;;
  esac
else
  fail "no topic or path given"
fi
if [ -L "$FILE" ]; then fail "refusing to write through a symlinked roadmap file"; fi
if [ -e "$FILE" ]; then
  case ${FILE##*/} in
    ROADMAP.md) ;;
    *) grep -q '^fvs_roadmap: true' -- "$FILE" 2>/dev/null ||
         fail "$FILE exists and is not a roadmap (no fvs_roadmap marker): pass a new path" ;;
  esac
fi
printf '%s\n' "$FILE"
```

## 2. Check git exclusion before writing anything

Roadmaps hold planning and trust decisions, so the default is local storage that git does not see.
Run the check with `ROADMAP_FILE` set. It reports `excluded`, `visible` or `not-git`; when a parent
directory such as `.formalising` is a symlink, git cannot look beyond it, so the block checks the
symlink itself.

```bash
# fvs:roadmap-exclusion
# Input (environment only): ROADMAP_FILE, the relative path printed by the path block.
# Output: excluded | visible | not-git
git rev-parse --is-inside-work-tree >/dev/null 2>&1 || { echo not-git; exit 0; }
CHECK=$ROADMAP_FILE
REST=$ROADMAP_FILE
PREFIX=
while [ -n "$REST" ]; do
  PART=${REST%%/*}
  case $REST in */*) REST=${REST#*/} ;; *) REST= ;; esac
  PREFIX=${PREFIX:+$PREFIX/}$PART
  if [ -L "$PREFIX" ]; then CHECK=$PREFIX; break; fi
done
git check-ignore -q -- "$CHECK"
case $? in
  0) echo excluded ;;
  1) echo visible ;;
  *) echo "FVS >> git check-ignore failed for $CHECK" >&2; exit 1 ;;
esac
```

- **`excluded`:** continue.
- **`not-git`:** say that no git exclusion applies here, and continue.
- **`visible`:** ask (AskUserQuestion; on Codex or Pi a plain-text question, then wait):
  - When the path is under `.formalising/`: **Add the exclusion** (append `.formalising/` and
    `/.formalising` to the repository's `info/exclude`; that file is local, never tracked and shared by
    every worktree of the repository; the second pattern is the one that matches a symlinked
    `.formalising`), **Write here anyway** (the roadmap stays visible to git; nothing is staged or
    committed), or **Cancel**. Show the two exact lines and the resolved `info/exclude` path before
    appending.
  - Any other path: the two patterns would not cover it, so offer **Write here anyway**, **Choose
    another path** or **Cancel**.

Appending is idempotent, keeps every existing line and edits no other file. Never edit a tracked
ignore file (`.gitignore` or any other) and never change a global ignore setting.

```bash
# fvs:roadmap-exclude-append
EXCLUDE_FILE=$(git rev-parse --git-path info/exclude) || exit 1
mkdir -p -- "$(dirname -- "$EXCLUDE_FILE")" || exit 1
[ -e "$EXCLUDE_FILE" ] || : > "$EXCLUDE_FILE" || exit 1
if [ -s "$EXCLUDE_FILE" ] && [ -n "$(tail -c 1 -- "$EXCLUDE_FILE")" ]; then
  printf '\n' >> "$EXCLUDE_FILE"
fi
for PATTERN in '.formalising/' '/.formalising'; do
  grep -Fxq -- "$PATTERN" "$EXCLUDE_FILE" || printf '%s\n' "$PATTERN" >> "$EXCLUDE_FILE"
done
echo "info/exclude: $EXCLUDE_FILE"
```

After an append, rerun the exclusion block. If it still does not report `excluded`, say so and treat
the path as the "any other path" case.

A noninteractive run never prompts and never infers consent: it writes only when the block reports
`excluded` or `not-git`, and otherwise stops with the two patterns and the `info/exclude` path as the
remediation.

Git exclusion is a local-storage default, not encryption or permission to publish. Say so in the final
report.

## 3. Rerun on an existing roadmap

If `ROADMAP_FILE` already exists, it is a roadmap only when it is named ROADMAP.md or carrying the
marker; the path block refuses any other existing file, so a stray first word of a prompt can never
turn a README into a roadmap. Read it fully before doing anything else. Apply steps 4 and 5 to
reconcile the request with its effective intent and approval, then use the rerun rules instead of
rewriting it from the step 6 template. A routine log update does not restart the interview.

## 4. Synthesize and check the applicable agreement

Synthesize every template field from what is already known, before asking anything: the conversation
and the goal prompt, files they name, and the facts that fix the target revision (`git rev-parse
HEAD`, `Cargo.toml` and `Cargo.lock`, `lean-toolchain`, the lakefile). Mark each field known, with the
evidence, or unknown. Investigate factual gaps from the available sources instead of asking the owner
to look them up. Never invent an answer, owner preference or approval.

Probe-derived facts (function counts, the dependency graph, progress) come from
`.formalising/CODEMAP.md` when it exists. The roadmap points to that file and never restates those
numbers: they are regenerated by `/fvs:map-code`, and a copy would go stale.

Read any existing owner-approved agreement and the actual owner response it references, not just an
agent's approval header. An agreement may be in this conversation or in the existing roadmap's
sections and Decisions log. Check its repository, target revision/configuration, goal/non-goals,
claims, trust boundaries/assumptions, acceptance evidence/authority and relevant limits against the
current request and sources. Record the owner response reference and the exact approved content or
its version/hash plus section/decision references; a timestamp alone does not bind approval.
Read the original sections together with non-superseded owner decisions to establish effective intent.

Reuse a current applicable owner-approved agreement without interviewing or confirming the same
intent again. Routine progress within that intent and its delegated scope is not a reason to ask
again, although changed sources may make earlier verification evidence stale. A changed target,
claims, trust policy or scope requires reconsideration of the affected decision; do not silently
carry approval over to a different revision/configuration outside the approved bounds. Preserve
settled decisions that remain applicable. Absent, stale or conflicting approval is not approval;
identify the exact missing or disputed decision rather than asking the owner to restart everything.

Semantic intent, file-edit approval and execution/publication authority are separate. A previously
explicit grant remains valid within its actual scope; cite it rather than requesting it again.
Roadmap agreement itself grants none. Record only relevant references to actual delegated actions
and limits (for example claim/status updates, branch work, push destination, PR or merge) under
Owner-reserved decisions; an unspecified action stays ungranted. Do not invent a policy engine or
infer a grant from credentials, a preselected choice, a skipped/bypassed prompt or a passing test.
This command records intent and never performs those actions. Publication cannot be assumed safe
because a PR can later be corrected: correction cannot reliably undo disclosure or restore stale
evidence. Existing publication consent and downstream approval contracts still apply.

## 5. Clarify and confirm shared intent

### Choose light, deep or reuse without ritual prompts

Default to light clarification when the context is clear. Reuse the applicable approval from step 4
when settled; no fresh interview or intent confirmation is needed. Honor an explicit depth preference
or a clear choice already in the conversation without asking a depth-selection question again.
Otherwise recommend deep clarification when goals, claims, trust policy or external/bridging
boundaries are materially uncertain or disputed. Explain the specific uncertainty, not a generic
menu. Only ask a depth question when the preference actually matters and remains unresolved.

For light clarification, ask at most seven questions in one initial round, only for unknown material
fields. Seven is a ceiling, never a quota; ask fewer or proceed without interviewing when the
conversation supplies the answers. The topics for either depth are:

1. target and exact revision, with configuration and features;
2. scope and exclusions, with non-goals and relevant conventions;
3. claims to establish;
4. external or model boundaries;
5. trust and axiom policy;
6. budget and limits, when they matter;
7. review route, with acceptance evidence and who has authority.

Group related topics: configuration with revision, adversary model with security claims, both
endpoints with bridging boundaries, and acceptance authority with review route. Offer a recommendation
when evidence supports one; label proposed assumptions as proposals, not accepted facts.

Deep clarification uses dependency-aware rounds: ask only owner decisions whose prerequisites are
settled, then read the answers and recompute the unresolved frontier. A question depending on an
unanswered decision waits for a later round. Investigate facts yourself first; never roleplay the
owner to answer. Keep each round focused on the material uncertainty and within the existing budget;
if the owner leaves a decision open, or the budget/no-progress boundary is reached, retain it as an
UNKNOWN and stop that line of questioning instead of retrying indefinitely. The same unresolved
decision recurring without new evidence is no progress: pause it, not another round. No whole-project
reset.

Ask each round together (AskUserQuestion; on Codex or Pi a plain-text question, then wait).
AskUserQuestion accepts up to four questions per call; split a larger round into consecutive calls,
or one numbered plain-text list on Codex/Pi. The light cap covers the initial interview only:
focused disagreement, later essential clarification and required consents have their own purpose.

### Confirm understanding, not just a file diff

For new or materially changed interactive intent, show a concise proposed shared understanding of
goal, non-goals, claims, assumptions/trust boundaries and acceptance evidence/authority, including
unresolved UNKNOWNs and relevant limits. Ask the owner to confirm that understanding explicitly,
correct a specific point, leave a named decision unresolved, or cancel. Wait for the actual owner
response before recording intent as agreed. A prior response that explicitly approved this exact
current understanding suffices; do not ask again merely because it was not a dedicated menu.
Confirmation of the bounded understanding can include explicit UNKNOWNs; it does not settle them.

Disagreement triggers targeted deeper clarification of the rejected point and its dependent
questions only; keep settled answers and show the revised affected understanding for confirmation.
Do not restart the full interview or silently reinterpret a rejection as approval. Cancellation
leaves the existing roadmap unchanged. File/diff approval alone does not confirm intent, and intent
confirmation alone does not approve a file write or execution/publication. One response may explicitly
cover multiple decisions, but never infer the others from an unlabeled yes to a different question.

### Autonomous reuse and unresolved owner choices

An autonomous invocation reads and reuses only a current applicable evidence-backed owner-approved
agreement and its existing delegated scope. No fresh user interview when settled, and no simulated
owner response. Investigate factual gaps within the existing grant. For missing, stale or conflicting
approval, block only the affected milestones with the precise owner decision needed; do not resolve
it by model consensus or a fabricated preference. Independent work already authorized may continue
through the existing executor/orchestrator; this roadmap command merely reports that work, not runs it.
If authorized to write the roadmap, record unresolved owner choices without marking new or changed
intent agreed; otherwise return the proposed blocked update without writing it. Do not replace a
previously agreed field with a guess. Research/decision work may be proposed, but creating an issue
or publishing it requires its own applicable grant and consent; this command creates no issues.

An adversarial model, if already part of the authorized review route, critiques the approved intent
against sources and acceptance evidence. It may suggest clearly labelled assumptions, never approve
them for the owner, supply owner preferences, change claims/trust/scope or extend delegated authority.
No additional reviewer launch or user-installed questioning skill is required by this workflow.

Record every answer still missing as `UNKNOWN (U<n>): <what is needed and who can supply it>` in the
field that needed it; mark dependent milestones `blocked (needs U<n>)`. An investigated factual UNKNOWN
may be resolved from cited evidence within authorized writes; an owner-choice UNKNOWN needs the
owner's actual answer. Unknowns never become approved claims just because a document was saved.

## 6. Write the roadmap

Fill the template below. Budgets and limits are recorded when relevant, not required as numbers in
every roadmap. Contents the sections always carry:

- **Goal:** the exact target revision with configuration and features, and the kind of work.
- **Claims to establish:** each claim in words, labelled unconditional or conditional on named
  assumptions. A protocol claim states the security experiment or adversary model and the intended
  quantitative conclusion. A bridging claim states both endpoints and the correspondence relation.
  A functional-correctness claim says what the theorem statement is meant to mean, not its proof.
- **Assumptions and external boundaries:** the trust and axiom policy, then one row per boundary with
  the correspondence obligation that would have to be shown for it to stop being an assumption.
- **Milestones:** each with a "done when" that an existing FVS command or checker decides, the
  evidence it produces, and who has authority to accept it. Examples: `/fvs:aeneas-extract` for
  extraction (extraction success is not proof), `/fvs:lean-spec-review` for a reviewed theorem
  statement, `/fvs:lean-verify` for VERIFIED after the build and cheat audit, `/fvs:trust-audit` for
  CLEAN axioms, `/fvs:model-external` for COMPLETE, `/fvs:crypto-eval` for ACCEPT, a named build
  target. When no command decides it, name the human reviewer and the evidence they inspect and label
  the milestone human-judged. A command's successful exit never establishes that a theorem statement
  is the right one; that is decided by statement review.

Persist only the agreement and preference references needed for this topic, using the existing
sections and append-only logs. Keep the approved content/version and target/source linkage with the
owner response reference in the Decisions log; a Status log entry records current applicability and
remaining UNKNOWNs. Store a depth preference only if the owner explicitly expressed one, not because
the model chose light or deep. No separate config, agreement file, mandatory glossary or ADR layer.

The roadmap frontmatter may carry an `issues:` block (a per-roadmap tracker override owned by the
issues-setup command); write one only when the user asks, and keep an existing block byte for byte on
every rerun. A project default whose `provider: null` means unconfigured, and a roadmap's `issues:`
block replaces the project default as a whole, with no field-wise merge.

```markdown
---
fvs_roadmap: true
topic: <short name>
last_updated: <UTC date, YYYY-MM-DD>
---

# <Title>: verification roadmap

## Goal

<One paragraph: what is to be established, and why.>

- Kind of work: <functional correctness | protocol security | bridging | mixed>
- Target: <name>, exact revision <commit or tag>, configuration and features <...>

## Claims to establish

| ID | Claim | Status label |
|---|---|---|
| C1 | <claim in words> | <unconditional | conditional on A1> |

## Scope, exclusions and non-goals

- In scope: <...>
- Out of scope and non-goals: <...>
- Limits (budget, time, spending), when relevant: <...>
- Function inventory, dependency graph and progress: see `.formalising/CODEMAP.md`; this roadmap never restates them.
- Honest scope: this roadmap makes no whole-library correctness or security claim beyond the stated scope. Extraction success is not proof. Conditional results stay labelled conditional.

## Assumptions and external boundaries

Trust and axiom policy: <...>

| ID | Boundary or assumption | Kind | Claimed behaviour | Correspondence obligation | Status |
|---|---|---|---|---|---|
| A1 | <...> | <opaque | external | handwritten model> | <...> | <what must be shown> | <open | accepted as an assumption | proved> |

## Milestones

### M1: <outcome>

- Depends on: <none | M-ids>
- Done when: <check by an existing FVS command or checker>; evidence <...>; accepted by <...>
- Status: <open | blocked (needs U1) | done>

## Owner-reserved decisions

- <decision only the owner takes>
- Roadmap approval grants no execution, spending or publication authority; concrete runs need their own approval, which may already exist as an explicit applicable grant.
- Shared understanding: <owner response reference; approved content/version and target/source references, or unconfirmed with UNKNOWNs>.
- Relevant delegated scope and limits: <actual owner grant reference, or none; never inferred from roadmap approval>.
- Clarification preference: <only if explicitly stated by the owner; reference>.

## Decisions log

| ID | Date | Decision | Reason | Supersedes |
|---|---|---|---|---|
| D1 | <date> | <decision> | <reason> | - |

## Status log

| Date | Entry |
|---|---|
| <date> | roadmap created |
```

Create the parent directory only now, after step 2 has passed, with the validated path quoted:
`mkdir -p -- "$(dirname -- "$ROADMAP_FILE")"`. Write the file with the Write tool so the runtime's
diff approval applies where required. Where file-write authority for this exact scope already
exists, reuse it. On a runtime without diff approval, ask once after showing the full draft only if
no applicable write grant exists. Neither this edit approval nor runtime prompt bypass supplies semantic agreement;
apply step 5's intent gate separately. The path/exclusion consents from steps 1–2 still apply.

## 7. Report

```
FVS >> ROADMAP WRITTEN

Roadmap: <ROADMAP_FILE>
Git:     <excluded | visible (written with your consent) | not a git work tree>
Milestones: <n> (<k> blocked on unknowns: U1, ...)
Agreement: <confirmed | reused | unconfirmed/stale/conflicting; owner/content references>

Roadmap approval grants no execution, spending or publication authority.
Git exclusion is a local-storage default, not encryption or permission to publish.
```

Then name the first unblocked milestone and the command that decides its "done when".

## Rerun rules

Read the existing roadmap fully first and apply steps 4–5 to effective intent. Routine status updates
reuse a current agreement, not a new interview. Material changes need only affected reconsideration
and, interactively, explicit intent confirmation. With absent/stale/conflicting autonomous approval,
record the gap/blocked work only within an actual write grant; otherwise stop with a proposed update.
Append new UNKNOWNs and affected milestone references to the Status log instead of replacing old
agreed fields or rewriting milestone history. Their affected work stays blocked pending the named
owner decision; unchanged independent authorized work remains available.
Every rerun that writes appends exactly one dated Status log row, even when no decision changed;
a cancelled or unauthorized rerun writes nothing. A rerun may only:

- append rows to the Decisions log and the Status log;
- replace a factual `UNKNOWN` with cited investigated evidence, or an owner-choice `UNKNOWN` with
  the owner's actual answer, unblocking only milestones whose prerequisites are settled and recording
  both in the logs;
- append claims, boundaries or milestones the user asks for;
- refresh `last_updated`.

Record relevant new approval/depth-preference references in appended Decisions log rows; do not
backfill or rewrite historical approvals, frontmatter or old prose to match them. The original
sections plus non-superseded decisions define the current approved understanding. A changed target,
claim, trust boundary or scope keeps affected evidence stale until reviewed for the new context;
independent authorized work is not automatically revoked. A routine source/progress refresh never
creates proof acceptance or new execution/publication authority.

Everything else is untouched text and stays byte for byte as it was, so apply each change with Edit
and never rewrite the whole file with Write. The command never silently rewrites a decision. A decision
changes only when the user names the replacement explicitly: append a new decision row whose
Supersedes column names the old ID and keep the old row verbatim. A roadmap with no frontmatter keeps
its text untouched; offer to add the marker as a separate, previewed edit. Report with
`FVS >> ROADMAP UPDATED`, listing every appended row.

</process>
