platformforge 0.1.0__py3-none-any.whl

platformforge/core/hashing.py

@@ -0,0 +1,39 @@
+"""Content addressing — the basis of caching, provenance and dedup.
+
+Everything persistent is keyed by sha256 of canonical content, never by
+filename or path.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+
+def sha256_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def sha256_text(text: str) -> str:
+    return sha256_bytes(text.encode("utf-8"))
+
+
+def sha256_file(path: str | Path) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as fh:
+        for chunk in iter(lambda: fh.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def sha256_obj(obj: Any) -> str:
+    """Canonical JSON hashing — key order and whitespace normalized."""
+    return sha256_text(
+        json.dumps(obj, sort_keys=True, separators=(",", ":"), default=str)
+    )
+
+
+def short(content_hash: str, n: int = 12) -> str:
+    return content_hash[:n]

platformforge/core/ownership.py

@@ -0,0 +1,220 @@
+"""Ownership resolution (§136–137) + contradictory evidence (§116).
+
+Ownership signals come from multiple sources, each with its own evidence
+tier. When two sources disagree for the same subject the result is a named
+`ownership.conflicted` fact — never a silently averaged winner.
+
+Signal sources and tiers:
+- CODEOWNERS            → T3 repo-config
+- Backstage catalog     → T3 repo-config
+- workspace member attr → T5 operator-declared
+- k8s labels/annotations→ T3 repo-config (manifest) / T1 (provider dump)
+- cloud resource tags   → T1 provider-observed
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from platformforge.models.base import EvidenceTier, stable_id
+
+_OWNER_LABEL_KEYS = ("team", "owner", "owner-id",
+                     "app.kubernetes.io/managed-by",
+                     "app.kubernetes.io/part-of")
+_OWNER_TAG_KEYS = ("owner", "team", "cost_center", "cost-center",
+                   "Owner", "Team")
+
+
+def _fact(fkind: str, source: str, location: str, tier: int,
+          attrs: dict[str, Any]) -> dict[str, Any]:
+    return {"fact_id": stable_id("PF-FACT", fkind, source, location,
+                                 json.dumps(attrs, sort_keys=True,
+                                            default=str)[:200]),
+            "kind": fkind, "source": source, "location": location,
+            "tier": int(tier), "attrs": attrs}
+
+
+def _codeowners_signals(path: Path) -> list[dict[str, Any]]:
+    """Parse CODEOWNERS → per-path owner signals."""
+    facts = []
+    text = path.read_text(errors="replace")
+    for i, line in enumerate(text.splitlines(), 1):
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        parts = line.split()
+        pattern, owners = parts[0], [o for o in parts[1:]
+                                   if not o.startswith("#")]
+        if not owners:
+            continue
+        facts.append(_fact(
+            "ownership.signal", str(path), f"{path}:{i}",
+            EvidenceTier.REPO_CONFIG,
+            {"subject": pattern, "owners": owners,
+             "source_kind": "codeowners"}))
+    return facts
+
+
+def _backstage_signals(path: Path) -> list[dict[str, Any]]:
+    facts = []
+    try:
+        doc = yaml.safe_load(path.read_text()) or {}
+    except yaml.YAMLError:
+        return facts
+    spec = doc.get("spec") or {}
+    owner = spec.get("owner")
+    if owner:
+        meta = doc.get("metadata") or {}
+        facts.append(_fact(
+            "ownership.signal", str(path),
+            f"{doc.get('kind', '?')}/{meta.get('name', '?')}",
+            EvidenceTier.REPO_CONFIG,
+            {"subject": meta.get("name", path.stem),
+             "owners": [str(owner)],
+             "source_kind": "backstage",
+             "system": spec.get("system")}))
+    return facts
+
+
+def _workspace_signals(root: Path) -> list[dict[str, Any]]:
+    ws = root / "workspace.yaml"
+    if not ws.is_file():
+        return []
+    try:
+        doc = yaml.safe_load(ws.read_text()) or {}
+    except yaml.YAMLError:
+        return []
+    facts = []
+    for m in doc.get("members", []):
+        owner = m.get("owner") or (m.get("attrs") or {}).get("owner")
+        if owner:
+            facts.append(_fact(
+                "ownership.signal", str(ws), f"member/{m.get('name')}",
+                EvidenceTier.OPERATOR_DECLARED,
+                {"subject": m.get("name", "?"), "owners": [str(owner)],
+                 "source_kind": "workspace"}))
+    return facts
+
+
+def ownership_signals_from_facts(facts: list[dict[str, Any]]
+                                 ) -> list[dict[str, Any]]:
+    """Harvest owner signals already present in collected fact attrs —
+    k8s labels and cloud tags. Each carries the parent fact's tier."""
+    out: list[dict[str, Any]] = []
+    for f in facts:
+        attrs = f.get("attrs") or {}
+        subject = f.get("location") or f.get("fact_id", "?")
+        labels = attrs.get("labels") or {}
+        found = {k: v for k, v in labels.items() if k in _OWNER_LABEL_KEYS}
+        if found:
+            out.append(_fact(
+                "ownership.signal", f.get("source", "?"), subject,
+                int(f.get("tier", 3)),
+                {"subject": subject, "owners": sorted(set(found.values())),
+                 "source_kind": "k8s_labels", "keys": sorted(found),
+                 "parent_fact": f.get("fact_id")}))
+        tags = attrs.get("tags") or {}
+        found = {k: v for k, v in tags.items() if k in _OWNER_TAG_KEYS}
+        if found:
+            out.append(_fact(
+                "ownership.signal", f.get("source", "?"), subject,
+                int(f.get("tier", 1)),
+                {"subject": subject, "owners": sorted(set(found.values())),
+                 "source_kind": "cloud_tags", "keys": sorted(found),
+                 "parent_fact": f.get("fact_id")}))
+    return out
+
+
+def detect_conflicts(signals: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Same subject, different owner sets across sources → conflicted fact."""
+    by_subject: dict[str, list[dict[str, Any]]] = {}
+    for s in signals:
+        by_subject.setdefault(str(s["attrs"].get("subject")), []).append(s)
+    out = []
+    for subject, sigs in sorted(by_subject.items()):
+        owner_sets = {tuple(sorted(s["attrs"].get("owners", [])))
+                      for s in sigs}
+        if len(owner_sets) <= 1:
+            continue
+        out.append(_fact(
+            "ownership.conflicted", "platformforge.ownership", subject,
+            EvidenceTier.REPO_CONFIG,
+            {"subject": subject,
+             "claims": [{"owners": s["attrs"].get("owners"),
+                         "source_kind": s["attrs"].get("source_kind"),
+                         "tier": s.get("tier"),
+                         "location": s.get("location")}
+                        for s in sigs],
+             "resolution": "unresolved — declared vs declared/observed "
+                           "disagree; needs human adjudication"}))
+    return out
+
+
+def analyze_ownership(root: str | Path,
+                      facts: list[dict[str, Any]] | None = None
+                      ) -> dict[str, Any]:
+    """Collect ownership signals under `root` + from existing fact attrs."""
+    root = Path(root)
+    signals: list[dict[str, Any]] = []
+    checked: list[str] = []
+    for name in ("CODEOWNERS", ".github/CODEOWNERS", "docs/CODEOWNERS"):
+        p = root / name
+        if p.is_file():
+            signals.extend(_codeowners_signals(p))
+            checked.append(name)
+    for cat in root.rglob("catalog-info.y*ml"):
+        signals.extend(_backstage_signals(cat))
+        checked.append(str(cat))
+    signals.extend(_workspace_signals(root))
+    if facts:
+        signals.extend(ownership_signals_from_facts(facts))
+    conflicts = detect_conflicts(signals)
+    return {"facts": signals + conflicts,
+            "summary": {"signals": len(signals), "conflicts": len(conflicts),
+                        "sources_checked": checked},
+            "boundary": "ownership signals are claims; conflicts are named, "
+                        "never averaged"}
+
+
+def detect_contradictions(facts: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """§116 — declared vs observed disagreement on the same subject+attr.
+
+    Pairs facts sharing an identity (kind + location) where a comparable
+    attr is asserted differently by a declared source (T2+... here T3 repo
+    config / T5 operator) vs an observed source (T0/T1). Result is a named
+    `state.contradiction` fact carrying both states — never a winner."""
+    _DECLARED = (int(EvidenceTier.GENERATED_PLAN),
+                 int(EvidenceTier.REPO_CONFIG),
+                 int(EvidenceTier.OPERATOR_DECLARED))
+    _OBSERVED = (int(EvidenceTier.MEASURED_RUNTIME),
+                 int(EvidenceTier.PROVIDER_OBSERVED))
+    out: list[dict[str, Any]] = []
+    groups: dict[tuple[str, str], list[dict[str, Any]]] = {}
+    for f in facts:
+        groups.setdefault((f.get("kind", ""), f.get("location", "")),
+                          []).append(f)
+    for (kind, loc), fs in sorted(groups.items()):
+        declared = [f for f in fs if int(f.get("tier", 3)) in _DECLARED]
+        observed = [f for f in fs if int(f.get("tier", 3)) in _OBSERVED]
+        if not declared or not observed:
+            continue
+        d_attrs = declared[0].get("attrs") or {}
+        o_attrs = observed[0].get("attrs") or {}
+        diffs = {k: {"declared": d_attrs[k], "observed": o_attrs[k]}
+                 for k in set(d_attrs) & set(o_attrs)
+                 if d_attrs[k] != o_attrs[k]
+                 and isinstance(d_attrs[k], (str, int, float, bool))
+                 and not k.startswith(("api_", "labels", "tags"))}
+        if diffs:
+            out.append(_fact(
+                "state.contradiction", "platformforge.contradictions", loc,
+                EvidenceTier.REPO_CONFIG,
+                {"kind": kind, "subject": loc, "diffs": diffs,
+                 "declared_fact": declared[0].get("fact_id"),
+                 "observed_fact": observed[0].get("fact_id"),
+                 "status": "drift confirmed — both states reported"}))
+    return out

platformforge/core/receipts.py

@@ -0,0 +1,74 @@
+"""Evidence receipts — every important operation emits one.
+
+Receipts capture operation, inputs, content hashes, tools/versions, produced
+fact/finding ids and timings so a run is auditable and replayable.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+from platformforge.core.hashing import sha256_obj
+
+
+@dataclass
+class Receipt:
+    """§152 receipt v2 — auditable, replayable operation record."""
+    operation: str
+    inputs: list[Any] = field(default_factory=list)
+    hashes: dict[str, str] = field(default_factory=dict)
+    tools: list[str] = field(default_factory=list)
+    versions: dict[str, str] = field(default_factory=dict)
+    facts: list[str] = field(default_factory=list)
+    findings: list[str] = field(default_factory=list)
+    sources: list[str] = field(default_factory=list)      # §152
+    cost: dict[str, Any] = field(default_factory=dict)    # bytes/tokens
+    graph: str | None = None
+    started_at: float = 0.0
+    ended_at: float = 0.0
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        d = asdict(self)
+        d["started_at"] = _iso(self.started_at)
+        d["ended_at"] = _iso(self.ended_at)
+        return d
+
+    @property
+    def receipt_id(self) -> str:
+        return "rcpt-" + sha256_obj(self.to_dict())[:16]
+
+
+def _iso(ts: float) -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(ts)) if ts else ""
+
+
+class ReceiptWriter:
+    """Persists receipts under .platformforge/receipts/ (audit trail)."""
+
+    def __init__(self, root: str | Path):
+        self.dir = Path(root) / ".platformforge" / "receipts"
+        self.dir.mkdir(parents=True, exist_ok=True)
+
+    def emit(self, receipt: Receipt) -> Path:
+        p = self.dir / f"{receipt.receipt_id}.json"
+        p.write_text(json.dumps(receipt.to_dict(), indent=2, default=str))
+        return p
+
+
+class timed:
+    """Context manager stamping started_at/ended_at on a receipt."""
+
+    def __init__(self, receipt: Receipt):
+        self.receipt = receipt
+
+    def __enter__(self) -> Receipt:
+        self.receipt.started_at = time.time()
+        return self.receipt
+
+    def __exit__(self, *exc) -> None:
+        self.receipt.ended_at = time.time()

