forge-autonomy 2.3.1__py3-none-any.whl

forge/architecture/advisor.py

@@ -0,0 +1,37 @@
+"""Immutable, non-executing Architecture Advisor contract."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from forge.models.architecture_mission import ArchitectureMission
+
+
+@dataclass(frozen=True)
+class ArchitectureAdvisorAdvice:
+    mission_id: str
+    technical_feasibility: str
+    architecture_consistency: str
+    implementation_boundaries: tuple[str, ...]
+    dependency_findings: tuple[str, ...]
+    risk_findings: tuple[str, ...]
+    repository_consistency: str
+    capability_reuse: tuple[str, ...]
+    governance_compliance: str
+    advisory: bool = True
+
+
+class ArchitectureAdvisor:
+    """Produces advice only; it cannot approve, plan, execute, or operate a repository."""
+
+    def advise(self, mission: ArchitectureMission) -> ArchitectureAdvisorAdvice:
+        readiness = "ready for engineering approval" if mission.is_engineering_ready() else "requires architectural refinement before engineering approval"
+        boundaries = mission.engineering_constraints or ("Define explicit engineering constraints.",)
+        dependencies = tuple(f"Review dependency: {item}" for item in mission.dependencies) or ("Identify dependencies.",)
+        risks = tuple(f"Review risk: {item}" for item in mission.risks) or ("Identify technical risks.",)
+        capabilities = tuple(f"Assess reuse of capability: {item}" for item in mission.required_capabilities) or ("Assess existing capability reuse.",)
+        return ArchitectureAdvisorAdvice(
+            mission.id, readiness, "Preserve the approved business objective and Mission boundaries.", boundaries,
+            dependencies, risks, "Repository truth must be reviewed by a human; this contract performs no repository access.",
+            capabilities, "Architecture approval remains a Platform Architect decision.",
+        )

forge/architecture/presentation.py

@@ -0,0 +1,21 @@
+"""Minimal deterministic Architecture Workspace detail view."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from forge.models.architecture_mission import ArchitectureMission
+from forge.models.decision_evidence import DecisionEvidence
+
+
+def render_architecture_mission(mission: ArchitectureMission) -> dict[str, Any]:
+    return {**mission.to_dict(), "advisory_available": True, "execution_available": False, "repository_mutation_available": False}
+
+
+def render_architecture_decision_evidence(evidence: DecisionEvidence) -> dict[str, Any]:
+    """Expose architecture rationale and traceability without an approval action."""
+    return {"id": evidence.id, "decision_type": evidence.decision_type.value, "decision": evidence.decision,
+            "reasoning_summary": evidence.reasoning_summary, "required_disciplines": list(evidence.required_disciplines),
+            "architecture_constraints": list(evidence.architecture_constraints),
+            "traceability": [item.to_dict() for item in evidence.evidence_references], "confidence": evidence.confidence.to_dict(),
+            "approval_state": evidence.approval_state.value, "execution_available": False}

forge/architecture/workspace.py

