arkaos 4.0.1 → 4.1.0

package/core/forge/orchestrator.py

@@ -157,6 +157,8 @@ class ForgeOrchestrator:
         self._dispatcher = dispatcher or ClaudeCodeForgeDispatcher()
         self._current_plan: Optional[ForgePlan] = None
         self._current_step: Optional[ForgeStep] = None
+        self._critic_verdict: Optional[CriticVerdict] = None
+        self._dispatch_errors: list[str] = []
 
     # -------------------------------------------------------------------------
     # Main Commands
@@ -554,12 +556,15 @@ class ForgeOrchestrator:
             for lens in lenses
         ]
 
+        self._dispatch_errors = []
         for req in requests:
             try:
                 approach = self._dispatcher.dispatch_explorer_and_parse(req)
                 self._approaches.append(approach)
             except Exception as e:
-                pass
+                self._dispatch_errors.append(
+                    f"explorer[{req.lens.value}]: {type(e).__name__}: {e}"
+                )
 
     def _step6_critic_synthesis(self, revision_request: Optional[str] = None) -> None:
         """Step 6: Launch critic subagent for synthesis.
@@ -576,16 +581,13 @@ class ForgeOrchestrator:
 
         try:
             self._critic_verdict = self._dispatcher.dispatch_critic_and_parse(critic_req)
-        except Exception:
-            self._critic_verdict = CriticVerdict(
-                synthesis={"approach_1": [a.summary for a in self._approaches]},
-                rejected_elements=[],
-                risks=[],
-                confidence=0.5,
-                estimated_phases=len(self._approaches[0].phases) if self._approaches else 3,
-            )
+        except Exception as e:
+            # Honest failure: NEVER fabricate a synthetic verdict. A missing
+            # critic means the plan is degraded and must say so.
+            self._critic_verdict = None
+            self._dispatch_errors.append(f"critic: {type(e).__name__}: {e}")
 
-        if revision_request:
+        if revision_request and self._critic_verdict is not None:
             self._critic_verdict.synthesis["revision_request"] = [revision_request]
 
     def _step7_enforce_constitution(self) -> None:
@@ -596,7 +598,7 @@ class ForgeOrchestrator:
         has_branch = any("branch" in n or "feature" in n for n in phase_names)
         has_spec = any("spec" in n or "specification" in n for n in phase_names)
         has_qg = any("quality" in n or "gate" in n or "qg" in n for n in phase_names)
-        has_obsidian = any("obsidian" in n or "persist" in n or "persist" in n for n in phase_names)
+        has_obsidian = any("obsidian" in n or "persist" in n or "document" in n for n in phase_names)
 
         enforced = []
         if not has_branch:
@@ -643,9 +645,16 @@ class ForgeOrchestrator:
         self._enforced_phases = enforced
 
     def _step8_build_plan(self) -> None:
-        """Step 8: Build the ForgePlan object."""
+        """Step 8: Build the ForgePlan object.
+
+        When explorer/critic dispatch failed, the plan is marked
+        ``degraded`` with confidence 0.0 and carries the dispatch errors —
+        never a fabricated verdict.
+        """
         plan_id = self._generate_plan_id(self._forge_context.prompt)
-        execution_path = select_execution_path(self._final_phases_from_critic())
+        phases = self._final_phases_from_critic()
+        execution_path = select_execution_path(phases)
+        degraded = self._critic_verdict is None
 
         self._current_plan = ForgePlan(
             id=plan_id,
@@ -656,8 +665,8 @@ class ForgeOrchestrator:
             context=self._forge_context,
             complexity=self._complexity,
             approaches=self._approaches,
-            critic=self._critic_verdict,
-            plan_phases=self._final_phases_from_critic(),
+            critic=self._critic_verdict or CriticVerdict(confidence=0.0),
+            plan_phases=phases,
             goal=self._forge_context.prompt,
             execution_path=execution_path,
             governance=ForgeGovernance(
@@ -665,6 +674,8 @@ class ForgeOrchestrator:
                 quality_gate_required=True,
                 branch_strategy=f"feature/{plan_id}",
             ),
+            degraded=degraded,
+            dispatch_errors=list(self._dispatch_errors),
             status=ForgeStatus.REVIEWING,
         )
 
@@ -700,21 +711,33 @@ class ForgeOrchestrator:
             pass
 
     def _final_phases_from_critic(self) -> list[PlanPhase]:
-        """Build final phases list from critic verdict + constitution enforcement."""
-        phases = []
-        for i, p in enumerate(range(self._critic_verdict.estimated_phases or 3)):
-            phases.append(
-                PlanPhase(
-                    name=f"Phase {i + 1}",
-                    department="dev",
-                )
-            )
-
-        for ep in self._enforced_phases:
-            phases.append(ep)
+        """Build final phases: critic-derived base + constitution enforcement.
 
