@heretek-ai/epistemic-swarm 0.7.13 → 0.7.14

package/schemas/beta_dossier.schema.json

@@ -0,0 +1,214 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "beta_dossier",
+  "type": "object",
+  "required": [
+    "scope_id"
+  ],
+  "properties": {
+    "scope_id": {
+      "type": "string"
+    },
+    "agent": {
+      "type": "string"
+    },
+    "mode": {
+      "type": "string"
+    },
+    "timestamp": {
+      "type": "string"
+    },
+    "negative_knowledge": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "query",
+          "finding"
+        ],
+        "properties": {
+          "query": {
+            "type": "string"
+          },
+          "finding": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "candidate_repositories": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "name"
+        ],
+        "properties": {
+          "repo_id": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "url": {
+            "type": "string"
+          },
+          "source_hash": {
+            "type": "string"
+          },
+          "verbatim_quote": {
+            "type": "string"
+          },
+          "license": {
+            "type": "string"
+          },
+          "license_risk": {
+            "type": "string",
+            "enum": [
+              "SAFE",
+              "COPYLEFT_WARNING",
+              "PROHIBITIVE"
+            ]
+          },
+          "harvest_policy": {
+            "type": "string",
+            "enum": [
+              "depend-or-vendor",
+              "clean-room-rebuild-only"
+            ]
+          },
+          "verdicts": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "feature",
+                "verdict"
+              ],
+              "properties": {
+                "feature": {
+                  "type": "string"
+                },
+                "verdict": {
+                  "type": "string",
+                  "enum": [
+                    "depend",
+                    "vendor",
+                    "clean-room-rebuild",
+                    "skip"
+                  ]
+                },
+                "reason": {
+                  "type": "string"
+                },
+                "verbatim_quote": {
+                  "type": "string"
+                },
+                "effort": {
+                  "type": "string"
+                },
+                "impact": {
+                  "type": "integer"
+                },
+                "differentiation": {
+                  "type": "integer"
+                }
+              }
+            }
+          },
+          "warnings": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "attribution": {
+            "type": "object"
+          }
+        }
+      }
+    },
+    "falsification_claims": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "claim_id",
+          "statement"
+        ],
+        "properties": {
+          "claim_id": {
+            "type": "string"
+          },
+          "tag": {
+            "type": "string",
+            "enum": [
+              "VERIFIED",
+              "INFERRED",
+              "HYPOTHESIS",
+              "NEGATIVE_KNOWLEDGE"
+            ]
+          },
+          "statement": {
+            "type": "string"
+          },
+          "source_hash": {
+            "type": "string"
+          },
+          "source_url": {
+            "type": "string"
+          },
+          "verbatim_quote": {
+            "type": "string"
+          },
+          "severity": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "methodological_critiques": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "target_assertion": {
+            "type": "string"
+          },
+          "critique": {
+            "type": "string"
+          },
+          "evidence_hash": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "hypotheses": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "statement"
+        ],
+        "properties": {
+          "hypothesis_id": {
+            "type": "string"
+          },
+          "claim_id": {
+            "type": "string"
+          },
+          "tag": {
+            "type": "string"
+          },
+          "statement": {
+            "type": "string"
+          },
+          "falsification": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/frontier.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "frontier",
+  "type": "object",
+  "required": [
+    "objective"
+  ],
+  "properties": {
+    "objective": {
+      "type": "string"
+    },
+    "is_complete": {
+      "type": "boolean"
+    },
+    "nodes": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": [
+          "node_id",
+          "question"
+        ],
+        "properties": {
+          "node_id": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "question": {
+            "type": "string"
+          },
+          "recommended": {
+            "type": "string"
+          },
+          "options": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "prerequisites": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "settled_answer": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        }
+      }
+    },
+    "settled_constraints": {
+      "type": "object"
+    }
+  }
+}

