engineering-platform 2.2.0__py3-none-any.whl

engineering_platform/recommendation_handoff.py

@@ -0,0 +1,238 @@
+"""Read-only projection of an immutable Forge governance handoff snapshot."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+import re
+from typing import Any
+
+
+FORGE_GOVERNANCE_HANDOFF_VERSION = "1.0"
+_MAX_TEXT = 2_000
+_REPORT = re.compile(r"(?ms)^## Forge Governance Handoff\s*$.*?^### Immutable Handoff Snapshot\s*$\n```json\s*(\{.*?\})\s*```")
+_LEGACY_REPORT = re.compile(r"(?ms)^## Forge Mission Recommendation Handoff\s*$.*?^```json\s*(\{.*?\})\s*```")
+
+
+class ForgeGovernanceHandoffError(ValueError):
+    """Raised only when a supplied Forge handoff cannot meet its transport contract."""
+
+
+def _text(value: object) -> str | None:
+    if not isinstance(value, str):
+        return None
+    value = " ".join(value.strip().split())
+    return value[:_MAX_TEXT] if value else None
+
+
+def _value(raw: dict[str, Any], *keys: str) -> str | None:
+    for key in keys:
+        value = _text(raw.get(key))
+        if value is not None:
+            return value
+    return None
+
+
+def _items(value: object) -> tuple[str, ...]:
+    if not isinstance(value, list):
+        return ()
+    return tuple(item for entry in value if (item := _text(entry)))[:50]
+
+
+def _rank(value: object) -> int | None:
+    return value if isinstance(value, int) and not isinstance(value, bool) and value > 0 else None
+
+
+def validate_forge_governance_handoff(payload: object) -> dict[str, object]:
+    """Validate transport shape without deriving any Forge governance meaning.
+
+    Unknown future fields are retained verbatim.  Known fields are checked only
+    when supplied, so legacy and incrementally richer Forge producers remain
+    compatible while malformed supplied handoffs fail closed at ingress.
+    """
+    if not isinstance(payload, dict):
+        raise ForgeGovernanceHandoffError("Forge Governance Handoff payload must be an object.")
+    if payload.get("version") != FORGE_GOVERNANCE_HANDOFF_VERSION:
+        raise ForgeGovernanceHandoffError("Forge Governance Handoff version is unsupported.")
+    for name in ("recommendation_set", "selected_recommendation", "decision_evidence", "business_workspace", "governance", "mission_runtime"):
+        if name in payload and payload[name] is not None and not isinstance(payload[name], dict):
+            raise ForgeGovernanceHandoffError(f"Forge Governance Handoff {name} must be an object when supplied.")
+    alternatives = payload.get("alternatives", payload.get("alternative_recommendations"))
+    if alternatives is not None:
+        if not isinstance(alternatives, list) or not all(isinstance(item, dict) for item in alternatives):
+            raise ForgeGovernanceHandoffError("Forge Governance Handoff alternatives must be an array of objects when supplied.")
+    selected = payload.get("selected_recommendation")
+    if selected is not None and not isinstance(selected, dict):
+        raise ForgeGovernanceHandoffError("Forge Governance Handoff selected_recommendation must be an object when supplied.")
+    return payload
+
+
+@dataclass(frozen=True)
+class Recommendation:
+    recommendation_id: str | None
+    rank: int | None
+    title: str | None
+    mission_origin: str | None
+    lifecycle_status: str | None
+    business_summary: str | None
+    engineering_summary: str | None
+    business_value: str | None
+    architecture_value: str | None
+    engineering_value: str | None
+    risk_if_deferred: str | None
+    dependencies: tuple[str, ...]
+    constraints: tuple[str, ...]
+    confidence: str | None
+    evidence_references: tuple[str, ...]
+
+    @classmethod
+    def from_mapping(cls, raw: object) -> "Recommendation":
+        mapping = raw if isinstance(raw, dict) else {}
+        return cls(
+            recommendation_id=_value(mapping, "recommendation_id", "id"), rank=_rank(mapping.get("rank")),
+            title=_value(mapping, "title", "recommendation_title"), mission_origin=_value(mapping, "mission_origin"),
+            lifecycle_status=_value(mapping, "lifecycle_status", "status", "recommendation_status"),
+            business_summary=_value(mapping, "business_summary", "summary"), engineering_summary=_value(mapping, "engineering_summary"),
+            business_value=_value(mapping, "business_value"), architecture_value=_value(mapping, "architecture_value", "architectural_value"),
+            engineering_value=_value(mapping, "engineering_value"), risk_if_deferred=_value(mapping, "risk_if_deferred"),
+            dependencies=_items(mapping.get("dependencies")), constraints=_items(mapping.get("constraints")),
+            confidence=_value(mapping, "confidence"), evidence_references=_items(mapping.get("evidence_references")),
+        )
+
+
+@dataclass(frozen=True)
+class ForgeGovernanceHandoff:
+    snapshot: dict[str, object]
+    recommendation_set_id: str | None
+    recommendation_set_timestamp: str | None
+    recommendation_count: int | None
+    selected: Recommendation
+    alternatives: tuple[Recommendation, ...]
+    decision_evidence: dict[str, object] | None
+    business_workspace: dict[str, object] | None
+    governance: dict[str, object] | None
+    mission_runtime: dict[str, object] | None
+
+    @classmethod
+    def from_snapshot(cls, snapshot: dict[str, object]) -> "ForgeGovernanceHandoff":
+        data = validate_forge_governance_handoff(snapshot)
+        recommendation_set = data.get("recommendation_set") if isinstance(data.get("recommendation_set"), dict) else {}
+        selected_raw = data.get("selected_recommendation") if isinstance(data.get("selected_recommendation"), dict) else {}
+        alternatives_raw = data.get("alternatives", data.get("alternative_recommendations", []))
+        alternatives = tuple(Recommendation.from_mapping(item) for item in alternatives_raw if isinstance(item, dict)) if isinstance(alternatives_raw, list) else ()
+        count = recommendation_set.get("count", data.get("recommendation_count"))
+        return cls(
+            snapshot=data, recommendation_set_id=_value(recommendation_set, "id", "recommendation_set_id") or _value(data, "recommendation_set_id"),
+            recommendation_set_timestamp=_value(recommendation_set, "timestamp", "created_at") or _value(data, "recommendation_set_timestamp"),
+            recommendation_count=count if isinstance(count, int) and not isinstance(count, bool) and count >= 0 else None,
+            selected=Recommendation.from_mapping(selected_raw), alternatives=alternatives,
+            decision_evidence=data.get("decision_evidence") if isinstance(data.get("decision_evidence"), dict) else None,
+            business_workspace=data.get("business_workspace") if isinstance(data.get("business_workspace"), dict) else None,
+            governance=data.get("governance") if isinstance(data.get("governance"), dict) else None,
+            mission_runtime=data.get("mission_runtime") if isinstance(data.get("mission_runtime"), dict) else None,
+        )
+
+    @property
+    def completeness(self) -> str:
+        required = (self.selected.recommendation_id, self.selected.title, self.selected.rank, self.selected.lifecycle_status, self.selected.confidence, self.decision_evidence_id, self.alternatives, self.business_approval_state)
+        return "COMPLETE" if all(value is not None and value != () for value in required) else "INCOMPLETE"
+
+    @property
+    def decision_evidence_id(self) -> str | None:
+        return _value(self.decision_evidence or {}, "id", "decision_evidence_id")
+
+    @property
+    def business_approval_state(self) -> str | None:
+        return _value(self.governance or {}, "business_approval_state")
+
+
+def _display(value: object) -> str:
+    if isinstance(value, tuple):
+        return ", ".join(value) or "NOT SUPPLIED BY PRODUCER"
+    return str(value) if value is not None else "NOT SUPPLIED BY PRODUCER"
+
+
+def _provenance(source: str) -> str:
+    return f"[Source: {source}]"
+
+
+def handoff_from_report(report: str) -> dict[str, object] | None:
+    """Read the already-rendered immutable snapshot for legacy report detail views."""
+    match = _REPORT.search(report) or _LEGACY_REPORT.search(report)
+    if match is None:
+        return None
+    try:
+        payload = json.loads(match.group(1))
+    except json.JSONDecodeError:
+        return None
+    return payload if isinstance(payload, dict) else None
+
+
+def report_lines(handoff: ForgeGovernanceHandoff | None, execution_status: str) -> tuple[str, ...]:
+    """Render only values explicitly supplied in the immutable snapshot."""
+    if handoff is None:
+        return (
+            "## Forge Governance Handoff", "- Forge Governance Handoff: `NOT SUPPLIED BY PRODUCER`",
+            "- Governance Status: `FORGE GOVERNANCE HANDOFF NOT SUPPLIED`", "- Decision Evidence: `NOT SUPPLIED BY PRODUCER`",
+            "- Governance Handoff Completeness: `INCOMPLETE`", "- Business Review Readiness: `NOT SUPPLIED BY PRODUCER`", "",
+        )
+    selected = handoff.selected
+    evidence = handoff.decision_evidence or {}
+    workspace = handoff.business_workspace or {}
+    governance = handoff.governance or {}
+    runtime = handoff.mission_runtime or {}
+    governance_status = _value(governance, "status", "governance_status") or "FORGE GOVERNANCE HANDOFF SUPPLIED"
+    readiness = _value(governance, "business_review_readiness", "readiness")
+    lines = [
+        "## Forge Governance Handoff",
+        "Forge owns governance truth. Engineering Platform persists and projects this supplied snapshot immutably; completeness is factual reporting, not governance authority.",
+        "- Forge Governance Handoff: `SUPPLIED BY PRODUCER; PERSISTED IMMUTABLY`",
+        f"- Governance Status: `{governance_status}` {_provenance('Forge Governance Handoff payload')}",
+        f"- Governance Handoff Completeness: `{handoff.completeness}` {_provenance('Forge Governance Handoff payload')}",
+        f"- Business Review Readiness: `{_display(readiness)}` {_provenance('Forge Governance Handoff payload')}",
+        f"- Recommendation Set ID: `{_display(handoff.recommendation_set_id)}` {_provenance('Forge Governance Handoff payload')}",
+        f"- Recommendation Set Timestamp: {_display(handoff.recommendation_set_timestamp)} {_provenance('Forge Governance Handoff payload')}",
+        f"- Recommendation Count: {_display(handoff.recommendation_count)} {_provenance('Forge Governance Handoff payload')}",
+        f"- Selected Recommendation ID: `{_display(selected.recommendation_id)}` {_provenance('Forge Governance Handoff payload')}",
+        f"- Selected Recommendation Rank: {_display(selected.rank)} {_provenance('Forge Governance Handoff payload')}",
+        f"- Selected Recommendation Title: {_display(selected.title)} {_provenance('Forge Governance Handoff payload')}",
+        f"- Selected Mission Origin: {_display(selected.mission_origin)} {_provenance('Forge Governance Handoff payload')}",
+        f"- Selected Lifecycle Status: {_display(selected.lifecycle_status)} {_provenance('Forge Governance Handoff payload')}",
+        f"- Selected Business Summary: {_display(selected.business_summary)} {_provenance('Forge Governance Handoff payload')}",
+        f"- Selected Engineering Summary: {_display(selected.engineering_summary)} {_provenance('Forge Governance Handoff payload')}",
+        f"- Selected Business Value: {_display(selected.business_value)} {_provenance('Forge Governance Handoff payload')}",
+        f"- Selected Architecture Value: {_display(selected.architecture_value)} {_provenance('Forge Governance Handoff payload')}",
+        f"- Selected Engineering Value: {_display(selected.engineering_value)} {_provenance('Forge Governance Handoff payload')}",
+        f"- Selected Risk If Deferred: {_display(selected.risk_if_deferred)} {_provenance('Forge Governance Handoff payload')}",
+        f"- Selected Dependencies: {_display(selected.dependencies)} {_provenance('Forge Governance Handoff payload')}",
+        f"- Selected Constraints: {_display(selected.constraints)} {_provenance('Forge Governance Handoff payload')}",
+        f"- Selected Confidence: {_display(selected.confidence)} {_provenance('Forge Governance Handoff payload')}",
+        f"- Selected Evidence References: {_display(selected.evidence_references)} {_provenance('Forge Governance Handoff payload')}",
+        f"- Decision Evidence ID: `{_display(_value(evidence, 'id', 'decision_evidence_id'))}` {_provenance('Forge Governance Handoff payload')}",
+        f"- Decision Evidence Type: {_display(_value(evidence, 'type', 'decision_evidence_type'))} {_provenance('Forge Governance Handoff payload')}",
+        f"- Decision Evidence Timestamp: {_display(_value(evidence, 'timestamp', 'created_at'))} {_provenance('Forge Governance Handoff payload')}",
+        f"- Decision Evidence Confidence: {_display(_value(evidence, 'confidence'))} {_provenance('Forge Governance Handoff payload')}",
+        f"- Decision Evidence References: {_display(_items(evidence.get('references')))} {_provenance('Forge Governance Handoff payload')}",
+        f"- Business Workspace Availability: {_display(_value(workspace, 'availability', 'state'))} {_provenance('Forge Governance Handoff payload')}",
+        f"- Business Workspace Reference: {_display(_value(workspace, 'reference', 'id'))} {_provenance('Forge Governance Handoff payload')}",
+        f"- Business Workspace Projected Selected Recommendation ID: {_display(_value(workspace, 'projected_selected_recommendation_id'))} {_provenance('Forge Governance Handoff payload')}",
+        f"- Business Workspace Projection Match State: {_display(_value(workspace, 'projection_match_state'))} {_provenance('Forge Governance Handoff payload')}",
+        f"- Business Approval State: {_display(_value(governance, 'business_approval_state'))} {_provenance('Forge Governance Handoff payload')}",
+        f"- Architecture Approval State: {_display(_value(governance, 'architecture_approval_state'))} {_provenance('Forge Governance Handoff payload')}",
+        f"- Mission Candidate ID: `{_display(_value(runtime, 'mission_candidate_id'))}` {_provenance('Forge Governance Handoff payload')}",
+        f"- Mission ID: `{_display(_value(runtime, 'mission_id'))}` {_provenance('Forge Governance Handoff payload')}",
+        f"- Mission Runtime State: {_display(_value(runtime, 'mission_runtime_state'))} {_provenance('Forge Governance Handoff payload')}",
+        f"- Scheduler State: {_display(_value(runtime, 'scheduler_state'))} {_provenance('Forge Governance Handoff payload')}",
+        "### Alternatives",
+    ]
+    if not handoff.alternatives:
+        lines.append("- Alternatives: `NOT SUPPLIED BY PRODUCER`")
+    for item in handoff.alternatives:
+        lines.extend((
+            f"- Recommendation ID: `{_display(item.recommendation_id)}`; Rank: {_display(item.rank)}; Title: {_display(item.title)}",
+            f"  - Mission Origin: {_display(item.mission_origin)}; Lifecycle Status: {_display(item.lifecycle_status)}",
+            f"  - Business Value: {_display(item.business_value)}; Architecture Value: {_display(item.architecture_value)}; Engineering Value: {_display(item.engineering_value)}",
+            f"  - Risk If Deferred: {_display(item.risk_if_deferred)}; Dependencies: {_display(item.dependencies)}; Confidence: {_display(item.confidence)} {_provenance('Forge Governance Handoff payload')}",
+        ))
+    lines.extend(("### Immutable Handoff Snapshot", "```json", json.dumps(handoff.snapshot, sort_keys=True), "```", ""))
+    return tuple(lines)

engineering_platform/report_analysis.py

@@ -0,0 +1,193 @@
+"""Read-only, redacted Codex analysis of one terminal Engineering Report."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+import tempfile
+
+from .agent_state import redact_diagnostic
+from .providers import CodexCliProvider
+
+
+MAX_ANALYSIS_LENGTH = 8_000
+MAX_REPORT_CONTEXT_LENGTH = 300_000
+_RUN_ID = __import__("re").compile(r"^[a-z0-9][a-z0-9-]{0,63}$")
+
+
+class AnalysisProcessingError(ValueError):
+    """A safe, user-presentable reason for rejecting advisory output."""
+
+
+_PROCESSING_REASONS = {
+    "processed": "De Codex-analyse is volgens het verplichte structuurcontract verwerkt.",
+    "report_unavailable": "Het Engineeringrapport was niet beschikbaar voor deze analyse.",
+    "provider_failed": "De EP-beheerde Codex CLI kon de analyseopdracht niet afronden.",
+    "provider_unavailable": "De EP-beheerde Codex CLI was niet beschikbaar voor de analyseopdracht.",
+    "invalid_structured_response": "Codex gaf geen geldig gestructureerd analyseantwoord terug.",
+}
+
+
+def _final_message(output: str) -> str:
+    """Extract the terminal agent message from Codex JSONL output."""
+    for line in reversed(output.splitlines()):
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        item = event.get("item") if isinstance(event, dict) else None
+        if (
+            event.get("type") == "item.completed"
+            and isinstance(item, dict)
+            and item.get("type") == "agent_message"
+            and isinstance(item.get("text"), str)
+        ):
+            return item["text"]
+    return output.strip().splitlines()[-1] if output.strip() else ""
+
+
+def _schema() -> dict[str, object]:
+    return {
+        "type": "object",
+        "additionalProperties": False,
+        "properties": {
+            "summary": {"type": "string"},
+            "findings": {"type": "array", "items": {"type": "string"}},
+            "issues": {"type": "array", "items": {"type": "string"}},
+            "risks": {"type": "array", "items": {"type": "string"}},
+            "next_steps": {"type": "array", "items": {"type": "string"}},
+            "product_architect_advice": {"type": "string"},
+        },
+        "required": (
+            "summary",
+            "findings",
+            "issues",
+            "risks",
+            "next_steps",
+            "product_architect_advice",
+        ),
+    }
+
+
+def _markdown(payload: dict[str, object], *, processing_status: str = "processed") -> str:
+    def items(value: object) -> str:
+        values = value if isinstance(value, list) else []
+        lines = [f"- {redact_diagnostic(str(item), limit=1_000)}" for item in values if isinstance(item, str)]
+        return "\n".join(lines) if lines else "- Geen vastgesteld."
+
+    return "\n".join(
+        (
+            "# Codex-analyse van Engineeringrapport",
+            "",
+            "Deze analyse is adviserend. Het terminale checkpoint, repositorybewijs, commits en validatie blijven de bron van waarheid.",
+            "",
+            "## Analyseverwerking",
+            f"- Status: `{processing_status}`",
+            f"- Reden: {_PROCESSING_REASONS[processing_status]}",
+            "",
+            "## Samenvatting",
+            redact_diagnostic(str(payload.get("summary", "Analyse niet beschikbaar.")), limit=1_500),
+            "",
+            "## Bevindingen",
+            items(payload.get("findings")),
+            "",
+            "## Issues",
+            items(payload.get("issues")),
+            "",
+            "## Risico's",
+            items(payload.get("risks")),
+            "",
+            "## Volgende stappen",
+            items(payload.get("next_steps")),
+            "",
+            "## Advies aan Product Architect",
+            redact_diagnostic(str(payload.get("product_architect_advice", "Geen aanvullend advies beschikbaar.")), limit=1_500),
+            "",
+        )
+    )[:MAX_ANALYSIS_LENGTH]
+
+
+def _write(root: Path, run_id: str, value: str) -> Path:
+    directory = root / ".engineering" / "report-analysis"
+    directory.mkdir(mode=0o700, parents=True, exist_ok=True)
+    destination = directory / f"{run_id}.md"
+    descriptor, temporary = tempfile.mkstemp(prefix=f".{run_id}.", suffix=".tmp", dir=directory)
+    try:
+        os.fchmod(descriptor, 0o600)
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            handle.write(value)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, destination)
+    finally:
+        Path(temporary).unlink(missing_ok=True)
+    return destination
+
+
+def _fallback(root: Path, run_id: str, status: str, summary: str) -> Path:
+    """Write a controlled processing reason without persisting provider output."""
+    return _write(root, run_id, _markdown({"summary": summary}, processing_status=status))
+
+
+def _payload(output: str) -> dict[str, object]:
+    """Accept only an object containing each required structured field."""
+    try:
+        raw = json.loads(_final_message(output))
+    except json.JSONDecodeError as error:
+        raise AnalysisProcessingError("invalid structured response") from error
+    if not isinstance(raw, dict) or set(_schema()["required"]) - set(raw):
+        raise AnalysisProcessingError("invalid structured response")
+    return raw
+
+
+def _bounded_report_context(report_text: str) -> str:
+    """Keep advisory input below the provider limit without altering report evidence."""
+    if len(report_text) <= MAX_REPORT_CONTEXT_LENGTH:
+        return report_text
+    first = MAX_REPORT_CONTEXT_LENGTH // 2
+    last = MAX_REPORT_CONTEXT_LENGTH - first
+    omitted = len(report_text) - first - last
+    return (
+        report_text[:first]
+        + f"\n\n[Analysecontext ingekort: {omitted} tekens uit het midden zijn niet aan Codex aangeboden. "
+        "Het volledige Engineeringrapport blijft de bron van waarheid.]\n\n"
+        + report_text[-last:]
+    )
+
+
+def analyze(root: Path, run_id: str, report: Path) -> Path:
+    """Persist a bounded advisory analysis; failure never changes transaction outcome."""
+    if not _RUN_ID.fullmatch(run_id):
+        raise ValueError("run_id is invalid")
+    try:
+        report_text = report.read_text(encoding="utf-8")
+    except OSError:
+        return _fallback(root, run_id, "report_unavailable", "Engineeringrapport was niet beschikbaar voor analyse.")
+    prompt = """Analyseer uitsluitend het onderstaande Engineeringrapport. Voer geen commando's uit, wijzig geen bestanden, doe geen netwerkverzoeken en doe geen aannames buiten het rapport. Het resultaat is adviserend: repositorybewijs, commits, validatie en het terminale checkpoint zijn altijd leidend. Geef compacte, feitelijke Nederlandse tekst voor samenvatting, bevindingen, issues, risico's, volgende stappen en advies aan de Product Architect. Herhaal geen geheimen, promptinhoud of ruwe loguitvoer.\n\nENGINEERINGRAPPORT:\n""" + _bounded_report_context(report_text)
+    schema_path: Path | None = None
+    try:
+        state_directory = root / ".engineering"
+        state_directory.mkdir(mode=0o700, parents=True, exist_ok=True)
+        with tempfile.NamedTemporaryFile("w", encoding="utf-8", suffix=".json", dir=state_directory, delete=False) as handle:
+            json.dump(_schema(), handle)
+            schema_path = Path(handle.name)
+        completed = CodexCliProvider().invoke(
+            root,
+            (
+                "codex", "exec", "--sandbox", "read-only", "-C", str(root), "--json",
+                "--output-schema", str(schema_path), "-",
+            ),
+            input_text=prompt,
+        )
+        if completed.returncode:
+            return _fallback(root, run_id, "provider_failed", "Codex-analyse kon niet worden uitgevoerd. De Engineering-uitkomst blijft ongewijzigd.")
+        raw = _payload(completed.stdout)
+        return _write(root, run_id, _markdown(raw))
+    except OSError:
+        return _fallback(root, run_id, "provider_unavailable", "Codex-analyse kon niet worden uitgevoerd. De Engineering-uitkomst blijft ongewijzigd.")
+    except AnalysisProcessingError:
+        return _fallback(root, run_id, "invalid_structured_response", "Codex-analyse kon niet veilig worden verwerkt. De Engineering-uitkomst blijft ongewijzigd.")
+    finally:
+        if schema_path is not None:
+            schema_path.unlink(missing_ok=True)

