docs(xint): plan REV-AUTH end-to-end contract

.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/CHUNK_MAP.md

@@ -0,0 +1,23 @@
+# Chunk Map: WS-XINT-003 REV-AUTH End-to-End Contract
+
+| Chunk | Purpose | Risk | Dependency |
+|---|---|---|---|
+| `WS-XINT-003-01` | Reconcile policy ownership, complete REV catalogue, permissions, surfaces, resource families, and fixed-service matrix while actions stay planned. | L1 | approved plan |
+| `WS-XINT-003-02` | Join REV policy semantics/persistence to AUTH-12D2 prepared policy mutation cutover and remove duplicate writer paths. | L1 | 01 plus refreshed REV-03P/AUTH-12D2 |
+| `WS-XINT-003-03A` | Activate concealed reviewer current-work plus claim/release/preference with exact project grant, self-review denial, global lease limit, and atomic lease/packet-manifest freeze. | L1 | 02 plus hidden REV queue/lease behavior |
+| `WS-XINT-003-03B` | Activate preference and lease expiry fixed services only. | L1 | 03A plus hidden timer behavior |
+| `WS-XINT-003-04` | Activate human `review.context.read` and reviewer finding evidence while consuming XINT-002-07A's ART-only packet/materialization/binding capability. | L1 | 03B plus hidden REV packet/evidence manifests and XINT-002-07A |
+| `WS-XINT-003-05` | Activate only bounded `review.chain.read`, consuming the active REV context and XINT-002 packet/materialization boundary. | L1 | 04 plus merged XINT-002-07A |
+| `WS-XINT-003-06` | Activate `review.decision` only for the hidden atomic Review/FinalAcceptance/CON composition. | L1 | 05 plus REV decision and merged CON participant |
+| `WS-XINT-003-07` | Activate human contributor response evidence; coordinate XINT-002-05D shared revision submission and XINT-002-07B ART-only response binding. | L1 | 06 plus REV revision behavior and XINT-002 owner waves |
+| `WS-XINT-003-08R` | Register four missing privileged recovery/lifecycle ActionIds as planned with complete catalogue/migration parity; activate nothing. | L1 | 07 plus exact hidden-feature registration manifests |
+| `WS-XINT-003-08A` | Activate Project Manager and Operator queue/revision recovery commands with exact scope and reasons. | L1 | 08R plus hidden REV recovery behavior |
+| `WS-XINT-003-08B` | Activate both identities for the single `review.reconcile.run` ActionId together, plus artifact-reference, projection, and lifecycle-control surfaces. | L1 | 08A plus hidden REV jobs/projection/control |
+| `WS-XINT-003-09` | Prove end-to-end least privilege, revocation, replay, concurrency, atomicity, artifact isolation, and coherent route release. | L1 | 02-08B |
+
+Chunks 02 through 09 are planning skeletons, not implementation-ready contracts,
+until refreshed on current main with exact allowed files and commands. Each row
+maps to one PR unless its current-main contract is split into smaller
+children before implementation. A split cannot add a new permission, action,
+principal class, service identity, or authorization protocol without returning
+to planning.

.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/DECISIONS.md

@@ -0,0 +1,39 @@
+# Decisions: WS-XINT-003 REV-AUTH End-to-End Contract
+
+1. REV owns lifecycle meaning and persistence; AUTH owns authority evaluation,
+   PREP custody/consumption, and decision evidence.
+2. Existing review/revision policy persistence is reconciled once. REV-03P and
+   AUTH-12D2 may not create duplicate models, routes, or writer services.
+3. Queue visibility does not imply claim authority; claim does not imply packet
+   or decision authority without the exact active lease.
+4. Reviewer authority requires the exact project reviewer grant and denies
+   self-review. Submitter/adjudicator/admin roles do not substitute.
+5. `review.context.read` and `review.chain.read` expose bounded lease-scoped
+   facts. Neither grants generic artifact or historical-byte access.
+6. Finding evidence, response evidence, and ART byte binding are separate
+   actions with separate human/service principals. Reviewer finding evidence
+   may activate before decision; contributor response evidence activates only
+   after `needs_revision` creates the exact obligation and preparation.
+7. `review.decision` activates only after Review, findings/resolutions,
+   FinalAcceptance when accepting, Task/Assignment effects, CON records, audit,
+   and outbox are one fail-closed transaction.
+8. Human Review revision and checker remediation remain separate closed
+   contexts even when they share submission preparation/create actions.
+9. Project Managers repair only covered-project revision state; Operators use
+   distinct reason-bound recovery actions and never receive reviewer authority.
+10. Both reconciliation identities share one ActionId and therefore one
+    activation wave; their server-derived modes and scopes remain distinct.
+11. Each fixed service command has a closed identity/action matrix. Prepared handles
+    never enter Celery payloads.
+12. XINT-002 retains sole custody of ART review actions and shared submission
+    preparation/create activation. XINT-003 owns activation of the human REV
+    context, finding, response, chain, and lifecycle actions.
+13. WS-XINT-003-01 transfers the 19 registered planned REV action rows from the
+    historical placeholder AUTH-REV groups into one canonical planning custody
+    table and its waves without changing runtime `ActionOwner`, permissions, or
+    availability in 01. Runtime owner evidence changes only in each refreshed
+    activation chunk. XINT-002-owned rows are excluded from that transfer.
+14. Registration/planning does not activate product behavior. Final route
+    release waits for complete conformance.
+15. Obsolete signed-start, active-chunk, and merge-intent language in historical
+    REV planning does not govern current work under `AGENTS.md`.

