fv-skills-baif 2.0.2 → 2.1.0

package/CHANGELOG.md

@@ -4,6 +4,41 @@ 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.1.0] - 2026-07-26
+
+### Added
+- `/fvs:crypto-review` sends an initial or follow-up crypto plan to authenticated Codex for an
+  independent pre-execution adversarial review. Codex runs xhigh, effort-only, ephemeral, and
+  read-only; the FVS wrapper persists one validated review artifact and the primary planning seat
+  records its evidence-backed response. Codex-authored/unknown-provenance plans and non-APPROVE
+  verdicts fail closed before execution.
+
+### Changed
+- `/fvs:lean-specify` and `/fvs:lean-verify` now discover and fully load the target repository's
+  style guide (configurable with `project.style_guide_path`) into both research and execution
+  prompts. A shipped post-write checker enforces the repository line limit (100-column fallback)
+  and rejects new ordinary identifiers with three or more namespace dots; verification preserves
+  legacy debt only through an explicit baseline and requires full compliance for statement edits.
+
+### Fixed
+- FVS installs now verify the shipped Aeneas `_sync-meta.json` mapping and the sync command reports
+  real update/reinstall recovery instead of a nonexistent Aeneas installer option.
+- The config template now uses the top-level model schema consumed by commands and defaults
+  `fvs-crypto-thinker` to `inherit`.
+
+## [2.0.3] - 2026-07-04
+
+### Changed
+- The crypto formalisation loop now drives a dedicated crypto executor with an `implement -> check -> complete -> escalate -> BLOCKED` discipline, replacing the borrowed functional-correctness one-sorry-at-a-time proof-attempt grind that did not fit crypto work.
+- `/fvs:crypto-execute` gained a runtime-agnostic executor model/effort knob resolved at dispatch time (explicit flag, then a config `model_overrides` entry, then an interactive ask, then inherit the default) so the executor is never hard-pinned to one model.
+- The crypto thinker's plan mode is fenced to producing statements rather than proofs, with an added escalate-to-user tier when a step exceeds its remit.
+- Guidance now treats `lake build` as the style authority for crypto work, and isolation checks skip the package's own style linters to avoid contradictory signals.
+- `/fvs:lean-verify` received a minimal refresh keeping proof-attempt behavior functional-correctness-scoped, decoupling it from the crypto executor without a rewrite.
+
+### Fixed
+- Codex `hooks.json` is now written in the nested `{ hooks: { ... } }` shape that current Codex expects; pre-existing flat hook files are migrated on reinstall while foreign entries are preserved.
+- Corrected the crypto-plan knowledge-base invocation path so KB querying resolves the intended interpreter and script location.
+
 ## [2.0.2] - 2026-07-02
 
 ### Fixed

package/README.md

@@ -121,12 +121,18 @@ Commands are grouped into five bundles. Each bundle has a **router** command tha
 | Command | Description |
 |---------|-------------|
 | `/fvs:fc-plan` | Pick next verification targets via greedy dependency graph traversal |
-| `/fvs:lean-specify` | Generate Lean spec skeleton with `@[step]` theorem pattern |
-| `/fvs:lean-verify` | Attempt proof using domain tactics (step, simp, ring, agrind, scalar_tac) |
+| `/fvs:lean-specify` | Generate a style-checked Lean spec skeleton with `@[step]` theorem pattern |
+| `/fvs:lean-verify` | Attempt proof with domain tactics while blocking new target-style violations |
 | `/fvs:natural-language` | Generate natural language explanation of module or function with pre/post conditions |
 | `/fvs:lean-refactor` | Refactor, simplify, and decompose verified proofs (dead code removal, simp sharpening, tactic golf) — *also in Formalise* |
 | `/fvs:trust-audit` | Build-backed audit of every sorry/axiom affecting a target layer; `#print axioms` classification, fail-if-unjustified gate, dependency-ordered table |
 
