SourceIndex 0.1.0__py3-none-any.whl

sourceindex/search/passes.py

@@ -0,0 +1,51 @@
+"""Two-pass LLM file/function selection.
+
+Pass 1a: index_search_model reads tier-1 index + query → picks relevant files.
+Pass 1b: index_search_model reads tier-2 function indexes → picks specific
+         functions, tagging each EDIT or READ.
+
+The two helpers here also clean up LLM prose around the selection lines so
+roadmap synthesis sees clean data.
+"""
+
+from ..lib.languages import all_extensions, default_languages
+
+
+# All registered source-file extensions, used to detect path-like lines in
+# LLM output (Pass 1a/1b post-processing) regardless of language. Cached at
+# import time so the every-file roadmap loop doesn't rebuild it.
+_KNOWN_EXTENSIONS: tuple[str, ...] = all_extensions(list(default_languages()))
+
+
+def _looks_like_path(line: str) -> bool:
+    """Heuristic: line looks like a file path (any registered language) or a
+    file::function entry. Used to filter LLM prose out of Pass 1a/1b output."""
+    s = line.strip()
+    if not s:
+        return False
+    if "::" in s or "/" in s:
+        return True
+    return s.lower().endswith(_KNOWN_EXTENSIONS)
+
+
+def _strip_llm_wrapper(text: str) -> str:
+    """Strip markdown fences and prose from LLM output, keeping only data lines.
+
+    Smarter models (Sonnet/Opus) sometimes wrap output in ```...``` blocks
+    and add explanatory prose despite being told not to. This extracts only
+    the lines that look like file paths or file::function entries across all
+    registered languages.
+    """
+    lines = text.strip().split("\n")
+    in_fence = False
+    fenced: list[str] = []
+    for line in lines:
+        stripped = line.strip()
+        if stripped.startswith("```"):
+            in_fence = not in_fence
+            continue
+        if in_fence:
+            fenced.append(stripped)
+    if fenced:
+        return "\n".join(fenced)
+    return "\n".join(ln.strip() for ln in lines if _looks_like_path(ln))

sourceindex/search/prompts.py

