phase-loop-runtime 0.2.0__py3-none-any.whl

phase_loop_runtime/baml_src/dotfiles_c4_document.baml

@@ -0,0 +1,14 @@
+class DotfilesC4Anchor {
+  id string
+  title string
+  source_path string
+}
+
+class DotfilesC4Document {
+  title string
+  mermaid_context_source string
+  mermaid_container_source string
+  mermaid_component_source string
+  anchors DotfilesC4Anchor[]
+  description string
+}

phase_loop_runtime/baml_src/dotfiles_plan_manifest.baml

@@ -0,0 +1,50 @@
+// DotfilesPlanType enum literals: phase, detailed
+// type enum literals: phase, detailed
+
+class DotfilesPlanMetadataItem {
+  key string
+  value string
+}
+
+class DotfilesPlanMetadata {
+  entries DotfilesPlanMetadataItem[]
+}
+
+class DotfilesPlanRef {
+  slug string
+  file string
+  type string
+  digest string?
+  status string
+}
+
+class DotfilesPlanLifecycleEvent {
+  transition string
+  by string
+  at string
+  metadata DotfilesPlanMetadata
+}
+
+class DotfilesPlanEntry {
+  slug string
+  file string
+  type string
+  status string
+  created_at string
+  updated_at string
+  owner_skill string
+  handoff_ref string?
+  reflection_ref string?
+  task_summary string?
+  acceptance_criteria_count int?
+  roadmap_ref DotfilesPlanRef?
+  phase_alias string?
+  if_gates_produced string[]
+  lanes string[]
+  lifecycle DotfilesPlanLifecycleEvent[]
+}
+
+class DotfilesPlanManifest {
+  schema_version int
+  plans DotfilesPlanEntry[]
+}

phase_loop_runtime/baml_src/dotfiles_runtime_projection.baml

@@ -0,0 +1,16 @@
+class DotfilesRuntimeProjection {
+  runtime_version string
+  protocol_version string
+  harness string
+  source_bundle_digest string
+  closeout_status string
+  handoff_status string
+  current_phase_boundary string
+  last_event_iso string
+  plans_in_flight int
+  plans_executing string[]
+  last_plan_event_iso string
+  install_status string
+  gitignore_init_status string
+  operating_mode string
+}

phase_loop_runtime/baml_src/dotfiles_task_catalog.baml

@@ -0,0 +1,20 @@
+class DotfilesTask {
+  id string
+  title string
+  audience string
+  owner string
+  dependencies string[]
+  status string
+}
+
+class DotfilesTaskReference {
+  title string
+  source_path string
+  anchor string
+}
+
+class DotfilesTaskCatalog {
+  tasks DotfilesTask[]
+  audiences string[]
+  references DotfilesTaskReference[]
+}

phase_loop_runtime/baml_src/emit_phase_closeout.baml