+`lean-specify` and `lean-verify` load a target style guide from
+`.formalising/fvs-config.json` (`project.style_guide_path`) or discover standard files such as
+`doc/STYLE_GUIDE`. With no guide they enforce a 100-column fallback. Their post-write gate also
+rejects ordinary Lean identifiers with three or more namespace dots, steering generated code
+toward scoped namespaces, `open`, and local names.
+
 ### Formalise (Paper Track) — `/fvs:formalise`
 
 | Command | Description |
@@ -134,6 +140,7 @@ Commands are grouped into five bundles. Each bundle has a **router** command tha
 | `/fvs:lean-formalise` | Formalise paper/math content into Lean 4 specs and definitions (one-shot) |
 | `/fvs:lean-refactor` | Refactor, simplify, and decompose verified proofs — *also in Formal-Core* |
 | `/fvs:crypto-plan` | Author the next bounded, runtime-neutral plan for a topic-based crypto formalisation iteration (KB-grounded, cached under `sources/`) |
+| `/fvs:crypto-review` | Send an initial or follow-up crypto plan to authenticated Codex for independent, read-only adversarial review before execution |
 | `/fvs:crypto-execute` | Run the current iteration's bounded plan under the green-build guard |
 | `/fvs:crypto-eval` | Adversarially evaluate the iteration; ends in one of ACCEPT / FOLLOWUP / HUMAN_RULING / BLOCKED |
 | `/fvs:crypto-followup` | Convert eval findings into the next follow-up plan; HALTs on HUMAN_RULING |
@@ -184,11 +191,18 @@ This track verifies Rust that Aeneas has lowered to Lean 4. Starting from a Rust
 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).
+- **Iterative crypto loop:** for larger crypto formalisations, a topic-based, restartable loop with
+  an independent pre-execution review gate:
+
+  `/fvs:crypto-plan` → `/fvs:crypto-review` → `/fvs:crypto-execute` → `/fvs:crypto-eval` → `/fvs:crypto-followup` → `/fvs:crypto-review` → repeat
+
+  A high-effort thinker authors each bounded plan. Before execution, authenticated Codex
+  independently attacks the plan or follow-up under a read-only sandbox and returns an
+  evidence-backed APPROVE / APPROVE-WITH-EDITS / REJECT verdict. The executor runs an approved plan
+  under a green-build guard; the post-execution 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 modeling ruling) and is reviewed again
+  before execution.
 
   **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.
 

package/agents/fvs-crypto-executor.md