@@ -0,0 +1,379 @@
+"""LLM prompts + roadmap template used by the search pipeline.
+
+PASS_1A_PROMPT — file-level selection from the tier-1 index.
+PASS_1B_PROMPT — function-level selection from tier-2 details, with
+                 EDIT/READ tagging.
+ROADMAP_TEMPLATE — wraps Pass 1b output into the authoritative pre-analysis
+                   delivered to the agent.
+
+QA variants (suffix _QA) are used when mode="qa": no EDIT tags, relaxed
+constraints (runtime exploration encouraged, no recon-bash ban).
+"""
+
+
+PASS_1A_PROMPT = """You are analyzing a source codebase to help another AI implement a feature.
+
+=== CODEBASE INDEX ===
+Each line: file_path — one-line description.
+
+{index_content}
+
+=== TASK ===
+{instruction}
+
+=== YOUR JOB ===
+Based on the task and codebase index, list the file paths (one per line) that are most likely to need reading or modification to implement this feature.
+
+Output ONLY file paths, one per line. No explanation, no markdown, no numbering.
+Include files that:
+- Would need to be modified to implement the feature
+- Contain related classes/functions the implementation depends on
+- Contain test patterns that reveal expected behavior
+List every file that is genuinely relevant — do not cap the count artificially."""
+
+
+PASS_1B_PROMPT = """You are analyzing a source codebase to help another AI implement a feature.
+
+=== FUNCTION-LEVEL INDEXES OF SELECTED FILES ===
+Each file lists its classes/functions with name, line range, and purpose.
+
+{selected_details}
+
+=== TASK ===
+{instruction}
+
+=== YOUR JOB ===
+Produce two sections, in this order, separated by the literal marker lines
+shown below. Output nothing outside these two sections.
+
+------------------------------------------------------------------------
+SECTION A — CODE LANDSCAPE (markdown, target 800–1500 tokens)
+------------------------------------------------------------------------
+Write a structured handoff describing the code landscape around the change
+site, in the style of a thorough codebase-exploration report. Use markdown
+sub-headers (### …). Cover:
+
+  • Where the change site sits in the architecture (which module, what
+    it's next to, what calls it).
+  • Conventions / patterns the surrounding code follows — naming, base
+    classes, how siblings are structured.
+  • Sibling files relevant as templates or examples — list their paths
+    with their one-line role, even if you do NOT recommend reading them.
+    The downstream agent should know these exist as patterns.
+  • Non-obvious gotchas the tier-2 indexes reveal — special cases,
+    version branches, edge cases tested.
+  • Cite specific paths and line ranges where load-bearing.
+
+Do NOT inline code snippets — function bodies belong in the agent's later
+Read calls, not in this landscape. Path + range citations only.
+
+Do NOT recap the SECTION B selections in prose — landscape only.
+
+------------------------------------------------------------------------
+SECTION B — SELECTIONS (structured, one per line)
+------------------------------------------------------------------------
+List the specific functions and classes that are most relevant to
+implementing this task. For each, output one line in this exact format:
+<TAG> file_path::QualifiedName (Lstart-Lend)
+
+Where <TAG> is:
+- EDIT: this function/class will be modified (new code added, existing
+  code changed) to implement the task.
+- READ: this function/class is reference material — called, extended,
+  followed as a pattern, or verified via tests.
+
+STRICT TAGGING RULE: A file is EDIT only if new lines will be added or
+existing lines changed there. Everything else — tests, sibling plugins,
+base classes, utilities, reference patterns, callers, examples — is READ.
+
+VETO RULE: A file in the input list may turn out to have no function
+genuinely relevant to this task — Pass 1a casts a wide net by design.
+If that is the case for a file, do NOT emit any SELECTIONS line for it.
+Files with zero emitted entries are dropped from the structured roadmap.
+You can still mention the file in SECTION A as a pattern/sibling if it
+helps the agent — that's exactly the landscape signal.
+
+The veto's purpose is to remove files that are clearly siblings/extras
+Pass 1a picked up by proximity. It is NOT to second-guess Pass 1a's
+central picks when their relevance is ambiguous.
+
+FLOOR: The SELECTIONS list MUST contain at least 3 files. If relevance is
+ambiguous for some of Pass 1a's picks, default to keeping rather than
+dropping — the LANDSCAPE block can de-emphasize a file without removing
+it from the structured roadmap. An empty or near-empty SELECTIONS list
+is a Pass-1b failure mode, not a feature. Only emit fewer than 3 files
+when the task genuinely touches a single file (e.g. a one-line config
+fix); in that case still include the file's tests as READ entries.
+
+Example output (format only — content depends on task):
+
+=== CODE LANDSCAPE ===
+### Change site
+The feature touches `beets/autotag/match.py`, specifically `tag_album`
+(L200-L250) which orchestrates album-level matching after track candidates
+are scored.
+
+### Surrounding patterns
+Matching helpers follow a consistent shape: each scoring function returns
+a `Distance` object built from comparator deltas. See `match.py::distance`
+(L80-L110) for the canonical pattern.
+
+### Sibling files (pattern reference, not necessarily to be read)
+- `beets/autotag/mb.py` — MusicBrainz lookup hooks, mirrors `match.py`'s
+  callback shape.
+- `beets/util.py` — utility helpers; offered by Pass 1a but no function
+  here is task-relevant.
+
+### Gotchas
+The candidate cache (`match.py` L150) silently dedupes by track-id; new
+scoring logic must handle the deduped list, not the raw candidates.
+
+=== SELECTIONS ===
+EDIT beets/autotag/match.py::tag_album (L200-L250)
+READ beets/plugins.py::BeetsPlugin.commands (L45-L60)
+READ test/test_match.py::test_tag_album (L100-L140)
+
+Output the literal markers `=== CODE LANDSCAPE ===` and `=== SELECTIONS ===`
+exactly. No markdown fences around the whole output. No prose outside the
+two sections."""
+
+
+# ── QA variants ──────────────────────────────────────────────────────────
+
+PASS_1A_QA_PROMPT = """You are analyzing a source codebase to help another AI answer a question.
+
+=== CODEBASE INDEX ===
+Each line: file_path — one-line description.
+
+{index_content}
+
+=== QUESTION ===
+{instruction}
+
+=== YOUR JOB ===
+Based on the question and codebase index, list the file paths (one per line)
+that are most relevant to answering this question.
+
+Output ONLY file paths, one per line. No explanation, no markdown, no numbering.
+Copy each path EXACTLY as it appears in the index above — same relative form,
+no added prefix (such as /app/) and no leading slash.
+Include files that:
+- Contain code directly referenced or asked about in the question
+- Implement the subsystem, feature, or behavior the question concerns
+- Contain configuration, initialization, or entry points relevant to the topic
+- Would help the answerer understand the architecture around the question
+List every file that is genuinely relevant — do not cap the count artificially."""
+
+
+PASS_1B_QA_PROMPT = """You are analyzing a source codebase to help another AI answer a question.
+
+=== FUNCTION-LEVEL INDEXES OF SELECTED FILES ===
+Each file lists its classes/functions with name, line range, and purpose.
+
+{selected_details}
+
+=== QUESTION ===
+{instruction}
+
+=== YOUR JOB ===
+Produce two sections, in this order, separated by the literal marker lines
+shown below. Output nothing outside these two sections.
+
+------------------------------------------------------------------------
+SECTION A — CODE LANDSCAPE (markdown, target 300–700 tokens)
+------------------------------------------------------------------------
+Write a structured handoff describing the code landscape relevant to the
+question. Keep it narrow: include only context that helps the downstream
+agent decide where to read or what to verify. Use markdown sub-headers
+(### …). Cover:
+
+  • How the subsystem(s) the question asks about fit in the architecture
+    (which module, what depends on them, what calls them).
+  • Key abstractions, patterns, and conventions in the relevant code —
+    class hierarchies, naming, configuration loading, etc.
+  • Sibling files relevant as context — list their paths with their
+    one-line role, even if you do NOT recommend reading them.
+  • Non-obvious gotchas the tier-2 indexes reveal — edge cases, version
+    branches, runtime vs compile-time behavior, dynamic dispatch.
+  • Cite specific paths and line ranges where load-bearing.
+
+Do NOT inline code snippets or answer the question — function bodies and
+runtime facts belong in the agent's later Reads/Bash output, not in this
+landscape. Path + range citations only.
+
+Do NOT recap the SECTION B selections in prose — landscape only.
+
+------------------------------------------------------------------------
+SECTION B — SELECTIONS (structured, one per line)
+------------------------------------------------------------------------
+List the specific functions and classes that are most relevant to
+answering this question. For each, output one line in this exact format:
+READ file_path::QualifiedName (Lstart-Lend)
+
+Every entry is READ — this is an investigation, not a modification task.
+The agent will read these to understand the code, not edit it.
+
+VETO RULE: A file in the input list may turn out to have no function
+genuinely relevant to this question — Pass 1a casts a wide net by design.
+If that is the case for a file, do NOT emit any SELECTIONS line for it.
+Files with zero emitted entries are dropped from the structured roadmap.
+You can still mention the file in SECTION A as context/sibling if it
+helps the agent — that's exactly the landscape signal.
+
+FLOOR: The SELECTIONS list MUST contain at least 3 files. If relevance is
+ambiguous for some of Pass 1a's picks, default to keeping rather than
+dropping. An empty or near-empty SELECTIONS list is a Pass-1b failure mode.
+
+Example output (format only — content depends on question):
+
+=== CODE LANDSCAPE ===
+### Relevant subsystem
+The question concerns `src/auth/middleware.py`, the WSGI middleware that
+intercepts every request and resolves the session token (L40-L85).
+
+### How auth is wired
+The middleware is registered in `src/app.py::create_app` (L20-L35). It
+delegates to `src/auth/backends.py` for token-to-user resolution.
+
+### Sibling files (context, not necessarily to be read)
+- `src/auth/backends.py` — token resolution strategies (DB, JWT, cookie).
+- `src/auth/models.py` — the User and Session ORM models.
+
+### Gotchas
+Token refresh (L60-L72) silently extends expired sessions by 30 min;
+the logging at L68 only fires in DEBUG mode — easy to miss in production.
+
+=== SELECTIONS ===
+READ src/auth/middleware.py::AuthMiddleware.__call__ (L40-L85)
+READ src/auth/backends.py::resolve_token (L15-L45)
+READ src/app.py::create_app (L20-L35)
+
+Output the literal markers `=== CODE LANDSCAPE ===` and `=== SELECTIONS ===`
+exactly. No markdown fences around the whole output. No prose outside the
+two sections."""
+
+
+ROADMAP_TEMPLATE = """=== CODEBASE ROADMAP (authoritative pre-analysis) ===
+
+This roadmap is the output of a dedicated analysis pass over the full codebase
+(file-level Pass 1a + function-level Pass 1b, both reading complete tier-1 and
+tier-2 indexes). Line ranges are AST-extracted function boundaries, not
+estimates. Treat it as authoritative — it IS the index. Do not rebuild it
+with grep/find/ls; do not second-guess its ranges with whole-file reads.
+
+{context_section}
+
+OPENING TURN — read every roadmap file at once, in parallel:
+
+  Your first response should contain ONE Read tool call PER file listed
+  below, all in the same response (multiple tool_use blocks in one turn).
+  For a 4-file roadmap, that is 4 Read calls in turn 1, NOT 4 separate
+  turns. Each new turn rebuilds ~$0.05 of input cache and adds latency;
+  the roadmap was paid for once — read all of it at once. After that
+  single turn you have the entire context — proceed to Edit.
+
+CONSTRAINTS (after the opening turn):
+
+1. PARALLELIZE: Any time you need multiple independent Reads, Greps, or Bash
+   commands, issue them in a SINGLE response with multiple tool_use blocks —
+   not one tool call per turn. Serializing wastes turns and rebuilds cache.
+
+2. USE THE LISTED RANGE: Each file below has an explicit (offset, limit).
+   Pass them to Read as-is. Do NOT call Read with no offset/limit on a
+   file that has a range listed — the range came from AST function
+   boundaries, not heuristics. Whole-file reads on roadmap files burn
+   tokens for no information gain.
+
+3. READ ONCE: Read each listed (offset, limit) exactly once. Files marked
+   [EDIT TARGET] may carry a small imports-preamble hint alongside the
+   function range — read both so you can add new imports without duplicating.
+   Do not re-Read a span you have already Read — scroll back instead.
+
+4. GAP-BEFORE-READ: Before reading or searching any file NOT listed below, you
+   MUST first state the specific gap in one sentence. Example:
+   "The roadmap covers the Discogs plugin but not the MusicBrainz sibling;
+    reading musicbrainz.py to find the extra_mb_field_by_tag pattern."
+   If you cannot name a concrete gap, the roadmap is sufficient — proceed to Edit.
+
+5. NO RECON BASH: Do not run `git log`, `ls`, `find`, `pip list`, `which`,
+   `env`, or other reconnaissance commands. The roadmap + its imports IS the
+   recon. If you think you need to look at the filesystem or environment,
+   you don't — re-read the roadmap entry instead.
+
+6. TEST RECOVERY: If a test fails with ImportError / ModuleNotFoundError /
+   command-not-found, the recovery is a single chained bash:
+   `pip install <pkg> -q && <retry command>`. Do not `find` the package on
+   disk, `ls` the venv, or inspect `env` first — the package name is in the
+   error and pip will resolve the path.
+
+Entries are grouped by file.
+
+{grouped}
+=== IMPORT STATEMENTS (extracted from files above) ===
+
+{import_section}
+=== END CODEBASE ROADMAP ===
+"""
+
+
+ROADMAP_QA_TEMPLATE = """=== CODEBASE ROADMAP (navigation pre-context) ===
+
+This roadmap is the output of a dedicated analysis pass over the full codebase
+(file-level Pass 1a + function-level Pass 1b, both reading complete tier-1 and
+tier-2 indexes). Line ranges are AST-extracted function boundaries, not
+estimates. Treat it as a navigation index, not evidence or a substitute answer.
+
+=== QUESTION TO ANSWER ===
+
+{question}
+
+=== ANSWER CONTRACT ===
+
+- Answer every part of the question.
+- If the question asks to run, verify, observe, measure, trace, or show output,
+  execute the relevant command or workflow and paste the literal runtime evidence.
+- Use this roadmap to find where to investigate; do not satisfy evidence
+  requirements from the roadmap or static source summaries alone.
+
+{context_section}
+
+OPENING TURN — read every roadmap file at once, in parallel:
+
+  Your first response should contain ONE Read tool call PER file listed
+  below, all in the same response (multiple tool_use blocks in one turn).
+  For a 4-file roadmap, that is 4 Read calls in turn 1, NOT 4 separate
+  turns. Each new turn rebuilds ~$0.05 of input cache and adds latency;
+  the roadmap was paid for once — read all of it at once. After that
+  single turn you have the full structural context.
+
+CONSTRAINTS (after the opening turn):
+
+1. PARALLELIZE: Any time you need multiple independent Reads, Greps, or Bash
+   commands, issue them in a SINGLE response with multiple tool_use blocks —
+   not one tool call per turn. Serializing wastes turns and rebuilds cache.
+
+2. USE THE LISTED RANGE: Each file below has an explicit (offset, limit).
+   Pass them to Read as-is. Do NOT call Read with no offset/limit on a
+   file that has a range listed — the range came from AST function
+   boundaries, not heuristics. Whole-file reads on roadmap files burn
+   tokens for no information gain.
+
+3. READ ONCE: Read each listed (offset, limit) exactly once.
+   Do not re-Read a span you have already Read — scroll back instead.
+
+4. EXPLORE BEYOND THE ROADMAP WHEN NEEDED: The roadmap covers the structural
+   layout — the files and functions most relevant to the question. If you need
+   to trace a call chain further, check runtime behavior, inspect configuration,
+   or follow an import the roadmap didn't cover, go ahead. State the gap briefly
+   ("the roadmap covers X but I need to check Y for Z") and proceed.
+
+5. RUNTIME EXPLORATION IS EXPECTED: Many questions require observing actual
+   behavior — running the application, executing test scripts, inspecting output.
+   Use Bash freely for runtime investigation. The roadmap tells you WHERE to
+   look; execution tells you WHAT HAPPENS.
+
+Entries are grouped by file.
+
+{grouped}
+=== END CODEBASE ROADMAP ===
+"""

