STD-CHANGELOG-001: Bluefly Factory AI Changelog Standard¶

1. Purpose¶

This standard governs the creation, formatting, and automated maintenance of CHANGELOG.md files across all Bluefly Factory repositories (BluCity-Docs, DrupalWorks, GasCity, OpenClaw, Harbormaster).

2. Prime Directives¶

Mandatory Artifact: Every Bluefly repository MUST maintain a top-level CHANGELOG.md.
Automated AI Synthesis: Humans and agents DO NOT write raw changelog entries manually. Changelogs are synthesized by AI during Bead closure (bd close), Gas City hook execution (gc hook), or GitLab MR merges (glab mr merge).
Traceability: Every entry MUST reference its originating Gas City Bead ID ([Bead: bc-xxx]) and/or GitLab MR ([MR: !123]).

3. Formatting Specification (Keep a Changelog v1.1.0 + Bead Provenance)¶

Changelogs MUST follow the Keep a Changelog standard with the following standard sections:

## [Unreleased] — Active work committed to development branches.
## [VERSION] - YYYY-MM-DD — Tagged releases.

Standard Categories:¶

### Added — New features, formulas, or capabilities.
### Changed — Modifications to existing behavior, architecture, or standards.
### Deprecated — Features marked for future removal.
### Removed — Deleted features, formulas, or files.
### Fixed — Bug fixes, RCA resolutions, or stability patches.
### Security — Vulnerability patches, auth constitution updates (STD-AUTH-001).
### Drupal & Schema — Database schema updates (hook_update_N), ECA workflow shifts, module updates (DrupalWorks scope).

4. Gas City & GitLab Integration¶

flowchart LR
    A["Developer / Agent Commit"] --> B["Bead Close (bd close)"]
    B --> C["Gas City Formula (mol-gascity-changelog-generate)"]
    C --> D["LiteLLM Gateway (fast / reasoning)"]
    D --> E["Prepend CHANGELOG.md"]
    E --> F["GitLab MR Merge (release/v0.1.x)"]

Gas City Formula: mol-gascity-changelog-generate
Trigger Points:
gc hook --close
GitLab MR Merge hook
Tooling: scripts/changelog/generate-ai-changelog.py