@@ -0,0 +1,169 @@
+"""Local Architecture Workspace governance and approval persistence."""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from dataclasses import dataclass, replace
+from pathlib import Path
+
+from forge.models.architecture_mission import ArchitectureMission, ArchitectureMissionStatus
+from forge.models.mission_candidate import MissionCandidate, MissionCandidateStatus
+
+
+class ArchitectureWorkspaceError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class ArchitectureMissionHistoryEntry:
+    revision: int
+    event: str
+    actor: str
+    occurred_at: str
+    rationale: str
+
+
+class ArchitectureWorkspace:
+    """Legacy local workspace storage for offline/tests; not production authority.
+
+    Supported Forge governance mutations use :meth:`for_runtime`, which is
+    bound to the resolved Runtime Instance and canonical evidence repository.
+    """
+
+    @classmethod
+    def for_runtime(cls, database: object, repository: object, context: object) -> object:
+        """Return the canonical runtime-bound Architecture approval service."""
+        from forge.governance_authority import CanonicalArchitectureWorkspace
+        if getattr(repository, "database", None) is not database:
+            raise ArchitectureWorkspaceError("Architecture governance repository must use the resolved Runtime Instance")
+        return CanonicalArchitectureWorkspace(repository, context)
+
+    def __init__(self, path: Path) -> None:
+        self._connection = sqlite3.connect(path)
+        self._connection.row_factory = sqlite3.Row
+        self._connection.executescript("""
+            CREATE TABLE IF NOT EXISTS architecture_mission (
+              mission_id TEXT PRIMARY KEY, candidate_id TEXT UNIQUE NOT NULL, revision INTEGER NOT NULL, status TEXT NOT NULL, document TEXT NOT NULL
+            );
+            CREATE TABLE IF NOT EXISTS architecture_mission_history (
+              mission_id TEXT NOT NULL, revision INTEGER NOT NULL, event TEXT NOT NULL, actor TEXT NOT NULL,
+              occurred_at TEXT NOT NULL, rationale TEXT NOT NULL, PRIMARY KEY(mission_id, revision),
+              FOREIGN KEY(mission_id) REFERENCES architecture_mission(mission_id)
+            );
+            CREATE TRIGGER IF NOT EXISTS architecture_mission_history_no_update BEFORE UPDATE ON architecture_mission_history
+            BEGIN SELECT RAISE(ABORT, 'architecture mission history is append-only'); END;
+            CREATE TRIGGER IF NOT EXISTS architecture_mission_history_no_delete BEFORE DELETE ON architecture_mission_history
+            BEGIN SELECT RAISE(ABORT, 'architecture mission history is append-only'); END;
+        """)
+        self._connection.commit()
+
+    def close(self) -> None:
+        self._connection.close()
+
+    def __enter__(self) -> "ArchitectureWorkspace":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def admit(self, candidate: MissionCandidate, *, actor: str, occurred_at: str, rationale: str) -> ArchitectureMission:
+        if candidate.status is not MissionCandidateStatus.APPROVED_FOR_ARCHITECTURE:
+            raise ArchitectureWorkspaceError("only business-approved candidates may enter architecture review")
+        mission = ArchitectureMission.from_candidate(candidate)
+        self._write(mission, 1, "admitted_from_business", actor, occurred_at, rationale, insert=True)
+        return self.get(mission.id)
+
+    create = admit
+
+    def get(self, mission_id: str) -> ArchitectureMission:
+        row = self._connection.execute("SELECT document FROM architecture_mission WHERE mission_id = ?", (mission_id,)).fetchone()
+        if row is None:
+            raise ArchitectureWorkspaceError(f"unknown architecture mission: {mission_id}")
+        return ArchitectureMission.from_dict(json.loads(row["document"]))
+
+    def list(self, *, status: ArchitectureMissionStatus | None = None) -> tuple[ArchitectureMission, ...]:
+        query = "SELECT document FROM architecture_mission" + (" WHERE status = ?" if status else "") + " ORDER BY mission_id"
+        rows = self._connection.execute(query, () if status is None else (status.value,)).fetchall()
+        return tuple(ArchitectureMission.from_dict(json.loads(row["document"])) for row in rows)
+
+    def approved_for_engineering(self) -> tuple[ArchitectureMission, ...]:
+        """Return the governed queue source in deterministic approval order."""
+        rows = self._connection.execute(
+            """
+            SELECT mission.document
+            FROM architecture_mission AS mission
+            JOIN architecture_mission_history AS history
+              ON history.mission_id = mission.mission_id
+             AND history.event = 'approved_for_engineering'
+            WHERE mission.status = ?
+            ORDER BY history.occurred_at, mission.mission_id
+            """,
+            (ArchitectureMissionStatus.APPROVED_FOR_ENGINEERING.value,),
+        ).fetchall()
+        return tuple(ArchitectureMission.from_dict(json.loads(row["document"])) for row in rows)
+
+    def refine(self, mission_id: str, *, actor: str, occurred_at: str, rationale: str, **changes: object) -> ArchitectureMission:
+        mission, revision = self._current(mission_id)
+        if mission.status is not ArchitectureMissionStatus.ARCHITECTURE_REVIEW:
+            raise ArchitectureWorkspaceError("only Missions in architecture_review may be refined")
+        allowed = {"scope", "engineering_constraints", "acceptance_criteria", "technical_assumptions", "dependencies", "required_capabilities", "required_disciplines", "risks"}
+        if not changes or set(changes) - allowed:
+            raise ArchitectureWorkspaceError("architecture refinement may update only engineering governance fields")
+        refined = replace(mission, **changes)
+        self._write(refined, revision + 1, "refined", actor, occurred_at, rationale)
+        return self.get(mission_id)
+
+    def approve_for_engineering(self, mission_id: str, *, actor: str, occurred_at: str, rationale: str) -> ArchitectureMission:
+        mission, revision = self._current(mission_id)
+        if mission.status is not ArchitectureMissionStatus.ARCHITECTURE_REVIEW:
+            raise ArchitectureWorkspaceError(f"architecture mission transition {mission.status.value} -> approved_for_engineering is not permitted")
+        if not mission.is_engineering_ready():
+            raise ArchitectureWorkspaceError("engineering approval requires a complete architectural refinement")
+        return self._transition(mission, revision, ArchitectureMissionStatus.APPROVED_FOR_ENGINEERING, "approved_for_engineering", actor, occurred_at, rationale)
+
+    def return_to_business(self, mission_id: str, *, actor: str, occurred_at: str, rationale: str) -> ArchitectureMission:
+        return self._terminal_transition(mission_id, ArchitectureMissionStatus.RETURNED_TO_BUSINESS, "returned_to_business", actor, occurred_at, rationale)
+
+    def reject(self, mission_id: str, *, actor: str, occurred_at: str, rationale: str) -> ArchitectureMission:
+        return self._terminal_transition(mission_id, ArchitectureMissionStatus.REJECTED, "rejected", actor, occurred_at, rationale)
+
+    def archive(self, mission_id: str, *, actor: str, occurred_at: str, rationale: str) -> ArchitectureMission:
+        return self._terminal_transition(mission_id, ArchitectureMissionStatus.ARCHIVED, "archived", actor, occurred_at, rationale)
+
+    def history(self, mission_id: str) -> tuple[ArchitectureMissionHistoryEntry, ...]:
+        self.get(mission_id)
+        rows = self._connection.execute("SELECT revision, event, actor, occurred_at, rationale FROM architecture_mission_history WHERE mission_id = ? ORDER BY revision", (mission_id,)).fetchall()
+        return tuple(ArchitectureMissionHistoryEntry(**dict(row)) for row in rows)
+
+    def _terminal_transition(self, mission_id: str, target: ArchitectureMissionStatus, event: str, actor: str, occurred_at: str, rationale: str) -> ArchitectureMission:
+        mission, revision = self._current(mission_id)
+        if mission.status is not ArchitectureMissionStatus.ARCHITECTURE_REVIEW:
+            raise ArchitectureWorkspaceError(f"architecture mission transition {mission.status.value} -> {target.value} is not permitted")
+        return self._transition(mission, revision, target, event, actor, occurred_at, rationale)
+
+    def _transition(self, mission: ArchitectureMission, revision: int, target: ArchitectureMissionStatus, event: str, actor: str, occurred_at: str, rationale: str) -> ArchitectureMission:
+        if not all((actor, occurred_at, rationale)):
+            raise ArchitectureWorkspaceError("architecture decision requires actor, time, and rationale")
+        self._write(replace(mission, status=target), revision + 1, event, actor, occurred_at, rationale)
+        return self.get(mission.id)
+
+    def _current(self, mission_id: str) -> tuple[ArchitectureMission, int]:
+        row = self._connection.execute("SELECT revision, document FROM architecture_mission WHERE mission_id = ?", (mission_id,)).fetchone()
+        if row is None:
+            raise ArchitectureWorkspaceError(f"unknown architecture mission: {mission_id}")
+        return ArchitectureMission.from_dict(json.loads(row["document"])), row["revision"]
+
+    def _write(self, mission: ArchitectureMission, revision: int, event: str, actor: str, occurred_at: str, rationale: str, *, insert: bool = False) -> None:
+        if not all((actor, occurred_at, rationale)):
+            raise ArchitectureWorkspaceError("architecture change requires actor, time, and rationale")
+        document = json.dumps(mission.to_dict(), sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+        try:
+            with self._connection:
+                if insert:
+                    self._connection.execute("INSERT INTO architecture_mission VALUES (?, ?, ?, ?, ?)", (mission.id, mission.candidate_id, revision, mission.status.value, document))
+                else:
+                    self._connection.execute("UPDATE architecture_mission SET revision = ?, status = ?, document = ? WHERE mission_id = ?", (revision, mission.status.value, document, mission.id))
+                self._connection.execute("INSERT INTO architecture_mission_history VALUES (?, ?, ?, ?, ?, ?)", (mission.id, revision, event, actor, occurred_at, rationale))
+        except sqlite3.IntegrityError as error:
+            raise ArchitectureWorkspaceError(f"architecture mission already exists: {mission.id}") from error

forge/autonomous_orchestrator.py

@@ -0,0 +1,201 @@
+"""Durable, fail-closed orchestration of one approved active Mission.
+
+This composition boundary deliberately does not invoke an Execution Host.  It
+selects one bounded action, records the hand-off, and accepts only a complete
+host-issued receipt before continuing.  All durable state belongs to the
+canonical :class:`RuntimeDatabase`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from hashlib import sha256
+from typing import Any
+
+from forge.runtime import RuntimeDatabase, RuntimeDatabaseError
+
+
+class AutonomousOrchestrationError(RuntimeDatabaseError):
+    """A Mission cannot be autonomously advanced without human intervention."""
+
+
+@dataclass(frozen=True)
+class ExecutionReceipt:
+    """The minimal immutable identity Forge retains from an Execution Host."""
+
+    receipt_id: str
+    action_id: str
+    execution_host: str
+    execution_run_id: str
+    engineering_report_id: str
+    correlation_identity: str
+    executed_at: str
+    outcome: str
+
+    def __post_init__(self) -> None:
+        if self.outcome not in {"complete", "blocked", "failed"}:
+            raise ValueError("execution receipt outcome is unsupported")
+        if not all(getattr(self, field) for field in self.__dataclass_fields__):
+            raise ValueError("execution receipt requires complete host-issued identity")
+
+
+@dataclass(frozen=True)
+class OrchestrationResult:
+    mission_id: str
+    state: str
+    iteration_number: int
+    current_intent_id: str | None
+    current_action_id: str | None
+    runtime_prompt_id: str | None
+    decision_evidence_id: str | None
+
+
+class AutonomousMissionOrchestrator:
+    """Advance exactly one approved Mission through sequential host receipts."""
+
+    def __init__(self, runtime: RuntimeDatabase, *, timestamp: str) -> None:
+        self._runtime = runtime
+        self._timestamp = timestamp
+
+    def advance(self, mission_id: str, receipt: ExecutionReceipt | None = None) -> OrchestrationResult:
+        state = self._runtime.get_document("mission_state", mission_id)
+        self._assert_active_mission(mission_id)
+        try:
+            self._assert_governance(state)
+        except AutonomousOrchestrationError as error:
+            state["orchestration_state"] = ("WAITING_BUSINESS_APPROVAL" if "Business" in str(error)
+                                            else "WAITING_ARCHITECTURE_APPROVAL")
+            state["status"] = "WAITING"
+            self._save(state)
+            return self._result(state)
+        if state.get("lifecycle") == "COMPLETE":
+            return self._result(state)
+        if state.get("orchestration_state") in {
+            "WAITING_EXTERNAL_CAPABILITY", "WAITING_BUSINESS_APPROVAL",
+            "WAITING_ARCHITECTURE_APPROVAL", "WAITING_EXECUTION_FAILURE",
+        }:
+            return self._result(state)
+        if receipt is not None:
+            state = self._apply_receipt(state, receipt)
+            if state.get("lifecycle") == "COMPLETE" or state.get("orchestration_state") == "WAITING_EXECUTION_FAILURE":
+                return self._result(state)
+        return self._dispatch_next(state)
+
+    def _assert_active_mission(self, mission_id: str) -> None:
+        row = self._runtime._connection.execute(
+            "SELECT status, active_mission_id FROM dispatcher_state WHERE singleton = 1"
+        ).fetchone()
+        if row is None or row["status"] != "ACTIVE" or row["active_mission_id"] != mission_id:
+            raise AutonomousOrchestrationError("autonomous orchestration requires exactly one active Mission")
+
+    @staticmethod
+    def _assert_governance(state: dict[str, Any]) -> None:
+        governance = state.get("governance", {})
+        if governance.get("business_approval") != "approved":
+            raise AutonomousOrchestrationError("Business approval is not valid for the next dispatch")
+        if governance.get("architecture_approval") != "approved":
+            raise AutonomousOrchestrationError("Architecture approval is not valid for the next dispatch")
+
+    def _apply_receipt(self, state: dict[str, Any], receipt: ExecutionReceipt) -> dict[str, Any]:
+        current = state.get("current_engineering_action") or {}
+        if current.get("id") != receipt.action_id:
+            raise AutonomousOrchestrationError("execution receipt does not match the current Engineering Action")
+        if self._runtime.has_execution_receipt(receipt.receipt_id):
+            return state
+        self._runtime.record_execution_receipt(
+            receipt_id=receipt.receipt_id, mission_id=state["mission_id"], execution_host=receipt.execution_host,
+            execution_run_id=receipt.execution_run_id, engineering_report_id=receipt.engineering_report_id,
+            correlation_identity=receipt.correlation_identity, executed_at=receipt.executed_at, outcome=receipt.outcome,
+        )
+        action_status = {"complete": "COMPLETED", "blocked": "BLOCKED", "failed": "FAILED"}[receipt.outcome]
+        for action in state["engineering_actions"]:
+            if action["id"] == receipt.action_id:
+                action["status"] = action_status
+        references = list(state.get("execution_receipt_references", []))
+        references.append({"artifact_id": receipt.receipt_id, "kind": "execution_receipt"})
+        state["execution_receipt_references"] = references
+        state.setdefault("iteration_history", []).append({
+            "iteration": state.get("iteration_number", 0), "action_id": receipt.action_id,
+            "receipt_id": receipt.receipt_id, "outcome": receipt.outcome,
+        })
+        if receipt.outcome != "complete":
+            state["orchestration_state"] = "WAITING_EXECUTION_FAILURE"
+            state["status"] = "BLOCKED" if receipt.outcome == "blocked" else "FAILED"
+            self._save(state)
+            return state
+        self._complete_intents(state)
+        if all(action["status"] == "COMPLETED" for action in state["engineering_actions"]):
+            state.update({"lifecycle": "COMPLETE", "status": "COMPLETE", "orchestration_state": "COMPLETE",
+                          "current_engineering_action": None, "current_engineering_intent": None,
+                          "runtime_prompts": [], "progress": self._progress(state)})
+            self._runtime.save_dispatcher_state(status="IDLE", mission_sequence=(state["mission_id"],))
+            self._save(state)
+            self._runtime.record_mission_lifecycle(state["mission_id"], "complete", self._timestamp)
+            return state
+        self._save(state)
+        return state
+
+    def _dispatch_next(self, state: dict[str, Any]) -> OrchestrationResult:
+        actions = {action["id"]: action for action in state.get("engineering_actions", [])}
+        candidates = [action for action in actions.values() if action.get("status") in {"READY", "ACTIVE"}
+                      and all(actions.get(dependency, {}).get("status") == "COMPLETED" for dependency in action.get("dependencies", []))]
+        if len(candidates) != 1:
+            raise AutonomousOrchestrationError("autonomous orchestration requires exactly one executable Engineering Action")
+        action = candidates[0]
+        action["status"] = "ACTIVE"
+        intent = next((item for item in state["engineering_intents"] if item["id"] == action["intent_id"]), None)
+        if intent is None:
+            raise AutonomousOrchestrationError("Engineering Action has no persisted Engineering Intent")
+        iteration = int(state.get("iteration_number", 0)) + 1
+        prompt_id = "runtime-prompt:" + sha256(f"{state['mission_id']}:{action['id']}:{iteration}".encode()).hexdigest()
+        decision_id = f"{state['mission_id']}-orchestration-decision-{iteration}"
+        state.update({
+            "iteration_number": iteration, "current_iteration": iteration, "current_engineering_action": action,
+            "current_engineering_intent": intent, "runtime_prompts": [{"id": prompt_id, "action_id": action["id"],
+                "intent_id": intent["id"], "status": "READY_FOR_ENGINEERING_PLATFORM"}],
+            "orchestration_state": "WAITING_FOR_EXECUTION", "status": "ACTIVE", "lifecycle": "ACTIVE",
+            "decision_evidence_ids": list(state.get("decision_evidence_ids", [])) + [decision_id], "progress": self._progress(state),
+        })
+        self._save(state)
+        self._runtime.record_decision_evidence({
+            "id": decision_id, "decision_type": "engineering_action_selection", "timestamp": self._timestamp,
+            "mission_context": {"artifact_id": state["mission_id"]}, "repository_context": {"artifact_id": "forge-repository-truth"},
+            "reasoning_summary": "Exactly one approved, dependency-satisfied action was selected for the next bounded execution.",
+            "evidence_references": [{"artifact_id": "runtime:mission_state"}],
+            "alternatives_considered": [{"id": "sequential", "reason": "Selected: preserves one-action execution and receipt correlation."}],
+            "chosen_alternative": "sequential", "confidence": {"score": 100, "mission_state": {"artifact_id": state["mission_id"]}},
+            "execution_receipt_references": [],
+        })
+        return self._result(state)
+
+    def _save(self, state: dict[str, Any]) -> None:
+        self._runtime.save_mission_state(state)
+        remaining = [action["id"] for action in state["engineering_actions"] if action["status"] != "COMPLETED"]
+        complete = state.get("lifecycle") == "COMPLETE"
+        self._runtime.save_planning_state({"planner_version": "autonomous-mission-orchestrator-1", "current_queue": [] if complete else [state["mission_id"]],
+            "pending_engineering_actions": [] if complete else remaining, "blocked_engineering_actions": [action["id"] for action in state["engineering_actions"] if action["status"] in {"BLOCKED", "FAILED"}],
+            "execution_policy": state["execution_policy"], "planner_runtime_metadata": {"iteration_number": state.get("iteration_number", 0)}})
+
+    @staticmethod
+    def _complete_intents(state: dict[str, Any]) -> None:
+        for intent in state["engineering_intents"]:
+            relevant = [action for action in state["engineering_actions"] if action["intent_id"] == intent["id"]]
+            if relevant and all(action["status"] == "COMPLETED" for action in relevant):
+                intent["status"] = "COMPLETED"
+
+    @staticmethod
+    def _progress(state: dict[str, Any]) -> dict[str, int]:
+        actions = state["engineering_actions"]
+        completed = sum(action["status"] == "COMPLETED" for action in actions)
+        return {"percent_complete": (completed * 100) // len(actions), "completed_engineering_actions": completed,
+                "remaining_engineering_actions": len(actions) - completed}
+
+    @staticmethod
+    def _result(state: dict[str, Any]) -> OrchestrationResult:
+        action = state.get("current_engineering_action") or {}
+        intent = state.get("current_engineering_intent") or {}
+        prompt = next(iter(state.get("runtime_prompts", [])), {})
+        decisions = state.get("decision_evidence_ids", [])
+        return OrchestrationResult(state["mission_id"], state.get("orchestration_state", state["status"]),
+            int(state.get("iteration_number", 0)), intent.get("id"), action.get("id"), prompt.get("id"),
+            decisions[-1] if decisions else None)

forge/business/__init__.py

@@ -0,0 +1,9 @@
+"""Business Workspace public contracts."""
+
+from .advisor import BusinessAdvisor, BusinessAdvisorAdvice
+from .presentation import render_business_decision_evidence, render_mission_recommendation, render_persisted_mission_recommendation, render_persisted_recommendation_set
+from .workspace import BusinessWorkspace, BusinessWorkspaceError, MissionCandidateHistoryEntry
+from forge.governance_authority import CanonicalBusinessWorkspace
+from .ingress import BusinessGovernanceIngress, BusinessGovernanceIngressResult
+
+__all__ = ["BusinessAdvisor", "BusinessAdvisorAdvice", "BusinessWorkspace", "BusinessWorkspaceError", "CanonicalBusinessWorkspace", "MissionCandidateHistoryEntry", "BusinessGovernanceIngress", "BusinessGovernanceIngressResult", "render_business_decision_evidence", "render_mission_recommendation", "render_persisted_mission_recommendation", "render_persisted_recommendation_set"]

forge/business/advisor.py

@@ -0,0 +1,44 @@
+"""Non-executing Business Advisor contract for Mission Candidate refinement."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from forge.models.mission_candidate import MissionCandidate, MissionCandidateMaturity
+from forge.models.mission_recommendation import RequiredDiscipline
+from forge.models.solution_template import SolutionTemplate
+from forge.solutions.generator import ADVISOR_QUESTIONS, BusinessAdvisorAnswers
+
+
+@dataclass(frozen=True)
+class BusinessAdvisorAdvice:
+    candidate_id: str
+    missing_information: tuple[str, ...]
+    missing_disciplines: tuple[RequiredDiscipline, ...]
+    assumption_challenges: tuple[str, ...]
+    business_impact_assessment: str
+    advisory: bool = True
+
+
+class BusinessAdvisor:
+    """Produces business advice only; it has no state, approval, Mission, or repository authority."""
+
+    def advise(self, candidate: MissionCandidate) -> BusinessAdvisorAdvice:
+        missing = []
+        if candidate.maturity is not MissionCandidateMaturity.READY_FOR_ARCHITECTURE:
+            missing.append("candidate maturity has not reached ready_for_architecture")
+        if len(candidate.business_objective.split()) < 3:
+            missing.append("business objective needs a concrete outcome")
+        if len(candidate.dependencies) == 0:
+            missing.append("dependencies need explicit confirmation, including none when applicable")
+        disciplines = tuple(item for item in candidate.required_disciplines if item in {RequiredDiscipline.BUSINESS, RequiredDiscipline.COMMERCIAL, RequiredDiscipline.MARKET_RESEARCH, RequiredDiscipline.LEGAL, RequiredDiscipline.PRIVACY})
+        challenges = ("Validate the stated business value against the target portfolio outcome.", "Confirm the priority against other Mission Candidates.")
+        impact = f"Priority {candidate.priority}/100 with {candidate.confidence.value} confidence; review evidence before approval."
+        return BusinessAdvisorAdvice(candidate.id, tuple(missing), disciplines, challenges, impact)
+
+    def advise_template(self, template: SolutionTemplate, answers: BusinessAdvisorAnswers) -> BusinessAdvisorAdvice:
+        """Guide a selected template without generating, approving, or persisting a Mission."""
+        missing = tuple(f"answer required: {question}" for question in answers.unanswered)
+        challenges = tuple(f"Confirm {question.replace('_', ' ')} for {template.name}." for question in ADVISOR_QUESTIONS)
+        impact = f"{template.name} is advisory; the Business Owner decides whether to create and refine its drafts."
+        return BusinessAdvisorAdvice(template.reference, missing, template.engineering_disciplines, challenges, impact)