package/schemas/manifest.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "manifest",
+  "type": "object",
+  "required": [
+    "session_id",
+    "objective",
+    "status",
+    "scopes"
+  ],
+  "properties": {
+    "session_id": {
+      "type": "string"
+    },
+    "objective": {
+      "type": "string"
+    },
+    "status": {
+      "type": "string"
+    },
+    "created_at": {
+      "type": "string"
+    },
+    "updated_at": {
+      "type": "string"
+    },
+    "plugin_version": {
+      "type": "string"
+    },
+    "backend": {
+      "type": "string"
+    },
+    "preflight": {
+      "type": "object"
+    },
+    "scopes": {
+      "type": "array"
+    },
+    "telemetry": {
+      "type": "object"
+    }
+  }
+}

package/schemas/scope_manifest.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "scope_manifest",
+  "type": "object",
+  "required": [
+    "scope_id",
+    "status"
+  ],
+  "properties": {
+    "scope_id": {
+      "type": "string"
+    },
+    "title": {
+      "type": "string"
+    },
+    "objective": {
+      "type": "string"
+    },
+    "dependencies": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "status": {
+      "type": "string"
+    },
+    "alpha_completed": {
+      "type": "boolean"
+    },
+    "beta_completed": {
+      "type": "boolean"
+    },
+    "audit_completed": {
+      "type": "boolean"
+    },
+    "created_at": {
+      "type": "string"
+    },
+    "outputs": {
+      "type": "array"
+    },
+    "self_reported_epistemic_audit": {
+      "type": "object"
+    }
+  }
+}