@@ -0,0 +1,86 @@
+client<llm> PhaseLoopCloseoutClient {
+  provider "openai-generic"
+  options {
+    base_url "https://example.invalid/v1"
+    model "phase-loop-closeout"
+    default_role "user"
+  }
+}
+
+// terminal_status enum literals:
+// unplanned, planned, executing, executed, awaiting_phase_closeout, complete, blocked, unknown
+// verification_status enum literals:
+// not_run, passed, failed, blocked
+// blocker_class enum literals:
+// missing_secret, account_or_billing_setup, admin_approval, destructive_operation,
+// ambiguous_roadmap_selection, product_decision_missing, dirty_worktree_conflict,
+// branch_sync_conflict, stalled_child_observation, repeated_verification_failure,
+// sandbox_command_restriction, upstream_phase_unmet, contract_bug,
+// gold_record_amendment, closeout_evidence_drift, closeout_scope_violation,
+// unretryable_external_outage, stuck_loop, merge_conflict,
+// operator_override_missing_reason, concurrent_dispatch,
+// verification_evidence_missing, none
+
+class PhaseLoopCloseoutV1 {
+  terminal_status string
+  verification_status string
+  dirty_paths string[]
+  produced_if_gates string[]
+  next_action string?
+  blocker_class string?
+  blocker_summary string?
+  human_required bool?
+  required_human_inputs string[]
+}
+
+function EmitPhaseCloseout(
+  phase_alias: string,
+  plan_produces: string[],
+  plan_owned_files: string[],
+  closeout_commit_sha: string?
+) -> PhaseLoopCloseoutV1 {
+  client PhaseLoopCloseoutClient
+  prompt #"
+Emit the phase-loop closeout for phase {{ phase_alias }} as one JSON object.
+
+Required contract:
+- Field-anchored enum list for terminal_status: {{ allowed_terminal_statuses | join(', ') }}.
+- Field-anchored enum list for verification_status: {{ allowed_verification_statuses | join(', ') }}.
+- terminal_status must never use dry_run. dry_run is an event-level execution mode, not a phase closeout status.
+- dirty_paths must list repo-relative dirty paths left after execution.
+- produced_if_gates must list the interface-freeze gates actually produced by this closeout.
+- Completed closeouts must include every IF gate produced by the active plan and must not leave produced_if_gates empty.
+- blocker_class must be null or one frozen blocker class: {{ allowed_blocker_classes | join(', ') }}. Use none only when a non-null no-blocker marker is required.
+- blocker_summary must be non-secret and null when there is no blocker.
+- human_required must be true only for a true human decision or access blocker, false for repairable automation blockers, and null when not blocked.
+- required_human_inputs must contain only non-secret inputs needed from a human.
+
+Terminal-status decision tree:
+- Use complete only when the phase work met acceptance, required verification passed, and every active-plan IF gate is listed in produced_if_gates.
+- Use blocked when work cannot complete in this turn because verification, ownership, access, policy, or contract checks failed.
+- Use executed when implementation ran but final acceptance, artifact tracking, or verification remains unresolved.
+- Use awaiting_phase_closeout when verified phase-owned dirty output still needs the runner closeout mode to commit, isolate, or preserve it.
+- Use planned or unplanned only for planning-state closeouts where execution did not run.
+- Use executing only for an in-progress closeout and unknown only when the executor cannot determine the phase state.
+
+Field-pair invariants:
+- terminal_status=complete requires verification_status=passed.
+- terminal_status=planned or terminal_status=unplanned requires verification_status=not_run.
+- terminal_status=blocked requires verification_status=failed or verification_status=blocked.
+- terminal_status=executed, terminal_status=executing, terminal_status=awaiting_phase_closeout, or terminal_status=unknown must use the most accurate verification_status from the work performed.
+
+Active plan IF gates:
+{% for gate in plan_produces %}
+- {{ gate }}
+{% endfor %}
+
+Active plan owned files:
+{% for owned_file in plan_owned_files %}
+- {{ owned_file }}
+{% endfor %}
+
+Closeout commit SHA: {{ closeout_commit_sha | default("none") }}
+
+{{ ctx.output_format }}
+"#
+}

phase_loop_runtime/baml_src/evaluate_suspected_fake_evidence.baml

@@ -0,0 +1,36 @@
+client<llm> EvidenceAuditClient {
+  provider "openai-generic"
+  options {
+    base_url "https://example.invalid/v1"
+    model "phase-loop-evidence-audit"
+    default_role "user"
+  }
+}
+
+class EvidenceJudgment {
+  verdict string
+  confidence float
+  reasoning string
+  specific_concerns string[]
+}
+
+function EvaluateSuspectedFakeEvidence(
+  tier2_signal_summary: string,
+  sample_artifact_content: string,
+  expected_artifact_characteristics: string
+) -> EvidenceJudgment {
+  client EvidenceAuditClient
+  prompt #"
+Evaluate whether a suspected evidence artifact looks fabricated.
+
+Inputs are intentionally bounded:
+- Tier 2 signal summary: {{ tier2_signal_summary }}
+- Sample artifact content: {{ sample_artifact_content }}
+- Expected artifact characteristics: {{ expected_artifact_characteristics }}
+
+Return only an EvidenceJudgment object. Use verdict "real", "fake", or
+"uncertain". Keep reasoning concise and list concrete concerns, if any.
+
+{{ ctx.output_format }}
+"#
+}