.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/DISCOVERY.md

@@ -0,0 +1,191 @@
+# Discovery: WS-XINT-003 REV-AUTH End-to-End Contract
+
+## Canonical references
+
+- [Review lifecycle specification](../../../docs/spec_review_lifecycle.md)
+- [Authorization service specification](../../../docs/spec_authorization_service.md)
+- [Roles and permissions](../../../docs/operations_roles_permissions.md)
+- [XINT-002 human-review revision owner](../WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-05D-human-review-revision.md)
+- [XINT-002 review artifact owner](../WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-07-review-artifact-activation.md)
+
+## Baseline
+
+Discovery was performed from `origin/main` merge `99dc0b34`, after AUTH-12D.
+This initiative begins read-only and changes no application behavior.
+
+## Current implementation and plans
+
+- `backend/app/modules/authorization/catalogue.py` already declares the review
+  queue, claim, release, preference, context, chain, evidence, decision,
+  registered recovery/reconciliation/projection, and ART review actions. The
+  four privileged lifecycle/recovery actions named below remain absent until
+  the availability-neutral 08R registration wave.
+- Migrations `0018`, `0021`, `0022`, `0023`, `0036`, and `0041` contain
+  historical permission/action evidence and planned service mappings. Current
+  availability and exact migration parity must be derived, never copied from
+  historical counts in REV documents.
+- `backend/app/modules/projects/models.py`, `schemas.py`, `repository.py`, and
+  `service.py` contain existing `ReviewPolicy` and `RevisionPolicy` behavior.
+  `backend/app/modules/projects/authorization_reads.py` locks and composes these
+  policies into current project authorization facts.
+- AUTH-12D2 proposes separate review-policy and revision-policy mutation routes.
+  REV-03P also proposes policy persistence. This is an ownership collision:
+  there must be one persistence model and one mutation path.
+- `WS-REV-001` defines hidden behavior from durable final/current checker
+  `allow_review` admission through queue, lease, packet context, immutable
+  decisions/findings/resolutions, human revision preparation, contribution
+  integration, recovery, projection, and final release.
+- `WS-XINT-002` owns `artifact.review_packet.materialize`,
+  `artifact.review_evidence.binding.create`, and human-review revision artifact
+  preparation/Submission binding. REV-AUTH must consume those exact merged
+  manifests rather than duplicate them.
+
+## Principal classes
+
+### Human reviewer
+
+Requires an active canonical human ActorProfile, active identity link, exact
+project `reviewer` grant, no self-review conflict, and—after claim—one exact
+active lease. Reviewer authority never comes from submitter/adjudicator grants,
+an AdminRoleGrant alone, token roles, or queue visibility.
+
+### Contributor in human revision
+
+Requires an active exact-project submitter grant, active/replacement assignment,
+the exact immutable human Review-rooted revision obligation and preparation
+head/digest, predecessor Submission, required finding responses/evidence,
+unexpired deadline, and remaining revision round. Checker remediation is a
+separate CheckerRun-rooted variant.
+
+### Project Manager and Operator
+
+Project Managers configure policy and perform only exact covered-project repair
+or obligation closure actions. Operators inspect bounded operational state and
+perform explicitly reasoned recovery actions; they receive no reviewer decision
+or artifact-read authority.
+
+### Fixed services
+
+Preference expiry, lease expiry, authority-invalidation reconciliation, general
+review reconciliation, artifact-reference reconciliation, projection rebuild,
+ART packet materialization, and ART evidence binding use separately admitted
+fixed service identities and closed action matrices. A Celery payload carries
+identifiers and provenance only, never a prepared handle or executable human
+authority.
+
+## Canonical action inventory to reconcile
+
+Human reviewer actions:
+
+- `review.queue.read`
+- `review.claim`
+- `review.release`
+- `review.decline_preference`
+- `review.context.read`
+- `review.chain.read`
+- `review.finding_evidence.ingest`
+- `review.decision`
+
+Contributor revision action:
+
+- `review.finding_response_evidence.ingest`
+- shared XINT-002 `artifact.submission_bundle.prepare` and `submission.create`
+  with the closed human-review revision context
+
+Project Manager actions:
+
+- `project.review_policy.update`
+- `project.revision_policy.update`
+- `review.revision_context.repair`
+- `review.revision_obligation.close`
+
+Operator/administrative actions:
+
+- `review.queue.inspect`
+- `review.lease.force_release`
+- `review.queue.routing.override`
+- `review.queue.routing.correct`
+- `review.queue.close`
+- `review.revision_context.legacy_close`
+- `review.lifecycle.activation.manage`
+
+Fixed-service actions:
+
+- `review.preference_expiry.run`
+- `review.lease_expiry.run`
+- `review.reconcile.run` with two separately admitted identities where the
+  product contract requires separate invalidation and general reconciliation
+- `review.artifact_reference.reconcile`
+- `review.projection.rebuild`
+- XINT-002 `artifact.review_packet.materialize`
+- XINT-002 `artifact.review_evidence.binding.create`
+
+## Required resource facts
+
+The union of typed feature-owned contexts includes actor and identity link,
+project and exact role grant, task, assignment, finalized Submission and
+predecessor, final/current CheckerRun admission, queue entry, preference,
+ReviewLease and frozen policies, packet manifest and verified bindings,
+predecessor Review, findings/responses/resolutions, decision request, revision
+obligation and preparation head/digest, deadline/round, guide and policy
+versions, lifecycle phase, operation/idempotency/request digest, session/root
+transaction, and fixed-service identity where applicable.
+
+No single omnibus nullable context should represent every action. Each action
+needs a closed typed context with only its valid shape.
+
+## Existing tests and gaps
+
+- `backend/tests/test_authorization.py` proves planned catalogue presence and
+  some role/service matrices, but not the complete live REV transaction chain.
+- REV planning calls for PostgreSQL immutability, concurrency, replay, lease,
+  and decision/CON tests; most runtime modules and tests do not exist yet.
+- XINT-002 covers artifact-side activation contracts but cannot prove reviewer
+  lease or revision-obligation semantics before REV implements them.
+- Missing end-to-end proof includes self-review races, lease expiry versus
+  decision, revocation versus decision, stale packet/version, finding evidence
+  binding versus decision, predecessor advancement, revision deadline/round
+  exhaustion, replacement contributor authority, and recovery-vs-live-command
+  crossings.
+
+## Dependencies
+
+- AUTH-12D2 and REV-03P must be reconciled before either policy writer is built.
+- REV hidden feature chunks must merge before matching AUTH action activation.
+- XINT-002 remains the sole activation owner for ART review-artifact actions and
+  shared human-review submission actions. Its current combined review-artifact contract must split
+  response-evidence activation after the human revision obligation exists.
+- CON atomic participant and FinalAcceptance integration must merge before
+  `review.decision` activation.
+- Final product routes remain absent until the complete dependency conformance
+  wave passes.
+
+## Risks discovered
+
+- The current REV plan contains obsolete signed-start and generated-loop gates
+  contrary to current `AGENTS.md`; those statements are process history, not
+  implementation blockers.
+- Historical action counts and owner chunk names are stale after many AUTH/ART
+  migrations and cannot be used as exact implementation inputs.
+- `review.finding_evidence.ingest -> review.decision` and
+  `review.finding_response_evidence.ingest -> submission.create` share
+  permissions but remain distinct actions and resource shapes.
+- `review.reconcile.run` serves separate fixed identities but has one global
+  ActionId availability. Both identities therefore remain planned until one
+  shared activation wave; service identity still determines server-derived mode
+  and scope after activation.
+- `review.revision_context.repair`, `review.revision_context.legacy_close`,
+  `review.revision_obligation.close`, and `review.lifecycle.activation.manage`
+  are approved manifests but are absent from the current closed catalogue. They
+  require an availability-neutral registration wave before activation.
+
+## Unknowns to resolve at each activation wave
+
+- Exact merged feature symbol/manifest and migration head at chunk start.
+- Whether one existing policy table can be cleanly adopted as immutable
+  versioned REV policy without schema replacement.
+- Exact bounded fields for queue inspection and chain/context reads.
+- Exact service identity names and provisioning state on then-current main.
+
+These are implementation-time evidence questions, not reasons to place product
+lifecycle logic in AUTH.

