feat: route agent execution through Workspace Operation Plane contracts

[Copilot]

Agent runs were writing workspace artifacts as hidden side effects with no shared lifecycle, no admission gate, and no structured evidence for replay or audit. This adds the AgentOperationContract as the mandatory routing layer for all agent-initiated workspace mutations.

Schema & example

• schemas/agent-operation-contract.schema.v0.1.json — maps agent runs onto WorkspaceOperation, OperationTask, OperationEvent, Artifact, DecisionCard, and PolicyGateRecord
• examples/agent-operation-contract.example.json — canonical agent.patch.propose contract instance

Emit script

scripts/emit_agent_operation_contract.py writes an AgentOperationContract to spec.artifacts.outDir for all six supported operation types:

python3 scripts/emit_agent_operation_contract.py bundle.json \
  --operation-type agent.patch.propose \
  --operation-id op-20260506-001 \
  --acting-for user:octocat \
  --scope workspace:write --scope pr:propose \
  --artifact-type patch --artifact-ref artifacts/patch/my.diff \
  --policy-ref policy://agentplane/default-patch-propose \
  --policy-result allow

Key invariants enforced by the contract:

• Admission gate — artifacts land as admissionStatus: pending-review; agents cannot self-admit
• Delegated authority — every contract records actingFor, explicit scope[], optional budget, and policyProfileRef
• Idempotency — lifecycle.idempotencyKey = {operationId}/attempt-{n} prevents duplicate effects on retry
• Observable events — ordered events[] trail for the Operation Inspector
• Cancellation/compensation — lifecycle.cancellation and lifecycle.compensation leave structured evidence with recoverable artifact refs

Tooling & docs

• tools/validate_agent_operation_contract.py — deterministic smoke validator
• tools/tests/test_agent_operation_contract.py — 30 pytest tests
• docs/adr/0008-agent-operation-plane-routing.md — ADR recording the contract-first decision
• docs/integration/workspace-operation-plane.md — step-by-step integration guide
• Makefile — validate-agent-operation-contract target wired into make validate

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/graphql
  • Triggering command: /usr/bin/gh gh pr view --json url --jq .url ndor/bin/git (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)