@heretek-ai/epistemic-swarm 0.7.10 → 0.7.11

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "epistemic-swarm",
-  "version": "0.7.10",
+  "version": "0.7.11",
   "description": "High-Integrity Dialectic Research Agent Harness for Claude Code enforcing empirical evidence over parametric hallucination.",
   "author": {
     "name": "Heretek AI",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heretek-ai/epistemic-swarm",
-  "version": "0.7.10",
+  "version": "0.7.11",
   "description": "IUMBTEMS (Epistemic Swarm) — High-Integrity Dialectic Research Agent Harness for Claude Code, OpenCode V2, Pi (pi.dev), OMP (oh-my-pi), Gemini CLI, Codex CLI, and AntiGravity",
   "main": "bin/cli.js",
   "bin": {

package/prompts/agent_brainstormer.md

@@ -81,10 +81,11 @@ Write `.research/brainstorm_<slug>.md`:
 <what you deliberately did NOT propose: bug fixes, chores, refactors>
 ```
 
-Also write `alpha_dossier.json`-compatible brainstorm dossier when running
-under `runner/research_swarm.py --mode brainstorm` (claims use tag
-`HYPOTHESIS` with `falsification` field; `VERIFIED` only for ingested
-workspace facts with `file://` pointers and verbatim snippets).
+Also write your **role dossier** as JSON, to the exact path the runner names in
+your task (Agent Alpha → `alpha_dossier.json`, Agent Beta → `beta_dossier.json`).
+It must be dossier-shaped and `scope_id`-keyed; claims use `HYPOTHESIS` with a
+`falsification` field, and `VERIFIED` only for ingested workspace facts with
+`file://` pointers plus verbatim snippets.
 
 ## 4. HARD BANS
 
@@ -95,3 +96,5 @@ workspace facts with `file://` pointers and verbatim snippets).
    `[HYPOTHESIS]` or `[INFERRED: <parents>]`.
 4. No writes outside `.research/`.
 5. No scope creep past 2 dialectic iterations without user confirmation.
+6. Do NOT create or modify `manifest.json` in the scratchpad — it is
+   runner-owned. Emit only your role dossier (and the mode's `.md` artifact).

package/runner/research_swarm.py

@@ -15,7 +15,7 @@ import subprocess
 from pathlib import Path
 from datetime import datetime, timezone
 from concurrent.futures import ThreadPoolExecutor, as_completed
-from typing import Dict, Any, List, Optional, Tuple
+from typing import Dict, Any, List, Optional, Sequence, Tuple
 
 # Ensure project root is in sys.path
 PROJECT_ROOT = Path(__file__).resolve().parent.parent
@@ -45,6 +45,13 @@ KNOWN_BACKEND_BINARIES = {"claude", "opencode", "python", "python3", "node"}
 # the default follows the host; explicit flags/env/config always win.
 OPENCODE_RUN_BASE = ["opencode", "run"]
 
+# Dossier filenames the loader and auditor require, per dialectic role.
+ROLE_DOSSIER_FILENAMES = {"Alpha": "alpha_dossier.json", "Beta": "beta_dossier.json"}
+
+# Additional filenames an agent may emit for a role in a given mode. Kept small
+# and mode-scoped: a complete run must not die on a filename drift.
+MODE_DOSSIER_ALIASES = {"brainstorm": ("brainstorm_dossier.json",)}
+
 # Fenced JSON block marker shared by orchestrator/dossier stdout parsers.
 _JSON_FENCE = "```json"
 
@@ -312,19 +319,22 @@ class SwarmRunner:
         )
 
     def _scope_prompt(self, role: str, scope: Dict[str, Any], scope_id: str) -> str:
-        """Prompt for a dialectic agent, naming the absolute scratchpad dir.
+        """Prompt for a dialectic agent, naming its exact output contract.
 
-        The canonical prompts describe evidence paths RELATIVELY, so a bare
-        scope id left the agent guessing which `.research` tree to write to.
-        Naming the absolute directory removes the ambiguity even when the
-        spawn cwd is overridden.
+        The canonical prompts describe evidence paths RELATIVELY, so a bare scope
+        id left the agent guessing which `.research` tree to write to — and, in
+        brainstorm mode, which dossier filename to emit. Name the absolute
+        scratchpad dir AND the role's dossier file, and forbid writing the
+        runner-owned manifest.
         """
+        scope_dir = self.state_machine.get_scope_dir(scope_id)
+        dossier = ROLE_DOSSIER_FILENAMES.get(role, f"{role.lower()}_dossier.json")
         return (
             f"Run Agent {role} ({self.mode} mode) for scope: {json.dumps(scope)}. "
             f"Engine: {self.engine}. Depth: {self.depth}. "
-            f"Save findings to the scratchpad directory "
-            f"{self.state_machine.get_scope_dir(scope_id)} (scope {scope_id}); "
-            f"write the dossier files there and nowhere else."
+            f"Write your role dossier to {scope_dir / dossier} (scope {scope_id}) "
+            f"and no other dossier file. Do NOT create or modify manifest.json in "
+            f"{scope_dir} — it is runner-owned."
         )
 
     def _resolve_opencode_agent(self, role: str) -> Optional[str]:
@@ -569,24 +579,78 @@ Output ONLY valid JSON representing the scope decomposition conforming to prompt
         """Extract a dossier dict from free-form agent stdout (fence-aware)."""
         return SwarmRunner._parse_json_block(text, require_key="scope_id")
 
+    @staticmethod
+    def _load_dossier_file(path: Path) -> Optional[Dict[str, Any]]:
+        """Load a path as a dossier dict, or None when it is not one."""
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                data = json.load(f)
+        except (OSError, ValueError):
+            return None
+        return data if isinstance(data, dict) and data.get("scope_id") else None
+
+    def _dossier_candidates(
+        self, dossier_path: Path, aliases: Sequence[str]
+    ) -> List[Path]:
+        """Candidate dossier paths: canonical, mode aliases, then manifest outputs.
+
+        Agents in some modes emit a differently named artifact (brainstorm writes
+        `brainstorm_dossier.json`), and the scope manifest may record an `outputs`
+        list. Accepting those keeps a complete run from dying on a filename drift.
+        """
+        scope_dir = dossier_path.parent
+        candidates = [dossier_path]
+        candidates.extend(scope_dir / alias for alias in aliases)
+        manifest_p = scope_dir / "manifest.json"
+        if manifest_p.exists():
+            try:
+                outputs = (
+                    json.loads(manifest_p.read_text(encoding="utf-8")).get("outputs")
+                    or []
+                )
+            except (OSError, ValueError):
+                outputs = []
+            for name in outputs:
+                if isinstance(name, str) and name.endswith(".json"):
+                    candidate = scope_dir / Path(name).name
+                    if candidate.name not in ("manifest.json", "domain_model.json"):
+                        candidates.append(candidate)
+        seen: set = set()
+        unique: List[Path] = []
+        for candidate in candidates:
+            if candidate not in seen:
+                seen.add(candidate)
+                unique.append(candidate)
+        return unique
+
     def _load_agent_dossier(
         self,
         dossier_path: Path,
         scope_id: str,
         role: str,
         transcript: Optional[str] = None,
+        aliases: Sequence[str] = (),
     ) -> Dict[str, Any]:
-        """Load an agent dossier from disk, falling back to stdout parsing.
+        """Load an agent dossier from disk, tolerating mode-specific filenames.
 
-        Headless agents sometimes answer in chat instead of writing the
-        dossier file; without this fallback the whole scope dies on
-        FileNotFoundError (observed live: 10+ minute runs, zero dossiers).
-        Parsed stdout dossiers are tagged so the auditor treats them as
-        recovered, not natively filed.
+        Tries the canonical path, then mode aliases, then the scope manifest's
+        `outputs`. A hit under an alias is normalized to the canonical filename so
+        the auditor and claim index stay consistent. Falls back to parsing the
+        agent's stdout, then raises a diagnostic error naming where it looked.
         """
-        if dossier_path.exists():
-            with open(dossier_path, "r", encoding="utf-8") as f:
-                return json.load(f)
+        for candidate in self._dossier_candidates(dossier_path, aliases):
+            data = self._load_dossier_file(candidate)
+            if data is None:
+                continue
+            if candidate != dossier_path:
+                data.setdefault("renamed_from", candidate.name)
+                dossier_path.parent.mkdir(parents=True, exist_ok=True)
+                _atomic_write_json(dossier_path, data)
+                print(
+                    f"  [{role}] ⚠️ Dossier found as {candidate.name}; "
+                    f"normalized to {dossier_path.name}."
+                )
+            return data
         recovered = self._parse_dossier_json(transcript or "")
         if recovered is not None:
             recovered.setdefault("recovered_from_stdout", True)
@@ -595,18 +659,18 @@ Output ONLY valid JSON representing the scope decomposition conforming to prompt
             print(f"  [{role}] ⚠️ Dossier file missing; recovered from stdout.")
             return recovered
         raise FileNotFoundError(
-            self._dossier_missing_message(dossier_path, scope_id, role)
+            self._dossier_missing_message(dossier_path, scope_id, role, aliases)
         )
 
     def _dossier_missing_message(
-        self, dossier_path: Path, scope_id: str, role: str
+        self, dossier_path: Path, scope_id: str, role: str, aliases: Sequence[str] = ()
     ) -> str:
         """Diagnostic message naming the searched path and any stray copy.
 
         The recurring failure mode is a workspace mismatch: the agent writes the
         dossier to a different `.research` tree than the runner reads. Reporting
         only the searched path made that invisible, so scan the plausible
-        alternates and say where the dossier actually is.
+        alternates — scoped to THIS scope id — and say where the dossier is.
         """
         lines = [
             f"{role} dossier not found at {dossier_path} and no dossier JSON "
@@ -615,10 +679,15 @@ Output ONLY valid JSON representing the scope decomposition conforming to prompt
             f"  spawn cwd/PWD    : {_agent_cwd(self.project_root)}",
             f"  IUMBTEMS_PROJECT_DIR: {os.environ.get('IUMBTEMS_PROJECT_DIR', '(unset)')}",
         ]
-        elsewhere = self._locate_dossier_elsewhere(dossier_path.name)
-        if elsewhere:
+        names = [dossier_path.name, *aliases]
+        found = None
+        for name in names:
+            found = self._locate_dossier_elsewhere(scope_id, name)
+            if found:
+                break
+        if found:
             lines.append(
-                f"  FOUND A COPY ELSEWHERE: {elsewhere} — the spawned agent wrote "
+                f"  FOUND A COPY ELSEWHERE: {found} — the spawned agent wrote "
                 f"to a different workspace than the runner reads"
             )
         else:
@@ -627,8 +696,12 @@ Output ONLY valid JSON representing the scope decomposition conforming to prompt
             )
         return "\n".join(lines)
 