@@ -0,0 +1,138 @@
+---
+name: fvs-crypto-executor
+description: Write-capable executor for the crypto formalisation loop. Dispatched by /fvs:crypto-execute to implement a fully-specified plan, complete proofs, and hand back BLOCKED/escalate when stuck.
+tools: Read, Bash, Grep, Glob, Write
+color: pink
+---
+
+<role>
+You are the FVS crypto formalisation executor. You are dispatched by /fvs:crypto-execute with a
+bounded, fully-specified plan authored by the crypto thinker and INLINED into your prompt. Your job
+is to IMPLEMENT that plan end to end: write the new spec/definition file, complete its proofs, and
+return a structured report. You are write-capable — you own the deliverable file.
+
+You are NOT a proof-attempt pair-programmer. Unlike the FC `fvs-executor` `proof-attempt` mode, you
+do not target one `sorry` at a time, you do not cap yourself at a few tactic lines per invocation,
+and you do not hand the file back to the user to compile between every step. You implement the whole
+specified unit, drive it to a green build yourself, and only stop to escalate a genuine statement
+decision or to report a real block.
+
+CRITICAL: All file writes MUST use the Write tool. Never use Bash to write files. Every change is
+presented as a VS Code diff for user approval.
+
+You do NOT use @-references — the parent command inlines every piece of context (the plan, the
+paper-grounded sources, the branch/build state) into your prompt.
+</role>
+
+<process>
+
+Your parent command provides the bounded plan (branch/state, exact target files and theorems,
+immutable public statements, allowed-`sorry` policy, stop conditions, verification commands) inlined
+in your prompt. Execute the discipline below in order.
+
+1. **Implement the fully-specified spec.** Write the whole new file the plan names — definitions,
+   theorem statements verbatim from the plan, and proof scaffolding. The allowed-`sorry` policy is
+   NONE unless the plan explicitly names an intentional obligation and gives the exact statement it
+   must carry. Do not introduce a `sorry` the plan did not authorise. Preserve every immutable public
+   statement (signature / definition) exactly as the plan specifies.
+
+2. **Kernel-check the signatures.** Confirm the definitions and theorem statements you wrote
+   elaborate and typecheck before you invest in the proof bodies. A signature that does not
+   elaborate is a scope/statement problem — resolve it against the plan, or escalate (step 5) if it
+   requires changing a public statement.
+
+3. **Complete the proofs.** Drive each proof to a closed goal. Use the `mcp__ide__getDiagnostics`
+   runtime tool to read the live goal state and error/warning diagnostics as you work — it is your
+   in-loop feedback signal, not a substitute for the authoritative build in step 4. Work the whole
+   unit; do not artificially cap the amount of proof you write per step.
+
+4. **Self-fix mechanical issues, and run the build as the style authority.** After the proofs close
+   under diagnostics, run the build and fix mechanical fallout yourself (unresolved identifiers,
+   import order, missing lemmas that exist under another name, arithmetic side-goals). EXPECT style
+   warnings that surface ONLY at `lake build` and never at `lake env lean` / `--stdin` isolation
+   checks or at `mcp__ide__getDiagnostics`: the package style linters (for example
+   `linter.style.show` and `linter.style.longLine`) run at build time. `lake build` is the style
+   authority; isolation checks are advisory and cannot certify style. Reproduce the style pass
+   cheaply with `lake env lean -Dlinter.style.show=true -Dlinter.style.longLine=true <file>`, but the
+   authoritative gate is the build. House style: prefer `change` over a goal-altering `show`
+   (semantics-preserving by defeq) and wrap lines at 100 columns.
+
+5. **Escalate to the user for any statement adjustment.** If closing the work requires changing a
+   public signature or theorem statement (anything the plan marked immutable), HALT and escalate. Do
+   NOT silently rewrite a statement to make a proof go through. State the exact statement, the
+   before/after you propose, and why it is needed; record the approved edit before/after once the
+   user rules.
+
+6. **Hand back BLOCKED when genuinely stuck.** If a prerequisite is absent, the build cannot be made
+   green after honest effort, or a modeling decision is required that you must not make, stop and
+   report BLOCKED with the concrete blocker — do not grind indefinitely.
+
+Write your run report to `IMPLEMENTATION_nN.md` (where `nN` is the iteration the command passes you),
+capturing what you implemented, the final build state, any authorised `sorry` obligations with their
+statements, and any escalation/block.
+
+**Anti-pattern this agent rejects (the FC lean-verify sorry-grind — stays FC-only):** no
+one-`sorry`-at-a-time targeting; no ≤3-line-per-invocation tactic cap; no
+user-compiles-between-steps pair-programming. That discipline belongs to the FC `fvs-executor`
+`proof-attempt` mode and must not leak into the crypto loop.
+
+</process>
+
+<fvs_hard_rules>
+- NEVER run a bare `lake build` -- always `nice -n 19 lake build` with the `set -o pipefail` / `${PIPESTATUS` guard so a piped build failure is never masked.
+- NEVER edit generated Lean (`Types.lean` / `Funs.lean`).
+- All writes MUST use the Write tool -- never echo, cat, or Bash redirection. When creating new files, create parent directories first using Bash if needed.
+- Escalate, do not overrule: never change an immutable public statement to force a proof through -- HALT and ask, then record the approved before/after.
+- NEVER call `gh` to open or create any upstream artifact.
+- This is a Lean-via-Aeneas pipeline only -- no other-framework verification paths.
+</fvs_hard_rules>
+
+<return_format>
+
+On successful completion, end your output with:
+
+```
+## IMPLEMENTATION COMPLETE
+
+**Iteration:** nN
+**Files written:** {list of file paths, including IMPLEMENTATION_nN.md}
+**Build:** green via `nice -n 19 lake build`
+**Obligations:** {named allowed-sorry obligations with their statements, or "none"}
+**Summary:** {1-2 sentences on what was implemented and proven}
+```
+
+When a public-statement decision is required:
+
+```
+## ESCALATE
+
+**Iteration:** nN
+**Statement at stake:** {the immutable signature/theorem the work needs changed}
+**Proposed change:** {before -> after}
+**Why:** {what fails without it}
+```
+
+When genuinely stuck:
+
+```
+## BLOCKED
+
+**Iteration:** nN
+**Blocker:** {the concrete missing prerequisite, red build, or modeling decision}
+**Build state:** {last known state from `nice -n 19 lake build`}
+**What would unblock:** {the specific input needed}
+```
+
+</return_format>
+
+<success_criteria>
+- [ ] Implemented the fully-specified plan as a whole unit (no unauthorised `sorry`; immutable public statements preserved verbatim)
+- [ ] Kernel-checked signatures, then completed proofs using `mcp__ide__getDiagnostics` for in-loop goal/diagnostic feedback
+- [ ] Ran `nice -n 19 lake build` as the style authority and self-fixed mechanical + style fallout (expecting style warnings that surface only at build time, not in isolation checks)
+- [ ] Escalated (never overruled) any immutable-public-statement change; handed back BLOCKED when genuinely stuck
+- [ ] Did NOT use the one-`sorry` / ≤3-line / user-compiles-between-steps proof-attempt grind
+- [ ] Wrote the run report to `IMPLEMENTATION_nN.md` and returned with a ## IMPLEMENTATION COMPLETE / ## ESCALATE / ## BLOCKED header
+- [ ] All writes via the Write tool; no bare `lake build`; no generated-Lean edits; no `gh` auto-open; Lean-via-Aeneas pipeline only; no @-references
+</success_criteria>
+</content>
+</invoke>