+        When the critic verdict is missing (dispatch failed) or carries no
+        real content, the base list is EMPTY — the plan then contains only
+        the constitution-enforced phases and is marked degraded downstream.
+        """
+        phases = self._critic_base_phases()
+        phases.extend(self._enforced_phases)
         return phases
 
+    def _critic_base_phases(self) -> list[PlanPhase]:
+        """Phases derived from the critic verdict; [] when absent/empty."""
+        verdict = self._critic_verdict
+        if verdict is None or not self._verdict_has_content(verdict):
+            return []
+        return [
+            PlanPhase(name=f"Phase {i + 1}", department="dev")
+            for i in range(verdict.estimated_phases)
+        ]
+
+    @staticmethod
+    def _verdict_has_content(verdict: CriticVerdict) -> bool:
+        """A verdict counts as real only when it estimated phases AND synthesized something."""
+        return verdict.estimated_phases > 0 and bool(
+            verdict.synthesis or verdict.rejected_elements or verdict.risks
+        )
+
     def _generate_plan_id(self, prompt: str) -> str:
         """Generate a forge plan ID."""
         date = datetime.now(timezone.utc).strftime("%Y%m%d")

package/core/forge/persistence.py

@@ -123,9 +123,25 @@ def _render_obsidian_frontmatter(plan: ForgePlan) -> list[str]:
         f"complexity: {plan.complexity.score}",
         f"created: {plan.created_at or ''}",
     ]
+    if plan.degraded:
+        lines.append("degraded: true")
     if plan.executed_at:
         lines.append(f"executed: {plan.executed_at}")
     lines += ["---", "", f"# {plan.name}", ""]
+    if plan.degraded:
+        lines += _render_obsidian_degraded(plan)
+    return lines
+
+
+def _render_obsidian_degraded(plan: ForgePlan) -> list[str]:
+    """Render the degraded-plan warning block."""
+    lines = [
+        "> [!warning] DEGRADED: explorer/critic dispatch unavailable — "
+        "plan contains only constitution-enforced phases",
+    ]
+    for err in plan.dispatch_errors:
+        lines.append(f"> - {err}")
+    lines.append("")
     return lines
 
 

package/core/forge/renderer.py

@@ -60,6 +60,12 @@ def render_plan_overview(phases: list[PlanPhase], execution_path: ExecutionPath)
     return "\n".join(lines)
 
 
+DEGRADED_NOTICE = (
+    "DEGRADED: explorer/critic dispatch unavailable — "
+    "plan contains only constitution-enforced phases"
+)
+
+
 def render_terminal(plan: ForgePlan) -> str:
     """Render a complete forge plan for terminal display."""
     lines = [
@@ -70,6 +76,10 @@ def render_terminal(plan: ForgePlan) -> str:
         "▸ Complexity Analysis",
         render_complexity(plan.complexity), "",
     ]
+    if plan.degraded:
+        lines.extend([f"⚠ {DEGRADED_NOTICE}"])
+        lines.extend(f"  - {err}" for err in plan.dispatch_errors)
+        lines.append("")
     if plan.critic.confidence > 0:
         lines.extend(["▸ Critic Verdict", render_critic_summary(plan.critic), ""])
     if plan.plan_phases:
@@ -115,6 +125,11 @@ def render_html(plan: ForgePlan) -> str:
     phases_html = _render_phases_html(plan.plan_phases)
     critic_html = _render_critic_html(plan.critic)
     approaches_html = _render_approaches_html(plan.approaches)
+    degraded_html = (
+        f'<p><span class="badge badge-red">⚠ {_esc(DEGRADED_NOTICE)}</span></p>'
+        if plan.degraded
+        else ""
+    )
     ctx = plan.context
     meta = (
         f"{_esc(ctx.repo)} @ {_esc(ctx.commit_at_forge)} | Branch: {_esc(ctx.branch)} "
@@ -128,6 +143,7 @@ def render_html(plan: ForgePlan) -> str:
         f"<style>\n{_COMPANION_CSS}\n</style></head><body>"
         f"<h1>\u2692 {_esc(plan.name)}</h1>"
         f'<div class="meta">{meta}</div>'
+        f"{degraded_html}"
         f'<div class="grid">'
         f'<div class="card"><h2>Complexity Radar</h2>{radar_svg}</div>'
         f'<div class="card"><h2>Critic Verdict</h2>{critic_html}</div>'

package/core/forge/runtime_dispatcher.py

@@ -84,6 +84,29 @@ Be adversarial but constructive. Your job is to stress-test assumptions, not to
 }
 
 
+class ForgeDispatchUnavailableError(RuntimeError):
+    """Raised when Python-side subagent dispatch is attempted.
+
+    Python-side agent dispatch does not exist: there is no in-process
+    bridge to the runtime's Agent/Task tool. The runtime executes the
+    explorer and critic prompts (built by ``_build_explorer_prompt`` /
+    ``_build_critic_prompt``) via the arka-forge SKILL, not via this
+    module. Callers that invoke the dispatcher directly MUST handle
+    degraded planning: no explorer approaches, no critic verdict, and
+    a plan that only carries constitution-enforced phases.
+    """
+
+    def __init__(self, agent_type: str, model: str) -> None:
+        super().__init__(
+            f"Cannot dispatch '{agent_type}' subagent (model={model}): "
+            "Python-side agent dispatch does not exist. The runtime "
+            "executes explorer/critic prompts via the arka-forge SKILL. "
+            "Callers must handle degraded planning."
+        )
+        self.agent_type = agent_type
+        self.model = model
+
+
 @dataclass
 class DispatchResult:
     """Result from a dispatcher call."""
@@ -384,22 +407,23 @@ class ForgeTaskDispatcher(ABC):
 
 
 class ClaudeCodeForgeDispatcher(ForgeTaskDispatcher):
-    """Claude Code implementation using the Task tool with model parameter.
+    """Claude Code dispatcher — prompt builder only, no in-process dispatch.
 
-    Claude Code supports the Agent tool with model routing:
-    - haiku: fast, cost-optimized
-    - sonnet: balanced
-    - opus: highest capability
+    This class builds the full explorer/critic prompts. Actual subagent
+    execution happens in the runtime via the arka-forge SKILL, never in
+    Python. ``_call_agent`` therefore raises
+    ``ForgeDispatchUnavailableError`` — callers must catch it and degrade
+    honestly instead of fabricating results.
     """
 
     def dispatch_explorer(self, request: ExplorerDispatchRequest) -> DispatchResult:
