Skip to content

FCoP 3.0.0 - Protocol Semantic Sealing

Choose a tag to compare

View all tags
@joinwell52-AI joinwell52-AI released this 21 May 14:23
v3.0.0
0efaa9b

FCoP 3.0.0 — Protocol Semantic Sealing

Files carry protocol. Paths address state. Events replay transitions.

文件即协议；位置定义状态；事件记录历史。

FCoP 3.0 is the protocol's first semantic seal. It marks the end of the design era and the beginning of the Runtime Absorption Era (ADR-0039).

From this date forward, the protocol surface is frozen. The only legitimate trigger for a future change is documented runtime pressure from a real coordination scenario — not theoretical purity, aesthetic extension, or completeness urge.

Canonical one-liner shown above is Layer 1 (cognitive bootstrap). The compressed formal definition (Layer 2 — "Files externalize protocol semantics. Paths address state. Events are replayable evidence of state transitions.") lives in spec §0.2. Rationale for the two-layer split: ADR-0040.

What's New

Protocol layer

  • State Ontology (frozen) — 5 stages (inbox / active / review / done / archive) defined by physical file location under _lifecycle/. (ADR-0035)
  • Event Layer — append-only transitions: array in YAML frontmatter records every state change. (ADR-0036)
  • Boundary Charter — meta-charter declaring what FCoP is not. (ADR-0038)
  • Freeze Discipline — self-binding meta-rule closing the protocol-design era. (ADR-0039)
  • Canonical Two-Layer Convention — splits the canonical one-liner into a teaching layer and a formal-definition layer. (ADR-0040)
  • Custody rejected as a separate layer — preserved as informative note (NOTE-custody-is-not-a-layer) and field-report essay (the-day-we-almost-added-custody).

Reference implementation

  • New fcop.lifecycle subpackage: state / transitions / events / atomic / detect / migrate
  • Project facade now detects topology (empty / v2 / v3 / mixed) and exposes lifecycle_root / inbox_dir / active_dir / review_dir / done_dir / archive_dir
  • write_task + archive_task transparently route through the lifecycle primitives on v3 projects — CodeFlow and any other v2-era caller continues to work unmodified
  • 35 MCP tools annotated with tier:L1 / tier:L2 / tier:L3 tags per spec §8

Migration

  • New CLI: fcop migrate --to-v3 (dry-run by default; --apply to execute)
  • Git-aware (uses git mv when the workspace is tracked)
  • Stamps synthetic baseline events on pre-existing files
  • Idempotent — safe to re-run

Documentation

Breaking Changes

  • Directory topology changes for v3 projects: tasks/ and log/tasks/ no longer exist; everything lives under _lifecycle/{inbox,active,review,done,archive}/
  • v2 projects continue to work unchanged — opt-in to v3 via fcop migrate --to-v3
  • No automatic migration in Project.__init__; explicit CLI command required

See docs/MIGRATION-3.0.md for the full migration walkthrough.

Install

# Python library
pip install fcop==3.0.0

# MCP server (any client: Cursor / Claude Desktop / PulseMCP / Cline / ...)
uvx fcop-mcp
pip install fcop-mcp==3.0.0

The MCP server is also listed in the official MCP registry as io.github.joinwell52-AI/fcop@3.0.0.

Engineering Numbers

  • 1202 tests passing · 0 regressions · 3 skipped
  • 0 new public methods on Project (the spec verbs are emitted as event tool names, not added as API)
  • 35 MCP tools — 2 L1 + 18 L2 + 15 L3 (exhaustive)
  • ruff clean across src/fcop, mcp/src/fcop_mcp, tests/
  • mypy --strict clean across the lifecycle subpackage

The Era This Opens

Adopting 3.0 is the moment FCoP stops being a designed protocol and starts being a lived one. The next protocol change — whenever it comes — will not have been imagined. It will have been observed.

Filed 2026-05-21 · the day the design era ended.

Full changelog: CHANGELOG.md [3.0.0]

Assets 2
Loading