procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/agents/procesio/knowledge.py

@@ -0,0 +1,115 @@
+"""Load the agent's knowledge base (the markdown docs in this folder).
+
+The `guidance` action serves these so any session/LLM loads the methodology from
+ONE registry-discoverable place instead of re-deriving it. The docs are the
+source of truth; this module just reads them.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+KB_DIR = Path(__file__).resolve().parent
+
+# The form-building guide lives beside the TOOL it documents (form DTO, event config,
+# field paths), not in this folder. Serving it from here rather than copying it keeps
+# one source of truth: a 100 KB guide duplicated into the agent would be stale within a
+# release, and the version the model reads is the one that would be wrong.
+FORM_GUIDE = KB_DIR.parents[1] / "tools" / "procesio" / "FORM-DEV-GUIDE"
+
+# The house style, distilled from auditing a production workspace: HOW this team builds,
+# where the best-practices doc says WHAT good looks like. Served per file like the form
+# guide (~80 KB together); `patterns` is the index and names the rest.
+PATTERNS = KB_DIR / "IMPLEMENTATION-PATTERNS"
+
+# topic -> (path relative to KB_DIR, or an absolute Path; human label)
+TOPICS: dict[str, tuple[str | Path, str]] = {
+    "playbook": ("PROCESIO-BUILD-AND-TEST-PLAYBOOK.md",
+                 "Build-and-test operating procedure"),
+    "best-practices": ("PROCESIO-BEST-PRACTICES.md",
+                       "PROCESIO implementation best practices"),
+    "visual-organization": ("PROCESIO-VISUAL-ORGANIZATION.md",
+                            "Visual canvas layout + recurring build patterns"),
+    "datastore": ("PROCESIO-DATASTORE.md",
+                  "Data Store module: API actions, process node, form trigger"),
+    "scheduling": ("PROCESIO-SCHEDULING.md",
+                   "Scheduling a process (recurrences + crontab)"),
+    "environments": ("PROCESIO-ENVIRONMENTS.md",
+                     "Working across PROCESIO environments (switch/add <Client>-<ENV>)"),
+    "reliability": ("PROCESIO-API-RELIABILITY-DOCTRINE.md",
+                    "Driving the PROCESIO Web API safely: sequential calls, "
+                    "behavioural verification, deadlines/retries, form-build traps"),
+    "boundary": ("README.md", "Agent knowledge base + tool-vs-agent boundary"),
+
+    # Building a FORM is a different discipline from building a process, and asking for
+    # it returned `unknown topic` - so an agent that needed the field-path shape, the
+    # event contract or the known traps had no way to reach the guide that documents
+    # all three. Measured cost of that gap in one run: a RUN_PROCESS map written with
+    # invented paths ("root.fields.<id>.value" instead of the four-GUID chain) and the
+    # two sides transposed, which the API accepts silently and which binds nothing.
+    #
+    # Served as ONE entry per guide file rather than a single `forms` blob: the guide is
+    # ~100 KB, over the character budget a run carries forward, so a single topic would
+    # be an answer no step could keep. `forms` is the index, which names the rest.
+    "forms": (FORM_GUIDE / "00-INDEX.md",
+              "Form development guide - START HERE, names the sub-topics below"),
+    "forms-anatomy": (FORM_GUIDE / "01-ANATOMY.md",
+                      "Form anatomy: elements, config ids, the field VALUE PATH"),
+    "forms-code": (FORM_GUIDE / "02-CODE-INJECTION.md",
+                   "Injecting custom code into a form"),
+    "forms-dom": (FORM_GUIDE / "03-DOM-CONTRACT.md",
+                  "The rendered DOM contract a form's code may rely on"),
+    "forms-interaction": (FORM_GUIDE / "04-INTERACTION-RECIPES.md",
+                          "Interaction recipes: show/hide, validation, computed fields"),
+    "forms-motion": (FORM_GUIDE / "05-STEPPER-AND-MOTION.md",
+                     "Multi-step forms (stepper) and motion"),
+    "forms-process": (FORM_GUIDE / "06-PROCESS-INTEGRATION.md",
+                      "Wiring a control to a process: RUN_PROCESS event, inputMap/"
+                      "outputMap row shape, form value paths"),
+    "forms-deploy": (FORM_GUIDE / "07-DEPLOY-WORKFLOW.md",
+                     "Publishing a form and its custom URL"),
+    "forms-pitfalls": (FORM_GUIDE / "08-PITFALLS.md",
+                       "Known form traps and their signatures"),
+
+    "patterns": (PATTERNS / "00-INDEX.md",
+                 "House implementation patterns - START HERE, names the sub-topics + the "
+                 "workspace-knowledge folder convention"),
+    "patterns-processes": (PATTERNS / "01-PROCESSES.md",
+                           "How we build processes: result flags, HTML rendering, Node idioms, utilities"),
+    "patterns-forms": (PATTERNS / "02-FORMS.md",
+                       "How we build forms and form<->process communication"),
+    "patterns-integrations": (PATTERNS / "03-INTEGRATIONS.md",
+                              "How we build integrations: webhooks, ERP, SFTP, LLM extraction, documents"),
+    "patterns-database": (PATTERNS / "04-DATABASE.md",
+                          "How we design tables and stored procedures for PROCESIO"),
+}
+
+# `topic=all` concatenates everything it lists, so the form guide's chapters stay out of
+# it: they would multiply that payload sixfold and bury the process guidance most callers
+# actually asked for. The `forms` index IS included - it is small and it advertises the
+# chapters, which is exactly what a caller who did not know they existed needs.
+_ALL_EXCLUDED = {t for t in TOPICS if t.startswith(("forms-", "patterns-"))}
+
+
+def topics() -> list[str]:
+    return list(TOPICS.keys())
+
+
+def load(topic: str) -> dict:
+    if topic not in TOPICS:
+        raise KeyError(
+            f"unknown topic: {topic}. Known: {', '.join(TOPICS)}")
+    filename, label = TOPICS[topic]
+    path = filename if isinstance(filename, Path) else KB_DIR / filename
+    if not path.exists():
+        raise FileNotFoundError(f"knowledge file missing: {path}")
+    return {
+        "topic": topic,
+        "label": label,
+        "source": str(path),
+        "content": path.read_text(encoding="utf-8"),
+    }
+
+
+def load_all() -> list[dict]:
+    """Every topic that belongs in a `topic=all` answer (see _ALL_EXCLUDED)."""
+    return [load(t) for t in TOPICS if t not in _ALL_EXCLUDED]

procesio_cli/agents/procesio/main.py

@@ -0,0 +1,89 @@
+"""procesio agent entrypoint - action dispatch.
+
+Drives the `procesio` tool (and, in later slices, web + google-* for forms and
+deliverables) to create, verify, and audit PROCESIO resources. Invoked exactly
+like an action-dispatch tool: action name first, JSON in / JSON out. It is the
+executable side of the build-and-test playbook in this folder.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+AGENT_ROOT = Path(__file__).resolve().parent
+FRAMEWORK_ROOT = AGENT_ROOT.parents[1]
+# .venv layout is per-OS: Scripts/python.exe on Windows, bin/python everywhere else.
+_VENV_PY = (FRAMEWORK_ROOT / ".venv" / "Scripts" / "python.exe" if sys.platform == "win32"
+            else FRAMEWORK_ROOT / ".venv" / "bin" / "python")
+if _VENV_PY.exists() and Path(sys.executable).resolve() != _VENV_PY.resolve():
+    import subprocess
+    sys.exit(subprocess.run([str(_VENV_PY), __file__, *sys.argv[1:]]).returncode)
+
+import argparse  # noqa: E402
+
+if str(FRAMEWORK_ROOT) not in sys.path:
+    sys.path.insert(0, str(FRAMEWORK_ROOT))
+
+from tools._lib.io import emit, fail  # noqa: E402
+from agents._lib import errors  # noqa: E402
+from agents._lib.actiondef import ActionDef  # noqa: E402
+
+
+class _Parser(argparse.ArgumentParser):
+    def error(self, message: str):
+        raise errors.UsageError(message)
+
+
+def collect_actions() -> dict[str, ActionDef]:
+    actions: dict[str, ActionDef] = {}
+    from agents.procesio.handlers import (status, guidance, checklist as checklist_h,
+                                          verify as verify_h, audit as audit_h)
+    actions.update(status.ACTIONS)
+    actions.update(guidance.ACTIONS)
+    actions.update(checklist_h.ACTIONS)
+    actions.update(verify_h.ACTIONS)
+    actions.update(audit_h.ACTIONS)
+    return actions
+
+
+ACTIONS = collect_actions()
+
+
+def _build_context():
+    from agents.procesio.context import ProcesioContext
+    return ProcesioContext.create()
+
+
+def dispatch(action: str, argv: list[str], *, context_builder=None) -> dict:
+    if action not in ACTIONS:
+        raise errors.UsageError(
+            f"unknown action: {action}. Known: {', '.join(sorted(ACTIONS))}")
+    defn = ACTIONS[action]
+    parser = _Parser(prog=f"procesio {action}", description=defn.description)
+    defn.add_args(parser)
+    parsed = parser.parse_args(argv)
+    if defn.context:
+        builder = context_builder or _build_context
+        ctx = builder()
+        return defn.func(ctx, parsed)
+    return defn.func(parsed)
+
+
+def main(argv=None) -> None:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if not argv or argv[0] in ("-h", "--help"):
+        print("Actions:", file=sys.stderr)
+        for name in sorted(ACTIONS):
+            print(f"  {name:<12} {ACTIONS[name].description}", file=sys.stderr)
+        sys.exit(0)
+    action, rest = argv[0], argv[1:]
+    try:
+        result = dispatch(action, rest)
+    except Exception as exc:  # noqa: BLE001
+        code, message, details, exit_code = errors.classify(exc)
+        fail(code, message, details, exit_code)
+    emit(result)
+
+
+if __name__ == "__main__":
+    main()

