docs: add public repo front door and missing execution contracts

[mdheller]

Summary

This PR captures the still-missing public-surface delta on top of the current main branch.

It does not try to replay the older hardening pack. Instead it preserves the newer work already on main:

• examples/receipts/
• docs/runtime-governance/control-matrix-integration.md
• lifecycle schemas for promotion / reversal / session artifacts
• the current bundle / run / replay evidence pipeline

What this adds

1. root README.md so the repo no longer presents as a file tree plus About text
2. docs/replay-boundary.md to make the current ReplayArtifact contract explicit
3. schemas/validation-artifact.schema.v0.1.json
4. schemas/placement-decision.schema.v0.1.json

Why

Publicly, agentplane is currently strongest as workflow orchestration / execution control:

• bundle -> validate -> place -> run -> evidence -> replay
• evidence-producing runtime surface
• lifecycle artifacts already present on main

But two concepts already present in scripts/docs were not yet first-class public schema files on main:

• ValidationArtifact
• PlacementDecision

And the repo still lacked a root reader path plus a concise replay-boundary note.

Deliberately not included

This PR does not yet resolve the naming seam between PlacementDecision and placement-receipt.json.
That should be a follow-up cleanup once we decide whether one becomes canonical and the other derived.

Files changed

• README.md
• docs/replay-boundary.md
• schemas/validation-artifact.schema.v0.1.json
• schemas/placement-decision.schema.v0.1.json

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: be7306bb1d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Align required ValidationArtifact fields with emitter output

The new schema requires capturedAt, valid, and checks, but scripts/validate_bundle.py currently writes validatedAt and result and does not emit a checks array (see the report object in that script). This means the validation artifact produced by the existing workflow cannot satisfy the published contract, so any schema-based validation step will fail for every run.

Useful? React with 👍 / 👎.

[mdheller]

Re-checked against current main and this still looks like the right minimal public-surface delta.

Confirmed main already contains the newer work we wanted to preserve rather than duplicate:

• examples/receipts/
• docs/runtime-governance/control-matrix-integration.md
• lifecycle schemas for promotion / reversal / session artifacts
• the current bundle / run / replay evidence path

So this PR remains the correct rebased scope:

• root README.md
• docs/replay-boundary.md
• schemas/validation-artifact.schema.v0.1.json
• schemas/placement-decision.schema.v0.1.json

Two useful follow-ons still remain after merge:

1. reconcile PlacementDecision vs placement-receipt.json naming
2. check in real emitted example artifacts if we want the repo itself to serve as the public proof pack for landscape positioning

External positioning remains strongest as workflow orchestration / execution control, not agent gatewaying, based on the current public surface.