<purpose>
Orchestrate a two-mode synchronization of upstream Charon/Aeneas content into FVS, fanning out to
the `fvs-doc-syncer` worker in two specialised modes:

- **tactics-lean-syntax** — the `_sync-meta.json` mapping + `tactic_renames` machinery (today's
  tactic/Lean-syntax scope): section-level diff, propose-each, reconcile-not-append.
- **extraction-docs** — the Charon/Aeneas EXTRACTION documentation plus a reconcile pass over the
  shipped blocker catalog: re-check each seed blocker against live upstream and flag
  retire / update-signature / still-open, in place, never blind-append.

The orchestrator mines the config-driven LOCAL clones first (Charon + Aeneas, resolved via
config -> auto-detect -> prompt -> error, never hardcoded), reports clone staleness gracefully, and
dispatches `fvs-doc-syncer` once per mode. The user reviews and approves each proposed change.

Output: Updated FVS references / extraction docs, a reconciled blocker catalog, a refreshed snapshot,
and updated `_sync-meta.json`.
</purpose>

<process>

<step name="preflight_sync_metadata">
## Step 0: Preflight Installed Sync Metadata

Before config resolution, clone prompts, fetches, or dispatches, resolve
`$HOME/.claude/fv-skills/upstream/aeneas/_sync-meta.json` (the installer rewrites the runtime path)
and require a non-empty, parseable JSON object with `upstream_source`, non-empty `mapping` and
`extraction_inputs` arrays, an explicit `snapshot_target` for every extraction input, and an
object-valued `tactic_renames` table.

If it is missing or invalid, STOP and report:

```
FVS >> AENEAS SYNC METADATA MISSING

Run /fvs:update to refresh this installation. There is no separate Aeneas install option.
```

**Inputs:** installed FVS tree
**Outputs:** validated `$SYNC_META`
**Error handling:** fail before every network call and worker dispatch; never continue with an empty
mapping and never direct the user to a nonexistent installer option.
</step>

<step name="resolve_models">
## Step 1: Resolve Subagent Model + Effort

Use stage `doc_sync` and the confirmed command-level selection manifest from
`model-profiles.md` for every `fvs-doc-syncer` mode. Validate exact runtime/provider model and effort
support. If the stage is absent, rebuild and reconfirm the manifest before dispatch; never silently
fall back.

**Inputs:** config file
**Outputs:** `$SYNCER_MODEL`, `$SYNCER_EFFORT`
</step>

<step name="resolve_clones">
## Step 2: Resolve the Local Clones

Resolve `charon_clone_path` and `aeneas_clone_path` with the precedence config -> auto-detect ->
prompt -> error. Never hardcode an absolute clone path. Quote every path expansion, reject a path
with shell metacharacters, never `eval` a path. Validate each resolved clone is a directory before
any `git -C "<clone>"`.

**Inputs:** config clone-path keys
**Outputs:** resolved `$CHARON_CLONE` / `$AENEAS_CLONE` (or a recorded "unresolved" for graceful
degradation)

**Error handling:**
- A clone path resolves but is not a directory: report and skip mining that source.
- A clone cannot be resolved at all (config tail): report the missing source and CONTINUE the other
  mode rather than aborting the run -- mining is config-gated, not run-gating.
</step>

<step name="freeze_upstream">
## Step 3: Freeze Upstream Revisions

Resolve upstream refs once before any content fetch or worker dispatch. Record
`FROZEN_AENEAS_SHA`, `FROZEN_AENEAS_DATE`, `FROZEN_CHARON_PIN`,
`FROZEN_CHARON_MAIN_SHA`, and `FROZEN_CHARON_MAIN_DATE` in the run manifest.
`FROZEN_CHARON_PIN` comes from `charon-pin` fetched at `FROZEN_AENEAS_SHA`; never read it from a
moving checkout. Validate revisions as 40 lowercase hex characters and dates as ISO-8601. All
Aeneas fetches use `FROZEN_AENEAS_SHA`, pinned-toolchain Charon evidence uses
`FROZEN_CHARON_PIN`, and upstream-fixed comparison evidence uses `FROZEN_CHARON_MAIN_SHA`.

**Inputs:** read-only upstream refs and `charon-pin` at the frozen Aeneas commit
**Outputs:** immutable run manifest; proposed metadata values only
**Error handling:** unresolved or malformed provenance stops before dispatch or writes. Do not
update `_sync-meta.json` in this step.
</step>

<step name="report_staleness">
## Step 4: Report Clone Staleness

Compare each resolved clone `HEAD` against its real expected revision: Aeneas against
`FROZEN_AENEAS_SHA`, Charon against `FROZEN_CHARON_PIN`. Report `up-to-date` / `behind N` /
`ahead N` / `diverged`. Use a clone only if it contains the required frozen commit; otherwise fetch
the exact revision read-only.

**Inputs:** resolved clones and frozen run manifest
**Outputs:** staleness report

**Error handling:** staleness does not invalidate a remotely available frozen source; source
ambiguity or inability to fetch the exact revision does.
</step>