sourceindex/search/roadmap.py

@@ -0,0 +1,265 @@
+"""Roadmap synthesis: turn Pass-1b output into the authoritative pre-analysis.
+
+Annotates each function entry with its tier-2 description, groups entries
+per file, computes merged read windows from per-function ranges, marks
+EDIT targets, prepends an imports-preamble Read window for Python EDIT
+targets, and wraps everything in ROADMAP_TEMPLATE.
+"""
+
+import re
+from pathlib import Path
+
+from ..lib.log import get_logger, log_file_error
+from .imports import _imports_preamble_end, extract_imports
+from .prompts import ROADMAP_QA_TEMPLATE, ROADMAP_TEMPLATE
+
+_log = get_logger(__name__)
+
+
+_RANGE_RE = re.compile(r"\(L(\d+)-L(\d+)\)")
+_TAG_RE = re.compile(r"^(EDIT|READ)\s+")
+
+# Test files are never an imports-preamble target — tests don't gain new imports
+# from the main code change. Haiku's Pass 1b was observed to mis-tag test files
+# as EDIT ~half the time on beets benchmarks; this regex is the belt to the prompt's
+# suspenders.
+_TEST_PATH_RE = re.compile(r"(^|/)tests?/|(^|/)(test_\w+|\w+_test)\.\w+$")
+
+
+def _strip_desc_prefix(line: str) -> str:
+    """Detail files store each entry as `<name/range>: <description>`."""
+    idx = line.find(": ")
+    return (line[idx + 2:] if idx >= 0 else line).strip()
+
+
+def _lookup_description(
+    detail_lines: list[str],
+    range_part: str,
+    func_name: str,
+) -> str:
+    """Find the tier-2 description. Range match wins (disambiguates duplicate
+    method names like `__init__`); qualified-name match is the fallback."""
+    if range_part:
+        for line in detail_lines:
+            if range_part in line:
+                return _strip_desc_prefix(line)
+
+    if func_name:
+        name_re = re.compile(rf"(^|\.){re.escape(func_name)} \(L")
+        for line in detail_lines:
+            if name_re.search(line):
+                return _strip_desc_prefix(line)
+
+    return ""
+
+
+def _load_detail_lines(
+    fpath: str,
+    store,
+    detail_texts: dict[str, str] | None,
+    cache: dict[str, list[str]],
+) -> list[str]:
+    """Memoize splitlines() across entries that share a source file.
+
+    Prefers the pre-loaded ``detail_texts`` dict (populated by Pass 1a so
+    we don't double-decrypt encrypted blobs) and falls back to a fresh
+    store read for files Pass 1b raised that weren't in 1a's selection.
+    """
+    lines = cache.get(fpath)
+    if lines is None:
+        text: str | None = None
+        if detail_texts is not None and fpath in detail_texts:
+            text = detail_texts[fpath]
+        else:
+            rel = f"details/{fpath}.md"
+            try:
+                if store is not None and store.exists(rel):
+                    text = store.read_text(rel)
+            except Exception as e:
+                log_file_error(_log, rel, e, phase="roadmap.detail")
+                text = None
+        lines = text.splitlines() if text else []
+        cache[fpath] = lines
+    return lines
+
+
+def _looks_like_test(fpath: str) -> bool:
+    return bool(_TEST_PATH_RE.search(fpath))
+
+
+def _compute_read_windows(
+    ranges: list[tuple[int, int]],
+    merge_gap: int = 10_000,
+) -> list[tuple[int, int]]:
+    """Collapse per-function ranges into read windows.
+
+    1. Drop wrappers — an entry whose range fully contains another entry's
+       range is redundant (Haiku often lists the whole class alongside its
+       methods; the class entry is descriptive, the methods tell us what
+       to actually read). If every range wraps something, keep them all.
+    2. Merge close-or-overlapping — adjacent windows within ``merge_gap``
+       lines collapse into one. Default is effectively "always merge":
+       experiments with narrow multi-window output (``merge_gap=30``) showed
+       opus didn't reliably parallelize the resulting Reads, adding turns
+       and cost. A single merged window per file tracks the pre-wrapper-drop
+       behaviour while still avoiding the "whole-class-entry inflates limit"
+       pathology.
+    """
+    if not ranges:
+        return []
+    uniq = sorted(set(ranges))
+    non_wrappers = [
+        (s, e) for s, e in uniq
+        if not any(os >= s and oe <= e and (os, oe) != (s, e) for os, oe in uniq)
+    ]
+    effective = non_wrappers or uniq
+    effective.sort()
+    merged: list[tuple[int, int]] = [effective[0]]
+    for s, e in effective[1:]:
+        last_s, last_e = merged[-1]
+        if s <= last_e + merge_gap:
+            merged[-1] = (last_s, max(last_e, e))
+        else:
+            merged.append((s, e))
+    return merged
+
+
+def _build_roadmap(
+    function_list: str,
+    repo_root: Path,
+    store=None,
+    detail_texts: dict[str, str] | None = None,
+    *,
+    details_dir: Path | None = None,
+    landscape: str | None = None,
+    mode: str = "implement",
+    question: str | None = None,
+) -> str:
+    """Annotate, group, and wrap pass-1b output into the roadmap preamble.
+
+    ``store`` is the daemon-aware path. ``details_dir`` is the legacy path
+    for callers that haven't migrated yet — when set, we wrap it in a
+    ``PlaintextStore`` so the same lookup logic applies."""
+    if store is None and details_dir is not None:
+        # Reconstruct a store from the legacy details_dir argument by
+        # walking back to the index_dir (the parent of details/).
+        from ..daemon import PlaintextStore
+        store = PlaintextStore(details_dir.parent)
+    order: list[str] = []
+    per_file: dict[str, list[str]] = {}
+    file_ranges: dict[str, list[tuple[int, int]]] = {}
+    edit_files: set[str] = set()
+    detail_cache: dict[str, list[str]] = {}
+
+    for raw in function_list.split("\n"):
+        line = raw.strip()
+        if not line or "::" not in line:
+            continue
+
+        # Strip the optional EDIT/READ tag. Absence => treat as READ for
+        # backward compatibility with older Pass 1b outputs.
+        tag_match = _TAG_RE.match(line)
+        tag = tag_match.group(1) if tag_match else "READ"
+        line = _TAG_RE.sub("", line, count=1)
+
+        fpath_raw, rest = line.split("::", 1)
+        fpath = fpath_raw.strip().lstrip("/")
+
+        range_match = _RANGE_RE.search(rest)
+        range_part = range_match.group(0) if range_match else ""
+        func_name = rest.split("(", 1)[0].strip()
+        detail_lines = _load_detail_lines(fpath, store, detail_texts, detail_cache)
+        desc = _lookup_description(detail_lines, range_part, func_name)
+        entry = f"  {rest} — {desc}" if desc else f"  {rest}"
+
+        if fpath not in per_file:
+            per_file[fpath] = []
+            order.append(fpath)
+        per_file[fpath].append(entry)
+
+        is_qa = mode == "qa"
+        if not is_qa and tag == "EDIT" and not _looks_like_test(fpath):
+            edit_files.add(fpath)
+
+        if range_match:
+            s, e = int(range_match.group(1)), int(range_match.group(2))
+            file_ranges.setdefault(fpath, []).append((s, e))
+
+    if mode != "qa" and not edit_files:
+        promoted = next(
+            (fp for fp in order if fp in file_ranges and not _looks_like_test(fp)),
+            None,
+        )
+        if promoted:
+            edit_files.add(promoted)
+
+    # Module tops (imports, constants, class/module setup) are frequent targets
+    # of follow-up reads. Extend the first window's start back to line 1 when
+    # its first line sits within HEADER_PREFIX_MAX lines of the top; beyond
+    # that, keep the narrow range (and add a separate imports-preamble hint
+    # for EDIT targets, since they'll add new imports at the file top).
+    # Path-emission helper: header / import-block lines are absolute so the
+    # agent has an unambiguous Read target regardless of its cwd. Roadmap
+    # consumers should never need to guess between EXTRACT_DIR / WORKSPACE_DIR.
+    # Function-detail lines (per_file entries with `file::QualifiedName` syntax)
+    # stay relative — they're descriptive, not Read targets.
+    abs_root = str(repo_root)
+    def _abs(fp: str) -> str:
+        return f"{abs_root}/{fp}"
+
+    is_qa = mode == "qa"
+    HEADER_PREFIX_MAX = 80
+    grouped_lines: list[str] = []
+    for fpath in order:
+        marker = "" if is_qa else ("  [EDIT TARGET]" if fpath in edit_files else "")
+        ranges = file_ranges.get(fpath, [])
+        if not ranges:
+            grouped_lines.append(f"{_abs(fpath)}{marker} — Read ONCE (full file)")
+            grouped_lines.extend(per_file[fpath])
+            grouped_lines.append("")
+            continue
+
+        windows = _compute_read_windows(ranges)
+        first_s, first_e = windows[0]
+        if first_s <= HEADER_PREFIX_MAX:
+            windows[0] = (1, first_e)
+        elif not is_qa and fpath.endswith(".py") and fpath in edit_files:
+            preamble_end = _imports_preamble_end(repo_root / fpath)
+            if preamble_end > 0:
+                windows.insert(0, (1, preamble_end))
+
+        for s, e in windows:
+            grouped_lines.append(
+                f"{_abs(fpath)}{marker} — Read ONCE: offset={s} limit={e - s + 1}"
+            )
+            marker = ""
+        grouped_lines.extend(per_file[fpath])
+        grouped_lines.append("")
+    grouped = "\n".join(grouped_lines)
+
+    landscape_text = (landscape or "").strip()
+    context_section = (
+        f"=== CODE LANDSCAPE (from Pass 1b) ===\n\n{landscape_text}\n"
+        if landscape_text
+        else ""
+    )
+
+    if is_qa:
+        return ROADMAP_QA_TEMPLATE.format(
+            grouped=grouped,
+            context_section=context_section,
+            question=(question or "").strip(),
+        )
+
+    import_blocks: list[str] = []
+    for fpath in order:
+        imports = extract_imports(repo_root / fpath, fpath)
+        if imports:
+            import_blocks.append(f"--- {_abs(fpath)} ---\n{imports}\n")
+    import_section = "\n".join(import_blocks)
+
+    return ROADMAP_TEMPLATE.format(
+        grouped=grouped,
+        import_section=import_section,
+        context_section=context_section,
+    )