feat(presets): resolve constitution templates at command time (#3984)

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

-for arg in "$@"; do
-    case "$arg" in
+while [[ $# -gt 0 ]]; do
+    case "$1" in
        --json)
            JSON_MODE=true
            ;;
@@ -41,6 +43,14 @@ for arg in "$@"; do
        --paths-only)
            PATHS_ONLY=true
            ;;
+        --template)
+            shift
+            if [[ $# -eq 0 ]]; then
+                echo "ERROR: --template requires a template name" >&2
+                exit 1
+            fi
+            TEMPLATE_NAME="$1"
+            ;;
        --help|-h)
            cat << 'EOF'
 Usage: check-prerequisites.sh [OPTIONS]
@@ -52,6 +62,7 @@ OPTIONS:
  --require-tasks     Require tasks.md to exist (for implementation phase)
  --include-tasks     Include tasks.md in AVAILABLE_DOCS list
  --paths-only        Only output path variables (no prerequisite validation)
+  --template NAME     Include composed template content in JSON output
  --help, -h          Show this help message

 EXAMPLES:
@@ -68,10 +79,11 @@ EOF
            exit 0
            ;;
        *)
-            echo "ERROR: Unknown option '$arg'. Use --help for usage information." >&2
+            echo "ERROR: Unknown option '$1'. Use --help for usage information." >&2
            exit 1
            ;;
    esac
+    shift
 done

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

+TEMPLATE_CONTENT=""
+if [[ -n "$TEMPLATE_NAME" ]]; then
+    if TEMPLATE_CONTENT=$(resolve_template_content "$TEMPLATE_NAME" "$REPO_ROOT"; status=$?; printf x; exit "$status"); then
+        TEMPLATE_CONTENT="${TEMPLATE_CONTENT%x}"
+    else
+        echo "ERROR: Could not resolve required $TEMPLATE_NAME from the template override stack for $REPO_ROOT" >&2
+        exit 1
+    fi
+fi
+
 # Output results
 if $JSON_MODE; then
    # Build JSON array of documents
@@ -165,10 +187,18 @@ if $JSON_MODE; then
        else
            json_docs=$(printf '%s\n' "${docs[@]}" | jq -R . | jq -s .)
        fi