procesio_cli/agents/procesio/tests/conftest.py

@@ -0,0 +1,62 @@
+"""Fixtures for the PROCESIO agent tests. Zero live calls: the tool invoker is a
+recording fake, Credential Manager is never touched.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+FRAMEWORK_ROOT = Path(__file__).resolve().parents[3]
+if str(FRAMEWORK_ROOT) not in sys.path:
+    sys.path.insert(0, str(FRAMEWORK_ROOT))
+
+
+@pytest.fixture(autouse=True)
+def _no_keyring(monkeypatch):
+    from tools._lib import creds
+    monkeypatch.setattr(creds, "get_optional", lambda tool, name: None)
+    monkeypatch.setattr(creds, "has", lambda tool, name: False)
+
+
+class FakeInvoke:
+    """Drop-in for toolrunner.invoke: __call__(tool, action, *args) -> dict.
+
+    Map an action name to the dict it should return, or to a ToolError instance
+    to simulate a tool failure. Records every call for assertions.
+    """
+
+    def __init__(self):
+        self.calls: list[tuple[str, str, list]] = []
+        self._map: dict[str, object] = {}
+
+    def set(self, action: str, value) -> "FakeInvoke":
+        self._map[action] = value
+        return self
+
+    def __call__(self, tool: str, action: str, *args):
+        self.calls.append((tool, action, list(args)))
+        v = self._map.get(action, {})
+        if isinstance(v, Exception):
+            raise v
+        return v
+
+
+@pytest.fixture
+def fake_invoke():
+    return FakeInvoke()
+
+
+def flow(actions, *, title="T", description="") -> dict:
+    """Build a get-process style envelope around a flow with these actions."""
+    return {"result": {"flow": {
+        "Title": title, "Description": description, "Actions": actions}}}
+
+
+def action(template, *, params=None, settings=None, name=None) -> dict:
+    a = {"ActionName": name or template, "ActionTemplateName": template,
+         "Parameters": params or []}
+    if settings is not None:
+        a["CustomData"] = {"configuration": [{"settings": settings}]}
+    return a

procesio_cli/agents/procesio/tests/test_audit.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from agents.procesio import audit
+from agents.procesio.tests.conftest import action
+
+START = action("Start")
+STOP = action("Stop")
+
+
+def _codes(findings):
+    return {f["code"] for f in findings}
+
+
+def test_clean_process_has_no_correctness_findings():
+    configured = action("Add", params=[{"Value": "x", "Variable": []}],
+                        settings=[{"value": "x"}])
+    flow = {"Title": "Clean", "Description": "does a thing",
+            "Actions": [START, configured, STOP]}
+    assert audit.correctness_findings(flow) == []
+
+
+def test_designer_blank_is_flagged_as_correctness_warn():
+    # runtime Parameters set, designer configuration empty -> the documented bug
+    blank = action("Send Email", params=[{"Value": "<%0%>", "Variable": [{"id": 0}]}],
+                   settings=[{"value": ""}])
+    flow = {"Actions": [START, blank, STOP]}
+    cf = audit.correctness_findings(flow)
+    assert "designer-blank" in _codes(cf)
+    assert all(f["severity"] in ("warn", "fail") for f in cf)
+
+
+def test_datastore_masquerade_flagged_as_fail():
+    # a Call API node NAMED like a cache op is the FX-usecase bug: it never touches
+    # the Data Store, but the process still runs green.
+    masq = action("Call API", name="Cache read")
+    flow = {"Actions": [START, masq, STOP]}
+    cf = audit.correctness_findings(flow)
+    hits = [f for f in cf if f["code"] == "datastore-as-callapi"]
+    assert hits and hits[0]["severity"] == "fail"
+    assert hits[0]["action"] == "Cache read"
+
+
+def test_real_datastore_node_and_plain_callapi_not_flagged():
+    real_cache = action("Data Store", name="Cache read",
+                        params=[{"Value": "x"}], settings=[{"value": "x"}])
+    plain_api = action("Call API", name="Fetch BNR XML",
+                       params=[{"Value": "https://bnr.ro"}], settings=[{"value": "url"}])
+    flow = {"Actions": [START, real_cache, plain_api, STOP]}
+    assert "datastore-as-callapi" not in _codes(audit.correctness_findings(flow))
+
+
+def test_practice_smells_flagged():
+    acts = [START, STOP]
+    acts += [action("Call API"), action("SQL Server"), action("Decisional")]
+    acts += [action(f"Add{i}", params=[{"Value": "1"}], settings=[{"value": "1"}])
+             for i in range(4)]  # push count over 5
+    flow = {"Title": "Heavy", "Description": "", "Actions": acts}
+    rep = audit.audit_process(flow)
+    codes = _codes(rep["findings"])
+    assert "high-action-count" in codes
+    assert "slow-actions" in codes
+    assert "missing-description" in codes
+    assert rep["summary"]["nonstructural_action_count"] == 7
+
+
+def test_audit_handles_live_camelcase_shape():
+    # the LIVE Web-API returns camelCase; the auditor must work on it, not just
+    # PascalCase export goldens (regression: live audit found 0 actions before ci()).
+    flow = {"title": "Live", "description": "", "actions": [
+        {"actionTemplateName": "Start", "parameters": []},
+        {"actionName": "notify", "actionTemplateName": "Send Email",
+         "parameters": [{"value": "<%0%>", "variable": [{"id": 0}]}],
+         "customData": {"configuration": [{"settings": [{"value": ""}]}]}},
+        {"actionTemplateName": "Stop", "parameters": []}]}
+    rep = audit.audit_process(flow)
+    assert rep["summary"]["nonstructural_action_count"] == 1
+    assert rep["summary"]["title"] == "Live"
+    assert "designer-blank" in _codes(rep["findings"])
+
+
+def test_inline_secret_flagged_but_guid_credential_is_not():
+    secret = action("Connect", params=[{"Value": "p@ssw0rd-secret-value", "Variable": []}])
+    credid = action("Send Email",
+                    params=[{"Value": "2aacf4f1-310c-469f-80ef-394d6ab9582f", "Variable": []}])
+    flow = {"Actions": [START, secret, credid, STOP]}
+    codes = _codes(audit.audit_process(flow)["findings"])
+    assert "possible-inline-secret" in codes
+    # the credential GUID literal must NOT be mistaken for a secret
+    secret_findings = [f for f in audit.audit_process(flow)["findings"]
+                       if f["code"] == "possible-inline-secret"]
+    assert all(f["action"] != "Send Email" for f in secret_findings)

procesio_cli/agents/procesio/tests/test_checklist.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from agents.procesio import checklist as cl
+
+
+def test_all_steps_have_required_keys():
+    keys = {"id", "phase", "title", "how", "tool", "automatable", "citation"}
+    for s in cl.STEPS:
+        assert keys <= set(s), f"{s.get('id')} missing {keys - set(s)}"
+        assert s["phase"] in cl.PHASES
+
+
+def test_phase_filter():
+    val = cl.steps(phase="validate")
+    assert val and all(s["phase"] == "validate" for s in val)
+
+
+def test_automatable_only_is_subset():
+    auto = cl.steps(automatable_only=True)
+    assert auto and all(s["automatable"] for s in auto)
+    assert len(auto) < len(cl.STEPS)  # there are genuine manual steps too
+
+
+def test_manual_steps_are_the_non_automatable_ones():
+    manual = cl.manual_steps()
+    assert manual and all(not s["automatable"] for s in manual)
+    # the real-browser form check must be in the manual set - it cannot be automated
+    assert "form-behavior" in {s["id"] for s in manual}

procesio_cli/agents/procesio/tests/test_guidance.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from agents.procesio import knowledge
+
+
+def test_topics_present():
+    assert set(knowledge.topics()) == {
+        "playbook", "best-practices", "visual-organization", "datastore",
+        "scheduling", "environments", "reliability", "boundary",
+        "forms", "forms-anatomy", "forms-code", "forms-dom", "forms-interaction",
+        "forms-motion", "forms-process", "forms-deploy", "forms-pitfalls",
+        "patterns", "patterns-processes", "patterns-forms", "patterns-integrations",
+        "patterns-database"}
+
+
+def test_each_topic_loads_real_content():
+    for t in knowledge.topics():
+        doc = knowledge.load(t)
+        assert doc["content"].strip(), f"{t} empty"
+        assert Path(doc["source"]).exists()
+        assert doc["topic"] == t
+
+
+def test_all_excludes_the_form_chapters_but_keeps_their_index():
+    """`topic=all` is a payload a run carries forward under a character budget. The
+    form guide is ~100 KB across nine files; folding it in would evict the process
+    guidance most callers asked for. The index is small and advertises the rest."""
+    served = {d["topic"] for d in knowledge.load_all()}
+    assert "forms" in served
+    assert not [t for t in served if t.startswith(("forms-", "patterns-"))]
+    assert "patterns" in served
+    assert sum(len(d["content"]) for d in knowledge.load_all()) < 100_000
+
+
+def test_the_form_chapters_are_reachable_one_at_a_time():
+    for t in ("forms-anatomy", "forms-process", "forms-pitfalls"):
+        assert knowledge.load(t)["content"].strip()
+
+
+def test_the_form_index_names_the_chapters_a_caller_must_ask_for():
+    """The index is the only form topic in `all`, so it has to be the map: a caller
+    that lands there must learn the sub-topics exist without a second guess."""
+    body = knowledge.load("forms")["content"]
+    for chapter in ("ANATOMY", "PROCESS-INTEGRATION", "PITFALLS"):
+        assert chapter in body
+
+
+def test_the_process_integration_chapter_carries_the_map_row_contract():
+    """This is the fact the gap actually cost: a RUN_PROCESS map row's two sides are
+    objects with DIFFERENT shapes, and the form side's path is a four-GUID chain, not
+    a readable pseudo-path. If this ever stops being served, the guide is not doing
+    the one job it was registered for."""
+    body = knowledge.load("forms-process")["content"]
+    assert "inputMap" in body and "outputMap" in body
+    assert "11223344-5566-7788-99aa-aabbccddeeff" in body       # the FIELDS_NS constant
+    assert "isList" in body                                      # the row object shape
+
+
+def test_unknown_topic_raises():
+    with pytest.raises(KeyError):
+        knowledge.load("nope")
+
+
+def test_implementation_patterns_carry_no_workspace_data():
+    """Hard rule 10: the patterns are framework files read by other teams. They were
+    distilled from one client's workspace, so guard the obvious leaks: GUIDs, e-mail
+    addresses and connection strings."""
+    import re
+    for t in ("patterns", "patterns-processes", "patterns-forms", "patterns-integrations",
+              "patterns-database"):
+        text = knowledge.load(t)["content"]
+        assert not re.search(r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}", text), t
+        assert not re.search(r"[\w.-]+@[\w-]+\.[a-z]{2,}", text), t
+        assert not re.search(r"(?i)password\s*=|pwd=\w", text), t

procesio_cli/agents/procesio/tests/test_manifest_sync.py

@@ -0,0 +1,48 @@
+"""Guard: agent.yaml must declare exactly the actions the dispatcher registers,
+the per-action args must match, and every driven tool must be registered.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from tools._lib.manifest import load_agent
+from agents.procesio import main
+
+
+def _manifest():
+    agent_root = Path(main.__file__).resolve().parent
+    return load_agent(agent_root / "agent.yaml")
+
+
+def test_manifest_actions_match_dispatch():
+    m = _manifest()
+    assert set(m.action_names()) == set(main.ACTIONS), (
+        f"only in manifest: {set(m.action_names()) - set(main.ACTIONS)}; "
+        f"only in code: {set(main.ACTIONS) - set(m.action_names())}")
+
+
+def test_expected_actions_registered():
+    assert set(main.ACTIONS) == {
+        "status", "guidance", "checklist", "verify", "audit"}
+
+
+def test_declared_tools_are_registered():
+    from registry import get_tool
+    for tool_name in _manifest().tools:
+        get_tool(tool_name)  # raises KeyError if missing
+
+
+def test_manifest_args_match_dispatch():
+    """Each action's manifest args (kebab) must match the argparse flags the
+    handler registers (so the contract cannot drift from the code)."""
+    import argparse
+    m = _manifest()
+    for name, defn in main.ACTIONS.items():
+        parser = argparse.ArgumentParser()
+        defn.add_args(parser)
+        code_args = {a.dest.replace("_", "-") for a in parser._actions
+                     if a.dest not in ("help",)}
+        spec = m.get_action(name)
+        manifest_args = {a.name for a in spec.args}
+        assert manifest_args == code_args, (
+            f"{name}: manifest {manifest_args} != code {code_args}")

