All notable changes to the Charter extension will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
- GitHub Actions workflow running the manifest tests and the shell test suite on macOS 15, macOS latest, Ubuntu, and Windows for every push and pull request.
- Regression tests for the YAML helpers on empty lists and missing fields, and
an end-to-end
compose-size-check.shtest with an emptystate.ymllist. - Project logo in README.md.
- BREAKING: Registry sub-constitution filenames now use
_(underscore) as the path separator instead of-(dash). TheWHEN WORKING ONpath is now derived by replacing_with/in the filename stem, leaving-free for readability within a segment (e.g.package_auth-gateway.md→WHEN WORKING ON package/auth-gateway). Previouslypackages-auth.mdmapped topackages/auth; rename existing registry sub-constitution files to use_instead of-between path segments (e.g.packages-auth.md→packages_auth.md). fragment-list.shno longer uses associative arrays (declare -A) andbackup-list.shno longer usesmapfile. Both require bash 4+, while macOS ships bash 3.2, so those scripts failed outright on a stock macOS shell.
yaml_fieldandyaml_listaborted the calling script underset -euo pipefailwhenever theirgrepstage matched nothing. Any state file holding an empty list (sub_constitutions: [],distributed_sub_constitutions: []) or a missing field killed the caller inside a command substitution —compose-size-check.shexited 1 without printingTOTAL_BYTES=/EXCEEDS_32K=, leaving the config and compose commands with no diagnostics. Both helpers now yield an empty result instead.yaml_liststripped YAML list syntax with\s, which BSD/macOSseddoes not support: every entry came back as- "name"instead ofname, so no fragment ever matched the manifest'smandatory_fragments/recommended_fragmentsand pre-selection was silently lost on macOS. It now uses POSIX character classes, matchingyaml_field.- CI workflow triggers referenced the
mainbranch, which does not exist in this repository; they now referencemaster.
extension.ymlstill declared version0.1.0, well behind the actual released state. Bumped to0.5.1and updated the GitHub release link in README.md to match.
-
Heading normalization in compose. Each section's top heading is automatically shifted to H2 in the final constitution, preserving internal relative depth. A fragment authored with
# Titleand a sub-constitution with#### Titleboth produce## Titlein the composed output. Registry files, snapshots, and distributed package files are never modified — only the assembled constitution content is normalized. -
Typed section markers. Section markers now carry a type tag so the origin of each section is identifiable at a glance in the composed constitution:
<!-- [F] global/compliance SECTION -->— fragment<!-- [SC] sub-constitutions/packages-auth SECTION -->— registry sub-constitution<!-- [DSC] packages/auth/.charter/constitution SECTION -->— distributed sub-constitution<!-- [PS] PROJECT SPECIFIC SECTION -->— project-specific local content
constitution-parse.shandconstitution-extract.shremain backwards-compatible with the legacy<!-- [NAME] SECTION -->format so existing constitutions can still be overridden or updated before recomposition. -
Heading-agnostic snapshot comparison.
snapshot-compare.shnow strips leading#characters from heading lines before diffing, preventing false "modified" warnings caused by the auto-indent applied during compose. Real content changes are still detected correctly. -
Improved sub-constitution prefix lines.
- Registry sub-constitutions: the
WHEN WORKING ONpath is now derived from the filename by replacing-with/(e.g.packages-auth.md→WHEN WORKING ON packages/auth). - Distributed sub-constitutions: the
WHEN WORKING ONpath is the package root (e.g.packages/auth), not the full.charter/constitutionpath.
- Registry sub-constitutions: the
-
New state ID formats for sub-constitutions:
- Registry sub-constitutions are stored as
sub-constitutions/<stem>(e.g.sub-constitutions/packages-auth) to encode their type. - Distributed sub-constitutions are stored as
<pkg>/.charter/constitution(e.g.packages/auth/.charter/constitution) to encode the full source path.
- Registry sub-constitutions are stored as
- Heading normalization and snapshot comparison now track fenced code blocks
(
```/~~~) so#-prefixed shell/Python/YAML comments and shebangs inside code samples are never mistaken for Markdown headings — previously this could mis-indent fragment content or hide a real content change behind a false "unmodified" snapshot comparison. - Replaced the GNU-only
sed 's/^#\+.../'heading-stripping insnapshot-compare.shwith a portableawkimplementation, since the\+extension silently becomes a no-op on BSD/macOSsed.
- BREAKING: Existing composed constitutions use the old
<!-- [NAME] SECTION -->marker format. Run/speckit.charter.composeonce to regenerate the constitution with the new typed markers. Back up first if needed —/speckit.charter.restorecan revert the change. - BREAKING:
state.ymlsub-constitution ID format changed. If you have an existingstate.yml, re-run/speckit.charter.configto regenerate it with the new IDs, or update it manually: change- packages-authundersub_constitutionsto- sub-constitutions/packages-auth, and change- packages/backunderdistributed_sub_constitutionsto- packages/back/.charter/constitution.
- Distributed sub-constitutions for monorepos. Charter can now detect
<package>/.charter/constitution.mdfiles in monorepo packages (recursive, up to 5 package levels) during configuration and offer them for selection. The feature is opt-in via thedistributed_sub_constitutionsflag inconfig.yml(defaultfalse); selected package paths are stored in thedistributed_sub_constitutionslist instate.yml. Each selected package is composed as a scoped section keyed by its package path (<!-- [packages/back] SECTION -->+WHEN WORKING ON packages/back, ...). Detection only matches files inside a.charterfolder, deliberately ignoring a package's own Spec Kit constitution (<package>/.specify/memory/constitution.md) to avoid conflicts when Spec Kit is used both at the monorepo root and inside packages. /speckit.charter.addand/speckit.charter.removenow support distributed sub-constitutions (referenced by package path, e.g.packages/back).- New scripts:
distributed-detect.sh,distributed-read.sh, andconfig-distributed-set.sh.
- Sub-constitutions are now cacheless. Registry sub-constitutions and
distributed sub-constitutions are re-read fresh from their source on every
/speckit.charter.compose, so a plain compose refreshes all of them without anupdatestep. Only fragments retain the snapshot / change-detection mechanism. - The fragment selection list and composition summary now tag every item by
source:
|R|(registry) and|L|(local). The current project constitution is now grouped under[OTHER]and tagged|L|. - The composition summary no longer uses the
------- COMPOSED -------/------- PROJECT SPECIFIC ------separators; it lists each item as[FRAGMENT] |R| <name>,[SUB-CONSTITUTION] |R|/|L| <name>, or[OTHER] |L| <CURRENT PROJECT CONSTITUTION>, followed by a source legend. config.ymlnow includes thedistributed_sub_constitutionsflag; it is preserved across registry changes.
- Added path traversal validation (
validate_package_pathincharter-common.sh) for distributed package paths, applied incompose-size-check.shandconstitution-validate-sections.sh. - Fixed missing executable permissions on the newly added
config-distributed-set.shanddistributed-detect.shscripts.
- Removed the unused
config-template.ymlfile and its stale reference intests/test_manifest.py.
/speckit.charter.composenow runs an inline configuration flow when no charter configuration exists yet (.specify/charter/state.ymlmissing). Instead of erroring out, it prompts for the registry value and the fragment selection, displays the composition summary without asking for confirmation, reminds the user that/speckit.charter.restorecan undo the change, and proceeds automatically to generate the constitution — letting users configure and compose in a single step.
/speckit.charter.configno longer asks for a yes/no/cancel confirmation after the composition summary. It now only requests the registry value and the fragment selection; the summary is shown for information and the configuration is saved automatically./speckit.charter.confignow reminds the user that/speckit.charter.restorecan restore the previous constitution if the generated one is not valid.- Charter commands now delegate to modular helper scripts (
backup-list.sh,backup-preview.sh,backup-restore.sh,constitution-validate-sections.sh,fragment-is-mandatory.sh,registry-default.sh,snapshot-detect-modified.sh,snapshot-list-missing.sh,state-check.sh) instead of inline logic.
- The restoration reminder in the inline configuration flow is now shown at the correct step, after composition completes rather than before.
- Constitution sections are now separated by a trailing blank line, and section extraction trims trailing blank lines to avoid duplicated separators.
- BREAKING: Charter now stores all persistent data under
.specify/charter/instead of.specify/extensions/charter/. The extension install directory is wiped byspecify extension update/remove(only*-config.ymlsurvives), which previously destroyedstate.yml,snapshots/, andbackups/. The new location lives outside the extension lifecycle and survives updates andspecify init --here --force. - Renamed the config file from
charter-config.ymltoconfig.yml. - Renamed the registry cache from
.registry-cache/to.cache/registry/. - A
.specify/charter/.gitignoreis now generated automatically to exclude the disposable.cache/while keeping config, state, snapshots, and backups version-controlled. - Removed the Spec Kit
config:declaration fromextension.yml(Charter reads its own config from.specify/charter/config.yml).
/speckit.charter.configcommand — configure registry and select fragments/speckit.charter.composecommand — compose and generate constitution from fragments/speckit.charter.removecommand — remove a fragment section- Support for local directory registries
- Support for git repository registries (SSH and HTTPS)
- Fragment selection with mandatory, recommended, and optional categories
- Sub-constitution support for monorepo setups
- Local constitution preservation during composition
- Section-aware constitution structure with HTML comment delimiters
- Fragment snapshot management for change detection
- Constitution backup before recomposition
- Size warning when composed constitution exceeds 32 KiB
- Comprehensive shell scripts for registry operations
- Full test suite with fixtures