-    def _locate_dossier_elsewhere(self, filename: str) -> Optional[Path]:
-        """Best-effort scan for the dossier in workspaces the agent might have used."""
+    def _locate_dossier_elsewhere(self, scope_id: str, filename: str) -> Optional[Path]:
+        """Find this scope's dossier in a workspace the agent might have used.
+
+        Scoped to `<root>/.research/scratchpads/<scope_id>/` so an unrelated older
+        scope holding a same-named file is never reported as a match.
+        """
         roots: List[Path] = []
         pwd = os.environ.get("PWD", "").strip()
         if pwd:
@@ -654,10 +727,9 @@ Output ONLY valid JSON representing the scope decomposition conforming to prompt
         except (OSError, subprocess.SubprocessError):
             pass
         for root in roots:
-            candidate = root / ".research" / "scratchpads"
-            if candidate.is_dir():
-                for hit in candidate.glob(f"*/{filename}"):
-                    return hit
+            candidate = root / ".research" / "scratchpads" / scope_id / filename
+            if candidate.exists():
+                return candidate
         return None
 
     def run_agent_alpha(self, scope: Dict[str, Any]):
@@ -822,7 +894,11 @@ Output ONLY valid JSON representing the scope decomposition conforming to prompt
                 self.state_machine.get_scope_dir(scope_id) / "alpha_dossier.json"
             )
             dossier = self._load_agent_dossier(
-                dossier_path, scope_id, "alpha", transcript
+                dossier_path,
+                scope_id,
+                "alpha",
+                transcript,
+                aliases=MODE_DOSSIER_ALIASES.get(self.mode, ()),
             )
 
         self.state_machine.record_agent_completion(scope_id, "alpha", dossier)