package/scripts/check_docs.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""Fail CI when a documentation reference points at a file that does not exist.
+
+Only *repo-relative* paths are checked (a leading known source directory); bare
+names like `manifest.json` or `hasher.py` are workspace-relative and must not be
+flagged. This is the guard for drifts like the recorded
+`skills/grilling/SKILL.md` `--export` reference (issue #6 item 3.11).
+"""
+
+import re
+import sys
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+DOC_FILES = ["README.md", "AGENTS.md", "MARKETPLACE.md"]
+DOC_FILES += [
+    str(p.relative_to(PROJECT_ROOT)) for p in (PROJECT_ROOT / "docs").glob("*.md")
+]
+
+REPO_PREFIXES = (
+    "runner/",
+    "skills/",
+    "scripts/",
+    "plugins/",
+    "prompts/",
+    "config/",
+    "schemas/",
+    "docs/",
+    "extensions/",
+    "hooks/",
+    ".claude-plugin/",
+    ".omp/",
+    ".agents/",
+)
+PATH_RE = re.compile(r"`([A-Za-z0-9_./-]+/[A-Za-z0-9_./-]+)`")
+
+
+def missing_references() -> list:
+    missing = []
+    for rel in DOC_FILES:
+        path = PROJECT_ROOT / rel
+        if not path.exists():
+            continue
+        text = path.read_text(encoding="utf-8")
+        for ref in set(PATH_RE.findall(text)):
+            if any(ch in ref for ch in "{}*"):
+                continue
+            if not ref.startswith(REPO_PREFIXES):
+                continue
+            if not (PROJECT_ROOT / ref.split("#")[0]).exists():
+                missing.append((rel, ref))
+    return sorted(set(missing))
+
+
+def main() -> int:
+    missing = missing_references()
+    if missing:
+        for doc, ref in missing:
+            print(f"❌ {doc}: references missing path `{ref}`", file=sys.stderr)
+        return 1
+    print(f"✅ {len(DOC_FILES)} docs: all repo-relative references resolve.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/gen_schemas.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""Render `schemas/*.schema.json` from `runner/schemas.py`.
+
+Generated, never hand-edited. `--check` regenerates in memory and diffs against
+disk so CI fails on drift (issue #6 item 2.1).
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+from runner.schemas import SCHEMAS  # noqa: E402
+
+SCHEMA_DIR = PROJECT_ROOT / "schemas"
+
+
+def render() -> dict:
+    return {name: schema for name, schema in SCHEMAS.items()}
+
+
+def write_all() -> int:
+    SCHEMA_DIR.mkdir(parents=True, exist_ok=True)
+    for name, schema in SCHEMAS.items():
+        (SCHEMA_DIR / f"{name}.schema.json").write_text(
+            json.dumps(schema, indent=2) + "\n", encoding="utf-8"
+        )
+    return len(SCHEMAS)
+
+
+def check() -> int:
+    errors = []
+    for name, schema in SCHEMAS.items():
+        path = SCHEMA_DIR / f"{name}.schema.json"
+        expected = json.dumps(schema, indent=2) + "\n"
+        if not path.exists():
+            errors.append(f"MISSING schema: {path.relative_to(PROJECT_ROOT)}")
+        elif path.read_text(encoding="utf-8") != expected:
+            errors.append(f"OUT OF SYNC: {path.relative_to(PROJECT_ROOT)}")
+    stray = {p.name for p in SCHEMA_DIR.glob("*.schema.json")} - {
+        f"{n}.schema.json" for n in SCHEMAS
+    }
+    for name in sorted(stray):
+        errors.append(f"STRAY schema (delete or add to runner/schemas.py): {name}")
+    if errors:
+        for e in errors:
+            print(f"❌ {e}", file=sys.stderr)
+        return 1
+    print(f"✅ {len(SCHEMAS)} schemas in sync with runner/schemas.py.")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate IUMBTEMS JSON schemas")
+    parser.add_argument("--check", action="store_true", help="fail on drift")
+    args = parser.parse_args()
+    if args.check:
+        return check()
+    count = write_all()
+    print(f"✅ Wrote {count} schemas to {SCHEMA_DIR.relative_to(PROJECT_ROOT)}/.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/factory/scripts/factory.py

@@ -55,7 +55,10 @@ def run_dir(run):
 def load_state(run):
     p = run_dir(run) / "state.json"
     if not p.exists():
-        raise SystemExit(f"No factory run '{run}'. Run `factory.py init` first.")
+        raise SystemExit(
+            f"No factory run '{run}'. Pass --run <name> (or run "
+            f"`factory.py init --run <name>` first)."
+        )
     return json.loads(p.read_text(encoding="utf-8"))
 
 
@@ -82,6 +85,19 @@ def cmd_phase_add(args):
     state = load_state(args.run)
     if args.phase in state["phases"]:
         raise SystemExit(f"Phase '{args.phase}' already exists.")
+    # Phase output goes to phase.json — a run-state helper must never clobber the
+    # author-written GOAL.md / dossier.json it is meant to track (#6 item 2.3).
+    # This check runs BEFORE any state mutation so a refusal leaves no trace.
+    phase_dir = ROADMAP_DIR / args.phase
+    authored = [
+        name for name in ("GOAL.md", "dossier.json") if (phase_dir / name).exists()
+    ]
+    if authored and not getattr(args, "force", False):
+        raise SystemExit(
+            f"Refusing to touch author-written file(s) in {phase_dir}: "
+            f"{', '.join(authored)}. phase-add now writes phase.json only; "
+            f"re-run with --force to overwrite."
+        )
     state["phases"][args.phase] = {
         "goal": args.goal,
         "acceptance": [a.strip() for a in args.accept.split(";") if a.strip()],
@@ -90,30 +106,52 @@ def cmd_phase_add(args):
         "qa_reports": [],
     }
     save_state(args.run, state)
-    # Phase output: GOAL.md + dossier.json skeleton (evidence filled by manager).
-    phase_dir = ROADMAP_DIR / args.phase
     phase_dir.mkdir(parents=True, exist_ok=True)
-    (phase_dir / "GOAL.md").write_text(
-        f"# {args.phase}: {args.goal}\n\n## Acceptance\n"
-        + "".join(f"- [ ] {a}\n" for a in state["phases"][args.phase]["acceptance"]),
-        encoding="utf-8",
-    )
-    (phase_dir / "dossier.json").write_text(
+    (phase_dir / "phase.json").write_text(
         json.dumps(
             {
                 "phase": args.phase,
                 "goal": args.goal,
-                "evidence": [],
                 "acceptance": state["phases"][args.phase]["acceptance"],
-                "brief": "",
-                "verdict": "briefed",
-                "hashes": [],
+                "status": "briefed",
             },
             indent=2,
         ),
         encoding="utf-8",
     )
-    print(f"✅ Phase '{args.phase}' briefed → {phase_dir}")
+    print(f"✅ Phase '{args.phase}' briefed → {phase_dir / 'phase.json'}")
+
+
+def cmd_gate(args):
+    """First-class gate bookkeeping (open/settle/approve/waive/escalate/count)."""
+    state = load_state(args.run)
+    gates = state.setdefault("gates", {})
+    gate = gates.setdefault(
+        args.phase, {"status": "closed", "cycles": 0, "waivers": [], "history": []}
+    )
+    action = (args.action or "").lower()
+    if action == "open":
+        gate["status"] = "open"
+        gate["cycles"] = gate.get("cycles", 0) + 1
+        state["gate_cycles"] = state.get("gate_cycles", 0) + 1
+    elif action == "settle":
+        gate["status"] = "settled"
+    elif action == "approve":
+        gate["status"] = "approved"
+    elif action == "waive":
+        gate["status"] = "waived"
+        gate["waivers"].append(args.reason or "")
+    elif action == "escalate":
+        gate["status"] = "escalated"
+        gate["cycles"] = gate.get("cycles", 0) + 1
+        state["gate_cycles"] = state.get("gate_cycles", 0) + 1
+    elif action != "count":
+        raise SystemExit(
+            "gate --action must be one of: open, settle, approve, waive, escalate, count"
+        )
+    gate["history"].append({"action": action, "at": now(), "reason": args.reason or ""})
+    save_state(args.run, state)
+    print(json.dumps({"phase": args.phase, "gate": gate}, indent=2))
 
 
 def cmd_qa_record(args):
@@ -211,6 +249,11 @@ def main():
     p.add_argument("--phase", required=True)
     p.add_argument("--goal", required=True)
     p.add_argument("--accept", default="")
+    p.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite author-written GOAL.md/dossier.json if present",
+    )
     _add_common(p)
     p = sub.add_parser("qa-record")
     p.add_argument("--run", required=True)
@@ -227,6 +270,16 @@ def main():
     p = sub.add_parser("stop")
     p.add_argument("--run", required=True)
     _add_common(p)
+    p = sub.add_parser("gate")
+    p.add_argument("--run", required=True)
+    p.add_argument("--phase", required=True)
+    p.add_argument(
+        "--action",
+        required=True,
+        choices=["open", "settle", "approve", "waive", "escalate", "count"],
+    )
+    p.add_argument("--reason", default="")
+    _add_common(p)
 
     args = ap.parse_args()
     root = resolve_project_root(args.project_dir)
@@ -238,6 +291,7 @@ def main():
         "qa-record": cmd_qa_record,
         "expansion": cmd_expansion,
         "stop": cmd_stop,
+        "gate": cmd_gate,
     }[args.command](args)
     sys.exit(code if isinstance(code, int) else 0)
 

package/skills/grilling/SKILL.md

@@ -42,7 +42,20 @@ Always challenge default premises in Round 1:
 
 ## 5. FRONTIER RESOLUTION & FREEZING
 
+The frontier is fully tool-drivable (no hand-written JSON):
+
+```bash
+# author a node (prerequisites gate when it appears on the frontier)
+python3 skills/grilling/socratic_tree.py --add-node --id N1 \
+  --question "L1 or L2 for state verification?" --depends-on ""
+# settle a node
+python3 skills/grilling/socratic_tree.py --settle N1 "L1 for finality"
+# inspect / freeze
+python3 skills/grilling/socratic_tree.py --show-frontier
+python3 skills/grilling/socratic_tree.py --export
+```
+
 When every branch of the design tree has been visited and the frontier is empty:
 1. Summarize the settled constraints.
-2. Save the settled state to `.research/frontier.json` using `python3 skills/grilling/socratic_tree.py --export`.
+2. Freeze the settled state to `.research/frontier.json` (`--export`, default path).
 3. Hand off the settled frontier to the **Swarm Orchestrator** to begin empirical dialectic execution.