-        jq -cn \
-            --arg feature_dir "$FEATURE_DIR" \
-            --argjson docs "$json_docs" \
-            '{FEATURE_DIR:$feature_dir,AVAILABLE_DOCS:$docs}'
+        if [[ -n "$TEMPLATE_NAME" ]]; then
+            jq -cn \
+                --arg feature_dir "$FEATURE_DIR" \
+                --argjson docs "$json_docs" \
+                --arg template_content "$TEMPLATE_CONTENT" \
+                '{FEATURE_DIR:$feature_dir,AVAILABLE_DOCS:$docs,TEMPLATE_CONTENT:$template_content}'
+        else
+            jq -cn \
+                --arg feature_dir "$FEATURE_DIR" \
+                --argjson docs "$json_docs" \
+                '{FEATURE_DIR:$feature_dir,AVAILABLE_DOCS:$docs}'
+        fi
    else
        if [[ ${#docs[@]} -eq 0 ]]; then
            json_docs="[]"
@@ -176,7 +206,12 @@ if $JSON_MODE; then
            json_docs=$(for d in "${docs[@]}"; do printf '"%s",' "$(json_escape "$d")"; done)
            json_docs="[${json_docs%,}]"
        fi
-        printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$(json_escape "$FEATURE_DIR")" "$json_docs"
+        if [[ -n "$TEMPLATE_NAME" ]]; then
+            printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s,"TEMPLATE_CONTENT":"%s"}\n' \
+                "$(json_escape "$FEATURE_DIR")" "$json_docs" "$(json_escape "$TEMPLATE_CONTENT")"
+        else
+            printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$(json_escape "$FEATURE_DIR")" "$json_docs"
+        fi
    fi
 else
    # Text output
@@ -398,6 +398,101 @@ json_escape() {
 check_file() { [[ -f "$1" ]] && echo "  ✓ $2" || echo "  ✗ $2"; }
 check_dir() { [[ -d "$1" && -n $(ls -A "$1" 2>/dev/null) ]] && echo "  ✓ $2" || echo "  ✗ $2"; }

+_python3_command() {
+    if command -v python3 >/dev/null 2>&1 &&
+        python3 -c 'import sys; raise SystemExit(sys.version_info.major != 3)' >/dev/null 2>&1; then
+        printf '%s\n' "python3"
+    elif command -v python >/dev/null 2>&1 &&
+        python -c 'import sys; raise SystemExit(sys.version_info.major != 3)' >/dev/null 2>&1; then
+        printf '%s\n' "python"
+    elif command -v py >/dev/null 2>&1 &&
+        py -3 -c 'import sys' >/dev/null 2>&1; then
+        printf '%s\n' "py -3"
+    else
+        return 1
+    fi
+}
+
+_sorted_extension_ids() {
+    local ext_dir="$1"
+    local python_spec
+    if python_spec=$(_python3_command); then
+        local -a python_cmd
+        read -r -a python_cmd <<< "$python_spec"
+        local py_stderr sorted_ids
+        py_stderr=$(mktemp)
+        if sorted_ids=$(SPECKIT_EXTENSIONS="$ext_dir" "${python_cmd[@]}" -c "
+import json, os, re, sys
+from pathlib import Path
+
+root = Path(os.environ['SPECKIT_EXTENSIONS'])
+registered = {}
+registry = root / '.registry'
+if os.path.lexists(registry):
+    if not registry.is_file():
+        print('registry_invalid: not a regular file', file=sys.stderr)
+        sys.exit(1)
+    try:
+        data = json.loads(registry.read_text(encoding='utf-8'))
+    except Exception as exc:
+        print('registry_invalid: ' + str(exc), file=sys.stderr)
+        sys.exit(1)
+    if not isinstance(data, dict):
+        print('registry_invalid: root must be a mapping', file=sys.stderr)
+        sys.exit(1)
+    raw_extensions = data.get('extensions', {})
+    if not isinstance(raw_extensions, dict):
+        print('registry_invalid: extensions must be a mapping', file=sys.stderr)
+        sys.exit(1)
+    registered = raw_extensions
+
+def priority(value):
+    if isinstance(value, bool):
+        return 10
+    try:
+        parsed = int(value)
+        return parsed if parsed >= 1 else 10
+    except (TypeError, ValueError, OverflowError):
+        return 10
+
+ranked = []
+for ext_id, meta in registered.items():
+    if isinstance(ext_id, str) and re.fullmatch(r'[a-z0-9-]+', ext_id) and isinstance(meta, dict) and bool(meta.get('enabled', True)):
+        ranked.append((priority(meta.get('priority')), ext_id))
+for path in root.iterdir():
+    if path.is_dir() and re.fullmatch(r'[a-z0-9-]+', path.name) and path.name not in registered:
+        ranked.append((10, path.name))
+for _, ext_id in sorted(ranked):
+    print(ext_id)
+" 2>"$py_stderr"); then
+            rm -f "$py_stderr"
+            printf '%s\n' "$sorted_ids"
+            return 0
+        else
+            echo "Error: invalid extension registry $ext_dir/.registry" >&2
+            rm -f "$py_stderr"
+            return 1
+        fi
+    fi
+
+    if [ -e "$ext_dir/.registry" ] || [ -L "$ext_dir/.registry" ]; then
+        if [ ! -f "$ext_dir/.registry" ] || [ ! -r "$ext_dir/.registry" ]; then
+            echo "Error: invalid extension registry $ext_dir/.registry" >&2
+            return 1
+        fi
+        echo "Error: Python 3 is required to honor the extension registry" >&2
+        return 2
+    fi
+
+    local ext extension_id
+    for ext in "$ext_dir"/*/; do
+        [ -d "$ext" ] || continue
+        extension_id=$(basename "$ext")
+        case "$extension_id" in *[!a-z0-9-]*) continue ;; esac
+        printf '%s\n' "$extension_id"
+    done
+}
+
 # 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)
@@ -408,6 +503,8 @@ resolve_template() {
    local repo_root="$2"
    local base="$repo_root/.specify/templates"

+    case "$template_name" in ""|*[!a-z0-9-]*) return 1 ;; esac
+
    # Priority 1: Project overrides
    local override="$base/overrides/${template_name}.md"
    [ -f "$override" ] && echo "$override" && return 0
@@ -416,19 +513,32 @@ resolve_template() {
    local presets_dir="$repo_root/.specify/presets"
    if [ -d "$presets_dir" ]; then
        local registry_file="$presets_dir/.registry"
-        if [ -f "$registry_file" ] && command -v python3 >/dev/null 2>&1; then
+        local python_spec=""
+        local -a python_cmd=()
+        if python_spec=$(_python3_command); then
+            read -r -a python_cmd <<< "$python_spec"
+        fi
+        if [ -f "$registry_file" ] && [ "${#python_cmd[@]}" -gt 0 ]; then
            # Read preset IDs sorted by priority (lower number = higher precedence).
            # The python3 call is wrapped in an if-condition so that set -e does not
            # abort the function when python3 exits non-zero (e.g. invalid JSON).
            local sorted_presets=""
-            if sorted_presets=$(SPECKIT_REGISTRY="$registry_file" python3 -c "
-import json, sys, os
+            if sorted_presets=$(SPECKIT_REGISTRY="$registry_file" "${python_cmd[@]}" -c "
+import json, re, sys, os
 try:
-    with open(os.environ['SPECKIT_REGISTRY']) as f:
+    with open(os.environ['SPECKIT_REGISTRY'], encoding='utf-8') 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:
+    def priority(meta):
+        if not isinstance(meta, dict) or isinstance(meta.get('priority'), bool):
+            return 10
+        try:
+            value = int(meta.get('priority', 10))
+            return value if value >= 1 else 10
+        except (TypeError, ValueError, OverflowError):
+            return 10
+    for pid, meta in sorted(presets.items(), key=lambda x: (priority(x[1]), x[0])):
+        if isinstance(meta, dict) and bool(meta.get('enabled', True)) and re.fullmatch(r'[a-z0-9-]+', pid):
            print(pid)
 except Exception:
    sys.exit(1)
@@ -438,6 +548,8 @@ except Exception:
                    while IFS= read -r preset_id; do
                        local candidate="$presets_dir/$preset_id/templates/${template_name}.md"
                        [ -f "$candidate" ] && echo "$candidate" && return 0
+                        candidate="$presets_dir/$preset_id/${template_name}.md"
+                        [ -f "$candidate" ] && echo "$candidate" && return 0
                    done <<< "$sorted_presets"
                fi
                # python3 succeeded but registry has no presets — nothing to search
@@ -447,6 +559,8 @@ except Exception:
                    [ -d "$preset" ] || continue
                    local candidate="$preset/templates/${template_name}.md"
                    [ -f "$candidate" ] && echo "$candidate" && return 0
+                    candidate="$preset/${template_name}.md"
+                    [ -f "$candidate" ] && echo "$candidate" && return 0
                done
            fi
        else
@@ -455,6 +569,8 @@ except Exception:
                [ -d "$preset" ] || continue
                local candidate="$preset/templates/${template_name}.md"
                [ -f "$candidate" ] && echo "$candidate" && return 0
+                candidate="$preset/${template_name}.md"
+                [ -f "$candidate" ] && echo "$candidate" && return 0
            done
        fi
    fi
@@ -462,13 +578,17 @@ except Exception:
    # Priority 3: Extension-provided templates
    local ext_dir="$repo_root/.specify/extensions"
    if [ -d "$ext_dir" ]; then
-        for ext in "$ext_dir"/*/; do
-            [ -d "$ext" ] || continue
-            # Skip hidden directories (e.g. .backup, .cache)
-            case "$(basename "$ext")" in .*) continue;; esac
+        local sorted_extensions=""
+        if ! sorted_extensions=$(_sorted_extension_ids "$ext_dir"); then
+            return 2
+        fi
+        while IFS= read -r extension_id; do
+            [ -n "$extension_id" ] || continue
+            local ext="$ext_dir/$extension_id"
            local candidate="$ext/templates/${template_name}.md"
+            [ -f "$candidate" ] || candidate="$ext/${template_name}.md"
            [ -f "$candidate" ] && echo "$candidate" && return 0
-        done
+        done <<< "$sorted_extensions"
    fi

    # Priority 4: Core templates
@@ -492,6 +612,8 @@ resolve_template_content() {
    local repo_root="$2"
    local base="$repo_root/.specify/templates"

+    case "$template_name" in ""|*[!a-z0-9-]*) return 1 ;; esac
+
    # Collect all layers (highest priority first)
    local -a layer_paths=()
    local -a layer_strategies=()
@@ -499,133 +621,206 @@ resolve_template_content() {
    # Priority 1: Project overrides (always "replace")
    local override="$base/overrides/${template_name}.md"
    if [ -f "$override" ]; then
-        layer_paths+=("$override")
-        layer_strategies+=("replace")
+        if ! cat "$override"; then
+            echo "Error: failed to read template layer $override" >&2
+            return 2
+        fi
+        return 0
    fi

+    local effective_base_found=false
+
    # 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
+        local registry_parsed=false
+        local python_spec=""
+        local -a python_cmd=()
+        if python_spec=$(_python3_command); then
+            read -r -a python_cmd <<< "$python_spec"
+        fi
+        if [ -f "$registry_file" ] && [ "${#python_cmd[@]}" -gt 0 ]; then
+            if sorted_presets=$(SPECKIT_REGISTRY="$registry_file" "${python_cmd[@]}" -c "
+import json, re, sys, os
 try:
-    with open(os.environ['SPECKIT_REGISTRY']) as f:
+    with open(os.environ['SPECKIT_REGISTRY'], encoding='utf-8') 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:
+    def priority(meta):
+        if not isinstance(meta, dict) or isinstance(meta.get('priority'), bool):
+            return 10
+        try:
+            value = int(meta.get('priority', 10))
+            return value if value >= 1 else 10
+        except (TypeError, ValueError, OverflowError):
+            return 10
+    for pid, meta in sorted(presets.items(), key=lambda x: (priority(x[1]), x[0])):
+        if isinstance(meta, dict) and bool(meta.get('enabled', True)) and re.fullmatch(r'[a-z0-9-]+', pid):
            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 "
+                registry_parsed=true
+            fi
+        fi
+        if [ "$registry_parsed" = false ]; then
+            for preset in "$presets_dir"/*/; do
+                [ -d "$preset" ] || continue
+                local fallback_id
+                fallback_id=$(basename "$preset")
+                case "$fallback_id" in *[!a-z0-9-]*) continue ;; esac
+                sorted_presets+="${sorted_presets:+$'\n'}$fallback_id"
+            done
+        fi
+
+        if [ -n "$sorted_presets" ]; then
+            while IFS= read -r preset_id; do
+                local strategy="replace"
+                local manifest_file=""
+                local manifest="$presets_dir/$preset_id/preset.yml"
+                local manifest_declared=false
+                if [ -f "$manifest" ]; then
+                    if [ "${#python_cmd[@]}" -eq 0 ]; then
+                        echo "Error: Python 3 and PyYAML are required to resolve preset template composition" >&2
+                        return 2
+                    fi
+                    local result
+                    local py_stderr
+                    local parse_status
+                    py_stderr=$(mktemp)
+                    if result=$(SPECKIT_MANIFEST="$manifest" SPECKIT_TMPL="$template_name" "${python_cmd[@]}" -c "
 import sys, os
 try:
    import yaml
 except ImportError:
    print('yaml_missing', file=sys.stderr)
-    print('replace\t')
-    sys.exit(0)
+    sys.exit(2)
 try:
-    with open(os.environ['SPECKIT_MANIFEST']) as f:
+    with open(os.environ['SPECKIT_MANIFEST'], encoding='utf-8') as f:
        data = yaml.safe_load(f)
-    for t in data.get('provides', {}).get('templates', []):
+    if not isinstance(data, dict):
+        raise ValueError('manifest root must be a mapping')
+    if 'provides' not in data:
+        raise ValueError('manifest missing provides section')
+    provides = data['provides']
+    if not isinstance(provides, dict):
+        raise ValueError('manifest provides must be a mapping')
+    if 'templates' not in provides:
+        raise ValueError('manifest provides missing templates')
+    templates = provides['templates']
+    if not isinstance(templates, list):
+        raise ValueError('manifest templates must be a list')
+    if not templates:
+        raise ValueError('manifest must provide at least one template')
+    valid_types = ('template', 'command', 'script')
+    valid_strategies = ('replace', 'prepend', 'append', 'wrap')
+    for t in templates:
+        if not isinstance(t, dict):
+            raise ValueError('manifest template entries must be mappings')
+        if 'type' not in t or 'name' not in t or 'file' not in t:
+            raise ValueError('manifest template entry missing type, name, or file')
+        for field in ('type', 'name', 'file'):
+            if not isinstance(t[field], str):
+                raise ValueError('manifest template ' + field + ' must be a string')
+        if t['type'] not in valid_types:
+            raise ValueError('invalid manifest template type')
+        strategy = t.get('strategy', 'replace')
+        if not isinstance(strategy, str):
+            raise ValueError('manifest template strategy must be a string')
+        strategy = strategy.lower()
+        if strategy not in valid_strategies:
+            raise ValueError('invalid manifest template strategy')
+        if t['type'] == 'script' and strategy not in ('replace', 'wrap'):
+            raise ValueError('invalid manifest script strategy')
+    for t in templates:
        if t.get('name') == os.environ['SPECKIT_TMPL'] and t.get('type', 'template') == 'template':
-            print(t.get('strategy', 'replace') + '\t' + t.get('file', ''))
+            file_value = t.get('file', '')
+            strategy = t.get('strategy', 'replace')
+            print('found\t' + strategy + '\t' + file_value)
            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")
+    print('absent\treplace\t')
+except Exception as exc:
+    print(f'manifest_invalid: {exc}', file=sys.stderr)
+    sys.exit(3)
+" 2>"$py_stderr"); then
+                        parse_status=0
+                    else
+                        parse_status=$?
                    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")
+                    if [ "$parse_status" -ne 0 ]; then
+                        if [ "$parse_status" -eq 2 ]; then
+                            echo "Error: PyYAML is required to resolve preset template composition" >&2
+                        else
+                            echo "Error: invalid preset manifest $manifest" >&2
+                        fi
+                        rm -f "$py_stderr"
+                        return 2
+                    fi
+                    if [ -n "$result" ]; then
+                        local declaration
+                        IFS=$'\t' read -r declaration strategy manifest_file <<< "$result"
+                        [ "$declaration" = "found" ] && manifest_declared=true
+                        strategy=$(printf '%s' "$strategy" | tr '[:upper:]' '[:lower:]')
+                    fi
+                    rm -f "$py_stderr"
                fi
-            done
+
+                local candidate=""
+                if [ -n "$manifest_file" ]; then
+                    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" ] && [ "$manifest_declared" = false ]; then
+                    local cf="$presets_dir/$preset_id/templates/${template_name}.md"
+                    [ -f "$cf" ] && candidate="$cf"
+                    if [ -z "$candidate" ]; then
+                        cf="$presets_dir/$preset_id/${template_name}.md"
+                        [ -f "$cf" ] && candidate="$cf"
+                    fi
+                fi
+                if [ -n "$candidate" ]; then
+                    layer_paths+=("$candidate")
+                    layer_strategies+=("$strategy")
+                    if [ "$strategy" = "replace" ]; then
+                        effective_base_found=true
+                        break
+                    fi
+                fi
+            done <<< "$sorted_presets"
        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
+    if [ "$effective_base_found" = false ] && [ -d "$ext_dir" ]; then
+        local sorted_extensions=""
+        if ! sorted_extensions=$(_sorted_extension_ids "$ext_dir"); then
+            return 2
+        fi
+        while IFS= read -r extension_id; do
+            [ -n "$extension_id" ] || continue
+            local ext="$ext_dir/$extension_id"
            local candidate="$ext/templates/${template_name}.md"
+            [ -f "$candidate" ] || candidate="$ext/${template_name}.md"
            if [ -f "$candidate" ]; then
                layer_paths+=("$candidate")
                layer_strategies+=("replace")
+                effective_base_found=true
+                break
            fi
-        done
+        done <<< "$sorted_extensions"
    fi

    # Priority 4: Core templates (always "replace")
    local core="$base/${template_name}.md"
-    if [ -f "$core" ]; then
+    if [ "$effective_base_found" = false ] && [ -f "$core" ]; then
        layer_paths+=("$core")
        layer_strategies+=("replace")
    fi
@@ -642,12 +837,18 @@ except Exception:
    # 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]}"
+        if ! cat "${layer_paths[0]}"; then
+            echo "Error: failed to read template layer ${layer_paths[0]}" >&2
+            return 2
+        fi
        return 0
    fi

    if [ "$has_composition" = false ]; then
-        cat "${layer_paths[0]}"
+        if ! cat "${layer_paths[0]}"; then
+            echo "Error: failed to read template layer ${layer_paths[0]}" >&2
+            return 2
+        fi
        return 0
    fi

@@ -663,12 +864,16 @@ except Exception:
    done

    if [ $base_idx -lt 0 ]; then
-        return 1  # no base layer found
+        echo "Error: template '$template_name' has composing layers but no replace base" >&2
+        return 2
    fi

    # Read the base content; compose layers above the base (higher priority)
    local content
-    content=$(cat "${layer_paths[$base_idx]}"; printf x)
+    if ! content=$(cat "${layer_paths[$base_idx]}"; status=$?; printf x; exit "$status"); then
+        echo "Error: failed to read template layer ${layer_paths[$base_idx]}" >&2
+        return 2
+    fi
    content="${content%x}"

    for (( i=base_idx-1; i>=0; i-- )); do
@@ -676,17 +881,26 @@ except Exception:
        local strat="${layer_strategies[$i]}"
        local layer_content
        # Preserve trailing newlines
-        layer_content=$(cat "$path"; printf x)
+        if ! layer_content=$(cat "$path"; status=$?; printf x; exit "$status"); then
+            echo "Error: failed to read template layer $path" >&2
+            return 2
+        fi
        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")" ;;
+            prepend)
+                content=$(printf '%s\n\n%s' "$layer_content" "$content"; printf x)
+                content="${content%x}"
+                ;;
+            append)
+                content=$(printf '%s\n\n%s' "$content" "$layer_content"; printf x)
+                content="${content%x}"
+                ;;
            wrap)
                case "$layer_content" in
                    *'{CORE_TEMPLATE}'*) ;;
-                    *) echo "Error: wrap strategy missing {CORE_TEMPLATE} placeholder" >&2; return 1 ;;
+                    *) echo "Error: wrap strategy missing {CORE_TEMPLATE} placeholder" >&2; return 2 ;;
                esac
                while [[ "$layer_content" == *'{CORE_TEMPLATE}'* ]]; do
                    local before="${layer_content%%\{CORE_TEMPLATE\}*}"
@@ -695,7 +909,7 @@ except Exception:
                done
                content="$layer_content"
                ;;
-            *) echo "Error: unknown strategy '$strat'" >&2; return 1 ;;
+            *) echo "Error: unknown strategy '$strat'" >&2; return 2 ;;
        esac
    done

@@ -339,12 +339,27 @@ if [ "$DRY_RUN" != true ]; then
        exit 1
    fi

+    NEEDS_SPEC=false
+    SPEC_TEMPLATE_FOUND=false
+    SPEC_TEMPLATE_CONTENT=""
+    if [ ! -f "$SPEC_FILE" ]; then
+        NEEDS_SPEC=true
+        if SPEC_TEMPLATE_CONTENT=$(resolve_template_content "spec-template" "$REPO_ROOT"; status=$?; printf x; exit "$status"); then
+            SPEC_TEMPLATE_CONTENT="${SPEC_TEMPLATE_CONTENT%x}"
+            SPEC_TEMPLATE_FOUND=true
+        else
+            resolve_status=$?
+            if [ "$resolve_status" -ne 1 ]; then
+                exit "$resolve_status"
+            fi
+        fi
+    fi
+
    mkdir -p "$FEATURE_DIR"

-    if [ ! -f "$SPEC_FILE" ]; then
-        TEMPLATE=$(resolve_template "spec-template" "$REPO_ROOT") || true
-        if [ -n "$TEMPLATE" ] && [ -f "$TEMPLATE" ]; then
-            cp "$TEMPLATE" "$SPEC_FILE"
+    if [ "$NEEDS_SPEC" = true ]; then
+        if [ "$SPEC_TEMPLATE_FOUND" = true ]; then
+            printf '%s' "$SPEC_TEMPLATE_CONTENT" > "$SPEC_FILE"
        else
            echo "Warning: Spec template not found; created empty spec file" >&2
            touch "$SPEC_FILE"
@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+
+set -e
+
+SCRIPT_DIR="$(CDPATH="" cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+JSON_MODE=false
+TEMPLATE_NAME=""
+
+for arg in "$@"; do
+    case "$arg" in
+        --json) JSON_MODE=true ;;
+        --help|-h)
+            echo "Usage: $0 <template-name> [--json]"
+            exit 0
+            ;;
+        -*)
+            echo "ERROR: Unknown option '$arg'" >&2
+            exit 1
+            ;;
+        *)
+            if [[ -n "$TEMPLATE_NAME" ]]; then
+                echo "ERROR: Unexpected argument '$arg'" >&2
+                exit 1
+            fi
+            TEMPLATE_NAME="$arg"
+            ;;
+    esac
+done
+
+if [[ -z "$TEMPLATE_NAME" ]]; then
+    echo "ERROR: Template name is required" >&2
+    exit 1
+fi
+
+REPO_ROOT=$(get_repo_root)
+if TEMPLATE_CONTENT=$(resolve_template_content "$TEMPLATE_NAME" "$REPO_ROOT"; status=$?; printf x; exit "$status"); then
+    TEMPLATE_CONTENT="${TEMPLATE_CONTENT%x}"
+else
+    echo "ERROR: Could not resolve required $TEMPLATE_NAME from the template override stack for $REPO_ROOT" >&2
+    exit 1
+fi
+
+if $JSON_MODE; then
+    if has_jq; then
+        jq -cn \
+            --arg template_name "$TEMPLATE_NAME" \
+            --arg template_content "$TEMPLATE_CONTENT" \
+            '{TEMPLATE_NAME:$template_name,TEMPLATE_CONTENT:$template_content}'
+    else
+        printf '{"TEMPLATE_NAME":"%s","TEMPLATE_CONTENT":"%s"}\n' \
+            "$(json_escape "$TEMPLATE_NAME")" "$(json_escape "$TEMPLATE_CONTENT")"
+    fi
+else
+    printf '%s' "$TEMPLATE_CONTENT"
+fi
@@ -43,21 +43,23 @@ if [[ -f "$IMPL_PLAN" ]]; then
        echo "Plan already exists at $IMPL_PLAN, skipping template copy"
    fi
 else
-    TEMPLATE=$(resolve_template "plan-template" "$REPO_ROOT") || true
-    if [[ -n "$TEMPLATE" ]] && [[ -f "$TEMPLATE" ]]; then
-        cp "$TEMPLATE" "$IMPL_PLAN"
+    if resolve_template_content "plan-template" "$REPO_ROOT" > "$IMPL_PLAN"; then
        if $JSON_MODE; then
            echo "Copied plan template to $IMPL_PLAN" >&2
        else
            echo "Copied plan template to $IMPL_PLAN"
        fi
    else
+        resolve_status=$?
+        rm -f "$IMPL_PLAN"
+        if [ "$resolve_status" -ne 1 ]; then
+            exit "$resolve_status"
+        fi
        if $JSON_MODE; then
            echo "Warning: Plan template not found" >&2
        else
            echo "Warning: Plan template not found"
        fi
-        # Create a basic plan file if template doesn't exist
        touch "$IMPL_PLAN"
    fi
 fi
@@ -51,7 +51,9 @@ fi

 # Resolve tasks template through override stack
 TASKS_TEMPLATE=$(resolve_template "tasks-template" "$REPO_ROOT") || true
-if [[ -z "$TASKS_TEMPLATE" ]] || [[ ! -f "$TASKS_TEMPLATE" ]]; then
+if TASKS_TEMPLATE_CONTENT=$(resolve_template_content "tasks-template" "$REPO_ROOT"; status=$?; printf x; exit "$status"); then
+    TASKS_TEMPLATE_CONTENT="${TASKS_TEMPLATE_CONTENT%x}"
+else
    echo "ERROR: Could not resolve required tasks-template from the template override stack for $REPO_ROOT" >&2
    echo "Template 'tasks-template' was not found in any supported location (overrides, presets, extensions, or shared core). Add an override at .specify/templates/overrides/tasks-template.md, or run 'specify init' / reinstall shared infra to restore the core .specify/templates/tasks-template.md template." >&2
    exit 1
@@ -69,7 +71,8 @@ if $JSON_MODE; then
            --arg feature_dir "$FEATURE_DIR" \
            --argjson docs "$json_docs" \
            --arg tasks_template "${TASKS_TEMPLATE:-}" \
-            '{FEATURE_DIR:$feature_dir,AVAILABLE_DOCS:$docs,TASKS_TEMPLATE:$tasks_template}'
+            --arg tasks_template_content "$TASKS_TEMPLATE_CONTENT" \
+            '{FEATURE_DIR:$feature_dir,AVAILABLE_DOCS:$docs,TASKS_TEMPLATE:$tasks_template,TASKS_TEMPLATE_CONTENT:$tasks_template_content}'
    else
        if [[ ${#docs[@]} -eq 0 ]]; then
            json_docs="[]"
@@ -77,8 +80,8 @@ if $JSON_MODE; then
            json_docs=$(for d in "${docs[@]}"; do printf '"%s",' "$(json_escape "$d")"; done)
            json_docs="[${json_docs%,}]"
        fi
-        printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s,"TASKS_TEMPLATE":"%s"}\n' \
-            "$(json_escape "$FEATURE_DIR")" "$json_docs" "$(json_escape "${TASKS_TEMPLATE:-}")"
+        printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s,"TASKS_TEMPLATE":"%s","TASKS_TEMPLATE_CONTENT":"%s"}\n' \
+            "$(json_escape "$FEATURE_DIR")" "$json_docs" "$(json_escape "${TASKS_TEMPLATE:-}")" "$(json_escape "$TASKS_TEMPLATE_CONTENT")"
    fi
 else
    echo "FEATURE_DIR: $FEATURE_DIR"