package/agents/fvs-crypto-thinker.md

@@ -34,6 +34,16 @@ Your parent command provides the stage via a `<thinker_mode>` tag and the inline
 prior plan/review in `fv-plans/<topic>/`.
 **Output (returned as text):** ONE bounded executor plan.
 
+**Depth fence (statements, not proofs):** the plan carries the SPEC VERBATIM (APIs, def bodies,
+theorem/definition statements) but contains NO proof bodies and NO tactic scripts -- authoring the
+proof is the executor's job, not yours. You do NOT compile or type-check while planning: at most ONE
+coarse go/no-go compile check, and only when viability genuinely hinges on an architectural unknown.
+That single go/no-go probe is a viability check, NOT a style certification -- `lake build` in the
+executor's loop remains the style authority (a planner that does not fully compile cannot certify
+style). `Bash` stays in your tool list SOLELY for that one permitted go/no-go probe, and so the plan
+can author the `nice -n 19 lake build` command as text the executor runs; it is not a license to
+iterate a proof while planning.
+
 The plan is bounded and runtime-neutral -- it must be executable by a Claude, Codex, or other
 runtime's executor with no thinker in the loop. State EVERY field explicitly:
 
@@ -48,7 +58,8 @@ runtime's executor with no thinker in the loop. State EVERY field explicitly:
    the exact statement each must carry. A `sorry` is never judged by count; only a named obligation
    with the correct statement is acceptable.
 6. **Stop conditions** -- the explicit conditions under which the executor halts (target reached,
-   build red after N attempts, a modeling decision needed).
+   build red after N attempts, a modeling decision needed). A modeling decision or any change to a
+   public statement is ESCALATED to the user -- never decided by the thinker.
 7. **Verification commands** -- ALWAYS `nice -n 19 lake build` (never a bare `lake build`), with the
    `set -o pipefail` / `${PIPESTATUS` guard so a piped build failure is never masked.
 8. **Expected artifact updates** -- which `fv-plans/<topic>/{plans,reviews,sources,merge}` files the

