agentic-dev-loop 1.0.0a4__tar.gz → 1.0.0a6__tar.gz

{agentic_dev_loop-1.0.0a4/src/agentic_dev_loop.egg-info → agentic_dev_loop-1.0.0a6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a4
+Version: 1.0.0a6
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -25,14 +25,17 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: openhands-sdk~=1.17.0
-Requires-Dist: openhands-tools~=1.17.0
-Requires-Dist: agent-client-protocol<1.0.0
-Requires-Dist: langgraph>=1.2
-Requires-Dist: langgraph-checkpoint-sqlite>=3.0
 Requires-Dist: pydantic>=2.0
 Requires-Dist: PyYAML>=6.0
+Provides-Extra: engine
+Requires-Dist: openhands-sdk~=1.17.0; extra == "engine"
+Requires-Dist: openhands-tools~=1.17.0; extra == "engine"
+Requires-Dist: agent-client-protocol<1.0.0; extra == "engine"
+Requires-Dist: langgraph>=1.2; extra == "engine"
+Requires-Dist: langgraph-checkpoint-sqlite>=3.0; extra == "engine"
+Provides-Extra: workflow
 Provides-Extra: dev
+Requires-Dist: agentic-dev-loop[engine]; extra == "dev"
 Requires-Dist: hypothesis>=6.0; extra == "dev"
 Requires-Dist: pytest>=8.0; extra == "dev"
 Dynamic: license-file
@@ -62,6 +65,11 @@ flowchart LR
 - **Sandboxed by default.** The agent's shell and every command step run inside
   an always-on Docker sandbox. There is no opt-out.
 
+Two modes share one `pipeline.yaml`: **engine mode** (the sandboxed, resumable
+loop above) and **workflow mode** — a Claude Dynamic Workflow exported from the
+same pipeline that runs in Claude Code's own environment, with the live graph
+visualiser. See [Workflow mode](#workflow-mode-claude-code).
+
 ---
 
 ## Core features
@@ -90,8 +98,13 @@ LLM timeout (agent runs are long).
 | LLM API key | The env var named by your pipeline's `api_key_env` (e.g. `OPENAI_API_KEY`) must be set — a missing key fails fast, naming it. |
 
 ```bash
-pip install agentic-dev-loop==1.0.0a3   # pin the current alpha release explicitly
+# engine mode (sandboxed loop — the full install)
+pip install "agentic-dev-loop[engine]==1.0.0a6"
 agentic-dev-loop --version
+
+# workflow mode (Claude Code — core + viz only, no SDK/Docker deps)
+pip install "agentic-dev-loop==1.0.0a6"
+agentic-dev-loop-workflow install-skill
 ```
 
 On the first run the engine pulls the **digest-pinned** dev image
@@ -102,6 +115,43 @@ image. Engine setup, first-run details, the full `pipeline.yaml` contract, and
 troubleshooting for every fail-fast code live in
 [docs/setup.md](docs/setup.md).
 
+## Workflow mode (Claude Code)
+
+For developers who know and love the agentic dev loop but are forced to use
+Claude Code at work: workflow mode exports a **Claude Dynamic Workflow** from
+the `pipeline.yaml` they already trust, plus the visualiser they trust. It adds
+the deterministic loop through Claude's mechanism — nothing more. **No Docker
+sandboxing, and no new security claims**: workflow steps run in Claude Code's
+own environment under its permission model (a documented trust-model change
+from engine mode).
+
+Install the skill once:
+
+```bash
+pip install "agentic-dev-loop==1.0.0a6"  # base install: core + viz, no SDK/Docker
+agentic-dev-loop-workflow install-skill # → ~/.claude/skills/agentic-dev-loop/
+```
+
+Then invoke `/agentic-dev-loop` in Claude Code. The skill walks through:
+
+1. **Build** — `python -m agentic_dev_loop.core.project <pipeline.yaml>` loads +
+   validates the pipeline, verifies every agent step's `.agent.md` prompt exists
+   (a missing prompt fails the build loudly, naming the file), and writes a
+   self-contained `.agentic-dev-loop/workflow.js`. Steps are frozen at creation
+   — mid-run `pipeline.yaml` edits never affect a running workflow.
+2. **Run** — the generated JS routes `on_pass` / `on_fail` / `goto` with its own
+   attempt counter, injects the failing subagent's output as the next retry note,
+   launches the live-graph server (localhost, token-authenticated ingest), and
+   invokes the docker-free commit shim, which refuses loudly unless the worktree
+   was clean at run start.
+
+Engine-only fields (`isolation:`, per-step `network:`, `setup:`) are ignored in
+workflow mode with no effect on the build or run.
+
+The base install is deliberately dependency-light (`pydantic` + `PyYAML` only);
+the heavy OpenHands-SDK engine lives in the `[engine]` extra. The `core` and
+`viz` packages are guarded against pulling engine deps.
+
 ## Usage
 
 ```bash
@@ -142,7 +192,7 @@ Exit code is `0` on pipeline success, `1` otherwise.
 ```yaml
 name: my-construction-loop
 extensions:
-  - agentic_dev_loop.extensions.aidlc:AidlcExtension   # bundled AI-DLC doc loader
+  - agentic_dev_loop.engine.extensions.aidlc:AidlcExtension   # bundled AI-DLC doc loader
 additional_files:
   - ../README.md                                       # shared context for every agent step
 

agentic_dev_loop-1.0.0a4/PKG-INFO → agentic_dev_loop-1.0.0a6/README.md

@@ -1,42 +1,3 @@
-Metadata-Version: 2.4
-Name: agentic-dev-loop
-Version: 1.0.0a4
-Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
-Author: Luke Wilson
-License-Expression: Apache-2.0
-Project-URL: Homepage, https://github.com/lukedawilson/agentic-dev-loop
-Classifier: Development Status :: 4 - Beta
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: Operating System :: MacOS
-Classifier: Operating System :: Microsoft :: Windows
-Classifier: Operating System :: POSIX :: Linux
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
-Classifier: Topic :: Software Development
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Topic :: Software Development :: Quality Assurance
-Classifier: Topic :: Security
-Classifier: Typing :: Typed
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: openhands-sdk~=1.17.0
-Requires-Dist: openhands-tools~=1.17.0
-Requires-Dist: agent-client-protocol<1.0.0
-Requires-Dist: langgraph>=1.2
-Requires-Dist: langgraph-checkpoint-sqlite>=3.0
-Requires-Dist: pydantic>=2.0
-Requires-Dist: PyYAML>=6.0
-Provides-Extra: dev
-Requires-Dist: hypothesis>=6.0; extra == "dev"
-Requires-Dist: pytest>=8.0; extra == "dev"
-Dynamic: license-file
-
 # agentic-dev-loop
 
 > **Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.**
@@ -62,6 +23,11 @@ flowchart LR
 - **Sandboxed by default.** The agent's shell and every command step run inside
   an always-on Docker sandbox. There is no opt-out.
 
+Two modes share one `pipeline.yaml`: **engine mode** (the sandboxed, resumable
+loop above) and **workflow mode** — a Claude Dynamic Workflow exported from the
+same pipeline that runs in Claude Code's own environment, with the live graph
+visualiser. See [Workflow mode](#workflow-mode-claude-code).
+
 ---
 
 ## Core features
@@ -90,8 +56,13 @@ LLM timeout (agent runs are long).
 | LLM API key | The env var named by your pipeline's `api_key_env` (e.g. `OPENAI_API_KEY`) must be set — a missing key fails fast, naming it. |
 
 ```bash
-pip install agentic-dev-loop==1.0.0a3   # pin the current alpha release explicitly
+# engine mode (sandboxed loop — the full install)
+pip install "agentic-dev-loop[engine]==1.0.0a6"
 agentic-dev-loop --version
+
+# workflow mode (Claude Code — core + viz only, no SDK/Docker deps)
+pip install "agentic-dev-loop==1.0.0a6"
+agentic-dev-loop-workflow install-skill
 ```
 
 On the first run the engine pulls the **digest-pinned** dev image
@@ -102,6 +73,43 @@ image. Engine setup, first-run details, the full `pipeline.yaml` contract, and
 troubleshooting for every fail-fast code live in
 [docs/setup.md](docs/setup.md).
 
+## Workflow mode (Claude Code)
+
+For developers who know and love the agentic dev loop but are forced to use
+Claude Code at work: workflow mode exports a **Claude Dynamic Workflow** from
+the `pipeline.yaml` they already trust, plus the visualiser they trust. It adds
+the deterministic loop through Claude's mechanism — nothing more. **No Docker
+sandboxing, and no new security claims**: workflow steps run in Claude Code's
+own environment under its permission model (a documented trust-model change
+from engine mode).
+
+Install the skill once:
+
+```bash
+pip install "agentic-dev-loop==1.0.0a6"  # base install: core + viz, no SDK/Docker
+agentic-dev-loop-workflow install-skill # → ~/.claude/skills/agentic-dev-loop/
+```
+
+Then invoke `/agentic-dev-loop` in Claude Code. The skill walks through:
+
+1. **Build** — `python -m agentic_dev_loop.core.project <pipeline.yaml>` loads +
+   validates the pipeline, verifies every agent step's `.agent.md` prompt exists
+   (a missing prompt fails the build loudly, naming the file), and writes a
+   self-contained `.agentic-dev-loop/workflow.js`. Steps are frozen at creation
+   — mid-run `pipeline.yaml` edits never affect a running workflow.
+2. **Run** — the generated JS routes `on_pass` / `on_fail` / `goto` with its own
+   attempt counter, injects the failing subagent's output as the next retry note,
+   launches the live-graph server (localhost, token-authenticated ingest), and
+   invokes the docker-free commit shim, which refuses loudly unless the worktree
+   was clean at run start.
+
+Engine-only fields (`isolation:`, per-step `network:`, `setup:`) are ignored in
+workflow mode with no effect on the build or run.
+
+The base install is deliberately dependency-light (`pydantic` + `PyYAML` only);
+the heavy OpenHands-SDK engine lives in the `[engine]` extra. The `core` and
+`viz` packages are guarded against pulling engine deps.
+
 ## Usage
 
 ```bash
@@ -142,7 +150,7 @@ Exit code is `0` on pipeline success, `1` otherwise.
 ```yaml
 name: my-construction-loop
 extensions:
-  - agentic_dev_loop.extensions.aidlc:AidlcExtension   # bundled AI-DLC doc loader
+  - agentic_dev_loop.engine.extensions.aidlc:AidlcExtension   # bundled AI-DLC doc loader
 additional_files:
   - ../README.md                                       # shared context for every agent step
 

{agentic_dev_loop-1.0.0a4 → agentic_dev_loop-1.0.0a6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentic-dev-loop"
-version = "1.0.0a4"
+version = "1.0.0a6"
 description = "Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -32,15 +32,9 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "openhands-sdk ~=1.17.0",
-    "openhands-tools ~=1.17.0",
-    # openhands-sdk declares agent-client-protocol>=0.8.1 with NO upper bound;
-    # the 1.0.0rc pre-releases drop acp.helpers (breaks sdk 1.17.0 imports).
-    # Without this cap, --pre installs resolve to the broken rc. See AGENTS.md
-    # error-handling rules + COMPAT-SHIMS.md for the SDK-compat pattern.
-    "agent-client-protocol<1.0.0",
-    "langgraph>=1.2",
-    "langgraph-checkpoint-sqlite>=3.0",
+    # Base install = workflow mode (core + viz + workflow CLI). Deliberately
+    # dependency-light (TS-1 / NFR-4.1 / BR-2): pydantic + PyYAML only. The
+    # heavy OpenHands-SDK engine deps live in the [engine] extra below.
     "pydantic>=2.0",
     "PyYAML>=6.0",
 ]
@@ -49,10 +43,28 @@ dependencies = [
 Homepage = "https://github.com/lukedawilson/agentic-dev-loop"
 
 [project.scripts]
-agentic-dev-loop = "agentic_dev_loop.cli:main"
+agentic-dev-loop = "agentic_dev_loop.engine.cli:main"
+agentic-dev-loop-workflow = "agentic_dev_loop.workflow.cli:main"
+agentic-dev-loop-commit = "agentic_dev_loop.engine.commit_shim:main"
 
 [project.optional-dependencies]
+engine = [
+    "openhands-sdk ~=1.17.0",
+    "openhands-tools ~=1.17.0",
+    # openhands-sdk declares agent-client-protocol>=0.8.1 with NO upper bound;
+    # the 1.0.0rc pre-releases drop acp.helpers (breaks sdk 1.17.0 imports).
+    # Without this cap, --pre installs resolve to the broken rc. See AGENTS.md
+    # error-handling rules + COMPAT-SHIMS.md for the SDK-compat pattern.
+    "agent-client-protocol<1.0.0",
+    "langgraph>=1.2",
+    "langgraph-checkpoint-sqlite>=3.0",
+]
+# Workflow mode is the BASE install — this empty extra exists only so
+# `pip install agentic-dev-loop[workflow]` reads naturally and pulls nothing
+# beyond the light base (core + viz). See README / NFR-4.1.
+workflow = []
 dev = [
+    "agentic-dev-loop[engine]",
     "hypothesis>=6.0",
     "pytest>=8.0",
 ]
@@ -62,6 +74,7 @@ where = ["src"]
 
 [tool.setuptools.package-data]
 agentic_dev_loop = ["py.typed"]
+"agentic_dev_loop.core" = ["workflow.js.template"]
 
 [tool.pytest.ini_options]
 markers = [

agentic_dev_loop-1.0.0a6/src/agentic_dev_loop/core/__init__.py

@@ -0,0 +1,25 @@
+"""Pipeline model + parse + workflow projection (unit-4 core).
+
+Dependency-light by contract (BR-2): pydantic + PyYAML + stdlib only. A guard
+test fails if this package imports engine/viz or heavy deps.
+"""
+
+from .config import (PipelineConfig, StepConfig, LlmConfig, IsolationConfig,
+                     VerdictSpec, Route, route_target, load_config,
+                     default_state_dir, TERMINALS)
+from .results import Result
+from .verdict import Verdict, VerdictError, parse_verdict, RETRY
+from .projection import (ProjectedStep, WorkflowProjection, project_workflow,
+                         validate_prompt_refs, render_workflow_js,
+                         clean_at_start_flag, pipeline_hash, core_version,
+                         WORKFLOW_TEMPLATE)
+
+__all__ = [
+    "PipelineConfig", "StepConfig", "LlmConfig", "IsolationConfig",
+    "VerdictSpec", "Route", "route_target", "load_config",
+    "default_state_dir", "TERMINALS",
+    "Result", "Verdict", "VerdictError", "parse_verdict", "RETRY",
+    "ProjectedStep", "WorkflowProjection", "project_workflow",
+    "validate_prompt_refs", "render_workflow_js", "clean_at_start_flag",
+    "pipeline_hash", "core_version", "WORKFLOW_TEMPLATE",
+]

{agentic_dev_loop-1.0.0a4/src/agentic_dev_loop → agentic_dev_loop-1.0.0a6/src/agentic_dev_loop/core}/config.py

@@ -206,7 +206,7 @@ def default_state_dir(pipeline_path: Path) -> str:
 
 def load_config(path: Path) -> PipelineConfig:
     path = Path(path)
-    data = yaml.safe_load(path.read_text())
+    data = yaml.safe_load(path.read_text(encoding="utf-8"))
     if not isinstance(data, dict):
         raise ValueError(
             f"pipeline config must be a mapping, got {type(data).__name__}: {path}"

agentic_dev_loop-1.0.0a6/src/agentic_dev_loop/core/project.py

@@ -0,0 +1,64 @@
+"""Build-time projection entry point (FD-5).
+
+`python -m agentic_dev_loop.core.project <pipeline.yaml>` loads + validates
+the pipeline, projects it, checks prompt references (BR-4), and renders the
+self-contained workflow JS to `.agentic-dev-loop/workflow.js` in the
+pipeline's directory. Runtime never parses the YAML (BR-1).
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from .config import load_config
+from .projection import (WORKFLOW_TEMPLATE, core_version, pipeline_hash,
+                         project_workflow, render_workflow_js)
+
+OUTPUT_DIR = ".agentic-dev-loop"
+OUTPUT_FILE = "workflow.js"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="agentic-dev-loop-project",
+        description="Project pipeline.yaml into a Claude Dynamic Workflow JS.")
+    parser.add_argument("pipeline", type=Path, nargs="?",
+                        default=Path("pipeline.yaml"),
+                        help="path to the pipeline YAML (default: pipeline.yaml)")
+    parser.add_argument("-o", "--output", type=Path, default=None,
+                        help="where to write the generated JS (default: "
+                             "<pipeline dir>/.agentic-dev-loop/workflow.js)")
+    args = parser.parse_args(argv)
+
+    pipeline_path = args.pipeline
+    cfg = load_config(pipeline_path)
+    base = pipeline_path.resolve().parent
+    agents_dir = base / cfg.agents_dir
+    phash = pipeline_hash(pipeline_path)
+
+    # Bake workspace-relative prompt references (BR-5): the generated
+    # workflow re-reads each `.agent.md` from the workspace at run time, so
+    # the reference must be relative to the invocation directory (Claude
+    # Code's workspace), never an absolute host path. Fall back to the
+    # absolute path when the pipeline lives on a different volume (Windows).
+    try:
+        agents_ref = Path(os.path.relpath(agents_dir, Path.cwd().resolve()))
+    except ValueError:
+        agents_ref = agents_dir
+
+    projection = project_workflow(cfg, agents_ref, phash)
+    js = render_workflow_js(WORKFLOW_TEMPLATE, projection, core_version(), phash)
+
+    out = args.output or (base / OUTPUT_DIR / OUTPUT_FILE)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(js, encoding="utf-8")
+    print(f"Projected {cfg.name!r} ({len(projection.steps)} steps) -> {out}",
+          flush=True)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agentic_dev_loop-1.0.0a6/src/agentic_dev_loop/core/projection.py

@@ -0,0 +1,206 @@
+"""Workflow projection — pure functions that turn a validated PipelineConfig
+into a Claude Dynamic Workflow (unit-4).
+
+The projection runs at workflow-creation time; the generated JS is
+self-contained (step data + prompt refs + routing baked in). Runtime never
+parses pipeline.yaml (BR-1). Everything here is dependency-light: pydantic +
+PyYAML + stdlib only (BR-2).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import importlib.metadata
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .config import Route, PipelineConfig, route_target
+
+_KINDS = ("agent", "command", "action")
+
+
+def core_version() -> str:
+    """The installed distribution version — the single source of truth for
+    the generated-JS header stamp (FD-5)."""
+    try:
+        return importlib.metadata.version("agentic-dev-loop")
+    except importlib.metadata.PackageNotFoundError:
+        return "0.0.0+dev"
+
+
+def pipeline_hash(pipeline_path: str | Path) -> str:
+    """The first 12 chars of the sha256 of the absolute pipeline-file path —
+    the same digest the engine uses for its per-pipeline state dir."""
+    return hashlib.sha256(
+        str(Path(pipeline_path).resolve()).encode("utf-8")).hexdigest()[:12]
+
+
+@dataclass(frozen=True)
+class ProjectedStep:
+    """One step, projected for the workflow: routing + verdict config + the
+    prompt *reference* (BR-5 — never embedded)."""
+
+    id: str
+    kind: str
+    command: str | None = None
+    prompt_path: str | None = None
+    action: str | None = None  # action steps (workflow mode supports commit)
+    params: dict | None = None  # action params (e.g. commit message template)
+    verdicts: dict[str, str] | None = None  # keyword -> canonical pass/fail
+    on_pass: str | None = None
+    on_fail: str | None = None
+    retry: bool = False  # on_fail is {goto, retry: true}
+    max_attempts: int = 3
+    timeout: float | None = None
+
+    def __post_init__(self) -> None:
+        if self.kind not in _KINDS:
+            raise ValueError(f"step {self.id!r}: unknown kind {self.kind!r}")
+        if self.kind == "agent" and self.prompt_path is None:
+            raise ValueError(f"agent step {self.id!r}: missing prompt reference")
+        if self.kind == "command" and not self.command:
+            raise ValueError(f"command step {self.id!r}: missing command")
+        if self.kind == "action" and not self.action:
+            raise ValueError(f"action step {self.id!r}: missing action name")
+
+    @staticmethod
+    def from_config(step, agents_dir: Path, max_attempts: int) -> "ProjectedStep":
+        command: str | None = None
+        prompt_path: str | None = None
+        action: str | None = None
+        if step.kind == "agent":
+            # POSIX form (BR-5): the reference is a workspace-relative
+            # path, and forward slashes keep the golden render machine-
+            # independent (Windows CI bakes the same bytes as POSIX).
+            prompt_path = (agents_dir / f"{step.agent}.agent.md").as_posix()
+        elif step.kind == "command":
+            command = step.command
+        elif step.kind == "action":
+            action = step.action
+        verdicts: dict[str, str] | None = None
+        if step.verdicts is not None:
+            verdicts = {step.verdicts.pass_: "pass", step.verdicts.fail: "fail"}
+        on_fail = route_target(step.on_fail)
+        return ProjectedStep(
+            id=step.name,
+            kind=step.kind,
+            command=command,
+            prompt_path=prompt_path,
+            action=action,
+            params=dict(step.params) if step.params else None,
+            verdicts=verdicts,
+            on_pass=route_target(step.on_pass),
+            on_fail=on_fail,
+            retry=isinstance(step.on_fail, Route) and step.on_fail.retry,
+            max_attempts=max_attempts,
+            timeout=step.timeout,
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "kind": self.kind,
+            "command": self.command,
+            "prompt_path": self.prompt_path,
+            "action": self.action,
+            "params": self.params,
+            "verdicts": self.verdicts,
+            "on_pass": self.on_pass,
+            "on_fail": self.on_fail,
+            "retry": self.retry,
+            "max_attempts": self.max_attempts,
+            "timeout": self.timeout,
+        }
+
+
+@dataclass(frozen=True)
+class WorkflowProjection:
+    """The frozen result of `project_workflow` — everything the generated JS
+    needs, nothing it doesn't (no `llm` block, no engine-only fields)."""
+
+    pipeline_name: str
+    pipeline_hash: str
+    core_version: str
+    steps: list[ProjectedStep] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        if not self.steps:
+            raise ValueError("workflow projection requires at least one step")
+
+    def steps_data(self) -> list[dict]:
+        return [s.to_dict() for s in self.steps]
+
+
+def project_workflow(cfg: PipelineConfig, agents_dir: str | Path,
+                     pipeline_hash: str) -> WorkflowProjection:
+    """Project a validated PipelineConfig into a WorkflowProjection.
+
+    Reuses the already-loaded/validated config (routing targets and step
+    shape are checked by `PipelineConfig`); the only build-time check added
+    here is prompt-reference existence (BR-4)."""
+    agents_dir = Path(agents_dir)
+    steps = [ProjectedStep.from_config(s, agents_dir, cfg.max_attempts)
+             for s in cfg.steps]
+    projection = WorkflowProjection(
+        pipeline_name=cfg.name,
+        pipeline_hash=pipeline_hash,
+        core_version=core_version(),
+        steps=steps,
+    )
+    validate_prompt_refs(projection, agents_dir)
+    return projection
+
+
+def validate_prompt_refs(projection: WorkflowProjection,
+                         agents_dir: str | Path) -> None:
+    """Every agent step's `.agent.md` must exist at build time (BR-4).
+
+    A missing prompt fails the build loudly, naming the file — never
+    silently generates a broken workflow."""
+    agents_dir = Path(agents_dir)
+    for step in projection.steps:
+        if step.kind == "agent" and step.prompt_path is not None:
+            prompt = Path(step.prompt_path)
+            if not prompt.is_file():
+                rel = prompt
+                try:
+                    rel = prompt.relative_to(agents_dir)
+                except ValueError:
+                    pass
+                raise FileNotFoundError(
+                    f"workflow agent step {step.id!r}: prompt file not found: "
+                    f"{rel} (under {agents_dir})")
+
+
+# The wheel-shipped workflow JS template (FD-5). It ships as package data
+# next to this module (a real file, not an inline string — TS-6/KD-3) and is
+# filled by render_workflow_js at build time. The deterministic loop — step
+# routing, the attempt counter, retry-note injection, clean-at-start, the viz
+# launch, and the gated commit — lives entirely inside the template.
+WORKFLOW_TEMPLATE = (
+    Path(__file__).with_name("workflow.js.template").read_text(encoding="utf-8")
+)
+
+
+def render_workflow_js(template: str, projection: WorkflowProjection,
+                       core_version: str, pipeline_hash: str) -> str:
+    """Fill the wheel-shipped template from a projection (FD-5).
+
+    Deterministic given (template, projection, core_version, pipeline_hash):
+    the version + hash appear only in the first-line header, so a differing
+    stamp changes the header alone — the baked steps never vary with it."""
+    steps_json = json.dumps(projection.steps_data(), sort_keys=True, indent=2)
+    return (
+        template
+        .replace("{{CORE_VERSION}}", core_version)
+        .replace("{{PIPELINE_HASH}}", pipeline_hash)
+        .replace("{{PIPELINE_NAME}}", json.dumps(projection.pipeline_name))
+        .replace("{{STEPS_JSON}}", steps_json)
+    )
+
+
+def clean_at_start_flag(git_porcelain_output: str) -> bool:
+    """True when `git status --porcelain` is empty — the worktree was clean
+    at run start, so the auto-commit is allowed (BR-8, FD-3)."""
+    return not git_porcelain_output.strip()