dl4rce/flaiwheel

Highlights

Every structured writer now auto-emits frontmatter. All seven write_* MCP tools (write_bugfix_summary, write_architecture_doc, write_api_doc, write_best_practice, write_setup_doc, write_changelog_entry, write_test_case) prepend a canonical YAML frontmatter block to every doc they create — meaning every new knowledge doc is automatically a graph node reachable from relations() and timeline(). No manual frontmatter editing, no agent ceremony, no opt-in step.

Combined with v3.10.0, this is what unlocks the structured-relations feature in practice: knowledge created from this point forward compounds into a real per-project graph without anyone having to remember.

Example

# Agent calls:
write_bugfix_summary(title="Fix Payment Race Condition", ...)

The resulting bugfix-log/2026-05-22-fix-payment-race-condition.md now starts with:

---
id: bugfix-2026-05-22-fix-payment-race-condition
type: bugfix
status: active
replaces: []
depends_on: []
fixes: []
implements: []
---

And relations("bugfix-2026-05-22-fix-payment-race-condition") will resolve any inbound/outbound edges across the project — out of the box.

ID convention (per writer)

| Writer | Entity ID pattern | Type |
|---|---|---|
| write_bugfix_summary | bugfix-YYYY-MM-DD-<slug> | bugfix |
| write_architecture_doc | adr-YYYY-MM-DD-<slug> | architecture |
| write_api_doc | api-<slug> | api |
| write_best_practice | best-practice-<slug> | best-practice |
| write_setup_doc | setup-<slug> | setup |
| write_changelog_entry | changelog-<version-slug> | changelog |
| write_test_case | test-YYYY-MM-DD-<slug> | test |

Stable, predictable, never reused. Same-day rewrites overwrite cleanly with minimal diff.

Added

• flaiwheel.frontmatter.emit(entity_id, entity_type, *, status, replaces, depends_on, fixes, implements) — deterministic, ordered frontmatter renderer. Stdlib only.
• 8 new tests in TestFrontmatterAutoEmission — one per writer plus an end-to-end relations() round-trip confirming inbound-edge resolution between two writer-created docs.

Changed

• All seven write_* builders prepend the emitted frontmatter to content and use the derived entity ID for the file slug.

Notes / limits

• Writers still do not accept explicit replaces / depends_on arguments. To declare an explicit edge today, edit the emitted frontmatter or write the doc manually. Adding optional relation params to the writers is a candidate for a follow-up minor — speak up if you want it sooner.
• Fully backwards-compatible. Existing docs without frontmatter continue to work; they just don't show up as graph nodes until rewritten.

Test coverage

• 292 tests pass (up from 284 in v3.10.0).

Upgrade

bash <(curl -sSL https://raw.githubusercontent.com/dl4rce/flaiwheel/main/scripts/install.sh)

No data migration. The next write_* call you make in any project will produce a frontmatter-bearing doc.

Full changelog: https://github.com/dl4rce/flaiwheel/blob/main/CHANGELOG.md
Diff: https://github.com/dl4rce/flaiwheel/compare/v3.10.0...v3.10.1