[Bug]: wrap template composition can loop forever when core content contains {CORE_TEMPLATE}

[mforce]

Bug Description

The Bash template resolver's wrap strategy can loop indefinitely when the resolved base content contains the literal {CORE_TEMPLATE} token.

The current loop replaces one token in layer_content with content, then scans the modified layer_content again. If content contains {CORE_TEMPLATE}, every iteration reintroduces a token and the resolver never terminates.

This is present on current main at commit 31e6b84f701b108a848847a8bc9ea86a1e2890b7 in scripts/bash/common.sh.

Steps to Reproduce

1. Initialize a project with Bash scripts.

2. Add this preset registry:

   .specify/presets/.registry

   {
     "presets": {
       "a-wrap": { "enabled": true, "priority": 1 },
       "b-base": { "enabled": true, "priority": 2 }
     }
   }

3. Add a wrapping preset:

   .specify/presets/a-wrap/preset.yml

   provides:
     templates:
       - type: template
         name: review-template
         file: wrapper.md
         strategy: wrap

   .specify/presets/a-wrap/wrapper.md

   BEFORE
   {CORE_TEMPLATE}
   AFTER
   

4. Add a base preset whose content intentionally contains the literal token:

   .specify/presets/b-base/preset.yml

   provides:
     templates:
       - type: template
         name: review-template
         file: base.md
         strategy: replace

   .specify/presets/b-base/base.md

   BASE {CORE_TEMPLATE}
   

5. Run:

   timeout 5 .specify/scripts/bash/resolve-template.sh review-template
   echo $?

Expected Behavior

The resolver replaces each {CORE_TEMPLATE} occurrence that existed in the original wrapper exactly once, preserves literal token text contained in the inserted base content, and terminates. For the example above, the output should contain:

BEFORE
BASE {CORE_TEMPLATE}
AFTER

Actual Behavior

The process consumes CPU until timeout terminates it with exit code 124. Each iteration replaces a token with base content that contains another token, so the loop condition remains true forever.

Specify CLI Version

1.0.3.dev0

AI Agent

Codex CLI

Operating System

Linux 7.2.0 x86_64

Python Version

Python 3.14.5 (Specify CLI runtime)

Error Logs

$ timeout 5 .specify/scripts/bash/resolve-template.sh review-template
$ echo $?
124

Additional Context

A single-pass replacement over an unmodified rest variable fixes the issue: consume tokens only from the original wrapper while appending content to a separate output buffer.

The issue was found while reviewing generated Spec Kit tooling in mforce/cluckwork#635. A verified local fix is in commit c70a5ad1.

I searched open and closed issues and PRs using {CORE_TEMPLATE}, wrap strategy, infinite loop, hang, and placeholder-reintroduction terms. Related issues #3991 and #4044 concern frontmatter corruption during wrap composition; they do not cover this non-terminating Bash replacement loop.

[github-actions]

Bug assessment — wrap-infinite-loop-core-token: Valid · severity high

---

Bug Assessment: wrap template composition infinite loop

• Slug: wrap-infinite-loop-core-token
• Created: 2026-09-01T12:08:45Z
• Source: issue [Bug]: wrap template composition can loop forever when core content contains {CORE_TEMPLATE} #4385
• Verdict: valid
• Severity: high

Report (summarized)

Reported by @mforce. The Bash wrap strategy in scripts/bash/common.sh can loop indefinitely when the resolved base content contains the literal string {CORE_TEMPLATE}. The reporter traced it to commit 31e6b84f701b108a848847a8bc9ea86a1e2890b7 and provided reproduction steps, expected vs. actual output, and a reference fix in an external fork.

Symptom

When a wrap-strategy preset wraps a replace-strategy preset whose content contains the literal text {CORE_TEMPLATE}, the resolver loops forever because each substitution reintroduces the sentinel token. The process must be killed externally (exit 124 from timeout).

Reproduction

1. Initialize a Spec Kit project with Bash scripts.
2. Create .specify/presets/.registry with presets a-wrap (priority 1, wrap strategy) and b-base (priority 2, replace strategy).
3. a-wrap/wrapper.md — content: BEFORE\n{CORE_TEMPLATE}\nAFTER
4. b-base/base.md — content: BASE {CORE_TEMPLATE} (literal token in base content)
5. Run: timeout 5 .specify/scripts/bash/resolve-template.sh review-template; echo $?
6. Observe exit code 124 (killed by timeout); CPU pegged during the 5-second window.

Expected output before timeout:

BEFORE
BASE {CORE_TEMPLATE}
AFTER

Suspected Code Paths

• scripts/bash/common.sh:905–910 — the wrap case uses a while loop that re-scans the already-modified layer_content variable. If content (the base) contains {CORE_TEMPLATE}, the loop condition is satisfied again after every iteration, producing an infinite loop.

# lines 905-910 (current, buggy)
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"

Root Cause Hypothesis

Confidence: high.

The while loop was intended to replace all occurrences of {CORE_TEMPLATE} in the wrapper content, but it re-evaluates the loop condition against the mutated layer_content after each replacement. Because the inserted content can itself contain the token, the loop never drains — it grows the string with each pass. A single-pass scan of the original wrapper string (consuming each token exactly once and treating the inserted content as opaque data) is the correct design.

Proposed Remediation

Preferred: Replace the while loop with a single-pass approach that reads tokens only from positions in the original wrapper string, never re-scanning the substituted content. The standard Bash idiom is to accumulate an output buffer from a rest variable that is advanced past each {CORE_TEMPLATE} occurrence:

# single-pass replacement (sketch — do not write the patch here)
# rest=<original layer_content>
# output=""
# while rest still contains {CORE_TEMPLATE}:
#     append rest's prefix up to the token to output
#     append content (opaque) to output
#     advance rest to the portion after the token
# append any remaining rest to output
# content=output