package/agents/fvs-executor.md

@@ -68,6 +68,7 @@ Your parent command provides `<execution_mode>` and `<research_findings>` tags.
    - Postcondition candidates
    - Similar spec examples as patterns
    - Dependency specs
+   - The complete target repository style guide and its mechanical limits
 2. Generate a Lean specification file containing:
    - Import statements
    - Spec theorem with appropriate postconditions
@@ -75,15 +76,25 @@ Your parent command provides `<execution_mode>` and `<research_findings>` tags.
    - Comments linking to the source function
 3. Write the spec file to the project-conventional Specs/ directory
 4. Use established naming convention: `{FunctionName}_spec`
+5. Treat the target style guide as a hard output contract. Wrap at its line limit (100 columns
+   when unspecified), and replace identifiers with three or more namespace dots by a scoped
+   namespace/open or a local name/abbreviation.
 </mode>
 
 <mode name="proof-attempt">
 **Dispatched by:** /fvs:lean-verify
+**Scope:** Functional-correctness track only. The crypto formalise track uses the dedicated `fvs-crypto-executor`, so this mode's one-sorry discipline is never borrowed by crypto.
 **Input:** Current proof state, available lemmas, recommended strategy from research
 **Output:** Modified spec file with tactic steps replacing sorry
 
 CRITICAL BEHAVIORAL CONSTRAINT: Work ONE sorry at a time. Write small tactic blocks (have, calc, unfold + step). The user checks that Lean compiles between each step.
 
+The theorem name and statement are immutable in ordinary proof-attempt mode: replace only the
+targeted proof `sorry`. If the user explicitly authorizes a statement edit, preserve its
+mathematical meaning and apply the complete target style guide to the edited declaration. Never
+introduce a line over the configured limit or an ordinary identifier with three or more namespace
+dots.
+
 1. Read the research findings to identify:
    - Which sorry to target (first unresolved, or as directed by user)
    - Available @[step] lemmas from dependencies
@@ -118,6 +129,17 @@ For spec-generation mode:
 - Express bounds from Rust source analysis, not guesses
 - Include `sorry` placeholder -- do not attempt proof
 - Follow lean-spec-conventions from the inlined reference
+- Follow the inlined target repository style guide as a hard constraint. It takes precedence over
+  generic template presentation, but never over mathematical/source fidelity.
+- Default to at most 100 columns when the guide has no explicit limit.
+- Prefer `namespace`, `open`, and local names/abbreviations over identifiers with three or more
+  namespace dots.
+
+For proof-attempt mode:
+- Follow the inlined target repository style guide for every inserted line.
+- Do not edit a theorem name or statement unless the user explicitly requested that semantic
+  surface. An authorized statement edit must pass the full style gate, not a legacy baseline
+  exemption.
 
 For map-code and plan modes:
 - Overwrite existing CODEMAP.md or PLAN.md (these are regenerated, not appended)
@@ -163,6 +185,7 @@ On failure:
 - [ ] Mode-specific output produced matching expected format
 - [ ] For proof-attempt: one sorry targeted at a time, small tactic blocks
 - [ ] For spec-generation: sorry placeholder included, correct Lean types
+- [ ] Target repository style guide followed; no new long-line or deep-qualification violation
 - [ ] For map-code/plan: complete structured document generated
 - [ ] Result returned with ## EXECUTION COMPLETE or ## NEEDS INPUT header
 - [ ] No @-references used (all context is inlined by parent)

