engineering-platform 2.2.0__py3-none-any.whl

engineering_platform/repository_handoff.py

@@ -0,0 +1,95 @@
+"""Generate reviewable, sanitized repository run-handoff records."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+import argparse
+import json
+from pathlib import Path
+
+from .agent_state import redact_diagnostic
+
+
+def publish(
+    root: Path,
+    *,
+    run_id: str,
+    platform_version: str,
+    implementation_pr: int,
+    finalization_pr: int,
+    objective: str = "Engineering transaction",
+) -> Path:
+    """Publish only durable completion metadata after a successful finalization."""
+    directory = root / "docs" / "engineering" / "runs" / str(datetime.now(timezone.utc).year)
+    directory.mkdir(parents=True, exist_ok=True)
+    stamp = datetime.now(timezone.utc)
+    relative = directory / f"{stamp.date().isoformat()}-{run_id}.md"
+    body = "\n".join(
+        (
+            "# Engineering Run Handoff",
+            "",
+            f"- Engineering Platform: `{platform_version}`",
+            f"- Run ID: `{run_id}`",
+            f"- Completed: `{stamp.isoformat()}`",
+            f"- Objective: {redact_diagnostic(objective)}",
+            f"- Implementation PR: `#{implementation_pr}`",
+            f"- Finalization PR: `#{finalization_pr}`",
+            "- Repository State: `MERGED_RECONCILED`",
+            "- Workspace State: `WORKSPACE_READY`",
+            "",
+            "## Platform Architect Handoff",
+            "",
+            "- Recommended next capability: repository-evidence-based selection by the Product & Platform Architect.",
+            "- Architect attention: no remote authority, release, deployment or publication authority was added.",
+            "- Qualification summary: validate the completed increment before relying on it.",
+            "",
+        )
+    )
+    relative.write_text(body, encoding="utf-8")
+    latest = root / "docs" / "engineering" / "runs" / "latest.md"
+    latest.write_text(
+        f"# Latest Engineering Run\n\n- Run ID: `{run_id}`\n- Engineering Platform: `{platform_version}`\n- Implementation PR: `#{implementation_pr}`\n- Finalization PR: `#{finalization_pr}`\n- Repository State: `MERGED_RECONCILED`\n- Workspace State: `WORKSPACE_READY`\n- Handoff: `{relative.relative_to(root)}`\n",
+        encoding="utf-8",
+    )
+    index = {
+        "schema_version": 1,
+        "latest_run_id": run_id,
+        "completed_at": stamp.isoformat(),
+        "platform_version": platform_version,
+        "report_path": str(relative.relative_to(root)),
+        "implementation_pr": implementation_pr,
+        "finalization_pr": finalization_pr,
+        "repository_state": "MERGED_RECONCILED",
+        "workspace_state": "WORKSPACE_READY",
+    }
+    (root / "docs" / "engineering" / "runs" / "index.json").write_text(
+        json.dumps(index, indent=2, sort_keys=True) + "\n", encoding="utf-8"
+    )
+    return relative
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Write the handoff record on the Finalization PR branch before merge."""
+    parser = argparse.ArgumentParser(
+        prog="engineering-repository-handoff",
+        description="Publish durable Engineering Platform Finalization handoff records.",
+    )
+    parser.add_argument("--run-id", required=True)
+    parser.add_argument("--platform-version", required=True)
+    parser.add_argument("--implementation-pr", required=True, type=int)
+    parser.add_argument("--finalization-pr", required=True, type=int)
+    parser.add_argument("--root", type=Path, default=Path.cwd())
+    args = parser.parse_args(argv)
+    handoff = publish(
+        args.root.resolve(),
+        run_id=args.run_id,
+        platform_version=args.platform_version,
+        implementation_pr=args.implementation_pr,
+        finalization_pr=args.finalization_pr,
+    )
+    print(handoff)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

engineering_platform/resources.py

@@ -0,0 +1,38 @@
+"""Access to resources owned by the installed Engineering Platform package.
+
+Project roots contain consumer-owned state.  They are never used to locate
+Engineering Platform defaults or metadata.
+"""
+from __future__ import annotations
+
+from importlib.resources import files
+from pathlib import Path
+
+
+class PackageResourceError(FileNotFoundError):
+    """Raised when a required Engineering Platform package resource is absent."""
+
+
+def package_text(name: str) -> str:
+    """Read one required UTF-8 resource from the installed package.
+
+    This deliberately has no checkout, working-directory, or project-root
+    fallback.  A missing resource is an invalid package installation.
+    """
+    resource = files("engineering_platform").joinpath(name)
+    if not resource.is_file():
+        raise PackageResourceError(f"Engineering Platform package resource is missing: {name}")
+    return resource.read_text(encoding="utf-8")
+
+
+def package_path(name: str) -> Path:
+    """Return a filesystem path for one required installed package resource.
+
+    Engineering Platform wheels are installed as regular package directories;
+    callers which require a path therefore receive the package-owned path,
+    never a path inferred from a project checkout.
+    """
+    resource = files("engineering_platform").joinpath(name)
+    if not resource.is_file():
+        raise PackageResourceError(f"Engineering Platform package resource is missing: {name}")
+    return Path(resource)