This guarantees termination in O(n) passes where n is the number of tokens in the original wrapper, regardless of what content contains.

Alternatives:

• Replace only the first occurrence (single substitution, not a loop), appropriate if the spec only ever expects one {CORE_TEMPLATE} token per wrapper — simpler but drops multi-token support.
• Escape content before substitution so any {CORE_TEMPLATE} inside it is temporarily renamed, then unescape after — more complex and fragile; not recommended.

Files likely to change:

• scripts/bash/common.sh (lines ~905–910, the wrap case)
• Any parity counterparts: scripts/powershell/ and scripts/python/ equivalents of the template-resolution logic should be audited for the same pattern.

Tests to add or update:

• A regression test for resolve-template.sh (or its Python/PowerShell equivalents) where the base content contains a literal {CORE_TEMPLATE} token — assert termination and correct output.
• A test verifying multiple {CORE_TEMPLATE} occurrences in a wrapper are each replaced exactly once.

Risks & Considerations

• Blast radius: any project using a wrap-strategy preset where the wrapped content happens to contain the literal string {CORE_TEMPLATE} (e.g., documentation, examples, or spec templates that mention the token by name) will hang at template resolution time. This is user-visible and blocks the workflow.
• Fix is low-risk: the change is confined to a single Bash loop in common.sh; the observable output for all inputs that do not contain {CORE_TEMPLATE} in base content is unchanged.
• Parity: the PowerShell and Python script variants should be reviewed for the same issue before closing.
• No API breakage, migrations, or security concerns identified.

Open Questions

• [NEEDS CLARIFICATION: Are there existing integration or unit tests for the wrap strategy in the Bash scripts, or only in the Python layer?]
• [NEEDS CLARIFICATION: Does the PowerShell/Python equivalent of this resolver have the same while-loop pattern?]

Generated by 🐛 Assess Bug from Labeled Issue for issue #4385 · 75.7 AIC · ⌖ 11.1 AIC · ⊞ 35.7K · ◷

[Yash-Chindam]

Reproduced on main. Adding one finding that should make the fix unambiguous: this is a Bash-only divergence — the PowerShell and Python ports already implement the correct behaviour.

scripts/bash/common.sh:905 rescans the string it just modified:

while [[ "$layer_content" == *'{CORE_TEMPLATE}'* ]]; do
    local before="${layer_content%%\{CORE_TEMPLATE\}*}"
    local after="${layer_content#*\{CORE_TEMPLATE\}}"
    layer_content="${before}${content}${after}"
done

Each pass reinserts $content into layer_content and then re-tests layer_content, so if $content carries the literal token the condition is true forever.

The other two ports do a single non-rescanning pass:

# scripts/powershell/common.ps1:789
$content = $layerContent.Replace('{CORE_TEMPLATE}', $content)

# scripts/python/common.py:466
content = layer_content.replace(placeholder, content)

String.Replace and str.replace both scan the original subject once and never revisit inserted text, which is exactly the expected behaviour described above. So the ports already agree with the spec, and only Bash needs to change — the correct semantics don't need to be invented, just matched.

A single-pass version that consumes the wrapper left to right:

wrap)
    case "$layer_content" in
        *'{CORE_TEMPLATE}'*) ;;
        *) echo "Error: wrap strategy missing {CORE_TEMPLATE} placeholder" >&2; return 2 ;;
    esac
    local out="" rest="$layer_content"
    while [[ "$rest" == *'{CORE_TEMPLATE}'* ]]; do
        out="${out}${rest%%\{CORE_TEMPLATE\}*}${content}"
        rest="${rest#*\{CORE_TEMPLATE\}}"
    done
    content="${out}${rest}"
    ;;

The loop advances over rest instead of rewriting the subject, so inserted content is never re-examined and termination is bounded by the number of tokens in the original wrapper.

I checked it against str.replace on three cases, and the output matches byte for byte:

case	wrapper	base content	result
A — normal	BEFORE\n{CORE_TEMPLATE}\nAFTER	BASE	BEFORE\nBASE\nAFTER
B — this bug	BEFORE\n{CORE_TEMPLATE}\nAFTER	BASE {CORE_TEMPLATE}	BEFORE\nBASE {CORE_TEMPLATE}\nAFTER
C — two tokens	A{CORE_TEMPLATE}B{CORE_TEMPLATE}C	X	AXBXC

Case B hangs on current main (timeout exits 124) and returns immediately with the change. Case C confirms multiple placeholders in the wrapper are still filled, so the fix is not just "replace the first one".

Worth adding a regression test that runs the resolver under a timeout, since the failure mode is a hang rather than a bad value — a plain assertion would never fail, it would just never finish.

Happy to open a PR with the change plus that test if nobody else is on it.

Disclosure: I used an AI assistant (Claude) to help investigate and draft this comment. The reproduction, the port comparison, and the three cases above were verified against main.

[mnriem]

@Yash-Chindam Feel free to create a PR with a fix

[Yash-Chindam]

PR up: #4396

It takes the approach described above — the bash wrap loop now consumes the wrapper left to right instead of rewriting and re-scanning it, matching the single-pass semantics common.ps1 and common.py already have.

Verified by extracting the wrap block verbatim from main and from the branch and running both: normal wrapping and the two-placeholder case are byte-identical before and after, while the reported case goes from a hang (rc=124) to the correct output.

Includes a parity regression test across all three variants. It passes a timeout deliberately — the failure mode is a hang, not a wrong value, so a plain assertion would never fail, it would just never finish.

Could you assign this issue to me so ownership is clear and nobody duplicates the work? Happy to revise the PR on any feedback.