Skip to content

Commit 16cfab7

Browse files
mnriemCopilot
andauthored
feat(presets): resolve constitution templates at command time (#3984)
* feat(presets): resolve constitutions at command time Gate install-time constitution materialization behind the constitution-sync preset while preserving one-time init seeding and authored-file safeguards. Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7dbce70f-80c6-4e14-a30d-78cb358bcb84 * fix(presets): emit composed template content Add a machine-readable preset resolve mode backed by PresetResolver.resolve_content and require the constitution command to consume it. Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7dbce70f-80c6-4e14-a30d-78cb358bcb84 * fix(presets): unify runtime template composition Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7dbce70f-80c6-4e14-a30d-78cb358bcb84 * fix(presets): secure runtime template resolution Align runtime resolution across script variants, validate registry path components, and honor canonical extension ordering and convention paths. Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * fix(presets): align runtime priority semantics Normalize and tie-break preset priorities consistently across script variants, and preserve template bytes when Python materializes generated files. Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * fix(presets): stop at effective template base Avoid parsing irrelevant lower layers once resolution reaches a replace base, and decode raw bytes so Python preserves source line endings. Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * fix(presets): align extension template resolution Support root-level extension templates across runtime resolvers, fail safely when Bash cannot parse an extension registry, and validate requested templates in every prerequisite output mode. Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * fix(presets): resolve dotted command identifiers Route safe dotted names through command resolution, correct traversal coverage, and make Windows CI text decoding explicit. Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Avoid orphan feature directories on template errors Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Align malformed preset manifest handling Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 3158e06f-95df-4e3a-843f-f159a35aa30c * Complete runtime resolver parity Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 3158e06f-95df-4e3a-843f-f159a35aa30c * Fail closed on resolver input errors Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 3158e06f-95df-4e3a-843f-f159a35aa30c * Force UTF-8 and full manifest validation Force UTF-8 decoding for registry and manifest reads in the Bash and PowerShell embedded-Python parsers so resolution no longer depends on the process locale, and validate every manifest template entry's required fields, type, and strategy consistent with the canonical PresetManifest. Assisted-by: GitHub Copilot (model: claude-opus-4.8, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 3158e06f-95df-4e3a-843f-f159a35aa30c * Fail closed on empty manifests and corrupt registries Reject manifests missing the provides/templates sections or declaring an empty template list in all three runtime resolvers, matching the canonical PresetManifest which treats those as invalid instead of silently degrading a composing layer to a convention `replace` lookup. Make a corrupt or unreadable extension registry fail closed in Bash, PowerShell, and Python instead of swallowing the error and treating every on-disk extension directory as unregistered-and-enabled, which could activate a disabled extension. Read the preset and extension registries as explicit UTF-8 in the PowerShell resolver so priority/enabled-state decoding no longer depends on the process code page under Windows PowerShell 5.1. Assisted-by: GitHub Copilot (model: claude-opus-4.8, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 3158e06f-95df-4e3a-843f-f159a35aa30c * fix(presets): fail closed when extension registry is not a regular file The Bash and Python resolvers used is_file()/`-f` to gate reading the extension `.registry`, which returns false for a directory or a broken symlink at that path. In those cases the resolvers treated the registry as absent and scanned every on-disk extension directory as unregistered and enabled — a fail-open path. Detect any filesystem entry at the registry path (including broken symlinks) and reject unless it is a readable regular file. PowerShell now rejects a non-leaf entry explicitly for parity. Adds directory- and broken-symlink parity regressions. Assisted-by: GitHub Copilot (model: claude-opus-4.8, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 3158e06f-95df-4e3a-843f-f159a35aa30c * fix(presets): fail closed on corrupt registry in canonical resolver and PowerShell Two remaining fail-open paths for an invalid extension registry: - The canonical PresetResolver enumerated extensions through ExtensionRegistry, whose _load() normalizes a corrupt or unreadable registry to an empty mapping. The directory scan then admitted every on-disk extension directory as unregistered-and-enabled, so a corrupt registry could still supply constitution content at init and through constitution-sync materialization. Add a non-invasive is_corrupt() probe (recovery behavior for install/enable/disable is unchanged) and raise from _get_all_extensions_by_priority() when the registry exists but is invalid. _load() now also recovers from OSError/UnicodeDecodeError so a directory or unreadable registry no longer crashes construction. - The PowerShell resolver gated the registry read with Test-Path, which returns false for a dangling symlink on Windows, letting a broken .registry symlink bypass the guard and enable every on-disk extension. Detect the entry via directory enumeration (which observes a broken symlink) and reject it unless it is a readable regular file. Adds canonical corrupt/directory-registry regressions and extends the broken-symlink parity test to PowerShell. Assisted-by: GitHub Copilot (model: claude-opus-4.8, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 3158e06f-95df-4e3a-843f-f159a35aa30c * fix(presets): detect dangling registry symlink in ExtensionRegistry.is_corrupt is_corrupt() gated on Path.exists(), which follows symlinks and returns False for a dangling .registry symlink — so the canonical PresetResolver treated it as an absent registry and fell back to scanning every on-disk extension directory as unregistered-and-enabled, reopening the fail-open path this guard closes. Detect lexical existence with os.path.lexists and require a regular file before parsing, so a broken symlink (or directory) is reported corrupt and resolution fails closed. Adds a canonical broken-symlink regression alongside the directory case. Assisted-by: GitHub Copilot (model: claude-opus-4.8, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 3158e06f-95df-4e3a-843f-f159a35aa30c --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7dbce70f-80c6-4e14-a30d-78cb358bcb84 Copilot-Session: 3158e06f-95df-4e3a-843f-f159a35aa30c
1 parent 1a60d1b commit 16cfab7

45 files changed

Lines changed: 2718 additions & 358 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

presets/ARCHITECTURE.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,19 @@ Content resolution functions for composition:
5959
- **Bash**: `resolve_template_content()` in `scripts/bash/common.sh` (templates only; command/script composition is handled by the Python resolver)
6060
- **PowerShell**: `Resolve-TemplateContent` in `scripts/powershell/common.ps1` (templates only; command/script composition is handled by the Python resolver)
6161

62+
### Constitution lifecycle
63+
64+
Initialization resolves `constitution-template` through the full stack and seeds
65+
`.specify/memory/constitution.md` once. Existing files are preserved byte-for-byte. On subsequent
66+
`/constitution` runs, the command resolves the current composed template at runtime and uses the live
67+
constitution as the source of project-specific values and amendments.
68+
69+
Preset installation, removal, enablement, disablement, and priority changes do not materialize
70+
`constitution-template` by default. When the enabled preset registry contains `constitution-sync`,
71+
those operations may reconcile the live file, but only if its provenance hash proves it is still
72+
generated content. Missing files may be seeded when the preset is installed; authored or edited
73+
constitutions are never overwritten.
74+
6275
## Command Registration
6376

6477
When a preset is installed with `type: "command"` entries, the `PresetManager` registers them into all detected agent directories using the shared `CommandRegistrar` from `src/specify_cli/agents.py`.

presets/README.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,16 @@ If no preset is installed, core templates are used — exactly the same behavior
1515

1616
Template resolution happens **at runtime** — although preset files are copied into `.specify/presets/<id>/` during installation, Spec Kit walks the resolution stack on every template lookup rather than merging templates into a single location.
1717

18+
`constitution-template` follows the same runtime model. Project initialization seeds
19+
`.specify/memory/constitution.md` once so downstream commands always have a constitution to read.
20+
After that, installing, removing, enabling, disabling, or reprioritizing presets does not rewrite the
21+
live constitution. Each `/constitution` run resolves the current composed `constitution-template`,
22+
then applies existing project values and amendments to that scaffold.
23+
24+
Teams that intentionally want preset stack changes to refresh an unchanged generated constitution can
25+
install the bundled `constitution-sync` preset. It restores guarded install-time materialization in
26+
addition to its command-time propagation behavior; authored constitutions remain protected.
27+
1828
For detailed resolution and command registration flows, see [ARCHITECTURE.md](ARCHITECTURE.md).
1929

2030
## Command Overrides

presets/catalog.json

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"schema_version": "1.0",
3-
"updated_at": "2026-04-24T00:00:00Z",
3+
"updated_at": "2026-08-04T00:00:00Z",
44
"catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/presets/catalog.json",
55
"presets": {
66
"lean": {
@@ -30,7 +30,7 @@
3030
"name": "Constitution Template Sync",
3131
"id": "constitution-sync",
3232
"version": "1.0.0",
33-
"description": "Opt-in: restores /constitution propagation of amended guidance into plan/spec/tasks templates and installed command files, for teams that treat materialized templates as reviewed artifacts.",
33+
"description": "Opt-in: restores guarded install-time constitution seeding and /constitution propagation for teams that treat materialized templates as reviewed artifacts.",
3434
"author": "github",
3535
"repository": "https://github.com/github/spec-kit",
3636
"license": "MIT",

presets/constitution-sync/README.md

Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,15 @@
11
# Constitution Template Sync
22

3-
An **opt-in** preset that restores `/constitution`'s ability to propagate amended guidance into your
4-
project's own templates and command files. After you update the constitution, it aligns
5-
`plan-template.md`, `spec-template.md`, `tasks-template.md`, project-local command files, and
3+
An **opt-in** preset that restores materialized constitution workflows. It refreshes an unchanged
4+
generated `.specify/memory/constitution.md` when constitution-providing presets are installed,
5+
removed, enabled, disabled, or reprioritized. After `/constitution` updates the live file, it also
6+
aligns `plan-template.md`, `spec-template.md`, `tasks-template.md`, project-local command files, and
67
guidance docs so they reflect the current principles.
78

89
This propagation used to be built into `/constitution`; it was dropped when the command moved to the
9-
preset model. Installing this preset opts you back into it: you get the guidance materialized into
10-
reviewed, committed artifacts instead of relying on runtime resolution alone.
10+
preset model. Installing this preset opts you back into materialization: preset stack changes refresh
11+
the generated constitution, and `/constitution` propagates its guidance into reviewed, committed
12+
artifacts instead of relying on runtime resolution alone.
1113

1214
> **What you're opting into.** Propagation was removed deliberately — it duplicates the constitution
1315
> as the source of truth and can fight the composition stack (materialized edits get shadowed or
@@ -28,7 +30,12 @@ versioned preset a core team maintains.
2830

2931
## What it does
3032

31-
Ships a single `wrap`-strategy override of `speckit.constitution`. It composes on top of the
33+
Its presence enables core's guarded install-time constitution reconciliation. Installing the preset
34+
materializes the currently resolved `constitution-template`; later stack changes re-materialize it
35+
only while the live file still matches its recorded generated-content hash. Human edits disable
36+
automatic replacement.
37+
38+
It also ships a single `wrap`-strategy override of `speckit.constitution`. It composes on top of the
3239
current core command (via `{CORE_TEMPLATE}`), so it stays forward-compatible with core changes, and
3340
appends a propagation pass that, after the constitution is written:
3441

@@ -43,6 +50,8 @@ appends a propagation pass that, after the constitution is written:
4350
- It does **not** disable runtime resolution. `plan`, `tasks`, and `analyze` still read the live
4451
constitution every run; this preset adds materialized copies on top — it does not replace the
4552
source of truth.
53+
- It does **not** overwrite an authored or edited constitution. Install-time reconciliation only
54+
replaces content whose provenance proves it is an unchanged generated file.
4655
- It does **not** edit versioned, package-owned files — templates or command files provided or
4756
wrapped by another preset or extension. Those are recomposed from the resolution stack, so it
4857
only ever writes into your project's own `.specify/templates/` scaffolds and command files that

presets/constitution-sync/preset.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ preset:
44
id: "constitution-sync"
55
name: "Constitution Template Sync"
66
version: "1.0.0"
7-
description: "Opt-in: restores /constitution propagation of amended guidance into plan/spec/tasks templates and installed command files, for teams that treat materialized templates as reviewed artifacts."
7+
description: "Opt-in: restores guarded install-time constitution seeding and /constitution propagation for teams that treat materialized templates as reviewed artifacts."
88
author: "github"
99
repository: "https://github.com/github/spec-kit"
1010
license: "MIT"

scripts/bash/check-prerequisites.sh

Lines changed: 43 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
# --require-tasks Require tasks.md to exist (for implementation phase)
1313
# --include-tasks Include tasks.md in AVAILABLE_DOCS list
1414
# --paths-only Only output path variables (no validation)
15+
# --template NAME Include composed template content in JSON output
1516
# --help, -h Show help message
1617
#
1718
# OUTPUTS:
@@ -26,9 +27,10 @@ JSON_MODE=false
2627
REQUIRE_TASKS=false
2728
INCLUDE_TASKS=false
2829
PATHS_ONLY=false
30+
TEMPLATE_NAME=""
2931

30-
for arg in "$@"; do
31-
case "$arg" in
32+
while [[ $# -gt 0 ]]; do
33+
case "$1" in
3234
--json)
3335
JSON_MODE=true
3436
;;
@@ -41,6 +43,14 @@ for arg in "$@"; do
4143
--paths-only)
4244
PATHS_ONLY=true
4345
;;
46+
--template)
47+
shift
48+
if [[ $# -eq 0 ]]; then
49+
echo "ERROR: --template requires a template name" >&2
50+
exit 1
51+
fi
52+
TEMPLATE_NAME="$1"
53+
;;
4454
--help|-h)
4555
cat << 'EOF'
4656
Usage: check-prerequisites.sh [OPTIONS]
@@ -52,6 +62,7 @@ OPTIONS:
5262
--require-tasks Require tasks.md to exist (for implementation phase)
5363
--include-tasks Include tasks.md in AVAILABLE_DOCS list
5464
--paths-only Only output path variables (no prerequisite validation)
65+
--template NAME Include composed template content in JSON output
5566
--help, -h Show this help message
5667
5768
EXAMPLES:
@@ -68,10 +79,11 @@ EOF
6879
exit 0
6980
;;
7081
*)
71-
echo "ERROR: Unknown option '$arg'. Use --help for usage information." >&2
82+
echo "ERROR: Unknown option '$1'. Use --help for usage information." >&2
7283
exit 1
7384
;;
7485
esac
86+
shift
7587
done
7688

7789
# Source common functions
@@ -156,6 +168,16 @@ if $INCLUDE_TASKS && [[ -f "$TASKS" ]]; then
156168
docs+=("tasks.md")
157169
fi
158170

171+
TEMPLATE_CONTENT=""
172+
if [[ -n "$TEMPLATE_NAME" ]]; then
173+
if TEMPLATE_CONTENT=$(resolve_template_content "$TEMPLATE_NAME" "$REPO_ROOT"; status=$?; printf x; exit "$status"); then
174+
TEMPLATE_CONTENT="${TEMPLATE_CONTENT%x}"
175+
else
176+
echo "ERROR: Could not resolve required $TEMPLATE_NAME from the template override stack for $REPO_ROOT" >&2
177+
exit 1
178+
fi
179+
fi
180+
159181
# Output results
160182
if $JSON_MODE; then
161183
# Build JSON array of documents
@@ -165,18 +187,31 @@ if $JSON_MODE; then
165187
else
166188
json_docs=$(printf '%s\n' "${docs[@]}" | jq -R . | jq -s .)
167189
fi
168-
jq -cn \
169-
--arg feature_dir "$FEATURE_DIR" \
170-
--argjson docs "$json_docs" \
171-
'{FEATURE_DIR:$feature_dir,AVAILABLE_DOCS:$docs}'
190+
if [[ -n "$TEMPLATE_NAME" ]]; then
191+
jq -cn \
192+
--arg feature_dir "$FEATURE_DIR" \
193+
--argjson docs "$json_docs" \
194+
--arg template_content "$TEMPLATE_CONTENT" \
195+
'{FEATURE_DIR:$feature_dir,AVAILABLE_DOCS:$docs,TEMPLATE_CONTENT:$template_content}'
196+
else
197+
jq -cn \
198+
--arg feature_dir "$FEATURE_DIR" \
199+
--argjson docs "$json_docs" \
200+
'{FEATURE_DIR:$feature_dir,AVAILABLE_DOCS:$docs}'
201+
fi
172202
else
173203
if [[ ${#docs[@]} -eq 0 ]]; then
174204
json_docs="[]"
175205
else
176206
json_docs=$(for d in "${docs[@]}"; do printf '"%s",' "$(json_escape "$d")"; done)
177207
json_docs="[${json_docs%,}]"
178208
fi
179-
printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$(json_escape "$FEATURE_DIR")" "$json_docs"
209+
if [[ -n "$TEMPLATE_NAME" ]]; then
210+
printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s,"TEMPLATE_CONTENT":"%s"}\n' \
211+
"$(json_escape "$FEATURE_DIR")" "$json_docs" "$(json_escape "$TEMPLATE_CONTENT")"
212+
else
213+
printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$(json_escape "$FEATURE_DIR")" "$json_docs"
214+
fi
180215
fi
181216
else
182217
# Text output

0 commit comments

Comments
 (0)