fpf-sync

name

fpf-sync

description

Sync the fpf-core skill from the canonical FPF-Spec.md monolith. Use when: (1) the FPF specification has been updated (git pull shows new commits), (2) the fpf-core skill references/ are stale or show wrong counts, (3) running scheduled maintenance on LFW skills. Self-contained — bundles decompose_fpf.py + _common.py directly. No dependencies on external skills. Works only with the local skill at `../fpf-core/` (relative to this skill) — NOT the global user skill.

FPF Core Skill Sync

Bounded context: Keeping ../fpf-core/ in sync with the canonical FPF monolith ../../FPF-Spec.md.

Self-contained — all decomposition logic is bundled in scripts/. No external skill dependencies. Requires only Python 3.10+ and git in PATH.

Quick Start

# Check if update is needed (exit code 0=up-to-date, 1=needs update):
python scripts/sync_fpf_core.py --check

# Full sync (git pull + copy + decompose + update SKILL.md):
python scripts/sync_fpf_core.py

# Preview without writing:
python scripts/sync_fpf_core.py --dry-run

# Sync without running git pull (use local state):
python scripts/sync_fpf_core.py --no-git

Workflow

The script performs these steps in order:

1. git pull in repo root (../..) — fetch latest FPF-Spec.md
2. Compare hashes — FPF-Spec.md vs skills/fpf-core/assets/FPF-Spec.md. If identical, exit cleanly
3. Copy monolith — updated FPF-Spec.md → skills/fpf-core/assets/FPF-Spec.md
4. Decompose — calls bundled decompose_fpf.parse_fpf_spec() to rebuild all references/*.md + INDEX.md from the monolith. Uses idempotent writes — only changed files are overwritten
5. Update SKILL.md — refreshes line count (e.g. 100K+) and reference counts (291 pattern reference files + INDEX + 34 context sections)
6. Report — prints counts, warnings, and errors

Scripts

File	Role	Size
sync_fpf_core.py	Orchestrator: git pull → diff → copy → decompose → update SKILL.md	7 KB
decompose_fpf.py	FPF monolith parser: ToC parsing, :End-marker boundary detection, pattern extraction	15 KB
_common.py	Shared utilities: reference formatting, YAML frontmatter, idempotent writes, INDEX generation	7 KB
errors.py	Error types for pattern extraction	1 KB

Error Handling

Situation	Script behavior
git pull fails (network, auth)	Warning — continues with local state
Source FPF-Spec.md missing	Error — exits with code 2
Decomposition produces warnings	Printed — exits with code 0 (non-fatal)
Decomposition produces errors	Printed — exits with code 1
No changes detected	Exits cleanly with code 0

SDC Alignment

This skill implements SDC.SyncDiscipline (Spec-Decomposer LPF) for the specific case of the fpf-core skill:

• Unidirectional sync (AS.10:4.1): monolith → references. Never the reverse.
• Carrier split (AS.4:4.1): agent reads references/, human edits assets/FPF-Spec.md
• Full rebuild on every change: copy monolith → decompose → update dispatcher
• Idempotent writes: decompose_fpf.py skips unchanged files

Evolution

If the user is dissatisfied with the result or the FPF-Spec structure changes, offer to update this skill's script or its SKILL.md instructions.