π« Toolkit to help you get started with SDD or any other process!
feat(presets): Composition strategies (prepend, append, wrap) for templates, commands, and scripts (#2133)
Copilota067d4c2e3a5
diff --git a/presets/ARCHITECTURE.md b/presets/ARCHITECTURE.mdindex d0e654781..3a119cbd5 100644--- a/presets/ARCHITECTURE.md+++ b/presets/ARCHITECTURE.md@@ -41,6 +41,24 @@ The resolution is implemented three times to ensure consistency:- **Bash**: `resolve_template()` in `scripts/bash/common.sh`- **PowerShell**: `Resolve-Template` in `scripts/powershell/common.ps1`+### Composition Strategies++Templates, commands, and scripts support a `strategy` field that controls how a preset's content is combined with lower-priority content instead of fully replacing it:++| Strategy | Description | Templates | Commands | Scripts |+|----------|-------------|-----------|----------|---------|+| `replace` (default) | Fully replaces lower-priority content | β | β | β |+| `prepend` | Places content before lower-priority content (separated by a blank line) | β | β | β |+| `append` | Places content after lower-priority content (separated by a blank line) | β | β | β |+| `wrap` | Content contains `{CORE_TEMPLATE}` (templates/commands) or `$CORE_SCRIPT` (scripts) placeholder replaced with lower-priority content | β | β | β |++Composition is recursive β multiple composing presets chain. The `PresetResolver.resolve_content()` method walks the full priority stack bottom-up and applies each layer's strategy.++Content resolution functions for composition:+- **Python**: `PresetResolver.resolve_content()` in `src/specify_cli/presets.py` (templates, commands, and scripts)+- **Bash**: `resolve_template_content()` in `scripts/bash/common.sh` (templates only; command/script composition is handled by the Python resolver)+- **PowerShell**: `Resolve-TemplateContent` in `scripts/powershell/common.ps1` (templates only; command/script composition is handled by the Python resolver)+## Command RegistrationWhen 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`.diff --git a/presets/README.md b/presets/README.mdindex 72751b4bf..7d7b9ae8a 100644--- a/presets/README.md+++ b/presets/README.md@@ -61,7 +61,37 @@ specify preset add healthcare-compliance --priority 5 # overrides enterprise-saspecify preset add pm-workflow --priority 1 # overrides everything```-Presets **override**, they don't merge. If two presets both provide `spec-template`, the one with the lowest priority number wins entirely.+Presets **override by default**, they don't merge. If two presets both provide `spec-template` with the default `replace` strategy, the one with the lowest priority number wins entirely. However, presets can use **composition strategies** to augment rather than replace content.++### Composition Strategies++Presets can declare a `strategy` per template to control how content is combined. The `name` field identifies which template to compose with in the priority stack, while `file` points to the actual content file (which can differ from the convention path `templates/<name>.md`):++```yaml+provides:+ templates:+ - type: "template"+ name: "spec-template"+ file: "templates/spec-addendum.md"+ strategy: "append" # adds content after the core template+```++| Strategy | Description |+|----------|-------------|+| `replace` (default) | Fully replaces the lower-priority template |+| `prepend` | Places content **before** the resolved lower-priority template, separated by a blank line |+| `append` | Places content **after** the resolved lower-priority template, separated by a blank line |+| `wrap` | Content contains `{CORE_TEMPLATE}` placeholder (or `$CORE_SCRIPT` for scripts) replaced with the lower-priority content |++**Supported combinations:**++| Type | `replace` | `prepend` | `append` | `wrap` |+|------|-----------|-----------|----------|--------|+| **template** | β (default) | β | β | β |+| **command** | β (default) | β | β | β |+| **script** | β (default) | β | β | β |++Multiple composing presets chain recursively. For example, a security preset with `prepend` and a compliance preset with `append` will produce: security header + core content + compliance footer.## Catalog Management@@ -108,13 +138,5 @@ See [scaffold/](scaffold/) for a scaffold you can copy to create your own presetThe following enhancements are under consideration for future releases:-- **Composition strategies** β Allow presets to declare a `strategy` per template instead of the default `replace`:-- | Type | `replace` | `prepend` | `append` | `wrap` |- |------|-----------|-----------|----------|--------|- | **template** | β (default) | β | β | β |- | **command** | β (default) | β | β | β |- | **script** | β (default) | β | β | β |-- For artifacts and commands (which are LLM directives), `wrap` injects preset content before and after the core template using a `{CORE_TEMPLATE}` placeholder (implemented). For scripts, `wrap` would run custom logic before/after the core script via a `$CORE_SCRIPT` variable (not yet implemented).-- **Script overrides** β Enable presets to provide alternative versions of core scripts (e.g. `create-new-feature.sh`) for workflow customization. A `strategy: "wrap"` option could allow presets to run custom logic before/after the core script without fully replacing it.+- **Structural merge strategies** β Parsing Markdown sections for per-section granularity (e.g., "replace only ## Security").+- **Conflict detection** β `specify preset lint` / `specify preset doctor` for detecting composition conflicts.diff --git a/presets/scaffold/preset.yml b/presets/scaffold/preset.ymlindex 975a92a41..65111ba9f 100644--- a/presets/scaffold/preset.yml+++ b/presets/scaffold/preset.yml@@ -32,6 +32,15 @@ provides:templates:# CUSTOMIZE: Define your template overrides# Templates are document scaffolds (spec-template.md, plan-template.md, etc.)+ #+ # Strategy options (optional, defaults to "replace"):+ # replace - Fully replaces the lower-priority template (default)+ # prepend - Places this content BEFORE the lower-priority template+ # append - Places this content AFTER the lower-priority template+ # wrap - Uses {CORE_TEMPLATE} placeholder (templates/commands) or+ # $CORE_SCRIPT placeholder (scripts), replaced with lower-priority content+ #+ # Note: Scripts only support "replace" and "wrap" strategies.- type: "template"name: "spec-template"file: "templates/spec-template.md"@@ -45,6 +54,26 @@ provides:# description: "Custom plan template"# replaces: "plan-template"+ # COMPOSITION EXAMPLES:+ # The `file` field points to the content file (can differ from the+ # convention path `templates/<name>.md`). The `name` field identifies+ # which template to compose with in the priority stack.+ #+ # Append additional sections to an existing template:+ # - type: "template"+ # name: "spec-template"+ # file: "templates/spec-addendum.md"+ # description: "Add compliance section to spec template"+ # strategy: "append"+ #+ # Wrap a command with preamble/sign-off:+ # - type: "command"+ # name: "speckit.specify"+ # file: "commands/specify-wrapper.md"+ # description: "Wrap specify command with compliance checks"+ # strategy: "wrap"+ # # In the wrapper file, use {CORE_TEMPLATE} where the original content goes+# OVERRIDE EXTENSION TEMPLATES:# Presets sit above extensions in the resolution stack, so you can# override templates provided by any installed extension.diff --git a/scripts/bash/common.sh b/scripts/bash/common.shindex b41d17dec..cad10bdb3 100644--- a/scripts/bash/common.sh+++ b/scripts/bash/common.sh@@ -320,8 +320,9 @@ try:with open(os.environ['SPECKIT_REGISTRY']) as f:data = json.load(f)presets = data.get('presets', {})- for pid, meta in sorted(presets.items(), key=lambda x: x[1].get('priority', 10)):- print(pid)+ for pid, meta in sorted(presets.items(), key=lambda x: x[1].get('priority', 10) if isinstance(x[1], dict) else 10):+ if isinstance(meta, dict) and meta.get('enabled', True) is not False:+ print(pid)except Exception:sys.exit(1)" 2>/dev/null); then@@ -373,3 +374,225 @@ except Exception:return 1}+# Resolve a template name to composed content using composition strategies.+# Reads strategy metadata from preset manifests and composes content+# from multiple layers using prepend, append, or wrap strategies.+#+# Usage: CONTENT=$(resolve_template_content "template-name" "$REPO_ROOT")+# Returns composed content string on stdout; exit code 1 if not found.+resolve_template_content() {+ local template_name="$1"+ local repo_root="$2"+ local base="$repo_root/.specify/templates"++ # Collect all layers (highest priority first)+ local -a layer_paths=()+ local -a layer_strategies=()++ # Priority 1: Project overrides (always "replace")+ local override="$base/overrides/${template_name}.md"+ if [ -f "$override" ]; then+ layer_paths+=("$override")+ layer_strategies+=("replace")+ fi++ # Priority 2: Installed presets (sorted by priority from .registry)+ local presets_dir="$repo_root/.specify/presets"+ if [ -d "$presets_dir" ]; then+ local registry_file="$presets_dir/.registry"+ local sorted_presets=""+ if [ -f "$registry_file" ] && command -v python3 >/dev/null 2>&1; then+ if sorted_presets=$(SPECKIT_REGISTRY="$registry_file" python3 -c "+import json, sys, os+try:+ with open(os.environ['SPECKIT_REGISTRY']) as f:+ data = json.load(f)+ presets = data.get('presets', {})+ for pid, meta in sorted(presets.items(), key=lambda x: x[1].get('priority', 10) if isinstance(x[1], dict) else 10):+ if isinstance(meta, dict) and meta.get('enabled', True) is not False:+ print(pid)+except Exception:+ sys.exit(1)+" 2>/dev/null); then+ if [ -n "$sorted_presets" ]; then+ local yaml_warned=false+ while IFS= read -r preset_id; do+ # Read strategy and file path from preset manifest+ local strategy="replace"+ local manifest_file=""+ local manifest="$presets_dir/$preset_id/preset.yml"+ if [ -f "$manifest" ] && command -v python3 >/dev/null 2>&1; then+ # Requires PyYAML; falls back to replace/convention if unavailable+ local result+ local py_stderr+ py_stderr=$(mktemp)+ result=$(SPECKIT_MANIFEST="$manifest" SPECKIT_TMPL="$template_name" python3 -c "+import sys, os+try:+ import yaml+except ImportError:+ print('yaml_missing', file=sys.stderr)+ print('replace\t')+ sys.exit(0)+try:+ with open(os.environ['SPECKIT_MANIFEST']) as f:+ data = yaml.safe_load(f)+ for t in data.get('provides', {}).get('templates', []):+ if t.get('name') == os.environ['SPECKIT_TMPL'] and t.get('type', 'template') == 'template':+ print(t.get('strategy', 'replace') + '\t' + t.get('file', ''))+ sys.exit(0)+ print('replace\t')+except Exception:+ print('replace\t')+" 2>"$py_stderr")+ local parse_status=$?+ if [ $parse_status -eq 0 ] && [ -n "$result" ]; then+ IFS=$'\t' read -r strategy manifest_file <<< "$result"+ strategy=$(printf '%s' "$strategy" | tr '[:upper:]' '[:lower:]')+ fi+ if [ "$yaml_warned" = false ] && grep -q 'yaml_missing' "$py_stderr" 2>/dev/null; then+ echo "Warning: PyYAML not available; composition strategies may be ignored" >&2+ yaml_warned=true+ fi+ rm -f "$py_stderr"+ fi+ # Try manifest file path first, then convention path+ local candidate=""+ if [ -n "$manifest_file" ]; then+ # Reject absolute paths and parent traversal+ case "$manifest_file" in+ /*|*../*|../*) manifest_file="" ;;+ esac+ fi+ if [ -n "$manifest_file" ]; then+ local mf="$presets_dir/$preset_id/$manifest_file"+ [ -f "$mf" ] && candidate="$mf"+ fi+ if [ -z "$candidate" ]; then+ local cf="$presets_dir/$preset_id/templates/${template_name}.md"+ [ -f "$cf" ] && candidate="$cf"+ fi+ if [ -n "$candidate" ]; then+ layer_paths+=("$candidate")+ layer_strategies+=("$strategy")+ fi+ done <<< "$sorted_presets"+ fi+ else+ # python3 failed β fall back to unordered directory scan (replace only)+ for preset in "$presets_dir"/*/; do+ [ -d "$preset" ] || continue+ local candidate="$preset/templates/${template_name}.md"+ if [ -f "$candidate" ]; then+ layer_paths+=("$candidate")+ layer_strategies+=("replace")+ fi+ done+ fi+ else+ # No python3 or registry β fall back to unordered directory scan (replace only)+ for preset in "$presets_dir"/*/; do+ [ -d "$preset" ] || continue+ local candidate="$preset/templates/${template_name}.md"+ if [ -f "$candidate" ]; then+ layer_paths+=("$candidate")+ layer_strategies+=("replace")+ fi+ done+ fi+ fi++ # Priority 3: Extension-provided templates (always "replace")+ local ext_dir="$repo_root/.specify/extensions"+ if [ -d "$ext_dir" ]; then+ for ext in "$ext_dir"/*/; do+ [ -d "$ext" ] || continue+ case "$(basename "$ext")" in .*) continue;; esac+ local candidate="$ext/templates/${template_name}.md"+ if [ -f "$candidate" ]; then+ layer_paths+=("$candidate")+ layer_strategies+=("replace")+ fi+ done+ fi++ # Priority 4: Core templates (always "replace")+ local core="$base/${template_name}.md"+ if [ -f "$core" ]; then+ layer_paths+=("$core")+ layer_strategies+=("replace")+ fi++ local count=${#layer_paths[@]}+ [ "$count" -eq 0 ] && return 1++ # Check if any layer uses a non-replace strategy+ local has_composition=false+ for s in "${layer_strategies[@]}"; do+ [ "$s" != "replace" ] && has_composition=true && break+ done++ # If the top (highest-priority) layer is replace, it wins entirely β+ # lower layers are irrelevant regardless of their strategies.+ if [ "${layer_strategies[0]}" = "replace" ]; then+ cat "${layer_paths[0]}"+ return 0+ fi++ if [ "$has_composition" = false ]; then+ cat "${layer_paths[0]}"+ return 0+ fi++ # Find the effective base: scan from highest priority (index 0) downward+ # to find the nearest replace layer. Only compose layers above that base.+ local base_idx=-1+ local i+ for (( i=0; i<count; i++ )); do+ if [ "${layer_strategies[$i]}" = "replace" ]; then+ base_idx=$i+ break+ fi+ done++ if [ $base_idx -lt 0 ]; then+ return 1 # no base layer found+ fi++ # Read the base content; compose layers above the base (higher priority)+ local content+ content=$(cat "${layer_paths[$base_idx]}"; printf x)+ content="${content%x}"++ for (( i=base_idx-1; i>=0; i-- )); do+ local path="${layer_paths[$i]}"+ local strat="${layer_strategies[$i]}"+ local layer_content+ # Preserve trailing newlines+ layer_content=$(cat "$path"; printf x)+ layer_content="${layer_content%x}"++ case "$strat" in+ replace) content="$layer_content" ;;+ prepend) content="$(printf '%s\n\n%s' "$layer_content" "$content")" ;;+ append) content="$(printf '%s\n\n%s' "$content" "$layer_content")" ;;+ wrap)+ case "$layer_content" in+ *'{CORE_TEMPLATE}'*) ;;+ *) echo "Error: wrap strategy missing {CORE_TEMPLATE} placeholder" >&2; return 1 ;;+ esac+ while [[ "$layer_content" == *'{CORE_TEMPLATE}'* ]]; do+ local before="${layer_content%%\{CORE_TEMPLATE\}*}"+ local after="${layer_content#*\{CORE_TEMPLATE\}}"+ layer_content="${before}${content}${after}"+ done+ content="$layer_content"+ ;;+ *) echo "Error: unknown strategy '$strat'" >&2; return 1 ;;+ esac+ done++ printf '%s' "$content"+ return 0+}+diff --git a/scripts/powershell/common.ps1 b/scripts/powershell/common.ps1index 0d6544aaf..d799e4f7e 100644--- a/scripts/powershell/common.ps1+++ b/scripts/powershell/common.ps1@@ -287,6 +287,21 @@ function Test-DirHasFiles {}}+# Find a usable Python 3 executable (python3, python, or py -3).+# Returns the command/arguments as an array, or $null if none found.+function Get-Python3Command {+ if (Get-Command python3 -ErrorAction SilentlyContinue) { return @('python3') }+ if (Get-Command python -ErrorAction SilentlyContinue) {+ $ver = & python --version 2>&1+ if ($ver -match 'Python 3') { return @('python') }+ }+ if (Get-Command py -ErrorAction SilentlyContinue) {+ $ver = & py -3 --version 2>&1+ if ($ver -match 'Python 3') { return @('py', '-3') }+ }+ return $null+}+# Resolve a template name to a file path using the priority stack:# 1. .specify/templates/overrides/# 2. .specify/presets/<preset-id>/templates/ (sorted by priority from .registry)@@ -315,6 +330,7 @@ function Resolve-Template {$presets = $registryData.presetsif ($presets) {$sortedPresets = $presets.PSObject.Properties |+ Where-Object { $null -eq $_.Value.enabled -or $_.Value.enabled -ne $false } |Sort-Object { if ($null -ne $_.Value.priority) { $_.Value.priority } else { 10 } } |ForEach-Object { $_.Name }}@@ -354,3 +370,206 @@ function Resolve-Template {return $null}+# Resolve a template name to composed content using composition strategies.+# Reads strategy metadata from preset manifests and composes content+# from multiple layers using prepend, append, or wrap strategies.+function Resolve-TemplateContent {+ param(+ [Parameter(Mandatory=$true)][string]$TemplateName,+ [Parameter(Mandatory=$true)][string]$RepoRoot+ )++ $base = Join-Path $RepoRoot '.specify/templates'++ # Collect all layers (highest priority first)+ $layerPaths = @()+ $layerStrategies = @()++ # Priority 1: Project overrides (always "replace")+ $override = Join-Path $base "overrides/$TemplateName.md"+ if (Test-Path $override) {+ $layerPaths += $override+ $layerStrategies += 'replace'+ }++ # Priority 2: Installed presets (sorted by priority from .registry)+ $presetsDir = Join-Path $RepoRoot '.specify/presets'+ if (Test-Path $presetsDir) {+ $registryFile = Join-Path $presetsDir '.registry'+ $sortedPresets = @()+ if (Test-Path $registryFile) {+ try {+ $registryData = Get-Content $registryFile -Raw | ConvertFrom-Json+ $presets = $registryData.presets+ if ($presets) {+ $sortedPresets = $presets.PSObject.Properties |+ Where-Object { $null -eq $_.Value.enabled -or $_.Value.enabled -ne $false } |+ Sort-Object { if ($null -ne $_.Value.priority) { $_.Value.priority } else { 10 } } |+ ForEach-Object { $_.Name }+ }+ } catch {+ $sortedPresets = @()+ }+ }++ if ($sortedPresets.Count -gt 0) {+ $pyCmd = Get-Python3Command+ if (-not $pyCmd) {+ # Check if any preset has strategy fields that would be ignored+ foreach ($pid in $sortedPresets) {+ $mf = Join-Path $presetsDir "$pid/preset.yml"+ if ((Test-Path $mf) -and (Select-String -Path $mf -Pattern 'strategy:' -Quiet -ErrorAction SilentlyContinue)) {+ Write-Warning "No Python 3 found; preset composition strategies will be ignored"+ break+ }+ }+ }+ $yamlWarned = $false+ foreach ($presetId in $sortedPresets) {+ # Read strategy and file path from preset manifest+ $strategy = 'replace'+ $manifestFilePath = ''+ $manifest = Join-Path $presetsDir "$presetId/preset.yml"+ if ((Test-Path $manifest) -and $pyCmd) {+ try {+ # Use Python to parse YAML manifest for strategy and file path+ $pyArgs = if ($pyCmd.Count -gt 1) { $pyCmd[1..($pyCmd.Count-1)] } else { @() }+ $pyStderrFile = [System.IO.Path]::GetTempFileName()+ $stratResult = & $pyCmd[0] @pyArgs -c @"+import sys+try:+ import yaml+except ImportError:+ print('yaml_missing', file=sys.stderr)+ print('replace\t')+ sys.exit(0)+try:+ with open(sys.argv[1]) as f:+ data = yaml.safe_load(f)+ for t in data.get('provides', {}).get('templates', []):+ if t.get('name') == sys.argv[2] and t.get('type', 'template') == 'template':+ print(t.get('strategy', 'replace') + '\t' + t.get('file', ''))+ sys.exit(0)+ print('replace\t')+except Exception:+ print('replace\t')+"@ $manifest $TemplateName 2>$pyStderrFile+ if ($stratResult) {+ $parts = $stratResult.Trim() -split "`t", 2+ $strategy = $parts[0].ToLowerInvariant()+ if ($parts.Count -gt 1 -and $parts[1]) { $manifestFilePath = $parts[1] }+ }+ if (-not $yamlWarned -and (Test-Path $pyStderrFile) -and (Get-Content $pyStderrFile -Raw -ErrorAction SilentlyContinue) -match 'yaml_missing') {+ Write-Warning "PyYAML not available; composition strategies may be ignored"+ $yamlWarned = $true+ }+ Remove-Item $pyStderrFile -Force -ErrorAction SilentlyContinue+ } catch {+ $strategy = 'replace'+ if ($pyStderrFile) { Remove-Item $pyStderrFile -Force -ErrorAction SilentlyContinue }+ }+ }+ # Try manifest file path first, then convention path+ $candidate = $null+ if ($manifestFilePath) {+ # Reject absolute paths and parent traversal+ if ([System.IO.Path]::IsPathRooted($manifestFilePath) -or $manifestFilePath -match '\.\.[\\/]') {+ $manifestFilePath = ''+ }+ }+ if ($manifestFilePath) {+ $mf = Join-Path $presetsDir "$presetId/$manifestFilePath"+ if (Test-Path $mf) { $candidate = $mf }+ }+ if (-not $candidate) {+ $cf = Join-Path $presetsDir "$presetId/templates/$TemplateName.md"+ if (Test-Path $cf) { $candidate = $cf }+ }+ if ($candidate) {+ $layerPaths += $candidate+ $layerStrategies += $strategy+ }+ }+ } else {+ # Fallback: alphabetical directory order (no registry or parse failure)+ foreach ($preset in Get-ChildItem -Path $presetsDir -Directory -ErrorAction SilentlyContinue | Where-Object { $_.Name -notlike '.*' }) {+ $candidate = Join-Path $preset.FullName "templates/$TemplateName.md"+ if (Test-Path $candidate) {+ $layerPaths += $candidate+ $layerStrategies += 'replace'+ }+ }+ }+ }++ # Priority 3: Extension-provided templates (always "replace")+ $extDir = Join-Path $RepoRoot '.specify/extensions'+ if (Test-Path $extDir) {+ foreach ($ext in Get-ChildItem -Path $extDir -Directory -ErrorAction SilentlyContinue | Where-Object { $_.Name -notlike '.*' } | Sort-Object Name) {+ $candidate = Join-Path $ext.FullName "templates/$TemplateName.md"+ if (Test-Path $candidate) {+ $layerPaths += $candidate+ $layerStrategies += 'replace'+ }+ }+ }++ # Priority 4: Core templates (always "replace")+ $core = Join-Path $base "$TemplateName.md"+ if (Test-Path $core) {+ $layerPaths += $core+ $layerStrategies += 'replace'+ }++ if ($layerPaths.Count -eq 0) { return $null }++ # If the top (highest-priority) layer is replace, it wins entirely β+ # lower layers are irrelevant regardless of their strategies.+ if ($layerStrategies[0] -eq 'replace') {+ return (Get-Content $layerPaths[0] -Raw)+ }++ # Check if any layer uses a non-replace strategy+ $hasComposition = $false+ foreach ($s in $layerStrategies) {+ if ($s -ne 'replace') { $hasComposition = $true; break }+ }++ if (-not $hasComposition) {+ return (Get-Content $layerPaths[0] -Raw)+ }++ # Find the effective base: scan from highest priority (index 0) downward+ # to find the nearest replace layer. Only compose layers above that base.+ $baseIdx = -1+ for ($i = 0; $i -lt $layerPaths.Count; $i++) {+ if ($layerStrategies[$i] -eq 'replace') {+ $baseIdx = $i+ break+ }+ }+ if ($baseIdx -lt 0) { return $null }++ $content = Get-Content $layerPaths[$baseIdx] -Raw++ for ($i = $baseIdx - 1; $i -ge 0; $i--) {+ $path = $layerPaths[$i]+ $strat = $layerStrategies[$i]+ $layerContent = Get-Content $path -Raw++ switch ($strat) {+ 'replace' { $content = $layerContent }+ 'prepend' { $content = "$layerContent`n`n$content" }+ 'append' { $content = "$content`n`n$layerContent" }+ 'wrap' {+ if (-not $layerContent.Contains('{CORE_TEMPLATE}')) {+ throw "Wrap strategy missing {CORE_TEMPLATE} placeholder"+ }+ $content = $layerContent.Replace('{CORE_TEMPLATE}', $content)+ }+ default { throw "Unknown strategy: $strat" }+ }+ }++ return $content+}\ No newline at end of filediff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.pyindex 743ceb995..77611128b 100644--- a/src/specify_cli/__init__.py+++ b/src/specify_cli/__init__.py@@ -2762,14 +2762,58 @@ def preset_resolve(raise typer.Exit(1)resolver = PresetResolver(project_root)- result = resolver.resolve_with_source(template_name)-- if result:- console.print(f" [bold]{template_name}[/bold]: {result['path']}")- console.print(f" [dim](from: {result['source']})[/dim]")+ layers = resolver.collect_all_layers(template_name)++ if layers:+ # Use the highest-priority layer for display because the final output+ # may be composed and may not map to resolve_with_source()'s single path.+ display_layer = layers[0]+ console.print(f" [bold]{template_name}[/bold]: {display_layer['path']}")+ console.print(f" [dim](top layer from: {display_layer['source']})[/dim]")++ has_composition = (+ layers[0]["strategy"] != "replace"+ and any(layer["strategy"] != "replace" for layer in layers)+ )+ if has_composition:+ # Verify composition is actually possible+ try:+ composed = resolver.resolve_content(template_name)+ except Exception as exc:+ composed = None+ console.print(f" [yellow]Warning: composition error: {exc}[/yellow]")+ if composed is None:+ console.print(" [yellow]Warning: composition cannot produce output (no base layer with 'replace' strategy)[/yellow]")+ else:+ console.print(" [dim]Final output is composed from multiple preset layers; the path above is the highest-priority contributing layer.[/dim]")+ console.print("\n [bold]Composition chain:[/bold]")+ # Compute the effective base: first replace layer scanning from+ # highest priority (matching resolve_content top-down logic).+ # Only show layers from the base upward (lower layers are ignored).+ effective_base_idx = None+ for idx, lyr in enumerate(layers):+ if lyr["strategy"] == "replace":+ effective_base_idx = idx+ break+ # Show only contributing layers (base and above)+ if effective_base_idx is not None:+ contributing = layers[:effective_base_idx + 1]+ else:+ contributing = layers+ for i, layer in enumerate(reversed(contributing)):+ strategy_label = layer["strategy"]+ if strategy_label == "replace" and i == 0:+ strategy_label = "base"+ console.print(f" {i + 1}. [{strategy_label}] {layer['source']} β {layer['path']}")else:- console.print(f" [yellow]{template_name}[/yellow]: not found")- console.print(" [dim]No template with this name exists in the resolution stack[/dim]")+ # No layers found β fall back to resolve_with_source for non-composition cases+ result = resolver.resolve_with_source(template_name)+ if result:+ console.print(f" [bold]{template_name}[/bold]: {result['path']}")+ console.print(f" [dim](from: {result['source']})[/dim]")+ else:+ console.print(f" [yellow]{template_name}[/yellow]: not found")+ console.print(" [dim]No template with this name exists in the resolution stack[/dim]")@preset_app.command("info")diff --git a/src/specify_cli/agents.py b/src/specify_cli/agents.pyindex 43cbfbe08..726b0fd2a 100644--- a/src/specify_cli/agents.py+++ b/src/specify_cli/agents.py@@ -8,7 +8,7 @@ command files into agent-specific directories in the correct format.import osfrom pathlib import Path-from typing import Dict, List, Any+from typing import Dict, List, Any, Optionalimport platformimport re@@ -652,6 +652,49 @@ class CommandRegistrar:return results+ def register_commands_for_non_skill_agents(+ self,+ commands: List[Dict[str, Any]],+ source_id: str,+ source_dir: Path,+ project_root: Path,+ context_note: Optional[str] = None,+ ) -> Dict[str, List[str]]:+ """Register commands for all non-skill agents in the project.++ Like register_commands_for_all_agents but skips skill-based agents+ (those with extension '/SKILL.md'). Used by reconciliation to avoid+ overwriting properly formatted SKILL.md files.++ Args:+ commands: List of command info dicts+ source_id: Identifier of the source+ source_dir: Directory containing command source files+ project_root: Path to project root+ context_note: Custom context comment for markdown output++ Returns:+ Dictionary mapping agent names to list of registered commands+ """+ results = {}+ self._ensure_configs()+ for agent_name, agent_config in self.AGENT_CONFIGS.items():+ if agent_config.get("extension") == "/SKILL.md":+ continue+ agent_dir = project_root / agent_config["dir"]+ if agent_dir.exists():+ try:+ registered = self.register_commands(+ agent_name, commands, source_id,+ source_dir, project_root,+ context_note=context_note,+ )+ if registered:+ results[agent_name] = registered+ except ValueError:+ continue+ return results+def unregister_commands(self, registered_commands: Dict[str, List[str]], project_root: Path) -> None:diff --git a/src/specify_cli/presets.py b/src/specify_cli/presets.pyindex 5f28be720..ed33f992c 100644--- a/src/specify_cli/presets.py+++ b/src/specify_cli/presets.py@@ -109,6 +109,9 @@ class PresetCompatibilityError(PresetError):VALID_PRESET_TEMPLATE_TYPES = {"template", "command", "script"}+VALID_PRESET_STRATEGIES = {"replace", "prepend", "append", "wrap"}+# Scripts only support replace and wrap (prepend/append don't make semantic sense for executable code)+VALID_SCRIPT_STRATEGIES = {"replace", "wrap"}class PresetManifest:@@ -207,6 +210,28 @@ class PresetManifest:"must be a relative path within the preset directory")+ # Validate strategy field (optional, defaults to "replace")+ strategy = tmpl.get("strategy", "replace")+ if not isinstance(strategy, str):+ raise PresetValidationError(+ f"Invalid strategy value: must be a string, "+ f"got {type(strategy).__name__}"+ )+ strategy = strategy.lower()+ # Persist normalized value so downstream code sees lowercase+ if "strategy" in tmpl:+ tmpl["strategy"] = strategy+ if strategy not in VALID_PRESET_STRATEGIES:+ raise PresetValidationError(+ f"Invalid strategy '{strategy}': "+ f"must be one of {sorted(VALID_PRESET_STRATEGIES)}"+ )+ if tmpl["type"] == "script" and strategy not in VALID_SCRIPT_STRATEGIES:+ raise PresetValidationError(+ f"Invalid strategy '{strategy}' for script: "+ f"scripts only support {sorted(VALID_SCRIPT_STRATEGIES)}"+ )+# Validate template name formatif tmpl["type"] == "command":# Commands use dot notation (e.g. speckit.specify)@@ -558,6 +583,10 @@ class PresetManager:file, and writes it to every detected agent directory using theCommandRegistrar from the agents module.+ When a command uses a composition strategy (prepend, append, wrap),+ the content is composed with the lower-priority command before+ registration.+Args:manifest: Preset manifestpreset_dir: Installed preset directory@@ -587,6 +616,50 @@ class PresetManager:if not filtered:return {}+ # Handle composition strategies: resolve composed content for non-replace commands+ resolver = PresetResolver(self.project_root)+ composed_dir = None+ commands_to_register = []+ for cmd in filtered:+ strategy = cmd.get("strategy", "replace")+ if strategy != "replace":+ # Only pre-compose if this preset is the top composing layer.+ # If a higher-priority replace already wins, skip composition+ # here β reconciliation will write the correct content.+ layers = resolver.collect_all_layers(cmd["name"], "command")+ top_layer_is_ours = (+ layers and layers[0]["path"].is_relative_to(preset_dir)+ )+ if top_layer_is_ours:+ composed = resolver.resolve_content(cmd["name"], "command")+ if composed is not None:+ if composed_dir is None:+ composed_dir = preset_dir / ".composed"+ composed_dir.mkdir(parents=True, exist_ok=True)+ composed_file = composed_dir / f"{cmd['name']}.md"+ composed_file.write_text(composed, encoding="utf-8")+ commands_to_register.append({+ **cmd,+ "file": f".composed/{cmd['name']}.md",+ })+ else:+ raise PresetValidationError(+ f"Command '{cmd['name']}' uses '{strategy}' strategy "+ f"but no base command layer exists to compose onto. "+ f"Ensure a lower-priority preset, extension, or core "+ f"command provides this command before using "+ f"composition strategies."+ )+ else:+ # Not the top layer β register raw file; reconciliation+ # will overwrite with the correct composed/winning content.+ # Note: CommandRegistrar may process frontmatter strategy: wrap+ # from the raw file (legacy compat), but reconciliation runs+ # immediately after install and corrects the final output.+ commands_to_register.append(cmd)+ else:+ commands_to_register.append(cmd)+try:from .agents import CommandRegistrarexcept ImportError:@@ -594,7 +667,7 @@ class PresetManager:registrar = CommandRegistrar()return registrar.register_commands_for_all_agents(- filtered, manifest.id, preset_dir, self.project_root+ commands_to_register, manifest.id, preset_dir, self.project_root)def _unregister_commands(self, registered_commands: Dict[str, List[str]]) -> None:@@ -611,231 +684,402 @@ class PresetManager:registrar = CommandRegistrar()registrar.unregister_commands(registered_commands, self.project_root)- def _replay_wraps_for_command(self, cmd_name: str) -> None:- """Recompose and rewrite agent files for a wrap-strategy command.-- Collects all installed presets that declare cmd_name in their- wrap_commands registry field, sorts them so the highest-precedence- preset (lowest priority number) wraps outermost, then writes the- fully composed output to every agent directory.+ def _reconcile_composed_commands(self, command_names: List[str]) -> None:+ """Re-resolve and re-register composed commands from the full stack.- Called after every install and remove to keep agent files correct- regardless of installation order.+ After install or remove, recompute the effective content for each+ command name that participates in composition, and write the winning+ content to the agent directories. This ensures command files always+ reflect the current priority stack rather than depending on+ install/remove order.Args:- cmd_name: Full command name (e.g. "speckit.specify")+ command_names: List of command names to reconcile"""+ if not command_names:+ return+try:from .agents import CommandRegistrarexcept ImportError:return- # Collect enabled presets that wrap this command, sorted ascending- # (lowest priority number = highest precedence = outermost).- wrap_presets = []- for pack_id, metadata in self.registry.list_by_priority(include_disabled=False):- if cmd_name not in metadata.get("wrap_commands", []):- continue- pack_dir = self.presets_dir / pack_id- if not pack_dir.is_dir():- continue # corrupted state β skip- wrap_presets.append((pack_id, pack_dir))+ resolver = PresetResolver(self.project_root)+ registrar = CommandRegistrar()- if not wrap_presets:- return+ # Cache registry and manifests outside the loop to avoid+ # repeated filesystem reads for each command name.+ presets_by_priority = list(self.registry.list_by_priority())- # Derive short name for core resolution fallback.- short_name = cmd_name- if short_name.startswith("speckit."):- short_name = short_name[len("speckit."):]+ for cmd_name in command_names:+ layers = resolver.collect_all_layers(cmd_name, "command")+ if not layers:+ continue- resolver = PresetResolver(self.project_root)- core_file = (- resolver.resolve_core(cmd_name, "command")- or resolver.resolve_extension_command_via_manifest(cmd_name)- or (- resolver.resolve_extension_command_via_manifest(short_name)- if short_name != cmd_name- else None+ # If the top layer is replace, it wins entirely β lower layers+ # are irrelevant regardless of their strategies.+ top_is_replace = layers[0]["strategy"] == "replace"+ has_composition = not top_is_replace and any(+ layer["strategy"] != "replace" for layer in layers)- or resolver.resolve_core(short_name, "command")- )- if core_file is None:- return-- registrar = CommandRegistrar()- core_frontmatter, core_body = registrar.parse_frontmatter(- core_file.read_text(encoding="utf-8")- )- replay_aliases: List[str] = []- seen_aliases: set[str] = set()-- # Apply wraps innermost-first (reverse of ascending list).- accumulated_body = core_body- outermost_frontmatter = {}- outermost_pack_id = wrap_presets[0][0] # fallback; updated per contributing preset- for pack_id, pack_dir in reversed(wrap_presets):- manifest_path = pack_dir / "preset.yml"- cmd_file: Optional[Path] = None- if manifest_path.exists():- try:- manifest = PresetManifest(manifest_path)- except (PresetValidationError, KeyError, TypeError, ValueError):- manifest = None- if manifest is not None:- for template in manifest.templates:- if template.get("type") != "command" or template.get("name") != cmd_name:- continue- file_rel = template.get("file")- if isinstance(file_rel, str):- rel_path = Path(file_rel)- if not rel_path.is_absolute():- try:- preset_root = pack_dir.resolve()- candidate = (preset_root / rel_path).resolve()- candidate.relative_to(preset_root)- except (OSError, ValueError):- candidate = None- if candidate is not None:- cmd_file = candidate- aliases = template.get("aliases", [])- if not isinstance(aliases, list):- aliases = []- for alias in aliases:- if isinstance(alias, str) and alias not in seen_aliases:- replay_aliases.append(alias)- seen_aliases.add(alias)+ if not has_composition:+ # Pure replace β the top layer wins.+ top_layer = layers[0]+ top_path = top_layer["path"]+ # Try to find which preset owns this layer+ registered = False+ for pack_id, _meta in presets_by_priority:+ pack_dir = self.presets_dir / pack_id+ if top_path.is_relative_to(pack_dir):+ manifest = resolver._get_manifest(pack_dir)+ if manifest:+ for tmpl in manifest.templates:+ if tmpl.get("name") == cmd_name and tmpl.get("type") == "command":+ self._register_for_non_skill_agents(+ registrar, [tmpl], manifest.id, pack_dir+ )+ registered = True+ breakbreak- if cmd_file is None:- cmd_file = pack_dir / "commands" / f"{cmd_name}.md"- if not cmd_file.exists():- continue- wrap_fm, wrap_body = registrar.parse_frontmatter(- cmd_file.read_text(encoding="utf-8")- )- accumulated_body = wrap_body.replace("{CORE_TEMPLATE}", accumulated_body)- outermost_frontmatter = wrap_fm # last iteration = outermost preset- outermost_pack_id = pack_id-- # Build final frontmatter: outermost preset wins; fall back to core for- # scripts/agent_scripts if the outermost preset does not define them.- final_frontmatter = dict(outermost_frontmatter)- final_frontmatter.pop("strategy", None)- for key in ("scripts", "agent_scripts"):- if key not in final_frontmatter and key in core_frontmatter:- final_frontmatter[key] = core_frontmatter[key]-- composed_content = (- registrar.render_frontmatter(final_frontmatter) + "\n" + accumulated_body- )-- self._replay_skill_override(cmd_name, composed_content, outermost_pack_id)-- with tempfile.TemporaryDirectory() as tmpdir:- tmp_path = Path(tmpdir)- cmd_dir = tmp_path / "commands"- cmd_dir.mkdir()- (cmd_dir / f"{cmd_name}.md").write_text(composed_content, encoding="utf-8")- registrar._ensure_configs()- for agent_name, agent_config in registrar.AGENT_CONFIGS.items():- if agent_config.get("extension") == "/SKILL.md":- continue- agent_dir = self.project_root / agent_config["dir"]- if not agent_dir.exists():- continue- try:- registrar.register_commands(- agent_name,- [{- "name": cmd_name,- "file": f"commands/{cmd_name}.md",- "aliases": replay_aliases,- }],- f"preset:{outermost_pack_id}",- tmp_path,+ if not registered:+ # Top layer is a non-preset source (extension, core, or+ # project override). Register directly from the layer path.+ source = layers[0]["source"]+ if source.startswith("extension:"):+ # Use extension's own registration to preserve context formatting+ ext_id = source.split(":", 1)[1].split(" ", 1)[0]+ ext_dir = self.project_root / ".specify" / "extensions" / ext_id+ ext_manifest_path = ext_dir / "extension.yml"+ if ext_manifest_path.exists():+ try:+ from .extensions import ExtensionManifest+ ext_manifest = ExtensionManifest(ext_manifest_path)+ # Filter to only the command being reconciled+ matching_cmds = [+ c for c in ext_manifest.commands+ if c.get("name") == cmd_name+ ]+ if matching_cmds:+ registrar.register_commands_for_non_skill_agents(+ matching_cmds, ext_id, ext_dir,+ self.project_root,+ context_note=f"\n<!-- Extension: {ext_id} -->\n<!-- Config: .specify/extensions/{ext_id}/ -->\n",+ )+ registered = True+ except Exception:+ # Extension registration failed; fall back to+ # generic path-based registration below.+ pass+ if not registered:+ source_id = source.split(":", 1)[1].split(" ", 1)[0] if source.startswith("extension:") else source+ self._register_command_from_path(+ registrar, cmd_name, top_path,+ source_id=source_id,+ )+ else:+ # Composed command β resolve from full stack+ composed = resolver.resolve_content(cmd_name, "command")+ if composed is None:+ # Composition no longer possible (e.g. base layer removed).+ # Unregister any stale command file from non-skill agents.+ import warnings+ warnings.warn(+ f"Cannot compose command '{cmd_name}': no base layer. "+ f"Stale command files may remain.",+ stacklevel=2,+ )+ registrar._ensure_configs()+ # Include aliases from the top layer's manifest+ cmd_names_to_unregister = [cmd_name]+ for _pid, _meta in presets_by_priority:+ _pd = self.presets_dir / _pid+ _m = resolver._get_manifest(_pd)+ if _m:+ for _t in _m.templates:+ if _t.get("name") == cmd_name and _t.get("type") == "command":+ for alias in _t.get("aliases", []):+ if isinstance(alias, str):+ cmd_names_to_unregister.append(alias)+ break+ registrar.unregister_commands(+ {agent: cmd_names_to_unregister for agent in registrar.AGENT_CONFIGS+ if registrar.AGENT_CONFIGS[agent].get("extension") != "/SKILL.md"},self.project_root,)- except ValueError:continue- def _replay_skill_override(+ # Write to the highest-priority preset's .composed dir+ registered = False+ for pack_id, _meta in presets_by_priority:+ pack_dir = self.presets_dir / pack_id+ manifest = resolver._get_manifest(pack_dir)+ if not manifest:+ continue+ for tmpl in manifest.templates:+ if tmpl.get("name") == cmd_name and tmpl.get("type") == "command":+ composed_dir = pack_dir / ".composed"+ composed_dir.mkdir(parents=True, exist_ok=True)+ composed_file = composed_dir / f"{cmd_name}.md"+ composed_file.write_text(composed, encoding="utf-8")+ self._register_for_non_skill_agents(+ registrar,+ [{**tmpl, "file": f".composed/{cmd_name}.md"}],+ manifest.id, pack_dir,+ )+ registered = True+ break+ else:+ continue+ break+ if not registered:+ # No preset owns this composed command β write to a+ # shared .composed dir and register from the top layer.+ shared_composed = self.presets_dir / ".composed"+ shared_composed.mkdir(parents=True, exist_ok=True)+ composed_file = shared_composed / f"{cmd_name}.md"+ composed_file.write_text(composed, encoding="utf-8")+ source = layers[0]["source"]+ if source.startswith("extension:"):+ source_id = source.split(":", 1)[1].split(" ", 1)[0]+ else:+ source_id = source+ self._register_command_from_path(+ registrar, cmd_name, composed_file,+ source_id=source_id,+ )++ def _register_command_from_path(self,+ registrar: Any,cmd_name: str,- composed_content: str,- outermost_pack_id: str,+ cmd_path: Path,+ source_id: str = "reconciled",) -> None:- """Rewrite any active SKILL.md override for a replayed wrap command."""- skills_dir = self._get_skills_dir()- if not skills_dir:- return+ """Register a single command from a file path (non-preset source).- from . import SKILL_DESCRIPTIONS, load_init_options- from .agents import CommandRegistrar- from .integrations import get_integration+ Used by reconciliation when the winning layer is an extension,+ core template, or project override rather than a preset.- init_opts = load_init_options(self.project_root)- if not isinstance(init_opts, dict):- init_opts = {}- selected_ai = init_opts.get("ai")- if not isinstance(selected_ai, str):+ Args:+ registrar: CommandRegistrar instance+ cmd_name: Command name+ cmd_path: Path to the command file+ source_id: Source attribution for rendered output+ """+ if not cmd_path.exists():return+ cmd_tmpl: Dict[str, Any] = {+ "name": cmd_name,+ "type": "command",+ "file": cmd_path.name,+ }+ # Load aliases from extension manifest when the winning layer is an extension+ if source_id and not source_id.startswith("preset:"):+ try:+ from .extensions import ExtensionManifest+ for ext_dir in (self.project_root / ".specify" / "extensions").iterdir():+ if not ext_dir.is_dir():+ continue+ if cmd_path.is_relative_to(ext_dir):+ manifest_path = ext_dir / "extension.yml"+ if manifest_path.exists():+ ext_manifest = ExtensionManifest(manifest_path)+ for cmd in ext_manifest.commands:+ if cmd.get("name") == cmd_name:+ aliases = cmd.get("aliases", [])+ if isinstance(aliases, list) and aliases:+ cmd_tmpl["aliases"] = aliases+ break+ break+ except Exception:+ pass # best-effort alias loading+ self._register_for_non_skill_agents(+ registrar, [cmd_tmpl], source_id, cmd_path.parent+ )- registrar = CommandRegistrar()- integration = get_integration(selected_ai)- agent_config = registrar.AGENT_CONFIGS.get(selected_ai, {})- create_missing_skills = bool(init_opts.get("ai_skills")) and agent_config.get("extension") != "/SKILL.md"-- skill_name, legacy_skill_name = self._skill_names_for_command(cmd_name)- target_skill_names: List[str] = []- if (skills_dir / skill_name).is_dir():- target_skill_names.append(skill_name)- if legacy_skill_name != skill_name and (skills_dir / legacy_skill_name).is_dir():- target_skill_names.append(legacy_skill_name)- if not target_skill_names and create_missing_skills:- missing_skill_dir = skills_dir / skill_name- if not missing_skill_dir.exists():- target_skill_names.append(skill_name)- if not target_skill_names:+ def _register_for_non_skill_agents(+ self,+ registrar: Any,+ commands: List[Dict[str, Any]],+ source_id: str,+ source_dir: Path,+ ) -> None:+ """Register commands for non-skill agents during reconciliation.++ Skill-based agents (``/SKILL.md`` layout) are handled separately:+ - On removal: ``_unregister_skills()`` restores from core/extension,+ then ``_reconcile_skills()`` re-runs ``_register_skills()`` for the+ next winning preset so SKILL.md files get proper frontmatter and+ descriptions.+ - On install: ``_register_skills()`` writes formatted SKILL.md, then+ ``_reconcile_skills()`` ensures the actual priority winner is used.++ Writing raw command content to skill agents would produce invalid+ SKILL.md files (missing skill frontmatter, descriptions, etc.).+ """+ registrar.register_commands_for_non_skill_agents(+ commands, source_id, source_dir, self.project_root+ )++ class _FilteredManifest:+ """Wrapper that exposes only selected command templates from a manifest.++ Used by _reconcile_skills to avoid overwriting skills for commands+ that aren't being reconciled.+ """++ def __init__(self, manifest: "PresetManifest", cmd_names: set):+ self._manifest = manifest+ self._cmd_names = cmd_names++ def __getattr__(self, name: str):+ return getattr(self._manifest, name)++ @property+ def templates(self) -> List[Dict[str, Any]]:+ return [+ t for t in self._manifest.templates+ if t.get("name") in self._cmd_names+ ]++ def _reconcile_skills(self, command_names: List[str]) -> None:+ """Re-register skills for commands whose winning layer changed.++ After a preset is removed, finds the next preset in the priority+ stack that provides each command and re-runs skill registration+ for that preset so SKILL.md files reflect the current winner.++ Args:+ command_names: List of command names to reconcile skills for+ """+ if not command_names:return- raw_short_name = cmd_name- if raw_short_name.startswith("speckit."):- raw_short_name = raw_short_name[len("speckit."):]- short_name = raw_short_name.replace(".", "-")- skill_title = self._skill_title_from_command(cmd_name)-- frontmatter, body = registrar.parse_frontmatter(composed_content)- original_desc = frontmatter.get("description", "")- enhanced_desc = SKILL_DESCRIPTIONS.get(- short_name,- original_desc or f"Spec-kit workflow command: {short_name}",- )- body = registrar.resolve_skill_placeholders(- selected_ai, dict(frontmatter), body, self.project_root- )+ resolver = PresetResolver(self.project_root)+ skills_dir = self._get_skills_dir()- for target_skill_name in target_skill_names:- skill_subdir = skills_dir / target_skill_name- if skill_subdir.exists() and not skill_subdir.is_dir():+ # Cache registry once to avoid repeated filesystem reads+ presets_by_priority = list(self.registry.list_by_priority())++ # Group command names by winning preset to batch _register_skills calls+ # while only registering skills for the specific commands being reconciled.+ preset_cmds: Dict[str, List[str]] = {}+ non_preset_skills: List[tuple] = []++ for cmd_name in command_names:+ layers = resolver.collect_all_layers(cmd_name, "command")+ if not layers:continue- skill_subdir.mkdir(parents=True, exist_ok=True)- frontmatter_data = registrar.build_skill_frontmatter(- selected_ai,- target_skill_name,- enhanced_desc,- f"preset:{outermost_pack_id}",- )- frontmatter_text = yaml.safe_dump(frontmatter_data, sort_keys=False).strip()- skill_content = (- f"---\n"- f"{frontmatter_text}\n"- f"---\n\n"- f"# Speckit {skill_title} Skill\n\n"- f"{body}\n"- )- if integration is not None and hasattr(integration, "post_process_skill_content"):- skill_content = integration.post_process_skill_content(skill_content)- (skill_subdir / "SKILL.md").write_text(skill_content, encoding="utf-8")++ # Re-create the skill directory only if it was previously managed+ # (i.e., listed in some preset's registered_skills). This avoids+ # creating new skill dirs that _register_skills would normally skip.+ if skills_dir:+ skill_name, _ = self._skill_names_for_command(cmd_name)+ skill_subdir = skills_dir / skill_name+ if not skill_subdir.exists():+ # Check if any preset previously registered this skill+ was_managed = False+ for _pid, meta in presets_by_priority:+ if not isinstance(meta, dict):+ continue+ if skill_name in meta.get("registered_skills", []):+ was_managed = True+ break+ if was_managed:+ skill_subdir.mkdir(parents=True, exist_ok=True)++ top_path = layers[0]["path"]+ # Find the preset that owns the winning layer+ found_preset = False+ for pack_id, _meta in presets_by_priority:+ pack_dir = self.presets_dir / pack_id+ if top_path.is_relative_to(pack_dir):+ preset_cmds.setdefault(pack_id, []).append(cmd_name)+ found_preset = True+ break+ if not found_preset:+ # Winner is a non-preset source (core/extension/override).+ # Track the winning layer path for skill restoration.+ skill_name, _ = self._skill_names_for_command(cmd_name)+ non_preset_skills.append((skill_name, cmd_name, layers[0]))++ # Restore skills for commands whose winner is non-preset.+ if non_preset_skills and skills_dir:+ # Separate override-backed skills from core/extension-backed ones.+ # _unregister_skills can rmtree the skill dir, so overrides must+ # be handled directly (create dir + write) without that call.+ core_ext_skills = []+ override_skills = []+ for item in non_preset_skills:+ if item[2]["source"] == "project override":+ override_skills.append(item)+ else:+ core_ext_skills.append(item)++ if core_ext_skills:+ self._unregister_skills(+ [s[0] for s in core_ext_skills], self.presets_dir+ )++ for skill_name, cmd_name, top_layer in override_skills:+ skill_subdir = skills_dir / skill_name+ skill_subdir.mkdir(parents=True, exist_ok=True)+ skill_file = skill_subdir / "SKILL.md"+ try:+ from .agents import CommandRegistrar+ from . import SKILL_DESCRIPTIONS, load_init_options+ registrar = CommandRegistrar()+ content = top_layer["path"].read_text(encoding="utf-8")+ fm, body = registrar.parse_frontmatter(content)+ short_name = cmd_name+ if short_name.startswith("speckit."):+ short_name = short_name[len("speckit."):]+ desc = SKILL_DESCRIPTIONS.get(+ short_name.replace(".", "-"),+ fm.get("description", f"Command: {short_name}"),+ )+ init_opts = load_init_options(self.project_root)+ selected_ai = init_opts.get("ai") if isinstance(init_opts, dict) else ""+ if isinstance(selected_ai, str):+ body = registrar.resolve_skill_placeholders(+ selected_ai, fm, body, self.project_root+ )+ fm_data = registrar.build_skill_frontmatter(+ selected_ai if isinstance(selected_ai, str) else "",+ skill_name, desc,+ f"override:{cmd_name}",+ )+ fm_text = yaml.safe_dump(fm_data, sort_keys=False).strip()+ skill_title = self._skill_title_from_command(cmd_name)+ skill_content = (+ f"---\n{fm_text}\n---\n\n"+ f"# Speckit {skill_title} Skill\n\n{body}\n"+ )+ # Apply integration post-processing (e.g. Claude flags)+ from .integrations import get_integration+ integration = get_integration(selected_ai) if isinstance(selected_ai, str) else None+ if integration is not None and hasattr(integration, "post_process_skill_content"):+ skill_content = integration.post_process_skill_content(skill_content)+ skill_file.write_text(skill_content, encoding="utf-8")+ except Exception:+ pass # best-effort override skill restoration++ # Register skills only for the specific commands being reconciled,+ # not all commands in each winning preset's manifest.+ for pack_id, cmds in preset_cmds.items():+ pack_dir = self.presets_dir / pack_id+ manifest_path = pack_dir / "preset.yml"+ if not manifest_path.exists():+ continue+ try:+ manifest = PresetManifest(manifest_path)+ except PresetValidationError:+ continue+ # Filter manifest to only the commands being reconciled+ cmds_set = set(cmds)+ filtered_manifest = self._FilteredManifest(manifest, cmds_set)+ self._register_skills(filtered_manifest, pack_dir)def _get_skills_dir(self) -> Optional[Path]:"""Return the active skills directory for preset skill overrides.@@ -1016,6 +1260,12 @@ class PresetManager:if not source_file.exists():continue+ # Use composed content if available (written by _register_commands+ # for commands with non-replace strategies), otherwise the original.+ composed_file = preset_dir / ".composed" / f"{cmd_name}.md"+ if composed_file.exists():+ source_file = composed_file+# Derive the short command name (e.g. "specify" from "speckit.specify")raw_short_name = cmd_nameif raw_short_name.startswith("speckit."):@@ -1257,43 +1507,81 @@ class PresetManager:shutil.copytree(source_dir, dest_dir)- # Register command overrides with AI agents- registered_commands = self._register_commands(manifest, dest_dir)-- # Update corresponding skills when --ai-skills was previously used- registered_skills = self._register_skills(manifest, dest_dir)-- # Detect wrap commands before registry.add() so a read failure doesn't- # leave a partially-committed registry entry.- wrap_commands = []- try:- from .agents import CommandRegistrar as _CR- _registrar = _CR()- for cmd_tmpl in manifest.templates:- if cmd_tmpl.get("type") != "command":- continue- cmd_file = dest_dir / cmd_tmpl["file"]- if not cmd_file.exists():- continue- cmd_fm, _ = _registrar.parse_frontmatter(cmd_file.read_text(encoding="utf-8"))- if cmd_fm.get("strategy") == "wrap":- wrap_commands.append(cmd_tmpl["name"])- except ImportError:- pass-+ # Pre-register the preset so that composition resolution can see it+ # in the priority stack when resolving composed command content.self.registry.add(manifest.id, {"version": manifest.version,"source": "local","manifest_hash": manifest.get_hash(),"enabled": True,"priority": priority,- "registered_commands": registered_commands,- "registered_skills": registered_skills,- "wrap_commands": wrap_commands,+ "registered_commands": {},+ "registered_skills": [],})- for cmd_name in wrap_commands:- self._replay_wraps_for_command(cmd_name)+ registered_commands: Dict[str, List[str]] = {}+ registered_skills: List[str] = []+ try:+ # Register command overrides with AI agents and persist the result+ # immediately so cleanup can recover even if installation stops+ # before later phases complete.+ registered_commands = self._register_commands(manifest, dest_dir)+ self.registry.update(manifest.id, {+ "registered_commands": registered_commands,+ })++ # Update corresponding skills when --ai-skills was previously used+ # and persist that result as well.+ registered_skills = self._register_skills(manifest, dest_dir)+ self.registry.update(manifest.id, {+ "registered_skills": registered_skills,+ })+ except Exception:+ # Roll back all side effects. Note: if _register_commands or+ # _register_skills raised mid-way (e.g. I/O error after writing+ # some files), registered_commands/registered_skills may be empty+ # and some agent command files could be orphaned. Removing dest_dir+ # (which contains .composed/) and the registry entry ensures the+ # preset system is consistent even if orphaned files remain.+ if registered_commands:+ self._unregister_commands(registered_commands)+ if registered_skills:+ self._unregister_skills(registered_skills, dest_dir)+ try:+ if dest_dir.exists():+ shutil.rmtree(dest_dir)+ except OSError:+ pass # best-effort cleanup; don't mask the original error+ self.registry.remove(manifest.id)+ raise++ # Reconcile all affected commands from the full priority stack so that+ # install order doesn't determine the winning command file.+ # Apply the same extension-installed filter as _register_commands to+ # avoid reconciling extension commands when the extension isn't installed.+ extensions_dir = self.project_root / ".specify" / "extensions"+ cmd_names = []+ for t in manifest.templates:+ if t.get("type") != "command":+ continue+ name = t["name"]+ parts = name.split(".")+ if len(parts) >= 3 and parts[0] == "speckit":+ ext_id = parts[1]+ if not (extensions_dir / ext_id).is_dir():+ continue+ cmd_names.append(name)+ if cmd_names:+ try:+ self._reconcile_composed_commands(cmd_names)+ self._reconcile_skills(cmd_names)+ except Exception as exc:+ import warnings+ warnings.warn(+ f"Post-install reconciliation failed for {manifest.id}: {exc}. "+ f"Agent command files may not reflect the current priority stack.",+ stacklevel=2,+ )return manifest@@ -1369,16 +1657,31 @@ class PresetManager:# Restore original skills when preset is removedregistered_skills = metadata.get("registered_skills", []) if metadata else []registered_commands = metadata.get("registered_commands", {}) if metadata else {}- wrap_commands = metadata.get("wrap_commands", []) if metadata else []pack_dir = self.presets_dir / pack_id- # _unregister_skills must run before directory deletion (reads preset files)+ # Collect ALL command names before filtering for reconciliation,+ # so commands registered only for skill-based agents are also reconciled.+ # Also include aliases from the manifest as a safety net for registries+ # populated by older versions that may not track aliases.+ removed_cmd_names = set()+ for cmd_names in registered_commands.values():+ removed_cmd_names.update(cmd_names)+ manifest_path = pack_dir / "preset.yml"+ if manifest_path.exists():+ try:+ manifest = PresetManifest(manifest_path)+ for tmpl in manifest.templates:+ if tmpl.get("type") == "command":+ for alias in tmpl.get("aliases", []):+ if isinstance(alias, str):+ removed_cmd_names.add(alias)+ except PresetValidationError:+ # Invalid manifest β skip alias extraction; primary command+ # names from registered_commands are still unregistered.+ pass+if registered_skills:self._unregister_skills(registered_skills, pack_dir)- # When _unregister_skills has already handled skill-agent files, strip- # those entries from registered_commands to avoid double-deletion.- # (When registered_skills is empty, skill-agent entries in- # registered_commands are the only deletion path for those files.)try:from .agents import CommandRegistrarexcept ImportError:@@ -1390,43 +1693,29 @@ class PresetManager:if CommandRegistrar.AGENT_CONFIGS.get(agent_name, {}).get("extension") != "/SKILL.md"}- # Delete the preset directory before mutating the registry so a- # filesystem failure cannot leave files on disk without a registry entry.+ # Unregister non-skill command files from AI agents.+ if registered_commands:+ self._unregister_commands(registered_commands)+if pack_dir.exists():shutil.rmtree(pack_dir)- # Remove from registry before replaying so _replay_wraps_for_command sees- # the post-removal registry state.self.registry.remove(pack_id)- # Separate wrap commands from non-wrap commands in registered_commands.- non_wrap_commands = {- agent_name: [c for c in cmd_names if c not in wrap_commands]- for agent_name, cmd_names in registered_commands.items()- }- non_wrap_commands = {k: v for k, v in non_wrap_commands.items() if v}-- # Unregister non-wrap command files from AI agents.- if non_wrap_commands:- self._unregister_commands(non_wrap_commands)-- # For each wrapped command, either re-compose remaining wraps or delete.- for cmd_name in wrap_commands:- remaining = [- pid for pid, meta in self.registry.list().items()- if cmd_name in meta.get("wrap_commands", [])- ]- if remaining:- self._replay_wraps_for_command(cmd_name)- else:- # No wrap presets remain β delete the agent file entirely.- wrap_agent_commands = {- agent_name: [c for c in cmd_names if c == cmd_name]- for agent_name, cmd_names in registered_commands.items()- }- wrap_agent_commands = {k: v for k, v in wrap_agent_commands.items() if v}- if wrap_agent_commands:- self._unregister_commands(wrap_agent_commands)+ # Reconcile: if other presets still provide these commands,+ # re-resolve from the remaining stack so the next layer takes effect.+ if removed_cmd_names:+ try:+ self._reconcile_composed_commands(list(removed_cmd_names))+ self._reconcile_skills(list(removed_cmd_names))+ except Exception as exc:+ import warnings+ warnings.warn(+ f"Post-removal reconciliation failed for {pack_id}: {exc}. "+ f"Agent command files may be stale; reinstall affected presets "+ f"or run 'specify preset add' to refresh.",+ stacklevel=2,+ )return True@@ -2036,6 +2325,21 @@ class PresetResolver:self.presets_dir = project_root / ".specify" / "presets"self.overrides_dir = self.templates_dir / "overrides"self.extensions_dir = project_root / ".specify" / "extensions"+ self._manifest_cache: Dict[str, Optional["PresetManifest"]] = {}++ def _get_manifest(self, pack_dir: Path) -> Optional["PresetManifest"]:+ """Get a cached preset manifest, parsing it on first access."""+ key = str(pack_dir)+ if key not in self._manifest_cache:+ manifest_path = pack_dir / "preset.yml"+ if manifest_path.exists():+ try:+ self._manifest_cache[key] = PresetManifest(manifest_path)+ except PresetValidationError:+ self._manifest_cache[key] = None+ else:+ self._manifest_cache[key] = None+ return self._manifest_cache[key]def _get_all_extensions_by_priority(self) -> list[tuple[int, str, dict | None]]:"""Build unified list of registered and unregistered extensions sorted by priority.@@ -2079,6 +2383,19 @@ class PresetResolver:all_extensions.sort(key=lambda x: (x[0], x[1]))return all_extensions+ @staticmethod+ def _core_stem(template_name: str) -> Optional[str]:+ """Extract the stem for core command lookup.++ Commands use dot notation (e.g. ``speckit.specify``), but core+ command files are named by stem (e.g. ``specify.md``). Returns+ the stem if *template_name* follows the ``speckit.<stem>`` pattern,+ or ``None`` otherwise.+ """+ if template_name.startswith("speckit."):+ return template_name[len("speckit."):]+ return None+def resolve(self,template_name: str,@@ -2156,6 +2473,12 @@ class PresetResolver:core = self.templates_dir / "commands" / f"{template_name}.md"if core.exists():return core+ # Fallback: speckit.<stem> β <stem>.md+ stem = self._core_stem(template_name)+ if stem:+ core = self.templates_dir / "commands" / f"{stem}.md"+ if core.exists():+ return coreelif template_type == "script":core = self.templates_dir / "scripts" / f"{template_name}{ext}"if core.exists():@@ -2173,6 +2496,10 @@ class PresetResolver:candidate = _core_pack / "templates" / f"{template_name}.md"elif template_type == "command":candidate = _core_pack / "commands" / f"{template_name}.md"+ if not candidate.exists():+ stem = self._core_stem(template_name)+ if stem:+ candidate = _core_pack / "commands" / f"{stem}.md"elif template_type == "script":candidate = _core_pack / "scripts" / f"{template_name}{ext}"else:@@ -2186,6 +2513,10 @@ class PresetResolver:candidate = repo_root / "templates" / f"{template_name}.md"elif template_type == "command":candidate = repo_root / "templates" / "commands" / f"{template_name}.md"+ if not candidate.exists():+ stem = self._core_stem(template_name)+ if stem:+ candidate = repo_root / "templates" / "commands" / f"{stem}.md"elif template_type == "script":candidate = repo_root / "scripts" / f"{template_name}{ext}"else:@@ -2317,3 +2648,428 @@ class PresetResolver:continuereturn {"path": resolved_str, "source": "core"}++ def collect_all_layers(+ self,+ template_name: str,+ template_type: str = "template",+ ) -> List[Dict[str, Any]]:+ """Collect all layers in the priority stack for a template.++ Returns layers from highest priority (checked first) to lowest priority.+ Each layer is a dict with 'path', 'source', and 'strategy' keys.++ Args:+ template_name: Template name (e.g., "spec-template")+ template_type: Template type ("template", "command", or "script")++ Returns:+ List of layer dicts ordered highest-to-lowest priority.+ """+ if template_type == "template":+ subdirs = ["templates", ""]+ elif template_type == "command":+ subdirs = ["commands"]+ elif template_type == "script":+ subdirs = ["scripts"]+ else:+ subdirs = [""]++ ext = ".md"+ if template_type == "script":+ ext = ".sh"++ layers: List[Dict[str, Any]] = []++ def _find_in_subdirs(base_dir: Path) -> Optional[Path]:+ for subdir in subdirs:+ if subdir:+ candidate = base_dir / subdir / f"{template_name}{ext}"+ else:+ candidate = base_dir / f"{template_name}{ext}"+ if candidate.exists():+ return candidate+ return None++ # Priority 1: Project-local overrides (always "replace" strategy)+ if template_type == "script":+ override = self.overrides_dir / "scripts" / f"{template_name}{ext}"+ else:+ override = self.overrides_dir / f"{template_name}{ext}"+ if override.exists():+ layers.append({+ "path": override,+ "source": "project override",+ "strategy": "replace",+ })++ # Priority 2: Installed presets (sorted by priority β lower number = higher precedence)+ if self.presets_dir.exists():+ registry = PresetRegistry(self.presets_dir)+ for pack_id, metadata in registry.list_by_priority():+ pack_dir = self.presets_dir / pack_id+ # Read strategy and manifest file path from preset manifest+ strategy = "replace"+ manifest_file_path = None+ manifest_has_strategy = False+ manifest_found_entry = False+ manifest = self._get_manifest(pack_dir)+ if manifest:+ for tmpl in manifest.templates:+ if (tmpl.get("name") == template_name+ and tmpl.get("type") == template_type):+ strategy = tmpl.get("strategy", "replace")+ manifest_has_strategy = "strategy" in tmpl+ manifest_file_path = tmpl.get("file")+ manifest_found_entry = True+ break+ # Use manifest file path if specified, otherwise convention-based+ # lookup β but only when the manifest doesn't exist or doesn't+ # list this template, so preset.yml stays authoritative.+ candidate = None+ if manifest_file_path:+ manifest_candidate = pack_dir / manifest_file_path+ if manifest_candidate.exists():+ candidate = manifest_candidate+ # Explicit file path that doesn't exist: skip convention+ # fallback to avoid masking typos or picking up unintended files.+ elif not manifest_found_entry:+ # Manifest doesn't list this template β check convention paths+ candidate = _find_in_subdirs(pack_dir)+ if candidate:+ # Legacy fallback: if manifest doesn't explicitly declare a+ # strategy, check the command file's frontmatter for any valid+ # strategy. Skip when the manifest entry includes strategy key+ # (even if it's "replace") to avoid overriding explicit declarations.+ if not manifest_has_strategy and strategy == "replace" and template_type == "command":+ try:+ cmd_content = candidate.read_text(encoding="utf-8")+ lines = cmd_content.splitlines(keepends=True)+ if lines and lines[0].rstrip("\r\n") == "---":+ fence_end = -1+ for fi, fline in enumerate(lines[1:], start=1):+ if fline.rstrip("\r\n") == "---":+ fence_end = fi+ break+ if fence_end > 0:+ fm_text = "".join(lines[1:fence_end])+ fm_data = yaml.safe_load(fm_text)+ if isinstance(fm_data, dict):+ fm_strategy = fm_data.get("strategy")+ if isinstance(fm_strategy, str) and fm_strategy.lower() in VALID_PRESET_STRATEGIES:+ strategy = fm_strategy.lower()+ except (yaml.YAMLError, OSError):+ # Best-effort legacy frontmatter parsing: keep default+ # strategy ("replace") when content is unreadable/invalid.+ pass+ version = metadata.get("version", "?") if metadata else "?"+ layers.append({+ "path": candidate,+ "source": f"{pack_id} v{version}",+ "strategy": strategy,+ })++ # Priority 3: Extension-provided templates (always "replace")+ for _priority, ext_id, ext_meta in self._get_all_extensions_by_priority():+ ext_dir = self.extensions_dir / ext_id+ if not ext_dir.is_dir():+ continue+ # Try convention-based lookup first+ candidate = _find_in_subdirs(ext_dir)+ # If not found and this is a command, check extension manifest+ if candidate is None and template_type == "command":+ ext_manifest_path = ext_dir / "extension.yml"+ if ext_manifest_path.exists():+ try:+ from .extensions import ExtensionManifest, ValidationError as ExtValidationError+ ext_manifest = ExtensionManifest(ext_manifest_path)+ for cmd in ext_manifest.commands:+ if cmd.get("name") == template_name:+ cmd_file = cmd.get("file")+ if cmd_file:+ c = ext_dir / cmd_file+ if c.exists():+ candidate = c+ break+ except (ExtValidationError, yaml.YAMLError):+ # Invalid extension manifest β fall back to+ # convention-based lookup (already attempted above).+ pass+ if candidate:+ if ext_meta:+ version = ext_meta.get("version", "?")+ source = f"extension:{ext_id} v{version}"+ else:+ source = f"extension:{ext_id} (unregistered)"+ layers.append({+ "path": candidate,+ "source": source,+ "strategy": "replace",+ })++ # Priority 4: Core templates (always "replace")+ core = None+ if template_type == "template":+ c = self.templates_dir / f"{template_name}.md"+ if c.exists():+ core = c+ elif template_type == "command":+ c = self.templates_dir / "commands" / f"{template_name}.md"+ if c.exists():+ core = c+ else:+ # Fallback: speckit.<stem> β <stem>.md+ stem = self._core_stem(template_name)+ if stem:+ c = self.templates_dir / "commands" / f"{stem}.md"+ if c.exists():+ core = c+ elif template_type == "script":+ c = self.templates_dir / "scripts" / f"{template_name}{ext}"+ if c.exists():+ core = c+ if core:+ layers.append({+ "path": core,+ "source": "core",+ "strategy": "replace",+ })+ else:+ # Priority 5: Bundled core_pack (wheel install) or repo-root+ # templates (source-checkout), matching resolve()'s tier-5 fallback.+ bundled = self._find_bundled_core(template_name, template_type, ext)+ if bundled:+ layers.append({+ "path": bundled,+ "source": "core (bundled)",+ "strategy": "replace",+ })++ return layers++ def _find_bundled_core(+ self,+ template_name: str,+ template_type: str,+ ext: str,+ ) -> Optional[Path]:+ """Find a core template from the bundled pack or source checkout.++ Mirrors the tier-5 fallback logic in ``resolve()`` so that+ ``collect_all_layers()`` can locate base layers even when+ ``.specify/templates/`` doesn't contain the core file.+ """+ try:+ from specify_cli import _locate_core_pack+ except ImportError:+ return None++ stem = self._core_stem(template_name)+ names = [template_name]+ if stem and stem != template_name:+ names.append(stem)++ core_pack = _locate_core_pack()+ if core_pack is not None:+ for name in names:+ if template_type == "template":+ c = core_pack / "templates" / f"{name}.md"+ elif template_type == "command":+ c = core_pack / "commands" / f"{name}.md"+ elif template_type == "script":+ c = core_pack / "scripts" / f"{name}{ext}"+ else:+ c = core_pack / f"{name}.md"+ if c.exists():+ return c+ else:+ repo_root = Path(__file__).parent.parent.parent+ for name in names:+ if template_type == "template":+ c = repo_root / "templates" / f"{name}.md"+ elif template_type == "command":+ c = repo_root / "templates" / "commands" / f"{name}.md"+ elif template_type == "script":+ c = repo_root / "scripts" / f"{name}{ext}"+ else:+ c = repo_root / f"{name}.md"+ if c.exists():+ return c+ return None++ def resolve_content(+ self,+ template_name: str,+ template_type: str = "template",+ ) -> Optional[str]:+ """Resolve a template name and return composed content.++ Walks the priority stack and composes content using strategies:+ - replace (default): highest-priority content wins entirely+ - prepend: content is placed before lower-priority content+ - append: content is placed after lower-priority content+ - wrap: content contains {CORE_TEMPLATE} placeholder replaced+ with lower-priority content (or $CORE_SCRIPT for scripts)++ Composition is recursive β multiple composing presets chain.++ Args:+ template_name: Template name (e.g., "spec-template")+ template_type: Template type ("template", "command", or "script")++ Returns:+ Composed content string, or None if not found+ """+ layers = self.collect_all_layers(template_name, template_type)+ if not layers:+ return None++ # If the top (highest-priority) layer is replace, it wins entirely β+ # lower layers are irrelevant regardless of their strategies.+ if layers[0]["strategy"] == "replace":+ return layers[0]["path"].read_text(encoding="utf-8")++ # Composition: build content bottom-up from the effective base.+ # The base is the nearest replace layer scanning from highest priority+ # downward. Only layers above the base contribute to composition.+ #+ # layers is ordered highest-priority first. We process in reverse.+ reversed_layers = list(reversed(layers))++ # Find the effective base: scan from highest priority (layers[0]) downward+ # to find the nearest replace layer. Only compose layers above that base.+ # layers is highest-priority first; reversed_layers is lowest first.+ base_layer_idx = None # index in layers[] (highest-priority first)+ for idx, layer in enumerate(layers):+ if layer["strategy"] == "replace":+ base_layer_idx = idx+ break++ if base_layer_idx is None:+ return None # no replace base found++ # Convert to reversed_layers index+ base_reversed_idx = len(layers) - 1 - base_layer_idx+ content = layers[base_layer_idx]["path"].read_text(encoding="utf-8")+ # Compose only the layers above the base (higher priority = lower index in layers,+ # higher index in reversed_layers). Process bottom-up from base+1.+ start_idx = base_reversed_idx + 1++ # For command composition, strip frontmatter from each layer to avoid+ # leaking YAML metadata into the composed body. The highest-priority+ # layer's frontmatter will be reattached at the end.+ is_command = template_type == "command"+ top_frontmatter_text = None+ base_frontmatter_text = None++ def _split_frontmatter(text: str) -> tuple:+ """Return (frontmatter_block_with_fences, body) or (None, text).++ Uses line-based fence detection (fence must be ``---`` on its+ own line) to avoid false matches on ``---`` inside YAML values.+ """+ lines = text.splitlines(keepends=True)+ if not lines or lines[0].rstrip("\r\n") != "---":+ return None, text++ fence_end = -1+ for i, line in enumerate(lines[1:], start=1):+ if line.rstrip("\r\n") == "---":+ fence_end = i+ break++ if fence_end == -1:+ return None, text++ fm_block = "".join(lines[:fence_end + 1]).rstrip("\r\n")+ body = "".join(lines[fence_end + 1:])+ return fm_block, body++ if is_command:+ fm, body = _split_frontmatter(content)+ if fm:+ top_frontmatter_text = fm+ base_frontmatter_text = fm+ content = body++ # Apply composition layers from bottom to top+ for layer in reversed_layers[start_idx:]:+ layer_content = layer["path"].read_text(encoding="utf-8")+ strategy = layer["strategy"]++ if is_command:+ fm, layer_body = _split_frontmatter(layer_content)+ layer_content = layer_body+ # Track the highest-priority frontmatter seen;+ # replace layers reset both top and base frontmatter since+ # they replace the entire command including metadata.+ if strategy == "replace":+ top_frontmatter_text = fm+ base_frontmatter_text = fm+ elif fm:+ top_frontmatter_text = fm++ if strategy == "replace":+ content = layer_content+ elif strategy == "prepend":+ content = layer_content + "\n\n" + content+ elif strategy == "append":+ content = content + "\n\n" + layer_content+ elif strategy == "wrap":+ if template_type == "script":+ placeholder = "$CORE_SCRIPT"+ else:+ placeholder = "{CORE_TEMPLATE}"+ if placeholder not in layer_content:+ raise PresetValidationError(+ f"Wrap strategy in '{layer['source']}' is missing "+ f"the {placeholder} placeholder. The wrapper must "+ f"contain {placeholder} to indicate where the "+ f"lower-priority content should be inserted."+ )+ content = layer_content.replace(placeholder, content)++ # Reattach the highest-priority frontmatter for commands,+ # inheriting scripts/agent_scripts from the base if missing+ # and stripping the strategy key (internal-only, not for agent output).+ if is_command and top_frontmatter_text:+ def _parse_fm_yaml(fm_block: str) -> dict:+ """Parse YAML from a frontmatter block (with --- fences)."""+ lines = fm_block.splitlines()+ # Parse only interior lines (between --- fences)+ if len(lines) >= 2:+ yaml_lines = lines[1:-1]+ else:+ yaml_lines = []+ try:+ return yaml.safe_load("\n".join(yaml_lines)) or {}+ except yaml.YAMLError:+ return {}++ top_fm = _parse_fm_yaml(top_frontmatter_text)++ # Inherit scripts/agent_scripts from base frontmatter if missing+ if base_frontmatter_text and base_frontmatter_text != top_frontmatter_text:+ base_fm = _parse_fm_yaml(base_frontmatter_text)+ for key in ("scripts", "agent_scripts"):+ if key not in top_fm and key in base_fm:+ top_fm[key] = base_fm[key]++ # Strip strategy key β it's an internal composition directive,+ # not meant for rendered agent command files+ top_fm.pop("strategy", None)++ if top_fm:+ top_frontmatter_text = (+ "---\n"+ + yaml.safe_dump(top_fm, sort_keys=False).strip()+ + "\n---"+ )+ else:+ # Empty frontmatter β omit rather than emitting {}+ top_frontmatter_text = None++ if top_frontmatter_text:+ content = top_frontmatter_text + "\n\n" + content++ return contentdiff --git a/tests/test_presets.py b/tests/test_presets.pyindex d913c3b19..64bdc1f0b 100644--- a/tests/test_presets.py+++ b/tests/test_presets.py@@ -3666,647 +3666,736 @@ def _make_wrap_preset_dir(return preset_dir-class TestReplayWrapsForCommand:- """Tests for PresetManager._replay_wraps_for_command()."""- def test_replay_no_op_when_no_wrap_presets(self, project_dir):- """replay does nothing when no presets declare wrap_commands for the command."""- manager = PresetManager(project_dir)- # Should not raise- manager._replay_wraps_for_command("speckit.specify")-- def test_replay_no_op_when_core_missing(self, project_dir, temp_dir):- """replay exits gracefully when resolve_core returns None."""- from specify_cli.agents import CommandRegistrar- import copy-- preset_dir = _make_wrap_preset_dir(temp_dir, "preset-a", "speckit.nonexistent-cmd", "pre-a", "post-a")- installed = project_dir / ".specify" / "presets" / "preset-a"- import shutil as _shutil- _shutil.copytree(preset_dir, installed)+class TestCompositionStrategyValidation:+ """Test strategy field validation in PresetManifest."""- manager = PresetManager(project_dir)- manager.registry.add("preset-a", {- "version": "1.0.0", "source": "local", "enabled": True,- "priority": 10, "manifest_hash": "x",- "registered_commands": {}, "registered_skills": [],- "wrap_commands": ["speckit.nonexistent-cmd"],- })+ def test_valid_replace_strategy(self, temp_dir, valid_pack_data):+ """Test that replace strategy is accepted."""+ valid_pack_data["provides"]["templates"][0]["strategy"] = "replace"+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ (temp_dir / "templates").mkdir(exist_ok=True)+ (temp_dir / "templates" / "spec-template.md").write_text("test")+ manifest = PresetManifest(manifest_path)+ assert manifest.templates[0]["strategy"] == "replace"- agent_dir = project_dir / ".claude" / "commands"- agent_dir.mkdir(parents=True)+ def test_valid_prepend_strategy(self, temp_dir, valid_pack_data):+ """Test that prepend strategy is accepted for templates."""+ valid_pack_data["provides"]["templates"][0]["strategy"] = "prepend"+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ (temp_dir / "templates").mkdir(exist_ok=True)+ (temp_dir / "templates" / "spec-template.md").write_text("test")+ manifest = PresetManifest(manifest_path)+ assert manifest.templates[0]["strategy"] == "prepend"- registrar = CommandRegistrar()- original = copy.deepcopy(registrar.AGENT_CONFIGS)- registrar.AGENT_CONFIGS["test-agent"] = {- "dir": str(agent_dir.relative_to(project_dir)),- "format": "markdown", "args": "$ARGUMENTS",- "extension": ".md", "strip_frontmatter_keys": [],- }- try:- # No core file exists for this command β replay should return without writing- manager._replay_wraps_for_command("speckit.nonexistent-cmd")- finally:- CommandRegistrar.AGENT_CONFIGS.clear()- CommandRegistrar.AGENT_CONFIGS.update(original)+ def test_valid_append_strategy(self, temp_dir, valid_pack_data):+ """Test that append strategy is accepted for templates."""+ valid_pack_data["provides"]["templates"][0]["strategy"] = "append"+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ (temp_dir / "templates").mkdir(exist_ok=True)+ (temp_dir / "templates" / "spec-template.md").write_text("test")+ manifest = PresetManifest(manifest_path)+ assert manifest.templates[0]["strategy"] == "append"- assert not (agent_dir / "speckit.nonexistent-cmd.md").exists()+ def test_valid_wrap_strategy(self, temp_dir, valid_pack_data):+ """Test that wrap strategy is accepted for templates."""+ valid_pack_data["provides"]["templates"][0]["strategy"] = "wrap"+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ (temp_dir / "templates").mkdir(exist_ok=True)+ (temp_dir / "templates" / "spec-template.md").write_text("test")+ manifest = PresetManifest(manifest_path)+ assert manifest.templates[0]["strategy"] == "wrap"- def test_replay_single_preset_writes_composed_output(self, project_dir, temp_dir):- """Single wrap preset: replay writes pre + core + post to agent dirs."""- from specify_cli.agents import CommandRegistrar- import copy, shutil as _shutil+ def test_default_strategy_is_replace(self, pack_dir):+ """Test that omitting strategy defaults to replace (key is absent)."""+ manifest = PresetManifest(pack_dir / "preset.yml")+ # Strategy key should not be present in the manifest data+ assert "strategy" not in manifest.templates[0]+ # But consumers should treat missing strategy as "replace"+ assert manifest.templates[0].get("strategy", "replace") == "replace"++ def test_invalid_strategy_rejected(self, temp_dir, valid_pack_data):+ """Test that invalid strategy values are rejected."""+ valid_pack_data["provides"]["templates"][0]["strategy"] = "merge"+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ with pytest.raises(PresetValidationError, match="Invalid strategy"):+ PresetManifest(manifest_path)- # Core template- core_dir = project_dir / ".specify" / "templates" / "commands"- core_dir.mkdir(parents=True, exist_ok=True)- (core_dir / "specify.md").write_text("---\ndescription: core\n---\n\ncore body\n")+ def test_prepend_rejected_for_scripts(self, temp_dir, valid_pack_data):+ """Test that prepend strategy is rejected for scripts."""+ valid_pack_data["provides"]["templates"] = [{+ "type": "script",+ "name": "create-new-feature",+ "file": "scripts/create-new-feature.sh",+ "strategy": "prepend",+ }]+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ with pytest.raises(PresetValidationError, match="Invalid strategy.*for script"):+ PresetManifest(manifest_path)- # Install preset-a- preset_dir = _make_wrap_preset_dir(temp_dir, "preset-a", "speckit.specify", "pre-a", "post-a")- installed = project_dir / ".specify" / "presets" / "preset-a"- _shutil.copytree(preset_dir, installed)+ def test_append_rejected_for_scripts(self, temp_dir, valid_pack_data):+ """Test that append strategy is rejected for scripts."""+ valid_pack_data["provides"]["templates"] = [{+ "type": "script",+ "name": "create-new-feature",+ "file": "scripts/create-new-feature.sh",+ "strategy": "append",+ }]+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ with pytest.raises(PresetValidationError, match="Invalid strategy.*for script"):+ PresetManifest(manifest_path)- manager = PresetManager(project_dir)- manager.registry.add("preset-a", {- "version": "1.0.0", "source": "local", "enabled": True,- "priority": 10, "manifest_hash": "x",- "registered_commands": {}, "registered_skills": [],- "wrap_commands": ["speckit.specify"],- })+ def test_wrap_accepted_for_scripts(self, temp_dir, valid_pack_data):+ """Test that wrap strategy is accepted for scripts."""+ valid_pack_data["provides"]["templates"] = [{+ "type": "script",+ "name": "create-new-feature",+ "file": "scripts/create-new-feature.sh",+ "strategy": "wrap",+ }]+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ manifest = PresetManifest(manifest_path)+ assert manifest.templates[0]["strategy"] == "wrap"++ def test_replace_accepted_for_scripts(self, temp_dir, valid_pack_data):+ """Test that replace strategy is accepted for scripts."""+ valid_pack_data["provides"]["templates"] = [{+ "type": "script",+ "name": "create-new-feature",+ "file": "scripts/create-new-feature.sh",+ "strategy": "replace",+ }]+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ manifest = PresetManifest(manifest_path)+ assert manifest.templates[0]["strategy"] == "replace"++ def test_prepend_accepted_for_commands(self, temp_dir, valid_pack_data):+ """Test that prepend strategy is accepted for commands."""+ valid_pack_data["provides"]["templates"] = [{+ "type": "command",+ "name": "speckit.specify",+ "file": "commands/speckit.specify.md",+ "strategy": "prepend",+ }]+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ manifest = PresetManifest(manifest_path)+ assert manifest.templates[0]["strategy"] == "prepend"- agent_dir = project_dir / ".claude" / "commands"- agent_dir.mkdir(parents=True)- registrar = CommandRegistrar()- original = copy.deepcopy(registrar.AGENT_CONFIGS)- registrar.AGENT_CONFIGS["test-agent"] = {- "dir": str(agent_dir.relative_to(project_dir)),- "format": "markdown", "args": "$ARGUMENTS",- "extension": ".md", "strip_frontmatter_keys": [],- }- try:- manager._replay_wraps_for_command("speckit.specify")- finally:- CommandRegistrar.AGENT_CONFIGS.clear()- CommandRegistrar.AGENT_CONFIGS.update(original)- written = (agent_dir / "speckit.specify.md").read_text()- assert "[pre-a]" in written- assert "core body" in written- assert "[post-a]" in written- assert "{CORE_TEMPLATE}" not in written- assert "strategy" not in written+class TestResolveContent:+ """Test PresetResolver.resolve_content() composition."""- def test_replay_uses_manifest_command_file_mapping(self, project_dir, temp_dir):- """Replay reads wrapper files from preset.yml instead of assuming command-name paths."""- from specify_cli.agents import CommandRegistrar- import copy, shutil as _shutil+ def test_resolve_content_core_template(self, project_dir):+ """Test resolve_content returns core template when no composition."""+ resolver = PresetResolver(project_dir)+ content = resolver.resolve_content("spec-template")+ assert content is not None+ assert "Core Spec Template" in content- core_dir = project_dir / ".specify" / "templates" / "commands"- core_dir.mkdir(parents=True, exist_ok=True)- (core_dir / "specify.md").write_text("---\ndescription: core\n---\n\nCORE\n")-- preset_dir = _make_wrap_preset_dir(- temp_dir,- "preset-a",- "speckit.specify",- "pre-a",- "post-a",- file_rel="commands/custom-wrapper.md",- )- installed = project_dir / ".specify" / "presets" / "preset-a"- _shutil.copytree(preset_dir, installed)+ def test_resolve_content_nonexistent(self, project_dir):+ """Test resolve_content returns None for nonexistent template."""+ resolver = PresetResolver(project_dir)+ content = resolver.resolve_content("nonexistent")+ assert content is None+ def test_resolve_content_replace_strategy(self, project_dir, temp_dir, valid_pack_data):+ """Test resolve_content with default replace strategy."""manager = PresetManager(project_dir)- manager.registry.add("preset-a", {- "version": "1.0.0", "source": "local", "enabled": True,- "priority": 10, "manifest_hash": "x",- "registered_commands": {}, "registered_skills": [],- "wrap_commands": ["speckit.specify"],- })+ manager.install_from_directory(+ _create_pack(temp_dir, valid_pack_data, "replace-pack",+ "# Replaced Content\n"),+ "0.1.5"+ )- agent_dir = project_dir / ".claude" / "commands"- agent_dir.mkdir(parents=True)- registrar = CommandRegistrar()- original = copy.deepcopy(registrar.AGENT_CONFIGS)- registrar.AGENT_CONFIGS["test-agent"] = {- "dir": str(agent_dir.relative_to(project_dir)),- "format": "markdown", "args": "$ARGUMENTS",- "extension": ".md", "strip_frontmatter_keys": [],+ resolver = PresetResolver(project_dir)+ content = resolver.resolve_content("spec-template")+ assert content is not None+ assert "Replaced Content" in content+ assert "Core Spec Template" not in content++ def test_resolve_content_append_strategy(self, project_dir, temp_dir, valid_pack_data):+ """Test resolve_content with append strategy."""+ pack_data = {**valid_pack_data}+ pack_data["preset"] = {**valid_pack_data["preset"], "id": "append-pack", "name": "Append"}+ pack_data["provides"] = {+ "templates": [{+ "type": "template",+ "name": "spec-template",+ "file": "templates/spec-template.md",+ "strategy": "append",+ }]}- try:- manager._replay_wraps_for_command("speckit.specify")- finally:- CommandRegistrar.AGENT_CONFIGS.clear()- CommandRegistrar.AGENT_CONFIGS.update(original)+ pack_dir = temp_dir / "append-pack"+ pack_dir.mkdir()+ with open(pack_dir / "preset.yml", 'w') as f:+ yaml.dump(pack_data, f)+ (pack_dir / "templates").mkdir()+ (pack_dir / "templates" / "spec-template.md").write_text("## Appended Section\n")- written = (agent_dir / "speckit.specify.md").read_text()- assert "[pre-a]" in written- assert "CORE" in written- assert "[post-a]" in written+ manager = PresetManager(project_dir)+ manager.install_from_directory(pack_dir, "0.1.5")- def test_replay_resolves_extension_core_via_manifest_mapping(self, project_dir, temp_dir):- """Replay finds extension core commands whose manifest file differs from command name."""- from specify_cli.agents import CommandRegistrar- import copy, shutil as _shutil+ resolver = PresetResolver(project_dir)+ content = resolver.resolve_content("spec-template")+ assert content is not None+ assert "Core Spec Template" in content+ assert "Appended Section" in content+ # Core should come first, appended after+ assert content.index("Core Spec Template") < content.index("Appended Section")++ def test_resolve_content_prepend_strategy(self, project_dir, temp_dir, valid_pack_data):+ """Test resolve_content with prepend strategy."""+ pack_data = {**valid_pack_data}+ pack_data["preset"] = {**valid_pack_data["preset"], "id": "prepend-pack", "name": "Prepend"}+ pack_data["provides"] = {+ "templates": [{+ "type": "template",+ "name": "spec-template",+ "file": "templates/spec-template.md",+ "strategy": "prepend",+ }]+ }+ pack_dir = temp_dir / "prepend-pack"+ pack_dir.mkdir()+ with open(pack_dir / "preset.yml", 'w') as f:+ yaml.dump(pack_data, f)+ (pack_dir / "templates").mkdir()+ (pack_dir / "templates" / "spec-template.md").write_text("## Security Header\n")- ext_dir = project_dir / ".specify" / "extensions" / "selftest"- cmd_dir = ext_dir / "commands"- cmd_dir.mkdir(parents=True, exist_ok=True)- (cmd_dir / "selftest.md").write_text(- "---\ndescription: selftest core\n---\n\nEXTENSION-CORE\n"- )- (ext_dir / "extension.yml").write_text(- "schema_version: '1.0'\n"- "extension:\n id: selftest\n name: Self-Test\n version: 1.0.0\n"- " description: test\n author: test\n repository: https://example.com\n"- " license: MIT\n"- "requires:\n speckit_version: '>=0.2.0'\n"- "provides:\n"- " commands:\n"- " - name: speckit.selftest.extension\n"- " file: commands/selftest.md\n"- " description: Selftest command\n"- )+ manager = PresetManager(project_dir)+ manager.install_from_directory(pack_dir, "0.1.5")- preset_dir = _make_wrap_preset_dir(- temp_dir, "preset-a", "speckit.selftest.extension", "pre-a", "post-a"+ resolver = PresetResolver(project_dir)+ content = resolver.resolve_content("spec-template")+ assert content is not None+ assert "Security Header" in content+ assert "Core Spec Template" in content+ # Prepended content should come first+ assert content.index("Security Header") < content.index("Core Spec Template")++ def test_resolve_content_wrap_strategy(self, project_dir, temp_dir, valid_pack_data):+ """Test resolve_content with wrap strategy for templates."""+ pack_data = {**valid_pack_data}+ pack_data["preset"] = {**valid_pack_data["preset"], "id": "wrap-pack", "name": "Wrap"}+ pack_data["provides"] = {+ "templates": [{+ "type": "template",+ "name": "spec-template",+ "file": "templates/spec-template.md",+ "strategy": "wrap",+ }]+ }+ pack_dir = temp_dir / "wrap-pack"+ pack_dir.mkdir()+ with open(pack_dir / "preset.yml", 'w') as f:+ yaml.dump(pack_data, f)+ (pack_dir / "templates").mkdir()+ (pack_dir / "templates" / "spec-template.md").write_text(+ "# Wrapper Start\n\n{CORE_TEMPLATE}\n\n# Wrapper End\n")- installed = project_dir / ".specify" / "presets" / "preset-a"- _shutil.copytree(preset_dir, installed)manager = PresetManager(project_dir)- manager.registry.add("preset-a", {- "version": "1.0.0", "source": "local", "enabled": True,- "priority": 10, "manifest_hash": "x",- "registered_commands": {}, "registered_skills": [],- "wrap_commands": ["speckit.selftest.extension"],- })+ manager.install_from_directory(pack_dir, "0.1.5")- agent_dir = project_dir / ".claude" / "commands"- agent_dir.mkdir(parents=True)- registrar = CommandRegistrar()- original = copy.deepcopy(registrar.AGENT_CONFIGS)- registrar.AGENT_CONFIGS["test-agent"] = {- "dir": str(agent_dir.relative_to(project_dir)),- "format": "markdown", "args": "$ARGUMENTS",- "extension": ".md", "strip_frontmatter_keys": [],+ resolver = PresetResolver(project_dir)+ content = resolver.resolve_content("spec-template")+ assert content is not None+ assert "Wrapper Start" in content+ assert "Core Spec Template" in content+ assert "Wrapper End" in content+ # Wrapper should surround core+ assert content.index("Wrapper Start") < content.index("Core Spec Template")+ assert content.index("Core Spec Template") < content.index("Wrapper End")++ def test_resolve_content_wrap_strategy_script(self, project_dir, temp_dir, valid_pack_data):+ """Test resolve_content with wrap strategy for scripts uses $CORE_SCRIPT."""+ # Create core script+ scripts_dir = project_dir / ".specify" / "templates" / "scripts"+ scripts_dir.mkdir(parents=True, exist_ok=True)+ (scripts_dir / "test-script.sh").write_text("echo 'core script'\n")++ pack_data = {**valid_pack_data}+ pack_data["preset"] = {**valid_pack_data["preset"], "id": "script-wrap", "name": "Script Wrap"}+ pack_data["provides"] = {+ "templates": [{+ "type": "script",+ "name": "test-script",+ "file": "scripts/test-script.sh",+ "strategy": "wrap",+ }]}- try:- manager._replay_wraps_for_command("speckit.selftest.extension")- finally:- CommandRegistrar.AGENT_CONFIGS.clear()- CommandRegistrar.AGENT_CONFIGS.update(original)-- written = (agent_dir / "speckit.selftest.extension.md").read_text()- assert "[pre-a]" in written- assert "EXTENSION-CORE" in written- assert "[post-a]" in written-- def test_replay_priority_order_lower_number_outermost(self, project_dir, temp_dir):- """Two wrap presets: lower priority number = outermost wrapper."""- from specify_cli.agents import CommandRegistrar- import copy, shutil as _shutil-- core_dir = project_dir / ".specify" / "templates" / "commands"- core_dir.mkdir(parents=True, exist_ok=True)- (core_dir / "specify.md").write_text("---\ndescription: core\n---\n\nCORE\n")-- for pid in ("preset-outer", "preset-inner"):- src = _make_wrap_preset_dir(temp_dir, pid, "speckit.specify", f"pre-{pid}", f"post-{pid}")- _shutil.copytree(src, project_dir / ".specify" / "presets" / pid)+ pack_dir = temp_dir / "script-wrap"+ pack_dir.mkdir()+ with open(pack_dir / "preset.yml", 'w') as f:+ yaml.dump(pack_data, f)+ (pack_dir / "scripts").mkdir()+ (pack_dir / "scripts" / "test-script.sh").write_text(+ "#!/bin/bash\necho 'before'\n$CORE_SCRIPT\necho 'after'\n"+ )manager = PresetManager(project_dir)- # preset-outer has priority 1 (highest precedence = outermost)- # preset-inner has priority 10 (lowest precedence = innermost)- for pid, pri in (("preset-outer", 1), ("preset-inner", 10)):- manager.registry.add(pid, {- "version": "1.0.0", "source": "local", "enabled": True,- "priority": pri, "manifest_hash": "x",- "registered_commands": {}, "registered_skills": [],- "wrap_commands": ["speckit.specify"],- })+ manager.install_from_directory(pack_dir, "0.1.5")- agent_dir = project_dir / ".claude" / "commands"- agent_dir.mkdir(parents=True)- registrar = CommandRegistrar()- original = copy.deepcopy(registrar.AGENT_CONFIGS)- registrar.AGENT_CONFIGS["test-agent"] = {- "dir": str(agent_dir.relative_to(project_dir)),- "format": "markdown", "args": "$ARGUMENTS",- "extension": ".md", "strip_frontmatter_keys": [],+ resolver = PresetResolver(project_dir)+ content = resolver.resolve_content("test-script", "script")+ assert content is not None+ assert "echo 'before'" in content+ assert "echo 'core script'" in content+ assert "echo 'after'" in content++ def test_resolve_content_multi_preset_chain(self, project_dir, temp_dir, valid_pack_data):+ """Test multi-preset composition chain: prepend + append stacking."""+ # Create preset A (priority 1): prepend security header+ pack_a_data = {**valid_pack_data}+ pack_a_data["preset"] = {**valid_pack_data["preset"], "id": "preset-a", "name": "A"}+ pack_a_data["provides"] = {+ "templates": [{+ "type": "template",+ "name": "spec-template",+ "file": "templates/spec-template.md",+ "strategy": "prepend",+ }]}- try:- manager._replay_wraps_for_command("speckit.specify")- finally:- CommandRegistrar.AGENT_CONFIGS.clear()- CommandRegistrar.AGENT_CONFIGS.update(original)-- written = (agent_dir / "speckit.specify.md").read_text()- # Outermost (preset-outer, p=1) wraps everything; innermost (preset-inner, p=10) is next- outer_pre = written.index("[pre-preset-outer]")- inner_pre = written.index("[pre-preset-inner]")- core_pos = written.index("CORE")- inner_post = written.index("[post-preset-inner]")- outer_post = written.index("[post-preset-outer]")- assert outer_pre < inner_pre < core_pos < inner_post < outer_post-- def test_replay_install_order_independent(self, project_dir, temp_dir):- """Nesting order is determined by priority, not install order."""- from specify_cli.agents import CommandRegistrar- import copy, shutil as _shutil-- core_dir = project_dir / ".specify" / "templates" / "commands"- core_dir.mkdir(parents=True, exist_ok=True)- (core_dir / "specify.md").write_text("---\ndescription: core\n---\n\nCORE\n")-- for pid in ("preset-a", "preset-b"):- src = _make_wrap_preset_dir(temp_dir, pid, "speckit.specify", f"pre-{pid}", f"post-{pid}")- _shutil.copytree(src, project_dir / ".specify" / "presets" / pid)+ pack_a_dir = temp_dir / "preset-a"+ pack_a_dir.mkdir()+ with open(pack_a_dir / "preset.yml", 'w') as f:+ yaml.dump(pack_a_data, f)+ (pack_a_dir / "templates").mkdir()+ (pack_a_dir / "templates" / "spec-template.md").write_text("## Security Header\n")++ # Create preset B (priority 2): append compliance footer+ pack_b_data = {**valid_pack_data}+ pack_b_data["preset"] = {**valid_pack_data["preset"], "id": "preset-b", "name": "B"}+ pack_b_data["provides"] = {+ "templates": [{+ "type": "template",+ "name": "spec-template",+ "file": "templates/spec-template.md",+ "strategy": "append",+ }]+ }+ pack_b_dir = temp_dir / "preset-b"+ pack_b_dir.mkdir()+ with open(pack_b_dir / "preset.yml", 'w') as f:+ yaml.dump(pack_b_data, f)+ (pack_b_dir / "templates").mkdir()+ (pack_b_dir / "templates" / "spec-template.md").write_text("## Compliance Footer\n")manager = PresetManager(project_dir)- # preset-a priority=5 (outermost), preset-b priority=10 (innermost)- # Install in reverse order to verify install order doesn't affect nesting- for pid, pri in (("preset-b", 10), ("preset-a", 5)):- manager.registry.add(pid, {- "version": "1.0.0", "source": "local", "enabled": True,- "priority": pri, "manifest_hash": "x",- "registered_commands": {}, "registered_skills": [],- "wrap_commands": ["speckit.specify"],- })+ manager.install_from_directory(pack_a_dir, "0.1.5", priority=1)+ manager.install_from_directory(pack_b_dir, "0.1.5", priority=2)- agent_dir = project_dir / ".claude" / "commands"- agent_dir.mkdir(parents=True)- registrar = CommandRegistrar()- original = copy.deepcopy(registrar.AGENT_CONFIGS)- registrar.AGENT_CONFIGS["test-agent"] = {- "dir": str(agent_dir.relative_to(project_dir)),- "format": "markdown", "args": "$ARGUMENTS",- "extension": ".md", "strip_frontmatter_keys": [],+ resolver = PresetResolver(project_dir)+ content = resolver.resolve_content("spec-template")+ assert content is not None+ # Result: <security header> + <core> + <compliance footer>+ assert "Security Header" in content+ assert "Core Spec Template" in content+ assert "Compliance Footer" in content+ assert content.index("Security Header") < content.index("Core Spec Template")+ assert content.index("Core Spec Template") < content.index("Compliance Footer")++ def test_resolve_content_override_trumps_composition(self, project_dir, temp_dir, valid_pack_data):+ """Test that project overrides trump composition (replace at top priority)."""+ # Install a composing preset+ pack_data = {**valid_pack_data}+ pack_data["preset"] = {**valid_pack_data["preset"], "id": "append-pack", "name": "Append"}+ pack_data["provides"] = {+ "templates": [{+ "type": "template",+ "name": "spec-template",+ "file": "templates/spec-template.md",+ "strategy": "append",+ }]}- try:- manager._replay_wraps_for_command("speckit.specify")- finally:- CommandRegistrar.AGENT_CONFIGS.clear()- CommandRegistrar.AGENT_CONFIGS.update(original)-- written = (agent_dir / "speckit.specify.md").read_text()- a_pre = written.index("[pre-preset-a]")- b_pre = written.index("[pre-preset-b]")- core_pos = written.index("CORE")- b_post = written.index("[post-preset-b]")- a_post = written.index("[post-preset-a]")- # preset-a (p=5) is outermost regardless of install order- assert a_pre < b_pre < core_pos < b_post < a_post-- def test_replay_updates_skill_outputs(self, project_dir, temp_dir):- """Replay also rewrites SKILL.md-backed agent outputs."""- import json- import shutil as _shutil-- core_dir = project_dir / ".specify" / "templates" / "commands"- core_dir.mkdir(parents=True, exist_ok=True)- (core_dir / "specify.md").write_text("---\ndescription: core\n---\n\nCORE\n")-- preset_dir = _make_wrap_preset_dir(temp_dir, "preset-a", "speckit.specify", "pre-a", "post-a")- _shutil.copytree(preset_dir, project_dir / ".specify" / "presets" / "preset-a")+ pack_dir = temp_dir / "append-pack"+ pack_dir.mkdir()+ with open(pack_dir / "preset.yml", 'w') as f:+ yaml.dump(pack_data, f)+ (pack_dir / "templates").mkdir()+ (pack_dir / "templates" / "spec-template.md").write_text("## Appended\n")manager = PresetManager(project_dir)- manager.registry.add("preset-a", {- "version": "1.0.0", "source": "local", "enabled": True,- "priority": 10, "manifest_hash": "x",- "registered_commands": {}, "registered_skills": [],- "wrap_commands": ["speckit.specify"],- })-- skills_dir = project_dir / ".claude" / "skills"- skill_subdir = skills_dir / "speckit-specify"- skill_subdir.mkdir(parents=True)- (skill_subdir / "SKILL.md").write_text("---\nname: speckit-specify\n---\n\nold\n")- (project_dir / ".specify" / "init-options.json").write_text(- json.dumps({"ai": "claude", "ai_skills": True})- )-- manager._replay_wraps_for_command("speckit.specify")-- written = (skill_subdir / "SKILL.md").read_text()- assert "[pre-a]" in written- assert "CORE" in written- assert "[post-a]" in written-- def test_replay_applies_integration_post_processing_to_skill(self, project_dir, temp_dir):- """_replay_skill_override must call post_process_skill_content, matching _register_skills."""- import json- import shutil as _shutil+ manager.install_from_directory(pack_dir, "0.1.5")- core_dir = project_dir / ".specify" / "templates" / "commands"- core_dir.mkdir(parents=True, exist_ok=True)- (core_dir / "specify.md").write_text("---\ndescription: core\n---\n\nCORE\n")+ # Create project override (replaces everything)+ overrides_dir = project_dir / ".specify" / "templates" / "overrides"+ overrides_dir.mkdir(parents=True)+ (overrides_dir / "spec-template.md").write_text("# Override Only\n")- preset_dir = _make_wrap_preset_dir(temp_dir, "preset-a", "speckit.specify", "pre-a", "post-a")- _shutil.copytree(preset_dir, project_dir / ".specify" / "presets" / "preset-a")+ resolver = PresetResolver(project_dir)+ content = resolver.resolve_content("spec-template")+ assert content is not None+ assert "Override Only" in content+ # Override replaces, so appended content should not be visible+ assert "Core Spec Template" not in content++ def test_resolve_content_command_type(self, project_dir, temp_dir, valid_pack_data):+ """Test resolve_content with command template type."""+ # Create core command using stem naming (matches real layout: plan.md, not speckit.plan.md)+ commands_dir = project_dir / ".specify" / "templates" / "commands"+ commands_dir.mkdir(parents=True, exist_ok=True)+ (commands_dir / "plan.md").write_text("# Core Plan Command\n")++ pack_data = {**valid_pack_data}+ pack_data["preset"] = {**valid_pack_data["preset"], "id": "cmd-append", "name": "CmdAppend"}+ pack_data["provides"] = {+ "templates": [{+ "type": "command",+ "name": "speckit.plan",+ "file": "commands/speckit.plan.md",+ "strategy": "append",+ }]+ }+ pack_dir = temp_dir / "cmd-append"+ pack_dir.mkdir()+ with open(pack_dir / "preset.yml", 'w') as f:+ yaml.dump(pack_data, f)+ (pack_dir / "commands").mkdir()+ (pack_dir / "commands" / "speckit.plan.md").write_text("## Additional Instructions\n")manager = PresetManager(project_dir)- manager.registry.add("preset-a", {- "version": "1.0.0", "source": "local", "enabled": True,- "priority": 10, "manifest_hash": "x",- "registered_commands": {}, "registered_skills": [],- "wrap_commands": ["speckit.specify"],- })+ manager.install_from_directory(pack_dir, "0.1.5")- skills_dir = project_dir / ".claude" / "skills"- skill_subdir = skills_dir / "speckit-specify"- skill_subdir.mkdir(parents=True)- (skill_subdir / "SKILL.md").write_text("---\nname: speckit-specify\n---\n\nold\n")- (project_dir / ".specify" / "init-options.json").write_text(- json.dumps({"ai": "claude", "ai_skills": True})+ resolver = PresetResolver(project_dir)+ content = resolver.resolve_content("speckit.plan", "command")+ assert content is not None+ assert "Core Plan Command" in content+ assert "Additional Instructions" in content++ def test_resolve_content_command_frontmatter_stripping(self, project_dir, temp_dir, valid_pack_data):+ """Test that command composition strips frontmatter from lower layers+ and reattaches only the highest-priority frontmatter."""+ # Create core command with frontmatter+ commands_dir = project_dir / ".specify" / "templates" / "commands"+ commands_dir.mkdir(parents=True, exist_ok=True)+ (commands_dir / "check.md").write_text(+ "---\ndescription: Core check command\n---\nCore body content\n")- manager._replay_wraps_for_command("speckit.specify")-- # ClaudeIntegration.post_process_skill_content injects these flags.- # Their presence proves the integration hook ran during replay.- written = (skill_subdir / "SKILL.md").read_text()- assert "disable-model-invocation: false" in written, (- "_replay_skill_override must call post_process_skill_content "- "(same as _register_skills)"+ pack_data = {**valid_pack_data}+ pack_data["preset"] = {**valid_pack_data["preset"], "id": "fm-test", "name": "FmTest"}+ pack_data["provides"] = {+ "templates": [{+ "type": "command",+ "name": "speckit.check",+ "file": "commands/speckit.check.md",+ "strategy": "append",+ }]+ }+ pack_dir = temp_dir / "fm-test"+ pack_dir.mkdir()+ with open(pack_dir / "preset.yml", 'w') as f:+ yaml.dump(pack_data, f)+ (pack_dir / "commands").mkdir()+ (pack_dir / "commands" / "speckit.check.md").write_text(+ "---\ndescription: Preset check override\n---\nPreset body content\n")+ manager = PresetManager(project_dir)+ manager.install_from_directory(pack_dir, "0.1.5")-class TestInstallRemoveWrapLifecycle:- """Tests for wrap_commands stored on install and replayed on remove."""-- def _setup_agent(self, project_dir, registrar, agent_configs_dict):- """Register a test markdown agent and return its commands dir."""- agent_dir = project_dir / ".claude" / "commands"- agent_dir.mkdir(parents=True, exist_ok=True)- agent_configs_dict["test-agent"] = {- "dir": str(agent_dir.relative_to(project_dir)),- "format": "markdown", "args": "$ARGUMENTS",- "extension": ".md", "strip_frontmatter_keys": [],+ resolver = PresetResolver(project_dir)+ content = resolver.resolve_content("speckit.check", "command")+ assert content is not None+ # Should have the preset (highest-priority) frontmatter+ assert "Preset check override" in content+ # Should have both bodies+ assert "Core body content" in content+ assert "Preset body content" in content+ # Core frontmatter should NOT appear in the body+ assert content.count("---") == 2 # only one frontmatter block (opening + closing)++ def test_resolve_content_blank_line_separator(self, project_dir, temp_dir, valid_pack_data):+ """Test that prepend/append use blank line separator."""+ pack_data = {**valid_pack_data}+ pack_data["preset"] = {**valid_pack_data["preset"], "id": "sep-test", "name": "SepTest"}+ pack_data["provides"] = {+ "templates": [{+ "type": "template",+ "name": "spec-template",+ "file": "templates/spec-template.md",+ "strategy": "append",+ }]}- return agent_dir+ pack_dir = temp_dir / "sep-test"+ pack_dir.mkdir()+ with open(pack_dir / "preset.yml", 'w') as f:+ yaml.dump(pack_data, f)+ (pack_dir / "templates").mkdir()+ (pack_dir / "templates" / "spec-template.md").write_text("appended")- def test_install_stores_wrap_commands_in_registry(self, project_dir, temp_dir):- """install_from_directory stores wrap_commands in the registry entry."""- from specify_cli.agents import CommandRegistrar- import copy-- core_dir = project_dir / ".specify" / "templates" / "commands"- core_dir.mkdir(parents=True, exist_ok=True)- (core_dir / "specify.md").write_text("---\ndescription: core\n---\n\ncore\n")-- preset_src = _make_wrap_preset_dir(temp_dir, "preset-a", "speckit.specify", "pre", "post")+ manager = PresetManager(project_dir)+ manager.install_from_directory(pack_dir, "0.1.5")- registrar = CommandRegistrar()- original = copy.deepcopy(registrar.AGENT_CONFIGS)- agent_dir = project_dir / ".claude" / "commands"- agent_dir.mkdir(parents=True, exist_ok=True)- registrar.AGENT_CONFIGS["test-agent"] = {- "dir": str(agent_dir.relative_to(project_dir)),- "format": "markdown", "args": "$ARGUMENTS",- "extension": ".md", "strip_frontmatter_keys": [],+ resolver = PresetResolver(project_dir)+ content = resolver.resolve_content("spec-template")+ # Should have blank line separator+ assert "\n\n" in content++ def test_resolve_content_replace_over_wrap(self, project_dir, temp_dir, valid_pack_data):+ """Top-priority replace layer should win even if a lower layer uses wrap."""+ # Install a low-priority wrap preset (with no placeholder β would fail if evaluated)+ wrap_data = {**valid_pack_data}+ wrap_data["preset"] = {**valid_pack_data["preset"], "id": "wrap-lo", "name": "WrapLo"}+ wrap_data["provides"] = {+ "templates": [{+ "type": "template",+ "name": "spec-template",+ "file": "templates/spec-template.md",+ "strategy": "wrap",+ }]}- try:- manager = PresetManager(project_dir)- manager.install_from_directory(preset_src, "0.1.0", priority=10)- finally:- CommandRegistrar.AGENT_CONFIGS.clear()- CommandRegistrar.AGENT_CONFIGS.update(original)-- meta = manager.registry.get("preset-a")- assert "wrap_commands" in meta- assert "speckit.specify" in meta["wrap_commands"]-- def test_install_replay_produces_correct_nested_output(self, project_dir, temp_dir):- """After installing two wrap presets, agent file contains correctly nested output."""- from specify_cli.agents import CommandRegistrar- import copy, shutil as _shutil-- core_dir = project_dir / ".specify" / "templates" / "commands"- core_dir.mkdir(parents=True, exist_ok=True)- (core_dir / "specify.md").write_text("---\ndescription: core\n---\n\nCORE\n")+ wrap_dir = temp_dir / "wrap-lo"+ wrap_dir.mkdir()+ with open(wrap_dir / "preset.yml", "w") as f:+ yaml.dump(wrap_data, f)+ (wrap_dir / "templates").mkdir()+ # Intentionally missing {CORE_TEMPLATE} β would error if composition ran+ (wrap_dir / "templates" / "spec-template.md").write_text("wrapper without placeholder")- registrar = CommandRegistrar()- original = copy.deepcopy(registrar.AGENT_CONFIGS)- agent_dir = project_dir / ".claude" / "commands"- agent_dir.mkdir(parents=True, exist_ok=True)- registrar.AGENT_CONFIGS["test-agent"] = {- "dir": str(agent_dir.relative_to(project_dir)),- "format": "markdown", "args": "$ARGUMENTS",- "extension": ".md", "strip_frontmatter_keys": [],+ manager = PresetManager(project_dir)+ manager.install_from_directory(wrap_dir, "0.1.5", priority=10)++ # Install a high-priority replace preset+ rep_data = {**valid_pack_data}+ rep_data["preset"] = {**valid_pack_data["preset"], "id": "rep-hi", "name": "RepHi"}+ rep_data["provides"] = {+ "templates": [{+ "type": "template",+ "name": "spec-template",+ "file": "templates/spec-template.md",+ }]}- try:- manager = PresetManager(project_dir)- # Install outermost first (priority=5), then innermost (priority=10)- outer_src = _make_wrap_preset_dir(temp_dir, "preset-outer", "speckit.specify", "OUTER-PRE", "OUTER-POST")- # Rename to avoid id conflict with fixture- inner_src = _make_wrap_preset_dir(temp_dir, "preset-inner", "speckit.specify", "INNER-PRE", "INNER-POST")- manager.install_from_directory(outer_src, "0.1.0", priority=5)- manager.install_from_directory(inner_src, "0.1.0", priority=10)- finally:- CommandRegistrar.AGENT_CONFIGS.clear()- CommandRegistrar.AGENT_CONFIGS.update(original)-- written = (agent_dir / "speckit.specify.md").read_text()- outer_pre = written.index("OUTER-PRE")- inner_pre = written.index("INNER-PRE")- core_pos = written.index("CORE")- inner_post = written.index("INNER-POST")- outer_post = written.index("OUTER-POST")- assert outer_pre < inner_pre < core_pos < inner_post < outer_post-- def test_remove_replays_remaining_wraps(self, project_dir, temp_dir):- """Removing one wrap preset re-composes the remaining wraps correctly."""- from specify_cli.agents import CommandRegistrar- import copy-- core_dir = project_dir / ".specify" / "templates" / "commands"- core_dir.mkdir(parents=True, exist_ok=True)- (core_dir / "specify.md").write_text("---\ndescription: core\n---\n\nCORE\n")+ rep_dir = temp_dir / "rep-hi"+ rep_dir.mkdir()+ with open(rep_dir / "preset.yml", "w") as f:+ yaml.dump(rep_data, f)+ (rep_dir / "templates").mkdir()+ (rep_dir / "templates" / "spec-template.md").write_text("# Replaced content\n")- registrar = CommandRegistrar()- original = copy.deepcopy(registrar.AGENT_CONFIGS)- agent_dir = project_dir / ".claude" / "commands"- agent_dir.mkdir(parents=True, exist_ok=True)- registrar.AGENT_CONFIGS["test-agent"] = {- "dir": str(agent_dir.relative_to(project_dir)),- "format": "markdown", "args": "$ARGUMENTS",- "extension": ".md", "strip_frontmatter_keys": [],- }- try:- manager = PresetManager(project_dir)- outer_src = _make_wrap_preset_dir(temp_dir, "preset-outer", "speckit.specify", "OUTER-PRE", "OUTER-POST")- inner_src = _make_wrap_preset_dir(temp_dir, "preset-inner", "speckit.specify", "INNER-PRE", "INNER-POST")- manager.install_from_directory(outer_src, "0.1.0", priority=5)- manager.install_from_directory(inner_src, "0.1.0", priority=10)- manager.remove("preset-outer")- finally:- CommandRegistrar.AGENT_CONFIGS.clear()- CommandRegistrar.AGENT_CONFIGS.update(original)+ manager.install_from_directory(rep_dir, "0.1.5", priority=1)- written = (agent_dir / "speckit.specify.md").read_text()- # Only inner wrap remains β should be: INNER-PRE + CORE + INNER-POST, no OUTER- assert "INNER-PRE" in written- assert "CORE" in written- assert "INNER-POST" in written- assert "OUTER-PRE" not in written- assert "OUTER-POST" not in written-- def test_wrap_aliases_are_replayed_and_removed(self, project_dir, temp_dir):- """Replay preserves wrap aliases across install/remove lifecycle changes."""- from specify_cli.agents import CommandRegistrar- import copy+ resolver = PresetResolver(project_dir)+ content = resolver.resolve_content("spec-template")+ assert content == "# Replaced content\n"- core_dir = project_dir / ".specify" / "templates" / "commands"- core_dir.mkdir(parents=True, exist_ok=True)- (core_dir / "specify.md").write_text("---\ndescription: core\n---\n\nCORE\n")- registrar = CommandRegistrar()- original = copy.deepcopy(registrar.AGENT_CONFIGS)- agent_dir = project_dir / ".claude" / "commands"- agent_dir.mkdir(parents=True, exist_ok=True)- registrar.AGENT_CONFIGS["test-agent"] = {- "dir": str(agent_dir.relative_to(project_dir)),- "format": "markdown", "args": "$ARGUMENTS",- "extension": ".md", "strip_frontmatter_keys": [],- }- try:- manager = PresetManager(project_dir)- outer_src = _make_wrap_preset_dir(- temp_dir,- "preset-outer",- "speckit.specify",- "OUTER-PRE",- "OUTER-POST",- aliases=["speckit.alias"],- )- inner_src = _make_wrap_preset_dir(- temp_dir, "preset-inner", "speckit.specify", "INNER-PRE", "INNER-POST"- )- manager.install_from_directory(outer_src, "0.1.0", priority=5)- manager.install_from_directory(inner_src, "0.1.0", priority=10)-- alias_file = agent_dir / "speckit.alias.md"- written = alias_file.read_text()- assert "OUTER-PRE" in written- assert "INNER-PRE" in written- assert "INNER-POST" in written- assert "OUTER-POST" in written-- manager.remove("preset-inner")- written = alias_file.read_text()- assert "OUTER-PRE" in written- assert "OUTER-POST" in written- assert "INNER-PRE" not in written- assert "INNER-POST" not in written-- manager.remove("preset-outer")- finally:- CommandRegistrar.AGENT_CONFIGS.clear()- CommandRegistrar.AGENT_CONFIGS.update(original)+class TestCollectAllLayers:+ """Test PresetResolver.collect_all_layers() method."""- assert not (agent_dir / "speckit.alias.md").exists()+ def test_single_core_layer(self, project_dir):+ """Test collecting layers with only core template."""+ resolver = PresetResolver(project_dir)+ layers = resolver.collect_all_layers("spec-template")+ assert len(layers) == 1+ assert layers[0]["source"] == "core"+ assert layers[0]["strategy"] == "replace"- def test_remove_last_wrap_preset_deletes_agent_file(self, project_dir, temp_dir):- """Removing the only wrap preset deletes the agent command file."""- from specify_cli.agents import CommandRegistrar- import copy+ def test_layers_include_presets(self, project_dir, temp_dir, valid_pack_data):+ """Test that layers include installed preset."""+ manager = PresetManager(project_dir)+ pack_dir = _create_pack(temp_dir, valid_pack_data, "test-pack",+ "# From Pack\n")+ manager.install_from_directory(pack_dir, "0.1.5")- core_dir = project_dir / ".specify" / "templates" / "commands"- core_dir.mkdir(parents=True, exist_ok=True)- (core_dir / "specify.md").write_text("---\ndescription: core\n---\n\nCORE\n")+ resolver = PresetResolver(project_dir)+ layers = resolver.collect_all_layers("spec-template")+ assert len(layers) == 2+ # Highest priority first+ assert "test-pack" in layers[0]["source"]+ assert layers[1]["source"] == "core"++ def test_layers_order_matches_priority(self, project_dir, temp_dir, valid_pack_data):+ """Test that layers are ordered by priority (highest first)."""+ manager = PresetManager(project_dir)+ for pid, prio in [("pack-lo", 10), ("pack-hi", 1)]:+ d = {**valid_pack_data}+ d["preset"] = {**valid_pack_data["preset"], "id": pid, "name": pid}+ p = temp_dir / pid+ p.mkdir()+ with open(p / "preset.yml", 'w') as f:+ yaml.dump(d, f)+ (p / "templates").mkdir()+ (p / "templates" / "spec-template.md").write_text(f"# {pid}\n")+ manager.install_from_directory(p, "0.1.5", priority=prio)- registrar = CommandRegistrar()- original = copy.deepcopy(registrar.AGENT_CONFIGS)- agent_dir = project_dir / ".claude" / "commands"- agent_dir.mkdir(parents=True, exist_ok=True)- registrar.AGENT_CONFIGS["test-agent"] = {- "dir": str(agent_dir.relative_to(project_dir)),- "format": "markdown", "args": "$ARGUMENTS",- "extension": ".md", "strip_frontmatter_keys": [],+ resolver = PresetResolver(project_dir)+ layers = resolver.collect_all_layers("spec-template")+ assert len(layers) == 3 # pack-hi, pack-lo, core+ assert "pack-hi" in layers[0]["source"]+ assert "pack-lo" in layers[1]["source"]+ assert layers[2]["source"] == "core"++ def test_layers_read_strategy_from_manifest(self, project_dir, temp_dir, valid_pack_data):+ """Test that layers read strategy from preset manifest."""+ pack_data = {**valid_pack_data}+ pack_data["preset"] = {**valid_pack_data["preset"], "id": "strat-pack", "name": "Strat"}+ pack_data["provides"] = {+ "templates": [{+ "type": "template",+ "name": "spec-template",+ "file": "templates/spec-template.md",+ "strategy": "append",+ }]}- try:- manager = PresetManager(project_dir)- src = _make_wrap_preset_dir(temp_dir, "preset-only", "speckit.specify", "PRE", "POST")- manager.install_from_directory(src, "0.1.0", priority=10)- assert (agent_dir / "speckit.specify.md").exists()- manager.remove("preset-only")- finally:- CommandRegistrar.AGENT_CONFIGS.clear()- CommandRegistrar.AGENT_CONFIGS.update(original)+ pack_dir = temp_dir / "strat-pack"+ pack_dir.mkdir()+ with open(pack_dir / "preset.yml", 'w') as f:+ yaml.dump(pack_data, f)+ (pack_dir / "templates").mkdir()+ (pack_dir / "templates" / "spec-template.md").write_text("## Footer\n")- assert not (agent_dir / "speckit.specify.md").exists()-- def test_remove_keeps_registry_entry_when_directory_delete_fails(self, project_dir, monkeypatch):- """A failed preset directory delete must not leave files untracked by the registry."""manager = PresetManager(project_dir)- pack_dir = manager.presets_dir / "preset-a"- pack_dir.mkdir(parents=True)- manager.registry.add("preset-a", {- "version": "1.0.0", "source": "local", "enabled": True,- "priority": 10, "manifest_hash": "x",- "registered_commands": {}, "registered_skills": [],- "wrap_commands": [],- })+ manager.install_from_directory(pack_dir, "0.1.5")- def fail_rmtree(_path):- raise OSError("locked")+ resolver = PresetResolver(project_dir)+ layers = resolver.collect_all_layers("spec-template")+ # Preset layer should have strategy=append+ assert layers[0]["strategy"] == "append"+ # Core layer should be replace+ assert layers[1]["strategy"] == "replace"- monkeypatch.setattr(shutil, "rmtree", fail_rmtree)- with pytest.raises(OSError, match="locked"):- manager.remove("preset-a")+class TestRemoveReconciliation:+ """Test that removing a preset re-registers the next layer's command."""- assert manager.registry.is_installed("preset-a")- assert pack_dir.exists()+ def test_remove_restores_lower_priority_command(+ self, project_dir, temp_dir, valid_pack_data+ ):+ """After removing the top-priority preset, the next preset's command+ should be re-registered in agent directories."""+ manager = PresetManager(project_dir)- def test_non_wrap_commands_unaffected_by_wrap_lifecycle(self, project_dir, temp_dir):- """wrap_commands is empty for a preset with no strategy:wrap commands."""- from specify_cli.agents import CommandRegistrar- import copy- import yaml as _yaml+ # Create a gemini commands dir so reconciliation writes there+ gemini_dir = project_dir / ".gemini" / "commands"+ gemini_dir.mkdir(parents=True)- # Create a preset with a non-wrap command- preset_dir = temp_dir / "non-wrap-preset"- cmd_dir = preset_dir / "commands"- cmd_dir.mkdir(parents=True)- manifest = {- "schema_version": "1.0",- "preset": {- "id": "non-wrap-preset", "name": "Non-wrap", "version": "1.0.0",- "description": "no wrap", "author": "test",- "repository": "https://example.com", "license": "MIT",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {"templates": [- {"type": "command", "name": "speckit.specify",- "file": "commands/speckit.specify.md", "description": "override"},- ]},- "tags": [],+ # Install a low-priority preset with a command+ lo_data = {**valid_pack_data}+ lo_data["preset"] = {+ **valid_pack_data["preset"],+ "id": "lo-preset",+ "name": "Lo",}- (preset_dir / "preset.yml").write_text(_yaml.dump(manifest))- (cmd_dir / "speckit.specify.md").write_text(- "---\ndescription: plain override\n---\n\nplain body\n"+ lo_data["provides"] = {+ "templates": [{+ "type": "command",+ "name": "speckit.specify",+ "file": "commands/speckit.specify.md",+ }]+ }+ lo_dir = temp_dir / "lo-preset"+ lo_dir.mkdir()+ with open(lo_dir / "preset.yml", "w") as f:+ yaml.dump(lo_data, f)+ (lo_dir / "commands").mkdir()+ (lo_dir / "commands" / "speckit.specify.md").write_text(+ "---\ndescription: lo\n---\nLo content\n")-- registrar = CommandRegistrar()- original = copy.deepcopy(registrar.AGENT_CONFIGS)- agent_dir = project_dir / ".claude" / "commands"- agent_dir.mkdir(parents=True, exist_ok=True)- registrar.AGENT_CONFIGS["test-agent"] = {- "dir": str(agent_dir.relative_to(project_dir)),- "format": "markdown", "args": "$ARGUMENTS",- "extension": ".md", "strip_frontmatter_keys": [],+ manager.install_from_directory(lo_dir, "0.1.5", priority=10)++ # Install a high-priority preset overriding the same command+ hi_data = {**valid_pack_data}+ hi_data["preset"] = {+ **valid_pack_data["preset"],+ "id": "hi-preset",+ "name": "Hi",}- try:- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.0", priority=10)- finally:- CommandRegistrar.AGENT_CONFIGS.clear()- CommandRegistrar.AGENT_CONFIGS.update(original)+ hi_data["provides"] = {+ "templates": [{+ "type": "command",+ "name": "speckit.specify",+ "file": "commands/speckit.specify.md",+ }]+ }+ hi_dir = temp_dir / "hi-preset"+ hi_dir.mkdir()+ with open(hi_dir / "preset.yml", "w") as f:+ yaml.dump(hi_data, f)+ (hi_dir / "commands").mkdir()+ (hi_dir / "commands" / "speckit.specify.md").write_text(+ "---\ndescription: hi\n---\nHi content\n"+ )+ manager.install_from_directory(hi_dir, "0.1.5", priority=1)- meta = manager.registry.get("non-wrap-preset")- assert meta.get("wrap_commands", []) == []- written = (agent_dir / "speckit.specify.md").read_text()- assert "plain body" in written+ # Verify the hi-preset's content is active in agent dir+ cmd_files = list(gemini_dir.glob("*specify*"))+ assert cmd_files, "Command file should exist in gemini dir"+ assert "Hi content" in cmd_files[0].read_text()++ # Remove the high-priority preset+ manager.remove("hi-preset")++ # The low-priority preset's command should now be in the resolution stack+ resolver = PresetResolver(project_dir)+ layers = resolver.collect_all_layers("speckit.specify", "command")+ assert len(layers) >= 1+ assert "lo-preset" in layers[0]["source"]++ # Verify on-disk agent command file switched to lo-preset content+ cmd_files = list(gemini_dir.glob("*specify*"))+ assert cmd_files, "Command file should still exist after removal"+ assert "Lo content" in cmd_files[0].read_text()+++def _create_pack(temp_dir, valid_pack_data, pack_id, content,+ strategy="replace", template_type="template",+ template_name="spec-template"):+ """Helper to create a preset pack directory."""+ pack_data = {**valid_pack_data}+ pack_data["preset"] = {**valid_pack_data["preset"], "id": pack_id, "name": pack_id}++ tmpl_entry = {+ "type": template_type,+ "name": template_name,+ }+ if template_type == "script":+ tmpl_entry["file"] = f"scripts/{template_name}.sh"+ elif template_type == "command":+ tmpl_entry["file"] = f"commands/{template_name}.md"+ else:+ tmpl_entry["file"] = f"templates/{template_name}.md"+ if strategy != "replace":+ tmpl_entry["strategy"] = strategy+ pack_data["provides"] = {"templates": [tmpl_entry]}++ pack_dir = temp_dir / pack_id+ pack_dir.mkdir(exist_ok=True)+ with open(pack_dir / "preset.yml", 'w') as f:+ yaml.dump(pack_data, f)++ if template_type == "script":+ subdir = pack_dir / "scripts"+ subdir.mkdir(exist_ok=True)+ (subdir / f"{template_name}.sh").write_text(content)+ elif template_type == "command":+ subdir = pack_dir / "commands"+ subdir.mkdir(exist_ok=True)+ (subdir / f"{template_name}.md").write_text(content)+ else:+ subdir = pack_dir / "templates"+ subdir.mkdir(exist_ok=True)+ (subdir / f"{template_name}.md").write_text(content)++ return pack_dir