fix(presets): seed constitution from preset constitution-template (#3272) by BenBtg · Pull Request #3276 · github/spec-kit

BenBtg · 2026-06-30T18:54:47Z

Summary

Fixes #3272. Preset-provided constitution-template entries are now materialized to .specify/memory/constitution.md through the same resolver priority stack used by other templates: project overrides -> installed presets -> extensions -> core.

Initialization seeds the constitution after preset installation, allowing specify init --preset to select the preset-provided template while retaining the core fallback.

Changes

Resolver-aware initialization - ensure_constitution_from_template materializes the resolved constitution-template after preset installation and preserves an existing constitution.
Preset lifecycle reconciliation - installing a directory preset, or a ZIP preset that delegates to it, materializes a declared constitution-template. Installing a higher-priority preset or removing the winning preset rematerializes an unchanged generated constitution from the new winning layer.
Composing strategies - replace copies the winning template bytes verbatim; prepend, append, and wrap use PresetResolver.resolve_content() to materialize the composed result.
Atomic safe writes - constitution and provenance files use checked atomic shared-infrastructure writes. Symlinked or escaping destinations are rejected, and post-install or post-removal materialization failures warn without falsely reporting the preset lifecycle operation as failed.
Tests and inventories - added coverage for resolver-aware initialization, composition, priority changes on install and removal, provenance, authored-file preservation, legacy migration, symlink rejection, and nonfatal failure handling. Integration inventories include the generated provenance sidecar.

Key guard

Each generated constitution receives .specify/memory/.constitution-template.json, recording its SHA-256 and winning source. A later preset installation or removal may overwrite the live constitution only when its current bytes still match the recorded SHA-256.

For legacy projects without a provenance sidecar, overwrite is permitted only when the live file exactly matches a known core constitution-template. Authored or edited constitutions are preserved, including files that merely contain [PROJECT_NAME] or other placeholder text.

Validation

ruff check src/ tests/test_presets.py
pytest tests/test_presets.py -q - 344 passed
pytest tests/ -q -x - 4046 passed, 4 skipped

This PR was authored autonomously by GitHub Copilot. Each commit carries an Assisted-by: trailer.

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

gglachant · 2026-07-01T08:41:26Z

+1 — we hit this independently. We maintain a spec-kit harness for a team with a fixed, ratified constitution authored upstream in a canonical repo and installed verbatim downstream. /speckit.constitution treating .specify/memory/constitution.md as a template to (re-)author from placeholders is exactly the hazard #3272 names: for us an AI-authored variant is a governance violation, not a convenience.

We read #3276's diff against our use case, and it handles our edge cases correctly:

Deferred-value markers are preserved. Our authored constitution carries a few intentional spec-kit-style TODO(FIELD) deferred values (e.g. TODO(RATIFICATION_DATE)) that resolve at a later milestone. Because _constitution_is_placeholder keys on the stock template's specific sentinels ([PROJECT_NAME], [PRINCIPLE_1_NAME]) rather than any generic TODO( / [...], such a constitution is correctly classified authored and preserved. 👍 (That was our one worry from the summary; the diff resolves it.)
Byte-faithful install. shutil.copy2(resolved, memory_constitution) materializes the preset's replace template unchanged — exactly what a ratified constitution needs (no reformatting, token-fill, or version recompute).

One small maintainability suggestion: _CONSTITUTION_PLACEHOLDER_TOKENS is a fixed pair — worth a test pinning it to the actual [ALL_CAPS] tokens in the stock constitution-template.md, so the guard can't silently drift out of sync if that template's placeholders ever change.

Our current stopgap is cp canonical → diff (confirm byte-identical) → run the command report-only plus disabling the auto-authoring path; #3276's preset-aware replace path would let us ship the constitution as a preset template and retire that entirely. Thanks for picking this up.

(Disclosure, per CONTRIBUTING: this comment was drafted with the assistance of Claude Code (an AI coding agent) and reviewed by a human before posting.)

Copilot

Review details

Files reviewed: 3/3 changed files
Comments generated: 2
Review effort level: Low

Copilot

Review details

Files reviewed: 3/3 changed files
Comments generated: 0 new
Review effort level: Low

BenBtg · 2026-07-01T18:30:45Z

Addressed review feedback in f954e30.\n\n- Fixed constitution seeding to handle composing strategies (//) in both paths ( and ): we now materialize composed content via whenever the winning layer is non-.\n- Added regression tests that verify wrap composition is materialized (no unresolved ) in both seeding paths.\n- Added a drift-guard test that pins to placeholders present in the core , per gglachant’s maintainability suggestion.\n\nPosted on behalf of @BenBtg by GitHub Copilot (model: gpt-5.3-codex).

BenBtg · 2026-07-01T18:30:52Z

Correction to my previous comment (shell quoting ate formatting). Addressed review feedback in f954e30.

Fixed constitution seeding to handle composing strategies (prepend/append/wrap) in both paths: ensure_constitution_from_template and PresetManager._seed_constitution_from_preset now materialize composed content via PresetResolver.resolve_content() whenever the winning layer is non-replace.
Added regression tests that verify wrap composition is materialized with no unresolved {CORE_TEMPLATE} in both seeding paths.
Added a drift-guard test that pins _CONSTITUTION_PLACEHOLDER_TOKENS to placeholders present in the core templates/constitution-template.md, per gglachant’s maintainability suggestion.

Posted on behalf of @BenBtg by GitHub Copilot (model: gpt-5.3-codex).

Copilot

Review details

Files reviewed: 3/3 changed files
Comments generated: 3
Review effort level: Low

BenBtg · 2026-07-01T18:53:34Z

Addressed the latest Copilot feedback in aa09272.

Moved resolver/layer collection behind the existing-memory fast path in ensure_constitution_from_template, so we avoid unnecessary I/O when memory already exists.
Updated tracker output to distinguish copied vs composed constitution materialization.
Deduplicated constitution materialization logic used by both init seeding and preset install re-seeding into a shared helper (_materialize_constitution_template) to keep behavior in sync.

Posted on behalf of @BenBtg by GitHub Copilot (model: gpt-5.3-codex).

) The constitution is the only template materialized to a live file (.specify/memory/constitution.md) rather than resolved on demand, yet ensure_constitution_from_template hardcoded a copy from the core template and ignored PresetResolver. Combined with init seeding the constitution before preset installation, a preset's constitution-template (e.g. strategy: replace with a ratified constitution) could never go live. Changes: - ensure_constitution_from_template now resolves constitution-template through PresetResolver, so a preset/override/extension wins and core is the fallback. - init seeds the constitution after preset installation so init --preset uses the resolved stack. - install_from_directory re-seeds memory/constitution.md from the resolved preset template, guarded to only act when the memory file is missing or still contains generic placeholder tokens — authored constitutions are never overwritten. Covers preset add and install_from_zip. - Tests for preset seeding, placeholder re-seed, authored-constitution preservation, override resolution, and resolver-aware init seeding. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Take on review feedback from Copilot and gglachant: - constitution seeding previously copied the top layer file path verbatim even when the winning layer used a composing strategy (prepend/append/wrap), which could leave {CORE_TEMPLATE} unresolved. - both seeding paths now inspect resolver layers and only copy verbatim for replace; non-replace strategies materialize composed content via PresetResolver.resolve_content(). - add regression tests for wrap strategy composition in both PresetManager seeding and ensure_constitution_from_template. - add a drift-guard test pinning _CONSTITUTION_PLACEHOLDER_TOKENS to the placeholders in templates/constitution-template.md. Assisted-by: GitHub Copilot (model: GPT-5.3-Codex, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Address latest Copilot feedback on the constitution seeding path: - moved resolver/layer I/O behind the existing-memory fast path in init - corrected tracker output for composed materialization - deduplicated materialization logic shared by init and preset install seeding into presets._materialize_constitution_template() Behavior is unchanged for replace strategies (copy verbatim) and remains composed for prepend/append/wrap via resolve_content(). Assisted-by: GitHub Copilot (model: GPT-5.3-Codex, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

The constitution materialization refactor removed the module import, but init still uses shutil.rmtree when cleaning up a failed new-project initialization. Restore the import so the required ruff check passes. Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

BenBtg · 2026-07-13T15:51:49Z

Resynced this PR with current main and marked it ready for review.

Rebased cleanly with no conflicts; branch is now 0 commits behind main.
Restored the required shutil import in init.py (commit e03fb69), fixing the prior ruff failure.
Local validation: ruff passed; 4,040 tests passed and 4 skipped.
All GitHub checks are now passing across lint, CodeQL, and the Python 3.13/3.14 OS matrix.

Posted on behalf of @BenBtg by GitHub Copilot (model: gpt-5.6-sol).

Copilot

Review details

Files reviewed: 3/3 changed files
Comments generated: 4
Review effort level: Medium

Address the outstanding review batch for preset constitution seeding: - use checked atomic writes and reject symlinked memory paths - replace placeholder heuristics with hash/source provenance - rematerialize unchanged generated constitutions by resolver priority - preserve authored or edited constitutions, including placeholder mentions - warn non-fatally when post-install materialization cannot complete - retain exact core-template comparison for legacy projects without provenance Add focused provenance, priority, symlink, and failure-path coverage, and update integration inventories for the generated provenance sidecar. Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 1b2c095d-b45c-4d52-8d56-bd6121d96ab6

BenBtg · 2026-07-13T16:57:07Z

Addressed the outstanding review batch in commit 116ab2c.

Routed constitution and provenance writes through checked atomic helpers and rejected symlinked parents and destinations.
Replaced placeholder substring heuristics with hash/source provenance, retaining exact core-template comparison for legacy projects.
Made unchanged generated constitutions follow resolver priority while preserving edited or authored files.
Made expected post-install materialization failures non-fatal warnings.
Confirmed the earlier composition, fast-path, tracker, and shared-helper feedback remains addressed.

Validation: ruff passed; 343 focused preset tests passed; full suite passed with 4,045 tests and 4 skips.

Posted on behalf of @BenBtg by GitHub Copilot (model: gpt-5.6-sol).

Copilot

Review details

Files reviewed: 10/10 changed files
Comments generated: 2
Review effort level: Medium

When the removed preset supplied constitution-template, rematerialize the winning remaining resolver layer only if provenance proves the live file is still generated and unchanged. Preserve edited constitutions and report post-removal reconciliation failures as non-fatal warnings. Add coverage for restoring the core layer, falling back from a removed higher-priority preset, and preserving edited generated content. Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 1b2c095d-b45c-4d52-8d56-bd6121d96ab6

BenBtg · 2026-07-14T10:58:37Z

Addressed the latest review round in commit 8685bcc.

Preset removal now reconciles unchanged generated constitutions from the winning remaining resolver layer.
Edited or authored constitutions remain preserved through provenance verification.
Updated the PR body to describe SHA-256 provenance, exact legacy core-template comparison, safe writes, composition, and install/removal reconciliation.

Validation: ruff passed; 344 focused preset tests passed; full suite passed with 4,046 tests and 4 skips.

Posted on behalf of @BenBtg by GitHub Copilot (model: gpt-5.6-sol).

Copilot

Review details

Files reviewed: 10/10 changed files
Comments generated: 1
Review effort level: Medium

+    # Older projects have no provenance sidecar. Only the exact known core
+    # template is safe to treat as generated; placeholder substrings are not.
+    for layer in layers:
+        if layer["source"].startswith("core") and layer["path"].read_bytes() == content:


Copilot

Review details

Files reviewed: 10/10 changed files
Comments generated: 2
Review effort level: Medium

+    # Older projects have no provenance sidecar. Only the exact known core
+    # template is safe to treat as generated; placeholder substrings are not.
+    for layer in layers:
+        if layer["source"].startswith("core") and layer["path"].read_bytes() == content:
+            return True


+                    if (
+                        tmpl.get("type") == "template"
+                        and tmpl.get("name") == "constitution-template"
+                    ):
+                        removed_constitution = True


Copilot AI review requested due to automatic review settings June 30, 2026 18:54

Copilot started reviewing on behalf of BenBtg June 30, 2026 18:55 View session

Copilot AI reviewed Jun 30, 2026

BenBtg requested a review from Copilot July 1, 2026 16:18

Copilot started reviewing on behalf of BenBtg July 1, 2026 16:18 View session

Copilot AI reviewed Jul 1, 2026

View reviewed changes

Comment thread src/specify_cli/commands/init.py Outdated

Comment thread src/specify_cli/presets/__init__.py Outdated

BenBtg requested a review from Copilot July 1, 2026 18:24

Copilot started reviewing on behalf of BenBtg July 1, 2026 18:25 View session

Copilot AI reviewed Jul 1, 2026

View reviewed changes

BenBtg requested a review from Copilot July 1, 2026 18:41

Copilot started reviewing on behalf of BenBtg July 1, 2026 18:42 View session

Copilot AI reviewed Jul 1, 2026

View reviewed changes

Comment thread src/specify_cli/commands/init.py

Comment thread src/specify_cli/commands/init.py Outdated

Comment thread src/specify_cli/presets/__init__.py Outdated

BenBtg and others added 4 commits July 13, 2026 16:41

Copilot AI review requested due to automatic review settings July 13, 2026 15:46

BenBtg force-pushed the benbtg-fix-3272-preset-constitution-template-se branch from aa09272 to e03fb69 Compare July 13, 2026 15:46

Copilot started reviewing on behalf of BenBtg July 13, 2026 15:46 View session

BenBtg marked this pull request as ready for review July 13, 2026 15:51

BenBtg requested a review from mnriem as a code owner July 13, 2026 15:51

Copilot AI reviewed Jul 13, 2026

View reviewed changes

Comment thread src/specify_cli/presets/__init__.py Outdated

Comment thread src/specify_cli/presets/__init__.py Outdated

Comment thread src/specify_cli/presets/__init__.py Outdated

Comment thread src/specify_cli/presets/__init__.py Outdated

Copilot AI review requested due to automatic review settings July 13, 2026 16:56

Copilot started reviewing on behalf of BenBtg July 13, 2026 16:56 View session

Copilot AI reviewed Jul 13, 2026

View reviewed changes

Comment thread src/specify_cli/presets/__init__.py

Comment thread src/specify_cli/presets/__init__.py

Copilot AI review requested due to automatic review settings July 14, 2026 10:58

Copilot started reviewing on behalf of BenBtg July 14, 2026 10:58 View session

Copilot AI reviewed Jul 14, 2026

View reviewed changes

BenBtg requested a review from Copilot July 14, 2026 11:16

Copilot started reviewing on behalf of BenBtg July 14, 2026 11:16 View session

Copilot AI reviewed Jul 14, 2026

View reviewed changes

Uh oh!

Conversation

BenBtg commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Key guard

Validation

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

gglachant commented Jul 1, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Review details

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Review details

Uh oh!

BenBtg commented Jul 1, 2026

Uh oh!

BenBtg commented Jul 1, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Review details

Uh oh!

Uh oh!

Uh oh!

Uh oh!

BenBtg commented Jul 1, 2026

Uh oh!

BenBtg commented Jul 13, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Review details

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

BenBtg commented Jul 13, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Review details

Uh oh!

Uh oh!

Uh oh!

BenBtg commented Jul 14, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Review details

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Review details

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

BenBtg commented Jun 30, 2026 •

edited

Loading