devflow-toolkit 0.3.0__py3-none-any.whl

devflow/core/discovery.py

@@ -0,0 +1,1304 @@
+"""Persistent discovery and clarification for specification requests.
+
+Discovery is deliberately separate from specification. It records the
+questions that change scope, the answers supplied by a human, and the
+technical assumptions proposed by DevFlow. A specification may only be
+generated when every blocking question is answered and every proposed
+assumption has been explicitly accepted.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from devflow.core.architecture import ArchitectureManifest
+from devflow.core.artifacts.store import ArtifactStore
+from devflow.core.clock import Clock, SystemClock, format_timestamp
+from devflow.models.project import PROJECT_MODES, Project
+
+DISCOVERY_FILENAME = "discovery.yaml"
+MAX_DISCOVERY_BYTES = 512_000
+MAX_QUESTIONS = 100
+MAX_ASSUMPTIONS = 100
+MAX_TEXT_LENGTH = 4_000
+MAX_OPTIONS = 10
+
+DISCOVERY_PENDING = "pending"
+DISCOVERY_AWAITING = "awaiting_clarification"
+DISCOVERY_COMPLETE = "complete"
+DISCOVERY_STATUSES = (
+  DISCOVERY_PENDING,
+  DISCOVERY_AWAITING,
+  DISCOVERY_COMPLETE,
+)
+
+QUESTION_PENDING = "pending"
+QUESTION_ANSWERED = "answered"
+QUESTION_STATUSES = (QUESTION_PENDING, QUESTION_ANSWERED)
+
+QUESTION_CATEGORIES = (
+  "functional_scope",
+  "user_behavior",
+  "data_persistence",
+  "security_authentication",
+  "external_integration",
+  "architecture_boundary",
+  "dependencies",
+  "deployment",
+)
+
+ASSUMPTION_PENDING = "pending_acceptance"
+ASSUMPTION_ACCEPTED = "accepted"
+ASSUMPTION_STATUSES = (ASSUMPTION_PENDING, ASSUMPTION_ACCEPTED)
+ASSUMPTION_SOURCES = ("agent_default", "human", "existing_convention")
+
+_QUESTION_ID = re.compile(r"^Q\d{1,3}$")
+_ASSUMPTION_ID = re.compile(r"^A\d{1,3}$")
+_SHA256 = re.compile(r"^sha256:[0-9a-f]{64}$")
+
+_STOPWORDS = {
+  "a",
+  "al",
+  "algo",
+  "and",
+  "con",
+  "de",
+  "del",
+  "el",
+  "en",
+  "for",
+  "from",
+  "in",
+  "la",
+  "las",
+  "lo",
+  "los",
+  "my",
+  "of",
+  "on",
+  "para",
+  "por",
+  "que",
+  "se",
+  "the",
+  "to",
+  "un",
+  "una",
+  "with",
+  "y",
+}
+
+_VAGUE_TERMS = {
+  "better",
+  "improve",
+  "improvement",
+  "mejor",
+  "mejora",
+  "mejorar",
+  "optimize",
+  "optimizacion",
+  "optimizar",
+  "optimization",
+  "robust",
+  "robusto",
+  "scalable",
+  "escalable",
+  "support",
+  "soportar",
+  "soporte",
+}
+
+_CONTACT_WORDS = {"contact", "contacto", "contactenos"}
+_FORM_WORDS = {"form", "formulario"}
+_PAGE_WORDS = {
+  "page",
+  "pagina",
+  "template",
+  "plantilla",
+  "view",
+  "vista",
+}
+_SUBMISSION_DECISIONS = {
+  "store",
+  "stored",
+  "save",
+  "saved",
+  "persist",
+  "persisted",
+  "database",
+  "db",
+  "email",
+  "correo",
+  "smtp",
+  "send_mail",
+  "confirmation",
+  "confirmacion",
+  "flash",
+  "almacenar",
+  "guardar",
+}
+_SUBMISSION_PHRASES = {
+  "no persistence",
+  "sin persistencia",
+  "only show",
+  "solo mostrar",
+  "confirmation message",
+  "mensaje de confirmacion",
+}
+_NO_PERSISTENCE_PHRASES = {
+  "no persistence",
+  "sin persistencia",
+  "do not persist",
+  "no guardar",
+  "only show",
+  "solo mostrar",
+}
+
+_AUTH_WORDS = {
+  "auth",
+  "authentication",
+  "autenticacion",
+  "authorization",
+  "autorizacion",
+  "contrasena",
+  "jwt",
+  "login",
+  "oauth",
+  "password",
+  "permission",
+  "permiso",
+  "session",
+  "sesion",
+  "token",
+}
+_AUTH_INTEGRATION_WORDS = {
+  "api",
+  "bearer",
+  "cookie",
+  "endpoint",
+  "html",
+  "rest",
+  "session",
+  "sesion",
+  "view",
+  "vista",
+}
+_DATA_WORDS = {
+  "campo",
+  "column",
+  "columna",
+  "data",
+  "database",
+  "datos",
+  "db",
+  "field",
+  "migration",
+  "migracion",
+  "model",
+  "modelo",
+  "persistencia",
+  "persistence",
+  "schema",
+  "tabla",
+  "table",
+}
+_PERSISTENCE_DECISIONS = {
+  "archivo",
+  "database",
+  "db",
+  "file",
+  "mongodb",
+  "mysql",
+  "postgres",
+  "postgresql",
+  "redis",
+  "sqlite",
+}
+_INTEGRATION_PHRASES = {
+  "send email",
+  "enviar correo",
+  "sendgrid",
+  "mailgun",
+  "smtp",
+  "stripe",
+  "webhook",
+  "third party",
+  "integrate with",
+  "integration with",
+  "integrar con",
+  "payment provider",
+  "pasarela de pago",
+}
+_PROVIDER_WORDS = {
+  "aws",
+  "gcp",
+  "github",
+  "google",
+  "mailgun",
+  "oauth",
+  "sendgrid",
+  "slack",
+  "smtp",
+  "stripe",
+  "twilio",
+}
+_DEPLOYMENT_WORDS = {
+  "aws",
+  "azure",
+  "cd",
+  "ci",
+  "deploy",
+  "deployment",
+  "desplegar",
+  "despliegue",
+  "docker",
+  "gcp",
+  "heroku",
+  "kubernetes",
+  "produccion",
+  "production",
+  "vercel",
+}
+_DEPLOYMENT_TARGETS = {
+  "aws",
+  "azure",
+  "docker",
+  "gcp",
+  "heroku",
+  "kubernetes",
+  "vercel",
+}
+_ARCHITECTURE_WORDS = {
+  "architecture",
+  "arquitectura",
+  "boundaries",
+  "boundary",
+  "capa",
+  "layer",
+  "microservice",
+  "microservicio",
+  "modulo",
+  "module",
+  "refactor",
+}
+
+
+class DiscoveryError(Exception):
+  """Raised when discovery data is missing or malformed."""
+
+
+class DiscoveryIncompleteError(DiscoveryError):
+  """Raised when a workflow requires a complete discovery."""
+
+
+@dataclass(frozen=True)
+class DiscoveryQuestion:
+  """One decision that may block specification generation."""
+
+  id: str
+  category: str
+  question: str
+  reason: str
+  blocking: bool
+  status: str = QUESTION_PENDING
+  options: tuple[str, ...] = ()
+  answer: str | None = None
+  answered_by: str | None = None
+  answered_at: str | None = None
+
+  @property
+  def is_answered(self) -> bool:
+    return self.status == QUESTION_ANSWERED and bool(self.answer)
+
+  def to_dict(self) -> dict[str, Any]:
+    return {
+      "id": self.id,
+      "category": self.category,
+      "question": self.question,
+      "reason": self.reason,
+      "blocking": self.blocking,
+      "status": self.status,
+      "options": list(self.options),
+      "answer": self.answer,
+      "answered_by": self.answered_by,
+      "answered_at": self.answered_at,
+    }
+
+
+@dataclass(frozen=True)
+class DiscoveryAssumption:
+  """A technical assumption that needs explicit human acceptance."""
+
+  id: str
+  value: str
+  reason: str
+  source: str = "agent_default"
+  status: str = ASSUMPTION_PENDING
+  question_id: str | None = None
+  accepted_by: str | None = None
+  accepted_at: str | None = None
+
+  @property
+  def is_accepted(self) -> bool:
+    return self.status == ASSUMPTION_ACCEPTED
+
+  def to_dict(self) -> dict[str, Any]:
+    return {
+      "id": self.id,
+      "question_id": self.question_id,
+      "value": self.value,
+      "reason": self.reason,
+      "source": self.source,
+      "status": self.status,
+      "accepted_by": self.accepted_by,
+      "accepted_at": self.accepted_at,
+    }
+
+
+@dataclass(frozen=True)
+class DiscoveryDocument:
+  """Persistent discovery record for one change."""
+
+  version: int
+  spec_id: str
+  change: str
+  request: str
+  project_mode: str
+  status: str
+  created_at: str
+  updated_at: str
+  questions: tuple[DiscoveryQuestion, ...] = ()
+  assumptions: tuple[DiscoveryAssumption, ...] = ()
+
+  @property
+  def pending_blocking(self) -> tuple[DiscoveryQuestion, ...]:
+    return tuple(
+      question
+      for question in self.questions
+      if question.blocking and not question.is_answered
+    )
+
+  @property
+  def pending_assumptions(
+    self,
+  ) -> tuple[DiscoveryAssumption, ...]:
+    return tuple(
+      assumption
+      for assumption in self.assumptions
+      if not assumption.is_accepted
+    )
+
+  @property
+  def derived_status(self) -> str:
+    if self.pending_blocking or self.pending_assumptions:
+      return DISCOVERY_AWAITING
+    if self.status == DISCOVERY_PENDING:
+      return DISCOVERY_PENDING
+    return DISCOVERY_COMPLETE
+
+  @property
+  def is_complete(self) -> bool:
+    return self.derived_status == DISCOVERY_COMPLETE
+
+  def blockers(self) -> tuple[str, ...]:
+    messages: list[str] = []
+    for question in self.pending_blocking:
+      messages.append(f"{question.id}: {question.question}")
+    for assumption in self.pending_assumptions:
+      messages.append(
+        f"{assumption.id}: proposed assumption requires acceptance: "
+        f"{assumption.value}"
+      )
+    if not messages and self.status == DISCOVERY_PENDING:
+      messages.append("Discovery has not been completed.")
+    return tuple(messages)
+
+  def decisions(self) -> tuple[str, ...]:
+    decisions: list[str] = []
+    for question in self.questions:
+      if question.is_answered:
+        decisions.append(
+          f"{question.id} ({question.category}): "
+          f"{question.question} -> {question.answer}"
+        )
+    for assumption in self.assumptions:
+      if assumption.is_accepted:
+        decisions.append(
+          f"{assumption.id} (accepted by "
+          f"{assumption.accepted_by}): {assumption.value}"
+        )
+    return tuple(decisions)
+
+  def to_dict(self) -> dict[str, Any]:
+    return {
+      "version": self.version,
+      "spec_id": self.spec_id,
+      "change": self.change,
+      "request": self.request,
+      "project_mode": self.project_mode,
+      "status": self.status,
+      "created_at": self.created_at,
+      "updated_at": self.updated_at,
+      "questions": [
+        question.to_dict() for question in self.questions
+      ],
+      "assumptions": [
+        assumption.to_dict() for assumption in self.assumptions
+      ],
+    }
+
+
+class DiscoveryManager:
+  """Read, validate and write discovery records safely."""
+
+  def __init__(
+    self,
+    root: Path,
+    *,
+    clock: Clock | None = None,
+  ) -> None:
+    self.root = root.resolve()
+    self.store = ArtifactStore(self.root)
+    self.clock = clock or SystemClock()
+
+  def path(self, directory: Path) -> Path:
+    """Return the discovery path for a change directory."""
+    return directory / DISCOVERY_FILENAME
+
+  def exists(self, directory: Path) -> bool:
+    """Return whether a discovery file exists for a change."""
+    path = self.path(directory)
+    return path.exists() or path.is_symlink()
+
+  def load(
+    self,
+    directory: Path,
+    *,
+    required: bool = False,
+  ) -> DiscoveryDocument | None:
+    """Load and validate discovery data for a change."""
+    path = self.path(directory)
+    if path.is_symlink():
+      msg = (
+        "Discovery file must not be a symbolic link: "
+        f"{path}"
+      )
+      raise DiscoveryError(msg)
+    if not path.is_file():
+      if required:
+        msg = f"Discovery file does not exist: {path}"
+        raise DiscoveryError(msg)
+      return None
+    try:
+      size = path.stat().st_size
+    except OSError as error:
+      msg = f"Could not inspect discovery file: {path}"
+      raise DiscoveryError(msg) from error
+    if size > MAX_DISCOVERY_BYTES:
+      msg = (
+        "Discovery file is too large: "
+        f"{size} bytes (max {MAX_DISCOVERY_BYTES})."
+      )
+      raise DiscoveryError(msg)
+    try:
+      content = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as error:
+      msg = f"Could not read discovery file: {path}"
+      raise DiscoveryError(msg) from error
+    try:
+      data = yaml.safe_load(content)
+    except yaml.YAMLError as error:
+      msg = f"Invalid YAML in discovery file: {path}"
+      raise DiscoveryError(msg) from error
+    document = self._parse(data, directory)
+    if (
+      document.status == DISCOVERY_COMPLETE
+      and (
+        document.pending_blocking
+        or document.pending_assumptions
+      )
+    ):
+      msg = (
+        "Discovery is marked complete but still has pending "
+        "blocking questions or assumptions."
+      )
+      raise DiscoveryError(msg)
+    return replace(document, status=document.derived_status)
+
+  def write(
+    self,
+    directory: Path,
+    document: DiscoveryDocument,
+  ) -> tuple[Path, str]:
+    """Write discovery data atomically and return its digest."""
+    now = format_timestamp(self.clock.now())
+    normalized = replace(
+      document,
+      status=document.derived_status,
+      updated_at=now,
+    )
+    path = self.path(directory)
+    if path.is_symlink():
+      msg = (
+        "Discovery file must not be a symbolic link: "
+        f"{path}"
+      )
+      raise DiscoveryError(msg)
+    self.store.write(path, self._dump(normalized))
+    return path, self.store.digest_file(path)
+
+  def answer(
+    self,
+    document: DiscoveryDocument,
+    question_id: str,
+    answer: str,
+    *,
+    by: str = "user",
+    at: str | None = None,
+  ) -> DiscoveryDocument:
+    """Return discovery with one question answered explicitly."""
+    value = answer.strip()
+    if not value:
+      msg = "A discovery answer cannot be empty."
+      raise DiscoveryError(msg)
+    timestamp = at or format_timestamp(self.clock.now())
+    found = False
+    questions: list[DiscoveryQuestion] = []
+    for question in document.questions:
+      if question.id != question_id:
+        questions.append(question)
+        continue
+      found = True
+      questions.append(
+        replace(
+          question,
+          status=QUESTION_ANSWERED,
+          answer=value,
+          answered_by=by,
+          answered_at=timestamp,
+        )
+      )
+    if not found:
+      msg = f"Unknown discovery question: {question_id}"
+      raise DiscoveryError(msg)
+    updated = replace(
+      document,
+      questions=tuple(questions),
+      updated_at=timestamp,
+    )
+    return replace(updated, status=updated.derived_status)
+
+  def accept(
+    self,
+    document: DiscoveryDocument,
+    assumption_id: str,
+    *,
+    by: str = "user",
+    at: str | None = None,
+  ) -> DiscoveryDocument:
+    """Return discovery with one assumption explicitly accepted."""
+    timestamp = at or format_timestamp(self.clock.now())
+    found = False
+    assumptions: list[DiscoveryAssumption] = []
+    for assumption in document.assumptions:
+      if assumption.id != assumption_id:
+        assumptions.append(assumption)
+        continue
+      found = True
+      assumptions.append(
+        replace(
+          assumption,
+          status=ASSUMPTION_ACCEPTED,
+          accepted_by=by,
+          accepted_at=timestamp,
+        )
+      )
+    if not found:
+      msg = f"Unknown discovery assumption: {assumption_id}"
+      raise DiscoveryError(msg)
+    updated = replace(
+      document,
+      assumptions=tuple(assumptions),
+      updated_at=timestamp,
+    )
+    return replace(updated, status=updated.derived_status)
+
+  def _dump(self, document: DiscoveryDocument) -> str:
+    return yaml.safe_dump(
+      document.to_dict(),
+      sort_keys=False,
+      allow_unicode=True,
+      width=1000,
+    )
+
+  def _parse(
+    self,
+    data: object,
+    directory: Path,
+  ) -> DiscoveryDocument:
+    mapping = _mapping(data, "discovery")
+    version = _integer(mapping.get("version"), "version")
+    if version != 1:
+      msg = "Only discovery version 1 is supported."
+      raise DiscoveryError(msg)
+    spec_id = _text(mapping.get("spec_id"), "spec_id")
+    change = _text(mapping.get("change"), "change")
+    request = _text(mapping.get("request"), "request")
+    project_mode = _text(
+      mapping.get("project_mode"),
+      "project_mode",
+    ).lower()
+    if project_mode not in PROJECT_MODES:
+      msg = (
+        "project_mode must be one of: "
+        + ", ".join(PROJECT_MODES)
+        + "."
+      )
+      raise DiscoveryError(msg)
+    status = _text(mapping.get("status"), "status")
+    if status not in DISCOVERY_STATUSES:
+      msg = (
+        "status must be one of: "
+        + ", ".join(DISCOVERY_STATUSES)
+        + "."
+      )
+      raise DiscoveryError(msg)
+    created_at = _text(mapping.get("created_at"), "created_at")
+    updated_at = _text(mapping.get("updated_at"), "updated_at")
+
+    if change != directory.name:
+      msg = (
+        f"Discovery change '{change}' does not match directory "
+        f"'{directory.name}'."
+      )
+      raise DiscoveryError(msg)
+    if not change.startswith(f"{spec_id}-"):
+      msg = (
+        f"Discovery spec_id '{spec_id}' does not match change "
+        f"'{change}'."
+      )
+      raise DiscoveryError(msg)
+
+    questions_data = _list(mapping.get("questions"), "questions")
+    assumptions_data = _list(
+      mapping.get("assumptions"),
+      "assumptions",
+    )
+    if len(questions_data) > MAX_QUESTIONS:
+      msg = f"At most {MAX_QUESTIONS} discovery questions are allowed."
+      raise DiscoveryError(msg)
+    if len(assumptions_data) > MAX_ASSUMPTIONS:
+      msg = (
+        f"At most {MAX_ASSUMPTIONS} discovery assumptions are allowed."
+      )
+      raise DiscoveryError(msg)
+
+    questions = tuple(
+      self._question(item, index)
+      for index, item in enumerate(questions_data, start=1)
+    )
+    question_ids = {question.id for question in questions}
+    if len(question_ids) != len(questions):
+      msg = "Discovery question ids must be unique."
+      raise DiscoveryError(msg)
+
+    assumptions = tuple(
+      self._assumption(item, index, question_ids)
+      for index, item in enumerate(assumptions_data, start=1)
+    )
+    assumption_ids = {
+      assumption.id for assumption in assumptions
+    }
+    if len(assumption_ids) != len(assumptions):
+      msg = "Discovery assumption ids must be unique."
+      raise DiscoveryError(msg)
+
+    document = DiscoveryDocument(
+      version=version,
+      spec_id=spec_id,
+      change=change,
+      request=request,
+      project_mode=project_mode,
+      status=status,
+      created_at=created_at,
+      updated_at=updated_at,
+      questions=questions,
+      assumptions=assumptions,
+    )
+    if (
+      document.status == DISCOVERY_COMPLETE
+      and (
+        document.pending_blocking
+        or document.pending_assumptions
+      )
+    ):
+      msg = (
+        "Discovery is marked complete but still has pending "
+        "blocking questions or assumptions."
+      )
+      raise DiscoveryError(msg)
+    return document
+
+  def _question(
+    self,
+    data: object,
+    index: int,
+  ) -> DiscoveryQuestion:
+    mapping = _mapping(data, f"questions[{index}]")
+    identifier = _text(mapping.get("id"), "question id")
+    if not _QUESTION_ID.fullmatch(identifier):
+      msg = f"Invalid discovery question id: {identifier!r}"
+      raise DiscoveryError(msg)
+    category = _text(mapping.get("category"), "question category")
+    if category not in QUESTION_CATEGORIES:
+      msg = (
+        f"Invalid discovery question category: {category!r}"
+      )
+      raise DiscoveryError(msg)
+    question = _limited_text(
+      mapping.get("question"),
+      f"{identifier}.question",
+    )
+    reason = _limited_text(
+      mapping.get("reason"),
+      f"{identifier}.reason",
+    )
+    blocking = _boolean(mapping.get("blocking"), f"{identifier}.blocking")
+    status = _text(mapping.get("status"), f"{identifier}.status")
+    if status not in QUESTION_STATUSES:
+      msg = (
+        f"Invalid status for {identifier}: {status!r}. "
+        f"Expected one of: {', '.join(QUESTION_STATUSES)}."
+      )
+      raise DiscoveryError(msg)
+    options = tuple(
+      _limited_text(item, f"{identifier}.options")
+      for item in _list(
+        mapping.get("options", []),
+        f"{identifier}.options",
+      )
+    )
+    if len(options) > MAX_OPTIONS:
+      msg = f"{identifier} has too many options."
+      raise DiscoveryError(msg)
+    answer = _optional_text(mapping.get("answer"), f"{identifier}.answer")
+    answered_by = _optional_text(
+      mapping.get("answered_by"),
+      f"{identifier}.answered_by",
+    )
+    answered_at = _optional_text(
+      mapping.get("answered_at"),
+      f"{identifier}.answered_at",
+    )
+    if status == QUESTION_ANSWERED:
+      if not answer:
+        raise DiscoveryError(
+          f"{identifier} is answered but has no answer."
+        )
+      if not answered_by:
+        raise DiscoveryError(
+          f"{identifier} is answered but has no answered_by."
+        )
+      if not answered_at:
+        raise DiscoveryError(
+          f"{identifier} is answered but has no answered_at."
+        )
+    elif answer or answered_by or answered_at:
+      raise DiscoveryError(
+        f"{identifier} is pending but contains answer metadata."
+      )
+    return DiscoveryQuestion(
+      id=identifier,
+      category=category,
+      question=question,
+      reason=reason,
+      blocking=blocking,
+      status=status,
+      options=options,
+      answer=answer,
+      answered_by=answered_by,
+      answered_at=answered_at,
+    )
+
+  def _assumption(
+    self,
+    data: object,
+    index: int,
+    question_ids: set[str],
+  ) -> DiscoveryAssumption:
+    mapping = _mapping(data, f"assumptions[{index}]")
+    identifier = _text(mapping.get("id"), "assumption id")
+    if not _ASSUMPTION_ID.fullmatch(identifier):
+      msg = f"Invalid discovery assumption id: {identifier!r}"
+      raise DiscoveryError(msg)
+    question_id = _optional_text(
+      mapping.get("question_id"),
+      f"{identifier}.question_id",
+    )
+    if question_id is not None and question_id not in question_ids:
+      msg = (
+        f"{identifier} references unknown question "
+        f"{question_id!r}."
+      )
+      raise DiscoveryError(msg)
+    value = _limited_text(
+      mapping.get("value"),
+      f"{identifier}.value",
+    )
+    reason = _limited_text(
+      mapping.get("reason"),
+      f"{identifier}.reason",
+    )
+    source = _text(mapping.get("source"), f"{identifier}.source")
+    if source not in ASSUMPTION_SOURCES:
+      msg = (
+        f"Invalid source for {identifier}: {source!r}. "
+        f"Expected one of: {', '.join(ASSUMPTION_SOURCES)}."
+      )
+      raise DiscoveryError(msg)
+    status = _text(mapping.get("status"), f"{identifier}.status")
+    if status not in ASSUMPTION_STATUSES:
+      msg = (
+        f"Invalid status for {identifier}: {status!r}. "
+        f"Expected one of: {', '.join(ASSUMPTION_STATUSES)}."
+      )
+      raise DiscoveryError(msg)
+    accepted_by = _optional_text(
+      mapping.get("accepted_by"),
+      f"{identifier}.accepted_by",
+    )
+    accepted_at = _optional_text(
+      mapping.get("accepted_at"),
+      f"{identifier}.accepted_at",
+    )
+    if status == ASSUMPTION_ACCEPTED:
+      if not accepted_by or not accepted_at:
+        raise DiscoveryError(
+          f"{identifier} is accepted but has no acceptance metadata."
+        )
+    elif accepted_by or accepted_at:
+      raise DiscoveryError(
+        f"{identifier} is pending but contains acceptance metadata."
+      )
+    return DiscoveryAssumption(
+      id=identifier,
+      question_id=question_id,
+      value=value,
+      reason=reason,
+      source=source,
+      status=status,
+      accepted_by=accepted_by,
+      accepted_at=accepted_at,
+    )
+
+
+class DiscoveryPlanner:
+  """Generate deterministic discovery questions from a request."""
+
+  def build(
+    self,
+    *,
+    request: str,
+    spec_id: str,
+    change: str,
+    project_mode: str,
+    project: Project,
+    profiles: tuple[str, ...],
+    reference_paths: tuple[str, ...],
+    category_paths: dict[str, tuple[str, ...]],
+    has_tests: bool,
+    architecture: ArchitectureManifest | None,
+    now: str,
+  ) -> DiscoveryDocument:
+    """Return a deterministic discovery record for a request."""
+    text = _normalize(request)
+    words = _words(text)
+    questions: list[DiscoveryQuestion] = []
+    assumptions: list[DiscoveryAssumption] = []
+
+    def add_question(
+      category: str,
+      question: str,
+      reason: str,
+      options: tuple[str, ...] = (),
+    ) -> str | None:
+      if any(
+        item.question.casefold() == question.casefold()
+        for item in questions
+      ):
+        return None
+      identifier = f"Q{len(questions) + 1}"
+      questions.append(
+        DiscoveryQuestion(
+          id=identifier,
+          category=category,
+          question=question,
+          reason=reason,
+          blocking=True,
+          options=options,
+        )
+      )
+      return identifier
+
+    keywords = [
+      word
+      for word in words
+      if len(word) >= 3 and word not in _STOPWORDS
+    ]
+    if len(keywords) < 2:
+      add_question(
+        "functional_scope",
+        "What exact behavior should change, and how will it be "
+        "verified?",
+        "The request is too short to define a testable scope.",
+        (
+          "Describe the user-visible behavior.",
+          "Describe the expected technical outcome.",
+        ),
+      )
+
+    vague = sorted(words & _VAGUE_TERMS)
+    if vague:
+      target = vague[0]
+      add_question(
+        "functional_scope",
+        f"What measurable outcome defines '{target}' for this change?",
+        "A vague goal changes the functional scope and the acceptance "
+        "criteria.",
+        (
+          "Define the expected observable behavior.",
+          "Define a measurable target.",
+          "Describe the current pain point.",
+        ),
+      )
+
+    contact_question: str | None = None
+    is_contact_page = (
+      bool(words & _CONTACT_WORDS)
+      and bool(words & (_FORM_WORDS | _PAGE_WORDS))
+    )
+    if is_contact_page and not _has_submission_decision(text, words):
+      contact_question = add_question(
+        "functional_scope",
+        "What should happen when the contact form is submitted?",
+        "Persistence, confirmation and email delivery change the data "
+        "model, dependencies and user-visible behavior.",
+        (
+          "Only show a confirmation message.",
+          "Store messages in the database.",
+          "Send an email notification.",
+          "Store messages and send an email.",
+        ),
+      )
+      if contact_question and not _has_contact_names(text, words):
+        assumptions.append(
+          DiscoveryAssumption(
+            id="A1",
+            question_id=contact_question,
+            value=(
+              "Use `contacto.html` as the template and `/contacto/` as "
+              "the URL path."
+            ),
+            reason=(
+              "Internal naming and routing can follow existing project "
+              "conventions, but the choice must be visible."
+            ),
+            source="agent_default",
+          )
+        )
+
+    auth_question: str | None = None
+    is_auth_request = bool(words & _AUTH_WORDS)
+    if is_auth_request and not (words & _AUTH_INTEGRATION_WORDS):
+      auth_question = add_question(
+        "security_authentication",
+        "How should authentication be integrated into the existing "
+        "application?",
+        "API tokens, browser cookies and session authentication change "
+        "security boundaries, dependencies and user-visible behavior.",
+        (
+          "New JSON API with Bearer tokens.",
+          "JWT in an HttpOnly cookie for HTML views.",
+          "Both the JSON API and the HTML views.",
+          "Other (describe).",
+        ),
+      )
+      if auth_question and (words & {"jwt", "oauth", "token"}):
+        if not (words & {
+          "django",
+          "djangorestframework",
+          "framework",
+          "pyjwt",
+          "rest",
+          "simplejwt",
+        }):
+          assumptions.append(
+            DiscoveryAssumption(
+              id=f"A{len(assumptions) + 1}",
+              question_id=auth_question,
+              value=(
+                "Use the existing user identity source and a maintained "
+                "JWT library instead of custom cryptographic code."
+              ),
+              reason=(
+                "The library and identity source change dependencies and "
+                "security behavior, so the assumption must be accepted."
+              ),
+              source="agent_default",
+            )
+          )
+        if not (words & {
+          "day",
+          "days",
+          "expiracion",
+          "hour",
+          "hours",
+          "lifetime",
+          "minute",
+          "minutes",
+        }):
+          assumptions.append(
+            DiscoveryAssumption(
+              id=f"A{len(assumptions) + 1}",
+              question_id=auth_question,
+              value=(
+                "Use short-lived access tokens with refresh tokens and "
+                "define both lifetimes in project settings."
+              ),
+              reason=(
+                "Token lifetimes are a security decision and must not be "
+                "invented silently."
+              ),
+              source="agent_default",
+            )
+          )
+
+    if (
+      words & _DATA_WORDS
+      and not project.databases
+      and not _has_persistence_decision(text, words)
+      and "Database migrations" not in category_paths
+    ):
+      add_question(
+        "data_persistence",
+        "Where should the new data be stored and how should it be "
+        "persisted?",
+        "Persistence changes the data model, migrations, tests and "
+        "deployment requirements.",
+        (
+          "Use the existing database.",
+          "Create a new database or service.",
+          "No persistence is required.",
+        ),
+      )
+
+    if (
+      contact_question is None
+      and _has_external_integration(text, words)
+      and not (words & _PROVIDER_WORDS)
+    ):
+      add_question(
+        "external_integration",
+        "Which external service or integration should be used?",
+        "The provider, credentials and failure behavior change the "
+        "implementation and operations.",
+        (
+          "Describe the provider and its configuration.",
+          "Reuse an existing integration.",
+          "No external integration is required.",
+        ),
+      )
+
+    if (
+      words & _DEPLOYMENT_WORDS
+      and not (words & _DEPLOYMENT_TARGETS)
+    ):
+      add_question(
+        "deployment",
+        "Which deployment target and environment should the change "
+        "support?",
+        "Deployment constraints change configuration, secrets and "
+        "operational requirements.",
+        (
+          "Use the existing deployment target.",
+          "Add a new target (describe it).",
+          "Local development only.",
+        ),
+      )
+
+    if (
+      project_mode == "existing"
+      and architecture is None
+      and words & _ARCHITECTURE_WORDS
+    ):
+      add_question(
+        "architecture_boundary",
+        "Which module boundaries and dependency direction should the "
+        "new behavior follow?",
+        "Without a declared architecture manifest, ownership and "
+        "dependency boundaries are ambiguous.",
+        (
+          "Follow the existing project structure.",
+          "Create a new module (describe it).",
+          "Other (describe).",
+        ),
+      )
+
+    if project_mode == "greenfield" and architecture is not None:
+      if not architecture.stack:
+        add_question(
+          "dependencies",
+          "Which technology stack should the new system use?",
+          "The declared architecture manifest does not define the "
+          "languages, frameworks or database.",
+          (
+            "Complete the architecture manifest.",
+            "Describe the stack for this change.",
+          ),
+        )
+
+    questions = questions[:4]
+    question_ids = {question.id for question in questions}
+    assumptions = [
+      assumption
+      for assumption in assumptions[:3]
+      if assumption.question_id is None
+      or assumption.question_id in question_ids
+    ]
+    # Keep assumption ids contiguous after filtering.
+    assumptions = [
+      replace(assumption, id=f"A{index}")
+      for index, assumption in enumerate(assumptions, start=1)
+    ]
+
+    document = DiscoveryDocument(
+      version=1,
+      spec_id=spec_id,
+      change=change,
+      request=request.strip(),
+      project_mode=project_mode,
+      status=(
+        DISCOVERY_COMPLETE
+        if not questions and not assumptions
+        else DISCOVERY_PENDING
+      ),
+      created_at=now,
+      updated_at=now,
+      questions=tuple(questions),
+      assumptions=tuple(assumptions),
+    )
+    return replace(document, status=document.derived_status)
+
+
+def _normalize(value: str) -> str:
+  normalized = unicodedata.normalize("NFKD", value)
+  without_accents = "".join(
+    character
+    for character in normalized
+    if not unicodedata.combining(character)
+  )
+  return without_accents.lower()
+
+
+def _words(text: str) -> set[str]:
+  return set(re.findall(r"[a-z0-9_]+", text))
+
+
+def _has_submission_decision(text: str, words: set[str]) -> bool:
+  if words & _SUBMISSION_DECISIONS:
+    return True
+  return _has_phrase(text, _SUBMISSION_PHRASES)
+
+
+def _has_contact_names(text: str, words: set[str]) -> bool:
+  return (
+    "contacto.html" in text
+    or "/contacto/" in text
+    or "contact.html" in text
+    or "/contact/" in text
+  )
+
+
+def _has_persistence_decision(text: str, words: set[str]) -> bool:
+  if words & _PERSISTENCE_DECISIONS:
+    return True
+  return _has_phrase(text, _NO_PERSISTENCE_PHRASES)
+
+
+def _has_external_integration(text: str, words: set[str]) -> bool:
+  return _has_phrase(text, _INTEGRATION_PHRASES) or (
+    bool(words & {"webhook", "webhooks"})
+  )
+
+
+def _has_phrase(text: str, phrases: set[str]) -> bool:
+  return any(phrase in text for phrase in phrases)
+
+
+def _mapping(value: object, field: str) -> dict[str, Any]:
+  if not isinstance(value, dict):
+    msg = f"{field} must be a mapping."
+    raise DiscoveryError(msg)
+  return value
+
+
+def _list(value: object, field: str) -> list[Any]:
+  if value is None:
+    return []
+  if not isinstance(value, list):
+    msg = f"{field} must be a list."
+    raise DiscoveryError(msg)
+  return value
+
+
+def _text(value: object, field: str) -> str:
+  if not isinstance(value, str) or not value.strip():
+    msg = f"{field} must be a non-empty string."
+    raise DiscoveryError(msg)
+  return value.strip()
+
+
+def _optional_text(value: object, field: str) -> str | None:
+  if value is None:
+    return None
+  if not isinstance(value, str):
+    msg = f"{field} must be a string or null."
+    raise DiscoveryError(msg)
+  stripped = value.strip()
+  return stripped or None
+
+
+def _limited_text(value: object, field: str) -> str:
+  text = _text(value, field)
+  if len(text) > MAX_TEXT_LENGTH:
+    msg = (
+      f"{field} is too long ({len(text)} characters, "
+      f"max {MAX_TEXT_LENGTH})."
+    )
+    raise DiscoveryError(msg)
+  return text
+
+
+def _boolean(value: object, field: str) -> bool:
+  if not isinstance(value, bool):
+    msg = f"{field} must be true or false."
+    raise DiscoveryError(msg)
+  return value
+
+
+def _integer(value: object, field: str) -> int:
+  if isinstance(value, bool) or not isinstance(value, int):
+    msg = f"{field} must be an integer."
+    raise DiscoveryError(msg)
+  return value
+
+
+def is_valid_digest(value: str) -> bool:
+  """Return whether a value is a DevFlow SHA-256 digest."""
+  return bool(_SHA256.fullmatch(value))