devflow-toolkit 0.3.0__py3-none-any.whl

devflow/core/specification.py

@@ -0,0 +1,2443 @@
+"""Analyze a change request and generate a structured specification."""
+
+from __future__ import annotations
+
+import re
+import sys
+import unicodedata
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+from types import TracebackType
+
+try:
+  import fcntl
+except ImportError:  # pragma: no cover - DevFlow targets POSIX systems.
+  fcntl = None  # type: ignore[assignment]
+
+from devflow.core.architecture import ArchitectureManifest
+from devflow.core.artifacts.store import ArtifactStore
+from devflow.core.config import DevFlowConfig
+from devflow.core.constitution import Constitution
+from devflow.core.discovery import DiscoveryDocument
+from devflow.core.project import (
+  canonicalize_dependency,
+  iter_project_files,
+)
+from devflow.models.profile import Profile
+from devflow.models.project import (
+  PROJECT_MODES,
+  Project,
+  canonical_project_mode,
+)
+
+ANALYSIS_EXTENSIONS = {
+  ".py",
+  ".js",
+  ".jsx",
+  ".ts",
+  ".tsx",
+  ".vue",
+  ".svelte",
+  ".go",
+  ".rs",
+  ".php",
+  ".rb",
+  ".java",
+  ".kt",
+  ".html",
+  ".css",
+  ".scss",
+  ".sql",
+  ".md",
+  ".yaml",
+  ".yml",
+  ".toml",
+  ".json",
+}
+
+IGNORED_FILENAMES = {
+  "package-lock.json",
+  "poetry.lock",
+  "pdm.lock",
+  "yarn.lock",
+  "pnpm-lock.yaml",
+  "uv.lock",
+}
+
+MAX_FILE_BYTES = 256_000
+MAX_ANALYSIS_FILES = 3000
+MAX_REFERENCES = 25
+
+STOPWORDS = {
+  "a",
+  "about",
+  "after",
+  "again",
+  "against",
+  "al",
+  "algo",
+  "algun",
+  "alguna",
+  "alguno",
+  "algunos",
+  "and",
+  "ante",
+  "antes",
+  "are",
+  "as",
+  "at",
+  "be",
+  "been",
+  "before",
+  "but",
+  "by",
+  "can",
+  "como",
+  "con",
+  "contra",
+  "could",
+  "cual",
+  "cuando",
+  "de",
+  "del",
+  "desde",
+  "do",
+  "does",
+  "donde",
+  "during",
+  "e",
+  "el",
+  "ella",
+  "ellas",
+  "ellos",
+  "en",
+  "entre",
+  "era",
+  "es",
+  "esa",
+  "ese",
+  "eso",
+  "esta",
+  "este",
+  "esto",
+  "estos",
+  "estoy",
+  "for",
+  "from",
+  "fue",
+  "ha",
+  "had",
+  "hace",
+  "hacia",
+  "han",
+  "has",
+  "have",
+  "hay",
+  "hasta",
+  "how",
+  "i",
+  "if",
+  "in",
+  "into",
+  "is",
+  "it",
+  "its",
+  "just",
+  "la",
+  "las",
+  "le",
+  "les",
+  "lo",
+  "los",
+  "mas",
+  "me",
+  "mi",
+  "mis",
+  "more",
+  "most",
+  "mucho",
+  "muy",
+  "my",
+  "nada",
+  "need",
+  "ni",
+  "no",
+  "nos",
+  "nosotros",
+  "not",
+  "o",
+  "of",
+  "on",
+  "or",
+  "os",
+  "otra",
+  "otro",
+  "our",
+  "para",
+  "pero",
+  "poco",
+  "por",
+  "porque",
+  "que",
+  "quien",
+  "se",
+  "sea",
+  "ser",
+  "should",
+  "si",
+  "sin",
+  "so",
+  "sobre",
+  "some",
+  "son",
+  "su",
+  "such",
+  "sus",
+  "tambien",
+  "tanto",
+  "te",
+  "than",
+  "that",
+  "the",
+  "their",
+  "them",
+  "then",
+  "there",
+  "these",
+  "they",
+  "this",
+  "tiene",
+  "to",
+  "todo",
+  "todos",
+  "too",
+  "tu",
+  "tus",
+  "un",
+  "una",
+  "uno",
+  "unos",
+  "use",
+  "using",
+  "was",
+  "we",
+  "were",
+  "what",
+  "when",
+  "where",
+  "which",
+  "who",
+  "will",
+  "with",
+  "would",
+  "y",
+  "ya",
+  "you",
+  "your",
+}
+
+TERM_EXPANSIONS = {
+  "autenticacion": ("authentication", "auth", "login"),
+  "authentication": ("auth", "login"),
+  "autorizacion": ("authorization", "permission"),
+  "authorization": ("permission",),
+  "base": ("database",),
+  "cliente": ("customer", "client"),
+  "configuracion": ("configuration", "config", "settings"),
+  "configuration": ("config", "settings"),
+  "contrasena": ("password",),
+  "cuenta": ("account",),
+  "datos": ("data", "database"),
+  "database": ("db",),
+  "documentacion": ("documentation", "docs"),
+  "documentation": ("docs", "readme"),
+  "factura": ("invoice",),
+  "inicio": ("login", "session"),
+  "invoice": ("billing",),
+  "login": ("auth", "session"),
+  "pago": ("payment",),
+  "payment": ("billing",),
+  "pedido": ("order",),
+  "permiso": ("permission",),
+  "permission": ("authorization",),
+  "producto": ("product",),
+  "session": ("auth",),
+  "sesion": ("session", "login"),
+  "usuario": ("user", "account"),
+  "usuarios": ("user", "account"),
+}
+
+CATEGORY_RULES = (
+  ("Tests", {"test", "tests", "spec", "specs"}),
+  (
+    "Database migrations",
+    {"migration", "migrations"},
+  ),
+  (
+    "Models and data",
+    {"model", "models", "entity", "entities"},
+  ),
+  (
+    "API and views",
+    {
+      "view",
+      "views",
+      "api",
+      "apis",
+      "router",
+      "routers",
+      "route",
+      "routes",
+      "controller",
+      "controllers",
+      "endpoint",
+      "endpoints",
+    },
+  ),
+  (
+    "Serializers and validation",
+    {"serializer", "serializers", "validator", "validators"},
+  ),
+  (
+    "Services and domain",
+    {"service", "services", "domain", "usecase", "usecases"},
+  ),
+  (
+    "Data access",
+    {"repository", "repositories", "query", "queries", "dao"},
+  ),
+  (
+    "Frontend",
+    {"component", "components", "page", "pages", "ui"},
+  ),
+  (
+    "Configuration",
+    {"config", "settings", "env"},
+  ),
+  (
+    "Documentation",
+    {"doc", "docs", "readme"},
+  ),
+)
+
+VAGUE_TERMS = {
+  "better",
+  "improve",
+  "improvement",
+  "mejor",
+  "mejora",
+  "mejorar",
+  "optimize",
+  "optimizacion",
+  "optimizar",
+  "optimization",
+  "robust",
+  "robusto",
+  "scalable",
+  "escalable",
+  "support",
+  "soportar",
+  "soporte",
+}
+
+DATA_TERMS = {
+  "campo",
+  "column",
+  "data",
+  "database",
+  "datos",
+  "db",
+  "field",
+  "migration",
+  "migracion",
+  "model",
+  "modelo",
+  "persistencia",
+  "schema",
+  "tabla",
+  "table",
+}
+
+API_TERMS = {
+  "api",
+  "endpoint",
+  "route",
+  "router",
+  "view",
+  "vista",
+  "webservice",
+}
+
+PYTHON_IMPORT = re.compile(
+  r"^\s*(?:from\s+([A-Za-z_][\w.]*)|import\s+([A-Za-z_][\w.]*))",
+  re.MULTILINE,
+)
+JS_IMPORT = re.compile(
+  r"""(?:from\s+|require\()\s*['"]([^'"]+)['"]""",
+)
+ANSI_ESCAPE = re.compile(r"\x1b\[[0-?]*[ -/]*[@-~]")
+
+
+def strip_ansi(value: str) -> str:
+  """Remove terminal color sequences from captured harness output."""
+  return ANSI_ESCAPE.sub("", value)
+
+
+@dataclass(frozen=True)
+class CodeReference:
+  """A project file relevant to the request."""
+
+  path: str
+  score: int
+  matches: tuple[str, ...]
+  lines: tuple[int, ...]
+  category: str
+
+
+@dataclass(frozen=True)
+class ImpactAnalysis:
+  """Static analysis of the code related to a request."""
+
+  keywords: tuple[str, ...]
+  references: tuple[CodeReference, ...]
+  categories: dict[str, tuple[CodeReference, ...]]
+  scanned_files: int
+  external_dependencies: tuple[str, ...]
+  has_tests: bool
+
+
+@dataclass(frozen=True)
+class GeneratedSpec:
+  """A generated specification document."""
+
+  spec_id: str
+  title: str
+  path: Path
+  open_questions: tuple[str, ...]
+  source: str = "static"
+
+
+@dataclass(frozen=True)
+class PreparedSpec:
+  """Analysis and content prepared before an agent writes the spec."""
+
+  spec_id: str
+  title: str
+  description: str
+  root: Path
+  directory: Path
+  path: Path
+  analysis: ImpactAnalysis
+  questions: tuple[str, ...]
+  fallback_content: str
+  context_content: str
+  project_mode: str = "existing"
+  architecture_digest: str | None = None
+  architecture: ArchitectureManifest | None = None
+  discovery: DiscoveryDocument | None = None
+  discovery_digest: str | None = None
+
+
+def normalize_word(value: str) -> str:
+  """Lowercase and remove accents from a word."""
+  normalized = unicodedata.normalize("NFKD", value)
+  without_accents = "".join(
+    character
+    for character in normalized
+    if not unicodedata.combining(character)
+  )
+  return without_accents.lower()
+
+
+def extract_keywords(description: str) -> list[str]:
+  """Extract meaningful request keywords."""
+  normalized = normalize_word(description)
+  words = re.findall(r"[a-z0-9_]{3,}", normalized)
+  keywords: list[str] = []
+  for word in words:
+    if word in STOPWORDS or word.isdigit():
+      continue
+    if word not in keywords:
+      keywords.append(word)
+  return keywords
+
+
+def request_terms(keywords: list[str]) -> list[str]:
+  """Expand keywords with common domain synonyms."""
+  terms: list[str] = []
+  for keyword in keywords:
+    candidates = (keyword, *TERM_EXPANSIONS.get(keyword, ()))
+    for candidate in candidates:
+      if candidate and candidate not in terms:
+        terms.append(candidate)
+  return terms
+
+
+def classifier_category(path: str) -> str:
+  """Return the architectural area inferred from a file path."""
+  parts = {
+    normalize_word(part)
+    for part in re.split(r"[\\/._-]+", path.lower())
+    if part
+  }
+
+  if path.lower().endswith((".md", ".rst")):
+    return "Documentation"
+
+  for category, markers in CATEGORY_RULES:
+    if parts & markers:
+      return category
+  return "Other"
+
+
+def slugify(value: str) -> str:
+  """Create a filesystem-safe slug from a request."""
+  normalized = normalize_word(value)
+  slug = re.sub(r"[^a-z0-9]+", "-", normalized).strip("-")
+  if len(slug) > 60:
+    shortened = slug[:60]
+    boundary = shortened.rfind("-")
+    if boundary >= 30:
+      shortened = shortened[:boundary]
+    slug = shortened.rstrip("-")
+  return slug or "spec"
+
+
+def request_title(description: str) -> str:
+  """Create a short human-readable title from the request."""
+  single_line = " ".join(description.split())
+  if len(single_line) <= 80:
+    return single_line.rstrip(".")
+  return single_line[:77].rstrip() + "..."
+
+
+def split_requirements(description: str) -> list[str]:
+  """Split a request into independent requirement clauses."""
+  normalized = " ".join(description.split())
+  parts = re.split(
+    r"(?:[.;!?]|\n|,\s+|\s+(?:and|y|plus)\s+)",
+    normalized,
+  )
+  clauses = [
+    part.strip(" ,;.!?")
+    for part in parts
+    if len(part.strip(" ,;.!?")) >= 4
+  ]
+  return clauses or [normalized]
+
+
+def _file_has_test_path(path: str) -> bool:
+  lowered = path.lower()
+  parts = {
+    normalize_word(part)
+    for part in re.split(r"[\\/._-]+", lowered)
+    if part
+  }
+  return (
+    "test" in parts
+    or "tests" in parts
+    or Path(lowered).name.startswith("test_")
+    or Path(lowered).name.endswith("_test.py")
+  )
+
+
+class RequestAnalyzer:
+  """Inspect the codebase for evidence related to a request."""
+
+  def analyze(self, description: str, project: Project) -> ImpactAnalysis:
+    """Return the files and areas likely affected by a request."""
+    keywords = extract_keywords(description)
+    terms = request_terms(keywords)
+
+    references: list[CodeReference] = []
+    scanned = 0
+    has_tests = any(
+      _file_has_test_path(path) for path in project.source_files
+    )
+
+    for path in iter_project_files(
+      project.root,
+      extensions=ANALYSIS_EXTENSIONS,
+      max_files=MAX_ANALYSIS_FILES,
+    ):
+      if path.name in IGNORED_FILENAMES:
+        continue
+      try:
+        if path.stat().st_size > MAX_FILE_BYTES:
+          continue
+        content = path.read_text(encoding="utf-8")
+      except (OSError, UnicodeDecodeError):
+        continue
+
+      scanned += 1
+      relative = path.relative_to(project.root).as_posix()
+      lowered_path = relative.lower()
+      lowered_content = content.lower()
+      lowered_lines = lowered_content.splitlines()
+
+      score = 0
+      matches: list[str] = []
+      line_numbers: set[int] = set()
+
+      for term in terms:
+        path_matches = lowered_path.count(term)
+        content_matches = lowered_content.count(term)
+        if not path_matches and not content_matches:
+          continue
+
+        matches.append(term)
+        score += path_matches * 4 + min(content_matches, 10)
+        found = 0
+        for index, line in enumerate(lowered_lines, start=1):
+          if term in line:
+            line_numbers.add(index)
+            found += 1
+            if found >= 2:
+              break
+
+      if score <= 0:
+        continue
+
+      references.append(
+        CodeReference(
+          path=relative,
+          score=score,
+          matches=tuple(matches),
+          lines=tuple(sorted(line_numbers)[:5]),
+          category=classifier_category(relative),
+        )
+      )
+
+    references.sort(key=lambda item: (-item.score, item.path))
+    selected = tuple(references[:MAX_REFERENCES])
+
+    categories: dict[str, list[CodeReference]] = {}
+    for reference in selected:
+      categories.setdefault(reference.category, []).append(reference)
+
+    external = self._external_dependencies(selected, project)
+
+    return ImpactAnalysis(
+      keywords=tuple(keywords),
+      references=selected,
+      categories={
+        name: tuple(items) for name, items in categories.items()
+      },
+      scanned_files=scanned,
+      external_dependencies=tuple(external),
+      has_tests=has_tests,
+    )
+
+  def _external_dependencies(
+    self,
+    references: tuple[CodeReference, ...],
+    project: Project,
+  ) -> list[str]:
+    external: list[str] = []
+    known = project.dependencies
+    stdlib = set(sys.stdlib_module_names)
+
+    for reference in references:
+      path = project.root / reference.path
+      try:
+        content = path.read_text(encoding="utf-8")
+      except (OSError, UnicodeDecodeError):
+        continue
+
+      suffix = path.suffix
+      if suffix == ".py":
+        for first, second in PYTHON_IMPORT.findall(content):
+          module = (first or second).split(".", maxsplit=1)[0]
+          canonical = canonicalize_dependency(module)
+          if module in stdlib:
+            continue
+          if canonical in known and canonical not in external:
+            external.append(canonical)
+      elif suffix in {".js", ".jsx", ".ts", ".tsx", ".vue", ".svelte"}:
+        for value in JS_IMPORT.findall(content):
+          if value.startswith("."):
+            continue
+          if value.startswith("@") and "/" in value:
+            package = "/".join(value.split("/")[:2])
+          else:
+            package = value.split("/", maxsplit=1)[0]
+          canonical = canonicalize_dependency(package)
+          if canonical in known and canonical not in external:
+            external.append(canonical)
+
+    return sorted(external)
+
+
+class _SpecsLock:
+  """Exclusive lock used while assigning a specification directory."""
+
+  def __init__(self, path: Path) -> None:
+    self.path = path
+    self._handle: object | None = None
+
+  def __enter__(self) -> _SpecsLock:
+    self.path.parent.mkdir(parents=True, exist_ok=True)
+    if fcntl is None:  # pragma: no cover
+      return self
+    self._handle = self.path.open("a+", encoding="utf-8")
+    fcntl.flock(self._handle.fileno(), fcntl.LOCK_EX)
+    return self
+
+  def __exit__(
+    self,
+    exc_type: type[BaseException] | None,
+    exc: BaseException | None,
+    traceback: TracebackType | None,
+  ) -> None:
+    handle = self._handle
+    if handle is None:
+      return
+    self._handle = None
+    try:
+      fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+    finally:
+      handle.close()
+
+
+class SpecificationManager:
+  """Generate spec.md documents from a request and project context."""
+
+  def __init__(self) -> None:
+    self.analyzer = RequestAnalyzer()
+
+  def create(
+    self,
+    description: str,
+    config: DevFlowConfig,
+    project: Project,
+    constitution: Constitution,
+    profiles: list[Profile],
+  ) -> GeneratedSpec:
+    """Analyze a request and write a deterministic specification."""
+    prepared = self.prepare(
+      description=description,
+      config=config,
+      project=project,
+      constitution=constitution,
+      profiles=profiles,
+    )
+    return self.write(prepared)
+
+  def prepare(
+    self,
+    description: str,
+    config: DevFlowConfig,
+    project: Project,
+    constitution: Constitution,
+    profiles: list[Profile],
+    *,
+    project_mode: str = "existing",
+    architecture: ArchitectureManifest | None = None,
+    discovery: DiscoveryDocument | None = None,
+    discovery_digest: str | None = None,
+    directory: Path | None = None,
+    spec_id: str | None = None,
+  ) -> PreparedSpec:
+    """Analyze a request without writing the specification file."""
+    mode = canonical_project_mode(project_mode)
+    if mode not in PROJECT_MODES:
+      msg = (
+        f"Unknown project mode: {project_mode}. "
+        f"Supported values: {', '.join(PROJECT_MODES)}."
+      )
+      raise ValueError(msg)
+    if mode == "greenfield" and architecture is None:
+      msg = "Greenfield mode requires a declared architecture manifest."
+      raise ValueError(msg)
+
+    title = request_title(description)
+    if directory is None:
+      spec_id, spec_directory = self._next_spec_directory(
+        config.specifications_path,
+        slugify(description),
+      )
+    else:
+      spec_directory = directory.resolve()
+      try:
+        spec_directory.relative_to(
+          config.specifications_path.resolve()
+        )
+      except ValueError as error:
+        msg = (
+          "Specification directory must stay inside the specifications "
+          f"path: {spec_directory}"
+        )
+        raise ValueError(msg) from error
+      match = re.match(r"^(\d{3})-", spec_directory.name)
+      if spec_id is None:
+        if match is None:
+          msg = (
+            "Specification directory must use the '<id>-<slug>' "
+            f"format: {spec_directory.name}"
+          )
+          raise ValueError(msg)
+        spec_id = match.group(1)
+      if not spec_directory.name.startswith(f"{spec_id}-"):
+        msg = (
+          f"Specification id '{spec_id}' does not match directory "
+          f"'{spec_directory.name}'."
+        )
+        raise ValueError(msg)
+      spec_directory.mkdir(parents=True, exist_ok=True)
+
+    if mode == "greenfield":
+      analysis = ImpactAnalysis(
+        keywords=tuple(extract_keywords(description)),
+        references=(),
+        categories={},
+        scanned_files=0,
+        external_dependencies=(),
+        has_tests=False,
+      )
+      questions = self._greenfield_questions(
+        description,
+        architecture,
+      )
+      fallback = self._render_greenfield(
+        spec_id=spec_id,
+        title=title,
+        description=description,
+        config=config,
+        project=project,
+        constitution=constitution,
+        profiles=profiles,
+        questions=questions,
+        architecture=architecture,
+        discovery=discovery,
+        discovery_digest=discovery_digest,
+        directory=spec_directory,
+      )
+      context = self._render_greenfield_context(
+        spec_id=spec_id,
+        title=title,
+        description=description,
+        config=config,
+        project=project,
+        constitution=constitution,
+        profiles=profiles,
+        questions=questions,
+        architecture=architecture,
+        discovery=discovery,
+        discovery_digest=discovery_digest,
+        directory=spec_directory,
+      )
+    else:
+      analysis = self.analyzer.analyze(description, project)
+      questions = self._open_questions(
+        description,
+        analysis,
+        profiles,
+        project,
+      )
+      fallback = self._render(
+        spec_id=spec_id,
+        title=title,
+        description=description,
+        analysis=analysis,
+        config=config,
+        project=project,
+        constitution=constitution,
+        profiles=profiles,
+        questions=questions,
+        project_mode=mode,
+        architecture=architecture,
+        discovery=discovery,
+        discovery_digest=discovery_digest,
+        directory=spec_directory,
+      )
+      context = self._render_context(
+        spec_id=spec_id,
+        title=title,
+        description=description,
+        analysis=analysis,
+        config=config,
+        project=project,
+        constitution=constitution,
+        profiles=profiles,
+        questions=questions,
+        project_mode=mode,
+        architecture=architecture,
+        discovery=discovery,
+        discovery_digest=discovery_digest,
+        directory=spec_directory,
+      )
+
+    return PreparedSpec(
+      spec_id=spec_id,
+      title=title,
+      description=description,
+      root=config.root,
+      directory=spec_directory,
+      path=spec_directory / "spec.md",
+      analysis=analysis,
+      questions=tuple(questions),
+      fallback_content=fallback,
+      context_content=context,
+      project_mode=mode,
+      architecture_digest=(
+        architecture.digest if architecture is not None else None
+      ),
+      architecture=architecture,
+      discovery=discovery,
+      discovery_digest=discovery_digest,
+    )
+
+  def materialize_context(self, prepared: PreparedSpec) -> Path:
+    """Write the static analysis context used by agent harnesses."""
+    prepared.directory.mkdir(parents=True, exist_ok=True)
+    path = prepared.directory / "context.md"
+    ArtifactStore(prepared.root).write(path, prepared.context_content)
+    return path
+
+  def write(
+    self,
+    prepared: PreparedSpec,
+    content: str | None = None,
+    *,
+    source: str = "static",
+    archive: bool = False,
+  ) -> GeneratedSpec:
+    """Write a specification, falling back to deterministic content."""
+    candidate = content if content is not None else prepared.fallback_content
+    cleaned = self.clean_agent_output(candidate)
+    if not cleaned.strip():
+      cleaned = prepared.fallback_content
+      source = "static"
+
+    prepared.directory.mkdir(parents=True, exist_ok=True)
+    ArtifactStore(prepared.root).write(
+      prepared.path,
+      cleaned.rstrip() + "\n",
+      archive=archive,
+    )
+    questions = (
+      prepared.questions
+      if source == "static"
+      else self.extract_open_questions(cleaned) or prepared.questions
+    )
+    return GeneratedSpec(
+      spec_id=prepared.spec_id,
+      title=prepared.title,
+      path=prepared.path,
+      open_questions=tuple(questions),
+      source=source,
+    )
+
+  def validate(
+    self,
+    content: str,
+    *,
+    project_mode: str = "existing",
+    architecture: ArchitectureManifest | None = None,
+    discovery_digest: str | None = None,
+  ) -> tuple[bool, str]:
+    """Validate that agent output has the required spec structure."""
+    cleaned = self.clean_agent_output(content)
+    if not cleaned.strip():
+      return False, "the specification is empty"
+
+    if not re.search(
+      r"^#\s+Specification\b",
+      cleaned,
+      re.MULTILINE,
+    ):
+      return False, "the '# Specification' heading is missing"
+
+    sections = {
+      int(number)
+      for number in re.findall(
+        r"^##\s+(\d+)\.\s+",
+        cleaned,
+        re.MULTILINE,
+      )
+    }
+    missing = [
+      number for number in range(1, 12) if number not in sections
+    ]
+    if missing:
+      return (
+        False,
+        "missing numbered sections: "
+        + ", ".join(str(number) for number in missing),
+      )
+
+    if "**FR-" not in cleaned:
+      return False, "functional requirements with **FR-XXX:** are missing"
+    if "**AC-" not in cleaned:
+      return False, "acceptance criteria with **AC-XXX:** are missing"
+
+    mode = canonical_project_mode(project_mode)
+    if mode not in PROJECT_MODES:
+      return False, f"unknown project mode: {project_mode}"
+    if discovery_digest and discovery_digest not in cleaned:
+      return (
+        False,
+        "the Discovery digest is missing from the specification",
+      )
+    if mode == "greenfield":
+      return self._validate_greenfield(cleaned, architecture)
+    return True, ""
+
+  def _validate_greenfield(
+    self,
+    cleaned: str,
+    architecture: ArchitectureManifest | None,
+  ) -> tuple[bool, str]:
+    if architecture is None:
+      return (
+        False,
+        "the declared architecture manifest is unavailable",
+      )
+
+    if not re.search(
+      r"^##\s+3\.\s+Target Architecture\s*$",
+      cleaned,
+      re.MULTILINE,
+    ):
+      return (
+        False,
+        "section 3 must be titled 'Target Architecture' in Greenfield mode",
+      )
+    if not re.search(
+      r"^##\s+4\.\s+Architecture Decisions and Risks\s*$",
+      cleaned,
+      re.MULTILINE,
+    ):
+      return (
+        False,
+        "section 4 must be titled 'Architecture Decisions and Risks'",
+      )
+    if not re.search(
+      r"^##\s+Appendix A:\s+Declared Architecture Manifest\s*$",
+      cleaned,
+      re.MULTILINE,
+    ):
+      return (
+        False,
+        "the declared architecture manifest appendix is missing",
+      )
+    if "Current Project State" in cleaned:
+      return (
+        False,
+        "Greenfield specifications must not describe a current project "
+        "state",
+      )
+    if "Relevant existing code" in cleaned:
+      return (
+        False,
+        "Greenfield specifications must not invent existing code "
+        "references",
+      )
+    if architecture.digest not in cleaned:
+      return (
+        False,
+        "the declared architecture manifest digest is missing",
+      )
+    if architecture.style.casefold() not in cleaned.casefold():
+      return (
+        False,
+        "the declared architecture style is missing",
+      )
+    for module in architecture.modules:
+      if module.name not in cleaned:
+        return (
+          False,
+          f"declared module '{module.name}' is missing",
+        )
+    for key, values in architecture.stack.items():
+      if key not in cleaned:
+        return False, f"declared stack field '{key}' is missing"
+      for value in values:
+        if value not in cleaned:
+          return (
+            False,
+            f"declared stack value '{value}' is missing",
+          )
+    for key, values in architecture.constraints.items():
+      if key not in cleaned:
+        return False, f"declared constraint '{key}' is missing"
+      for value in values:
+        if value not in cleaned:
+          return (
+            False,
+            f"declared constraint value '{value}' is missing",
+          )
+    return True, ""
+
+  def clean_agent_output(self, content: str) -> str:
+    """Remove common wrappers from an agent response."""
+    cleaned = strip_ansi(content).lstrip("\ufeff").strip()
+    wrapped = bool(
+      re.match(
+        r"^```(?:markdown|md)?[ \t]*\n",
+        cleaned,
+        flags=re.IGNORECASE,
+      )
+    )
+    # Only remove the closing fence when the whole response was wrapped.
+    # Specifications may legitimately end with a fenced manifest appendix.
+    cleaned = re.sub(
+      r"^```(?:markdown|md)?[ \t]*\n",
+      "",
+      cleaned,
+      count=1,
+      flags=re.IGNORECASE,
+    )
+    if wrapped and cleaned.endswith("```"):
+      cleaned = cleaned[:-3].rstrip()
+
+    start = cleaned.find("# Specification")
+    if start > 0:
+      cleaned = cleaned[start:]
+    return cleaned.strip()
+
+  def extract_open_questions(self, content: str) -> tuple[str, ...]:
+    """Read the open questions listed by an agent specification."""
+    match = re.search(
+      r"^##\s+7\.\s+Open Questions\s*$(.*?)(?=^##\s+8\.|\Z)",
+      content,
+      re.MULTILINE | re.DOTALL,
+    )
+    if not match:
+      return ()
+
+    body = match.group(1).strip()
+    if not body or "no open questions" in body.lower():
+      return ()
+
+    questions: list[str] = []
+    for line in body.splitlines():
+      item = re.match(r"^\s*(?:\d+[.)]|[-*])\s+(.*)", line)
+      if item:
+        question = item.group(1).strip()
+        if question:
+          questions.append(question)
+    return tuple(questions)
+
+  def _next_spec_directory(
+    self,
+    specs_path: Path,
+    slug: str,
+  ) -> tuple[str, Path]:
+    resolved = specs_path.resolve()
+    resolved.mkdir(parents=True, exist_ok=True)
+
+    lock_path = resolved.parent / f".{resolved.name}.lock"
+    with _SpecsLock(lock_path):
+      highest = 0
+      for child in resolved.iterdir():
+        match = re.match(r"^(\d{3})-", child.name)
+        if match:
+          highest = max(highest, int(match.group(1)))
+
+      number = highest + 1
+      while number <= 999:
+        spec_id = f"{number:03d}"
+        candidate = resolved / f"{spec_id}-{slug}"
+        try:
+          candidate.mkdir()
+        except FileExistsError:
+          number += 1
+          continue
+        return spec_id, candidate
+
+    msg = f"No specification id is available in {resolved}."
+    raise OSError(msg)
+
+  def _open_questions(
+    self,
+    description: str,
+    analysis: ImpactAnalysis,
+    profiles: list[Profile],
+    project: Project,
+  ) -> list[str]:
+    questions: list[str] = []
+    meaningful_words = extract_keywords(description)
+
+    if len(meaningful_words) < 2:
+      questions.append(
+        "What exact behavior should change, and how will it be "
+        "verified?"
+      )
+
+    if not analysis.references:
+      searched = (
+        ", ".join(analysis.keywords)
+        or "the request terms"
+      )
+      questions.append(
+        "Which existing modules or entry points are involved? "
+        f"No relevant files were found for: {searched}."
+      )
+
+    vague = sorted(set(meaningful_words) & VAGUE_TERMS)
+    if vague:
+      questions.append(
+        "What measurable outcome defines '"
+        + "', '".join(vague)
+        + "' for this change?"
+      )
+
+    data_words = set(meaningful_words) & DATA_TERMS
+    has_migrations = any(
+      reference.category == "Database migrations"
+      for reference in analysis.references
+    )
+    if data_words and not has_migrations and not project.databases:
+      questions.append(
+        "Does this change require schema or data persistence "
+        "changes? If so, which database and migration strategy "
+        "should be used?"
+      )
+
+    api_words = set(meaningful_words) & API_TERMS
+    has_api = "API and views" in analysis.categories
+    if api_words and not has_api:
+      questions.append(
+        "Which API contract should be used (route, method, request "
+        "and response schema, and error responses)?"
+      )
+
+    if not analysis.has_tests:
+      questions.append(
+        "Where should automated tests for this change live, and "
+        "which cases are mandatory?"
+      )
+
+    detected_profiles = [
+      profile for profile in profiles if profile.name != "base"
+    ]
+    if len(detected_profiles) > 1:
+      names = ", ".join(
+        profile.name for profile in detected_profiles
+      )
+      questions.append(
+        f"Should this change apply to all detected profiles ({names})?"
+      )
+
+    if not questions:
+      questions.extend(
+        [
+          "What is explicitly out of scope for this change?",
+          "Are there backward-compatibility requirements for "
+          "existing clients, data, or integrations?",
+        ]
+      )
+
+    return questions[:6]
+
+  def _discovery_header_rows(
+    self,
+    discovery: DiscoveryDocument | None,
+    digest: str | None,
+    specs_path: Path,
+    root: Path,
+  ) -> list[str]:
+    if discovery is None or not digest:
+      return []
+    path = specs_path / discovery.change / "discovery.yaml"
+    try:
+      relative = path.relative_to(root).as_posix()
+    except ValueError:
+      relative = path.as_posix()
+    return [
+      f"| Discovery | `{relative}` |",
+      f"| Discovery digest | `{digest}` |",
+    ]
+
+  def _discovery_context_lines(
+    self,
+    discovery: DiscoveryDocument | None,
+    digest: str | None,
+    specs_path: Path,
+    root: Path,
+  ) -> list[str]:
+    if discovery is None:
+      return []
+    path = specs_path / discovery.change / "discovery.yaml"
+    try:
+      relative = path.relative_to(root).as_posix()
+    except ValueError:
+      relative = path.as_posix()
+    lines = [
+      "## Discovery",
+      "",
+      f"- File: `{relative}`",
+      f"- Status: `{discovery.status}`",
+      f"- Digest: `{digest or 'unknown'}`",
+      f"- Project mode: `{discovery.project_mode}`",
+      "",
+    ]
+    if discovery.questions:
+      lines.extend(
+        [
+          "| Question | Category | Blocking | Status | Answer |",
+          "| --- | --- | --- | --- | --- |",
+        ]
+      )
+      for question in discovery.questions:
+        answer = question.answer or "-"
+        lines.append(
+          f"| {question.id} | {question.category} | "
+          f"{'yes' if question.blocking else 'no'} | "
+          f"{question.status} | {answer} |"
+        )
+    else:
+      lines.append("No discovery questions were recorded.")
+    if discovery.assumptions:
+      lines.extend(["", "### Proposed assumptions", ""])
+      for assumption in discovery.assumptions:
+        accepted = (
+          f"accepted by {assumption.accepted_by}"
+          if assumption.is_accepted
+          else "pending acceptance"
+        )
+        lines.append(
+          f"- {assumption.id}: {assumption.value} ({accepted})"
+        )
+    return lines
+
+  def _open_questions_lines(
+    self,
+    questions: list[str],
+    discovery: DiscoveryDocument | None,
+  ) -> list[str]:
+    if discovery is not None:
+      if not discovery.is_complete:
+        lines = [
+          "Discovery is not complete. The specification cannot be "
+          "approved until these decisions are resolved:",
+          "",
+        ]
+        for blocker in discovery.blockers():
+          lines.append(f"- {blocker}")
+        return lines
+      lines = [
+        "Discovery is complete. No blocking open questions remain.",
+      ]
+      decisions = discovery.decisions()
+      if decisions:
+        lines.extend(
+          [
+            "",
+            "Decisions consolidated during Discovery:",
+            "",
+          ]
+        )
+        for decision in decisions:
+          lines.append(f"- {decision}")
+      if questions:
+        lines.extend(
+          [
+            "",
+            "Non-blocking questions recorded by static analysis:",
+            "",
+          ]
+        )
+        for index, question in enumerate(questions, start=1):
+          lines.append(f"{index}. {question}")
+      return lines
+
+    if questions:
+      return [
+        f"{index}. {question}"
+        for index, question in enumerate(questions, start=1)
+      ]
+    return ["No open questions were identified by static analysis."]
+
+  def _discovery_approval_lines(
+    self,
+    discovery: DiscoveryDocument | None,
+  ) -> list[str]:
+    if discovery is None:
+      return []
+    return [
+      "- [ ] Discovery is complete and its digest matches this "
+      "specification.",
+    ]
+
+  def _architecture_header_rows(
+    self,
+    architecture: ArchitectureManifest | None,
+    root: Path,
+  ) -> list[str]:
+    if architecture is None:
+      return []
+    return [
+      f"| Architecture manifest | `{architecture.relative_path(root)}` |",
+      f"| Architecture digest | `{architecture.digest}` |",
+    ]
+
+  def _architecture_context_lines(
+    self,
+    architecture: ArchitectureManifest,
+    root: Path,
+  ) -> list[str]:
+    lines = [
+      "The following architecture was declared by the user. It is "
+      "evidence of intended design, not evidence of implemented code.",
+      "",
+      "| Field | Value |",
+      "| --- | --- |",
+      f"| Manifest | `{architecture.relative_path(root)}` |",
+      f"| Digest | `{architecture.digest}` |",
+      f"| Version | `{architecture.version}` |",
+      f"| Style | {architecture.style} |",
+      "",
+      "### Declared summary",
+      "",
+      architecture.summary,
+      "",
+      "### Declared modules",
+      "",
+      "| Module | Responsibility | Depends on |",
+      "| --- | --- | --- |",
+    ]
+    for module in architecture.modules:
+      depends = ", ".join(module.depends_on) or "-"
+      lines.append(
+        f"| {module.name} | {module.responsibility} | {depends} |"
+      )
+
+    lines.extend(["", "### Declared layers", ""])
+    if architecture.layers:
+      lines.extend(
+        [
+          "| Layer | May depend on |",
+          "| --- | --- |",
+        ]
+      )
+      for layer in architecture.layers:
+        depends = ", ".join(layer.may_depend_on) or "-"
+        lines.append(f"| {layer.name} | {depends} |")
+    else:
+      lines.append("No layers were declared.")
+
+    lines.extend(["", "### Declared stack", ""])
+    lines.extend(self._declared_values_table(
+      architecture.stack,
+      "Area",
+      "Technologies",
+    ))
+
+    lines.extend(["", "### Declared constraints", ""])
+    lines.extend(self._declared_values_table(
+      architecture.constraints,
+      "Constraint",
+      "Values",
+    ))
+
+    lines.extend(["", "### Quality attributes", ""])
+    lines.extend(
+      self._bullet_list(architecture.quality_attributes)
+    )
+
+    lines.extend(["", "### Fitness functions", ""])
+    lines.extend(
+      self._bullet_list(architecture.fitness_functions)
+    )
+
+    if architecture.warnings:
+      lines.extend(["", "### Manifest warnings", ""])
+      lines.extend(self._bullet_list(architecture.warnings))
+    return lines
+
+  def _declared_values_table(
+    self,
+    values: dict[str, tuple[str, ...]],
+    key_label: str,
+    value_label: str,
+  ) -> list[str]:
+    if not values:
+      return ["No values were declared."]
+    lines = [
+      f"| {key_label} | {value_label} |",
+      "| --- | --- |",
+    ]
+    for key, items in values.items():
+      lines.append(f"| {key} | {', '.join(items)} |")
+    return lines
+
+  def _bullet_list(self, values: tuple[str, ...]) -> list[str]:
+    if not values:
+      return ["None declared."]
+    return [f"- {value}" for value in values]
+
+  def _greenfield_questions(
+    self,
+    description: str,
+    architecture: ArchitectureManifest,
+  ) -> list[str]:
+    questions: list[str] = []
+    if len(extract_keywords(description)) < 2:
+      questions.append(
+        "What functional outcome should the new system deliver, and "
+        "how will it be verified?"
+      )
+    if not architecture.layers:
+      questions.append(
+        "Which layers or boundaries should the architecture enforce?"
+      )
+    if not architecture.stack:
+      questions.append(
+        "Which languages, frameworks, databases and platforms should "
+        "the new system use?"
+      )
+    if not architecture.constraints:
+      questions.append(
+        "Which non-negotiable constraints apply (authentication, "
+        "deployment, compliance, performance)?"
+      )
+    if not architecture.quality_attributes:
+      questions.append(
+        "Which quality attributes matter most and how will they be "
+        "measured?"
+      )
+    if not architecture.fitness_functions:
+      questions.append(
+        "Which automated checks should prove that the architecture "
+        "remains intact?"
+      )
+
+    if len(questions) < 2:
+      questions.extend(
+        [
+          "What is explicitly out of scope for the first delivery?",
+          "Which user roles, external integrations and data sources "
+          "must the system support?",
+        ]
+      )
+    return questions[:6]
+
+  def _render_greenfield_context(
+    self,
+    spec_id: str,
+    title: str,
+    description: str,
+    config: DevFlowConfig,
+    project: Project,
+    constitution: Constitution,
+    profiles: list[Profile],
+    questions: list[str],
+    architecture: ArchitectureManifest,
+    discovery: DiscoveryDocument | None = None,
+    discovery_digest: str | None = None,
+    directory: Path | None = None,
+  ) -> str:
+    target_directory = directory or (
+      config.specifications_path / f"{spec_id}-{slugify(description)}"
+    )
+    spec_path = target_directory / "spec.md"
+    lines = [
+      f"# DevFlow Greenfield Specification Context {spec_id}: {title}",
+      "",
+      "This file contains the declared architecture and requirements "
+      "gathered by DevFlow. There is no existing implementation to "
+      "analyze. Do not invent source files or claim that code exists.",
+      "",
+      "## Request",
+      "",
+      "> " + "\n> ".join(description.strip().splitlines()),
+      "",
+      "## Project",
+      "",
+      f"- Name: `{project.name}`",
+      f"- Type: `{project.project_type}`",
+      "- Project mode: `greenfield`",
+      "",
+      "## Constitution",
+      "",
+      "Apply these documents. Do not copy their contents into the "
+      "specification.",
+      "",
+    ]
+    lines.extend(self._constitution_table(constitution, profiles))
+    lines.extend(["", "## Declared Architecture", ""])
+    lines.extend(
+      self._architecture_context_lines(architecture, config.root)
+    )
+    discovery_lines = self._discovery_context_lines(
+      discovery,
+      discovery_digest,
+      config.specifications_path,
+      config.root,
+    )
+    if discovery_lines:
+      lines.extend(["", *discovery_lines])
+    lines.extend(["", "## Initial Open Questions", ""])
+    lines.extend(self._open_questions_lines(questions, discovery))
+
+    lines.extend(
+      [
+        "",
+        "## Required Output",
+        "",
+        f"Write the final specification to "
+        f"`{spec_path.relative_to(config.root).as_posix()}`.",
+        "",
+        "Use the eleven numbered sections defined by the Greenfield "
+        "prompt. Describe the target system in future tense. Use "
+        "`**FR-XXX:**` identifiers for functional requirements and "
+        "`- [ ] **AC-XXX:**` checklist items for acceptance criteria.",
+        "",
+        "End the document with `## Appendix A: Declared Architecture "
+        "Manifest` and include the manifest digest.",
+        "",
+      ]
+    )
+    return "\n".join(lines)
+
+  def _constitution_table(
+    self,
+    constitution: Constitution,
+    profiles: list[Profile],
+  ) -> list[str]:
+    lines = [
+      "| Document | Profile scope |",
+      "| --- | --- |",
+    ]
+    for document in constitution.documents:
+      scope = "project"
+      for profile in profiles:
+        if document.name in profile.constitution:
+          scope = (
+            "project" if profile.name == "base" else profile.name
+          )
+          break
+      lines.append(
+        f"| `.devflow/constitution/{document.name}` | {scope} |"
+      )
+    return lines
+
+  def _render_greenfield(
+    self,
+    spec_id: str,
+    title: str,
+    description: str,
+    config: DevFlowConfig,
+    project: Project,
+    constitution: Constitution,
+    profiles: list[Profile],
+    questions: list[str],
+    architecture: ArchitectureManifest,
+    discovery: DiscoveryDocument | None = None,
+    discovery_digest: str | None = None,
+    directory: Path | None = None,
+  ) -> str:
+    detected_profiles = [
+      profile for profile in profiles if profile.name != "base"
+    ]
+    profile_names = ", ".join(
+      profile.name for profile in detected_profiles
+    )
+    today = date.today().isoformat()
+    clauses = split_requirements(description)[:6]
+    target_directory = directory or (
+      config.specifications_path / f"{spec_id}-{slugify(description)}"
+    )
+    spec_path = target_directory / "spec.md"
+
+    lines = [
+      f"# Specification {spec_id}: {title}",
+      "",
+      "| Field | Value |",
+      "| --- | --- |",
+      "| Status | Draft |",
+      f"| Created | {today} |",
+      f"| Project | `{project.name}` |",
+      f"| Project type | `{project.project_type}` |",
+      "| Project mode | `greenfield` |",
+      f"| Profiles | {profile_names or 'none'} |",
+      f"| Specification | `{spec_path.relative_to(config.root).as_posix()}` |",
+      *self._architecture_header_rows(architecture, config.root),
+      *self._discovery_header_rows(
+        discovery,
+        discovery_digest,
+        config.specifications_path,
+        config.root,
+      ),
+      "",
+      "## 1. Request",
+      "",
+      "> " + "\n> ".join(description.strip().splitlines()),
+      "",
+      "## 2. Summary",
+      "",
+      "This specification defines the system to be built. It is "
+      "derived from the requested behavior and the declared "
+      "architecture manifest. No existing implementation is assumed "
+      "or inferred. The document must be reviewed and approved before "
+      "planning or implementation begins.",
+      "",
+      "## 3. Target Architecture",
+      "",
+      "### 3.1 Style and scope",
+      "",
+      f"- Architecture style: {architecture.style}",
+      f"- Manifest version: `{architecture.version}`",
+      f"- Manifest digest: `{architecture.digest}`",
+      "",
+      architecture.summary,
+      "",
+      "### 3.2 Declared modules",
+      "",
+      "| Module | Responsibility | Depends on |",
+      "| --- | --- | --- |",
+    ]
+    for module in architecture.modules:
+      depends = ", ".join(module.depends_on) or "-"
+      lines.append(
+        f"| {module.name} | {module.responsibility} | {depends} |"
+      )
+
+    lines.extend(["", "### 3.3 Declared layers", ""])
+    if architecture.layers:
+      lines.extend(
+        [
+          "| Layer | May depend on |",
+          "| --- | --- |",
+        ]
+      )
+      for layer in architecture.layers:
+        depends = ", ".join(layer.may_depend_on) or "-"
+        lines.append(f"| {layer.name} | {depends} |")
+    else:
+      lines.append(
+        "No layers were declared. The boundaries are defined by the "
+        "modules above and must be confirmed before implementation."
+      )
+
+    lines.extend(["", "### 3.4 Declared technology stack", ""])
+    lines.extend(self._declared_values_table(
+      architecture.stack,
+      "Area",
+      "Technologies",
+    ))
+
+    lines.extend(
+      [
+        "",
+        "## 4. Architecture Decisions and Risks",
+        "",
+        "### 4.1 Declared decisions",
+        "",
+        f"- Use {architecture.style} as the primary architectural style.",
+        "- Keep each module responsible for the scope declared above.",
+        "- Respect declared dependency directions between modules and "
+        "layers.",
+      ]
+    )
+    if architecture.stack:
+      stack_summary = "; ".join(
+        f"{key}: {', '.join(values)}"
+        for key, values in architecture.stack.items()
+      )
+      lines.append(f"- Target stack: {stack_summary}.")
+    if architecture.constraints:
+      lines.append(
+        "- Honor every constraint listed in section 6."
+      )
+
+    lines.extend(["", "### 4.2 Quality attributes", ""])
+    lines.extend(self._bullet_list(architecture.quality_attributes))
+    lines.extend(["", "### 4.3 Fitness functions", ""])
+    lines.extend(self._bullet_list(architecture.fitness_functions))
+    lines.extend(
+      [
+        "",
+        "### 4.4 Risks and reconciliation",
+        "",
+        "- The manifest records intended design, not implemented code.",
+        "- DevFlow validates structural consistency only. It does not "
+        "certify that this architecture is correct or sufficient.",
+        "- Contradictions between requirements and the manifest must be "
+        "resolved as open questions before implementation.",
+      ]
+    )
+    if architecture.warnings:
+      lines.append("- Manifest warnings:")
+      for warning in architecture.warnings:
+        lines.append(f"  - {warning}")
+
+    lines.extend(
+      [
+        "",
+        "## 5. Functional Requirements",
+        "",
+      ]
+    )
+    for index, clause in enumerate(clauses, start=1):
+      sentence = clause[0].upper() + clause[1:] if clause else clause
+      lines.append(
+        f"- **FR-{index:03d}:** The new system must support the "
+        f"following requested behavior: {sentence}."
+      )
+
+    next_requirement = len(clauses) + 1
+    lines.append(
+      f"- **FR-{next_requirement:03d}:** The implementation must honor "
+      "the declared module responsibilities and dependency directions."
+    )
+    next_requirement += 1
+    lines.append(
+      f"- **FR-{next_requirement:03d}:** The system must comply with "
+      "every document listed in the Constitution Applied section."
+    )
+
+    lines.extend(
+      [
+        "",
+        "## 6. Constraints and Dependencies",
+        "",
+        "### 6.1 Declared constraints",
+        "",
+      ]
+    )
+    lines.extend(self._declared_values_table(
+      architecture.constraints,
+      "Constraint",
+      "Values",
+    ))
+    lines.extend(
+      [
+        "",
+        "### 6.2 Technology stack",
+        "",
+      ]
+    )
+    lines.extend(self._declared_values_table(
+      architecture.stack,
+      "Area",
+      "Technologies",
+    ))
+    lines.extend(
+      [
+        "",
+        "### 6.3 Quality gates",
+        "",
+        "The following fitness functions should become automated checks "
+        "during planning and implementation:",
+        "",
+      ]
+    )
+    lines.extend(self._bullet_list(architecture.fitness_functions))
+    lines.extend(
+      [
+        "",
+        "No existing third-party dependency is assumed. New "
+        "dependencies must be justified by a requirement and reviewed.",
+        "",
+        "## 7. Open Questions",
+        "",
+      ]
+    )
+    lines.extend(self._open_questions_lines(questions, discovery))
+
+    lines.extend(
+      [
+        "",
+        "## 8. Acceptance Criteria",
+        "",
+      ]
+    )
+    criteria: list[str] = []
+    for index, _clause in enumerate(clauses, start=1):
+      criteria.append(
+        f"The behavior described by FR-{index:03d} is demonstrable "
+        "and verified."
+      )
+    criteria.extend(
+      [
+        "Declared module boundaries and dependency directions are "
+        "verified by review or automated checks.",
+        "The system uses only the declared stack and honors the "
+        "declared constraints.",
+        "Every declared fitness function has an automated check or a "
+        "documented manual verification.",
+        "Automated tests cover the new behavior, relevant edge cases "
+        "and failure paths.",
+        "The implementation complies with the referenced constitution "
+        "documents.",
+        "Documentation and configuration are created for setup, "
+        "deployment and integrations.",
+      ]
+    )
+    for index, criterion in enumerate(criteria, start=1):
+      lines.append(
+        f"- [ ] **AC-{index:03d}:** {criterion}"
+      )
+
+    lines.extend(
+      [
+        "",
+        "## 9. Constitution Applied",
+        "",
+      ]
+    )
+    lines.extend(self._constitution_table(constitution, profiles))
+    lines.extend(
+      [
+        "",
+        "Technology-specific rules apply only to the profiles listed "
+        "above.",
+        "",
+        "## 10. Out of Scope",
+        "",
+        "- Generating application code or project scaffolding in this "
+        "stage.",
+        "- Planning, implementation and review workflows.",
+        "- Guaranteeing that the declared architecture is correct.",
+        "- Inventing existing code, files or dependencies that were not "
+        "declared.",
+        "",
+        "## 11. Approval",
+        "",
+        "- [ ] The request and functional requirements are complete.",
+        "- [ ] Open questions are resolved or explicitly accepted.",
+        "- [ ] Acceptance criteria are agreed.",
+        "- [ ] The declared architecture manifest digest is correct.",
+        *self._discovery_approval_lines(discovery),
+        "- [ ] The specification is approved for planning.",
+        "",
+        "---",
+        "",
+        "Generated by DevFlow. This document does not implement the "
+        "system and must be reviewed by a developer.",
+        "",
+      ]
+    )
+    lines.append(architecture.render_appendix(config.root))
+    return "\n".join(lines)
+
+  def _render_context(
+    self,
+    spec_id: str,
+    title: str,
+    description: str,
+    analysis: ImpactAnalysis,
+    config: DevFlowConfig,
+    project: Project,
+    constitution: Constitution,
+    profiles: list[Profile],
+    questions: list[str],
+    project_mode: str = "existing",
+    architecture: ArchitectureManifest | None = None,
+    discovery: DiscoveryDocument | None = None,
+    discovery_digest: str | None = None,
+    directory: Path | None = None,
+  ) -> str:
+    detected_profiles = [
+      profile for profile in profiles if profile.name != "base"
+    ]
+    profile_names = ", ".join(
+      profile.name for profile in detected_profiles
+    )
+    target_directory = directory or (
+      config.specifications_path / f"{spec_id}-{slugify(description)}"
+    )
+    spec_path = target_directory / "spec.md"
+    lines = [
+      f"# DevFlow Specification Context {spec_id}: {title}",
+      "",
+      "This file contains deterministic evidence gathered by DevFlow. "
+      "It is not the specification. Use it to understand the project, "
+      "then write the specification to the target path.",
+      "",
+      "## Request",
+      "",
+      "> " + "\n> ".join(description.strip().splitlines()),
+      "",
+      "## Project",
+      "",
+      f"- Name: `{project.name}`",
+      f"- Type: `{project.project_type}`",
+      f"- Project mode: `{project_mode}`",
+      f"- Languages: {', '.join(project.languages) or 'not detected'}",
+      f"- Frameworks: {', '.join(project.frameworks) or 'not detected'}",
+      f"- Databases: {', '.join(project.databases) or 'not detected'}",
+      f"- Profiles: {profile_names or 'none'}",
+      f"- Source files: {len(project.source_files)}",
+      f"- Manifests: {', '.join(project.manifests) or 'none'}",
+      "",
+      "## Constitution",
+      "",
+      "Apply these documents. Do not copy their contents into the "
+      "specification.",
+      "",
+      "| Document | Profile scope |",
+      "| --- | --- |",
+    ]
+
+    for document in constitution.documents:
+      scope = "project"
+      for profile in profiles:
+        if document.name in profile.constitution:
+          scope = (
+            "project" if profile.name == "base" else profile.name
+          )
+          break
+      lines.append(
+        f"| `.devflow/constitution/{document.name}` | {scope} |"
+      )
+
+    if architecture is not None:
+      lines.extend(
+        [
+          "",
+          "## Declared Architecture",
+          "",
+          *self._architecture_context_lines(
+            architecture,
+            config.root,
+          ),
+        ]
+      )
+
+    discovery_lines = self._discovery_context_lines(
+      discovery,
+      discovery_digest,
+      config.specifications_path,
+      config.root,
+    )
+    if discovery_lines:
+      lines.extend(["", *discovery_lines])
+
+    lines.extend(
+      [
+        "",
+        "## Static Analysis",
+        "",
+        "- Request keywords: "
+        + (
+          ", ".join(f"`{word}`" for word in analysis.keywords)
+          or "none"
+        ),
+        f"- Scanned text files: {analysis.scanned_files}",
+        f"- Existing tests detected: "
+        f"{'yes' if analysis.has_tests else 'no'}",
+        "",
+        "## Relevant Existing Code",
+        "",
+      ]
+    )
+
+    if analysis.references:
+      lines.extend(
+        [
+          "The following files matched the request. They are evidence, "
+          "not a complete impact map. Inspect them and related files "
+          "before writing requirements.",
+          "",
+          "| Area | File | Matched terms | Lines |",
+          "| --- | --- | --- | --- |",
+        ]
+      )
+      for reference in analysis.references:
+        positions = (
+          ", ".join(str(line) for line in reference.lines) or "-"
+        )
+        lines.append(
+          f"| {reference.category} | `{reference.path}` | "
+          f"{', '.join(reference.matches)} | {positions} |"
+        )
+    else:
+      lines.extend(
+        [
+          "No directly related source files were found. The feature may "
+          "be new, the project may use different terminology, or the "
+          "request may need more detail.",
+          "",
+        ]
+      )
+
+    lines.extend(
+      [
+        "",
+        "## Dependencies",
+        "",
+        (
+          "Declared dependencies found in the relevant files: "
+          + ", ".join(
+            f"`{dependency}`"
+            for dependency in analysis.external_dependencies
+          )
+          if analysis.external_dependencies
+          else "No existing third-party dependency was identified in "
+          "the matched code. Confirm whether the change requires one."
+        ),
+        "",
+        "## Initial Open Questions",
+        "",
+      ]
+    )
+    lines.extend(self._open_questions_lines(questions, discovery))
+
+    lines.extend(
+      [
+        "",
+        "## Required Output",
+        "",
+        f"Write the final specification to `{spec_path.relative_to(config.root).as_posix()}`.",
+        "",
+        "Use the eleven numbered sections defined by the DevFlow "
+        "specification prompt. Use `**FR-XXX:**` identifiers for "
+        "functional requirements and `- [ ] **AC-XXX:**` checklist "
+        "items for acceptance criteria.",
+        "",
+        "The specification must remain valid if the project later "
+        "switches to a different agent harness.",
+        "",
+      ]
+    )
+    return "\n".join(lines)
+
+  def _render(
+    self,
+    spec_id: str,
+    title: str,
+    description: str,
+    analysis: ImpactAnalysis,
+    config: DevFlowConfig,
+    project: Project,
+    constitution: Constitution,
+    profiles: list[Profile],
+    questions: list[str],
+    project_mode: str = "existing",
+    architecture: ArchitectureManifest | None = None,
+    discovery: DiscoveryDocument | None = None,
+    discovery_digest: str | None = None,
+    directory: Path | None = None,
+  ) -> str:
+    detected_profiles = [
+      profile for profile in profiles if profile.name != "base"
+    ]
+    profile_names = ", ".join(
+      profile.name for profile in detected_profiles
+    )
+    today = date.today().isoformat()
+    clauses = split_requirements(description)[:6]
+    target_directory = directory or (
+      config.specifications_path / f"{spec_id}-{slugify(description)}"
+    )
+    spec_path = target_directory / "spec.md"
+
+    lines = [
+      f"# Specification {spec_id}: {title}",
+      "",
+      "| Field | Value |",
+      "| --- | --- |",
+      "| Status | Draft |",
+      f"| Created | {today} |",
+      f"| Project | `{project.name}` |",
+      f"| Project type | `{project.project_type}` |",
+      f"| Project mode | `{project_mode}` |",
+      f"| Profiles | {profile_names or 'none'} |",
+      f"| Specification | `{spec_path.relative_to(config.root).as_posix()}` |",
+      *self._architecture_header_rows(architecture, config.root),
+      *self._discovery_header_rows(
+        discovery,
+        discovery_digest,
+        config.specifications_path,
+        config.root,
+      ),
+      "",
+      "## 1. Request",
+      "",
+      "> " + "\n> ".join(description.strip().splitlines()),
+      "",
+      "## 2. Summary",
+      "",
+      "This specification describes the requested change and its "
+      "expected behavior. It was generated from static inspection "
+      "of the existing project and must be reviewed before "
+      "implementation.",
+      "",
+      "## 3. Current Project State",
+      "",
+      "### 3.1 Detected stack",
+      "",
+      "| Area | Detected values |",
+      "| --- | --- |",
+      "| Languages | "
+      + (", ".join(project.languages) or "not detected")
+      + " |",
+      "| Frameworks | "
+      + (", ".join(project.frameworks) or "not detected")
+      + " |",
+      "| Databases | "
+      + (", ".join(project.databases) or "not detected")
+      + " |",
+      "| Profiles | " + (profile_names or "base only") + " |",
+      "| Source files | " + str(len(project.source_files)) + " |",
+      "",
+      "### 3.2 Relevant existing code",
+      "",
+    ]
+
+    if analysis.references:
+      lines.extend(
+        [
+          "The following files matched the request. They are "
+          "evidence for impact analysis, not a guarantee that every "
+          "affected file was found.",
+          "",
+          "| Area | File | Matched terms | Lines |",
+          "| --- | --- | --- | --- |",
+        ]
+      )
+      for reference in analysis.references:
+        matched = ", ".join(reference.matches)
+        positions = (
+          ", ".join(str(line) for line in reference.lines)
+          or "-"
+        )
+        lines.append(
+          f"| {reference.category} | `{reference.path}` | "
+          f"{matched} | {positions} |"
+        )
+    else:
+      lines.extend(
+        [
+          "No directly related source files were found for the "
+          "request keywords. This may mean that the feature is new, "
+          "that different terminology is used in the codebase, or "
+          "that the request needs more detail.",
+          "",
+          "Request keywords: "
+          + (", ".join(f"`{word}`" for word in analysis.keywords)
+             or "none"),
+        ]
+      )
+
+    lines.extend(
+      [
+        "",
+        f"Analysis scanned {analysis.scanned_files} text files.",
+        "",
+        "## 4. Impact Analysis",
+        "",
+      ]
+    )
+
+    if analysis.categories:
+      lines.extend(
+        [
+          "| Area | Potentially affected files |",
+          "| --- | --- |",
+        ]
+      )
+      for category, references in analysis.categories.items():
+        files = ", ".join(
+          f"`{reference.path}`" for reference in references[:6]
+        )
+        lines.append(f"| {category} | {files} |")
+    else:
+      lines.append(
+        "No affected areas can be confirmed from the current "
+        "codebase. Resolve the open questions before planning."
+      )
+
+    lines.extend(
+      [
+        "",
+        "### 4.1 Impact notes",
+        "",
+        "- Existing behavior in the identified areas must be "
+        "preserved unless this specification explicitly changes it.",
+        "- Public interfaces, background processes, integrations "
+        "and data flows connected to these files require review.",
+        "- The implementation must remain within the detected "
+        "project profiles.",
+        "",
+        "## 5. Functional Requirements",
+        "",
+      ]
+    )
+
+    for index, clause in enumerate(clauses, start=1):
+      sentence = clause[0].upper() + clause[1:] if clause else clause
+      lines.append(
+        f"- **FR-{index:03d}:** The system must support the "
+        f"following requested behavior: {sentence}."
+      )
+
+    next_requirement = len(clauses) + 1
+    if analysis.references:
+      lines.append(
+        f"- **FR-{next_requirement:03d}:** Existing behavior in the "
+        "affected components must remain compatible unless a "
+        "requirement above explicitly changes it."
+      )
+      next_requirement += 1
+
+    lines.extend(
+      [
+        f"- **FR-{next_requirement:03d}:** The change must comply "
+        "with every document listed in the Constitution Applied "
+        "section.",
+        "",
+        "## 6. Constraints and Dependencies",
+        "",
+        "### 6.1 Architectural and project constraints",
+        "",
+        "- Follow the project constitution. Guidelines are "
+        "referenced, not duplicated, in this specification.",
+        "- Respect existing module boundaries and reuse existing "
+        "components where possible.",
+        "- Do not introduce dependencies without an explicit "
+        "requirement and review.",
+      ]
+    )
+
+    if analysis.external_dependencies:
+      dependencies = ", ".join(
+        f"`{dependency}`"
+        for dependency in analysis.external_dependencies
+      )
+      lines.extend(
+        [
+          "",
+          "### 6.2 Existing dependencies used by affected code",
+          "",
+          f"The following declared dependencies appear in the "
+          f"relevant files: {dependencies}.",
+        ]
+      )
+    else:
+      lines.extend(
+        [
+          "",
+          "### 6.2 Dependencies",
+          "",
+          "No existing third-party dependency was identified in "
+          "the matched code. Confirm whether the change requires a "
+          "new dependency.",
+        ]
+      )
+
+    if analysis.has_tests:
+      lines.extend(
+        [
+          "",
+          "Test files were detected in the project. Reuse the "
+          "existing test structure, fixtures and factories.",
+        ]
+      )
+    else:
+      lines.extend(
+        [
+          "",
+          "No test files were detected. The testing location and "
+          "strategy must be confirmed.",
+        ]
+      )
+
+    lines.extend(
+      [
+        "",
+        "## 7. Open Questions",
+        "",
+      ]
+    )
+    lines.extend(self._open_questions_lines(questions, discovery))
+
+    lines.extend(
+      [
+        "",
+        "## 8. Acceptance Criteria",
+        "",
+      ]
+    )
+
+    criteria: list[str] = []
+    for index, _clause in enumerate(clauses, start=1):
+      criteria.append(
+        f"The behavior described by FR-{index:03d} is "
+        "demonstrable and verified."
+      )
+
+    if analysis.references:
+      criteria.append(
+        "Existing related flows and tests continue to pass without "
+        "unexpected regressions."
+      )
+
+    criteria.extend(
+      [
+        "Automated tests cover the new behavior, relevant edge "
+        "cases and failure paths.",
+        "The implementation complies with the referenced "
+        "constitution documents.",
+        "Documentation and configuration are updated when public "
+        "behavior, setup or integrations change.",
+      ]
+    )
+
+    for index, criterion in enumerate(criteria, start=1):
+      lines.append(
+        f"- [ ] **AC-{index:03d}:** {criterion}"
+      )
+
+    lines.extend(
+      [
+        "",
+        "## 9. Constitution Applied",
+        "",
+        "| Document | Profile scope |",
+        "| --- | --- |",
+      ]
+    )
+
+    for document in constitution.documents:
+      scope = "project"
+      for profile in profiles:
+        if document.name in profile.constitution:
+          scope = (
+            "project" if profile.name == "base" else profile.name
+          )
+          break
+      lines.append(
+        f"| `.devflow/constitution/{document.name}` | {scope} |"
+      )
+
+    lines.extend(
+      [
+        "",
+        "Technology-specific rules apply only to the profiles listed "
+        "above.",
+        "",
+        "## 10. Out of Scope",
+        "",
+        "No out-of-scope items have been confirmed. Resolve the open "
+        "questions before implementation.",
+        "",
+        "## 11. Approval",
+        "",
+        "- [ ] The request and functional requirements are complete.",
+        "- [ ] Open questions are resolved or explicitly accepted.",
+        "- [ ] Acceptance criteria are agreed.",
+        *self._discovery_approval_lines(discovery),
+        "- [ ] The specification is approved for planning.",
+        "",
+        "---",
+        "",
+        "Generated by DevFlow. This document does not implement the "
+        "change and must be reviewed by a developer.",
+        "",
+      ]
+    )
+
+    if architecture is not None:
+      lines.extend(
+        [
+          architecture.render_appendix(config.root),
+        ]
+      )
+
+    return "\n".join(lines)