Skip to content

v3.3.0 - Markdown Frontmatter Fix + Post-Upgrade Task Convention

Choose a tag to compare

View all tags
@edmondscommerce edmondscommerce released this 14 Apr 15:26
· 6576 commits to main since this release
v3.3.0
f34e8cb

Release v3.3.0 - Markdown Frontmatter Fix + Post-Upgrade Task Convention

Release Date: 2026-04-14
Type: Minor Release

Summary

Version 3.3.0 fixes a silent file-corruption bug in the markdown_table_formatter PostToolUse handler and the format-markdown CLI subcommand, and introduces a generic post-upgrade-tasks/ convention that gives the release pipeline a formal mechanism for shipping post-upgrade instructions (audits, config migrations, workflow changes, notifications) to upgrading LLMs and humans.

The markdown fix is important on its own — any .md file whose first line was --- (notably Claude Code SKILL.md files, but also any Jekyll/Hugo/MkDocs content) was being silently rewritten so the opening --- became a 70-underscore thematic break and the YAML body was collapsed into a ## heading. The bug is now fixed, but files already damaged on disk remain damaged — the shipped post-upgrade task 01-audit-markdown-frontmatter.md walks an upgrading agent through detection and remediation.

Added

  • post-upgrade-tasks/ convention: Tasks are drafted in CLAUDE/UPGRADES/UNRELEASED/post-upgrade-tasks/ during the release cycle and moved into the versioned upgrade guide at release time. Each task is a self-contained .md file with a mandatory header (Type/Severity/Applies to/Idempotent) and sections Why/How to detect/How to handle/How to confirm/Rollback. Advisory only — nothing runs them automatically.
  • Release pipeline BLOCKING gate (Step 6): RELEASING.md and the /release skill now require moving every UNRELEASED task into the versioned upgrade guide before the Opus documentation review. Release ABORTS if any task file remains in UNRELEASED/ after Step 6. The Opus review checklist verifies the versioned guide's task index is populated and that release notes reference post-upgrade tasks when any are critical or recommended.
  • Per-release task index README: CLAUDE/UPGRADES/upgrade-template/post-upgrade-tasks/README.md template with the task-index table schema.

Fixed

  • markdown_table_formatter YAML frontmatter mangling: The handler and the format-markdown CLI now strip frontmatter before formatting and re-attach it byte-for-byte afterwards. Previously, mdformat (which does not understand frontmatter) rewrote the opening --- as a 70-underscore thematic break, collapsed the YAML body onto a ## heading, and lost the closing ---.

Post-Upgrade Tasks

After upgrading, review CLAUDE/UPGRADES/v3/v3.2-to-v3.3/post-upgrade-tasks/ — it contains 1 recommended task that may require action in your project: 01-audit-markdown-frontmatter.md walks through detecting and restoring any .md files damaged by the frontmatter bug during v3.0.0–v3.2.1. If the project has never been on v3.0.0–v3.2.1, skip this task.

Install / Upgrade

# New installation
git clone -b v3.3.0 https://github.com/Edmonds-Commerce-Limited/claude-code-hooks-daemon.git .claude/hooks-daemon
cd .claude/hooks-daemon && ./install.sh

# Upgrade from v3.2.x
cd .claude/hooks-daemon && ./upgrade.sh

Test Stats

  • Tests: 7,621+ passing
  • Coverage: 95%+
  • QA checks: 10/10 passing

Comparison

Full diff: v3.2.1...v3.3.0

Assets 2
Loading