mirror of
https://github.com/github/spec-kit.git
synced 2026-08-03 06:26:30 +08:00
43a54bf2d6
* feat(presets): add opt-in constitution-sync preset Follow-up to #3790, which removed the consistency-propagation pass from the core /constitution command in favor of runtime resolution. Teams that treat materialized plan/spec/tasks templates as reviewed, committed artifacts lost the auto-sync of amended constitutional guidance on a non-forced upgrade. Add a bundled, opt-in `constitution-sync` preset that restores that behavior via a wrap-strategy override of speckit.constitution (composes on {CORE_TEMPLATE} so it stays forward-compatible). It only writes into the project's own .specify/templates scaffolds and installed command files, never into stack-owned template layers. - presets/constitution-sync/: preset.yml (requires >=0.14.4), wrap command, README documenting the tension between auto-propagation and the resolution stack - presets/catalog.json: bundled entry - docs/upgrade.md: document the 0.14.4 behavior change and the opt-in - tests/test_presets.py: structural + composition coverage (TestConstitutionSyncPreset) Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: afa7c1d2-147b-4f62-a6fc-a2cc824cfa3e * fix(presets): ship constitution-sync in wheel, clarify scope guard, assert composition Address review feedback on #3873: - pyproject.toml: force-include presets/constitution-sync into the wheel's core_pack so `_locate_bundled_preset` resolves it in a released install; the bundled advertisement was otherwise unshippable. - tests/contract/test_wheel_bundled_presets.py: new contract test asserting every bundled preset in presets/catalog.json is force-included (guards lean too). - commands/speckit.constitution.md: explicitly state the propagation section supersedes the core Scope Guard, which otherwise says dependent templates are not modified here. - tests/test_presets.py: assert resolve_content substitutes {CORE_TEMPLATE} and the effective command embeds both the core body and the sync pass. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: afa7c1d2-147b-4f62-a6fc-a2cc824cfa3e * test(presets): parse frontmatter as YAML in constitution-sync wrapper test Address review feedback on #3873: assert `strategy: wrap` structurally by parsing the Markdown frontmatter as YAML (instead of a substring match that could false-positive on body text), and assert {CORE_TEMPLATE} in the body section only. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: afa7c1d2-147b-4f62-a6fc-a2cc824cfa3e * docs(presets): reframe constitution-sync README around behavior and caveats Rework the preset's user-facing docs to describe what it does, what it does not do, and the caveats you take on — rather than leading with version/origin history. The preset stack is the project's forward direction, so the README no longer positions this as "restoring pre-0.14.4 behavior." Also make the edit-in-place vs. composition conflict explicit and consistent across the wrapper command and docs: propagation into command files/templates that are provided or wrapped by a preset/extension is clobbered on stack reconciliation (integration use/upgrade, preset/extension install/remove), so the wrapper restricts propagation to project-local artifacts the team owns. - README: forward-looking "What it does / does not do / When to use / Caveats" - speckit.constitution.md: step 4 no longer hand-edits composed command files; closing caveat covers command files too - docs/upgrade.md: note the composition-model conflict in the opt-in section - tests: assert the updated closing-caveat wording Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: afa7c1d2-147b-4f62-a6fc-a2cc824cfa3e * docs(presets): tweak constitution-sync README default-behavior wording Phrase the default-behavior note as "the current version of Spec Kit" and rewrap the opening paragraph. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: afa7c1d2-147b-4f62-a6fc-a2cc824cfa3e * docs(presets): keep emphasis spans on one line in constitution-sync README Avoid **bold** spans broken across soft line breaks (runtime resolution, reviewed committed artifacts) so they render consistently. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: afa7c1d2-147b-4f62-a6fc-a2cc824cfa3e * docs(presets): refocus constitution-sync README on what it restores Reframe the intro around what the preset restores and what the user opts into, rather than describing current Spec Kit default behavior. Be honest that propagation was removed deliberately (duplicates the source of truth, fights composition) and this preset knowingly reintroduces it and its tradeoffs. Minor flow fixes (comma splice, terse bullet). Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: afa7c1d2-147b-4f62-a6fc-a2cc824cfa3e * docs(upgrade): de-pin version from /constitution behavior-change section The upgrade guide always describes the latest version, so hard-pinning "0.14.4" in the heading and "Starting in 0.14.4" in the body added no value. Keep the #3790 provenance link and the "no longer propagates" framing; the machine-readable version gate stays in preset.yml. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: afa7c1d2-147b-4f62-a6fc-a2cc824cfa3e * docs(upgrade): clarify non-breaking nuance and presets direction Note that the /constitution scope change is only noticeable if you relied on the old edit-in-place behavior, and add the forward-looking framing: presets and extensions — not in-place file edits — are how Spec Kit now governs, versions, and audits shared assets across repositories. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: afa7c1d2-147b-4f62-a6fc-a2cc824cfa3e --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: afa7c1d2-147b-4f62-a6fc-a2cc824cfa3e
127 lines
6.3 KiB
Markdown
127 lines
6.3 KiB
Markdown
# Constitution Template Sync
|
|
|
|
An **opt-in** preset that restores `/constitution`'s ability to propagate amended guidance into your
|
|
project's own templates and command files. After you update the constitution, it aligns
|
|
`plan-template.md`, `spec-template.md`, `tasks-template.md`, project-local command files, and
|
|
guidance docs so they reflect the current principles.
|
|
|
|
This propagation used to be built into `/constitution`; it was dropped when the command moved to the
|
|
preset model. Installing this preset opts you back into it: you get the guidance materialized into
|
|
reviewed, committed artifacts instead of relying on runtime resolution alone.
|
|
|
|
> **What you're opting into.** Propagation was removed deliberately — it duplicates the constitution
|
|
> as the source of truth and can fight the composition stack (materialized edits get shadowed or
|
|
> clobbered on the next recompose). This preset knowingly **reintroduces** that behavior, and those
|
|
> tradeoffs, for teams that want it. Read the [caveats](#caveats-you-take-on) before installing.
|
|
|
|
For most projects the default composable stack is the **recommended** approach, and at organization
|
|
scale it is usually the stronger governance model. Runtime resolution keeps the live constitution as
|
|
the single source of truth (nothing to re-sync, so nothing drifts), and the stack composes the
|
|
**entire** Spec Kit ecosystem — not just the SDD commands, but every command, template, script and
|
|
extension — with explicit priority levels, strategies, and independent versioning. It is a
|
|
capability, not automatic governance: a core team authors its own organizational presets and
|
|
extensions, then owns, versions, and audits that policy in one place and rolls it across many
|
|
repositories, instead of scattering frozen, per-repo copies no central team can see. This preset is
|
|
a supported escape hatch for teams whose workflow depends on reviewing materialized artifacts
|
|
directly — useful as a bridge, though for org-wide policy the better long-term path is usually a
|
|
versioned preset a core team maintains.
|
|
|
|
## What it does
|
|
|
|
Ships a single `wrap`-strategy override of `speckit.constitution`. It composes on top of the
|
|
current core command (via `{CORE_TEMPLATE}`), so it stays forward-compatible with core changes, and
|
|
appends a propagation pass that, after the constitution is written:
|
|
|
|
- Aligns `plan/spec/tasks-template.md` in `.specify/templates/` with the updated principles.
|
|
- Updates **project-local** command files and guidance docs to correct stale references.
|
|
- Extends the Sync Impact Report in `.specify/memory/constitution.md` with the files it touched.
|
|
|
|
## What it does not do
|
|
|
|
- It does **not** change behavior for anyone who does not install it — the default runtime
|
|
resolution model is untouched.
|
|
- It does **not** disable runtime resolution. `plan`, `tasks`, and `analyze` still read the live
|
|
constitution every run; this preset adds materialized copies on top — it does not replace the
|
|
source of truth.
|
|
- It does **not** edit versioned, package-owned files — templates or command files provided or
|
|
wrapped by another preset or extension. Those are recomposed from the resolution stack, so it
|
|
only ever writes into your project's own `.specify/templates/` scaffolds and command files that
|
|
are not managed by a preset/extension.
|
|
|
|
## When to use it
|
|
|
|
Install it **only** if your team treats the materialized templates and commands as
|
|
**reviewed, committed artifacts** — for example, if `plan-template.md`'s Constitution Check is
|
|
read in PRs as "here are our current gates" and is expected to track the constitution.
|
|
|
|
If you rely on the default runtime-resolution model, you do **not** need this preset: the live
|
|
constitution is already the single source of truth and there is nothing to sync.
|
|
|
|
## Caveats you take on
|
|
|
|
The preset resolution stack is how Spec Kit composes templates and commands going forward: they are
|
|
**layered, package-owned artifacts recomposed on demand**, not frozen files you edit in place.
|
|
Propagation is the opposite idea — it **materializes** guidance into files and freezes it. That
|
|
tension is the main thing to understand before installing:
|
|
|
|
- **Materialized copies can drift.** Anything propagated is a snapshot; if you amend the
|
|
constitution and do not re-run `/constitution`, the copies fall out of sync. The default runtime
|
|
model has no drift because it reads the live constitution every run.
|
|
|
|
- **Edits to composed files do not survive reconciliation.** If the rest of your SDD flow is
|
|
preset/extension-managed, the commands it materializes (`speckit.plan`, `speckit.specify`,
|
|
`speckit.tasks`, `speckit.analyze`, `speckit.implement`, …) are recomputed from the stack. Any
|
|
guidance propagated into them is clobbered the next time the stack reconciles — on
|
|
`specify integration use <key>` / `switch`, `specify integration upgrade`, or any preset/extension
|
|
install or remove. The same applies to templates owned by another preset/extension. This is why
|
|
the preset restricts itself to project-local files; propagation is reliable **only** for
|
|
artifacts you own outright.
|
|
|
|
- **A pre-filled Constitution Check can bias `/plan`.** Materializing concrete gates into
|
|
`plan-template.md` replaces the runtime pointer, so the first `/plan` pass may anchor on the
|
|
frozen text. Keep the pointer unless you specifically want committed gates.
|
|
|
|
**Bottom line:** this preset fits projects whose governed templates and commands are project-local
|
|
artifacts they review, with the rest of the SDD flow on the plain bundled core. If your
|
|
`plan`/`specify`/`tasks`/`analyze` commands or templates come from other presets or extensions,
|
|
prefer the default runtime-resolution model.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
# constitution-sync is a bundled preset — no download needed
|
|
specify preset add constitution-sync
|
|
```
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Test from local directory
|
|
specify preset add --dev ./presets/constitution-sync
|
|
|
|
# Verify the wrapped command resolves
|
|
specify preset resolve speckit.constitution
|
|
|
|
# Remove when done
|
|
specify preset remove constitution-sync
|
|
```
|
|
|
|
## Migrating back to the default
|
|
|
|
To move back to runtime resolution, reset each materialized `## Constitution Check` section in
|
|
`.specify/templates/plan-template.md` to the pointer:
|
|
|
|
```text
|
|
## Constitution Check
|
|
|
|
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
|
|
|
[Gates determined based on constitution file]
|
|
```
|
|
|
|
Then remove this preset. See `docs/upgrade.md` for details.
|
|
|
|
## License
|
|
|
|
MIT
|