-        """Dispatch explorer using Claude Code's Agent tool."""
+        """Build the explorer prompt and attempt dispatch (raises)."""
         prompt = _build_explorer_prompt(request)
         raw_response = self._call_agent(prompt, model=request.model, agent_type="explorer")
         return DispatchResult(success=True, raw_response=raw_response, output=raw_response)
 
     def dispatch_critic(self, request: CriticDispatchRequest) -> DispatchResult:
-        """Dispatch critic using Claude Code's Agent tool."""
+        """Build the critic prompt and attempt dispatch (raises)."""
         prompt = _build_critic_prompt(request)
         raw_response = self._call_agent(prompt, model=request.model, agent_type="critic")
         return DispatchResult(success=True, raw_response=raw_response, output=raw_response)
@@ -411,20 +435,11 @@ class ClaudeCodeForgeDispatcher(ForgeTaskDispatcher):
         agent_type: str,
         timeout: int = 120,
     ) -> str:
-        """Call the Claude Code Agent tool.
+        """Always raises — Python cannot call the runtime's Agent tool.
 
-        This method should be overridden in tests to mock the actual
-        Task tool call. The real implementation uses the Agent tool
-        from Claude Code's toolkit.
+        Tests may override this method to simulate a working runtime.
         """
-        from agentTool import Agent  # type: ignore
-
-        task_result = Agent(
-            prompt=prompt,
-            model=model,
-            task_type=agent_type,
-        )
-        return task_result.output
+        raise ForgeDispatchUnavailableError(agent_type=agent_type, model=model)
 
 
 def create_dispatcher(runtime: str | None = None) -> ForgeTaskDispatcher:

package/core/forge/schema.py

@@ -206,6 +206,18 @@ class ForgePlan(BaseModel):
 
     governance: ForgeGovernance = Field(default_factory=ForgeGovernance)
 
+    degraded: bool = Field(
+        default=False,
+        description=(
+            "True when explorer/critic dispatch was unavailable — the plan "
+            "contains only constitution-enforced phases and confidence is 0.0."
+        ),
+    )
+    dispatch_errors: List[str] = Field(
+        default_factory=list,
+        description="Dispatch failures collected during forge (lens: error class: message).",
+    )
+
     status: ForgeStatus = ForgeStatus.DRAFT
     approved_at: Optional[str] = None
     approved_by: Optional[str] = None

package/core/governance/closing_marker_check.py

@@ -1,9 +1,10 @@
-"""[arka:phase:13] / [arka:trivial] closing-marker soft-block (PR59 v2.76.0).
+"""Closing-marker soft-block (PR59 v2.76.0; evidence flow v4.1.0).
 
 Response-side classifier. Inspects the closing assistant message of a
-flow-required turn for the mandatory closure marker — either
-``[arka:phase:13]`` (full flow completed) or ``[arka:trivial]``
-(trivial bypass). Mirrors the contract of
+flow-required turn for the mandatory closure marker — ``[arka:gate:4]``
+(evidence flow review gate), the legacy ``[arka:phase:13]`` (accepted
+during the v4.1 deprecation window), or ``[arka:trivial]`` (trivial
+bypass). Mirrors the contract of
 ``core.governance.meta_tag_check`` (PR30 v2.49.0) and
 ``core.governance.kb_cite_check`` (PR18 v2.40.0).
 
@@ -23,12 +24,13 @@ import re
 from dataclasses import dataclass
 
 
+_GATE4_RE: re.Pattern[str] = re.compile(r"\[arka:gate:4\]", re.IGNORECASE)
 _PHASE13_RE: re.Pattern[str] = re.compile(r"\[arka:phase:13\]", re.IGNORECASE)
 _TRIVIAL_RE: re.Pattern[str] = re.compile(r"\[arka:trivial\]", re.IGNORECASE)
 _TRIVIAL_WORD_THRESHOLD: int = 15
 _SUGGESTION_TEXT: str = (
     "Closing marker missing — end every flow-required turn with "
-    "`[arka:phase:13] <label>` (full canonical flow) or "
+    "`[arka:gate:4] <label>` (evidence flow review gate) or "
     "`[arka:trivial] <reason>` (single-file edit < 10 lines, "
     "imperative verb). Without the marker, telemetry can't confirm "
     "the turn closed cleanly."
@@ -52,6 +54,8 @@ def check_closing_marker(response_text: str) -> ClosingMarkerResult:
     marker is found.
     """
     text = response_text or ""
