feat: require named context placeholders, remove bulk {{ contexts }} and implicit append

Forces explicit placement of each context with {{ contexts.name }}.
Contexts not referenced by a named placeholder are excluded from the
prompt, preventing accidental data dumps.

Closes #8 (comment)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 2 people

docs/contributing/codebase-map.md

@@ -86,8 +86,7 @@ Discovery is handled by `_discovery.py:discover_primitives()` which scans `.ralp
 Contexts use the resolver (`resolver.py:resolve_placeholders()`):
 
 - `{{ contexts.git-log }}` — named placement for a specific context
-- `{{ contexts }}` — bulk placement for all remaining contexts
-- No placeholders at all — everything appended to the end of the prompt
+- Contexts not referenced by name are excluded from the prompt
 
 ### Event system
 

docs/getting-started.md

@@ -172,13 +172,7 @@ By default, context output is appended to the end of the prompt. You can control
 You are an autonomous coding agent running in a loop...
 ```
 
-Or use `{{ contexts }}` to place all contexts at once:
-
-```markdown
-{{ contexts }}
-
-You are an autonomous coding agent...
-```
+Each context must be referenced by name — contexts not referenced are excluded from the prompt.
 
 ## Step 8: Verify and run
 

docs/primitives.md

@@ -110,19 +110,17 @@ Context output is injected **regardless of the command's exit code**. Commands l
 
 ### Placement in the prompt
 
-By default, all context output is appended to the end of the prompt. Control placement with placeholders in your `RALPH.md`:
+Use named placeholders in your `RALPH.md` to place specific contexts:
 
 ```markdown
 {{ contexts.git-log }}
 
 Work on the next task.
 
-{{ contexts }}
+{{ contexts.test-status }}
 ```
 
-- `{{ contexts.git-log }}` — places that specific context here
-- `{{ contexts }}` — places all remaining contexts (those not already placed by name)
-- If no placeholders are found, all context output is appended to the end
+Each context must be referenced by name with `{{ contexts.name }}`. Contexts not referenced by a placeholder are excluded from the prompt.
 
 ## Ralphs
 
@@ -146,7 +144,7 @@ You are a documentation agent. Each iteration starts fresh.
 
 Read the codebase and existing docs. Find the biggest gap and improve one page per iteration.
 
