platformforge 0.1.0__py3-none-any.whl

platformforge/agents/contracts.py

@@ -0,0 +1,394 @@
+"""Agent runtime contracts — canonical, versioned, hashable (cycle5.1).
+
+Everything crossing an agent boundary is a typed document:
+
+    PlatformTaskSpec   sealed intent (draft|reviewed|sealed|rejected|expired)
+    AgentHandoff       structured transfer between agents (refs, not bodies)
+    AgentRunEnvelope   hard budget limits for one run
+    AgentRunRecord     auditable run receipt
+    Debate             bounded, evidence-carrying disagreement
+
+Schema ids ship in contracts/*.schema.json and are validated by the
+agents-contract gate. None of these documents mutate platform state —
+agents propose; governed ops execute.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+SCHEMA_AGENT_SPEC = "platformforge/agent-spec/v1"
+SCHEMA_TASK_SPEC = "platformforge/task-spec/v1"
+SCHEMA_HANDOFF = "platformforge/agent-handoff/v1"
+SCHEMA_RUN = "platformforge/agent-run/v1"
+SCHEMA_DEBATE = "platformforge/debate/v1"
+
+# §9 — never a bare "writer"; scope is part of the tier's meaning.
+ACCESS_TIERS = ("read-only", "state-writer", "workspace-writer",
+                "governed-writer")
+# write_scope refines *what* an agent may persist inside the platform:
+# runs/artifacts are its own audit trail; "governed" still routes through
+# the ops pipeline — no tier mints approval.
+WRITE_SCOPES = ("none", "runs", "artifacts", "governed")
+
+# §10 — tiers, not providers. A host adapter maps tier → concrete model.
+MODEL_TIERS = ("deterministic", "fast", "standard", "deep",
+               "critical-review")
+
+ROLES = ("orchestrator", "planner", "coordinator", "specialist",
+         "executor", "reviewer", "critic", "referee", "verifier",
+         "guardian")
+
+TASK_STATES = ("draft", "reviewed", "sealed", "rejected", "expired")
+
+# §98 — shared output status vocabulary for every agent-facing document.
+OUTPUT_STATUSES = ("confirmed", "supported", "candidate", "unresolved",
+                   "refuted", "unsupported", "not-observed")
+
+ROUTING_MODES = ("deterministic", "single-specialist", "multi-specialist",
+                 "coordinated", "debate", "critical-review")
+
+
+class AgentRefusal:
+    """§100–101 — the PF-AGENT-* namespace. A refusal keeps its code and
+    an `unlock` instruction; it is never a soft failure."""
+
+    NO_EVIDENCE = "PF-AGENT-NO-EVIDENCE"
+    BUDGET_EXHAUSTED = "PF-AGENT-BUDGET-EXHAUSTED"
+    ROUTE_UNRESOLVED = "PF-AGENT-ROUTE-UNRESOLVED"
+    CAPABILITY_UNAVAILABLE = "PF-AGENT-CAPABILITY-UNAVAILABLE"
+    INDEPENDENCE_FAILED = "PF-AGENT-INDEPENDENCE-FAILED"
+    DEBATE_UNRESOLVED = "PF-AGENT-DEBATE-UNRESOLVED"
+    CONTEXT_LIMIT = "PF-AGENT-CONTEXT-LIMIT"
+    SPEC_UNSEALED = "PF-AGENT-SPEC-UNSEALED"
+    SPEC_REJECTED = "PF-AGENT-SPEC-REJECTED"
+    HOST_CAPABILITY = "PF-AGENT-HOST-CAPABILITY"
+    SELF_VERIFICATION = "PF-AGENT-SELF-VERIFICATION"
+    UNKNOWN_AGENT = "PF-AGENT-UNKNOWN-AGENT"
+    ALL = (NO_EVIDENCE, BUDGET_EXHAUSTED, ROUTE_UNRESOLVED,
+           CAPABILITY_UNAVAILABLE, INDEPENDENCE_FAILED,
+           DEBATE_UNRESOLVED, CONTEXT_LIMIT, SPEC_UNSEALED,
+           SPEC_REJECTED, HOST_CAPABILITY, SELF_VERIFICATION,
+           UNKNOWN_AGENT)
+
+
+def refusal(code: str, why: str, unlock: str, **extra: Any) -> dict[str, Any]:
+    """Uniform agent refusal — code + reason + unlock, plus context."""
+    return {"refusal": code, "why": why, "unlock": unlock, **extra}
+
+
+def doc_hash(doc: dict[str, Any]) -> str:
+    """Content hash over a contract doc (schema field excluded)."""
+    body = {k: v for k, v in doc.items() if k != "spec_hash"}
+    blob = json.dumps(body, sort_keys=True, default=str)
+    return "sha256:" + hashlib.sha256(blob.encode()).hexdigest()
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+@dataclass
+class AgentRunEnvelope:
+    """§76 — hard limits for one agentic run. Exhaustion is an explicit
+    result (PF-AGENT-BUDGET-EXHAUSTED + partial), never silent success."""
+
+    max_model_calls: int = 8
+    max_tool_calls: int = 24
+    max_agents: int = 6
+    max_fanout: int = 4
+    max_context_bytes: int = 120_000
+    max_runtime_s: float = 600.0
+    max_provider_calls: int = 0
+
+    # measured spend — monotonic, never reset on resume (§141)
+    model_calls: int = 0
+    tool_calls: int = 0
+    agents_used: int = 0
+    fanout: int = 0
+    context_bytes: int = 0
+    provider_calls: int = 0
+    elapsed_s: float = 0.0
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> AgentRunEnvelope:
+        return cls(**{k: v for k, v in d.items()
+                      if k in cls.__dataclass_fields__})
+
+    def charge(self, *, model_calls: int = 0, tool_calls: int = 0,
+               agents: int = 0, fanout: int = 0, context_bytes: int = 0,
+               provider_calls: int = 0, elapsed_s: float = 0.0) -> None:
+        self.model_calls += model_calls
+        self.tool_calls += tool_calls
+        self.agents_used += agents
+        self.fanout += fanout
+        self.context_bytes += context_bytes
+        self.provider_calls += provider_calls
+        self.elapsed_s += elapsed_s
+
+    def exceeded(self) -> list[str]:
+        dims = []
+        for limit, spent, name in (
+                (self.max_model_calls, self.model_calls, "model_calls"),
+                (self.max_tool_calls, self.tool_calls, "tool_calls"),
+                (self.max_agents, self.agents_used, "agents"),
+                (self.max_fanout, self.fanout, "fanout"),
+                (self.max_context_bytes, self.context_bytes,
+                 "context_bytes"),
+                (self.max_runtime_s, self.elapsed_s, "runtime_s"),
+                (self.max_provider_calls, self.provider_calls,
+                 "provider_calls")):
+            if spent > limit:
+                dims.append(f"{name} {spent}>{limit}")
+        return dims
+
+    def check(self) -> dict[str, Any] | None:
+        """None if inside budget; else the §77/§289 partial-result refusal."""
+        over = self.exceeded()
+        if not over:
+            return None
+        return refusal(
+            AgentRefusal.BUDGET_EXHAUSTED,
+            "run envelope exhausted: " + ", ".join(over),
+            "raise the budget class or narrow the task scope and resume "
+            "the run — spent budget is preserved, never reset",
+            exceeded=over, spent=self.to_dict())
+
+
+# §112 — budget classes are named envelopes, not magic numbers inline.
+BUDGET_CLASSES: dict[str, AgentRunEnvelope] = {
+    "tiny": AgentRunEnvelope(max_model_calls=1, max_tool_calls=4,
+                             max_agents=1, max_fanout=1,
+                             max_context_bytes=24_000, max_runtime_s=60),
+    "small": AgentRunEnvelope(max_model_calls=2, max_tool_calls=8,
+                              max_agents=2, max_fanout=2,
+                              max_context_bytes=48_000, max_runtime_s=120),
+    "standard": AgentRunEnvelope(max_model_calls=8, max_tool_calls=24,
+                                 max_agents=6, max_fanout=4,
+                                 max_context_bytes=120_000,
+                                 max_runtime_s=600),
+    "deep": AgentRunEnvelope(max_model_calls=16, max_tool_calls=48,
+                             max_agents=10, max_fanout=6,
+                             max_context_bytes=320_000,
+                             max_runtime_s=1800),
+    "critical": AgentRunEnvelope(max_model_calls=24, max_tool_calls=64,
+                                 max_agents=12, max_fanout=8,
+                                 max_context_bytes=480_000,
+                                 max_runtime_s=3600),
+}
+
+
+def envelope_for(budget_class: str) -> AgentRunEnvelope:
+    """Fresh envelope for a budget class (unknown → standard)."""
+    env = BUDGET_CLASSES.get(budget_class) or BUDGET_CLASSES["standard"]
+    return AgentRunEnvelope(**{k: getattr(env, k)
+                               for k in env.__dataclass_fields__})
+
+
+@dataclass
+class PlatformTaskSpec:
+    """§74–75 — sealed task the orchestrator executes. `state` transitions
+    only via taskspec.py: draft → reviewed → sealed (or rejected/expired).
+    Orchestrators refuse unsealed specs for non-trivial work (§18)."""
+
+    task_id: str
+    intent: str
+    scope: str = "repo"               # repo | fleet | runtime | change
+    domains: tuple[str, ...] = ()
+    risk: str = "low"                 # low | medium | high | critical
+    complexity: str = "low"           # low | medium | high
+    evidence_requirements: tuple[str, ...] = ()
+    acceptance_criteria: tuple[str, ...] = ()
+    autonomy: str = "read-only"       # read-only | propose | simulate
+    allowed_capabilities: tuple[str, ...] = ()
+    forbidden_capabilities: tuple[str, ...] = ()
+    rollback_requirement: str = "none"     # none | declared | material-bound
+    verification_requirement: str = "independent-verifier"
+    budget: str = "standard"          # BUDGET_CLASSES key
+    state: str = "draft"              # TASK_STATES
+    reviewer: str = ""
+    review_notes: tuple[str, ...] = ()
+    created_at: str = ""
+    schema: str = SCHEMA_TASK_SPEC
+    spec_hash: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.created_at:
+            self.created_at = _now()
+        if not self.spec_hash:
+            self.spec_hash = doc_hash(self.to_dict())
+
+    def to_dict(self) -> dict[str, Any]:
+        d = asdict(self)
+        for k in ("domains", "evidence_requirements",
+                  "acceptance_criteria", "allowed_capabilities",
+                  "forbidden_capabilities", "review_notes"):
+            d[k] = list(d[k])
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> PlatformTaskSpec:
+        kw = {k: v for k, v in d.items() if k in cls.__dataclass_fields__}
+        for k in ("domains", "evidence_requirements",
+                  "acceptance_criteria", "allowed_capabilities",
+                  "forbidden_capabilities", "review_notes"):
+            if k in kw and isinstance(kw[k], list):
+                kw[k] = tuple(kw[k])
+        return cls(**kw)
+
+    def transition(self, to: str, reviewer: str = "",
+                   notes: tuple[str, ...] = ()) -> PlatformTaskSpec:
+        """Move state; returns a NEW spec (specs are immutable docs).
+        Legal: draft→reviewed|rejected; reviewed→sealed|rejected;
+        any→expired. Everything else refuses."""
+        legal = {"draft": {"reviewed", "rejected", "expired"},
+                 "reviewed": {"sealed", "rejected", "expired"},
+                 "sealed": {"expired"},
+                 "rejected": set(), "expired": set()}
+        if to not in legal.get(self.state, set()):
+            raise ValueError(
+                f"illegal TaskSpec transition {self.state}→{to}")
+        d = self.to_dict()
+        d["state"] = to
+        d["reviewer"] = reviewer or self.reviewer
+        d["review_notes"] = list(notes) or list(self.review_notes)
+        d["spec_hash"] = ""
+        out = PlatformTaskSpec.from_dict(d)
+        return out
+
+
+@dataclass
+class AgentHandoff:
+    """§71–73 — every transfer between agents is structured and carries
+    refs (artifact/fact/graph/context-pack), never raw context bodies."""
+
+    sender: str                     # serialized as `from`
+    to: str
+    task_id: str
+    reason: str = ""
+    completed: tuple[str, ...] = ()
+    evidence: tuple[str, ...] = ()          # fact_id / artifact refs only
+    findings: tuple[str, ...] = ()          # finding ids / summaries
+    open_questions: tuple[str, ...] = ()
+    unresolved: tuple[str, ...] = ()
+    budget_spent: dict[str, Any] = field(default_factory=dict)
+    budget_remaining: dict[str, Any] = field(default_factory=dict)
+    next_required_capability: str = ""
+    context_pack_ref: str = ""              # §73 — pack hash, not body
+    schema: str = SCHEMA_HANDOFF
+
+    def to_dict(self) -> dict[str, Any]:
+        d = asdict(self)
+        d["from"] = d.pop("sender")
+        for k in ("completed", "evidence", "findings", "open_questions",
+                  "unresolved"):
+            d[k] = list(d[k])
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> AgentHandoff:
+        kw = {k: v for k, v in d.items() if k in cls.__dataclass_fields__}
+        if "from" in d:
+            kw["sender"] = d["from"]
+        for k in ("completed", "evidence", "findings", "open_questions",
+                  "unresolved"):
+            if k in kw and isinstance(kw[k], list):
+                kw[k] = tuple(kw[k])
+        return cls(**kw)
+
+
+@dataclass
+class AgentRunRecord:
+    """§138–139 — the auditable receipt of one agentic run. Persisted
+    under .platformforge/runs/ (append-only)."""
+
+    run_id: str
+    task_spec_hash: str
+    router_decision: dict[str, Any] = field(default_factory=dict)
+    agents: tuple[str, ...] = ()
+    handoffs: tuple[dict[str, Any], ...] = ()
+    budget: dict[str, Any] = field(default_factory=dict)
+    evidence: tuple[str, ...] = ()
+    debates: tuple[str, ...] = ()
+    gates: tuple[str, ...] = ()
+    verifier: str = ""
+    verdict: str = "unresolved"             # OUTPUT_STATUSES
+    checkpoint: dict[str, Any] = field(default_factory=dict)
+    started_at: str = ""
+    finished_at: str = ""
+    schema: str = SCHEMA_RUN
+
+    def to_dict(self) -> dict[str, Any]:
+        d = asdict(self)
+        for k in ("agents", "handoffs", "evidence", "debates", "gates"):
+            d[k] = list(d[k])
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> AgentRunRecord:
+        kw = {k: v for k, v in d.items() if k in cls.__dataclass_fields__}
+        for k in ("agents", "evidence", "debates", "gates"):
+            if k in kw and isinstance(kw[k], list):
+                kw[k] = tuple(kw[k])
+        if isinstance(kw.get("handoffs"), list):
+            kw["handoffs"] = tuple(kw["handoffs"])
+        return cls(**kw)
+
+
+@dataclass
+class DebatePosition:
+    """One participant's position — must cite evidence (§130–131)."""
+    agent: str
+    claim: str
+    evidence: tuple[str, ...] = ()
+    evidence_tier: int = 7
+    freshness: str = "unresolved"
+    round: int = 0
+
+    def to_dict(self) -> dict[str, Any]:
+        d = asdict(self)
+        d["evidence"] = list(self.evidence)
+        return d
+
+
+@dataclass
+class Debate:
+    """§126–129 — bounded disagreement. Default shape is small:
+    2 specialists + 1 critic + 1 referee, 1–3 rounds, inside the run
+    envelope. A position without evidence is refused, not debated."""
+
+    debate_id: str
+    question: str
+    positions: tuple[DebatePosition, ...] = ()
+    max_participants: int = 4
+    max_rounds: int = 3
+    round: int = 0
+    outcome: str = "open"            # open | winner | tied | unresolved
+    winner: str = ""
+    axes: tuple[str, ...] = ()
+    receipt: dict[str, Any] = field(default_factory=dict)
+    schema: str = SCHEMA_DEBATE
+
+    def to_dict(self) -> dict[str, Any]:
+        d = asdict(self)
+        d["positions"] = [p.to_dict() for p in self.positions]
+        d["axes"] = list(self.axes)
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Debate:
+        kw = {k: v for k, v in d.items() if k in cls.__dataclass_fields__}
+        kw["positions"] = tuple(
+            DebatePosition(**{k: v for k, v in p.items()
+                              if k in DebatePosition.__dataclass_fields__})
+            for p in d.get("positions", []))
+        if isinstance(kw.get("axes"), list):
+            kw["axes"] = tuple(kw["axes"])
+        return cls(**kw)

