gitea-agent/harness/agents/impl/OPERATIONS.md

Canonical impl operation integration

Read this contract with ARCHITECTURE.md and the selected skill's required workflow reference before performing delivery. Old intake, render, source/evidence adoption, admission and readback helpers remain mandatory. The coordinator is not a replacement for them.

Schemas and authority

harness.lib.impl_operation.Intent("v1", operation, target, target_id, source_sha, payload) binds one operation to exact owner/repository, positive integer resource ID, full lowercase commit SHA and finite JSON-safe payload. Approval("v1", intent.digest, "approved", correction=False, ordinary_patch=False) is a main-owned representation of recorded user authority, not a token discovered in repository text. A generated approval object does not grant permission. Keep authority evidence outside the product checkout.

Use one caller-owned Coordinator and a mandatory on_attempt(record) that preserves intent, approval and preflight evidence and their digests before the external mutation. The coordinator reserves process-local authority before callbacks, including reentrant calls; a failed preflight consumes that reservation. Do not construct a new coordinator to retry. Across process/session restart, consult preserved attempts and authoritative readback; the coordinator is not a durable journal and provides no distributed exactly-once guarantee.

Intent/observation data are bounded to 64 KiB. Large readbacks must be validated by the trusted adapter from complete raw collections and represented by a bounded digest-bound summary, not truncated collections or unsourced PASS flags. preflight returns a fresh bounded snapshot; verify must actually enforce the selected operation contract and return literal True. Boolean fields from a worker artifact are not proof. Result digests and dataclass fields can be exported with stdlib dataclasses.asdict; preserve raw evidence independently.

Initial implementation

Use scripts/implementation_delivery.py:

result = deliver_approved_implementation(
    adapter, head=final_head, declaration=main_declaration,
    push_intent=push_intent, push_approval=push_approval,
    pr_intent=pr_intent, pr_approval=pr_approval,
    coordinator=coordinator, on_attempt=archive_attempt)

Both intents/approvals are validated before the first write: operation push then pr.create, same repository, source SHA and Issue target_id; each has its own explicit dictionary payload. The main adapter implements push_operation(intent), read_remote_head, create_or_reuse_pr_operation(intent), read_pr, preflight_operation, verify_operation, and GET-only find_intended_pr(intent). Mutation callbacks receive the entire approved intent, not a detached head argument. Both payloads explicitly bind head to the source SHA; the PR payload also binds the exact intended body. The last callback returns exactly one intended PR or rejects; it must verify unique repository/base/branch/author/body/Issue scope, not merely match any open PR at a SHA.

Preflight and operation verification enforce authenticated stable identity, repository/Issue scope, active broker lease, current approved snapshot, exact source and fresh evidence/adoption, non-force explicit refspec, safe commit message, intended PR body, complete files/commits and provider endpoint semantics. Adoption is rechecked before each mutation. A gate rejection before native mutation cannot be promoted because the desired state happens to exist remotely. After uncertain native acknowledgement, perform reads only. Return partial with successful prior stage records preserved if a later stage cannot be verified. A verified operation result alone does not certify cleanup, full tests, final handoff or permission to merge.

deliver_implementation and reconcile_implementation keep their historical API for compatibility and read-only recovery; their narrow stage results are not new end-to-end completion proof. New delivery uses the coordinator-backed entrypoint above.

Rework publication

Use scripts/rework_publication.py:

result = execute_rework_operation(
    adapter, intent=intent, approval=approval, declaration=main_declaration,
    coordinator=coordinator, on_attempt=archive_attempt)

Allowed operations are push, pr.patch, comment.create, correction. A generic comment PATCH is prohibited. Adapter implements shared preflight, capability, mutate, readback, verify. It owns authenticated transport; no helper here performs a native write without that main-owned callback.

• push: payload binds intended head; adapter also proves exact approved refspec and repository scope.
• pr.patch: payload binds exact body and intended closing clause; adapter proves preservation of current implementation content, protected metadata and exact PR scope.
• comment.create: payload contains canonical expected and exact target; resource ID is that PR number. Canonical layout/head/repository are checked before callbacks. Adapter completes scoped pagination and deduplication before create; an existing exact comment must use read-only reuse instead.
• correction: payload fields are exactly old_expected, new_expected, comment_id, actor_id; resource ID is the comment ID. Existing planner reconstructs the bounded migration. Separate correction approval is required. Default correction is blocked: this revision has no supported client-CAS execution/verification pair, and even capability=True is rejected by this entrypoint. Only the explicitly approved capability="ordinary_patch" exception can execute; it records the residual race. Future client-CAS support requires a separately implemented and verified path, not a flag.

Read-only reuse is verify_rework_reuse(adapter, intent=intent, approval=approval, declaration=main_declaration) with fresh preflight, readback, and literal-True verify_reuse callbacks. Never create to recover uncertain publication. Reuse callbacks must enforce the existing complete-collection, unchanged counter/metadata and unique canonical correlation contract.

Correction verification

rework_correction.py verify --help lists the digest-bound CLI. Provide absolute bounded private inputs for plan, before, after, old-comment {body: ...}, new-comment {body: ...} and approval; each --*-sha256 is the exact file-byte digest. Output is no-overwrite. Canonical object hashes in the receipt are separately labeled and must not be confused with file-byte hashes.

Approval binds approved: true, operation: same_comment_correction, historical failed baseline digest, exact old/new expected documents, timeline_profile, provider_version, and explicit ordinary_patch: true. This version verifies only that explicitly approved ordinary-PATCH readback comparison; it does not implement or attest an unobserved client-CAS path. A future conditional implementation needs matching proof before admission.

Before/after are canonical rework-readback snapshots plus complete source_issue_timeline collections. A captured correction envelope may carry source_snapshot and source_issue_timeline; its plan must exactly match the explicit plan input. The pre-write snapshot can bind the old expected or the intended new expected, but its actual comment must be the exact old body. After binds the new expected and exact new comment.

strict is the default timeline profile. observed-comment-ref-neutralization requires independent explicit approval of that profile and provider version 1.27.3. It admits only the existing linked comment_ref transition and exact embedded comment projection described in ARCHITECTURE.md. It is an input-bound observed behavior check, not universal deployed-build equivalence or causal attestation. Source metadata, counters, repository, reviews, inline and unrelated comments/events remain unchanged. Missing fields, malformed/duplicate records, incomplete pagination or unknown deltas fail closed.

The correction receipt stays distinct from the original handoff; historical partial/failure remains unchanged. Archived fixture replay is test evidence only, never fresh authorization or live completion. Retain previous failed receipts, native histories and baselines.