platformforge/core/redaction.py

@@ -0,0 +1,97 @@
+"""Secrets redaction — core layer. Applied to anything entering context
+packs, receipts, findings messages, or LLM-bound payloads. Never prints a
+secret value; replaces with a stable redaction marker."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from typing import Any
+
+# Ordered (label, pattern). First match wins per span.
+PATTERNS: list[tuple[str, re.Pattern[str]]] = [
+    ("aws_access_key", re.compile(r"\bAKIA[0-9A-Z]{16}\b")),
+    ("aws_secret_key", re.compile(r"(?i)aws[_-]?(secret[_-]?)?access[_-]?key['\"\s:=]+[A-Za-z0-9/+=]{40}")),
+    ("github_token", re.compile(r"\b(ghp|gho|ghu|ghs|ghr|github_pat)_[A-Za-z0-9_]{22,}\b")),
+    ("gitlab_token", re.compile(r"\bglpat-[A-Za-z0-9_\-]{20,}\b")),
+    ("slack_token", re.compile(r"\bxox[baprs]-[A-Za-z0-9\-]{10,}\b")),
+    ("private_key", re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----")),
+    ("jwt", re.compile(r"\beyJ[A-Za-z0-9_\-]{8,}\.[A-Za-z0-9_\-]{8,}\.[A-Za-z0-9_\-]{8,}\b")),
+    ("bearer", re.compile(r"(?i)bearer\s+[A-Za-z0-9_\-\.]{20,}")),
+    # Delimiter required (:= or quote) — prose like "password policy" must
+    # not redact (§88 false-positive guard). Snake-case prefixes allowed:
+    # db_password / client_secret / my_api_key must still match.
+    # Dogfood RW-5: the value must contain ≥1 non-lowercase char — prose
+    # like "pass: refuse and route" matched as a secret otherwise.
+    ("password_kv", re.compile(r"(?i)\b(?:[a-z0-9]+_)*(?:pass(?:word)?|passwd|pwd)\s*[:='\"]\s*['\"]?(?=[^\s'\"]*[^\sa-z'\"])[^\s'\"]{6,}")),
+    ("conn_string", re.compile(
+        r"\b(?:postgres|mysql|mongodb|redis|amqp|mssql|sqlserver|kafka|"
+        r"ldaps?)://[^\s'\"]+|"
+        r"\b(?:https?|ssh|ftp)://[^\s/'\"]+:[^\s/'\"]+@")),
+    ("generic_secret_kv", re.compile(
+        r"(?i)\b(?:[a-z0-9]+_)*(?:api[_-]?key|secret(?:[_-]?key)?|"
+        r"access[_-]?key|access[_-]?token|refresh[_-]?token|"
+        r"client[_-]?secret|account[_-]?key|token)"
+        r"['\"\s:=]+[A-Za-z0-9_\-./+=]{16,}")),
+]
+
+SECRET_VALUE_KEYS = ("stringData", "data")  # k8s Secret keys whose values are secrets
+
+
+def _marker(label: str, matched: str) -> str:
+    return f"[REDACTED:{label}:{hashlib.sha256(matched.encode()).hexdigest()[:8]}]"
+
+
+def redact_text(text: str) -> str:
+    for label, pat in PATTERNS:
+        text = pat.sub(lambda m, label=label: _marker(label, m.group(0)), text)
+    return text
+
+
+def redact_text_report(text: str) -> tuple[str, dict[str, int]]:
+    """Redact and return per-label counts for a redaction receipt (§18)."""
+    counts: dict[str, int] = {}
+    for label, pat in PATTERNS:
+        def _sub(m: re.Match[str], label: str = label) -> str:
+            counts[label] = counts.get(label, 0) + 1
+            return _marker(label, m.group(0))
+        text = pat.sub(_sub, text)
+    return text, counts
+
+
+def redaction_receipt(source: str, counts: dict[str, int]) -> dict[str, Any]:
+    """§18 — a receipt names what was redacted (labels + counts + hash of
+    the pattern set), never the values. """
+    return {
+        "kind": "pf-redaction-receipt/1",
+        "source": str(source),
+        "redactions": dict(sorted(counts.items())),
+        "total": sum(counts.values()),
+        "patterns_sha256": hashlib.sha256(
+            "".join(p.pattern for _, p in PATTERNS).encode()).hexdigest()[:16],
+    }
+
+
+def redact_obj(obj: Any) -> Any:
+    """Deep-redact strings in dict/list structures."""
+    if isinstance(obj, str):
+        return redact_text(obj)
+    if isinstance(obj, dict):
+        return {k: redact_obj(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [redact_obj(v) for v in obj]
+    return obj
+
+
+def k8s_secret_values(obj: dict[str, Any]) -> dict[str, Any]:
+    """Blank out Kubernetes Secret payload fields entirely — base64 values are
+    still secrets."""
+    out = dict(obj)
+    for key in SECRET_VALUE_KEYS:
+        if key in out and isinstance(out[key], dict):
+            out[key] = {k: "[REDACTED:k8s-secret]" for k in out[key]}
+    return out
+
+
+def contains_secret(text: str) -> bool:
+    return any(pat.search(text) for _, pat in PATTERNS)

platformforge/core/store.py

@@ -0,0 +1,119 @@
+"""Content-addressed artifact store.
+
+Raw tool output, large evidence blobs and intermediate state live here —
+referenced by hash, so context packs carry pointers, not payloads.
+
+Layout:  .platformforge/store/<sha[:2]>/<sha>   (+ .json sidecar metadata)
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+from platformforge.core.hashing import sha256_bytes
+
+STORE_DIR = ".platformforge/store"
+
+
+class ArtifactStore:
+    def __init__(self, root: str | Path):
+        self.root = Path(root) / STORE_DIR
+        self.root.mkdir(parents=True, exist_ok=True)
+
+    def _path(self, sha: str) -> Path:
+        return self.root / sha[:2] / sha
+
+    def put(self, data: bytes, meta: dict[str, Any] | None = None) -> str:
+        sha = sha256_bytes(data)
+        p = self._path(sha)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        if not p.exists():
+            p.write_bytes(data)
+            p.with_suffix(p.suffix + ".meta.json").write_text(
+                json.dumps(
+                    {"sha256": sha, "bytes": len(data), "stored_at": time.time(),
+                     **(meta or {})},
+                    indent=2, default=str,
+                )
+            )
+        return sha
+
+    def put_text(self, text: str, meta: dict[str, Any] | None = None) -> str:
+        return self.put(text.encode("utf-8"), meta)
+
+    def put_obj(self, obj: Any, meta: dict[str, Any] | None = None) -> str:
+        return self.put_text(
+            json.dumps(obj, indent=2, sort_keys=True, default=str), meta
+        )
+
+    def get(self, sha: str) -> bytes | None:
+        p = self._path(sha)
+        return p.read_bytes() if p.exists() else None
+
+    def get_text(self, sha: str) -> str | None:
+        b = self.get(sha)
+        return b.decode("utf-8") if b is not None else None
+
+    def get_obj(self, sha: str) -> Any | None:
+        t = self.get_text(sha)
+        return json.loads(t) if t is not None else None
+
+    def has(self, sha: str) -> bool:
+        return self._path(sha).exists()
+
+    def meta(self, sha: str) -> dict[str, Any] | None:
+        mp = self._path(sha).with_suffix(".meta.json")
+        return json.loads(mp.read_text()) if mp.exists() else None
+
+    def stats(self) -> dict[str, int]:
+        blobs = [p for p in self.root.glob("*/*") if not p.name.endswith(".meta.json")]
+        return {"artifacts": len(blobs),
+                "bytes": sum(p.stat().st_size for p in blobs)}
+
+    def gc(self, keep_days: float = 30.0,
+           referenced: set[str] | None = None,
+           dry_run: bool = True) -> dict[str, Any]:
+        """§151 — garbage-collect stale blobs.
+
+        Never deletes a hash in `referenced` (receipts, packs, ledger rows).
+        `dry_run=True` reports candidates without touching the store.
+        """
+        ref = referenced or set()
+        cutoff = time.time() - keep_days * 86400
+        stale: list[dict[str, Any]] = []
+        kept = 0
+        for blob in self.root.glob("*/*"):
+            if blob.name.endswith(".meta.json"):
+                continue
+            sha = blob.name
+            meta = self.meta(sha) or {}
+            stored_at = float(meta.get("stored_at") or blob.stat().st_mtime)
+            if sha in ref or stored_at > cutoff:
+                kept += 1
+                continue
+            stale.append({"sha256": sha, "bytes": blob.stat().st_size,
+                          "stored_at": stored_at})
+        removed_bytes = 0
+        if not dry_run:
+            for s in stale:
+                p = self._path(s["sha256"])
+                mp = p.with_suffix(".meta.json")
+                removed_bytes += p.stat().st_size
+                p.unlink(missing_ok=True)
+                mp.unlink(missing_ok=True)
+        return {"dry_run": dry_run, "keep_days": keep_days,
+                "candidates": len(stale),
+                "candidate_bytes": sum(s["bytes"] for s in stale),
+                "removed": 0 if dry_run else len(stale),
+                "removed_bytes": removed_bytes,
+                "kept": kept,
+                "referenced_protected": len(ref),
+                "stale": stale if dry_run else []}
+
+
+def ref(sha: str) -> str:
+    """Artifact reference used in context packs and receipts."""
+    return f"artifact://sha256/{sha}"

