O11 Report 06 — Patch-as-information-unit contract (BRANCH 5)

• macro: v0.6-o11-automation-agent-sandbox-program-bundle
• date_utc: 2026-05-21 · host: Contabo vmi3080463 · gate: BRANCH 5
• result: PASS — metadata contract defined; mirrored to iu-cutter-agent-sandbox/PATCH-CONTRACT.md

1. Principle

A patch produced by an external agent is an information unit: a self-describing, traceable, reviewable record of a proposed change. It is not a change. It carries enough metadata that a reviewer/promotion gate can judge it without trusting the agent that wrote it.

Every proposal is a pair:

patches/<patch_id>.patch.diff        unified diff (git format-patch / diff -u)
patches/<patch_id>.patch.meta.yaml   the metadata record below — REQUIRED

A diff without a conforming .patch.meta.yaml is rejected unread.

2. Metadata contract (*.patch.meta.yaml)

Field	Type	Meaning
patch_id	string	Unique, kebab-case. e.g. o11-deepseek-fix-cutplan-001.
author_agent	string	Model + role. e.g. deepseek-coder-v2 / drafter.
trust_level	enum	untrusted | community | reviewed | promoted. External agents emit at most untrusted.
source_gap	string	KB id / gap name the patch addresses. e.g. kb:4400, GAP-X.
affected_files	list[str]	Repo-relative paths the diff touches. Must contain zero DENY-path entries.
base_commit	string	Full 40-char commit the diff applies onto. Must be a real commit.
tests_added	list[str]	Test files / test names added by this patch. Non-empty for any non-doc change.
commands_run	list[str]	Exact commands the agent ran in the sandbox + their result.
risk_notes	string	What could go wrong; blast radius; data-touching?; idempotent?
review_status	enum	pending | gemini_ok | gemini_changes | codex_ok | codex_changes.
promotion_status	enum	sandbox | proposed | promoted | rejected.
rollback_notes	string	How to undo if promoted (revert commit / inverse diff / N/A).
created_utc	string	ISO-8601 UTC.

3. Field rules

trust_level:        external/open-source agents may only emit "untrusted".
                    "reviewed" set by a human/Claude reviewer; "promoted" set
                    ONLY by the promotion gate.
base_commit:        MUST exist in the real repo. The promotion gate re-derives
                    the diff from this base; a fabricated base => reject.
affected_files:     MUST NOT include /opt/incomex/dot/iu-cutter-v0.6,
                    /opt/incomex/dot/iu-cutter, /var/lib/cutter, or any secret
                    file. Any DENY-path entry => reject on sight.
tests_added:        empty is allowed ONLY for a docs-only patch.
commands_run:       every command must have been runnable inside the sandbox
                    with no production access. A command claiming production
                    access is a contract violation.
promotion_status:   only the Claude promotion gate writes "promoted"/"rejected".

4. Lifecycle

sandbox  --agent emits diff+meta+tests+report-->  proposed
proposed --Gemini-->  review_status: gemini_ok | gemini_changes
proposed --Codex -->  review_status: codex_ok  | codex_changes
proposed --Claude promotion gate, all checks pass-->  promoted
         --any check fails-->                          rejected

Admission checks at the promotion gate (all must hold): base_commit valid · affected_files DENY-free · tests_added non-empty & real · review_status is gemini_ok AND codex_ok · risk_notes and rollback_notes concrete · metadata conforms to this contract.

5. Why this makes external agents safe to use

- the unit of exchange is INFORMATION (a described diff), never an applied change
- the diff is bound to a named base_commit — re-derivable, not trusted blind
- affected_files is checkable mechanically against the DENY list
- promotion is a human re-creation on a real branch, not an in-place apply
=> a wrong/hostile agent's worst outcome is a rejected patch.

6. Verdict

contract:    11-field metadata record, enum-typed, mechanically checkable
mirrored:    /opt/incomex/dot/iu-cutter-agent-sandbox/PATCH-CONTRACT.md
branch_5:    PASS