engineering_platform/repository_attachment.py

@@ -0,0 +1,171 @@
+"""Read-only repository attachment contract for future EP Project Agents.
+
+This module validates declarations only.  It never executes a validation
+entrypoint, probes a host, writes local state, or registers with a server.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+from pathlib import Path
+import re
+from typing import Any, Mapping
+
+
+CONFIG_RELATIVE_PATH = Path(".engineering-platform/repository.json")
+SCHEMA_VERSION = "1.0"
+SCHEMA_RESOURCE = "schemas/repository-attachment.schema.json"
+_IDENTIFIER = re.compile(r"^[a-z0-9][a-z0-9._-]*$")
+_METADATA_KEY = re.compile(r"^[a-z][a-z0-9._-]*$")
+_ROLES = frozenset({"authority", "child"})
+_VALIDATION_KINDS = frozenset({"command", "script", "workflow", "none"})
+
+
+class RepositoryAttachmentError(ValueError):
+    """Raised when a repository attachment is absent or structurally unsafe."""
+
+
+@dataclass(frozen=True)
+class ValidationBoundary:
+    kind: str
+    entrypoint: str | None
+    description: str | None
+
+
+@dataclass(frozen=True)
+class RepositoryAttachment:
+    project_id: str
+    authority_repository_id: str
+    repository_id: str
+    repository_role: str
+    validation: ValidationBoundary
+    host_requirements: Mapping[str, str]
+    tool_requirements: Mapping[str, str]
+    integrations: Mapping[str, Mapping[str, Any]]
+
+    def agent_read_surface(self) -> dict[str, object]:
+        """Return the deliberately small, non-secret future Agent read surface."""
+        return {
+            "schema_version": SCHEMA_VERSION,
+            "project": {
+                "id": self.project_id,
+                "authority_repository_id": self.authority_repository_id,
+            },
+            "repository": {"id": self.repository_id, "role": self.repository_role},
+            "validation": {
+                "kind": self.validation.kind,
+                "entrypoint": self.validation.entrypoint,
+                "description": self.validation.description,
+            },
+            "requirements": {"host": dict(self.host_requirements), "tools": dict(self.tool_requirements)},
+            "integrations": {name: dict(metadata) for name, metadata in self.integrations.items()},
+        }
+
+
+def config_path(repository_root: Path) -> Path:
+    """Return the one canonical repository-local attachment location."""
+    return repository_root / CONFIG_RELATIVE_PATH
+
+
+def load_repository_attachment(repository_root: Path) -> RepositoryAttachment:
+    """Load and validate one repository declaration without discovering peers."""
+    path = config_path(repository_root)
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError as error:
+        raise RepositoryAttachmentError(f"repository attachment is missing: {CONFIG_RELATIVE_PATH}") from error
+    except json.JSONDecodeError as error:
+        raise RepositoryAttachmentError("repository attachment is not valid JSON") from error
+    return parse_repository_attachment(payload)
+
+
+def parse_repository_attachment(payload: object) -> RepositoryAttachment:
+    """Validate JSON-compatible attachment data against schema version 1.0."""
+    root = _object(payload, "attachment")
+    _only(root, {"schema_version", "project", "repository", "validation", "requirements", "integrations"}, "attachment")
+    if root.get("schema_version") != SCHEMA_VERSION:
+        raise RepositoryAttachmentError("unsupported repository attachment schema_version")
+
+    project = _object(_required(root, "project", "attachment"), "project")
+    _only(project, {"id", "authority_repository_id"}, "project")
+    project_id = _identifier(_required(project, "id", "project"), "project.id")
+    authority_repository_id = _identifier(_required(project, "authority_repository_id", "project"), "project.authority_repository_id")
+
+    repository = _object(_required(root, "repository", "attachment"), "repository")
+    _only(repository, {"id", "role"}, "repository")
+    repository_id = _identifier(_required(repository, "id", "repository"), "repository.id")
+    role = _required(repository, "role", "repository")
+    if role not in _ROLES:
+        raise RepositoryAttachmentError("repository.role must be authority or child")
+    if (role == "authority") != (repository_id == authority_repository_id):
+        raise RepositoryAttachmentError("repository.role and project.authority_repository_id disagree")
+
+    validation_data = _object(_required(root, "validation", "attachment"), "validation")
+    _only(validation_data, {"kind", "entrypoint", "description"}, "validation")
+    kind = _required(validation_data, "kind", "validation")
+    if kind not in _VALIDATION_KINDS:
+        raise RepositoryAttachmentError("validation.kind is unsupported")
+    entrypoint = validation_data.get("entrypoint")
+    if kind == "none" and entrypoint is not None:
+        raise RepositoryAttachmentError("validation.entrypoint is forbidden when validation.kind is none")
+    if kind != "none":
+        entrypoint = _bounded_text(entrypoint, "validation.entrypoint")
+    description = validation_data.get("description")
+    if description is not None:
+        description = _bounded_text(description, "validation.description")
+
+    requirements = _object(root.get("requirements", {}), "requirements")
+    _only(requirements, {"host", "tools"}, "requirements")
+    host = _string_map(requirements.get("host", {}), "requirements.host")
+    tools = _string_map(requirements.get("tools", {}), "requirements.tools")
+    integrations = _integration_map(root.get("integrations", {}))
+    return RepositoryAttachment(project_id, authority_repository_id, repository_id, role, ValidationBoundary(kind, entrypoint, description), host, tools, integrations)
+
+
+def _required(mapping: Mapping[str, Any], key: str, context: str) -> Any:
+    if key not in mapping:
+        raise RepositoryAttachmentError(f"{context}.{key} is required")
+    return mapping[key]
+
+
+def _object(value: object, context: str) -> Mapping[str, Any]:
+    if not isinstance(value, dict):
+        raise RepositoryAttachmentError(f"{context} must be an object")
+    return value
+
+
+def _only(mapping: Mapping[str, Any], allowed: set[str], context: str) -> None:
+    unexpected = set(mapping) - allowed
+    if unexpected:
+        raise RepositoryAttachmentError(f"{context} has unsupported fields: {', '.join(sorted(unexpected))}")
+
+
+def _identifier(value: object, context: str) -> str:
+    if not isinstance(value, str) or not 3 <= len(value) <= 128 or not _IDENTIFIER.fullmatch(value):
+        raise RepositoryAttachmentError(f"{context} must be a lowercase stable identifier")
+    return value
+
+
+def _bounded_text(value: object, context: str) -> str:
+    if not isinstance(value, str) or not value or len(value) > 512 or "\x00" in value or "\n" in value or "\r" in value:
+        raise RepositoryAttachmentError(f"{context} must be one non-empty line of at most 512 characters")
+    return value
+
+
+def _string_map(value: object, context: str) -> Mapping[str, str]:
+    mapping = _object(value, context)
+    return {_metadata_key(key, f"{context} key"): _bounded_text(item, f"{context}.{key}") for key, item in mapping.items()}
+
+
+def _integration_map(value: object) -> Mapping[str, Mapping[str, Any]]:
+    mapping = _object(value, "integrations")
+    result: dict[str, Mapping[str, Any]] = {}
+    for name, metadata in mapping.items():
+        result[_metadata_key(name, "integrations key")] = _object(metadata, f"integrations.{name}")
+    return result
+
+
+def _metadata_key(value: object, context: str) -> str:
+    if not isinstance(value, str) or not 1 <= len(value) <= 128 or not _METADATA_KEY.fullmatch(value):
+        raise RepositoryAttachmentError(f"{context} must be a lowercase metadata key")
+    return value