codd-dev 2.25.0__tar.gz → 2.26.0__tar.gz

{codd_dev-2.25.0 → codd_dev-2.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codd-dev
-Version: 2.25.0
+Version: 2.26.0
 Summary: CoDD: Coherence-Driven Development — cross-artifact change impact analysis
 Project-URL: Homepage, https://github.com/yohey-w/codd-dev
 Project-URL: Repository, https://github.com/yohey-w/codd-dev

{codd_dev-2.25.0 → codd_dev-2.26.0}/codd/__init__.py

@@ -1,3 +1,3 @@
 """CoDD — Coherence-Driven Development."""
 
-__version__ = "2.25.0"
+__version__ = "2.26.0"

{codd_dev-2.25.0 → codd_dev-2.26.0}/codd/greenfield/pipeline.py

@@ -741,14 +741,16 @@ class GreenfieldPipeline:
         Ensures the stack topology is scaffolded first (idempotent — the same
         ``_ensure_test_runner`` verify uses), so the oracle's config (tsconfig)
         exists to certify and run against AT implement-time. Then runs the gate
-        with a ``rerun(feedback)`` callback that re-invokes implementation for
-        every task carrying the normalized oracle feedback (the cross-file
-        incoherence is not localized to one task, so the whole build is
-        regenerated under the feedback — the same broad-rerun shape the VB
-        coverage gate uses). A non-passing final result is a StageError; an
-        uncertifiable oracle scope (OracleScopeError) propagates as a hard
-        failure. The whole gate is a NO-OP for a stack without a declared
-        implement-time oracle.
+        with a SCOPED ``rerun(feedback, scope)`` callback: on an oracle failure
+        the gate derives the both-ends-of-the-broken-edge scope and re-implements
+        ONLY the owning tasks (under a write-fence), escalating
+        narrow→expanded→broad only when the diagnostic signature fails to move
+        (see ``codd.implement_oracle_scope`` + ``run_implement_oracle_gate``).
+        ``scope is None`` ⇒ the broad fallback (re-implement every task — the
+        legacy shape the VB coverage gate uses). A non-passing final result is a
+        StageError; an uncertifiable oracle scope (OracleScopeError) propagates
+        as a hard failure. The whole gate is a NO-OP for a stack without a
+        declared implement-time oracle.
         """
         from codd.implement_oracle import (
             OracleScopeError,
@@ -776,8 +778,14 @@ class GreenfieldPipeline:
         # clobbering, so verify's re-scaffold is a no-op.
         self._ensure_test_runner(project_root)
 
-        def _rerun(feedback: str) -> None:
-            self._rerun_tasks_with_feedback(project_root, tasks, feedback, options)
+        # The path→owning-task index for the SCOPED rerun: declared task outputs
+        # UNION the config-derived output paths. Built once; the gate consults it
+        # to localize each rerun to the diagnostics' owners.
+        scope_index = self._build_oracle_scope_index(project_root, tasks, config)
+        manifest_paths = self._oracle_manifest_paths(project_root)
+
+        def _rerun(feedback: str, scope: Any = None) -> None:
+            self._rerun_tasks_with_feedback(project_root, tasks, feedback, options, scope=scope)
 
         try:
             result = run_implement_oracle_gate(
@@ -789,6 +797,8 @@ class GreenfieldPipeline:
                 config=config,
                 rerun=_rerun,
                 echo=self.echo,
+                scope_index=scope_index,
+                manifest_paths=manifest_paths,
             )
         except OracleScopeError as exc:
             raise StageError(str(exc)) from exc
@@ -802,29 +812,122 @@ class GreenfieldPipeline:
                 f"{result.category_counts()}. {result.detail}"
             )
 
+    def _build_oracle_scope_index(
+        self,
+        project_root: Path,
+        tasks: list[ImplementTaskRef],
+        config: dict[str, Any],
+    ) -> Any:
+        """Build the path→owning-task index used to scope an oracle rerun.
+
+        Unions each task's DECLARED ``output_paths`` with its CONFIG-derived
+        output paths (``_output_paths_for_task`` — the same resolution the rerun
+        itself uses), so a diagnostic on any owned file/dir maps back to the task
+        that wrote it. A failure to build the index degrades the gate to the
+        broad rerun (``None`` → ``scope_index`` unset), never aborts.
+        """
+        try:
+            from codd.implement_oracle_scope import build_path_owner_index
+
+            config_output_paths: dict[str, list[str]] = {}
+            for task in tasks:
+                try:
+                    config_output_paths[task.task_id] = (
+                        list(task.output_paths)
+                        if task.output_paths
+                        else _output_paths_for_task(config, task)
+                    )
+                except Exception:  # noqa: BLE001 — a task whose paths fail just falls to broad.
+                    config_output_paths[task.task_id] = list(task.output_paths or ())
+            return build_path_owner_index(
+                tasks,
+                project_root=project_root,
+                config=config,
+                config_output_paths=config_output_paths,
+            )
+        except Exception as exc:  # noqa: BLE001 — index build is best-effort.
+            self.echo(f"[greenfield] implement-oracle: scope index unavailable ({exc}); rerun stays broad.")
+            return None
+
+    def _oracle_manifest_paths(self, project_root: Path) -> tuple[str, ...]:
+        """Manifest/config files the write-fence always permits (they are shared).
+
+        A scoped rerun may legitimately touch the build manifest/config even when
+        no task "owns" it (e.g. adding a dependency the fix needs). Only files
+        that actually exist are listed, project-relative.
+        """
+        candidates = (
+            "package.json",
+            "tsconfig.json",
+            "package-lock.json",
+            "pnpm-lock.yaml",
+            "yarn.lock",
+        )
+        present: list[str] = []
+        for name in candidates:
+            if (project_root / name).is_file():
+                present.append(name)
+        return tuple(present)
+
     def _rerun_tasks_with_feedback(
         self,
         project_root: Path,
         tasks: list[ImplementTaskRef],
         feedback: str,
         options: dict[str, Any],
+        *,
+        scope: Any = None,
     ) -> None:
-        """Re-invoke implementation for every task carrying ``feedback``.
-
-        Routes through the SAME implement path the stage uses
-        (``implement_tasks`` with the resolved output paths), threading the
-        normalized oracle feedback so the SUT regenerates coherent files. Uses
-        the configured implement-task runner only when it is the default
-        (feedback-aware path); a custom injected runner has no feedback channel,
-        so this falls back to ``implement_tasks`` directly.
+        """Re-invoke implementation under ``feedback`` — SCOPED when ``scope`` set.
+
+        ``scope is None`` (or a broad scope) → re-implement EVERY task (the
+        legacy broad rerun). A scoped :class:`~codd.implement_oracle_scope.OracleRerunScope`
+        → re-implement ONLY its ``task_ids``, under a WRITE-FENCE: out-of-scope
+        files the SUT writes during the scoped rerun are reverted afterwards (an
+        out-of-scope CREATE is removed, an out-of-scope MODIFY is restored), so a
+        "targeted" rerun cannot silently regenerate the whole tree. The fence is
+        OFF for a broad rerun (broad legitimately rewrites everything).
+
+        Routes through the SAME implement path the stage uses (``implement_tasks``
+        with the resolved output paths), threading the normalized oracle feedback
+        so the SUT regenerates coherent files.
         """
         from codd.config import load_project_config
-        from codd.implementer import implement_tasks
 
         try:
             config = load_project_config(project_root)
         except (FileNotFoundError, ValueError):
             config = {}
+
+        scoped = scope is not None and not bool(getattr(scope, "is_broad", lambda: False)())
+        if not scoped:
+            self._reimplement_tasks(project_root, tasks, feedback, config)
+            return
+
+        # Scoped rerun: only the scope's tasks, fenced to its allowed paths.
+        target_ids = set(getattr(scope, "task_ids", ()) or ())
+        scoped_tasks = [task for task in tasks if task.task_id in target_ids]
+        if not scoped_tasks:
+            # Nothing resolvable in this scope (defensive) → broad, never a no-op.
+            self.echo("[greenfield] implement-oracle: scoped task set empty — re-running broad.")
+            self._reimplement_tasks(project_root, tasks, feedback, config)
+            return
+
+        allowed = tuple(getattr(scope, "allowed_paths", ()) or ())
+        with _OracleWriteFence(project_root, allowed_paths=allowed, echo=self.echo) as fence:
+            self._reimplement_tasks(project_root, scoped_tasks, feedback, config)
+            fence.enforce()
+
+    def _reimplement_tasks(
+        self,
+        project_root: Path,
+        tasks: list[ImplementTaskRef],
+        feedback: str,
+        config: dict[str, Any],
+    ) -> None:
+        """Re-run ``implement_tasks`` for each given task carrying ``feedback``."""
+        from codd.implementer import implement_tasks
+
         for task in tasks:
             output_paths = (
                 list(task.output_paths)
@@ -1253,6 +1356,144 @@ def _default_generate_wave_runner(project_root: Path, wave: int, *, ai_command:
     return f"{generated} generated, {len(results) - generated} skipped"
 
 
+#: Directories never snapshotted/fenced — vendored deps, VCS, the codd cache,
+#: build output. A write here is not a SUT source-write the fence governs.
+_FENCE_EXCLUDE_DIRS = frozenset(
+    {"node_modules", ".git", ".codd", ".hg", ".svn", "dist", "build", "__pycache__", ".pytest_cache"}
+)
+#: Source/test file suffixes the fence tracks. Restricting to code keeps the
+#: snapshot cheap and avoids fighting tooling that touches caches/logs.
+_FENCE_TRACKED_SUFFIXES = frozenset(
+    {".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs", ".py", ".json"}
+)
+
+
+class _OracleWriteFence:
+    """Restrict a SCOPED oracle rerun's writes to the scope's ``allowed_paths``.
+
+    Re-implementing only the scoped tasks does NOT stop the SUT from writing
+    OUT-of-scope files (the design's #1 implementation note). The fence snapshots
+    the tracked source/test tree on entry; on :meth:`enforce` it reverts every
+    out-of-scope change made during the rerun — an out-of-scope CREATE is deleted,
+    an out-of-scope MODIFY is restored to its pre-rerun bytes. In-scope writes
+    (under an allowed file/dir, or a manifest/config) pass untouched. This makes
+    a "targeted" rerun genuinely local: it cannot silently regenerate the tree.
+
+    ``allowed_paths`` entries are matched as exact files OR directory prefixes
+    (a task that owns ``src/`` may write any file under ``src/``). An EMPTY
+    allow-set means "no fence" (the broad rerun's signal) and the caller does not
+    construct a fence in that case.
+    """
+
+    def __init__(self, project_root: Path, *, allowed_paths: tuple[str, ...], echo: Callable[[str], str]):
+        self._root = Path(project_root).resolve()
+        self._allowed_files, self._allowed_dirs = self._split_allowed(allowed_paths)
+        self._echo = echo
+        self._snapshot: dict[str, bytes] = {}
+
+    def __enter__(self) -> "_OracleWriteFence":
+        self._snapshot = self._capture()
+        return self
+
+    def __exit__(self, *_exc: Any) -> None:
+        # The fence does not suppress exceptions; enforce() is called explicitly
+        # by the caller on the SUCCESS path so a failing rerun's exception still
+        # propagates with the tree left for the caller's error handling.
+        return None
+
+    def enforce(self) -> None:
+        """Revert every out-of-scope create/modify made since entry."""
+        current = self._capture()
+        reverted_modified: list[str] = []
+        reverted_created: list[str] = []
+
+        # Reverts for modified/created files.
+        for rel, content in current.items():
+            if self._is_allowed(rel):
+                continue
+            if rel in self._snapshot:
+                if self._snapshot[rel] != content:
+                    self._restore(rel, self._snapshot[rel])
+                    reverted_modified.append(rel)
+            else:
+                self._remove(rel)
+                reverted_created.append(rel)
+
+        # Re-create any tracked file the scoped rerun DELETED out of scope (a
+        # deletion is also an out-of-scope mutation we must undo).
+        reverted_deleted: list[str] = []
+        for rel, content in self._snapshot.items():
+            if rel in current or self._is_allowed(rel):
+                continue
+            self._restore(rel, content)
+            reverted_deleted.append(rel)
+
+        total = len(reverted_modified) + len(reverted_created) + len(reverted_deleted)
+        if total:
+            self._echo(
+                "[greenfield] implement-oracle: write-fence reverted "
+                f"{total} out-of-scope change(s) "
+                f"(modified={len(reverted_modified)}, created={len(reverted_created)}, "
+                f"deleted={len(reverted_deleted)}); the scoped rerun is kept local."
+            )
+
+    # ── internals ──
+    @staticmethod
+    def _split_allowed(allowed_paths: tuple[str, ...]) -> tuple[set[str], list[str]]:
+        files: set[str] = set()
+        dirs: list[str] = []
+        for raw in allowed_paths:
+            norm = str(raw).strip().replace("\\", "/").strip("/")
+            if not norm:
+                continue
+            if PurePosixPath(norm).suffix:
+                files.add(norm)
+            else:
+                dirs.append(norm)
+        return files, dirs
+
+    def _is_allowed(self, rel: str) -> bool:
+        if rel in self._allowed_files:
+            return True
+        for directory in self._allowed_dirs:
+            if rel == directory or rel.startswith(directory + "/"):
+                return True
+        return False
+
+    def _capture(self) -> dict[str, bytes]:
+        out: dict[str, bytes] = {}
+        for path in self._iter_tracked_files():
+            try:
+                out[path.relative_to(self._root).as_posix()] = path.read_bytes()
+            except OSError:
+                continue
+        return out
+
+    def _iter_tracked_files(self):
+        import os
+
+        for dirpath, dirnames, filenames in os.walk(self._root):
+            dirnames[:] = [d for d in dirnames if d not in _FENCE_EXCLUDE_DIRS]
+            for name in filenames:
+                if PurePosixPath(name).suffix in _FENCE_TRACKED_SUFFIXES:
+                    yield Path(dirpath) / name
+
+    def _restore(self, rel: str, content: bytes) -> None:
+        target = self._root / rel
+        try:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_bytes(content)
+        except OSError as exc:
+            self._echo(f"[greenfield] implement-oracle: write-fence could not restore {rel} ({exc}).")
+
+    def _remove(self, rel: str) -> None:
+        target = self._root / rel
+        try:
+            target.unlink()
+        except OSError as exc:
+            self._echo(f"[greenfield] implement-oracle: write-fence could not remove {rel} ({exc}).")
+
+
 def _default_task_lister(project_root: Path) -> list[ImplementTaskRef]:
     from codd.implementer import list_implement_tasks
 

{codd_dev-2.25.0 → codd_dev-2.26.0}/codd/implement_oracle.py

@@ -92,6 +92,7 @@ __all__ = [
     "EVIDENCE_CATEGORIES",
     "ImplementOracleFinding",
     "ImplementOracleResult",
+    "OracleRerunCallback",
     "OracleScopeError",
     "certify_oracle_scope",
     "normalize_oracle_output",
@@ -197,6 +198,12 @@ class ImplementOracleResult:
     failed_paths: list[str] = field(default_factory=list)
     detail: str = ""
     raw_output: str = ""
+    #: Structured diagnostics (code + primary file + symbol/module) for the SCOPED
+    #: rerun derivation + the loop-breaking signature. Empty for a pass / for a
+    #: non-TS oracle. Kept separate from ``findings`` (the SUT-facing normalized
+    #: evidence) because scope derivation needs the per-diagnostic counterpart
+    #: keys, not the language-neutral category. See ``codd.implement_oracle_scope``.
+    diagnostics: list[Any] = field(default_factory=list)
 
     def category_counts(self) -> dict[str, int]:
         counts: dict[str, int] = {}
@@ -724,6 +731,16 @@ def _run_oracle_command(
                 message=(_output_tail(completed.stdout, completed.stderr) or "non-zero exit, no diagnostics"),
             )
         ]
+    # Structured diagnostics for the scoped rerun + the loop-breaking signature.
+    # Best-effort: a parser failure must never abort the gate (the scope layer
+    # degrades to broad on empty diagnostics).
+    diagnostics: list[Any] = []
+    try:
+        from codd.implement_oracle_scope import _parse_ts_diagnostics
+
+        diagnostics = _parse_ts_diagnostics(full_output, project_root)
+    except Exception:  # noqa: BLE001 — structured-diag parsing is enrichment only.
+        diagnostics = []
     return ImplementOracleResult(
         passed=False,
         executed=True,
@@ -732,6 +749,7 @@ def _run_oracle_command(
         failed_paths=failed_paths,
         detail=f"native oracle failed (exit {completed.returncode}); {len(findings)} diagnostic(s)",
         raw_output=full_output,
+        diagnostics=diagnostics,
     )
 
 
@@ -778,6 +796,16 @@ def resolve_implement_oracle(
     return profile, profile.implement_oracle
 
 
+#: The rerun callback the gate invokes to re-implement under the oracle feedback.
+#: ``scope is None`` ⇒ BROAD rerun (re-implement every task — the escalation
+#: fallback, the legacy behaviour). A non-None ``OracleRerunScope`` ⇒ a SCOPED
+#: rerun (re-implement only the scope's tasks, under its write-fence). The second
+#: positional is kept optional in spirit — a callback that ignores it falls back
+#: to broad, preserving back-compat for any plain ``Callable[[str], None]`` only
+#: if it accepts the extra arg; the pipeline's callback consumes the scope.
+OracleRerunCallback = Callable[[str, "Any"], None]
+
+
 def run_implement_oracle_gate(
     project_root: Path | str,
     *,
@@ -786,9 +814,12 @@ def run_implement_oracle_gate(
     source_dirs: Any = None,
     test_dirs: Any = None,
     config: Mapping[str, Any] | None = None,
-    rerun: Callable[[str], None] | None = None,
+    rerun: OracleRerunCallback | Callable[[str], None] | None = None,
     echo: Callable[[str], None] = print,
     profile: LayoutProfile | None = None,
+    scope_index: Any = None,
+    structured_source: Any = None,
+    manifest_paths: Any = None,
 ) -> ImplementOracleResult:
     """Run the implement-time native-oracle gate (stage-level, once).
 
@@ -799,10 +830,26 @@ def run_implement_oracle_gate(
          install failure is an honest ``environment_build_error`` (no retry).
       3. CERTIFY the oracle scope covers source + tests (raises
          :class:`OracleScopeError` on an uncertifiable scope — anti-false-green).
-      4. Run the oracle. On failure, normalize the diagnostics and, if a
-         ``rerun(feedback)`` callback is provided, re-invoke implementation with
-         the normalized feedback up to a bounded cap, re-running the oracle each
-         time. Returns the FINAL result (``passed`` True iff the oracle is clean).
+      4. Run the oracle. On failure, derive a SCOPED rerun and re-invoke
+         implementation through ``rerun(feedback, scope)`` up to a bounded cap,
+         re-running the oracle each time. Returns the FINAL result.
+
+    SCOPED RERUN + ESCALATION LADDER (the localized-rerun design)
+    -------------------------------------------------------------
+    A broad rerun (regenerate every task) is correct but slow. When a
+    ``scope_index`` (a ``codd.implement_oracle_scope.TaskOutputIndex``, the
+    path→owning-task map) is supplied, the gate derives the BOTH-ENDS-OF-THE-
+    BROKEN-EDGE scope from the diagnostics and re-implements only those tasks.
+    Broad is DEMOTED to a fallback rung. The ladder — driven by the diagnostic
+    SIGNATURE (the loop-breaker) — is:
+
+        narrow edge scope → expanded one-hop scope → broad → fail honestly
+
+    Escalation triggers: the diagnostics have no determinable owner (→ broad);
+    the SAME signature survives a scoped rerun (the scope was too small →
+    next rung); or a breadth/fan-out guard fires inside the derivation (→ broad).
+    Without a ``scope_index`` the gate behaves exactly as before — a broad rerun
+    every attempt — so the change is opt-in via the index.
 
     The caller (greenfield ``_stage_implement``) turns a non-passing result into
     a :class:`StageError`. ``OracleScopeError`` propagates (it is a hard
@@ -839,21 +886,62 @@ def run_implement_oracle_gate(
     certification = certify_oracle_scope(root, profile, spec)
     echo(f"[greenfield] implement-oracle: {certification}")
 
-    # 4. Run + bounded retry-with-feedback.
+    # 4. Run + bounded retry-with-feedback, escalating the rerun scope.
     max_attempts = _oracle_max_attempts(config)
     result = _run_oracle_command(root, profile, spec, config)
     attempt = 1
+    rung = _SCOPE_NARROW if scope_index is not None else _SCOPE_BROAD
+    last_signature: tuple[Any, ...] | None = None
     while not result.passed and result.executed and rerun is not None and attempt < max_attempts:
         # Only retry CURABLE incoherence — an environment/toolchain failure is not
         # something the SUT can fix in source, so do not burn retries on it.
         if _only_environment(result):
             break
+
+        # Loop-breaker: if the SAME diagnostic signature survived the previous
+        # scoped rerun, the scope was too small — escalate the ladder a rung
+        # (narrow → expanded → broad). Past broad with no progress → stop and
+        # fail honestly (the next loop guard / the final return handle it).
+        signature = _diagnostic_signature(result)
+        if last_signature is not None and signature == last_signature and scope_index is not None:
+            escalated = _next_rung(rung)
+            if escalated is None:
+                echo(
+                    "[greenfield] implement-oracle: signature unchanged after broad rerun — "
+                    "stopping (honest failure)."
+                )
+                break
+            echo(
+                f"[greenfield] implement-oracle: signature unchanged after {rung} rerun — "
+                f"escalating scope to {escalated}."
+            )
+            rung = escalated
+        last_signature = signature
+
+        # Derive the scope for this rung (broad when no index, or when the
+        # derivation's guards force it). A broad scope is passed as ``None`` so a
+        # callback that distinguishes scoped-vs-broad sees the legacy signal.
+        scope, forced_broad = _derive_scope_for_rung(
+            result=result,
+            project_root=root,
+            scope_index=scope_index,
+            rung=rung,
+            structured_source=structured_source,
+            manifest_paths=manifest_paths,
+            echo=echo,
+        )
+        if forced_broad and scope_index is not None:
+            rung = _SCOPE_BROAD  # a forced-broad derivation pins the rung (monotonic ladder)
+        scope_label = (
+            "broad" if scope is None or getattr(scope, "is_broad", lambda: False)() else getattr(scope, "rung", rung)
+        )
         echo(
             f"[greenfield] implement-oracle: {result.detail}; "
             f"re-running implementation with normalized feedback "
-            f"(attempt {attempt}/{max_attempts - 1}) — categories {result.category_counts()}"
+            f"(attempt {attempt}/{max_attempts - 1}, scope={scope_label}) — "
+            f"categories {result.category_counts()}"
         )
-        rerun(result.feedback_message())
+        _invoke_rerun(rerun, result.feedback_message(), scope)
         attempt += 1
         result = _run_oracle_command(root, profile, spec, config)
 
@@ -867,6 +955,109 @@ def run_implement_oracle_gate(
     return result
 
 
+# Ladder-rung constants mirrored here so the gate does not hard-import the scope
+# module at call time when no index is supplied (keeps the no-op path light).
+_SCOPE_NARROW = "narrow"
+_SCOPE_BROAD = "broad"
+
+
+def _next_rung(rung: str) -> str | None:
+    from codd.implement_oracle_scope import next_rung
+
+    return next_rung(rung)
+
+
+def _diagnostic_signature(result: ImplementOracleResult) -> tuple[Any, ...]:
+    """The result's diagnostic signature (the loop-breaker key); () if none."""
+    if not result.diagnostics:
+        return ()
+    try:
+        from codd.implement_oracle_scope import diagnostic_signature
+
+        return diagnostic_signature(result.diagnostics)
+    except Exception:  # noqa: BLE001 — signature is a guard; a parse miss ⇒ no guard.
+        return ()
+
+
+def _derive_scope_for_rung(
+    *,
+    result: ImplementOracleResult,
+    project_root: Path,
+    scope_index: Any,
+    rung: str,
+    structured_source: Any,
+    manifest_paths: Any,
+    echo: Callable[[str], None],
+) -> tuple[Any, bool]:
+    """Derive the rerun scope for ``rung`` → ``(scope, forced_broad)``.
+
+    ``scope is None`` ⇒ broad (the legacy signal the callback re-runs everything
+    on). ``forced_broad`` is True when the derivation itself demanded broad (no
+    determinable owner / too-wide / wide-fan-out artifact, or a derivation error)
+    so the caller can PIN the ladder rung at broad — the ladder is monotonic, it
+    never drops back to a narrower rung once broad was required. With no
+    ``scope_index`` (the back-compat path) returns ``(None, False)`` so behaviour
+    is exactly the legacy broad rerun without disturbing the rung bookkeeping.
+    """
+    if scope_index is None:
+        return None, False
+    try:
+        from codd.implement_oracle_scope import derive_oracle_rerun_scope
+
+        decision = derive_oracle_rerun_scope(
+            output=result.raw_output,
+            project_root=project_root,
+            index=scope_index,
+            rung=rung,
+            structured_source=structured_source,
+            manifest_paths=tuple(manifest_paths or ()),
+        )
+    except Exception as exc:  # noqa: BLE001 — a derivation failure degrades to broad.
+        echo(f"[greenfield] implement-oracle: scope derivation failed ({exc}); falling back to broad.")
+        return None, True
+    if decision.scope is None or decision.force_broad:
+        if decision.reason:
+            echo(f"[greenfield] implement-oracle: {decision.reason}")
+        return None, True
+    echo(f"[greenfield] implement-oracle: {decision.scope.detail}")
+    return decision.scope, decision.scope.rung == _SCOPE_BROAD
+
+
+def _invoke_rerun(rerun: Callable[..., None], feedback: str, scope: Any) -> None:
+    """Call the rerun callback, supporting both the scoped ``(feedback, scope)``
+    and the legacy single-arg ``(feedback)`` signatures.
+
+    Arity is decided by INSPECTION (not by catching ``TypeError``): a ``TypeError``
+    raised *inside* a 2-arg callback must propagate, not be silently retried as a
+    1-arg call. A callback that takes only one positional parameter (and no
+    ``*args``) is invoked with feedback alone (it cannot localize → broad).
+    """
+    if _accepts_scope_arg(rerun):
+        rerun(feedback, scope)
+    else:
+        rerun(feedback)
+
+
+def _accepts_scope_arg(rerun: Callable[..., None]) -> bool:
+    """True if ``rerun`` accepts a second positional (the scope) — else legacy."""
+    import inspect
+
+    try:
+        sig = inspect.signature(rerun)
+    except (TypeError, ValueError):
+        return True  # un-introspectable (builtin/C) — assume the new signature.
+    positional = 0
+    for param in sig.parameters.values():
+        if param.kind in (
+            inspect.Parameter.POSITIONAL_ONLY,
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+        ):
+            positional += 1
+        elif param.kind is inspect.Parameter.VAR_POSITIONAL:
+            return True  # *args swallows the scope.
+    return positional >= 2
+
+
 def _only_environment(result: ImplementOracleResult) -> bool:
     """True when every finding is an environment/toolchain failure (not curable by SUT)."""
     if not result.findings: