controlled-execution-system 0.1.2__py3-none-any.whl

ces/__init__.py

@@ -0,0 +1,3 @@
+"""Controlled Execution System - Deterministic governance for AI agents."""
+
+__version__ = "0.1.0"

ces/brownfield/__init__.py

@@ -0,0 +1,11 @@
+"""Brownfield legacy behavior register (BROWN-01 to BROWN-03)."""
+
+from ces.brownfield.protocols import LegacyRegisterProtocol
+from ces.brownfield.services.disposition_workflow import DispositionWorkflow
+from ces.brownfield.services.legacy_register import LegacyBehaviorService
+
+__all__ = [
+    "DispositionWorkflow",
+    "LegacyBehaviorService",
+    "LegacyRegisterProtocol",
+]

ces/brownfield/protocols.py

@@ -0,0 +1,38 @@
+"""Protocols for brownfield subsystem dependency injection.
+
+Defines the LegacyRegisterProtocol that governed services depend on
+for brownfield behavior management. This decouples consumers from the
+concrete LegacyBehaviorService implementation.
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Protocol, runtime_checkable
+
+from ces.harness.models.observed_legacy import ObservedLegacyBehavior
+
+
+@runtime_checkable
+class LegacyRegisterProtocol(Protocol):
+    """Protocol for legacy behavior register dependency injection.
+
+    Any service needing to interact with the brownfield legacy behavior
+    register should depend on this protocol rather than the concrete
+    LegacyBehaviorService.
+    """
+
+    async def register_behavior(
+        self,
+        *,
+        system: str,
+        behavior_description: str,
+        inferred_by: str,
+        confidence: float,
+        source_manifest_id: Optional[str] = None,
+    ) -> ObservedLegacyBehavior:
+        """Register a newly observed legacy behavior."""
+        ...
+
+    async def get_pending_behaviors(self) -> list[ObservedLegacyBehavior]:
+        """Get all behaviors pending human disposition."""
+        ...

ces/brownfield/services/disposition_workflow.py

@@ -0,0 +1,44 @@
+"""Disposition workflow state machine for legacy behaviors (BROWN-03).
+
+Three-state workflow enforcing human review before PRL promotion:
+    pending -> reviewed -> promoted_to_prl
+    pending -> reviewed -> discarded
+
+Invalid transitions raise TransitionNotAllowed (python-statemachine v3).
+Reconstructable from any state via start_value parameter (D-11 pattern).
+"""
+
+from __future__ import annotations
+
+from statemachine import State, StateMachine
+
+
+class DispositionWorkflow(StateMachine):
+    """Three-state disposition workflow for legacy behaviors (BROWN-03).
+
+    Enforces the invariant that legacy behaviors must be reviewed by a human
+    before they can be promoted to the PRL or discarded. This prevents
+    agents from auto-promoting inferred behaviors (T-05-15).
+
+    States:
+        pending: Initial state. Behavior has been observed but not reviewed.
+        reviewed: Human has reviewed and set a disposition.
+        promoted_to_prl: Final state. Behavior has been copied to PRL.
+        discarded: Final state. Behavior has been rejected.
+
+    Transitions:
+        review: pending -> reviewed
+        promote: reviewed -> promoted_to_prl
+        discard: reviewed -> discarded
+    """
+
+    # States
+    pending = State(initial=True)
+    reviewed = State()
+    promoted_to_prl = State(final=True)
+    discarded = State(final=True)
+
+    # Transitions
+    review = pending.to(reviewed)
+    promote = reviewed.to(promoted_to_prl)
+    discard = reviewed.to(discarded)

ces/brownfield/services/legacy_register.py

@@ -0,0 +1,417 @@
+"""Legacy behavior register service (BROWN-01, BROWN-02, BROWN-03).
+
+Manages the Observed Legacy Behavior Register for brownfield projects.
+Key invariants:
+- BROWN-01: Stores inferred behaviors with confidence scores
+- BROWN-02: register_behavior() NEVER creates a PRLItem directly.
+  Legacy behaviors go to the register, NOT the PRL, until human disposition.
+- BROWN-03: Copy-on-promote creates a NEW PRLItem with back-reference
+  to the register entry. The original entry is PRESERVED (not deleted).
+
+Threat mitigations:
+- T-05-15: promote_to_prl requires approver string; DispositionWorkflow
+  state machine prevents skipping the review step.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Optional
+
+from ces.brownfield.services.disposition_workflow import DispositionWorkflow
+from ces.control.models.prl_item import AcceptanceCriterion, PRLItem
+from ces.harness.models.observed_legacy import ObservedLegacyBehavior
+from ces.shared.enums import (
+    ActorType,
+    ArtifactStatus,
+    EventType,
+    LegacyDisposition,
+    Priority,
+    PRLItemType,
+    VerificationMethod,
+)
+
+if TYPE_CHECKING:
+    from ces.control.db.repository import LegacyBehaviorRepository
+    from ces.control.db.tables import LegacyBehaviorRow
+
+
+class LegacyBehaviorService:
+    """Service managing the Observed Legacy Behavior Register.
+
+    Implements BROWN-01 (register), BROWN-02 (separate from PRL),
+    and BROWN-03 (disposition workflow with copy-on-promote).
+    """
+
+    def __init__(
+        self,
+        repository: Optional[LegacyBehaviorRepository] = None,
+        audit_ledger: Optional[object] = None,
+    ) -> None:
+        """Initialize with optional repository and audit ledger.
+
+        Args:
+            repository: LegacyBehaviorRepository for DB persistence.
+            audit_ledger: Any object with append_event method for auditing.
+        """
+        self._repository = repository
+        self._audit_ledger = audit_ledger
+
+    async def register_behavior(
+        self,
+        *,
+        system: str,
+        behavior_description: str,
+        inferred_by: str,
+        confidence: float,
+        source_manifest_id: Optional[str] = None,
+    ) -> ObservedLegacyBehavior:
+        """Register a newly observed legacy behavior.
+
+        BROWN-01: Creates an ObservedLegacyBehavior entry in the register.
+        BROWN-02: This method NEVER creates a PRLItem. Legacy behaviors go
+        to the register, NOT the PRL, until human disposition.
+
+        Args:
+            system: The legacy system where behavior was observed.
+            behavior_description: Description of the observed behavior.
+            inferred_by: ID of the agent that inferred the behavior.
+            confidence: Confidence score (0.0 to 1.0).
+            source_manifest_id: Optional manifest ID that triggered discovery.
+
+        Returns:
+            The created ObservedLegacyBehavior domain model.
+        """
+        entry_id = f"OLB-{uuid.uuid4().hex[:12]}"
+        now = datetime.now(timezone.utc)
+
+        behavior = ObservedLegacyBehavior(
+            entry_id=entry_id,
+            system=system,
+            behavior_description=behavior_description,
+            inferred_by=inferred_by,
+            inferred_at=now,
+            confidence=confidence,
+        )
+
+        # Persist to DB if repository available
+        if self._repository is not None:
+            from ces.control.db.tables import LegacyBehaviorRow
+
+            row = LegacyBehaviorRow(
+                entry_id=behavior.entry_id,
+                system=behavior.system,
+                behavior_description=behavior.behavior_description,
+                inferred_by=behavior.inferred_by,
+                inferred_at=behavior.inferred_at,
+                confidence=behavior.confidence,
+                source_manifest_id=source_manifest_id,
+            )
+            await self._repository.save(row)
+
+        # Log to audit ledger
+        if self._audit_ledger is not None:
+            await self._audit_ledger.append_event(  # type: ignore[attr-defined]
+                event_type=EventType.TRUTH_CHANGE,
+                actor=inferred_by,
+                actor_type=ActorType.AGENT,
+                action_summary=(
+                    f"Registered legacy behavior {entry_id} from system '{system}': {behavior_description}"
+                ),
+            )
+
+        return behavior
+
+    async def get_pending_behaviors(self) -> list[ObservedLegacyBehavior]:
+        """Get all behaviors pending human disposition.
+
+        Returns only entries with disposition=None and discarded=False.
+
+        Returns:
+            List of pending ObservedLegacyBehavior entries.
+        """
+        if self._repository is None:
+            return []
+
+        rows = await self._repository.get_pending()
+        return [self._row_to_behavior(row) for row in rows]
+
+    async def get_behaviors_by_system(self, system: str) -> list[ObservedLegacyBehavior]:
+        """Get all behaviors for a specific legacy system.
+
+        Args:
+            system: The legacy system name to filter by.
+
+        Returns:
+            List of ObservedLegacyBehavior entries for the system.
+        """
+        if self._repository is None:
+            return []
+
+        rows = await self._repository.get_by_system(system)
+        return [self._row_to_behavior(row) for row in rows]
+
+    async def review_behavior(
+        self,
+        entry_id: str,
+        disposition: LegacyDisposition,
+        reviewed_by: str,
+    ) -> ObservedLegacyBehavior:
+        """Review a pending behavior and set its disposition.
+
+        Validates that the entry is pending (disposition is None), then
+        transitions through the DispositionWorkflow state machine.
+
+        Args:
+            entry_id: The behavior entry to review.
+            disposition: The disposition decision (PRESERVE, CHANGE, RETIRE, etc.).
+            reviewed_by: Human reviewer identifier.
+
+        Returns:
+            The updated ObservedLegacyBehavior.
+
+        Raises:
+            ValueError: If entry not found or not in pending state.
+        """
+        if self._repository is None:
+            msg = "Repository required for review_behavior"
+            raise RuntimeError(msg)
+
+        row = await self._repository.get_by_id(entry_id)
+        if row is None:
+            msg = f"Legacy behavior entry not found: {entry_id}"
+            raise ValueError(msg)
+
+        if row.disposition is not None:
+            msg = f"Entry {entry_id} already has disposition: {row.disposition}"
+            raise ValueError(msg)
+
+        # Validate state transition via DispositionWorkflow
+        wf = DispositionWorkflow()
+        wf.review()
+
+        now = datetime.now(timezone.utc)
+        updated_row = await self._repository.update_disposition(
+            entry_id=entry_id,
+            disposition=disposition.value,
+            reviewed_by=reviewed_by,
+            reviewed_at=now,
+        )
+
+        if updated_row is None:
+            msg = f"Failed to update disposition for {entry_id}"
+            raise ValueError(msg)
+
+        # Log to audit ledger
+        if self._audit_ledger is not None:
+            await self._audit_ledger.append_event(  # type: ignore[attr-defined]
+                event_type=EventType.TRUTH_CHANGE,
+                actor=reviewed_by,
+                actor_type=ActorType.HUMAN,
+                action_summary=(f"Reviewed legacy behavior {entry_id}: disposition={disposition.value}"),
+            )
+
+        return self._row_to_behavior(updated_row)
+
+    async def promote_to_prl(
+        self,
+        entry_id: str,
+        approver: str,
+        acceptance_criteria: list[dict] | None = None,
+        negative_examples: list[str] | None = None,
+    ) -> tuple[ObservedLegacyBehavior, PRLItem]:
+        """Promote a reviewed behavior to the PRL via copy-on-promote (BROWN-03).
+
+        Creates a NEW PRLItem from the behavior description. The original
+        register entry is PRESERVED (not deleted) with a back-reference to
+        the new PRL item. This is the copy-on-promote invariant.
+
+        Args:
+            entry_id: The behavior entry to promote.
+            approver: Human approver identifier (T-05-15 requirement).
+            acceptance_criteria: Optional custom acceptance criteria.
+            negative_examples: Optional negative examples.
+
+        Returns:
+            Tuple of (updated register entry, new PRLItem).
+
+        Raises:
+            ValueError: If entry not found, not reviewed, or already discarded.
+        """
+        if self._repository is None:
+            msg = "Repository required for promote_to_prl"
+            raise RuntimeError(msg)
+
+        row = await self._repository.get_by_id(entry_id)
+        if row is None:
+            msg = f"Legacy behavior entry not found: {entry_id}"
+            raise ValueError(msg)
+
+        if row.disposition is None:
+            msg = f"Entry {entry_id} must be reviewed before promotion"
+            raise ValueError(msg)
+
+        if row.discarded:
+            msg = f"Entry {entry_id} is discarded and cannot be promoted"
+            raise ValueError(msg)
+
+        if row.promoted_to_prl_id is not None:
+            msg = f"Entry {entry_id} already promoted to {row.promoted_to_prl_id}"
+            raise ValueError(msg)
+
+        # Validate state transition via DispositionWorkflow
+        wf = DispositionWorkflow(start_value="reviewed")
+        wf.promote()
+
+        # Copy-on-promote (BROWN-03): Create a NEW PRLItem
+        now = datetime.now(timezone.utc)
+        prl_id = f"PRL-{uuid.uuid4().hex[:12]}"
+
+        criteria = acceptance_criteria or [
+            {
+                "criterion": "Behavior preserved as observed",
+                "verification_method": VerificationMethod.MANUAL,
+            }
+        ]
+        ac_list = [
+            AcceptanceCriterion(
+                criterion=c["criterion"],
+                verification_method=(
+                    c["verification_method"]
+                    if isinstance(c["verification_method"], VerificationMethod)
+                    else VerificationMethod(c["verification_method"])
+                ),
+            )
+            for c in criteria
+        ]
+
+        prl_item = PRLItem(
+            schema_type="prl_item",
+            prl_id=prl_id,
+            type=PRLItemType.CONSTRAINT,
+            statement=row.behavior_description,
+            acceptance_criteria=tuple(ac_list),
+            negative_examples=tuple(negative_examples) if negative_examples else (),
+            priority=Priority.MEDIUM,
+            release_slice="brownfield-import",
+            legacy_disposition=LegacyDisposition.PRESERVE,
+            legacy_source_system=row.system,
+            status=ArtifactStatus.DRAFT,
+            version=1,
+            owner=approver,
+            created_at=now,
+            last_confirmed=now,
+        )
+
+        # Set back-reference on register entry (copy-on-promote preserves original)
+        promoted_row = await self._repository.mark_promoted(entry_id, prl_id)
+        if promoted_row is None:
+            msg = f"Failed to mark {entry_id} as promoted"
+            raise ValueError(msg)
+
+        # Log promotion to audit ledger
+        if self._audit_ledger is not None:
+            await self._audit_ledger.append_event(  # type: ignore[attr-defined]
+                event_type=EventType.TRUTH_CHANGE,
+                actor=approver,
+                actor_type=ActorType.HUMAN,
+                action_summary=(
+                    f"Promoted legacy behavior {entry_id} to PRL item {prl_id} (copy-on-promote, BROWN-03)"
+                ),
+            )
+
+        updated_entry = self._row_to_behavior(promoted_row)
+        return updated_entry, prl_item
+
+    async def discard_behavior(
+        self,
+        entry_id: str,
+        reviewed_by: str,
+        reason: str,
+    ) -> ObservedLegacyBehavior:
+        """Discard a behavior entry.
+
+        Marks the entry as discarded. Cannot discard an already-promoted entry.
+
+        Args:
+            entry_id: The behavior entry to discard.
+            reviewed_by: Human reviewer performing the discard.
+            reason: Reason for discarding.
+
+        Returns:
+            The updated ObservedLegacyBehavior.
+
+        Raises:
+            ValueError: If entry not found or already promoted.
+        """
+        if self._repository is None:
+            msg = "Repository required for discard_behavior"
+            raise RuntimeError(msg)
+
+        row = await self._repository.get_by_id(entry_id)
+        if row is None:
+            msg = f"Legacy behavior entry not found: {entry_id}"
+            raise ValueError(msg)
+
+        if row.promoted_to_prl_id is not None:
+            msg = f"Entry {entry_id} is already promoted to {row.promoted_to_prl_id} and cannot be discarded"
+            raise ValueError(msg)
+
+        # Transition through DispositionWorkflow
+        wf = DispositionWorkflow()
+        wf.review()
+        wf.discard()
+
+        now = datetime.now(timezone.utc)
+
+        # Update disposition to RETIRE and mark as discarded
+        updated_row = await self._repository.update_disposition(
+            entry_id=entry_id,
+            disposition=LegacyDisposition.RETIRE.value,
+            reviewed_by=reviewed_by,
+            reviewed_at=now,
+        )
+
+        if updated_row is None:
+            msg = f"Failed to update disposition for {entry_id}"
+            raise ValueError(msg)
+
+        # Mark discarded by setting the discarded flag on the row directly
+        updated_row.discarded = True
+        await self._repository.save(updated_row)
+
+        # Log to audit ledger
+        if self._audit_ledger is not None:
+            await self._audit_ledger.append_event(  # type: ignore[attr-defined]
+                event_type=EventType.TRUTH_CHANGE,
+                actor=reviewed_by,
+                actor_type=ActorType.HUMAN,
+                action_summary=(f"Discarded legacy behavior {entry_id}: {reason}"),
+            )
+
+        return self._row_to_behavior(updated_row)
+
+    @staticmethod
+    def _row_to_behavior(row: LegacyBehaviorRow) -> ObservedLegacyBehavior:
+        """Convert a DB row to an ObservedLegacyBehavior domain model.
+
+        Args:
+            row: A LegacyBehaviorRow instance from the database.
+
+        Returns:
+            ObservedLegacyBehavior domain model.
+        """
+        return ObservedLegacyBehavior(
+            entry_id=row.entry_id,
+            system=row.system,
+            behavior_description=row.behavior_description,
+            inferred_by=row.inferred_by,
+            inferred_at=row.inferred_at,
+            confidence=row.confidence,
+            disposition=(LegacyDisposition(row.disposition) if row.disposition else None),
+            reviewed_by=row.reviewed_by,
+            reviewed_at=row.reviewed_at,
+            promoted_to_prl_id=row.promoted_to_prl_id,
+            discarded=row.discarded,
+        )