phase_loop_runtime/baml_src/verification_evidence.baml

@@ -0,0 +1,40 @@
+class VerificationCommandEvidence {
+  argv string[]
+  cwd string
+  exit_code int
+  duration_s float
+  log_offset int
+}
+
+class VerificationEnvRefreshEvidence {
+  triggered bool
+  manifests string[]
+  install_argv string[]
+  exit_code int
+}
+
+class VerificationSuiteEvidence {
+  argv string[]
+  exit_code int
+  duration_s float
+}
+
+class VerificationValidationFinding {
+  code string
+  message string
+  command_index int
+  argument_index int?
+  value string?
+}
+
+class VerificationEvidence {
+  schema_version int
+  run_id string
+  phase_alias string
+  commands VerificationCommandEvidence[]
+  env_refresh VerificationEnvRefreshEvidence?
+  suite VerificationSuiteEvidence?
+  started_at string
+  finished_at string
+  log_sha256 string
+}

phase_loop_runtime/broker.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from .capability_registry import resolve_dispatch_decision
+from .discovery import dispatch_hints_for_action, parse_dispatch_hints, parse_plan_ownership
+from .models import DelegationDecision, DelegationRequest, DispatchHints
+
+
+DEFAULT_MAX_DELEGATION_DEPTH = 2
+DEFAULT_MAX_DELEGATION_FANOUT = 2
+DELEGATION_CHILD_ACTIONS = ("execute", "repair", "review")
+DELEGATION_CHILD_EXECUTORS = ("codex", "claude")
+
+
+def validate_delegation_request(
+    repo: Path,
+    roadmap: Path,
+    plan: Path | None,
+    request: DelegationRequest,
+    *,
+    active_loop_mode: str,
+    current_depth: int = 0,
+    current_fanout: int = 0,
+    max_depth: int = DEFAULT_MAX_DELEGATION_DEPTH,
+    max_fanout: int = DEFAULT_MAX_DELEGATION_FANOUT,
+    dry_run: bool = False,
+) -> DelegationDecision:
+    if active_loop_mode != "product":
+        return _deny(
+            request,
+            "active_loop_mode_denied",
+            f"Delegation requires product loop mode; current mode is {active_loop_mode}.",
+            observed_depth=current_depth,
+            observed_fanout=current_fanout,
+        )
+
+    if request.product_action not in DELEGATION_CHILD_ACTIONS:
+        return _deny(
+            request,
+            "unsupported_product_action",
+            "Delegation requests may only externalize execute, repair, or review child work.",
+            observed_depth=current_depth,
+            observed_fanout=current_fanout,
+        )
+
+    if request.target_executor not in DELEGATION_CHILD_EXECUTORS:
+        return _deny(
+            request,
+            "unsupported_target_executor",
+            "Delegation requests may target only codex or claude child executors.",
+            observed_depth=current_depth,
+            observed_fanout=current_fanout,
+        )
+
+    ownership = parse_plan_ownership(repo, roadmap, plan)
+    if not ownership.valid:
+        return _deny(
+            request,
+            "ownership_contract_invalid",
+            "Delegation denied because the active phase plan ownership contract is invalid or incomplete.",
+            observed_depth=current_depth,
+            observed_fanout=current_fanout,
+        )
+
+    if not request.owned_files:
+        return _deny(
+            request,
+            "missing_owned_files_claim",
+            "Delegation requests must claim at least one owned file path or glob.",
+            observed_depth=current_depth,
+            observed_fanout=current_fanout,
+        )
+
+    invalid_paths = tuple(path for path in request.owned_files if not ownership.matches(path))
+    if invalid_paths:
+        return _deny(
+            request,
+            "owned_files_out_of_bounds",
+            f"Delegation denied because owned-file claims escape the active phase contract: {', '.join(invalid_paths)}.",
+            observed_depth=current_depth,
+            observed_fanout=current_fanout,
+        )
+
+    next_depth = current_depth + 1
+    if next_depth > max_depth:
+        return _deny(
+            request,
+            "depth_limit_exceeded",
+            f"Delegation depth {next_depth} exceeds the configured limit {max_depth}.",
+            observed_depth=next_depth,
+            observed_fanout=current_fanout,
+        )
+
+    next_fanout = current_fanout + 1
+    if next_fanout > max_fanout:
+        return _deny(
+            request,
+            "fanout_limit_exceeded",
+            f"Delegation fanout {next_fanout} exceeds the configured limit {max_fanout}.",
+            observed_depth=next_depth,
+            observed_fanout=next_fanout,
+        )
+
+    if request.budget is None or not request.budget.is_defined():
+        return _deny(
+            request,
+            "missing_budget_metadata",
+            "Delegation requests must include metadata-only budget guidance before the runner can approve them.",
+            observed_depth=next_depth,
+            observed_fanout=next_fanout,
+        )
+
+    plan_hints = dispatch_hints_for_action(parse_dispatch_hints(plan, kind="plan"), request.product_action) if plan else None
+    roadmap_hints = dispatch_hints_for_action(parse_dispatch_hints(roadmap, kind="roadmap"), request.product_action)
+    operator_hints = DispatchHints(
+        preferred_executors=(request.target_executor,),
+        allowed_executors=(request.target_executor,),
+        source="delegation",
+        action=request.product_action,
+    )
+    dispatch_decision = resolve_dispatch_decision(
+        action=request.product_action,
+        dry_run=dry_run,
+        operator=operator_hints,
+        plan=plan_hints,
+        roadmap=roadmap_hints,
+    )
+    if dispatch_decision.blocked:
+        return _deny(
+            request,
+            "dispatch_policy_denied",
+            dispatch_decision.blocked_summary or "Delegation denied by dispatch policy.",
+            dispatch_decision=dispatch_decision.to_json(),
+            observed_depth=next_depth,
+            observed_fanout=next_fanout,
+        )
+    if dispatch_decision.selected_executor != request.target_executor:
+        return _deny(
+            request,
+            "dispatch_executor_mismatch",
+            (
+                f"Delegation requested {request.target_executor} but dispatch resolved "
+                f"{dispatch_decision.selected_executor or 'none'}."
+            ),
+            dispatch_decision=dispatch_decision.to_json(),
+            observed_depth=next_depth,
+            observed_fanout=next_fanout,
+        )
+    return DelegationDecision(
+        request_id=request.request_id,
+        status="approved",
+        reason_code="approved",
+        summary=f"Delegation approved for {request.product_action} on {request.target_executor}.",
+        selected_executor=request.target_executor,
+        dispatch_decision=dispatch_decision.to_json(),
+        observed_depth=next_depth,
+        observed_fanout=next_fanout,
+    )
+
+
+def _deny(
+    request: DelegationRequest,
+    reason_code: str,
+    summary: str,
+    *,
+    dispatch_decision: dict | None = None,
+    observed_depth: int | None = None,
+    observed_fanout: int | None = None,
+) -> DelegationDecision:
+    return DelegationDecision(
+        request_id=request.request_id,
+        status="denied",
+        reason_code=reason_code,
+        summary=summary,
+        dispatch_decision=dispatch_decision,
+        human_required=False,
+        blocker_class="repeated_verification_failure",
+        observed_depth=observed_depth,
+        observed_fanout=observed_fanout,
+    )