platformforge/core/workspace.py

@@ -0,0 +1,89 @@
+"""Workspace model — Platform Forge works globally-installed, inside a repo,
+across multi-repo workspaces, in CI and in containers.
+
+`workspace.yaml` at a root joins related repos (application / infra / gitops /
+platform) into one analyzable system.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+PF_DIR = ".platformforge"
+WORKSPACE_FILE = "workspace.yaml"
+
+
+@dataclass
+class WorkspaceMember:
+    name: str
+    path: str
+    role: str = ""  # application | infra | gitops | platform
+    attrs: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Workspace:
+    root: Path
+    members: list[WorkspaceMember] = field(default_factory=list)
+    name: str = ""
+
+    @property
+    def pf_dir(self) -> Path:
+        return self.root / PF_DIR
+
+    @property
+    def is_multi_repo(self) -> bool:
+        return len(self.members) > 1
+
+    def member_paths(self) -> list[Path]:
+        if not self.members:
+            return [self.root]
+        return [(self.root / m.path).resolve() for m in self.members]
+
+
+def find_root(start: str | Path) -> Path:
+    """Walk up to the nearest .platformforge/ or workspace.yaml, else `start`."""
+    p = Path(start).resolve()
+    for cand in [p, *p.parents]:
+        if (cand / PF_DIR).is_dir() or (cand / WORKSPACE_FILE).is_file():
+            return cand
+    return p
+
+
+def init_workspace(root: str | Path, name: str = "") -> Path:
+    root = Path(root).resolve()
+    pf = root / PF_DIR
+    for sub in ("store", "receipts", "cache", "sdd", "ledger"):
+        (pf / sub).mkdir(parents=True, exist_ok=True)
+    ws = root / WORKSPACE_FILE
+    if not ws.exists():
+        ws.write_text(
+            yaml.safe_dump(
+                {"schema": "platformforge/workspace/v1",
+                 "name": name or root.name,
+                 "members": [{"name": root.name, "path": ".", "role": "platform"}]},
+                sort_keys=False,
+            )
+        )
+    return pf
+
+
+def load_workspace(start: str | Path) -> Workspace:
+    root = find_root(start)
+    ws_file = root / WORKSPACE_FILE
+    members: list[WorkspaceMember] = []
+    name = root.name
+    if ws_file.is_file():
+        doc = yaml.safe_load(ws_file.read_text()) or {}
+        name = doc.get("name", name)
+        for m in doc.get("members", []):
+            members.append(WorkspaceMember(
+                name=m.get("name", ""), path=m.get("path", "."),
+                role=m.get("role", ""), attrs={k: v for k, v in m.items()
+                                              if k not in ("name", "path", "role")},
+            ))
+    return Workspace(root=root, members=members, name=name)

platformforge/data/contracts/agent-handoff.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "platformforge/agent-handoff/v1",
+  "title": "PlatformForge AgentHandoff — structured agent transfer",
+  "type": "object",
+  "required": ["schema", "from", "to", "task_id"],
+  "properties": {
+    "schema": {"const": "platformforge/agent-handoff/v1"},
+    "from": {"type": "string", "minLength": 1},
+    "to": {"type": "string", "minLength": 1},
+    "task_id": {"type": "string", "minLength": 1},
+    "reason": {"type": "string"},
+    "completed": {"type": "array", "items": {"type": "string"}},
+    "evidence": {"type": "array", "items": {"type": "string"},
+                 "description": "fact_id / artifact refs only — never raw bodies"},
+    "findings": {"type": "array", "items": {"type": "string"}},
+    "open_questions": {"type": "array", "items": {"type": "string"}},
+    "unresolved": {"type": "array", "items": {"type": "string"}},
+    "budget_spent": {"type": "object"},
+    "budget_remaining": {"type": "object"},
+    "next_required_capability": {"type": "string"},
+    "context_pack_ref": {"type": "string",
+                         "description": "hash ref to a context pack"}
+  },
+  "additionalProperties": false
+}