-{{ contexts }}
+{{ contexts.git-log }}
 ```
 
 ### Running a named ralph

docs/troubleshooting.md

@@ -195,15 +195,7 @@ Run the context command manually to verify it produces output. Note that context
 
 ### Some contexts are missing from the prompt
 
-If you use a **named placeholder** like `{{ contexts.git-log }}` but don't include a bulk `{{ contexts }}` placeholder, any other contexts are silently excluded. Add `{{ contexts }}` somewhere in your prompt to catch all remaining contexts:
-
-```markdown
-{{ contexts.git-log }}
-
-Do the work.
-
-{{ contexts }}
-```
+Each context must be referenced by a named placeholder like `{{ contexts.git-log }}` to appear in the prompt. Contexts without a placeholder are excluded. Make sure every context you want included has a corresponding `{{ contexts.name }}` in your `RALPH.md`.
 
 See [Placement in the prompt](primitives.md#placement-in-the-prompt) for full details.
 

src/ralphify/contexts.py

@@ -144,9 +144,9 @@ def resolve_contexts(prompt: str, results: list[ContextResult]) -> str:
     Callers are responsible for passing only the results they want
     resolved (the engine pre-filters via ``_discover_enabled_primitives``).
 
+    Only named placeholders are supported:
     - {{ contexts.<name> }} → specific context content
-    - {{ contexts }} → all contexts not already placed
-    - If no placeholders found → append all at end
+    - Contexts not referenced by name are excluded
     """
     available: dict[str, str] = {}
     for r in results:

src/ralphify/ralphs.py

@@ -22,7 +22,7 @@ class Ralph:
 
     The *content* is the body text below the YAML frontmatter — this is the
     full prompt that gets piped to the agent.  Context placeholders
-    (``{{ contexts }}``) resolve the same way as in a root ``RALPH.md``.
+    (``{{ contexts.name }}``) resolve the same way as in a root ``RALPH.md``.
     """
 
     name: str

src/ralphify/resolver.py

@@ -1,10 +1,11 @@
 """Template placeholder resolution for contexts.
 
-Handles three placement strategies:
+Only named placeholders are supported:
 
-1. **Named** — ``{{ kind.name }}`` inserts a specific primitive's content.
-2. **Bulk** — ``{{ kind }}`` inserts all remaining primitives (alphabetically).
-3. **Implicit** — when no placeholders exist, all content is appended to the end.
+``{{ kind.name }}`` inserts a specific primitive's content.
+
+Contexts not referenced by a named placeholder are excluded from the
+prompt.  This forces explicit placement and avoids accidental data dumps.
 """
 
 import re
@@ -15,42 +16,23 @@ def resolve_placeholders(
     available: dict[str, str],
     kind: str,
 ) -> str:
-    """Replace template placeholders in a prompt string.
+    """Replace named template placeholders in a prompt string.
 
     *kind* is the placeholder category (e.g. "contexts").
 
-    - Named placeholders (e.g. {{ kind.name }}) -> specific content
-    - Bulk placeholder (e.g. {{ kind }}) -> all not already placed
-    - No placeholders found -> append all at end
+    - ``{{ kind.name }}`` → replaced with the matching content
+    - Unknown names → replaced with empty string
+    - Unreferenced items are silently excluded
     """
     if not available:
         return prompt
 
     named_pattern = re.compile(r"\{\{\s*" + re.escape(kind) + r"\.([a-zA-Z0-9_-]+)\s*\}\}")
-    bulk_pattern = re.compile(r"\{\{\s*" + re.escape(kind) + r"\s*\}\}")
-
-    has_named = bool(named_pattern.search(prompt))
-    placed: set[str] = set()
 
     def _replace_named(match: re.Match) -> str:
         name = match.group(1)
         if name in available:
-            placed.add(name)
             return available[name]
         return ""
 
-    result = named_pattern.sub(_replace_named, prompt)
-
-    remaining = [content for name, content in sorted(available.items()) if name not in placed]
-    bulk_text = "\n\n".join(remaining)
-
-    if bulk_pattern.search(result):
-        # Use a function replacement to prevent re.sub from interpreting
-        # backslash sequences (e.g. \1, \d) in user-provided content.
-        result = bulk_pattern.sub(lambda _: bulk_text, result)
-    elif not has_named:
-        # No placeholders found at all -> append
-        if bulk_text:
-            result = result + "\n\n" + bulk_text
-
-    return result
+    return named_pattern.sub(_replace_named, prompt)

src/ralphify/skills/new-ralph/SKILL.md

@@ -60,8 +60,7 @@ enabled: true
 
 - Body text appears as a label above the command output
 - Contexts run regardless of command exit code
-- Place contexts in the prompt with `{{ contexts.context-name }}` or `{{ contexts }}` for all remaining
-- If no placeholders, all context output is appended to the end
+- Place contexts in the prompt with `{{ contexts.context-name }}` — each context must be referenced by name
 
 ### Scripts
 
@@ -91,7 +90,7 @@ All primitive output is truncated to 5000 characters.
      - What it is and what it's doing
      - That each iteration starts fresh (progress lives in code and git)
      - Specific rules and constraints
-     - Where to place context output (use `{{ contexts }}` or named placeholders)
+     - Where to place context output (use named placeholders like `{{ contexts.name }}`)
    - Follow these prompt patterns:
      - Start with role and loop awareness: "You are an autonomous X agent running in a loop."
      - Include "Each iteration starts with a fresh context. Your progress lives in the code and git."

tests/test_cli.py

@@ -772,7 +772,7 @@ class TestRunContexts:
     def test_contexts_injected_into_prompt(self, mock_agent, mock_run_contexts, tmp_path, monkeypatch):
         monkeypatch.chdir(tmp_path)
         (tmp_path / CONFIG_FILENAME).write_text(RALPH_TOML_TEMPLATE)
-        (tmp_path / "RALPH.md").write_text("Base.\n\n{{ contexts }}")
+        (tmp_path / "RALPH.md").write_text("Base.\n\n{{ contexts.git-log }}")
         _setup_context(tmp_path, "git-log", "git log --oneline -5")
 
         ctx = Context(name="git-log", path=Path("/fake"), command="git log", enabled=True)
@@ -784,7 +784,7 @@ def test_contexts_injected_into_prompt(self, mock_agent, mock_run_contexts, tmp_
         assert result.exit_code == 0
         prompt_sent = mock_agent.call_args.kwargs["input"]
         assert "abc123 fix bug" in prompt_sent
-        assert "{{ contexts }}" not in prompt_sent
+        assert "{{ contexts.git-log }}" not in prompt_sent
 
 
     @patch("ralphify.engine.run_all_contexts")
@@ -813,7 +813,7 @@ def test_disabled_contexts_not_run(self, mock_agent, mock_run_contexts, tmp_path
     def test_contexts_run_each_iteration(self, mock_agent, mock_run_contexts, tmp_path, monkeypatch):
         monkeypatch.chdir(tmp_path)
         (tmp_path / CONFIG_FILENAME).write_text(RALPH_TOML_TEMPLATE)
-        (tmp_path / "RALPH.md").write_text("{{ contexts }}")
+        (tmp_path / "RALPH.md").write_text("{{ contexts.info }}")
         _setup_context(tmp_path, "info", "echo hi")
 
         ctx = Context(name="info", path=Path("/fake"), command="echo hi", enabled=True)

tests/test_contexts.py

@@ -387,10 +387,10 @@ def test_no_results_returns_prompt_unchanged(self):
         prompt = "Do the thing."
         assert resolve_contexts(prompt, []) == prompt
 
-    def test_no_placeholders_appends_at_end(self):
+    def test_no_placeholders_leaves_prompt_unchanged(self):
         results = self._make_results(("git-log", "abc123 fix bug\n"))
         result = resolve_contexts("Base prompt.", results)
-        assert result == "Base prompt.\n\nabc123 fix bug"
+        assert result == "Base prompt."
 
     def test_named_placeholder_replaced(self):
         results = self._make_results(("git-log", "abc123 fix\n"))
@@ -399,26 +399,15 @@ def test_named_placeholder_replaced(self):
         assert "abc123 fix" in result
         assert "{{ contexts.git-log }}" not in result
 
-    def test_bulk_placeholder_injects_all(self):
+    def test_unreferenced_contexts_excluded(self):
         results = self._make_results(
             ("alpha", "Alpha output\n"),
             ("beta", "Beta output\n"),
         )
-        prompt = "Start.\n\n{{ contexts }}\n\nEnd."
+        prompt = "Only alpha: {{ contexts.alpha }}"
         result = resolve_contexts(prompt, results)
         assert "Alpha output" in result
-        assert "Beta output" in result
-        assert "{{ contexts }}" not in result
-
-    def test_named_excludes_from_bulk(self):
-        results = self._make_results(
-            ("alpha", "Alpha output\n"),
-            ("beta", "Beta output\n"),
-        )
-        prompt = "{{ contexts.alpha }}\n\n{{ contexts }}"
-        result = resolve_contexts(prompt, results)
-        assert result.count("Alpha output") == 1
-        assert "Beta output" in result
+        assert "Beta output" not in result
 
     def test_multiple_named_placeholders(self):
         results = self._make_results(
@@ -451,7 +440,7 @@ def test_static_content_included(self):
             static_content="Header:",
         )
         results = [ContextResult(context=ctx, output="dynamic\n", success=True)]
-        prompt = "{{ contexts }}"
+        prompt = "{{ contexts.info }}"
         result = resolve_contexts(prompt, results)
         assert "Header:" in result
         assert "dynamic" in result