skillflow-py 1.2.0__tar.gz → 1.3.0__tar.gz

{skillflow_py-1.2.0/src/skillflow_py.egg-info → skillflow_py-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: skillflow-py
-Version: 1.2.0
+Version: 1.3.0
 Summary: Config-agnostic LLM pipeline graph executor — turn skills into flows
 Author: Skillflow contributors
 License-Expression: MIT
@@ -207,10 +207,15 @@ This powers both **inner review loops** (e.g. `review → implement`, `max_loop:
 context:
   - source: { step: "1" }
   - source: { step: "2", mode: "interfaces" }
-  - source: { config: "meta", output: "brief.md" }
+  - source: { config: "meta", output: "brief.md" }                  # any step of another config
+  - source: { config: "meta", step: "finalize", output: "x.json" }  # a SPECIFIC step's output
   - source: { tool: "dir_tree" }
 ```
 
+A cross-config source without `step` scans the other config's step dirs for the
+file; adding `step` reads that one step's output (use it when only a specific
+producing step is authoritative).
+
 ## Checkpoints
 
 Agent steps can pause for human approval (`tests/fixtures/checkpoint_cycle.yaml`). On reject, the feedback is injected (via the `_feedback` channel) so the re-run knows *why* it was rejected:
@@ -268,6 +273,8 @@ end_conditions:
     - type: node_reached
       node: "5_review"
       result: "completed"
+      require_completed: true   # fire only once the node has COMPLETED, not merely
+                                # been reached (i.e. become current_node)
     - type: max_total_steps
       limit: 200
     - type: max_run_duration_seconds
@@ -276,6 +283,17 @@ end_conditions:
       flag: { fatal_error: true }
 ```
 
+`require_completed` (node_reached only) gates termination on the node's step
+reaching `completed` status. Use it when the terminal node is a real agent/tool
+step that must execute before the run ends — without it the condition fires as
+soon as the node becomes `current_node`.
+
+**Terminating a run needs an end condition.** A transition `to: null` does NOT by
+itself end a run: with no resolvable target the run is marked **failed** ("no
+matching transition"). To finish cleanly, give the terminal step `to: null` **and**
+a `node_reached` end condition for that node (the pattern above). This applies to
+`tool` and `gate` steps too, not just `agent` steps.
+
 ## Stale Claim Recovery
 
 Built into `advance_run`. A claim whose worker died before calling `confirm`, and that is older than `stale_threshold_seconds` (default 300), is auto-reset to `pending` and re-claimed:

{skillflow_py-1.2.0 → skillflow_py-1.3.0}/README.md

@@ -183,10 +183,15 @@ This powers both **inner review loops** (e.g. `review → implement`, `max_loop:
 context:
   - source: { step: "1" }
   - source: { step: "2", mode: "interfaces" }
-  - source: { config: "meta", output: "brief.md" }
+  - source: { config: "meta", output: "brief.md" }                  # any step of another config
+  - source: { config: "meta", step: "finalize", output: "x.json" }  # a SPECIFIC step's output
   - source: { tool: "dir_tree" }
 ```
 
+A cross-config source without `step` scans the other config's step dirs for the
+file; adding `step` reads that one step's output (use it when only a specific
+producing step is authoritative).
+
 ## Checkpoints
 
 Agent steps can pause for human approval (`tests/fixtures/checkpoint_cycle.yaml`). On reject, the feedback is injected (via the `_feedback` channel) so the re-run knows *why* it was rejected:
@@ -244,6 +249,8 @@ end_conditions:
     - type: node_reached
       node: "5_review"
       result: "completed"
+      require_completed: true   # fire only once the node has COMPLETED, not merely
+                                # been reached (i.e. become current_node)
     - type: max_total_steps
       limit: 200
     - type: max_run_duration_seconds
@@ -252,6 +259,17 @@ end_conditions:
       flag: { fatal_error: true }
 ```
 
+`require_completed` (node_reached only) gates termination on the node's step
+reaching `completed` status. Use it when the terminal node is a real agent/tool
+step that must execute before the run ends — without it the condition fires as
+soon as the node becomes `current_node`.
+
+**Terminating a run needs an end condition.** A transition `to: null` does NOT by
+itself end a run: with no resolvable target the run is marked **failed** ("no
+matching transition"). To finish cleanly, give the terminal step `to: null` **and**
+a `node_reached` end condition for that node (the pattern above). This applies to
+`tool` and `gate` steps too, not just `agent` steps.
+
 ## Stale Claim Recovery
 
 Built into `advance_run`. A claim whose worker died before calling `confirm`, and that is older than `stale_threshold_seconds` (default 300), is auto-reset to `pending` and re-claimed:

{skillflow_py-1.2.0 → skillflow_py-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "skillflow-py"
-version = "1.2.0"
+version = "1.3.0"
 description = "Config-agnostic LLM pipeline graph executor — turn skills into flows"
 readme = "README.md"
 license = "MIT"

{skillflow_py-1.2.0 → skillflow_py-1.3.0}/src/skillflow/core.py

@@ -861,10 +861,15 @@ class SkillFlow:
                     if k.startswith("[") and k not in inputs_with_tools["_resolved_context"]:
                         inputs_with_tools["_resolved_context"][k] = v
 
-            # Merge dynamic write tool schemas from graph's output.fixed
-            if node.output_mode and node.output_fixed:
+            # Merge dynamic write tool schemas derived from the step's output
+            # contract (mode). Write-mode without fixed slots → create/edit
+            # (+ write only when allow_full_write); content-mode → write_/create_/
+            # edit_ per slot. Single source of truth for mutation tools.
+            if node.output_mode:
                 from skillflow.write_tools import generate_write_tool_schemas
-                for ws in generate_write_tool_schemas(node.output_mode, node.output_fixed):
+                for ws in generate_write_tool_schemas(
+                        node.output_mode, node.output_fixed,
+                        allow_full_write=node.output_allow_full_write):
                     tool_schemas[ws["name"]] = ws
 
             # Merge dynamic read tool schemas from graph's context specs
@@ -927,6 +932,14 @@ class SkillFlow:
                 tmp_dir = self._workspace.get_step_tmp_dir(
                     run["project_id"], run["graph_name"], node.id
                 )
+                # Reset staging at the start of each attempt so create/edit/write
+                # rebuild from a clean baseline (the repo). Without this, a partial
+                # result from a failed attempt pollutes the next one — e.g. a
+                # re-issued edit(old→new) would fail because 'old' was already
+                # replaced last attempt. Keeps step execution idempotent on retry.
+                import shutil
+                if tmp_dir.exists():
+                    shutil.rmtree(str(tmp_dir))
                 tmp_dir.mkdir(parents=True, exist_ok=True)
                 inputs_with_tools["_output_dir"] = str(tmp_dir)
                 if node.output_fixed:
@@ -1817,16 +1830,20 @@ class SkillFlow:
             items = flat
         return items, False
 
-    def _reset_loop_body_edge_counts(self, conn, run_id, resolver,
-                                     loop_step_id, body_target):
-        """Clear edge counts for the loop body so each iteration gets a fresh
-        retry budget.
-
-        Inner review/verify loops (e.g. t_impl_review→t_impl, max_loop=3) are
-        counted per (run, from, to) — i.e. shared across every iteration. That
-        starves later tasks of retries. Resetting the body's edge counts when a
-        new item is dispatched scopes the budget to the current iteration.
+    def _loop_body_nodes(self, resolver, loop_step_id) -> set[str]:
+        """The set of node ids that form a loop's body: reachable from the
+        loop's body transition, following transitions, excluding the loop node
+        itself. Purely topological — derived from the graph, no config-specific
+        names — so it stays config-agnostic.
         """
+        node = resolver.get_node(loop_step_id)
+        if not node:
+            return set()
+        body_target = None
+        for t in node.transitions:
+            if t.to:
+                body_target = t.to
+                break
         body_nodes: set[str] = set()
         stack = [body_target]
         while stack:
@@ -1834,12 +1851,25 @@ class SkillFlow:
             if not nid or nid in body_nodes or nid == loop_step_id:
                 continue
             body_nodes.add(nid)
-            node = resolver.get_node(nid)
-            if not node:
+            n = resolver.get_node(nid)
+            if not n:
                 continue
-            for t in node.transitions:
+            for t in n.transitions:
                 if t.to and t.to != loop_step_id:
                     stack.append(t.to)
+        return body_nodes
+
+    def _reset_loop_body_edge_counts(self, conn, run_id, resolver,
+                                     loop_step_id, body_target):
+        """Clear edge counts for the loop body so each iteration gets a fresh
+        retry budget.
+
+        Inner review/verify loops (e.g. t_impl_review→t_impl, max_loop=3) are
+        counted per (run, from, to) — i.e. shared across every iteration. That
+        starves later tasks of retries. Resetting the body's edge counts when a
+        new item is dispatched scopes the budget to the current iteration.
+        """
+        body_nodes = self._loop_body_nodes(resolver, loop_step_id)
         if not body_nodes:
             return
         placeholders = ",".join("?" for _ in body_nodes)
@@ -1849,6 +1879,38 @@ class SkillFlow:
             (run_id, *sorted(body_nodes)),
         )
 
+    def _credit_loop_current_item(self, conn, run_id: str, loop_step_id: str) -> None:
+        """Progression (write): mark the loop's current_item completed.
+
+        Called from confirm_step when a body cycle's terminal step routes back to
+        the loop node — exactly once per completed body cycle, atomic with the
+        terminal step's completion. _resolve_loop performs NO crediting (it only
+        reads completed_items to pick the next item), so resolution is idempotent
+        and the separate advance/claim transactions can't cause a spurious
+        advance or skipped item.
+        """
+        row = conn.execute(
+            "SELECT completed_items, current_item FROM skillflow_loop_state "
+            "WHERE run_id = ? AND loop_step_id = ?",
+            (run_id, loop_step_id),
+        ).fetchone()
+        if not row or not row["current_item"]:
+            return
+        completed: set[str] = set()
+        if row["completed_items"]:
+            try:
+                completed = set(self._deserialize(row["completed_items"]))
+            except Exception:
+                pass
+        if row["current_item"] in completed:
+            return  # idempotent — already credited
+        completed.add(row["current_item"])
+        conn.execute(
+            "UPDATE skillflow_loop_state SET completed_items = ?, "
+            "updated_at = datetime('now') WHERE run_id = ? AND loop_step_id = ?",
+            (self._serialize(sorted(completed)), run_id, loop_step_id),
+        )
+
     def _resolve_loop(self, conn, run: dict, resolver, loop_step_id: str) -> str | None:
         """Resolve a loop step to either its body or done transition.
 
@@ -1907,42 +1969,25 @@ class SkillFlow:
                     return t.to
             return None
 
-        # ── Completed set ────────────────────────────────────────────────
+        # ── Completed set — scoped to the LIVE manifest ───────────────────
+        # Resolution is READ-ONLY w.r.t. progression: it never credits
+        # completion (confirm_step does that via _credit_loop_current_item when a
+        # body cycle returns to the loop). So re-entry — e.g. an extra scheduler
+        # tick in the dispatch→claim gap — re-picks the SAME item with
+        # current_item unchanged, never spuriously advancing or skipping work.
         completed: set[str] = set()
-        prev_item: str | None = None
+        current_item: str | None = None
         if row:
             if row["completed_items"]:
                 try:
                     completed = set(self._deserialize(row["completed_items"]))
                 except Exception:
                     pass
-            prev_item = row["current_item"] or None
-        # Backward compat: old rows with current_index (no completed_items).
-        # current_index points to the LAST DISPATCHED item.
-        # Items BEFORE current_index are completed; items[current_index] is
-        # the currently-executing item.  Only reconstruct prev_item when at
-        # least one item has finished (so we have a "previously dispatched"
-        # item to mark completed).
-        if not completed and row and row["current_item"] is None:
-            try:
-                old_items = self._deserialize(row["items_json"]) if row["items_json"] else []
-                old_idx = row["current_index"]
-                if isinstance(old_idx, int) and old_idx > 0:
-                    completed = set(old_items[:old_idx])
-                    if old_idx < len(old_items):
-                        prev_item = old_items[old_idx]
-                elif isinstance(old_idx, int) and old_idx == 0:
-                    pass  # first dispatch — nothing completed, nothing to mark
-            except Exception:
-                pass
-
-        # Mark the previously-dispatched item as completed.
-        # prev_item is None on the very first dispatch (row is None),
-        # so nothing is marked. On every subsequent entry, prev_item
-        # was set by the previous dispatch and has now finished.
-        if prev_item and prev_item not in completed:
-            completed.add(prev_item)
-            prev_item = None
+            current_item = row["current_item"] or None
+        # Drop superseded names from prior goal-loop rounds so completed_items
+        # reflects only the active manifest (prevents the len(completed) overcount
+        # and the scheduler's idx-out-of-range).
+        completed &= set(items)
 
         if row is None:
             if not items:
@@ -1955,13 +2000,6 @@ class SkillFlow:
                 (run["id"], loop_step_id, self._serialize(items),
                  loop_cfg.item_as or "loop_item"),
             )
-        else:
-            # Always persist the live manifest so context resolution sees it
-            conn.execute(
-                "UPDATE skillflow_loop_state SET items_json = ?, "
-                "updated_at = datetime('now') WHERE run_id = ? AND loop_step_id = ?",
-                (self._serialize(items), run["id"], loop_step_id),
-            )
 
         # ── Find first uncompleted item (manifest order) ────────────────
         if not items:
@@ -1974,17 +2012,23 @@ class SkillFlow:
         if next_item is None:
             return _route_done()
 
-        # ── Dispatch ─────────────────────────────────────────────────────
+        # ── Dispatch (idempotent) ─────────────────────────────────────────
+        # Persist the live manifest + scoped completed set + the item to run.
+        new_dispatch = (next_item != current_item)
         conn.execute(
-            "UPDATE skillflow_loop_state SET completed_items = ?, "
+            "UPDATE skillflow_loop_state SET items_json = ?, completed_items = ?, "
             "current_item = ?, updated_at = datetime('now') "
             "WHERE run_id = ? AND loop_step_id = ?",
-            (self._serialize(sorted(completed)), next_item,
-             run["id"], loop_step_id),
-        )
-        self._reset_loop_body_edge_counts(
-            conn, run["id"], resolver, loop_step_id, body_target
+            (self._serialize(items), self._serialize(sorted(completed)),
+             next_item, run["id"], loop_step_id),
         )
+        # Reset the body's per-iteration retry budget ONLY for a genuinely new
+        # item — never on an idempotent re-entry for the same in-flight item,
+        # which would wipe the body's mid-cycle edge counts.
+        if new_dispatch:
+            self._reset_loop_body_edge_counts(
+                conn, run["id"], resolver, loop_step_id, body_target
+            )
         return body_target
 
     def _resolve_next_in_tx(self, conn, run_id: str, step_id: str,
@@ -2043,7 +2087,19 @@ class SkillFlow:
                 tool_node = resolver.get_node(t.to)
                 if tool_node and not self._should_delegate_tool(tool_node.tool_name):
                     skip_tool = True
-            if resolver.is_gate(t.to) or resolver.is_loop(t.to) or skip_tool:
+            if resolver.is_loop(t.to):
+                # PROGRESSION: credit the loop's current_item — but ONLY when
+                # THIS completing step is inside the loop body (a body cycle
+                # returning). An EXTERNAL step transitioning INTO the loop
+                # (entry / goal-loop re-entry) must NOT credit: that would mark
+                # the in-flight item complete and skip it. Topological check
+                # (no config-specific names). Fires once per body cycle; a stray
+                # re-tick at the loop node goes through advance_run only (no
+                # credit), so resolution stays idempotent.
+                if step_id in self._loop_body_nodes(resolver, t.to):
+                    self._credit_loop_current_item(conn, run_id, t.to)
+                return None
+            if resolver.is_gate(t.to) or skip_tool:
                 return None
 
             # Check max_loop on this edge
@@ -3057,9 +3113,11 @@ class SkillFlow:
                 ac = self.agent_registry.get(node.agent_config)
                 if ac:
                     allowed.update(ac.tools)
-            if node.output_mode and node.output_fixed:
+            if node.output_mode:
                 from skillflow.write_tools import generate_write_tool_schemas
-                for ws in generate_write_tool_schemas(node.output_mode, node.output_fixed):
+                for ws in generate_write_tool_schemas(
+                        node.output_mode, node.output_fixed,
+                        allow_full_write=node.output_allow_full_write):
                     allowed.add(ws["name"])
             # Add read tool names from context specs (mode ∈ {tool, both})
             if node.context:
@@ -3092,13 +3150,25 @@ class SkillFlow:
             else:
                 return execute_write(slot, fixed, params, str(tmp_dir))
 
-        if name == "write":
+        # Generic write-mode tools (mode: write, no fixed slots): create new
+        # files / edit existing ones surgically. edit reads its baseline from
+        # the consolidated repo (project_root) but writes the whole result into
+        # staging — the repo is only ever mutated by on_deliver:repo_apply.
+        if name in ("create", "edit", "write"):
             if not self._workspace:
                 return {"error": "No workspace configured for write tool"}
             pid = self._get_project_id(run_id)
             gname = self._get_graph_name(run_id)
             tmp_dir = self._workspace.get_step_tmp_dir(pid, gname, step_id)
-            from skillflow.write_tools import execute_generic_write
+            from skillflow.write_tools import (execute_generic_create,
+                                               execute_generic_edit,
+                                               execute_generic_write)
+            if name == "create":
+                return execute_generic_create(params, str(tmp_dir),
+                                              source_dir=project_root or "")
+            if name == "edit":
+                return execute_generic_edit(params, str(tmp_dir),
+                                            source_dir=project_root or "")
             return execute_generic_write(params, str(tmp_dir))
 
         # finish_step — no-op completion signal; the host runner detects it and
@@ -3111,6 +3181,11 @@ class SkillFlow:
         kwargs = dict(params)
         kwargs.setdefault("workspace_root", project_root or "")
         kwargs.setdefault("project_root", project_root or "")
+        # Forward step/run identity so tools that want per-step state (e.g.
+        # scratch-file tools) can isolate by step. Signature-filtered below, so
+        # tools that don't declare these params are unaffected.
+        kwargs.setdefault("step_id", step_id or "")
+        kwargs.setdefault("run_id", run_id or "")
         # SF-10: pass step staging/output dirs so read_file (and similar tools)
         # can find files the agent just wrote (in .tmp) or files from previous
         # retries (in the step's final dir). write_* tools write to .tmp; without

{skillflow_py-1.2.0 → skillflow_py-1.3.0}/src/skillflow/graph.py

@@ -117,6 +117,7 @@ class StepNode:
     context: list[dict] = field(default_factory=list)
     output_mode: str = ""
     output_fixed: dict = field(default_factory=dict)
+    output_allow_full_write: bool = False
     validation: list[dict] = field(default_factory=list)
     notify: list[str] | None = None  # event types to push (None = outbox only)
     lifecycle: dict[str, Any] = field(default_factory=dict)
@@ -264,6 +265,7 @@ class PipelineGraph:
                     context=s.get("context", []),
                     output_mode=(s.get("output") or {}).get("mode", "") or s.get("output_mode", ""),
                     output_fixed=(s.get("output") or {}).get("fixed", {}),
+                    output_allow_full_write=bool((s.get("output") or {}).get("allow_full_write", False)),
                     validation=s.get("validation", []),
                     notify=s.get("notify"),
                     lifecycle=s.get("lifecycle", {}),
@@ -337,8 +339,12 @@ class PipelineGraph:
                 sd["context"] = s.context
             if s.output_mode:
                 sd["output_mode"] = s.output_mode
-                if s.output_fixed:
-                    sd["output"] = {"fixed": s.output_fixed}
+                if s.output_fixed or s.output_allow_full_write:
+                    sd["output"] = {}
+                    if s.output_fixed:
+                        sd["output"]["fixed"] = s.output_fixed
+                    if s.output_allow_full_write:
+                        sd["output"]["allow_full_write"] = True
             if s.validation:
                 sd["validation"] = s.validation
             if s.lifecycle:

{skillflow_py-1.2.0 → skillflow_py-1.3.0}/src/skillflow/write_tools.py

@@ -87,31 +87,74 @@ def _archive_old_file(directory: Path, base_name: str) -> str | None:
 
 
 def generate_write_tool_schemas(output_mode: str,
-                                fixed: dict) -> list[dict]:
-    """Generate tool schema dicts for write/create/append tools.
+                                fixed: dict,
+                                allow_full_write: bool = False) -> list[dict]:
+    """Generate tool schema dicts for write/create/edit/append tools.
 
     Returns a list of dicts with 'name', 'description', 'parameters'.
+
+    For generic write-mode (``mode: write`` with no fixed slots) the default
+    tools are ``create`` (new files) + ``edit`` (surgical in-place change) —
+    NOT whole-file ``write``. Rewriting a whole existing file from the model's
+    (necessarily partial) view silently drops any region it didn't reproduce;
+    ``edit`` carries the rest of the file through verbatim, so that failure mode
+    is impossible. Whole-file ``write`` is exposed only when ``allow_full_write``
+    is set on the step (rare: genuine from-scratch authorship).
     """
     if output_mode == "write" and not fixed:
-        return [{
-            "name": "write",
-            "description": "Write a file. The 'file' param must be a bare filename.",
+        tools = [{
+            "name": "create",
+            "description": (
+                "Create a NEW file with the given content. The 'file' param is a "
+                "repo-relative path (e.g. 'core/db_manager.py'). Fails if the file "
+                "already exists — use 'edit' to change an existing file."
+            ),
             "parameters": {
                 "file": {"type": "string", "required": True},
                 "content": {"type": "string", "required": True},
             },
         }, {
+            "name": "edit",
+            "description": (
+                "Surgically change an EXISTING file by replacing an exact, unique "
+                "snippet — use this to fix or update part of a file without "
+                "rewriting the whole thing (the rest is preserved verbatim). "
+                "'old_str' must appear exactly once; include surrounding context "
+                "to make it unique. Fails if the file is absent or 'old_str' isn't "
+                "found exactly once. For multiple changes, call edit repeatedly."
+            ),
+            "parameters": {
+                "file": {"type": "string", "required": True},
+                "old_str": {"type": "string", "required": True,
+                            "description": "Exact text to find (must appear exactly once)."},
+                "new_str": {"type": "string", "required": True,
+                            "description": "Replacement text."},
+            },
+        }]
+        if allow_full_write:
+            tools.append({
+                "name": "write",
+                "description": ("Write a whole file, replacing it entirely if it "
+                                "exists. Prefer 'edit' for existing files."),
+                "parameters": {
+                    "file": {"type": "string", "required": True},
+                    "content": {"type": "string", "required": True},
+                },
+            })
+        tools.append({
             "name": "finish_step",
             "description": (
                 "Signal that all required output files have been written and "
-                "the step is complete. Call this ONLY after all write tool calls "
-                "in the current turn have been made — it must be the last call."
+                "the step is complete. Call this ONLY after all create/edit/write "
+                "tool calls in the current turn have been made — it must be the "
+                "last call."
             ),
             "parameters": {
                 "summary": {"type": "string", "required": False,
                            "description": "Brief summary of what was created or completed"},
             },
-        }]
+        })
+        return tools
 
     if output_mode == "content":
         tools = []
@@ -336,3 +379,72 @@ def execute_generic_write(params: dict, output_dir: str) -> dict:
     path.parent.mkdir(parents=True, exist_ok=True)
     path.write_text(_ensure_str(params.get("content", "")), encoding="utf-8")
     return {"written": str(Path(*safe_parts))}
+
+
+def execute_generic_create(params: dict, output_dir: str,
+                           source_dir: str = "") -> dict:
+    """Execute a generic create(file, content) call for new repo files.
+
+    Writes the whole file into ``output_dir`` (staging). Refuses to create a
+    file that already exists in staging or in the consolidated repo
+    (``source_dir``) — existing files must be changed with ``edit``, so a
+    create can never silently clobber an existing file's contents.
+    """
+    raw = params.get("file") or params.get("filename") or params.get("path", "")
+    safe_parts = normalize_repo_path(raw)
+    if not safe_parts:
+        return {"error": "Invalid filename: path traversal denied"}
+    rel = str(Path(*safe_parts))
+    staged = Path(output_dir) / rel
+    repo = (Path(source_dir) / rel) if source_dir else None
+    if staged.exists() or (repo is not None and repo.exists()):
+        return {"error": (f"create: '{rel}' already exists — use 'edit' to change "
+                          f"an existing file (create is for new files only).")}
+    staged.parent.mkdir(parents=True, exist_ok=True)
+    staged.write_text(_ensure_str(params.get("content", "")), encoding="utf-8")
+    return {"written": rel}
+
+
+def execute_generic_edit(params: dict, output_dir: str,
+                         source_dir: str = "") -> dict:
+    """Execute a generic edit(file, old_str, new_str) call on an EXISTING file.
+
+    Baseline is staging-first: read ``output_dir/file`` if a prior edit/create
+    this same step already produced it (so repeated edits to one file compound),
+    else the consolidated repo ``source_dir/file``. Requires ``old_str`` to
+    match exactly once; writes the whole spliced result into staging, from where
+    promotion + repo_apply overwrites the repo copy. The repo is never edited in
+    place — ``edit`` only reads it as a baseline.
+    """
+    raw = params.get("file") or params.get("filename") or params.get("path", "")
+    safe_parts = normalize_repo_path(raw)
+    if not safe_parts:
+        return {"error": "Invalid filename: path traversal denied"}
+    rel = str(Path(*safe_parts))
+    old_str = _ensure_str(params.get("old_str", ""))
+    new_str = _ensure_str(params.get("new_str", ""))
+    if not old_str:
+        return {"error": "edit: 'old_str' is required and must be non-empty"}
+
+    staged = Path(output_dir) / rel
+    repo = (Path(source_dir) / rel) if source_dir else None
+    if staged.exists():
+        src = staged
+    elif repo is not None and repo.exists():
+        src = repo
+    else:
+        return {"error": (f"edit: cannot edit '{rel}' — file does not exist "
+                          f"(use 'create' for a new file).")}
+
+    content = src.read_text(encoding="utf-8")
+    occurrences = content.count(old_str)
+    if occurrences == 0:
+        return {"error": f"edit: 'old_str' not found in '{rel}'"}
+    if occurrences > 1:
+        return {"error": (f"edit: 'old_str' matches {occurrences} times in '{rel}' "
+                          f"— include more surrounding context to make it unique")}
+
+    updated = content.replace(old_str, new_str, 1)
+    staged.parent.mkdir(parents=True, exist_ok=True)
+    staged.write_text(updated, encoding="utf-8")
+    return {"edited": rel}

{skillflow_py-1.2.0 → skillflow_py-1.3.0/src/skillflow_py.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: skillflow-py
-Version: 1.2.0
+Version: 1.3.0
 Summary: Config-agnostic LLM pipeline graph executor — turn skills into flows
 Author: Skillflow contributors
 License-Expression: MIT
@@ -207,10 +207,15 @@ This powers both **inner review loops** (e.g. `review → implement`, `max_loop:
 context:
   - source: { step: "1" }
   - source: { step: "2", mode: "interfaces" }
-  - source: { config: "meta", output: "brief.md" }
+  - source: { config: "meta", output: "brief.md" }                  # any step of another config
+  - source: { config: "meta", step: "finalize", output: "x.json" }  # a SPECIFIC step's output
   - source: { tool: "dir_tree" }
 ```
 
+A cross-config source without `step` scans the other config's step dirs for the
+file; adding `step` reads that one step's output (use it when only a specific
+producing step is authoritative).
+
 ## Checkpoints
 
 Agent steps can pause for human approval (`tests/fixtures/checkpoint_cycle.yaml`). On reject, the feedback is injected (via the `_feedback` channel) so the re-run knows *why* it was rejected:
@@ -268,6 +273,8 @@ end_conditions:
     - type: node_reached
       node: "5_review"
       result: "completed"
+      require_completed: true   # fire only once the node has COMPLETED, not merely
+                                # been reached (i.e. become current_node)
     - type: max_total_steps
       limit: 200
     - type: max_run_duration_seconds
@@ -276,6 +283,17 @@ end_conditions:
       flag: { fatal_error: true }
 ```
 
+`require_completed` (node_reached only) gates termination on the node's step
+reaching `completed` status. Use it when the terminal node is a real agent/tool
+step that must execute before the run ends — without it the condition fires as
+soon as the node becomes `current_node`.
+
+**Terminating a run needs an end condition.** A transition `to: null` does NOT by
+itself end a run: with no resolvable target the run is marked **failed** ("no
+matching transition"). To finish cleanly, give the terminal step `to: null` **and**
+a `node_reached` end condition for that node (the pattern above). This applies to
+`tool` and `gate` steps too, not just `agent` steps.
+
 ## Stale Claim Recovery
 
 Built into `advance_run`. A claim whose worker died before calling `confirm`, and that is older than `stale_threshold_seconds` (default 300), is auto-reset to `pending` and re-claimed: