devflow-toolkit 0.3.0__py3-none-any.whl

devflow/core/spec_workflow.py

@@ -0,0 +1,932 @@
+"""Harness-independent specification workflow."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from devflow.core.architecture import (
+  ArchitectureManifest,
+  ArchitectureManifestLoader,
+)
+from devflow.core.artifacts.store import ArtifactStore
+from devflow.core.clock import Clock, SystemClock, format_timestamp
+from devflow.core.config import (
+  EXECUTION_MODES,
+  ConfigError,
+  DevFlowConfig,
+)
+from devflow.core.constitution import Constitution, ConstitutionLoader
+from devflow.core.discovery import (
+  DiscoveryDocument,
+  DiscoveryError,
+  DiscoveryManager,
+  DiscoveryPlanner,
+)
+from devflow.core.ports import (
+  HarnessExecutionError,
+  HarnessPort,
+  Invocation,
+  InvocationExecutor,
+  RunContext,
+  SetupResult,
+  build_setup_context,
+)
+from devflow.core.profile_manager import ProfileManager
+from devflow.core.project import ProjectDetector
+from devflow.core.specification import (
+  GeneratedSpec,
+  PreparedSpec,
+  SpecificationManager,
+  strip_ansi,
+)
+from devflow.core.state import WorkflowLocator
+from devflow.models.project import (
+  PROJECT_MODES,
+  Project,
+  canonical_project_mode,
+)
+from devflow.models.profile import Profile
+from devflow.prompts import (
+  build_discovery_prompt,
+  build_spec_prompt,
+)
+
+
+@dataclass(frozen=True)
+class SpecWorkflowRequest:
+  """Everything the workflow needs to generate one specification."""
+
+  description: str
+  config: DevFlowConfig
+  execution_mode: str
+  adapter: HarnessPort | None = None
+  warnings: tuple[str, ...] = ()
+  project_mode: str = "existing"
+  continue_spec_id: str | None = None
+
+
+@dataclass(frozen=True)
+class SpecWorkflowResult:
+  """Outcome of a specification workflow run."""
+
+  spec: GeneratedSpec | None
+  harness_name: str | None
+  execution_mode: str
+  warnings: tuple[str, ...]
+  run_warnings: tuple[str, ...]
+  constitution_warnings: tuple[str, ...]
+  setup_result: SetupResult | None
+  constitution_names: tuple[str, ...]
+  project_mode: str = "existing"
+  architecture_digest: str | None = None
+  architecture: ArchitectureManifest | None = None
+  discovery: DiscoveryDocument | None = None
+  discovery_digest: str | None = None
+  discovery_path: Path | None = None
+  discovery_source: str = "deterministic"
+  discovery_created: bool = False
+  blocked: bool = False
+  spec_written: bool = False
+  spec_reused: bool = False
+  continuation: bool = False
+  directory: Path | None = None
+
+
+class SpecWorkflow:
+  """Prepare, run and validate a specification independently of any harness."""
+
+  def __init__(
+    self,
+    executor: InvocationExecutor,
+    *,
+    manager: SpecificationManager | None = None,
+    profile_manager: ProfileManager | None = None,
+    project_detector: ProjectDetector | None = None,
+    clock: Clock | None = None,
+    discovery_planner: DiscoveryPlanner | None = None,
+  ) -> None:
+    self.executor = executor
+    self.manager = manager or SpecificationManager()
+    self.profile_manager = profile_manager or ProfileManager()
+    self.project_detector = project_detector or ProjectDetector()
+    self.constitution_loader = ConstitutionLoader(self.profile_manager)
+    self.clock = clock or SystemClock()
+    self.discovery_planner = discovery_planner or DiscoveryPlanner()
+
+  def run(self, request: SpecWorkflowRequest) -> SpecWorkflowResult:
+    """Run the specification workflow and return its outcome."""
+    description = request.description.strip()
+    continue_id = (request.continue_spec_id or "").strip() or None
+    if continue_id and description:
+      msg = (
+        "Pass either a new change description or --continue, not both. "
+        "Continuing reuses the discovery request of the existing change."
+      )
+      raise ConfigError(msg)
+    if not description and continue_id is None:
+      msg = "The change description cannot be empty."
+      raise ConfigError(msg)
+    if request.execution_mode not in EXECUTION_MODES:
+      msg = (
+        f"Unknown execution mode: {request.execution_mode}. "
+        f"Supported values: {', '.join(EXECUTION_MODES)}."
+      )
+      raise ConfigError(msg)
+
+    requested_mode = canonical_project_mode(request.project_mode)
+    if requested_mode not in PROJECT_MODES:
+      msg = (
+        f"Unknown project mode: {request.project_mode}. "
+        f"Supported values: {', '.join(PROJECT_MODES)}."
+      )
+      raise ConfigError(msg)
+
+    config = request.config
+    profiles = self.profile_manager.resolve(list(config.profiles))
+    constitution = self.constitution_loader.load(config, profiles)
+
+    project = self.project_detector.detect(config.root)
+    project.profiles = list(config.profiles)
+
+    warnings = self._profile_warnings(config, project)
+    discovery_manager = DiscoveryManager(config.root, clock=self.clock)
+    continuation = continue_id is not None
+    project_mode = requested_mode
+    location_directory: Path | None = None
+    location_spec_id: str | None = None
+    discovery: DiscoveryDocument | None = None
+
+    if continue_id is not None:
+      location = WorkflowLocator(config.specifications_path).find(
+        continue_id
+      )
+      location_directory = location.directory
+      location_spec_id = location.spec_id
+      discovery = discovery_manager.load(location.directory, required=True)
+      description = discovery.request.strip()
+      if not description:
+        msg = "The discovery record has an empty request."
+        raise ConfigError(msg)
+      project_mode = discovery.project_mode
+      if requested_mode != project_mode:
+        warnings.append(
+          f"the discovery record uses project mode '{project_mode}'. "
+          f"Ignoring the configured mode '{requested_mode}' for this "
+          "change."
+        )
+
+    architecture = ArchitectureManifestLoader().load(
+      config.root,
+      required=project_mode == "greenfield",
+    )
+    if architecture is not None:
+      warnings.extend(architecture.warnings)
+
+    prepared = self.manager.prepare(
+      description=description,
+      config=config,
+      project=project,
+      constitution=constitution,
+      profiles=profiles,
+      project_mode=project_mode,
+      architecture=architecture,
+      discovery=discovery,
+      discovery_digest=(
+        self._discovery_digest(discovery_manager, location_directory)
+        if continuation and location_directory is not None
+        else None
+      ),
+      directory=location_directory,
+      spec_id=location_spec_id,
+    )
+
+    discovery_created = False
+    discovery_source = "deterministic"
+    if continuation:
+      assert discovery is not None
+      assert location_directory is not None
+      discovery_path = discovery_manager.path(location_directory)
+      discovery_digest = self._discovery_digest(
+        discovery_manager,
+        location_directory,
+      )
+    else:
+      now = format_timestamp(self.clock.now())
+      discovery = self.discovery_planner.build(
+        request=description,
+        spec_id=prepared.spec_id,
+        change=prepared.directory.name,
+        project_mode=project_mode,
+        project=project,
+        profiles=tuple(profile.name for profile in profiles),
+        reference_paths=tuple(
+          reference.path for reference in prepared.analysis.references
+        ),
+        category_paths={
+          category: tuple(
+            reference.path for reference in references
+          )
+          for category, references in prepared.analysis.categories.items()
+        },
+        has_tests=prepared.analysis.has_tests,
+        architecture=architecture,
+        now=now,
+      )
+      discovery_path, discovery_digest = discovery_manager.write(
+        prepared.directory,
+        discovery,
+      )
+      discovery_created = True
+      discovery = discovery_manager.load(
+        prepared.directory,
+        required=True,
+      )
+      discovery_digest = discovery_manager.store.digest_file(
+        discovery_path
+      )
+      prepared = self.manager.prepare(
+        description=description,
+        config=config,
+        project=project,
+        constitution=constitution,
+        profiles=profiles,
+        project_mode=project_mode,
+        architecture=architecture,
+        discovery=discovery,
+        discovery_digest=discovery_digest,
+        directory=prepared.directory,
+        spec_id=prepared.spec_id,
+      )
+
+    warnings.extend(request.warnings)
+    if (
+      request.execution_mode == "interactive"
+      and not config.permissions.allow_spec_write
+    ):
+      warnings.append(
+        "Specification writes are disabled for the agent. The interactive "
+        "run cannot persist artifacts, so DevFlow will use deterministic "
+        "output unless the harness returns a valid document another way."
+      )
+
+    adapter = request.adapter
+    setup_result: SetupResult | None = None
+    if (
+      not discovery.is_complete
+      and self._can_run_discovery(adapter, request, config)
+    ):
+      assert adapter is not None
+      setup_result = self._setup_adapter(
+        adapter=adapter,
+        config=config,
+        project=project,
+        profiles=profiles,
+        constitution=constitution,
+        warnings=warnings,
+      )
+      discovery, discovery_digest, discovery_changed = (
+        self._run_discovery(
+          prepared=prepared,
+          discovery=discovery,
+          discovery_manager=discovery_manager,
+          adapter=adapter,
+          execution_mode=request.execution_mode,
+          config=config,
+          project=project,
+          constitution=constitution,
+          profiles=profiles,
+          warnings=warnings,
+        )
+      )
+      if discovery_changed:
+        discovery_source = "agent"
+      discovery = discovery_manager.load(
+        prepared.directory,
+        required=True,
+      )
+      discovery_digest = self._discovery_digest(
+        discovery_manager,
+        prepared.directory,
+      )
+      prepared = self.manager.prepare(
+        description=description,
+        config=config,
+        project=project,
+        constitution=constitution,
+        profiles=profiles,
+        project_mode=project_mode,
+        architecture=architecture,
+        discovery=discovery,
+        discovery_digest=discovery_digest,
+        directory=prepared.directory,
+        spec_id=prepared.spec_id,
+      )
+
+    self.manager.materialize_context(prepared)
+
+    if not discovery.is_complete:
+      return self._build_result(
+        spec=None,
+        harness_name=None,
+        execution_mode=request.execution_mode,
+        warnings=warnings,
+        run_warnings=[],
+        setup_result=setup_result,
+        constitution=constitution,
+        project_mode=project_mode,
+        architecture=architecture,
+        discovery=discovery,
+        discovery_digest=discovery_digest,
+        discovery_path=discovery_path,
+        discovery_source=discovery_source,
+        discovery_created=discovery_created,
+        blocked=True,
+        spec_written=False,
+        spec_reused=False,
+        continuation=continuation,
+        directory=prepared.directory,
+      )
+
+    reused_spec = self._reusable_spec(
+      prepared=prepared,
+      continuation=continuation,
+      project_mode=project_mode,
+      architecture=architecture,
+      discovery_digest=discovery_digest,
+    )
+    if reused_spec is not None:
+      return self._build_result(
+        spec=reused_spec,
+        harness_name=None,
+        execution_mode=request.execution_mode,
+        warnings=warnings,
+        run_warnings=[],
+        setup_result=setup_result,
+        constitution=constitution,
+        project_mode=project_mode,
+        architecture=architecture,
+        discovery=discovery,
+        discovery_digest=discovery_digest,
+        discovery_path=discovery_path,
+        discovery_source=discovery_source,
+        discovery_created=discovery_created,
+        blocked=False,
+        spec_written=False,
+        spec_reused=True,
+        continuation=continuation,
+        directory=prepared.directory,
+      )
+
+    archive_existing = prepared.path.is_file()
+
+    if adapter is None:
+      return self._fallback(
+        prepared=prepared,
+        warnings=warnings,
+        constitution=constitution,
+        execution_mode=request.execution_mode,
+        project_mode=project_mode,
+        architecture=architecture,
+        discovery=discovery,
+        discovery_digest=discovery_digest,
+        discovery_path=discovery_path,
+        discovery_source=discovery_source,
+        discovery_created=discovery_created,
+        continuation=continuation,
+        archive=archive_existing,
+      )
+
+    if not config.permissions.allow_project_read:
+      warnings.append(
+        "Project reads are disabled for the selected harness. DevFlow "
+        "cannot provide project context to the agent, so deterministic "
+        "DevFlow output will be used."
+      )
+      return self._fallback(
+        prepared=prepared,
+        warnings=warnings,
+        constitution=constitution,
+        execution_mode=request.execution_mode,
+        project_mode=project_mode,
+        architecture=architecture,
+        discovery=discovery,
+        discovery_digest=discovery_digest,
+        discovery_path=discovery_path,
+        discovery_source=discovery_source,
+        discovery_created=discovery_created,
+        continuation=continuation,
+        archive=archive_existing,
+      )
+
+    if not adapter.is_available():
+      warnings.append(
+        f"Agent harness '{adapter.name}' is no longer available on "
+        "PATH. DevFlow will use deterministic output."
+      )
+      return self._fallback(
+        prepared=prepared,
+        warnings=warnings,
+        constitution=constitution,
+        execution_mode=request.execution_mode,
+        project_mode=project_mode,
+        architecture=architecture,
+        discovery=discovery,
+        discovery_digest=discovery_digest,
+        discovery_path=discovery_path,
+        discovery_source=discovery_source,
+        discovery_created=discovery_created,
+        continuation=continuation,
+        archive=archive_existing,
+      )
+
+    if setup_result is None:
+      setup_result = self._setup_adapter(
+        adapter=adapter,
+        config=config,
+        project=project,
+        profiles=profiles,
+        constitution=constitution,
+        warnings=warnings,
+      )
+
+    context_path = self.manager.materialize_context(prepared)
+    prompt = build_spec_prompt(
+      request=description,
+      project_name=project.name,
+      context_path=self._relative(config, context_path),
+      spec_path=self._relative(config, prepared.path),
+      constitution_paths=[
+        self._relative(
+          config,
+          config.constitution.path / document.name,
+        )
+        for document in constitution.documents
+      ],
+      harness_name=adapter.display_name,
+      execution_mode=request.execution_mode,
+      permissions=config.permissions,
+      project_mode=project_mode,
+      architecture_path=(
+        architecture.relative_path(config.root)
+        if architecture is not None
+        else ""
+      ),
+      architecture_digest=(
+        architecture.digest if architecture is not None else ""
+      ),
+      architecture_style=(
+        architecture.style if architecture is not None else ""
+      ),
+      discovery_path=(
+        self._relative(config, discovery_path)
+        if discovery_path is not None
+        else ""
+      ),
+      discovery_digest=discovery_digest,
+      discovery_decisions=list(discovery.decisions()),
+    )
+
+    output_path = (
+      prepared.directory / ".devflow-agent-output.md"
+      if request.execution_mode == "non-interactive"
+      else None
+    )
+    run_context = RunContext(
+      root=config.root,
+      prompt=prompt,
+      spec_directory=prepared.directory,
+      spec_path=prepared.path,
+      mode=request.execution_mode,
+      permissions=config.permissions,
+      output_path=output_path,
+    )
+    warnings.extend(adapter.permission_warnings(run_context))
+
+    invocation = adapter.build_run(run_context)
+    spec, run_warnings = self._run_agent(
+      prepared=prepared,
+      adapter=adapter,
+      invocation=invocation,
+      execution_mode=request.execution_mode,
+      output_path=output_path,
+      project_mode=project_mode,
+      architecture=architecture,
+      discovery_digest=discovery_digest,
+      archive=archive_existing,
+    )
+    return self._build_result(
+      spec=spec,
+      harness_name=adapter.display_name,
+      execution_mode=request.execution_mode,
+      warnings=warnings,
+      run_warnings=run_warnings,
+      setup_result=setup_result,
+      constitution=constitution,
+      project_mode=project_mode,
+      architecture=architecture,
+      discovery=discovery,
+      discovery_digest=discovery_digest,
+      discovery_path=discovery_path,
+      discovery_source=discovery_source,
+      discovery_created=discovery_created,
+      blocked=False,
+      spec_written=True,
+      spec_reused=False,
+      continuation=continuation,
+      directory=prepared.directory,
+    )
+
+  def _can_run_discovery(
+    self,
+    adapter: HarnessPort | None,
+    request: SpecWorkflowRequest,
+    config: DevFlowConfig,
+  ) -> bool:
+    return (
+      adapter is not None
+      and request.execution_mode == "interactive"
+      and config.permissions.allow_project_read
+      and config.permissions.allow_spec_write
+      and adapter.is_available()
+    )
+
+  def _setup_adapter(
+    self,
+    *,
+    adapter: HarnessPort,
+    config: DevFlowConfig,
+    project: Project,
+    profiles: list[Profile],
+    constitution: Constitution,
+    warnings: list[str],
+  ) -> SetupResult:
+    setup_result = adapter.setup(
+      build_setup_context(
+        config=config,
+        project=project,
+        profiles=profiles,
+        constitution=constitution,
+      )
+    )
+    warnings.extend(setup_result.warnings)
+    return setup_result
+
+  def _run_discovery(
+    self,
+    *,
+    prepared: PreparedSpec,
+    discovery: DiscoveryDocument,
+    discovery_manager: DiscoveryManager,
+    adapter: HarnessPort,
+    execution_mode: str,
+    config: DevFlowConfig,
+    project: Project,
+    constitution: Constitution,
+    profiles: list[Profile],
+    warnings: list[str],
+  ) -> tuple[DiscoveryDocument, str, bool]:
+    context_path = self.manager.materialize_context(prepared)
+    discovery_path = discovery_manager.path(prepared.directory)
+    original_digest = self._discovery_digest(
+      discovery_manager,
+      prepared.directory,
+    )
+    spec_existed = prepared.path.exists()
+    prompt = build_discovery_prompt(
+      request=discovery.request,
+      project_name=project.name,
+      context_path=self._relative(config, context_path),
+      discovery_path=self._relative(config, discovery_path),
+      harness_name=adapter.display_name,
+      execution_mode=execution_mode,
+      permissions=config.permissions,
+    )
+    run_context = RunContext(
+      root=config.root,
+      prompt=prompt,
+      spec_directory=prepared.directory,
+      spec_path=prepared.path,
+      mode=execution_mode,
+      permissions=config.permissions,
+      output_path=None,
+    )
+    warnings.extend(adapter.permission_warnings(run_context))
+    invocation = adapter.build_run(run_context)
+    try:
+      self.executor(invocation)
+    except HarnessExecutionError as error:
+      warnings.append(
+        f"discovery agent run failed: {error}. Discovery remains "
+        "awaiting clarification."
+      )
+      return discovery, original_digest, False
+    if not spec_existed and prepared.path.exists():
+      warnings.append(
+        "the discovery agent wrote spec.md although Discovery was "
+        "incomplete. The file was archived and will not be recorded."
+      )
+      store = ArtifactStore(prepared.root)
+      store.archive(prepared.path)
+      prepared.path.unlink(missing_ok=True)
+    try:
+      updated = discovery_manager.load(
+        prepared.directory,
+        required=True,
+      )
+    except DiscoveryError as error:
+      warnings.append(
+        f"the discovery agent produced invalid discovery data: {error}. "
+        "Discovery remains unchanged."
+      )
+      return discovery, original_digest, False
+    digest = self._discovery_digest(
+      discovery_manager,
+      prepared.directory,
+    )
+    if digest == original_digest:
+      warnings.append(
+        "the discovery agent did not record any answer or assumption "
+        "acceptance."
+      )
+    return updated, digest, digest != original_digest
+
+  def _discovery_digest(
+    self,
+    discovery_manager: DiscoveryManager,
+    directory: Path | None,
+  ) -> str:
+    if directory is None:
+      return ""
+    path = discovery_manager.path(directory)
+    if not path.is_file():
+      return ""
+    return discovery_manager.store.digest_file(path)
+
+  def _reusable_spec(
+    self,
+    *,
+    prepared: PreparedSpec,
+    continuation: bool,
+    project_mode: str,
+    architecture: ArchitectureManifest | None,
+    discovery_digest: str,
+  ) -> GeneratedSpec | None:
+    if not continuation or not prepared.path.is_file():
+      return None
+    try:
+      content = prepared.path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+      return None
+    valid, _reason = self.manager.validate(
+      content,
+      project_mode=project_mode,
+      architecture=architecture,
+      discovery_digest=discovery_digest,
+    )
+    if not valid:
+      return None
+    questions = self.manager.extract_open_questions(content)
+    return GeneratedSpec(
+      spec_id=prepared.spec_id,
+      title=prepared.title,
+      path=prepared.path,
+      open_questions=tuple(questions),
+      source="existing",
+    )
+
+  def _run_agent(
+    self,
+    *,
+    prepared: PreparedSpec,
+    adapter: HarnessPort,
+    invocation: Invocation,
+    execution_mode: str,
+    output_path: Path | None,
+    project_mode: str,
+    architecture: ArchitectureManifest | None,
+    discovery_digest: str,
+    archive: bool,
+  ) -> tuple[GeneratedSpec, list[str]]:
+    source = f"{adapter.display_name} ({execution_mode})"
+    run_warnings: list[str] = []
+    try:
+      run_result = self.executor(invocation)
+    except HarnessExecutionError as error:
+      run_warnings.append(str(error))
+      return (
+        self.manager.write(prepared, archive=archive),
+        run_warnings,
+      )
+
+    try:
+      if execution_mode == "interactive":
+        if prepared.path.is_symlink():
+          run_warnings.append(
+            "the interactive agent wrote the specification as a "
+            "symbolic link. Using deterministic DevFlow output."
+          )
+          return (
+            self.manager.write(prepared, archive=archive),
+            run_warnings,
+          )
+        if prepared.path.is_file():
+          content = prepared.path.read_text(encoding="utf-8")
+          valid, reason = self.manager.validate(
+            content,
+            project_mode=project_mode,
+            architecture=architecture,
+            discovery_digest=discovery_digest,
+          )
+          if valid:
+            return (
+              self.manager.write(
+                prepared,
+                content,
+                source=source,
+                archive=archive,
+              ),
+              run_warnings,
+            )
+          run_warnings.append(
+            "agent specification was invalid: "
+            f"{reason}. Using deterministic DevFlow output."
+          )
+          return (
+            self.manager.write(prepared, archive=archive),
+            run_warnings,
+          )
+
+        run_warnings.append(
+          "the interactive agent did not write the specification. "
+          "Using deterministic DevFlow output."
+        )
+        return (
+          self.manager.write(prepared, archive=archive),
+          run_warnings,
+        )
+
+      if run_result.returncode != 0:
+        detail = strip_ansi(run_result.stderr).strip().splitlines()
+        reason = (
+          detail[-1]
+          if detail
+          else f"exit code {run_result.returncode}"
+        )
+        run_warnings.append(
+          f"agent run failed: {reason}. "
+          "Using deterministic DevFlow output."
+        )
+        return (
+          self.manager.write(prepared, archive=archive),
+          run_warnings,
+        )
+
+      content = run_result.file_output or run_result.stdout
+      valid, reason = self.manager.validate(
+        content,
+        project_mode=project_mode,
+        architecture=architecture,
+        discovery_digest=discovery_digest,
+      )
+      if valid:
+        return (
+          self.manager.write(
+            prepared,
+            content,
+            source=source,
+            archive=archive,
+          ),
+          run_warnings,
+        )
+
+      run_warnings.append(
+        f"agent output was invalid: {reason}. "
+        "Using deterministic DevFlow output."
+      )
+      return (
+        self.manager.write(prepared, archive=archive),
+        run_warnings,
+      )
+    finally:
+      if output_path is not None:
+        output_path.unlink(missing_ok=True)
+
+  def _profile_warnings(
+    self,
+    config: DevFlowConfig,
+    project: Project,
+  ) -> list[str]:
+    detected_profiles = {
+      match.profile.name
+      for match in self.profile_manager.detect(project)
+    }
+    configured_profiles = set(config.profiles)
+    new_profiles = sorted(detected_profiles - configured_profiles)
+    stale_profiles = sorted(configured_profiles - detected_profiles)
+
+    warnings: list[str] = []
+    for profile_name in new_profiles:
+      warnings.append(
+        f"detected profile '{profile_name}' is not configured. Current "
+        "analysis uses the profiles in .devflow/config.yaml."
+      )
+    for profile_name in stale_profiles:
+      warnings.append(
+        f"configured profile '{profile_name}' was not detected in the "
+        "current project. Review .devflow/config.yaml if this changed."
+      )
+    return warnings
+
+  def _fallback(
+    self,
+    *,
+    prepared: PreparedSpec,
+    warnings: list[str],
+    constitution: Constitution,
+    execution_mode: str,
+    project_mode: str,
+    architecture: ArchitectureManifest | None,
+    discovery: DiscoveryDocument,
+    discovery_digest: str,
+    discovery_path: Path,
+    discovery_source: str,
+    discovery_created: bool,
+    continuation: bool,
+    archive: bool,
+  ) -> SpecWorkflowResult:
+    self.manager.materialize_context(prepared)
+    return self._build_result(
+      spec=self.manager.write(prepared, archive=archive),
+      harness_name=None,
+      execution_mode=execution_mode,
+      warnings=warnings,
+      run_warnings=[],
+      setup_result=None,
+      constitution=constitution,
+      project_mode=project_mode,
+      architecture=architecture,
+      discovery=discovery,
+      discovery_digest=discovery_digest,
+      discovery_path=discovery_path,
+      discovery_source=discovery_source,
+      discovery_created=discovery_created,
+      blocked=False,
+      spec_written=True,
+      spec_reused=False,
+      continuation=continuation,
+      directory=prepared.directory,
+    )
+
+  def _build_result(
+    self,
+    *,
+    spec: GeneratedSpec | None,
+    harness_name: str | None,
+    execution_mode: str,
+    warnings: list[str],
+    run_warnings: list[str],
+    setup_result: SetupResult | None,
+    constitution: Constitution,
+    project_mode: str,
+    architecture: ArchitectureManifest | None,
+    discovery: DiscoveryDocument | None,
+    discovery_digest: str,
+    discovery_path: Path | None,
+    discovery_source: str,
+    discovery_created: bool,
+    blocked: bool,
+    spec_written: bool,
+    spec_reused: bool,
+    continuation: bool,
+    directory: Path,
+  ) -> SpecWorkflowResult:
+    return SpecWorkflowResult(
+      spec=spec,
+      harness_name=harness_name,
+      execution_mode=execution_mode,
+      warnings=tuple(warnings),
+      run_warnings=tuple(run_warnings),
+      constitution_warnings=constitution.warnings,
+      setup_result=setup_result,
+      constitution_names=constitution.names,
+      project_mode=project_mode,
+      architecture_digest=(
+        architecture.digest if architecture is not None else None
+      ),
+      architecture=architecture,
+      discovery=discovery,
+      discovery_digest=discovery_digest or None,
+      discovery_path=discovery_path,
+      discovery_source=discovery_source,
+      discovery_created=discovery_created,
+      blocked=blocked,
+      spec_written=spec_written,
+      spec_reused=spec_reused,
+      continuation=continuation,
+      directory=directory,
+    )
+
+  @staticmethod
+  def _relative(config: DevFlowConfig, path: Path) -> str:
+    return path.relative_to(config.root).as_posix()