+    if _GATE4_RE.search(text):
+        return ClosingMarkerResult(True, "gate4", None)
     if _PHASE13_RE.search(text):
         return ClosingMarkerResult(True, "phase13", None)
     if _TRIVIAL_RE.search(text):

package/core/governance/compliance_telemetry.py

@@ -4,7 +4,7 @@ Reads the stop-hook entries in ``~/.arkaos/telemetry/enforcement.jsonl``
 and reports compliance with the four contracts the session-start hook
 establishes:
 
-  - closing_marker_found  — [arka:phase:13] or [arka:trivial] present
+  - closing_marker_found  — [arka:gate:4] (or legacy [arka:phase:13]) or [arka:trivial] present
   - meta_tag_found        — [arka:meta] one-liner present (PR12)
   - kb_cite_passed        — KB citation soft block result (PR18)
   - sycophancy clean      — inverse of sycophancy_is_flagged (PR13)

package/core/governance/compliance_telemetry_cli.py

@@ -27,7 +27,7 @@ def _render(summary: ComplianceSummary) -> str:
         "",
         "| Contract | Compliance rate |",
         "|---|---|",
-        f"| `[arka:phase:13]` / `[arka:trivial]` closing marker "
+        f"| `[arka:gate:4]` / `[arka:trivial]` closing marker "
         f"| {_fmt_rate(summary.closing_marker_rate)} |",
         f"| `[arka:meta]` one-liner (PR12 v2.34.0) "
         f"| {_fmt_rate(summary.meta_tag_rate)} |",