@@ -1017,7 +1093,11 @@ Output ONLY valid JSON representing the scope decomposition conforming to prompt
                 self.state_machine.get_scope_dir(scope_id) / "beta_dossier.json"
             )
             dossier = self._load_agent_dossier(
-                dossier_path, scope_id, "beta", transcript
+                dossier_path,
+                scope_id,
+                "beta",
+                transcript,
+                aliases=MODE_DOSSIER_ALIASES.get(self.mode, ()),
             )
 
         self.state_machine.record_agent_completion(scope_id, "beta", dossier)
@@ -1108,7 +1188,7 @@ Output ONLY valid JSON representing the scope decomposition conforming to prompt
 
     def _all_scopes_complete(self, manifest: Dict[str, Any]) -> bool:
         return all(
-            self.state_machine.load_scope_manifest(s["scope_id"]).get("status")
+            self.state_machine.reconcile_scope_status(s["scope_id"]).get("status")
             == ScopeStatus.COMPLETE.value
             for s in manifest["scopes"]
         )

package/runner/state_machine.py

@@ -251,32 +251,50 @@ class ResearchStateMachine:
 
         if agent_type.lower() in ["alpha", "thesis", "proponent"]:
             filename = "alpha_dossier.json"
-            is_alpha = True
         elif agent_type.lower() in ["beta", "antithesis", "adversary", "red_team"]:
             filename = "beta_dossier.json"