<step name="sync_tactics_lean_syntax">
## Step 5: Fan Out — Mode (a) tactics-lean-syntax

Dispatch the worker for the tactic/Lean-syntax scope, inlining the `_sync-meta.json` mapping, the
`tactic_renames` table, the current snapshot SHA, and the resolved Aeneas clone path:

```
Task(subagent_type="fvs-doc-syncer", model="$SYNCER_MODEL",
     reasoning_effort="$SYNCER_EFFORT", // when supported; otherwise apply the capability gate
     description="Sync tactics + Lean-syntax (mode a)",
     prompt="<sync_mode>tactics-lean-syntax</sync_mode> ...inlined mapping + tactic_renames + ...")
```

The worker fetches mapped upstream files at `FROZEN_AENEAS_SHA` (local clone first only when it
contains that commit, read-only `gh api` / `curl` otherwise), computes a SECTION-LEVEL diff (split
by `## `, hash, classify added/removed/modified), maps changes via `merge_strategy`, checks
`tactic_renames`, and PROPOSES each change (yes / skip / edit). Snapshot and derived-reference
writes are completed and verified before any metadata update.

**Inputs:** mapping, tactic_renames, snapshot SHA, Aeneas clone
**Outputs:** worker return summary (applied / skipped / renames propagated)

**Error handling:**
- GitHub unreachable AND clone unresolved: report, propose no changes for this mode, continue.
- Mapping references a non-existent FVS file: worker reports and skips that entry.
</step>

<step name="sync_extraction_docs">
## Step 6: Fan Out — Mode (b) extraction-docs

Dispatch the worker for the extraction-docs scope + blocker-catalog reconcile, inlining the Charon
and Aeneas extraction doc targets and the current `blocker-catalog.md` seed:

```
Task(subagent_type="fvs-doc-syncer", model="$SYNCER_MODEL",
     reasoning_effort="$SYNCER_EFFORT", // when supported; otherwise apply the capability gate
     description="Sync extraction docs + reconcile catalog (mode b)",
     prompt="<sync_mode>extraction-docs</sync_mode> ...exact extraction_inputs rows and
             snapshot_target values; frozen run manifest; resolved clone paths; current catalog
             seed...")
```

The worker fetches each exact extraction input at its declared frozen revision and writes only its
declared `snapshot_target`. It section-level-diffs snapshots, then RECONCILES the blocker catalog:
re-check each seed blocker against `FROZEN_CHARON_PIN`; check `FROZEN_CHARON_MAIN_SHA` separately
for an `upstream-fixed` annotation. "Fixed in upstream main" is NOT "fixed for us": an entry stays
active until the pin carries the fix and is never auto-`retire`. Never duplicate a signature.
Propose each change (yes / skip / edit).

After approved snapshot and derived-reference writes, verify synchronized targets and hashes, then
write `_sync-meta.json` last. Failed verification leaves metadata unchanged and reports the
candidate.

**Inputs:** extraction doc targets, resolved clones, catalog seed
**Outputs:** worker return summary (applied / skipped / catalog entries reconciled)

**Error handling:**
- Aeneas has no issue templates / CONTRIBUTING: the worker reports the gap, does not fabricate one.
- A reconcile would overwrite the seed wholesale: rejected by the reconcile-not-append discipline.
</step>

<step name="report">
## Step 7: Report

Merge the two workers' return summaries into one banner:

```
FVS >> Sync Complete

| Mode                | Applied | Skipped | Notes                          |
|---------------------|---------|---------|--------------------------------|
| tactics-lean-syntax | {N}     | {M}     | {K} tactic renames propagated  |
| extraction-docs     | {N}     | {M}     | {R} catalog entries reconciled |

Snapshot updated: {old_commit} -> {new_commit}

Run `npm test` to verify no frontmatter or structural issues.
```

**Inputs:** both worker summaries
**Outputs:** final merged report
</step>

</process>

<success_criteria>
- Installed `_sync-meta.json` exists and passes its minimum schema preflight before any other work.
- Clone paths resolved via config -> auto-detect -> prompt -> error; no hardcoded absolute path.
- Aeneas main, its commit date, its exact Charon pin, and current Charon main are frozen once.
- Clone staleness compares Aeneas with the frozen main SHA and Charon with the frozen pin; no
  nonexistent Aeneas self-pin assumption.
- `fvs-doc-syncer` dispatched in BOTH `tactics-lean-syntax` and `extraction-docs` modes.
- Section-level diff (not byte-level) in each mode; each change proposed individually for approval.
- tactics-lean-syntax: mapping + tactic-rename machinery; metadata updated.
- extraction-docs: every input has an explicit snapshot target; blocker catalog reconciled in
  place; no blind append; no auto-retire before the resolved pin carries the fix.
- Approved content is written and verified before `_sync-meta.json` is updated.
- No `gh` auto-open/create; read-only fetch is the only GH path and only a fallback to local mining.
- No silent failures -- all errors reported to the user.
</success_criteria>
