[verified] Add ordered initial rework review input gate

2026-10-12 04:54:43 +00:00
parent aeab04289d
commit b270c2ce30
8 changed files with 722 additions and 7 deletions
@@ -0,0 +1,41 @@
+# Ordered initial review input gate
+
+## Canonical invocation and artifacts
+
+Run the public entry point before choosing no-op or editing source:
+
+```sh
+python3 -B harness/agents/impl/skills/gitea-issue-rework/scripts/rework_comment.py input-gate \
+  --target <rework-input.json> --target-sha256 <exact-file-sha256> \
+  --provider-contract <provider-contract.json> \
+  --provider-contract-sha256 <exact-file-sha256> --actor-id <impl-stable-id> \
+  --output <admitted-verification-run>/decision.json
+```
+
+The canonical output is `<harness-root>/repositories/<owner>/<repository>/worktrees/issue-<issue>/verification/<run-id>/decision.json`. First prepare/admit this run root using the existing `verification_root.py prepare` procedure in `harness/operations/repository-cache.md`. The caller derives exact identity/path from authenticated workflow state. The CLI checks private descriptor-relative filesystem safety; it does **not** authenticate a broker lease or canonical verification-root identity. Do not infer authority from an arbitrary `--output` path.
+
+Use a fresh run and receipt after source/head/decision inputs change. Existing outputs are refused before credential loading or GETs; atomic no-clobber publication also preserves a file created concurrently. There is no update-in-place mode for this immutable artifact. The entire serialized receipt, including raw snapshot, is bounded to 1,000,000 bytes and fails closed rather than truncating. Legacy completion output size/replacement behavior is unchanged.
+
+## Independent input
+
+The target file is exactly schema `gitea-agent.rework-input/v1`:
+
+```json
+{"schema":"gitea-agent.rework-input/v1","target":{"owner":"acme","repository":"demo","issue":7,"pr":9},"head":"<40 lowercase hex>","contract_sha256":"<64 lowercase hex>"}
+```
+
+Use the independently verified current PR head and SHA-256 of the exact fresh Source Issue UTF-8 body. Names/positive integer IDs/digests/field sets are strict; Issue and PR differ. No selected review ID, final rework head, rendered comment, or `expected.json` is required. The schema and explicit provider contract are validated before credentials or network access.
+
+Two authenticated GET-only captures reuse identity-first native metadata, repository/PR/Issue/author binding, complete bounded pagination, Link provenance, per-review inline/count capability fallback and drift checks. The initial phase also requires the repository's native default branch to match PR base ref, the exact discovery-draft/v2 first line, and exact Source Issue digest. Discovery structural approval, unresolved-question checks and edit authorization are independent upstream requirements, not claims made by this gate.
+
+## Derived decisions
+
+The `gitea-agent.rework-input-gate/v1` receipt retains parsed native records, provider row order and body text in `raw_input_snapshot`, bound by `raw_input_sha256`; it is not a byte archive of HTTP serialization. A separate derived timeline records every review's ID, native author stable ID/login/role, state, submitted timestamp, reviewed SHA, stale/dismissed flags, canonical body marker, body digest and eligibility/exclusion reasons. Sorting does not mutate raw evidence.
+
+Order by UTC instant with exact up-to-nine-digit fractional precision, then numeric review ID for deterministic display ties. ID order is not causal attestation. Conflicting same-instant same-role state/body/marker records block and have no selected review. Markers use the actual canonical code FIRST-line and spec LAST-line formats; spec result digest and correlation match its renderer's separator-LF algorithm. Current authoritative marker/head/contract/state contradictions block. Role IDs must be positive, distinct from impl, and consistent; unrelated roles cannot supply required approvals. Old-head history is recorded but cannot determine current-head action.
+
+- `rework`: both roles have a current usable selection, and the only remaining decision reason is latest role-specific `REQUEST_CHANGES`. `decision.rework_review_ids` contains those request IDs only, never spec/code approvals. Validate their findings and authorization independently before source edits.
+- `no_op`: both spec and code-review role-specific latest current-head, nonstale, nondismissed reviews are `APPROVED` for the fresh contract. A spec approval cannot supersede a code request. Earlier same-role requests may be superseded by a later valid same-role approval, never by another role.
+- `blocked`: missing current roles, pending authoritative reviews, malformed/ambiguous bindings, same-instant conflicts, current manual `COMMENT`, or `blocked_spec` prevent automatic action. `blocked_spec` is explicit and routes to Discovery investigation, not impl repair. No keyword heuristic or marker alone proves actionable finding semantics.
+
+This gate's no-op means skip implementation rework, not native review publisher idempotent reuse (which can reuse an existing REQUEST_CHANGES review). Publication, journals and their candidate-selection rules remain unchanged. A receipt is neither publication success nor edit permission, lease/worktree admission, full Discovery approval, independent reviewer-ID attestation, or causal event proof. Do not reuse an old receipt as authority; recheck provider/head/contract and independent upstream gates before an action.