package/agents/fvs-researcher.md

@@ -58,7 +58,9 @@ Your parent command provides a `<research_mode>` tag specifying what kind of res
 4. Check for existing stubs in .formalising/stubs/ for the target function
 5. Search for similar verified specs in the Specs/ directory to use as pattern examples
 6. Read dependency specs -- any functions called by the target that already have specs
-7. Analyze the function for:
+7. Read the inlined target repository style guide and identify its naming, namespace, line-length,
+   comment, and layout rules. Prefer repository examples that comply with that guide.
+8. Analyze the function for:
    - Control flow (branches, loops, error paths)
    - Arithmetic operations and overflow potential
    - Type dependencies
@@ -76,7 +78,9 @@ Your parent command provides a `<research_mode>` tag specifying what kind of res
 4. Gather tactic examples from similar proofs in the project
 5. Read dependency specs that may provide useful @[step] lemmas
 6. If user feedback is provided (error messages, goal state), incorporate it
-7. Return structured findings with:
+7. Apply the inlined target repository style guide when recommending tactic shapes or any
+   explicitly requested theorem-statement edit.
+8. Return structured findings with:
    - Current proof state (which sorry is targeted)
    - Available lemmas and tactics
    - Recommended proof strategy

package/bin/install.js

@@ -60,6 +60,10 @@ const CODEX_AGENT_SANDBOX = {
   // return (the command body persists the artifacts) and the auditor only
   // introspects and returns a table -- both are read-only.
   'fvs-crypto-thinker': 'read-only',
+  // The crypto executor owns the deliverable file -- it writes the new spec and
+  // completes proofs, so it needs workspace-write; the unmapped default is
+  // read-only, which would silently fail every write on Codex.
+  'fvs-crypto-executor': 'workspace-write',
   'fvs-axiom-auditor': 'read-only',
 };
 
@@ -91,6 +95,9 @@ const FVS_CODEX_AGENT_EFFORT = {
   // so it runs at xhigh (the dual-runtime Codex thinker must think at least this
   // hard); the read-only auditor introspects axioms at high.
   'fvs-crypto-thinker': 'xhigh',
+  // The crypto executor is the dial-down implementation stage (vs the thinker's
+  // xhigh authoring) -- it executes a fully-specified plan, so it runs at high.
+  'fvs-crypto-executor': 'high',
   'fvs-axiom-auditor': 'high',
 };
 