platformforge/agents/coordinators.py

@@ -0,0 +1,98 @@
+"""Coordinator machinery — bounded dispatch + collection (§28–34, §67).
+
+Coordinators may dispatch (only orchestrators/coordinators create
+fan-out, §67); specialists may not spawn. A coordinator's dispatch plan
+is deterministic: TaskSpec domains ∩ coordinator delegates_to →
+AgentHandoff list. Collection merges handoffs without minting facts.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from platformforge.agents.contracts import AgentHandoff, AgentRefusal, PlatformTaskSpec, refusal
+from platformforge.agents.roster import resolve
+from platformforge.models.base import stable_id
+
+# coordinator → its canonical loop in rules/catalog/orchestration.yaml
+COORDINATOR_LOOPS = {
+    "platform-incident-coordinator": "incident",
+    "platform-change-coordinator": "change",
+    "platform-fleet-coordinator": "fleet",
+    "platform-optimization-coordinator": "optimization",
+    "platform-product-coordinator": "platform-audit",
+}
+
+
+def dispatch_plan(coordinator: str, spec: PlatformTaskSpec) \
+        -> dict[str, Any]:
+    """coordinator + sealed spec → handoffs to delegated specialists.
+
+    Only delegates whose declared domains intersect the task's are
+    dispatched — a coordinator never fans out to its whole delegate
+    list 'just in case' (§68 companion)."""
+    coord = resolve(coordinator)
+    if coord is None:
+        return refusal(AgentRefusal.UNKNOWN_AGENT,
+                       f"no agent named {coordinator!r}",
+                       "check the canonical roster")
+    if coord.role not in ("coordinator", "orchestrator"):
+        return refusal(
+            AgentRefusal.HOST_CAPABILITY,
+            f"{coordinator} is role={coord.role} — only orchestrators "
+            "and coordinators may dispatch (§67)",
+            "route through platform-orchestrator")
+    targets = [d for d in coord.delegates_to
+               if resolve(d) is not None
+               and (not spec.domains
+                    or set(resolve(d).domains) & set(spec.domains)
+                    or "all" in resolve(d).domains)]
+    if not targets:
+        return refusal(
+            AgentRefusal.ROUTE_UNRESOLVED,
+            f"{coordinator} has no delegate covering domains "
+            f"{sorted(spec.domains)}",
+            "widen the spec domains or escalate to the orchestrator")
+    # §67/§113 — fanout is bounded: never dispatch past the
+    # coordinator's declared parallelism; the remainder stays queued
+    capped = targets[:coord.max_parallelism]
+    queued = targets[coord.max_parallelism:]
+    handoffs = []
+    for t in capped:
+        handoffs.append(AgentHandoff(
+            sender=coordinator, to=t, task_id=spec.task_id,
+            reason=f"dispatch: {spec.intent[:80]}",
+            open_questions=tuple(c for c in spec.acceptance_criteria),
+            budget_spent={},
+            next_required_capability="",
+            context_pack_ref="", ))
+    return {"coordinator": coordinator,
+            "loop": COORDINATOR_LOOPS.get(coord.name, "platform-audit"),
+            "dispatched": capped,
+            "queued": queued,
+            "handoffs": [h.to_dict() for h in handoffs],
+            "bounded": not queued}
+
+
+def collect(handoffs: list[dict[str, Any]]) -> dict[str, Any]:
+    """Merge specialist handoffs — completed/evidence/unresolved.
+    Collecting is bookkeeping, not adjudication: conflicts go to the
+    referee, gaps stay unresolved (§98 vocabulary)."""
+    done, ev, unresolved, questions = set(), set(), set(), set()
+    for h in handoffs:
+        done.update(h.get("completed") or ())
+        ev.update(h.get("evidence") or ())
+        unresolved.update(h.get("unresolved") or ())
+        questions.update(h.get("open_questions") or ())
+    return {"completed": sorted(done), "evidence": sorted(ev),
+            "unresolved": sorted(unresolved),
+            "open_questions": sorted(questions),
+            "responded": len(handoffs),
+            "collection_id": stable_id(
+                "PF-COLL", str(len(handoffs)),
+                ",".join(sorted(ev)))}
+
+
+def coordinator_loop(name: str) -> str:
+    """Coordinator name → canonical loop; orchestrator → audit."""
+    return COORDINATOR_LOOPS.get(name, "platform-audit")

platformforge/agents/critic.py

@@ -0,0 +1,113 @@
+"""platform-adversarial-critic — attack the plan before acceptance (§22).
+
+The critic runs BEFORE execution/ship and asks the §22 questions as
+deterministic checks over the plan + spec. It does not verify (§23):
+it finds ways this could be wrong; the verifier proves or refuses
+closure after work.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from platformforge.agents.contracts import PlatformTaskSpec
+from platformforge.agents.orchestrator import OrchestrationPlan
+from platformforge.agents.roster import resolve
+
+_ATTACKS = (
+    ("assumption", "What assumption could make this wrong?"),
+    ("missing-evidence", "What evidence is missing?"),
+    ("fail-open", "Can this fail open?"),
+    ("partial-coverage", "Can partial coverage look complete?"),
+    ("rollback", "Can rollback fail?"),
+    ("source-ownership", "Can source ownership be wrong?"),
+    ("regression", "Can this recommendation create regression?"),
+)
+
+
+def _has_verifier(plan: OrchestrationPlan) -> bool:
+    return any(resolve(n.agent) and resolve(n.agent).role == "verifier"
+               for n in plan.dag)
+
+
+def _has_reviewer(plan: OrchestrationPlan) -> bool:
+    return any(resolve(n.agent) and resolve(n.agent).role == "reviewer"
+               for n in plan.dag)
+
+
+def adversarial_review(plan: OrchestrationPlan,
+                       spec: PlatformTaskSpec) -> dict[str, Any]:
+    """Return one challenge per attack axis with a status: ok | risk."""
+    checks: list[dict[str, Any]] = []
+
+    def add(axis: str, status: str, detail: str) -> None:
+        checks.append({"axis": axis, "status": status,
+                       "detail": detail})
+
+    # assumption — no evidence requirements means conclusions ride on air
+    add("assumption",
+        "risk" if not spec.evidence_requirements else "ok",
+        "spec declares evidence_requirements"
+        if spec.evidence_requirements
+        else "spec declares no evidence_requirements — any conclusion "
+             "could be invented")
+
+    # missing evidence
+    add("missing-evidence",
+        "risk" if not spec.acceptance_criteria else "ok",
+        "acceptance criteria declared" if spec.acceptance_criteria
+        else "no acceptance criteria — closure would be uncheckable")
+
+    # fail-open — is a verifier in the DAG and is it terminal
+    add("fail-open",
+        "ok" if _has_verifier(plan) else "risk",
+        "verifier stage present" if _has_verifier(plan)
+        else "no verifier in DAG — run could close unverified")
+
+    # partial coverage — fleet/coverage-scoped tasks need coverage evidence
+    needs_cov = spec.scope == "fleet" or any(
+        "coverage" in e for e in spec.evidence_requirements)
+    add("partial-coverage",
+        "risk" if needs_cov and "coverage"
+        not in " ".join(spec.evidence_requirements) else "ok",
+        "coverage evidence required and declared"
+        if needs_cov else "no coverage requirement inferred")
+
+    # rollback — risky specs must demand rollback material
+    add("rollback",
+        "risk" if spec.risk in ("high", "critical")
+        and spec.rollback_requirement == "none" else "ok",
+        f"rollback_requirement={spec.rollback_requirement}")
+
+    # source-ownership — mutating caps must be forbidden
+    from platformforge.agents.taskspec import MUTATING_CAPS
+    missing = [c for c in MUTATING_CAPS
+               if c not in spec.forbidden_capabilities]
+    add("source-ownership",
+        "risk" if missing else "ok",
+        "mutating capabilities forbidden"
+        if not missing else "forbidden_capabilities missing: "
+        + ", ".join(missing))
+
+    # regression — envelope must bound fanout
+    add("regression",
+        "risk" if plan.envelope.max_fanout > plan.envelope.max_agents
+        else "ok",
+        f"fanout≤{plan.envelope.max_fanout} agents≤"
+        f"{plan.envelope.max_agents}")
+
+    risky = [c for c in checks if c["status"] == "risk"]
+    return {"verdict": "risk" if risky else "clear",
+            "attacks": checks,
+            "open_risks": len(risky),
+            "note": "critic attacks before acceptance — the verifier "
+                    "still decides closure"}
+
+
+def pre_mortem(spec: PlatformTaskSpec) -> dict[str, Any]:
+    """Spec-level attack surface, before a plan exists (§22 questions)."""
+    return {"question": spec.intent,
+            "axes": [{"axis": a, "question": q} for a, q in _ATTACKS],
+            "note": "run adversarial_review(plan, spec) once a DAG "
+                    "exists — a question without a plan is a checklist, "
+                    "not a finding"}