[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 · ◷