engineering_platform/reviewer_evidence.py

@@ -0,0 +1,70 @@
+"""Bounded, run-scoped repository facts for independent reviewer prompts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .execution_models import RepositoryEvidence
+
+
+@dataclass(frozen=True)
+class ReviewerEvidence:
+    """A minimal post-synchronization fact set, valid for one reviewer wave.
+
+    The Execution Host creates this after its repository synchronization while
+    holding the run lease.  It contains facts, never command output or
+    conclusions.  A caller must create a new instance after any repository,
+    validation, PR, merge, finalization, or cleanup boundary.
+    """
+
+    run_id: str
+    repository: str
+    execution_mode: str
+    branch: str
+    head_sha: str
+    worktree: str
+    main_contains_head: bool
+    freshness_boundary: str = "post_synchronization_pre_reviewer_wave"
+
+    @classmethod
+    def from_repository(
+        cls, run_id: str, execution_mode: str, evidence: RepositoryEvidence
+    ) -> "ReviewerEvidence":
+        return cls(
+            run_id=run_id,
+            repository=evidence.repository,
+            execution_mode=execution_mode,
+            branch=evidence.branch,
+            head_sha=evidence.head_sha,
+            worktree="clean" if evidence.clean else "dirty",
+            main_contains_head=evidence.main_contains_head,
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        # Keep the wire projection deliberately explicit about freshness.  The
+        # data class stays flat so callers cannot accidentally substitute a
+        # mutable observation for a run-stable identity field.
+        return {
+            "run_id": self.run_id,
+            "run_stable": {
+                "repository": self.repository,
+                "execution_mode": self.execution_mode,
+            },
+            "mutable": {
+                "branch": self.branch,
+                "head_sha": self.head_sha,
+                "worktree": self.worktree,
+                "main_contains_head": self.main_contains_head,
+            },
+            "boundary_sensitive": {
+                "freshness_boundary": self.freshness_boundary,
+                "invalidated_by": (
+                    "repository_mutation",
+                    "validation",
+                    "pull_request_mutation",
+                    "merge",
+                    "finalization",
+                    "repository_cleanup",
+                ),
+            },
+        }

engineering_platform/schemas/repository-attachment.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://engineering-platform.dev/schemas/repository-attachment/1.0",
+  "title": "Engineering Platform repository attachment",
+  "description": "Declarative, repository-local project attachment metadata. It is never executable configuration.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "project", "repository", "validation"],
+  "properties": {
+    "schema_version": {"const": "1.0"},
+    "project": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "authority_repository_id"],
+      "properties": {
+        "id": {"$ref": "#/$defs/identifier"},
+        "authority_repository_id": {"$ref": "#/$defs/identifier"}
+      }
+    },
+    "repository": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "role"],
+      "properties": {
+        "id": {"$ref": "#/$defs/identifier"},
+        "role": {"enum": ["authority", "child"]}
+      }
+    },
+    "validation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind"],
+      "properties": {
+        "kind": {"enum": ["command", "script", "workflow", "none"]},
+        "entrypoint": {"type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[^\\u0000\\r\\n]+$"},
+        "description": {"type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[^\\u0000\\r\\n]+$"}
+      },
+      "allOf": [
+        {"if": {"properties": {"kind": {"const": "none"}}}, "then": {"not": {"required": ["entrypoint"]}}},
+        {"if": {"properties": {"kind": {"enum": ["command", "script", "workflow"]}}}, "then": {"required": ["entrypoint"]}}
+      ]
+    },
+    "requirements": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "host": {"type": "object", "propertyNames": {"$ref": "#/$defs/metadata_key"}, "additionalProperties": {"type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[^\\u0000\\r\\n]+$"}},
+        "tools": {"type": "object", "propertyNames": {"$ref": "#/$defs/metadata_key"}, "additionalProperties": {"type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[^\\u0000\\r\\n]+$"}}
+      }
+    },
+    "integrations": {
+      "type": "object",
+      "propertyNames": {"$ref": "#/$defs/metadata_key"},
+      "additionalProperties": {"type": "object", "additionalProperties": true}
+    }
+  },
+  "$defs": {
+    "identifier": {"type": "string", "minLength": 3, "maxLength": 128, "pattern": "^[a-z0-9][a-z0-9._-]*$"},
+    "metadata_key": {"type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9._-]*$"}
+  }
+}