-            is_alpha = False
         else:
             raise ValueError(f"Unknown agent type: {agent_type}")
 
         _atomic_write_json(scope_dir / filename, dossier_data)
+        self.reconcile_scope_status(scope_id)
 
-        # Alpha and Beta complete concurrently in separate threads: hold the lock
-        # across the read-modify-write so neither loses the other's flag.
+    def _artifacts_complete(self, scope_id: str) -> tuple:
+        """(alpha, beta) dossier presence, derived from disk — never from stored flags."""
+        scope_dir = self.get_scope_dir(scope_id)
+        return (
+            (scope_dir / "alpha_dossier.json").exists(),
+            (scope_dir / "beta_dossier.json").exists(),
+        )
+
+    def reconcile_scope_status(self, scope_id: str) -> Dict[str, Any]:
+        """Recompute completion flags + status from dossier artifacts on disk.
+
+        The scope manifest is runner-owned, but agents can write to the workspace
+        and have forged `beta_completed: true` / `DOSSIERS_READY` without emitting
+        the dossier. Deriving from files means stored booleans can never disagree
+        with reality.
+        """
+        alpha, beta = self._artifacts_complete(scope_id)
         with self._lock, _file_lock(self._lock_file):
             sm = self._read_scope_unlocked(scope_id)
-            if is_alpha:
-                sm["alpha_completed"] = True
-            else:
-                sm["beta_completed"] = True
-
-            if sm.get("alpha_completed") and sm.get("beta_completed"):
+            sm["alpha_completed"] = alpha
+            sm["beta_completed"] = beta
+            if sm.get("audit_completed"):
+                sm["status"] = ScopeStatus.COMPLETE.value
+            elif alpha and beta:
                 sm["status"] = ScopeStatus.DOSSIERS_READY.value
-            elif sm.get("alpha_completed"):
+            elif alpha:
                 sm["status"] = ScopeStatus.ALPHA_COMPLETE.value
-            elif sm.get("beta_completed"):
+            elif beta:
                 sm["status"] = ScopeStatus.BETA_COMPLETE.value