procesio_cli/agents/procesio/tests/test_verify.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+from agents._lib.toolrunner import ToolError
+from agents.procesio import verifylib
+from agents.procesio.tests.conftest import action, flow
+
+START = action("Start")
+STOP = action("Stop")
+CONFIGURED = action("Add", params=[{"Value": "x", "Variable": []}],
+                    settings=[{"value": "x"}])
+
+
+def _check(report, cid):
+    return next(c for c in report["checks"] if c["id"] == cid)
+
+
+def test_clean_process_passes_without_run(fake_invoke):
+    fake_invoke.set("get-process", flow([START, CONFIGURED, STOP]))
+    fake_invoke.set("request", {"result": {"isValid": True}})
+    rep = verifylib.verify_process(fake_invoke, "pid")
+    assert rep["verdict"] == "pass"
+    assert _check(rep, "validate-process")["status"] == "pass"
+    assert _check(rep, "config-parity-audit")["status"] == "pass"
+    assert _check(rep, "run-instance")["status"] == "skip"
+    # manual checks must always be surfaced
+    assert any(s["id"] == "form-behavior" for s in rep["manual_checks"])
+
+
+def test_designer_blank_drops_verdict_to_warn(fake_invoke):
+    blank = action("Send Email", params=[{"Value": "<%0%>", "Variable": [{"id": 0}]}],
+                   settings=[{"value": ""}])
+    fake_invoke.set("get-process", flow([START, blank, STOP]))
+    fake_invoke.set("request", {"result": {"isValid": True}})
+    rep = verifylib.verify_process(fake_invoke, "pid")
+    assert rep["verdict"] == "warn"
+    assert _check(rep, "config-parity-audit")["status"] == "warn"
+
+
+def test_validate_sends_flow_via_body_file_not_inline(fake_invoke):
+    # regression: a large flow passed as inline --body overflows the OS command line
+    # (Windows WinError 206 / POSIX E2BIG) and crashed the gate. The validate call must
+    # use --body-file, never --body.
+    fake_invoke.set("get-process", flow([START, CONFIGURED, STOP]))
+    fake_invoke.set("request", {"result": {"isValid": True}})
+    verifylib.verify_process(fake_invoke, "pid")
+    req = next(c for c in fake_invoke.calls
+               if c[0] == "procesio" and c[1] == "request" and "/api/Projects/validate" in c[2])
+    assert "--body-file" in req[2]
+    assert "--body" not in req[2]
+
+
+def test_datastore_masquerade_hard_fails_the_gate(fake_invoke):
+    # a Call-API node named like a cache op is a hard defect (severity fail), so the
+    # config-parity check and the whole verdict must be `fail`, not merely `warn`.
+    masq = action("Call API", name="Cache read")
+    fake_invoke.set("get-process", flow([START, masq, STOP]))
+    fake_invoke.set("request", {"result": {"isValid": True}})
+    rep = verifylib.verify_process(fake_invoke, "pid")
+    assert _check(rep, "config-parity-audit")["status"] == "fail"
+    assert rep["verdict"] == "fail"
+
+
+def test_run_finished_status_50_passes(fake_invoke):
+    fake_invoke.set("get-process", flow([START, CONFIGURED, STOP]))
+    fake_invoke.set("request", {"result": {"isValid": True}})
+    fake_invoke.set("run-process", {"result": {"id": "iid", "status": 50}})
+    fake_invoke.set("get-instance-status", {"result": {"status": 50, "actions": []}})
+    rep = verifylib.verify_process(fake_invoke, "pid", run=True)
+    assert rep["verdict"] == "pass"
+    assert _check(rep, "run-instance")["status"] == "pass"
+
+
+def test_run_with_errors_status_40_fails(fake_invoke):
+    fake_invoke.set("get-process", flow([START, CONFIGURED, STOP]))
+    fake_invoke.set("request", {"result": {"isValid": True}})
+    fake_invoke.set("run-process", {"result": {"id": "iid", "status": 40}})
+    fake_invoke.set("get-instance-status", {"result": {
+        "status": 40, "actions": [{"name": "Add", "errorMessage": "boom"}]}})
+    rep = verifylib.verify_process(fake_invoke, "pid", run=True)
+    assert rep["verdict"] == "fail"
+    rc = _check(rep, "run-instance")
+    assert rc["status"] == "fail"
+    assert rc["detail"]["action_errors"][0]["errorMessage"] == "boom"
+
+
+def test_validate_surfaces_400_validation_messages_as_warn(fake_invoke):
+    # PROCESIO returns HTTP 400 + a list of validation messages for an invalid
+    # process; verify must surface them as a warn, not skip.
+    fake_invoke.set("get-process", flow([START, CONFIGURED, STOP]))
+    fake_invoke.set("request", ToolError(
+        "procesio", "invalid_argument", "HTTP 400",
+        {"status": 400, "body": {"body": [
+            {"statusCode": 390, "value": "Action has too few input ports.",
+             "target": "prc"}]}}))
+    rep = verifylib.verify_process(fake_invoke, "pid")
+    vc = _check(rep, "validate-process")
+    assert vc["status"] == "warn"
+    assert vc["detail"]["errors"][0]["statusCode"] == 390
+    assert rep["verdict"] == "warn"
+
+
+def test_validate_endpoint_error_is_skip_not_fail(fake_invoke):
+    fake_invoke.set("get-process", flow([START, CONFIGURED, STOP]))
+    fake_invoke.set("request", ToolError("procesio", "server_error", "no validate here"))
+    rep = verifylib.verify_process(fake_invoke, "pid")
+    assert _check(rep, "validate-process")["status"] == "skip"
+    assert rep["verdict"] == "pass"  # a skipped optional check does not fail the gate
+
+
+def test_verify_reads_live_camelcase_shapes(fake_invoke):
+    # regression: live get-process/instance status are camelCase and nest actions
+    # under instance.actions; verify must parse both.
+    fake_invoke.set("get-process", {"result": {"flow": {
+        "title": "Live", "actions": [
+            {"actionTemplateName": "Start", "parameters": []},
+            {"actionName": "a", "actionTemplateName": "Add",
+             "parameters": [{"value": "x"}],
+             "customData": {"configuration": [{"settings": [{"value": "x"}]}]}},
+            {"actionTemplateName": "Stop", "parameters": []}]}}})
+    fake_invoke.set("request", {"result": {"isValid": True}})
+    fake_invoke.set("run-process", {"result": {"id": "iid", "status": 50}})
+    fake_invoke.set("get-instance-status",
+                    {"result": {"instance": {"status": 50, "actions": []}}})
+    rep = verifylib.verify_process(fake_invoke, "pid", run=True)
+    assert rep["title"] == "Live"
+    assert rep["verdict"] == "pass"
+    assert _check(rep, "run-instance")["status"] == "pass"
+
+
+def test_fetch_failure_fails_fast(fake_invoke):
+    fake_invoke.set("get-process", ToolError("procesio", "not_found", "no such process"))
+    rep = verifylib.verify_process(fake_invoke, "pid")
+    assert rep["verdict"] == "fail"
+    assert _check(rep, "fetch")["status"] == "fail"