docs: add public boundary and evidence examples

[sambegui]

Summary

Adds the public-boundary, declassification, and evidence-model documentation for BoundaryKit (the
public reference architecture, formerly agent-vm), plus a self-contained set of clearly-fake
reference-cell policy/evidence examples and a local public-safety scan script.

This packet documents how governed, untrusted agent-workload cells are reasoned about and what stays
public vs. private. All examples are newly written, illustrative, and marked example_only. Nothing
here describes, copies, or validates any private deployment.

Files changed (10 files, +530)

Docs

• docs/public-private-boundary.md — what is public reference material vs. private operational truth; trust/promotion boundaries; release rule.
• docs/declassification-checklist.md — content + governance checklist to run before publishing.
• docs/evidence-model.md — generic evidence receipt fields and per-gate evidence requirements ("evidence over assertion").

Fake reference-cell examples (all example_only)

• examples/reference-cell/policies/demo-tool-policy.yaml — fake allowlisted tools, fake schema hashes, denied-tools-absent, fail-closed flags.
• examples/reference-cell/policies/demo-egress-policy.yaml — default-deny egress, fake .invalid endpoints, audit-on-deny.
• examples/reference-cell/policies/demo-secret-refs.yaml — secret://demo/... references only, no values.
• examples/reference-cell/evidence/demo-build-sign-receipt.md — fake digest/SBOM/signature receipt shape.
• examples/reference-cell/evidence/demo-rollback-receipt.md — fake rollback target + drill receipt.

Tooling

• scripts/public-safety-scan — local Python scanner for common public-boundary mistakes (secret patterns, absolute home paths, key blocks, broad mounts, non-placeholder image refs, missing example_only markers). No external service dependency; exits non-zero on findings.

README

• README.md — links the three new docs and lists examples/reference-cell/ + scripts/public-safety-scan in the layout table.

Validation commands and exact results

Run against this branch (base origin/main = 12bd3c98db92bfa849b4aa85f50187867c3c71b3):

$ git diff --check origin/main...HEAD
OK: no whitespace/conflict-marker errors

$ python3 scripts/public-safety-scan $(git diff --name-only origin/main...HEAD)
public-safety-scan: PASS (9 text files scanned)        # scan script self-excludes

$ python3 -m py_compile scripts/public-safety-scan
OK: compiles

$ bash platform/tests/docs-public-contract-test
public docs contract tests passed                       # incl. verbatim-private-copy hash tripwire over docs/

$ private/disallowed-string scan over changed files
CLEAN: no private/disallowed terms found in changed files

Public-safety / declassification verdict

PASS — public-safe. Examples are obviously fictional and example_only; fake domains use
.invalid / reserved .example; digests are all-pattern (0000…, 1111…, aaaa…); secrets are
secret://demo/... references only. No private hostnames, IPs, registry paths, source paths, service
units, real digests/SBOMs/receipts, task ledgers, transcripts, or credentials appear. Docs frame
BoundaryKit strictly as public reference architecture/methodology and explicitly do not claim that any
private system was validated.

Non-goals (explicitly out of scope)

• No private runtime changes.
• No NUC / operator-host ops.
• No GHCR or any registry publication.
• No deploy, service restart, traffic shift, DNS/tunnel/sysctl change.
• No real private artifact data (no real digest, SBOM, signing output, logs, or evidence).
• This PR is not to be merged as part of this task.

🤖 Generated with Claude Code