-
+            elif sm.get("status") not in (
+                ScopeStatus.RUNNING_PARALLEL.value,
+                ScopeStatus.AUDITING.value,
+            ):
+                sm["status"] = ScopeStatus.PENDING.value
             self._write_scope_unlocked(scope_id, sm)
+        return sm
 
     def get_ready_scopes(self) -> List[Dict[str, Any]]:
         """Return scopes whose dependencies are completed and status is PENDING."""

package/runner/tests/test_dossier_contract.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+"""Dossier-contract + derived-status regressions.
+
+Reproduced live (#1 retest on 0.7.10, brainstorm mode): the loader required
+`beta_dossier.json`, the shared brainstorm prompt only ever named the
+alpha-compatible dossier, so Beta emitted `brainstorm_dossier.json` and the run
+aborted — while the scope manifest (written by the agent) claimed
+`DOSSIERS_READY`. These tests pin both halves: an explicit role contract plus a
+tolerant loader, and status derived from artifacts rather than stored booleans.
+"""
+
+import json
+import os
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+from runner.research_swarm import SwarmRunner  # noqa: E402
+from runner.state_machine import ResearchStateMachine, ScopeStatus  # noqa: E402
+
+
+def _write_json(path: Path, data: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data), encoding="utf-8")
+
+
+class TestRoleOutputContract(unittest.TestCase):
+    def _runner(self, base: Path, mode: str = "brainstorm") -> SwarmRunner:
+        return SwarmRunner(base_dir=base, mock_mode=True, mode=mode)
+
+    def test_prompt_names_role_dossier_and_bans_manifest(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            base = Path(tmp) / ".research"
+            runner = self._runner(base)
+            scope = {"scope_id": "s1", "title": "t", "objective": "o"}
+
+            alpha = runner._scope_prompt("Alpha", scope, "s1")
+            beta = runner._scope_prompt("Beta", scope, "s1")
+
+            self.assertIn(
+                str(runner.state_machine.get_scope_dir("s1") / "alpha_dossier.json"),
+                alpha,
+            )
+            self.assertIn(
+                str(runner.state_machine.get_scope_dir("s1") / "beta_dossier.json"),
+                beta,
+            )
+            self.assertNotIn("beta_dossier.json", alpha)
+            for text in (alpha, beta):
+                self.assertIn("manifest.json", text)
+                self.assertIn("runner-owned", text)
+
+
+class TestTolerantLoader(unittest.TestCase):
+    def test_alias_is_loaded_and_normalized(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            base = Path(tmp) / ".research"
+            runner = SwarmRunner(base_dir=base, mock_mode=True, mode="brainstorm")
+            scope_dir = runner.state_machine.get_scope_dir("s1")
+            _write_json(
+                scope_dir / "brainstorm_dossier.json", {"scope_id": "s1", "claims": []}
+            )
+
+            data = runner._load_agent_dossier(
+                scope_dir / "beta_dossier.json",
+                "s1",
+                "beta",
+                None,
+                aliases=("brainstorm_dossier.json",),
+            )
+            self.assertEqual(data["scope_id"], "s1")
+            self.assertEqual(data["renamed_from"], "brainstorm_dossier.json")
+            self.assertTrue((scope_dir / "beta_dossier.json").exists())
+
+    def test_manifest_outputs_are_consulted(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            base = Path(tmp) / ".research"
+            runner = SwarmRunner(base_dir=base, mock_mode=True, mode="brainstorm")
+            scope_dir = runner.state_machine.get_scope_dir("s1")
+            _write_json(scope_dir / "weird_name.json", {"scope_id": "s1", "claims": []})
+            _write_json(
+                scope_dir / "manifest.json",
+                {"scope_id": "s1", "outputs": ["weird_name.json"]},
+            )
+
+            data = runner._load_agent_dossier(
+                scope_dir / "beta_dossier.json", "s1", "beta", None
+            )
+            self.assertEqual(data["scope_id"], "s1")
+            self.assertTrue((scope_dir / "beta_dossier.json").exists())
+
+    def test_non_dossier_json_is_ignored(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            base = Path(tmp) / ".research"
+            runner = SwarmRunner(base_dir=base, mock_mode=True, mode="brainstorm")
+            scope_dir = runner.state_machine.get_scope_dir("s1")
+            # domain_model.json has no scope_id and must never be taken as a dossier.
+            _write_json(scope_dir / "manifest.json", {"outputs": ["domain_model.json"]})
+            _write_json(scope_dir / "domain_model.json", {"entities": ["a"]})
+
+            with self.assertRaises(FileNotFoundError):
+                runner._load_agent_dossier(
+                    scope_dir / "beta_dossier.json", "s1", "beta", None
+                )
+
+
+class TestDerivedStatus(unittest.TestCase):
+    def test_forged_manifest_cannot_report_ready(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            base = Path(tmp) / ".research"
+            sm = ResearchStateMachine(base_dir=base)
+            sm.init_session("x")
+            sm.set_scopes([{"scope_id": "s1", "title": "t", "objective": "o"}])
+            scope_dir = sm.get_scope_dir("s1")
+
+            # Agent pretends both dossiers exist.
+            _write_json(
+                scope_dir / "manifest.json",
+                {
+                    "scope_id": "s1",
+                    "status": ScopeStatus.DOSSIERS_READY.value,
+                    "alpha_completed": True,
+                    "beta_completed": True,
+                },
+            )
+            sm.reconcile_scope_status("s1")
+            sm_after = sm.load_scope_manifest("s1")
+            self.assertFalse(sm_after["alpha_completed"])
+            self.assertFalse(sm_after["beta_completed"])
+            self.assertNotEqual(sm_after["status"], ScopeStatus.DOSSIERS_READY.value)
+
+    def test_status_derives_from_artifacts(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            base = Path(tmp) / ".research"
+            sm = ResearchStateMachine(base_dir=base)
+            sm.init_session("x")
+            sm.set_scopes([{"scope_id": "s1", "title": "t", "objective": "o"}])
+            scope_dir = sm.get_scope_dir("s1")
+
+            sm.record_agent_completion("s1", "alpha", {"scope_id": "s1", "claims": []})
+            self.assertEqual(
+                sm.load_scope_manifest("s1")["status"], ScopeStatus.ALPHA_COMPLETE.value
+            )
+
+            sm.record_agent_completion("s1", "beta", {"scope_id": "s1", "claims": []})
+            after = sm.load_scope_manifest("s1")
+            self.assertEqual(after["status"], ScopeStatus.DOSSIERS_READY.value)
+            self.assertTrue(after["alpha_completed"] and after["beta_completed"])
+
+            # audit completion survives reconciliation
+            after["audit_completed"] = True
+            sm.save_scope_manifest("s1", after)
+            self.assertEqual(
+                sm.reconcile_scope_status("s1")["status"], ScopeStatus.COMPLETE.value
+            )
+            self.assertTrue(scope_dir.exists())
+
+
+class TestScopedAlternateScan(unittest.TestCase):
+    def test_only_same_scope_is_reported(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            project = Path(tmp)
+            alt = project / "alt"
+            base = project / ".research"
+            runner = SwarmRunner(base_dir=base, mock_mode=True, mode="research")
+
+            # Different scope holds the same filename.
+            _write_json(
+                alt / ".research" / "scratchpads" / "scope_other" / "beta_dossier.json",
+                {"scope_id": "scope_other"},
+            )
+            with mock.patch.dict(os.environ, {"PWD": str(alt)}, clear=False):
+                self.assertIsNone(
+                    runner._locate_dossier_elsewhere("scope_mine", "beta_dossier.json")
+                )
+
+            # Same scope in the alternate workspace is reported.
+            target = (
+                alt / ".research" / "scratchpads" / "scope_mine" / "beta_dossier.json"
+            )
+            _write_json(target, {"scope_id": "scope_mine"})
+            with mock.patch.dict(os.environ, {"PWD": str(alt)}, clear=False):
+                self.assertEqual(
+                    runner._locate_dossier_elsewhere("scope_mine", "beta_dossier.json"),
+                    target,
+                )
+
+
+if __name__ == "__main__":
+    unittest.main()