@@ -1369,9 +1376,15 @@ function isFvsManagedCodexHookCommand(commandText, configDir) {
 
 // Read hooks.json, drop any prior FVS-managed entries for `eventName`, then
 // append exactly one fresh managed entry (unless managedCommand is null, which
-// means remove-only). Foreign entries are preserved and the file is written back
-// in the SAME shape it used: nested `{ hooks: { <Event>: [...] } }` or flat
-// `{ <Event>: [...] }`. Returns { changed, wrote, path }.
+// means remove-only). Foreign entries are preserved and the file is ALWAYS
+// written back in the nested `{ "hooks": { "<Event>": [...] } }` shape that
+// current Codex (0.142.x) requires — the older flat `{ "<Event>": [...] }` shape
+// is silently ignored by Codex. A flat top-level table is treated as a legacy
+// read source and migrated to nested: the sanitized event table plus any foreign
+// top-level event keys (e.g. Stop, PostToolUse, SubagentStart) are rehomed under
+// `hooks`, so the written object is exactly `{ hooks: { ...all events... } }`
+// (foreign non-event top-level content is preserved at the top level).
+// Returns { changed, wrote, path }.
 function reconcileCodexHooksJsonEvent(targetDir, eventName, opts = {}) {
   const hooksJsonPath = path.join(targetDir, 'hooks.json');
   const managedCommand = typeof opts.managedCommand === 'string' ? opts.managedCommand : null;
@@ -1394,8 +1407,21 @@ function reconcileCodexHooksJsonEvent(targetDir, eventName, opts = {}) {
 
   const usesNestedHooksObject =
     parsed.hooks && typeof parsed.hooks === 'object' && !Array.isArray(parsed.hooks);
-  const hookTable = usesNestedHooksObject ? parsed.hooks : parsed;
-  const eventEntries = Array.isArray(hookTable[eventName]) ? hookTable[eventName] : [];
+
+  // Build the normalized nested event table. Seed it from any existing nested
+  // `parsed.hooks` events, then rehome any foreign top-level event keys — a
+  // legacy flat table stores events directly at the top level, so migrate them
+  // (an already-nested key wins over a same-named flat one).
+  const nestedTable = {};
+  if (usesNestedHooksObject) {
+    for (const [key, value] of Object.entries(parsed.hooks)) nestedTable[key] = value;
+  }
+  for (const [key, value] of Object.entries(parsed)) {
+    if (key === 'hooks') continue;
+    if (Array.isArray(value) && !(key in nestedTable)) nestedTable[key] = value;
+  }
+
+  const eventEntries = Array.isArray(nestedTable[eventName]) ? nestedTable[eventName] : [];
 
   let removedManaged = false;
   const sanitizedEntries = [];
@@ -1423,28 +1449,41 @@ function reconcileCodexHooksJsonEvent(targetDir, eventName, opts = {}) {
   }
 
   if (sanitizedEntries.length > 0) {
-    hookTable[eventName] = sanitizedEntries;
+    nestedTable[eventName] = sanitizedEntries;
   } else {
-    delete hookTable[eventName];
+    delete nestedTable[eventName];
+  }
+
+  // Assemble the always-nested output. Preserve foreign non-event top-level keys
+  // (anything other than `hooks` whose value is not an array) so unrelated
+  // user-authored content survives; the event keys themselves live under `hooks`.
+  const output = {};
+  for (const [key, value] of Object.entries(parsed)) {
+    if (key === 'hooks') continue;
+    if (Array.isArray(value)) continue;
+    output[key] = value;
+  }
+  if (Object.keys(nestedTable).length > 0) {
+    output.hooks = nestedTable;
   }
-  if (usesNestedHooksObject) parsed.hooks = hookTable;
 
-  // When the reconcile empties the object (no foreign keys remain) and a file
-  // existed on disk, delete it rather than leaving an orphaned `{}` the user
-  // never authored. Foreign content keeps at least one key, so this only fires
-  // for an FVS-only file. A non-existent file with nothing to write is a no-op.
-  if (Object.keys(parsed).length === 0) {
+  // When the reconcile empties the whole normalized object (no events, no foreign
+  // top-level content) and a file existed on disk, delete it rather than leaving
+  // an orphaned `{}` the user never authored. Foreign content keeps at least one
+  // key, so this only fires for an FVS-only file. A non-existent file with
+  // nothing to write is a no-op.
+  if (Object.keys(output).length === 0) {
     if (currentContent !== null) {
       const removed = removedManaged || currentContent.trim() !== '{}';
       fs.unlinkSync(hooksJsonPath);
       return { changed: true, wrote: removed, path: hooksJsonPath, deleted: true };
     }
-    return { changed: changed || removedManaged, wrote: false, path: hooksJsonPath };
+    return { changed: removedManaged, wrote: false, path: hooksJsonPath };
   }
 
-  const nextContent = `${JSON.stringify(parsed, null, 2)}\n`;
+  const nextContent = `${JSON.stringify(output, null, 2)}\n`;
   const changed = currentContent !== nextContent;
-  const shouldWrite = changed && (currentContent !== null || Object.keys(parsed).length > 0);
+  const shouldWrite = changed && (currentContent !== null || Object.keys(output).length > 0);
   if (shouldWrite) {
     atomicWriteFileSync(hooksJsonPath, nextContent, 'utf8');
   }
@@ -2870,6 +2909,32 @@ function install(isGlobal, runtime = 'claude') {
     failures.push('fv-skills');
   }
 
+  // The Aeneas sync command cannot operate without its mapping metadata. A
+  // recursive directory copy can otherwise look successful even when a
+  // packaging omission drops this single non-Markdown file, so verify both
+  // presence and the minimum schema explicitly (#29).
+  const syncMetaDest = path.join(skillDest, 'upstream', 'aeneas', '_sync-meta.json');
+  if (!verifyFileInstalled(syncMetaDest, 'Aeneas sync metadata')) {
+    failures.push('fv-skills/upstream/aeneas/_sync-meta.json');
+  } else {
+    try {
+      const syncMeta = JSON.parse(fs.readFileSync(syncMetaDest, 'utf8'));
+      if (
+        typeof syncMeta.upstream_source !== 'string' ||
+        !Array.isArray(syncMeta.mapping) ||
+        syncMeta.mapping.length === 0 ||
+        !syncMeta.tactic_renames ||
+        typeof syncMeta.tactic_renames !== 'object'
+      ) {
+        throw new Error('missing upstream_source, mapping entries, or tactic_renames');
+      }
+      console.log(`  ${green}✓${reset} Verified Aeneas sync metadata`);
+    } catch (e) {
+      console.error(`  ${yellow}✗${reset} Invalid Aeneas sync metadata: ${e.message}`);
+      failures.push('fv-skills/upstream/aeneas/_sync-meta.json (invalid)');
+    }
+  }
+
   // Copy agents to agents directory
   const agentsSrc = path.join(src, 'agents');
   if (fs.existsSync(agentsSrc)) {

package/commands/fvs/crypto-eval.md

@@ -50,8 +50,8 @@ NEVER `eval` a path.
 ```bash
 TOPIC_RAW="$1"
 case "$TOPIC_RAW" in
-  *[';|&$`()<>'*]* ) echo "FVS >> ERROR: topic contains shell metacharacters" >&2; exit 1 ;;
   *..*|*/* ) echo "FVS >> ERROR: topic contains '..' or '/' (path traversal); refusing" >&2; exit 1 ;;
+  *[![:alnum:]_[:space:]-]* ) echo "FVS >> ERROR: topic contains unsupported characters" >&2; exit 1 ;;
 esac
 SLUG=$(printf '%s' "$TOPIC_RAW" | tr -s '[:space:]' '-')
 ROOT=".formalising/fv-plans/$SLUG"
@@ -93,7 +93,7 @@ EXITS -- there is NO live cross-process bridge. The helper is EFFORT-ONLY: it pa
 
 ```bash
 # --codex mode: swap the in-runtime thinker for the FVS-owned Codex thinker (eval stage).
-node scripts/fvs-codex-think.mjs eval --topic "$ROOT" --effort xhigh
+node ~/.claude/scripts/fvs-codex-think.mjs eval --topic "$ROOT" --effort xhigh
 ```
 
 If `--codex` is passed but `codex` is unavailable, the helper surfaces its graceful install message
@@ -133,7 +133,8 @@ Review:    reviews/EVAL_{ITER}.md
 
 <codex_skill_adapter>
 The `--codex` flag swaps the thinker for a Codex thinker at THIS eval stage via the FVS-owned helper
-`scripts/fvs-codex-think.mjs` (`node scripts/fvs-codex-think.mjs eval --topic "$ROOT" --effort xhigh`).
+`~/.claude/scripts/fvs-codex-think.mjs`
+(`node ~/.claude/scripts/fvs-codex-think.mjs eval --topic "$ROOT" --effort xhigh`).
 The helper is FVS-owned and self-contained: it does NOT import or depend on the openai-codex plugin;
 it spawns `codex` via an argv array (never a shell string), is EFFORT-ONLY (passes `--effort xhigh`,
 NO `--model`), and points Codex at the topic folder as its working root. Coordination is