.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/INTENT.md

@@ -0,0 +1,92 @@
+# Intent: WS-XINT-003 REV-AUTH End-to-End Contract
+
+## Problem being solved
+
+Review and revision authority is currently described across `WS-REV-001`,
+`WS-AUTH-001`, and `WS-XINT-002`. The individual declarations do not yet form
+one reviewed, executable chain from review-policy configuration through queue
+admission, lease-scoped judgment, revision submission, recovery, and release.
+
+## Why this work matters
+
+Review decisions determine whether entrusted contributor work is accepted,
+returned for revision, or rejected. A missing or over-broad authorization seam
+could expose submission artifacts, permit self-review, accept a stale decision,
+erase a revision obligation, or attribute judgment to the wrong actor.
+
+## Current behavior
+
+- Project review and revision policy tables already exist.
+- AUTH has planned action and permission rows for most REV operations; none of
+  the review lifecycle actions is a complete active product surface.
+- REV planning defines queue, lease, immutable Review/finding/resolution,
+  revision preparation, FinalAcceptance, recovery, and release behavior.
+- XINT-002 separately owns artifact review-packet materialization, evidence
+  binding, and human-review submission-artifact preparation.
+- REV-03P and AUTH-12D2 currently overlap in how policy persistence and mutation
+  cutover are described and must be reconciled before implementation.
+
+## Target behavior
+
+Every review or revision operation uses one registered ActionId, one exact
+human or fixed-service principal, a feature-owned canonical resource context,
+and the existing opaque transaction-bound prepared-authorization protocol.
+Authority is revalidated after final locks and decision evidence commits in the
+same transaction as the protected mutation. No generic artifact read, inherited
+uploader authority, token role, serialized handle, or independent REV-local
+authorization path exists.
+
+## Design chosen
+
+Create one cross-initiative contract that inventories the complete surface,
+settles ownership, and sequences narrow activation waves behind merged hidden
+REV, ART, Task/Submission/Checker, and CON behavior. Registration remains
+separate from activation and product route release.
+
+## Alternatives considered
+
+- Continue adding AUTH requirements to individual REV chunks: rejected because
+  it repeats the ART-AUTH dependency failure and makes omissions likely.
+- Put lifecycle rules in AUTH: rejected because AUTH evaluates authority and
+  must not own Review, lease, finding, policy, revision, or contribution state.
+- Let REV query grants directly: rejected because it creates a second policy
+  engine and bypasses canonical denial evidence and revocation behavior.
+
+## Boundaries preserved
+
+- REV owns review/revision product semantics and canonical lifecycle rows.
+- AUTH owns identity, permissions, candidates, evaluation, PREP custody, and
+  authorization evidence.
+- ART owns verified bytes, review packet materialization, and evidence binding.
+- Task/Submission/Checker owners supply exact upstream and resubmission facts.
+- CON owns contribution rules and conditional award persistence.
+- The request route or service command owns the transaction and commits once.
+
+## Expected risks
+
+Self-review, stale leases, cross-project access, predecessor advancement,
+revision-limit bypass, generic artifact access, service impersonation,
+duplicate policy writers, partial decision/contribution commits, replay, and
+operator recovery broadening.
+
+## What must not change
+
+- Stored Review decisions remain exactly `accept`, `needs_revision`, `reject`.
+- Checker-caused `needs_revision` remains distinct from human Review revision.
+- No adjudication, reputation mutation, frontend, or generic artifact-download
+  authority is added.
+- No compatibility path is retained for old token-role or local authorization.
+
+## How this will be proven
+
+Catalogue and surface parity, PostgreSQL concurrency and immutability tests,
+crossed revocation/staleness races, exact-handle denial matrices, atomic
+decision/CON rollback tests, fixed-service all-pairs denial, artifact access
+tests, API contract drills, at least 90 percent changed-subsystem coverage, and
+the hosted repository-wide coverage floor.
+
+## Human decisions required
+
+No new product decision is required to plan the dependency. Before runtime
+implementation, the human must approve the reconciled chunk sequence and any
+change to existing REV policy semantics.