ces/cli/__init__.py

@@ -0,0 +1,114 @@
+"""CES CLI entry point using Typer for the local builder-first workflow."""
+
+from __future__ import annotations
+
+import typer
+
+from ces.cli import (
+    approve_cmd,
+    audit_cmd,
+    baseline_cmd,
+    brownfield_cmd,
+    calibrate_cmd,
+    classify_cmd,
+    doctor_cmd,
+    dogfood_cmd,
+    emergency_cmd,
+    execute_cmd,
+    gate_cmd,
+    init_cmd,
+    intake_cmd,
+    manifest_cmd,
+    report_cmd,
+    review_cmd,
+    run_cmd,
+    scan_cmd,
+    setup_ci_cmd,
+    spec_cmd,
+    status_cmd,
+    triage_cmd,
+    vault_cmd,
+)
+from ces.cli._output import set_json_mode
+
+_ROOT_HELP = """Builder-first governed AI delivery for local repos.
+
+Start Here:
+  `ces build`      Describe the change and let CES guide the workflow
+  `ces continue`   Resume the latest builder session
+  `ces explain`    Summarize the latest request, blockers, and next step
+  `ces status`     Show builder-first status; add `--expert` for the full expert view
+
+Advanced Governance:
+  `ces manifest`, `classify`, `review`, `triage`, `approve`, `audit`, `gate`
+"""
+
+app = typer.Typer(
+    name="ces",
+    help=_ROOT_HELP,
+    rich_markup_mode="rich",
+)
+
+
+@app.callback()
+def main(
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output results as JSON instead of Rich tables.",
+    ),
+) -> None:
+    """Controlled Execution System - Deterministic governance for AI agents."""
+    set_json_mode(json_output)
+
+
+# ---------------------------------------------------------------------------
+# Core commands -- always available (no optional deps)
+# ---------------------------------------------------------------------------
+
+app.command(name="init", help="Optional manual setup before your first builder-first run.")(init_cmd.init_project)
+app.command(name="manifest", help="Advanced governance: generate a task manifest from natural language.")(
+    manifest_cmd.create_manifest
+)
+app.command(
+    name="build",
+    help=(
+        "Describe what you want to build and let CES run the local workflow. "
+        "Tip: CES_DEMO_MODE=1 only affects optional LLM-backed steps; "
+        "`ces build` still needs Codex CLI or Claude Code."
+    ),
+)(run_cmd.run_task)
+app.command(name="continue", help="Resume the latest saved builder brief without re-entering context.")(
+    run_cmd.continue_task
+)
+app.command(name="explain", help="Explain the latest builder brief and current CES state in plain language.")(
+    run_cmd.explain_task
+)
+app.command(name="run", help="Legacy alias for the guided local-first build flow.")(run_cmd.run_task)
+
+app.command(name="classify", help="Classify a task manifest.")(classify_cmd.classify_task)
+app.command(name="execute", help="Execute an agent task locally within manifest boundaries.")(execute_cmd.execute_task)
+app.command(name="review", help="Run review pipeline and display evidence summary.")(review_cmd.review_task)
+app.command(name="triage", help="Pre-screen evidence with triage color.")(triage_cmd.triage_evidence)
+app.command(name="approve", help="Approve or reject evidence.")(approve_cmd.approve_evidence)
+app.command(name="gate", help="Evaluate a phase gate.")(gate_cmd.evaluate_gate)
+app.command(name="intake", help="Run intake interview for a phase.")(intake_cmd.run_intake)
+app.command(name="calibrate", help="Run hidden check calibration probes.")(calibrate_cmd.run_calibration)
+app.add_typer(vault_cmd.vault_app, name="vault")
+app.add_typer(spec_cmd.spec_app, name="spec")
+app.command(name="status", help="Show builder-first project status. Use --expert for the full expert view.")(
+    status_cmd.show_status
+)
+app.command(name="dogfood", help="Use CES to review its own changes.")(dogfood_cmd.dogfood)
+app.command(name="doctor", help="Run pre-flight checks (Python, providers, extras, project dir).")(
+    doctor_cmd.run_doctor
+)
+app.command(name="setup-ci", help="Generate a CI gating workflow for the chosen provider (github|gitlab).")(
+    setup_ci_cmd.setup_ci
+)
+app.command(name="scan", help="Inventory the repository: modules, generated code, CODEOWNERS.")(scan_cmd.scan)
+app.command(name="baseline", help="Capture a day-0 sensor snapshot under .ces/baseline/.")(baseline_cmd.baseline)
+app.command(name="audit", help="Inspect the local audit ledger.")(audit_cmd.query_audit)
+app.add_typer(report_cmd.report_app, name="report")
+app.add_typer(brownfield_cmd.brownfield_app, name="brownfield")
+app.add_typer(emergency_cmd.emergency_app, name="emergency")

ces/cli/_async.py

@@ -0,0 +1,44 @@
+"""Async wrapper for Typer commands.
+
+Typer commands are synchronous, but CES services are async.
+This module provides a decorator that bridges the gap by calling
+asyncio.run() inside a synchronous wrapper.
+
+Exports:
+    run_async: Decorator that wraps an async function for Typer.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from functools import wraps
+from typing import Any, Callable, Coroutine, TypeVar
+
+T = TypeVar("T")
+
+
+def run_async(func: Callable[..., Coroutine[Any, Any, T]]) -> Callable[..., T]:
+    """Wrap an async function so it can be used as a Typer command.
+
+    Uses asyncio.run() to execute the coroutine synchronously.
+    Preserves the original function's name, docstring, and type hints
+    so Typer can introspect parameters for --help generation.
+
+    Args:
+        func: An async function to wrap.
+
+    Returns:
+        A synchronous wrapper that calls asyncio.run(func(...)).
+
+    Example::
+
+        @run_async
+        async def my_command(name: str) -> None:
+            await some_async_operation(name)
+    """
+
+    @wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> T:
+        return asyncio.run(func(*args, **kwargs))
+
+    return wrapper