diff --git a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/CHUNK_MAP.md b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/CHUNK_MAP.md index b8b018daf..f7ae099ac 100644 --- a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/CHUNK_MAP.md +++ b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/CHUNK_MAP.md @@ -1,145 +1,77 @@ # Chunk Map: WS-REV-001 Review And Revision Lifecycle -REV-03P is reconciled into WS-XINT-003-02 and is not an independent policy -writer. AUTH activation follows the exact XINT-003 waves. - -REV owns every review/revision lifecycle row, rule, command, service job, projection, -fence, and route. AUTH owns catalogue, principals, PREP/evaluation/evidence and -availability. REV runtime work begins after XINT-003-02C/02D fail-closed -readiness and does not wait for action activation; XINT activation then waits -for the exact merged REV child. Only REV-13C releases product routes. - -## Rule - -One executable chunk maps to one PR. Merged parent IDs remain non-executable -split records. A proposed child is not executable until its own current-main -contract is authored, internally reviewed, explicitly started, and every owner -gate is proven by exact chunk ID, merged PR/SHA, migration head where relevant, -typed symbol/manifest, and tests. - -## Current sequence - -| Chunk | Title | Risk | Gate | Status | -|---|---|---:|---|---| -| `WS-REV-001-PLAN` | Review And Revision Lifecycle Planning | L1 | None | Merged PR #128 | -| `WS-REV-001-01` | Canonical Contract Adoption And Dependency Conformance | L1 | PLAN | Merged PR #145 | -| `WS-REV-001-02` | Locked Review Policy And Task Lifecycle Alignment | L1 | 01 | Merged PR #147; non-executable split record | -| `WS-REV-001-PLAN2` | REV-02A Runtime Readiness Plan Refresh | L1 | 02; planning-only human start | Merged PR #150 | -| `WS-REV-001-02A` | Guide Chronology And Task Locking Split | L1 | Historical | Superseded boundary-crossing plan; never executable by REV | -| `WS-REV-001-02A1` | Project And Setup Publication Fence | L1 | Historical | Retired from REV; upstream owner concern | -| `WS-REV-001-02A3` | Guide Activation Chronology | L1 | Historical | Retired from REV; upstream owner concern | -| `WS-REV-001-02A4` | Task Guide Triplet And Screening | L1 | Historical | Retired from REV; upstream owner concern | -| `WS-REV-001-02A2` | Prepared Superseded Guide Reactivation | L1 | Historical | Retired from REV; upstream owner concern | -| `WS-REV-001-02B` | Locked Review Policy And Dormant Task Lifecycle Compatibility | L1 | Historical | Superseded; any upstream gap is reported to its owner | -| `WS-REV-001-02C` | Submission Attribution, Context, And Immutable Lineage | L1 | Historical | Superseded as an ownership chunk; REV consumes owner-supplied Submission lineage | -| `WS-REV-001-PLAN3` | Allow-Review Boundary Reset | L1 | Historical | Merged boundary correction | -| `WS-REV-001-03P` | Review And Revision Policy Persistence | L1 | Reconciled into `WS-XINT-003-02` | Planning input only; never executable independently | -| `WS-REV-001-03` | Review Queue And Lease Persistence | L1 | PLAN3 | Non-executable split record | -| `WS-REV-001-03A` | Queue And Lease Base Persistence | L1 | merged `WS-XINT-003-02C/02D`; exact `allow_review`, Submission/artifact, and actor handoffs | Proposed contract; requires current-main refresh and explicit user request | -| `WS-REV-001-03B` | Normalized Review Packet Manifest Persistence | L1 | 03A; exact ART packet-membership owner chunk merged | Proposed; owner chunk unscheduled | -| `WS-REV-001-04` | Review Chain Persistence | L1 | 03B | Non-executable split record | -| `WS-REV-001-04A` | Immutable Review Chain And Decision Request Persistence | L1 | 03B; current actor constraints | Proposed; no contract yet | -| `WS-REV-001-04B` | Final Acceptance, Task Linkage, Audit, And Outbox Persistence | L1 | 04A; merged `WS-CON-001-02A` and `02C` | Proposed; no contract yet | -| `WS-REV-001-05` | Checker Routing And Queue Views | L1 | 04B | Non-executable split record | -| `WS-REV-001-05A` | Atomic Checker Admission Participant | L1 | 04B; merged ART 05/06A/06B exact admission facts | Proposed; no contract yet | -| `WS-REV-001-05B` | Server-Selected Reviewer And Admin Queue Reads | L1 | 05A; exact AUTH read contracts | Proposed; no contract yet | -| `WS-REV-001-06` | Claims, Preference, And Timers | L1 | 05B | Non-executable split record | -| `WS-REV-001-06A` | Atomic Claim, Lease, Packet, And Reviewer Policy Freeze | L1 | 05B; merged 03B persistence contract; merged `WS-CON-001-06`; AUTH PREP/custody/service contracts | Proposed; consumes 03B and owns no packet schema/migration | -| `WS-REV-001-06B` | Owned Release, Decline, And Preference Transitions | L1 | 06A; exact AUTH mutation contracts | Proposed; no contract yet | -| `WS-REV-001-06C` | Preference And Lease Expiry With Lazy Recovery | L1 | 06B; provisioned/admitted exact service identities | Proposed; no contract yet | -| `WS-REV-001-07` | Review Context And Finding Evidence | L1 | 06C | Non-executable split record | -| `WS-REV-001-07A` | Lease-Bounded Packet And Review Chain Context | L1 | 06C; exact ART packet-read owner chunk | Proposed; owner chunk unscheduled | -| `WS-REV-001-07B` | Reviewer Finding And Note Records | L1 | 07A; no artifact candidate/finalize port and no evidence-upload action | Proposed; v0.1 records only | -| `WS-REV-001-08` | Pure Decision, Final Acceptance, And Task-Effect Contract | L1 | 07B; typed participant contracts; v0.1 findings are records/notes, not uploaded evidence | Proposed; executable contract after repair, no canonical write | -| `WS-REV-001-09A` | Revision Context Preparation And Resubmission | L1 | 08 | Non-executable split record | -| `WS-REV-001-09A1` | Review-Rooted Revision Preparation Persistence | L1 | 08; exact owner-supplied guide/task facts; approved human round/deadline semantics; migration/head refresh | Proposed; no contract yet | -| `WS-REV-001-09A2` | Revision Preparation Participant, Resolver, And Task Context | L1 | 09A1 | Proposed; task-owned flush-only participant, no transaction composition | -| `WS-REV-001-09A3` | Human Revision Finding Response Records | L1 | 09A2; no artifact candidate/finalize port and no response-evidence action | Proposed; v0.1 text/metadata records only | -| `WS-REV-001-09A4` | Hidden Human Prepared N+1 And Checker Source Compatibility | L1 | 09A3; merged AUTH-14 contract amendment only; ART digest contract | Proposed; adds preparation binding/source XOR while consuming owner-supplied checker source; AUTH-14 owns public request acknowledgement, authorization cutover, and activation | -| `WS-REV-001-09A5` | Hidden Replacement Assignment Preparation Transfer | L1 | 09A4; merged AUTH-13 contract amendment only | Proposed; AUTH-13 later owns public command/cutover/activation | -| `WS-REV-001-09B` | Finding Replay, Resolution, And Preferred Return Routing | L1 | 09A5 | Proposed | -| `WS-REV-001-10` | Canonical Review, Final Acceptance, And CON Atomic Integration | L1 | 09B; merged `WS-CON-001-03C` and `07`; stabilized digest owner chunk | Proposed; first canonical decision commit | -| `WS-REV-001-11` | Administrative Recovery And Reconciliation | L1 | 10 | Non-executable split record | -| `WS-REV-001-11A` | Privileged Queue And Lease Commands | L1 | 10; exact AUTH command contracts | Proposed; no contract yet | -| `WS-REV-001-11B` | Revision Repair And Obligation Closure | L1 | 11A; registered additive actions | Proposed; no contract yet | -| `WS-REV-001-11C` | Reconciliation Persistence, Historical Admission Scan, And Service Jobs | L1 | 11B; exact service identities/admission | Proposed; owns batched resumable audited scan/classification | -| `WS-REV-001-11D` | Legacy Closure And ART Recovery Delegation | L1 | 11C; ART Operator recovery port | Proposed; no contract yet | -| `WS-REV-001-12` | Projection And Observability | L1 | 11D | Non-executable split record | -| `WS-REV-001-12P1` | Deterministic Review Projection Handler | L1 | 11D; merged CON outbox dispatcher/handler registry | Proposed; no contract yet | -| `WS-REV-001-12P2` | Artifact Reference Reconciliation And Projection Rebuild Jobs | L1 | 12P1; exact services/actions/ART projection port | Proposed; no contract yet | -| `WS-REV-001-12P3` | Notifications, Admin Reads, Metrics, And Drain Observation | L1 | 12P2 | Proposed; no contract yet | -| `WS-REV-001-12A` | Joint Lifecycle Release Control | L1 | 12P3 | Non-executable split record; preserves canonical parent ID | -| `WS-REV-001-12A1` | Lifecycle Controller Persistence And Typed Ports | L1 | 12P3; exact core CON readiness manifest | Proposed; no contract yet | -| `WS-REV-001-12A2` | REV, Task, And Checker Mutation Fence Composition | L1 | 12A1 | Proposed; no contract yet | -| `WS-REV-001-12A3` | CON Writer, Dispatcher, Callback, Cutoff, And Drain Fences | L1 | 12A2; CON 03D/08A/08B/10B/11 hooks | Proposed; no contract yet | -| `WS-REV-001-12A4` | Operator Transition, Drain, And Crash Recovery | L1 | 12A3; exact AUTH Operator contract | Proposed; no contract yet | -| `WS-REV-001-13` | Coherent Product Release And Proof | L1 | 12A4 | Non-executable split record | -| `WS-REV-001-13A` | Exact Dependency Preflight, Manifests, And Drill Harness | L1 | 12A4; every owner gate exact and merged | Proposed; no contract yet | -| `WS-REV-001-13B` | Pre-Release Documentation And Generated Artifact Preparation | L1 | 13A; hidden behavior proof | Proposed; no contract yet | -| `WS-REV-001-13C` | Product Router Registration And Final HTTP Proof | L1 | 13B; exact AUTH activations; ART 07; CON 11 | Proposed; sole product release | - -## Same-initiative order +## Live sequence + +Historical PLAN through PLAN3 and retired 02-family records remain evidence. +PLAN4 is the current-main end-to-end refresh after merged AUTH 02D. + +| Chunk | Purpose | Gate | Status | +|---|---|---|---| +| `WS-REV-001-PLAN4` | Current-main full lifecycle replan | AUTH 02D merged PR #257 | Proposed planning PR | +| `WS-REV-001-03A1` | Queue and admission-idempotency persistence | PLAN4 approved | First proposed runtime child | +| `WS-REV-001-03A2` | REV-owned lease and preference persistence | 03A1 + existing CON-03B ContributionPolicyVersion table solely as the required FK target | Skeleton | +| `WS-REV-001-03B` | Normalized packet-manifest persistence | 03A2 + ART-owned contract-only packet membership port published before ART-07A runtime | Skeleton | +| `WS-REV-001-04A` | Immutable Review/finding/resolution/decision-request persistence | 03B | Skeleton | +| `WS-REV-001-04B` | FinalAcceptance and shared audit/outbox linkage persistence | 04A + CON-02A outbox persistence + CON-02C audit participant | Skeleton; enables CON-03C schema work | +| `WS-REV-001-05A` | Atomic final `allow_review` admission | 04B + exact TASK/CHECKER/ART admission manifest after ART checker routing/XINT activation | Skeleton | +| `WS-REV-001-05B` | Concealed active-lease/one-offer/none query | 05A | Skeleton | +| `WS-REV-001-06A` | Atomic claim and REV-owned lease/packet freezes | 05B + 03B + CON-06 policy lookup result + exact ART packet proof | Skeleton | +| `WS-REV-001-06B` | Owned release and preferred decline | 06A | Skeleton | +| `WS-REV-001-06C` | Preference/lease expiry and lazy recovery | 06B + fixed service admission | Skeleton | +| `WS-REV-001-07A` | Lease-bounded packet/context/chain reads | 06C + ART 07A | Skeleton | +| `WS-REV-001-07B` | Immutable reviewer notes/findings | 07A | Skeleton; no evidence upload | +| `WS-REV-001-08` | Pure decision validator/effect plan | 07B | Skeleton; no canonical write | +| `WS-REV-001-09A1` | Review-rooted revision episode/preparation persistence | 08 + human round/deadline decision | Skeleton | +| `WS-REV-001-09A2` | TASK revision participant and context resolver | 09A1 | Skeleton | +| `WS-REV-001-09A3` | Contributor finding-response records | 09A2 | Skeleton; no evidence upload | +| `WS-REV-001-09A4` | Human prepared N+1 and checker-source XOR | 09A3 + TASK/ART submission cutover | Skeleton | +| `WS-REV-001-09A5` | Replacement-assignment preparation successor | 09A4 + AUTH replacement contract | Skeleton | +| `WS-REV-001-09B` | Finding replay/resolution/preferred return | 09A5 | Skeleton | +| `WS-REV-001-10` | Canonical Review/FinalAcceptance/TASK/CON transaction | 09B + CON-07 participant + shared audit/outbox | Skeleton; first Review commit | +| `WS-REV-001-11A` | Queue inspection and privileged queue/lease commands | 10 | Skeleton | +| `WS-REV-001-11B` | Revision repair and obligation close | 11A | Skeleton | +| `WS-REV-001-11C` | Reconciliation persistence and service jobs | 11B | Skeleton | +| `WS-REV-001-11D` | Legacy closure and ART recovery delegation | 11C + ART recovery port | Skeleton | +| `WS-REV-001-12P1` | Deterministic projection handler | 11D + shared dispatcher | Skeleton | +| `WS-REV-001-12P2` | Artifact-reference reconciliation/projection rebuild | 12P1 + ART typed repair port | Skeleton | +| `WS-REV-001-12P3` | Notifications, admin reads, metrics, drain facts | 12P2 | Skeleton | +| `WS-REV-001-12A1` | Lifecycle release-controller persistence | 12P3 + dependency manifest | Skeleton | +| `WS-REV-001-12A2` | REV/TASK/CHECKER mutation fences | 12A1 | Skeleton | +| `WS-REV-001-12A3` | CON mutation/cutoff/drain fences | 12A2 + CON hooks | Skeleton | +| `WS-REV-001-12A4` | Operator transitions and crash recovery | 12A3 | Skeleton | +| `WS-REV-001-13A` | Dependency preflight and drill harness | 12A4 | Skeleton | +| `WS-REV-001-13B` | Pre-release docs/generated evidence | 13A | Skeleton | +| `WS-REV-001-13C` | Product routers and final conformance release | 13B + exact AUTH activations | Skeleton; sole release | + +## Dependency shape ```text -PLAN -> 01 -> 02(parent) -> PLAN2 -> 02A(historical, superseded) --> PLAN3(boundary reset) -> WS-XINT-003-02 (03P planning input) --> 03(parent) -> 03A -> 03B --> 04(parent) -> 04A -> 04B --> 05(parent) -> 05A -> 05B --> 06(parent) -> 06A -> 06B -> 06C --> 07(parent) -> 07A -> 07B --> 08 --> 09A(parent) -> 09A1 -> 09A2 -> 09A3 -> 09A4 -> 09A5 -> 09B --> 10 --> 11(parent) -> 11A -> 11B -> 11C -> 11D --> 12(parent) -> 12P1 -> 12P2 -> 12P3 --> 12A(parent) -> 12A1 -> 12A2 -> 12A3 -> 12A4 --> 13(parent) -> 13A -> 13B -> 13C +AUTH 02D -> PLAN4 -> 03A1 +CON-03B publishes FK target + REV-03A1 -> REV-03A2 owns lease persistence +ART contract-only membership port + 03A2 -> 03B -> 04A +CON-02A + CON-02C + 04A -> 04B -> CON-03C +TASK/CHECKER/ART admission manifest -> 05A -> 05B +CON-06 + ART packet proof -> 06A -> 06B -> 06C +REV lease/manifest -> ART-07A -> REV-07A -> 07B -> 08 +human decision -> 09A1 -> 09A2 -> 09A3 -> 09A4 -> 09A5 -> 09B +CON-07 decision participant -> 10 +11A -> 11B -> 11C -> 11D +12P1 -> 12P2 -> 12P3 -> 12A1 -> 12A2 -> 12A3 -> 12A4 +13A -> 13B -> 13C ``` -Non-executable parents do not consume a PR after this planning refresh. Their -first child is the successor of the preceding executable chunk. - -REV-07B and REV-09A3 are v0.1 note/finding/response record chunks, not artifact -evidence-upload chunks. They use no evidence-upload ActionId or ART -candidate/finalize port. Any future uploaded evidence requires a separate -approved REV-owned intent plus exact ART and AUTH owner work. - -## Owner-gate rule - -Phrases such as "AUTH contributor foundation", "ART owner amendment", or -"CON participant" describe required ownership but are not executable gates. -Before a child starts, replace each phrase in its new contract with: - -```text -owner chunk ID + merged PR + merge SHA + migration head (if schema) -+ typed symbol/manifest + exact focused and regression test evidence -``` - -Known merged/planned CON IDs may be named, but proposed status remains blocked. -The contributor clean cut is merged as -`WS-AUTH-001-CONTRIBUTOR-FOUNDATION` through PR #153 at `8d5eb15b`. ART -packet-read/review-evidence/digest work still lacks exact merged owner chunks; -REV neither invents those IDs nor edits owner plans. - -## Parent split records - -Parent 02A and all of its children are retired historical planning records. -Existing parent contract files for 03, 04, 05, 06, 07, 09A, 11, 12, former 12A -release control, and 13 remain non-executable split records. -They must not be used as implementation authorization. New child contracts are -authored only from the then-current main when each child receives a human start. +Distinct owner initiatives may progress concurrently. A missing owner gate +blocks only its consumer child, not earlier independent REV persistence. +Current AUTH/XINT/CON status prose is not uniformly refreshed to current main; +each child must verify signed merge evidence and runtime symbols at start. -## Reviewers +## Contract rule -Every executable chunk requires senior engineering, QA/test, security/auth, and -product/ops. Architecture and reuse/dedup apply throughout. Schema/routes/jobs/ -active behavior add docs and test-delta. Workflows, scripts, dependencies, test -configuration, or coverage changes add CI integrity. +Only PLAN4 and 03A1 are concrete in this planning refresh. Every later row is a +reviewed architectural skeleton and must receive an exact current-main child +contract before implementation. That contract must name exact allowed files, +migration head, symbols, tests, reviewers, and owner evidence. -## Stop condition +## Stop -PLAN3 is complete. Never resume 02A, 02A1, 02A2, 02A3, 02A4, 02B, or 02C as -REV implementation. Policy work proceeds only through `WS-XINT-003-02`; later -REV feature chunks require current-main contract refresh and an explicit user -request under the ordinary engineering loop. +Planning does not start implementation. After human approval, start 03A1 only. diff --git a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/CONFORMANCE_MATRIX.md b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/CONFORMANCE_MATRIX.md index 58eaaaf7e..e6213da8c 100644 --- a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/CONFORMANCE_MATRIX.md +++ b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/CONFORMANCE_MATRIX.md @@ -6,9 +6,9 @@ No row is complete from prose or an unmerged owner contract. | Area | Owning chunks | Required executable proof | Release proof | |---|---|---|---| | Authority | 05B, 06A-C, 07A-B, 08, 09A2-A5, 10, 11A-D, 12P2, 12A1-A4, 13C | Exact active/project reviewer grant; canonical human actors; AUTH-first prepared mutations; opaque one-use bindings; clean denial/restaging; service identity isolation; no direct grant reads; no adjudication authority | Exact merged feature manifests -> AUTH activation -> phase-enabled HTTP denial/allow matrix | -| Upstream intake handoff | external Project/Task/Submission/Checker owners; consumed by 03A/05A/09A | Finalized immutable Submission; verified bindings; final current CheckerRun `allow_review`; immutable Submission predecessor and stamped context contracts. REV performs no upstream mutation. | Owner evidence plus REV admission/replay proof; gaps block and are reported, never implemented inside REV | -| Queue routing | 03A-B, 05A-B, 06A-C, 09B, 11A/C | Exact checker admission; one open/preferred entry; normalized packet membership; current returns lease/offer/none; duplicate/supersession races; authorized batched historical classification | New and historical eligible rows, preferred return, takeover, counts/age evidence | -| Leases | 03A-B, 06A-C, 11A/C | One active lease globally; canonical reviewer; packet manifest; reviewer ContributionPolicyVersion freeze; release/decline/expiry/revocation/lazy recovery and both-order races | Claim/release/expiry/reclaim/revocation through exact admitted service identities | +| Upstream intake handoff | external Project/Task/Submission/Checker owners; Submission identity referenced by 03A1, admission consumed by 05A, revision lineage consumed by 09A4 | Finalized immutable Submission; verified bindings; final current CheckerRun `allow_review`; immutable Submission predecessor and stamped context contracts. REV performs no upstream mutation. | Owner evidence plus REV admission/replay proof; gaps block and are reported, never implemented inside REV | +| Queue routing | 03A1, 03A2, 03B, 05A-B, 06A-C, 09B, 11A/C | Exact checker admission; one open/preferred entry; normalized packet membership; current returns lease/offer/none; duplicate/supersession races; authorized batched historical classification | New and historical eligible rows, preferred return, takeover, counts/age evidence | +| Leases | 03A2, 03B, 06A-C, 11A/C | One active lease globally; canonical reviewer; packet manifest; reviewer ContributionPolicyVersion freeze; release/decline/expiry/revocation/lazy recovery and both-order races | Claim/release/expiry/reclaim/revocation through exact admitted service identities | | Review history | 04A-B, 08, 10 | Every decision/finding/resolution immutable; exact predecessor/assignment lineage; reviewer CON operation before branch; accept-only FinalAcceptance and submitter operation; reject exact assignment; atomic rollback | Real accept/needs_revision/reject HTTP/database/audit/CON agreement and changed replay denial | | Revision paths | 09A1-A5, 09B, 10, 11B-D | Human Review revision creates one immutable non-branching preparation before readable state; REV consumes owner-supplied checker remediation lineage, keeps task context, creates no Review/preparation/CON record for checker-only remediation, and never classifies it as legacy | Separate checker and human drills both reach corrected N+1 without policy or lineage drift | | Revision context | 09A1-A5, 09B | Review-rooted preparation consumes owner-supplied immutable Submission/current-context facts; kept/rebased/blocked; exact head acknowledgement; one winner per head; replacement successor; no contribution-policy rebase; checker path bypasses human preparation | Human context display, checker rerun, prior-reviewer preference, resolution, final decision; checker correction returns open | diff --git a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/DECISIONS.md b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/DECISIONS.md index 24447afa8..f8d4cd058 100644 --- a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/DECISIONS.md +++ b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/DECISIONS.md @@ -206,8 +206,9 @@ adverse review outcome. REV may land decision schemas, pure validation, and transaction input types behind an unexposed boundary, but no service may commit a canonical Review until -the merged CON flush-only participant and ReviewLease/TaskAssignment -`ContributionPolicyVersion` freezes are mandatory. CON failure rolls back the +the merged CON flush-only participant and REV-owned ReviewLease plus task-owned +TaskAssignment `ContributionPolicyVersion` freezes are mandatory. CON lookup or +participant failure rolls back the entire decision. No production or test-only no-op participant exists. AUTH may activate `review.decision` only after the complete hidden REV+CON composition merges. @@ -606,3 +607,50 @@ submitter accepted-submission contribution. Submission and Review predecessor chains remain fully traversable for future adjudication without implementing adjudication now. A missing owner capability is documented and escalated to the human; REV never fills it opportunistically. + +### D29 - AUTH 02D Unblocks Hidden REV Core + +Merged PR #257 publishes the closed typed authorization contracts for all +approved REV actions while keeping those actions unavailable. REV may now build +hidden persistence and lifecycle rules without waiting for activation. Later +XINT activation consumes exact merged REV behavior; it does not authorize or +implement that behavior. + +### D30 - Core Persistence Proceeds Before External Integration + +ART and CON do not block queue persistence or other REV-owned persistence that +contains no unresolved foreign invariant. They do gate the exact consumer +schema or behavior: REV owns ReviewLease completely, but its migration follows +CON-03B because the canonical reviewer ContributionPolicyVersion table must +already exist as a mandatory FK target. ART's membership identifier contract +precedes ReviewPacketManifest; later CON and ART operations precede claim, +packet read, and decision composition. REV never guesses the missing interface, +creates a placeholder foreign model, or imports the foreign repository. + +### D31 - Queue And Lease Persistence Are Separate L1 Children + +The former 03A combined child is non-executable. 03A1 owns queue and admission- +idempotency persistence; 03A2 owns lease and preference persistence. Automatic +checker admission remains 05A, and claim behavior remains 06A. + +### D32 - v0.1 Review Evidence Is Records, Not Uploaded Artifacts + +ReviewFinding and SubmissionFindingResponse store bounded text/metadata. +`review.finding_evidence.ingest`, +`review.finding_response_evidence.ingest`, and ART review-evidence binding stay +future-intent-required and unavailable. ART packet materialization remains in +scope because it supplies the exact submitted work being reviewed. + +### D33 - Contribution Cardinality And Source Are Fixed + +Every committed human Review invokes CON's reviewer operation exactly once. +Only accept creates REV-owned FinalAcceptance and invokes CON's submitter +operation. Needs revision and reject create no submitter contribution. CON owns +ContributionRecord and award persistence; REV owns orchestration and one commit. + +### D34 - PLAN4 Is The Live Sequence + +PLAN4, the live CHUNK_MAP, and the active review specification control future +work. PLAN2/PLAN3 and retired 02-family files remain historical evidence. Only +03A1 is proposed as the first runtime child after PLAN4 approval; later child +contracts must be refreshed from then-current main. diff --git a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/DISCOVERY.md b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/DISCOVERY.md index b16fee50d..f557aa19a 100644 --- a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/DISCOVERY.md +++ b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/DISCOVERY.md @@ -1,179 +1,150 @@ # Discovery: WS-REV-001 Review And Revision Lifecycle -## 2026-07-22 Boundary Correction - -Complete rereading of the checksum-bound WS-REV Markdown, all 52 pages of its -PDF companion, the active `docs/spec_review_lifecycle.md`, and ADR 0010 confirms -that REV begins after a final current checker `allow_review` admission and must -preserve the proven Project Guide/Task/Submission/Checker intake spine. ADR 0010 -requires REV revision preparation to consume a stable active-guide identity; it -does not transfer Project Guide setup or activation ownership to REV. - -The derived PLAN2/02A sequence incorrectly converted that dependency into REV -implementation ownership. Proposed 02A1 Project/setup fencing, 02A3 activation -chronology, 02A4 general Task stamping, and 02A2 guide reactivation are therefore -retired as REV chunks. Any still-needed capability must be specified as an -external owner handoff. The unmerged 02A1 runtime candidate was reverted before -publication. - -After merging current main at `14fa4316f7d984f2176657bfafd2a2dae56f944e`, -the sole migration head is `0033_authorization_read_rate_control`. AUTH PR #175 -changes no REV product boundary. Signed loop memory remains stopped with retired -02A1 named next; PLAN3 must replace that successor through reviewed merge memory -before 03P can receive a signed start. - -## Baseline - -Discovery was refreshed read-only from trusted main -`14fa4316f7d984f2176657bfafd2a2dae56f944e`. PLAN3 makes no backend/runtime -changes. - -## Current boundary facts - -- The repository remains FastAPI/Python with async SQLAlchemy 2.x, Alembic, - Pydantic, and PostgreSQL; the sole head is - `0033_authorization_read_rate_control`. -- `Submission` remains the owner-supplied versioned submission entity. REV must - consume its exact finalized identity, immediate-predecessor lineage, Task and - contributor facts, and submitted artifact membership; any missing invariant - or typed read contract is work for that owner. -- Checker completion remains owner-supplied. REV admission may consume only one - durable final/current `allow_review` result; it may not produce or repair a - CheckerRun. -- ART recovery is present through migration `0032_artifact_recovery_attempts`, - but each future REV artifact read/evidence need still requires an exact merged - typed owner contract and proof at that chunk's signed start. -- AUTH PR #175 and migration `0033_authorization_read_rate_control` add - authorization-read rate control without transferring reviewer identity, - permission, or lifecycle ownership to REV. -- CON remains the owner of contribution records. REV later composes its typed - participant so every committed Review creates one reviewer contribution and - only accept creates the submitter accepted-submission contribution. -- REV owns ReviewPolicy/RevisionPolicy (03P), queue/lease persistence (03A/03B), - admission/routing (05A/05B), immutable Review/finding/resolution chains, - human revision replay, FinalAcceptance, and decision orchestration. - -## Historical PLAN2 discovery snapshot — archival and void - -> Every section and ownership/chunk statement below this heading records the -> superseded PLAN2/02A investigation only. It is not current dependency truth, -> an owner assignment, a human-decision request, or implementation authority. -> D28, PLAN3, `CHUNK_MAP.md`, and the proposed 03P/03A contracts control. - -## Historical backend snapshot - -- FastAPI/Python, async SQLAlchemy 2.x, Alembic, Pydantic, PostgreSQL. -- Historical single Alembic head: `0028_artifact_admission`. -- `Submission` is the existing versioned submission entity; no separate - SubmissionVersion is needed. -- TaskAssignment and Submission now expose only `contributor_id`; each has an - ActorProfile FK and database-enforced human-kind lineage. -- Existing checker routing can move a Task to `needs_revision` with - `review_decision_id=None`. The regression - `test_checker_caused_revision_resubmits_fixed_version_through_api` proves this - supported path. -- Existing project guide activation is a public bodyless route with legacy - registered-actor/local-role checks, locks the candidate before Project, uses - application time, and allows only draft activation. It rejects both an - already-active repeat and a superseded candidate. 02A3 owns the explicit - additive no-write active repeat; superseded-guide reactivation must not be - added under legacy authorization. -- Task screening currently does not share the Project-first publication lock. - -## AUTH discovery - -- Trusted catalogue remains independent from this split; all REV lifecycle - actions remain unavailable. -- AUTH-09A/09B/09C, 09D-A, and 09D-B are merged. PR #148 merged 09D-A as - `99ae4c963e53f317175dcb308b9e47c93ccf19ed` from reviewed head - `9c5ef8a1feffd6324acfd947e67042921955320b`, establishing database-backed - ActorProfile lifecycle status/provenance and migration - `0026_actor_profile_lifecycle`. -- `WS-AUTH-001-CONTRIBUTOR-FOUNDATION` merged through PR #153 at `8d5eb15b` - from reviewed head `6a70b33f`. Migration `0027_contributor_foundation` - supplies the exact field clean cut, ActorProfile FKs, reusable human-kind - trigger function, active-human transaction revalidation, and regression - evidence required by REV. -- AUTH-09E, AUTH-PREP, REV custody, AUTH-10 through 14, and matching feature - activations remain unmerged. AUTH-13/14 contracts require later amendment for - prepared revision/replacement facts and cannot be treated as current runtime - gates. -- All 24 REV lifecycle actions remain unavailable. REV never registers, - provisions, evaluates, or activates them. - -## ART discovery - -- ART v2 LocalStorage clean cut merged through PR #141 at `a10d901`, S3/MinIO - preparation merged through PR #151 at `1b5422fc`, and admission/put-attempt - foundation merged through PR #154 at - `44f2467cedc266d2efe261119cfff436ac6b7715` from final head `c93f1a24`. -- PR #154 adds `0028_artifact_admission` and no Project/setup writer file, so - the 02A1 writer inventory is unchanged by that merge. Provider execution, - verification publication, recovery, routes, and product cutover remain later - ART work. -- Current ART map does not schedule an exact lease-scoped review packet-read - capability, review-evidence candidate/finalize capability, or server-derived - stabilized Submission artifact digest. REV-03B, 07A/07B, 09A3/09A4, 10, and - projection work remain blocked on exact owner chunks. -- REV must consume typed capability ports and never ArtifactStore, concrete - adapters, provider references, scratch paths, or ART repositories. - -## CON discovery - -- CON-01 canonical specification/ADR is merged; CON runtime 02A onward remains - proposed on trusted main. -- Any unmerged CON migration must rebase from the current head; REV consumes no - sibling worktree or proposed revision number. -- Exact planned dependencies are CON-02A outbox, 02C audit participant, 03B - ContributionPolicyVersion, 03C contribution/award persistence, 06 lease - freeze, 07 atomic two-operation participant, and later delivery/readiness - hooks. Proposed contracts are not runtime proof. -- The stable boundary is reviewer contribution from Review for every decision - and submitter contribution from accept-only FinalAcceptance. - -## Product findings - -- All reviewer decisions/findings/resolutions are append-only. -- The historical PLAN2 proposal observed that checker-caused remediation is - supported but accepted ADRs scope controlled - guide rebase/preparation to human Review revision. The plan must preserve a - distinct CheckerRun-rooted N+1 path rather than treating it as legacy or - silently applying human RevisionPolicy/D6 behavior. Current Submission storage - lacked immutable causal CheckerRun lineage. It incorrectly assigned 02C to add - and backfill `remediation_source_checker_run_id`; under PLAN3, any still-needed - lineage is an external Checker/Submission owner requirement that REV consumes. -- Human revision context is task-owned. REV supplies exact human decision/ - finding facts through a typed task participant. Checker remediation retains - its existing task/checker path and locked context. -- Task guide identity and reviewer packet access require database-enforced - immutability/lease scope, not service convention. -- The exact decision lock order must put AUTH authority first, then - ReviewDecisionRequest, ReviewLease, queue, task, exact Submission assignment, - Submission, and stable subordinate rows. - -## Plan-review findings incorporated - -- Split unsafe oversized parents 03-07, 09A, 11, 12/12A, and 13. -- Keep 08 pure; keep 10 as the first canonical decision transaction. -- Parent 02A failed L1 preimplementation review because it combined the entire - project/setup writer graph, guide chronology, Task stamping, two migrations, - and persistent coverage work. Split it into 02A1 fencing, 02A3 chronology, - and 02A4 Task triplet before runtime. Keep later hidden 02A2 reactivation - separate; 02A2 must merge - before AUTH-12 evaluator/cutover/activation, not after an active action. -- Move historical admission scan to authorized reconciliation child 11C. -- Separate persisted phase execution denial from static router/AUTH membership - and operational scheduler state. -- Keep active release docs and route registration together in 13C. - -## Unknowns and owner actions - -- AUTH must later amend AUTH-12/13/14 contracts; the contributor foundation - gate itself is satisfied. -- ART must schedule/merge packet-read, review-evidence, digest, and projection - capabilities. -- CON must merge its runtime foundations from the then-current migration head. -- Human must approve the two positive 02B duration defaults. - -Until those facts are on trusted main, REV planning may continue but runtime -must stop at each affected gate. +## Current-main baseline + +Discovery was refreshed read-only from `origin/main` at `3479ee71`, merged PR +#257, on 2026-08-03. The sole Alembic head is +`0049_rev_auth_readiness`. No `backend/app/modules/reviews/` package or REV +runtime table currently exists. + +The active product contract is `docs/spec_review_lifecycle.md`. The supplied +WS-REV/WS-IMP Markdown and PDF files under `docs/reference_specs/` are immutable +historical inputs governed by the precedence rules in that active contract. + +## Implemented upstream facts + +### AUTH + +- `backend/app/modules/authorization/review_contracts.py` defines frozen typed + contracts for all approved REV reads, mutations, services, recovery, and + release control. +- `backend/tests/test_review_authorization_contracts.py` proves strict shapes, + action/mode parity, scalar serialization, and absence of handles/ORM values. +- `catalogue.py`, migration `0049_rev_auth_readiness`, and fixed service + identity registration contain all approved REV actions and six service + identities. Lifecycle actions remain unavailable. +- Policy configuration is already active through + `policy_mutation_router.py`, `policy_mutation_service.py`, and migration + `0048_review_revision_policy_authority.py`; it is setup authority, not REV + lifecycle behavior. + +REV must compose the exact models from `review_contracts.py`. It must not add a +parallel resource-context family or import AUTH repositories. + +### Project, Task, Submission, and Checker + +- ReviewPolicy and RevisionPolicy are immutable identities with generation, + digest, semantic status, and predecessor lineage. +- ProjectGuide selects exact policy triples. Task, Submission, and CheckerRun + copy and foreign-key the same lineage. +- `backend/app/modules/tasks/models.py` owns Task, TaskAssignment, and the + existing versioned Submission identity. +- `backend/app/modules/checkers/models.py` owns CheckerRun; + `backend/app/modules/checkers/service.py` defines `allow_review` routing. +- Current checker tests prove final `allow_review` outcomes, but there is no REV + queue admission participant yet. + +REV consumes these facts and never edits their general intake semantics. + +### ART + +- ART owns immutable bytes, verified bindings, extraction, materialization, + and provider access through typed capability ports. +- Reviewer evidence upload/binding is not approved v0.1 behavior. Findings and + contributor responses are records only. +- ART reviewer packet materialization remains future `WS-ART-001-07A` and + requires a hidden REV packet manifest. +- The current ART plan does not yet publish the contract-only packet membership + identifier/port that REV-03B needs. ART must publish that type first without + depending on REV runtime; REV then owns normalized lifecycle membership and + ART-07A consumes the resulting manifest for byte materialization. +- ART's submission/checker cutover remains incomplete. Until the final typed + admission handoff merges, REV may build persistence and pure rules but must + not guess binding identifiers or call the raw ArtifactStore. + +### CON, audit, and outbox + +- Shared transactional outbox persistence exists under + `backend/app/modules/outbox/`. +- Shared audit services exist under `backend/app/modules/audit/`, but that does + not by itself prove the planned CON-02C lifecycle-audit participant. +- CON runtime review integration remains future. The stable boundary is one + ordered reviewer operation for every Review and one submitter operation only + after REV creates FinalAcceptance on accept. +- Core decision composition performs no ART/provider I/O. + +## REV-owned runtime to add + +- ReviewQueueEntry and admission idempotency. +- ReviewLease, preference state, and completed lease history. +- ReviewPacketManifest and normalized membership. +- Review, ReviewFinding, FindingResolution, and decision idempotency. +- FinalAcceptance. +- RevisionContextPreparation, SubmissionFindingResponse, and immutable episode + lineage. +- Recovery/reconciliation findings, projection inputs, and lifecycle release + control. +- Thin routers only at the final product release. + +## Existing conventions to preserve + +- Async SQLAlchemy 2.x models/repositories/services and caller-owned sessions. +- Alembic single-head migrations allocated only from then-current main. +- PostgreSQL partial unique constraints, database time, `FOR UPDATE`, stable + lock order, and direct-SQL invariant tests. +- Pydantic schemas and closed enums. +- AUTH PREP handles remain opaque, process-local, session/transaction/action/ + principal/request/resource-bound, and single use. +- Typed participant/port boundaries; no generic service locator or concrete + adapter import. +- GitHub Actions owns the full suite and repository-wide coverage run. + +## Tests and gaps + +Existing tests cover policy lineage, checker routing, task/Submission behavior, +AUTH contracts, audit, and outbox. Missing tests necessarily include all REV +schema, queue, lease, decision, revision, recovery, projection, and release +behavior because those modules do not exist. + +Each implementation child must add focused tests for its own constraints and +both orders of every relevant race. No child may weaken existing checker-caused +revision coverage. + +## Dependencies and integration gates + +- Queue/admission-idempotency persistence: AUTH 02D merged; safe to begin. +- REV owns all lease persistence and lifecycle. Its migration requires the + merged CON-03B canonical ContributionPolicyVersion table solely as the + non-null FK target; that target is not yet evidenced merged. +- Packet-manifest persistence requires a published ART contract-only membership + identifier/port without an ART-07A runtime dependency; it is currently an + owner gap. +- Automatic queue admission requires the exact final TASK/CHECKER/ART handoff + to merge before 05A; it is not currently evidenced merged. +- Claim packet creation: queue/lease persistence, CON-06's claim-time policy + lookup result used by REV for its lease freeze, and exact ART packet + membership/materialization contracts. +- Decision commit: Review/FinalAcceptance persistence, TASK participant, CON + contribution participant, audit, and outbox. +- Product reads/routes: matching AUTH activation plus lifecycle release gate. + +## Risks discovered + +- Current planning contains large historical sections that can be mistaken for + live authority. +- ART and CON status documents contain stale historical snapshots; only exact + merged symbols and current capability ledger are implementation evidence. +- Far-future file and migration paths cannot be frozen safely now. Their chunk + contracts remain skeletons until refreshed at start. +- The human revision round/deadline semantics remain intentionally undecided. + +## Unknowns requiring later owner evidence + +- Final typed ART/CHECKER-to-REV admission manifest. +- ART contract-only reviewer packet membership input and later ART-07A + materialization input/output types. +- Final CON claim-time reviewer-policy lookup and two-operation decision + participant. +- Exact TASK decision and human-revision participant interfaces. + +These unknowns do not block 03A1. They do block their named later consumers. diff --git a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/INTENT.md b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/INTENT.md index 7d73a83ab..541cd397e 100644 --- a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/INTENT.md +++ b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/INTENT.md @@ -1,175 +1,114 @@ # Intent: WS-REV-001 Review And Revision Lifecycle -## Human goal - -Implement the complete Workstream v0.1 human review and revision lifecycle from -durable checker admission through immutable review decisions, revision replay, -terminal reject, recovery, artifact-backed judgment, contribution integration, -and HTTP-visible proof. - -## Why this matters - -The current backend proves intake through `review_pending`, but it does not yet -provide an authorized human judgment layer. Workstream cannot certify completed -work until it can route review-ready submissions, prevent self-review and lease -hoarding, preserve every review attempt and finding, replay prior feedback on a -revision, and distinguish product judgment from checker or infrastructure -outcomes. - -## Success state - -- An admitted submission creates exactly one review queue entry. -- A current human holding one exact active project `reviewer` grant sees only - their active lease or one next offered item and can claim at most one review - globally. Separate `submitter` or `adjudicator` grants add no review authority. -- Claims, releases, preference changes, decisions, overrides, and recovery use - current centralized authorization and canonical resource scope. -- Every human identity in task/submission/review lineage is the canonical - active `ActorProfile.id`; service/system actors remain explicitly typed and - cannot occupy contributor or reviewer identity. -- Reviewers see full bounded Submission/Review history, but artifact content is - restricted to the canonical current review packet anchored to the exact - Submission covered by their active lease. -- Every valid reviewer decision appends a new immutable `Review`. Every finding - submitted with that Review and every later finding resolution is also - immutable; later revision rounds append new records rather than changing old - ones. `accept`, `needs_revision`, and `reject` remain idempotent, atomic - decision values with their specified task and assignment effects. -- When the immutable Review decision is `accept`, the same transaction also - creates one immutable REV-owned `FinalAcceptance` linked to that Review and - Submission. Submitter contribution lineage consumes that stable fact rather - than inferring acceptance from `Review.decision`. -- Revisions respond to every unresolved blocking finding, preserve both - predecessor chains, and compare the prior Submission's stamped guide identity - and activation sequence with the project's currently active Project Guide. - Exact match keeps context; any different active identity or sequence rebases - forward or backward; missing, incomplete, or unsafe active context blocks. - Return routing prefers the prior reviewer before falling back to open FIFO. -- A supported checker-caused `needs_revision` remains a distinct CheckerRun- - rooted remediation that keeps task context and persists a unique server- - derived immutable source-CheckerRun relation on corrected N+1. It creates no - synthetic Review, finding, reviewer contribution, or human actor. Controlled - preparation/rebase, finding replay, human revision policy, and D6 closure apply - only to an exact `Review(needs_revision)`. -- Artifact outage or integrity failure blocks judgment without creating an - adverse contributor outcome. -- Every committed Review joins the `WS-CON-001` contribution and conditional - compensation transaction before any public review lifecycle route is enabled. - Every decision creates the reviewer contribution. When the decision is - `accept`, REV also creates `FinalAcceptance`, and CON creates the submitter - contribution from that fact. -- Guide rebase never rebases compensation: TaskAssignment freezes submitter - terms and each ReviewLease independently freezes reviewer terms. -- Timers, revocation recovery, reconciliation, projection, audit, - observability, and privacy-safe live drills prove normal and failure paths. - -## Boundaries - -- REV runtime begins only from a durable, final, current CheckerRun whose - routing recommendation is `allow_review`, using the existing finalized - Submission and its canonical verified artifact bindings. Project Guide - creation, setup, publication, activation, chronology, approval provenance, - and general Task-context stamping remain upstream owner responsibilities. -- If REV discovery finds a missing upstream capability, record the exact typed - contract, invariants, and proof needed from that owner and stop. Do not - implement the missing Project, Task, Submission, Checker, AUTH, ART, or CON - subsystem behavior inside REV. -- Preserve the proven project guide, task, submission, and checker spine through - `review_pending`. -- Extend the existing versioned `Submission`; do not create a duplicate - `SubmissionVersion` business identity. -- Maintain one Project Guide context through the task pipeline. TaskAssignment - binds to the WorkstreamTask that owns the initial context lock rather than - duplicating guide fields; reviewers consume the context stamped on the leased - Submission and do not maintain a separate review guide. -- Consume `WS-AUTH-001` through its authorization kernel and decisions; do not - query grant tables or reconstruct permissions in review code. -- Consume only the typed ART-owned packet-read capability backed by the - canonical `ArtifactStore`; review services never receive the raw store, - provider adapters, provider references, or scratch paths. Evidence - candidate/finalize capabilities remain future-intent-required. -- Keep PostgreSQL canonical for review truth. Storage projection is derived, - asynchronous, and retryable. -- Keep review code free of contribution-policy, award, fulfillment, and - reputation policy. `WS-CON-001` owns the flush-only transaction participant; - REV owns lifecycle orchestration and shared audit/outbox staging inside the - caller transaction, while the request route or service command owns the caller - `AsyncSession` and only commit. Core contribution/award creation performs no - ART call or external I/O. -- Keep frontend delivery separate until backend contracts and lifecycle guards - are stable and proven. - -- Preserve a fully traversable immutable task history: every revised Submission - identifies its immediate predecessor, every later Review identifies the prior - Review in the same task chain, and findings, responses, and resolutions append - without rewriting history. This history is future adjudication input, but REV - implements no adjudication behavior. - -## Non-goals - -- Self-review, reviewer bidding, multiple concurrent review leases, automated - reviewer grants, reputation scoring, adjudication lifecycle/actions, or reject - reassignment. The independent `adjudicator` grant exists but confers no REV - operation in this initiative. -- Flow Node or R2 provider implementation in v0.1. -- Workstream-owned authentication, login, sessions, or credentials. -- A second artifact store or review-authoritative search index. -- Payment-provider execution, points balances, or settlement. -- A frontend implementation inside the backend-first WS-REV chunks. - -## Human decisions confirmed - -1. Approved provider direction: LocalStorage for development, MinIO for local/CI - conformance, AWS S3 for production; Flow Node remains deferred. -2. ADR 0010 is retained with the clarified one-Project-Guide task pipeline, - exact stamped guide identity/activation-sequence match keeps, any different - currently active identity/sequence rebases forward or backward, Task Context - visibility uses the frozen preparation, and no reviewer-side guide exists. -3. D6's recommendation is approved: limit/deadline blocks further submission while - leaving `needs_revision` active, with only the covered Project Manager's - explicit reason-bound `review.revision_obligation.close` command and never a - fabricated human `reject` Review. -4. The revised reviewer `current` endpoint controls over - the older WS-IMP full-backlog reviewer response. -5. Production enables the coherent lifecycle route set only after the - repaired and reviewed `WS-CON-001` plan, exact lineage/digest contract, - atomic participant, lease freeze, recovery, reconciliation, projection - operations, and the exact merged CON-owned joint-readiness manifest exist. -6. Merged WS-XINT-001 PR #139 controls cross-initiative ownership: feature - chunks build hidden behavior, AUTH alone registers/transfers/activates exact - actions, and REV performs only the later joint product-surface release. -7. Project roles are independent `submitter`, `reviewer`, and `adjudicator` - grants. REV consumes only the exact reviewer grant and reviewer invalidation. -8. Core ContributionRecord creation copies the stabilized versioned - Submission `artifact_hash` lineage, evaluates the frozen - `ContributionPolicyVersion`, and has no mandatory contribution-evidence - artifact projection. -9. The v0.1 acceptance boundary is `Review(accept) -> FinalAcceptance -> - accepted_submission`. `FinalAcceptance` is an internal REV-owned derived - fact with no manual/public create API or separate authorization action. The - review request uses one CON participant with an ordered reviewer contribution - operation before the decision branch. It invokes the submitter contribution - operation only after FinalAcceptance exists. REV stages shared audit and - outbox records; the request route or service command commits once. -10. Merged AUTH reconciliation PR #140 is planning authority, not runtime proof. - Exact AUTH custody, PREP, registration, service-identity, and activation gates - apply per consumer so hidden REV work can proceed while every action remains - unavailable; REV-13C alone releases product surfaces. -11. **Superseded by D28/PLAN3:** the former guide chronology/reactivation - sequencing decision is historical and provides no REV implementation authority. -12. Persisted release phase denies execution but does not dynamically unregister - routers, deactivate AUTH mappings, or replace operational scheduler control. - -Items 3-5 and the proposed chunk sequence were approved by the human on -2026-07-15 for planning publication. This approval does not activate a successor -implementation chunk before the planning PR merges and its separately declared -start gate is satisfied. - -## Proof strategy - -Use PostgreSQL constraint and concurrency tests, focused module coverage at or -above 90 percent, repository-wide coverage at or above the current 78 percent -floor, API contract tests, LocalStorage and MinIO artifact conformance, timer -and reconciliation tests, and privacy-safe HTTP-visible drills covering -revision, takeover, reject, expiry, revocation, evidence attachment, outage, -and recovery. +## Problem being solved + +Current main proves project policy, task, Submission, checker, and authorization +foundations but has no human review runtime. Workstream cannot yet turn a final +current CheckerRun recommendation of `allow_review` into an authorized, +immutable, traversable judgment and revision history. + +## Why this work matters + +Review is the certification boundary between submitted work and trusted +ContributionRecord facts. It must prevent self-review, duplicate claims, +mutable judgment, hidden history loss, and partial contribution effects while +remaining independent of AUTH, ART, CHECKER, TASK, and CON internals. + +## Current behavior + +- AUTH `WS-XINT-003-02A` through `02D` are merged through PR #257 at + `3479ee71`. Policy identity/mutation, the complete unavailable REV catalogue, + six fixed service principals, and closed typed REV authorization contracts + exist. +- The sole Alembic head is `0049_rev_auth_readiness`. +- All REV lifecycle actions remain planned or unavailable; no review route, + queue, lease, Review, revision, or recovery behavior exists. +- ART owns the Submission artifact custody chain and reviewer packet bytes. + Its final submission/checker and reviewer-packet handoffs remain future work. +- CON owns ContributionRecord, award, and fulfillment behavior. Its typed + review participant remains a later integration dependency. + +## Target behavior + +```text +final current CheckerRun = allow_review ++ existing immutable Submission ++ exact verified ART binding facts + -> one REV queue entry + -> server-selected offer + -> one active reviewer lease globally + -> lease-bounded packet and chain + -> immutable Review + findings/resolutions + -> accept | needs_revision | reject + -> revision replay or FinalAcceptance + -> reviewer ContributionRecord for every Review + -> submitter ContributionRecord only from FinalAcceptance +``` + +All prior Submissions, Reviews, findings, responses, and resolutions remain +traversable. Future adjudication may consume that history but is not part of +v0.1. + +## Design chosen + +Build the complete hidden REV core behind stable AUTH `02D` contracts. Keep +external intersections behind typed ports and wire them only after their owners +merge exact interfaces. Persistence and pure lifecycle rules may proceed before +ART packet materialization or CON decision participation is available. + +The first implementation child is a REV-only persistence foundation. It does +not admit checker results, expose routes, activate actions, call ART, or create +contributions. + +## Boundaries preserved + +- REV begins at final current `allow_review`; it never creates or repairs a + Project Guide, Task, Submission, CheckerRun, or artifact binding. +- AUTH owns ActorProfile/grant evaluation, PREP, evidence, fixed principals, + catalogue, and availability. REV locks its own facts and composes the exact + final `review_contracts.py` model. +- ART owns bytes, verified bindings, the typed binding/membership identifier + port, materialization, provider behavior, and packet-byte delivery. REV owns + normalized packet-manifest membership and lifecycle meaning after consuming + those identifiers. +- TASK owns task/assignment/Submission transitions through typed + caller-transaction participants; REV owns decision orchestration. +- CON owns ContributionRecord, policy, awards, and fulfillment through typed + flush-only operations. REV owns Review, FinalAcceptance, audit/outbox staging, + and the single transaction commit. +- PostgreSQL is canonical. Projections are derived and retryable. + +## Expected risks + +- Cross-subsystem interfaces may arrive after core persistence. +- Queue, claim, expiry, decision, and revocation races require database proof. +- Historical plans use obsolete names, owners, and dependencies. +- Large combined migrations or public-route work would be unreviewable. +- A contribution or artifact outage must never fabricate an adverse decision. + +## What must not change + +- Decisions remain exactly `accept`, `needs_revision`, and `reject`. +- Self-review remains forbidden and reviewer capacity remains one active lease. +- Existing Submission is the version identity; no `SubmissionVersion` table. +- Findings and responses are text/metadata records in v0.1; uploaded review + evidence remains separate future intent. +- Checker-caused remediation remains distinct from human revision. +- Reject affects only the exact task/assignment and creates no submitter + contribution. +- No adjudication, reputation mutation, frontend, marketplace, or provider + expansion enters this initiative. + +## How this will be proven + +Database constraints, migrations, independent-session concurrency tests, +AUTH-contract parity, typed-port architecture scans, fault injection, focused +changed-subsystem coverage at or above 90 percent, GitHub-hosted full coverage +at or above 78 percent, and final real-API lifecycle drills. + +## Human decisions required + +No decision blocks the first persistence child. Before human revision episode +work, the human must approve exact revision round counting, deadline anchor, +and inclusive/exclusive deadline semantics. Every later implementation child +still requires its own explicit start. diff --git a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/PLAN.md b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/PLAN.md index 6c233879b..203a2a030 100644 --- a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/PLAN.md +++ b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/PLAN.md @@ -1,403 +1,273 @@ # Plan: WS-REV-001 Review And Revision Lifecycle -Current cross-initiative authority and policy-writer sequencing is canonical in -`../WS-XINT-003-rev-auth-end-to-end/ACTION_CUSTODY.md`. Planning artifacts do -not require signed starts, active-chunk state, or merge intents. - -## Boundary Reset — 2026-07-22 - -This section supersedes every later passage that assigns Project Guide setup, -publication, activation, chronology, reactivation, or general Task-context -stamping to a REV chunk. Those passages remain historical planning evidence but -are not implementation authority. - -REV consumes one existing finalized Submission after a durable final current -CheckerRun recommends `allow_review`. It then owns admission into review, -routing, leases, packet semantics, immutable Reviews/findings/resolutions, -human revision replay, FinalAcceptance, and decision orchestration into CON. -Every Review creates one reviewer contribution; accept alone creates -FinalAcceptance and the submitter accepted-submission contribution. - -Submission and Review history are immutable predecessor chains scoped to one -Task and must be completely traversable for operations and future adjudication. -Adjudication itself remains out of scope. Missing upstream facts become typed -owner handoffs and blockers; REV does not implement them. - -## Planning authority - -This PLAN3 candidate is reconciled from current trusted main -`14fa4316f7d984f2176657bfafd2a2dae56f944e`; its single Alembic head is -`0033_authorization_read_rate_control`. Worktree branches, unmerged PRs, and proposed owner -changes are discovery evidence only. The detailed facts below were captured at -the earlier PLAN2 snapshot and are historical unless independently re-proven. - -Generated loop memory naming retired 02A1 is historical only and has no -implementation authority. The current WS-XINT-003 chunk map governs future -cross-initiative sequence; implementation still requires an explicit user -request under the ordinary repository engineering loop. -They are not runtime dependencies until their exact owner chunk, PR, merge SHA, -schema head, typed contract, and tests exist on trusted main. - -Historical PLAN2 merged facts were: - -- the PLAN2 snapshot Alembic head was `0028_artifact_admission`; -- TaskAssignment and Submission attribution use canonical `contributor_id` - ActorProfile foreign keys and database-enforced human lineage; -- the AUTH catalogue contains 74 PermissionIds and 65 ActionIds, with 15 active - and 50 planned; -- all 24 REV lifecycle action dependencies remain unavailable; -- ART admission and prepared put-attempt foundation is merged through PR #154, - but provider execution/publication, review packet reads, review-evidence - candidate/finalize, and server-derived stabilized Submission artifact lineage - do not have merged owner contracts; -- CON has merged its canonical specification, but its outbox, audit, - contribution-policy, contribution/award, freeze, and atomic participant - runtime chunks remain proposed. - -AUTH-09D-A is merged through PR #148 at -`99ae4c963e53f317175dcb308b9e47c93ccf19ed` and supplies database-backed -ActorProfile lifecycle status/provenance in migration `0026`. The separate -`WS-AUTH-001-CONTRIBUTOR-FOUNDATION` merged through PR #153 at `8d5eb15b` from -reviewed head `6a70b33f`; migration `0027_contributor_foundation` clean-cuts -both task-subsystem owner fields, adds canonical-human constraints, and exposes -transaction-local active-human revalidation without changing authorization -availability. That external runtime gate is satisfied. Each REV migration still -allocates only the then-current next revision at its own explicit start. -ART PR #154 later advanced the sole head to `0028_artifact_admission` without -changing a Project/setup writer. It creates no REV migration conflict; every -future REV child still refreshes from then-current trusted main. - -## Shipping boundary - -The v0.1 product path is: +## Current authority -```text -project guide -> task -> submission -> checkers -> review/revision --> FinalAcceptance on accept -> ContributionRecord --> CompensationAward where frozen policy permits --> asynchronous external fulfillment -``` - -Review decisions stored by the product are only `accept`, `needs_revision`, and -`reject`. Every valid Review, every submitted finding, and every later finding -resolution is immutable. A later round appends new records. +This PLAN4 refresh supersedes PLAN2/PLAN3 implementation sequencing while +preserving their boundary correction: REV begins only at a final current +CheckerRun `allow_review`. Historical files remain evidence, not executable +authority. Current implementation must follow this plan, `CHUNK_MAP.md`, the +active `docs/spec_review_lifecycle.md`, and exact refreshed child contracts. -Adjudication is disabled and unimplemented. This initiative adds no -adjudication action, state, queue, lease, policy, decision, contribution, or -readiness dependency. Stable origin and lineage interfaces may accept a new -future origin kind only through a separately approved migration and lifecycle; -that future compatibility does not implement adjudication now. +## Architecture -## Canonical decision transaction +```text +TASK/CHECKER/ART handoff + immutable Submission + final allow_review + verified binding facts + | + v +REV hidden core + admission -> queue -> offer -> claim -> lease -> packet/context + -> Review/findings -> revision or FinalAcceptance + | + +-> AUTH evaluates exact typed contracts and stages decision evidence + +-> TASK applies typed lifecycle effects + +-> ART materializes only authorized packet bytes + +-> CON stages contribution/award facts + +-> shared audit/outbox stage in the same caller transaction +``` -The review request or service command owns the only transaction and commit. -AUTH, task, REV, CON, audit, and outbox collaborators are session-bound, -flush-only participants. +REV owns lifecycle state and orchestration. It never imports foreign +repositories or repairs foreign facts. + +## Delivery strategy + +### Wave 1 — REV persistence with explicit owner gates + +1. `03A1` adds queue/admission-idempotency persistence only. +2. `03A2` adds the entirely REV-owned lease/preference persistence. Its + migration follows CON-03B only so the lease can store its required non-null + FK to the already-existing canonical `ContributionPolicyVersion`. +3. `03B` adds normalized immutable ReviewPacketManifest persistence after the + ART membership contract is exact. +4. `04A` adds immutable Review/finding/resolution and decision-request + persistence. +5. `04B` adds FinalAcceptance plus shared audit/outbox linkage persistence. + +These chunks expose no routes, activate no actions, and perform no ART or CON +operation. After AUTH 02D, 03A1 can proceed independently. REV still owns every +03A2 lease row, constraint, timestamp, and transition; only its migration order +waits for CON-03B's FK target. 03B waits for the exact ART packet-membership +identifier contract. These are reference-order gates, not foreign ownership of +REV behavior. + +### Wave 2 — Admission and server-selected work + +6. `05A` composes final `allow_review` admission using owner-supplied + Submission, CheckerRun, and verified ART facts. It creates exactly one open + queue entry and transitions only through typed TASK/CHECKER participants. +7. `05B` implements concealed current-work selection: active lease, one + server-selected offer, or none. It never exposes the backlog. + +AUTH action activation remains separate in XINT-003-03A and does not release a +product router. Before activation, REV proves its hidden feature rules and the +AUTH-unavailable denial path separately; the positive integrated authorization +path belongs to the matching XINT activation after the REV behavior merges. + +### Wave 3 — Claim, lease, and packet + +8. `06A` implements atomic claim, one-active-lease capacity, REV's lease policy- + version freeze using the lookup result supplied by CON-06, and packet- + manifest freeze with ART-owned membership. +9. `06B` implements owned release and preferred decline. +10. `06C` implements database-time preference/lease expiry, lazy recovery, and + fixed-service commands. +11. `07A` implements lease-bounded context and chain reads, consuming ART + packet materialization without raw storage access. +12. `07B` implements immutable reviewer notes/findings as records only. + +### Wave 4 — Decision and human revision core + +13. `08` is pure decision validation and effect planning. It commits no Review. +14. `09A1` persists Review-rooted revision episodes/preparation after the human + approves round/deadline semantics. +15. `09A2` publishes the typed TASK revision participant and context resolver. +16. `09A3` adds immutable contributor finding-response records. +17. `09A4` integrates prepared human N+1 Submission lineage while preserving + the separate CheckerRun-remediation source. +18. `09A5` handles replacement-assignment preparation successors. +19. `09B` replays findings/resolutions and creates preferred return routing. + +Uploaded reviewer/response evidence is excluded from v0.1. + +### Wave 5 — Canonical decision commit + +20. `10` composes the first canonical decision transaction: ```text -compute canonical request key/digest without a database lock --> AUTH prepare and authority lock --> reserve/lock ReviewDecisionRequest --> lock the review lifecycle fence --> lock ReviewLease --> lock ReviewQueueEntry --> lock WorkstreamTask --> lock the exact Submission.task_assignment_id row --> lock the exact Submission --> lock predecessor Review/finding/resolution/evidence rows in stable ID order --> recompose final facts and consume/evaluate AUTH handle once --> append immutable Review and submitted findings/resolutions --> consume ReviewLease and close ReviewQueueEntry --> CON reviewer operation creates completed_review and evaluates reviewer freeze --> apply decision branch --> stage shared audit/outbox rows --> commit once +AUTH consume +-> Review/finding/resolution append +-> lease consume + queue close +-> reviewer CON operation +-> decision branch +-> accept only: FinalAcceptance + TASK accept + submitter CON operation +-> needs_revision: TASK state + revision preparation +-> reject: exact assignment block + TASK reject +-> shared audit/outbox +-> one commit ``` -The user-confirmed ReviewLease-before-queue order controls this command. Other -commands must publish their own order and may not refer vaguely to a universal -canonical order. Cross-domain rows of the same type lock by ascending primary -key. Database time is read after the relevant locks. No remote ART or external -fulfillment call occurs in the transaction. - -Decision branches are exact: - -- `accept`: append `FinalAcceptance`, set Task `accepted`, complete the exact - reviewed TaskAssignment, invoke CON submitter operation from - `FinalAcceptance`, then stage shared audit/outbox. -- `needs_revision`: invoke the task-owned preparation participant, append the - human-Review-rooted initial preparation, set Task - `needs_revision`, keep the assignment active, and create no FinalAcceptance or - submitter contribution. -- `reject`: block the exact immutable `Submission.task_assignment_id`, set Task - `rejected`, and create no FinalAcceptance or submitter contribution. - -Every branch creates the reviewer `completed_review` ContributionRecord. CON -failure rolls back the Review and all lifecycle effects. External award/points -delivery is post-commit outbox work and cannot roll back acceptance. - -## FinalAcceptance - -`FinalAcceptance` is an immutable internal derived fact created only by the -successful accept branch. It has no public/manual create API and no separate -authorization action. It records project, task, exact Submission, source Review, -accepted submitter, database acceptance time, recording reviewer, and frozen -ReviewPolicy context. PostgreSQL enforces unique task, source Review, and -Submission plus exact same-chain actor/policy lineage. - -Submitter `accepted_submission` contribution consumes FinalAcceptance and never -infers acceptance from `Review.decision`. Reviewer `completed_review` -contribution consumes Review and ReviewLease directly. - -## One Project Guide pipeline - -Project Guide is the single task and review authority. Task stamps one immutable -guide identity triplet when leaving draft. Submission copies the exact task or -prepared-revision context used for that attempt. The reviewer reads the context -stamped on the exact leased Submission and never performs a separate rebase. - -Project Guide activation receives an immutable per-project positive -`activation_sequence`. Version strings are never ordered. A superseded guide -retains its original sequence and provenance if intentionally reactivated. - -Publication and task screening both lock Project first. Publication then locks -candidate/current guide and every exact generation input in a declared stable -type/ID order. Task screening locks Project, Task, and the selected active guide -before stamping. This prevents activation from changing the active generation -between task context selection and commit. - -02A1 first makes every current setup writer share one Project-first fence. -02A3 then adds chronology, freezes the complete activated guide row except exact -lifecycle transitions, and explicitly introduces a no-write idempotent repeat -for the sole active candidate; current runtime rejects that repeat, so this is -additive behavior rather than a claimed preservation. Draft first activation -remains allowed and a superseded candidate remains denied. 02A4 finally stamps -the exact Task triplet. After the pure REV contracts and AUTH-PREP/custody merge, -02A2 adds the hidden prepared-authorized reactivation branch while -`project.guide.activate` remains unavailable. Its reviewed resource manifest -then gates AUTH-12 evaluator/cutover/activation. The bodyless command requires `If-Match` for -the exact current active guide ETag; missing precondition fails with 428 and a -stale/mismatched precondition fails with 412. Therefore a delayed retry cannot -silently replace a newer guide. - -Task guide ID, version, and activation sequence are nullable only together while -draft and complete thereafter. PostgreSQL validates that the triplet names one -same-project guide and rejects every valid-to-valid mutation after allocation. - -## Human Review revision preparation - -Controlled Project Guide rebase is rooted only in an immutable -`Review(needs_revision)` and its exact prior Submission. Checker-caused -`needs_revision` remains a distinct supported upstream remediation path anchored -to its final CheckerRun. It keeps the Task's existing locked context, creates no -Review/ReviewFinding/reviewer contribution, consumes no human ReviewPolicy -revision round/deadline, and does not use D6 close or human finding replay. -Corrected N+1 persists the unique server-derived -`remediation_source_checker_run_id` for that exact predecessor CheckerRun. - -`RevisionContextPreparation` is task-owned and directly references the exact -Review and prior Submission. It forms an immutable non-branching root/successor -chain with one head. The task participant owns guide resolution, Task Context, -and N+1 validation; REV invokes it through typed human-review facts without -importing task/project repositories. +Any participant failure rolls back all product effects. ART/provider I/O is +forbidden inside this transaction. + +### Wave 6 — Recovery, projection, and lifecycle control + +21. `11A` adds queue inspection and privileged queue/lease commands. +22. `11B` adds covered-project revision repair and obligation close. +23. `11C` adds resumable reconciliation and authority-invalidation jobs. +24. `11D` adds true-legacy closure and typed ART recovery delegation. +25. `12P1` adds deterministic review projection handling on shared outbox. +26. `12P2` adds artifact-reference reconciliation and projection rebuild. +27. `12P3` adds notifications, bounded admin reads, metrics, and drain facts. +28. `12A1` persists the single lifecycle release controller. +29. `12A2` composes REV/TASK/CHECKER mutation fences. +30. `12A3` composes CON writer/dispatcher/callback cutoff and drain fences. +31. `12A4` adds Operator transitions and crash-safe forward recovery. + +### Wave 7 — Conformance and release + +32. `13A` verifies exact merged dependency manifests and builds the drill + harness. +33. `13B` prepares current documentation and generated evidence without + exposing routes. +34. `13C` registers the coherent REV product routers and performs final HTTP, + database, job, storage, authorization, contribution, and recovery proof. + +`13C` is the sole product release. Earlier AUTH activations enable hidden +integrated proof only. + +## Authorization protocol + +Reads use request-scoped AUTH evaluation with the exact frozen contract. +Mutations prepare an opaque handle, lock AUTH authority first, lock REV and +participant facts in the command-specific published order, recompose the final +typed contract, consume once, stage bounded decision evidence, flush all +participants, and commit once at the route/service-command boundary. + +Unavailable actions fail closed. REV never changes catalogue availability. + +## Data and history invariants + +- One queue entry per admitted Submission. +- One active lease per queue entry and one active lease globally per reviewer. +- Immutable queue age; preference and lease timers are independent. +- One Review per Submission; every Review records the exact lease, packet, + reviewer, policy, checker admission, and artifact lineage. +- Every revised Submission points to its immediate predecessor; every later + Review points to the prior Review; findings/responses/resolutions append. +- Accept alone creates one FinalAcceptance, unique by Review, Submission, and + Task. +- Checker remediation and human revision sources are mutually exclusive. + +## External intersections + +### Cross-initiative consume/produce contract + +| Subsystem | It owns | It gives REV | It receives from REV | It never owns in this lifecycle | +|---|---|---|---|---| +| AUTH/XINT | ActorProfile/grants, action catalogue and availability, request-scoped evaluation/PREP, decision evidence, fixed service principals, activation | Closed typed REV action contracts and later authorized evaluation/consume results | Canonical REV resource composers, hidden behavior/manifests, and integration fixtures needed for matching XINT activation | Queue, lease, packet, Review, revision, FinalAcceptance, contribution, or product-router release | +| TASK/CHECKER | Project/Task/TaskAssignment/Submission and CheckerRun state, final current `allow_review`, typed task/submission transitions | Existing immutable Submission, final current CheckerRun facts, stamped policy/context lineage, typed caller-transaction participants | Admission/decision/revision commands containing exact locked REV facts | Review queue, reviewer routing/lease, Review judgment, findings, or contribution records | +| ART/XINT | Artifact bytes, verified binding/hash/membership identifiers, provider access, scratch/materialization, packet-byte authorization and delivery | Exact verified Submission binding facts, a contract-only membership port, and later lease-scoped packet materialization | Active REV lease and normalized immutable ReviewPacketManifest identifying what may be materialized | Admission meaning, queue/lease lifecycle, reviewer notes/findings, decisions, revisions, or contributions | +| REV | Queue/admission idempotency, routing/preference, ReviewLease, normalized packet-manifest semantics, immutable Review/findings/resolutions, human revision history, FinalAcceptance, orchestration and the single commit | N/A | N/A | AUTH grants/activation, artifact custody/provider I/O, upstream Submission/checker creation, ContributionRecord/award/fulfillment persistence | +| CON | ContributionPolicy/versions, ContributionRecord, award and fulfillment state, policy-freeze lookup, flush-only decision participant, shared dispatcher/release hooks | Existing canonical policy-version FK target, claim-time policy lookup result, and decision-time contribution/award staging | REV-owned lease reference facts; immutable Review source for reviewer work; accept-only FinalAcceptance source for submitter work; caller session/locked facts | ReviewLease persistence/transitions, reviewer selection, review decision, FinalAcceptance creation, task transition, authorization, or transaction commit | +| Future adjudication | Future policy and adjudication behavior under separate intent | Nothing in v0.1 | Traversable immutable Submission/Review/finding/response/resolution/FinalAcceptance lineage | Any v0.1 REV behavior | + +### Exact ownership flows ```text -Review(needs_revision) after reviewer CON operation --> append the Review-rooted initial preparation --> Task needs_revision -> REV audit/outbox -> review transaction commits once +Admission +TASK/CHECKER/ART own and supply: + immutable Submission + final current CheckerRun allow_review + verified binding facts +REV alone decides admission meaning and persists: + admission idempotency + ReviewQueueEntry + +Claim +AUTH prepares/consumes authority +CON looks up and returns the canonical reviewer ContributionPolicyVersion ID +REV alone persists and manages: + ReviewLease + policy-version FK + queue/lease transitions + packet freeze +ART performs no claim write and CON performs no lease write + +Packet read +REV supplies active lease + normalized ReviewPacketManifest +ART authorizes/materializes/verifies exact bytes +REV exposes the lease-bounded review context + +Decision +REV locks and validates the complete lifecycle state +REV appends Review/findings/resolutions and consumes lease/closes queue +CON stages exactly one reviewer contribution from Review +accept only: REV creates FinalAcceptance and TASK acceptance; + CON stages one submitter contribution from FinalAcceptance +needs_revision/reject: CON stages no submitter contribution +REV-owned caller commits every staged effect exactly once ``` -No contributor-readable human-review-caused `needs_revision` state may exist -without one preparation head. Unsafe context creates a blocked head rather than -a missing root. - -Preparation compares the prior Submission guide identity/sequence to the -currently active guide: - -- exact pair: `kept`; -- any different internally consistent active pair: `rebased` with `forward` or - `backward` direction; -- missing, incomplete, revoked, inconsistent, or unsafe pair: `blocked`. - -It freezes guide/source/task-execution policy context, not contribution policy. -Task Context returns the exact head. Submission N+1 acknowledges the head ID and -digest; a later guide activation does not silently change it. - -Human revision requires one immutable response for every unresolved blocking -ReviewFinding and later resolution during review, and returns prefer the prior -reviewer. Checker remediation shows contributor-safe checker messages/fixes, -creates no fake ReviewFinding response/resolution, preserves current guide/task -context, and returns to ordinary open routing after corrected checker admission. - -## Revision limits and deadlines - -The exact human Review revision-round counting source, deadline anchor, and -boundary remain a human-owned product decision before 09A1. They are not -inferred from checker retries, task SLA, current time, or archival examples. -Whatever values are approved freeze on the Review-rooted episode and use -database time. At exhaustion, Task remains `needs_revision` and assignment -active; context repair cannot bypass exhaustion, and only exact D6 close may -terminate the human revision episode. No synthetic reject is created. - -An exact final CheckerRun proves a checker-remediation task is not a rootless -human revision. Only state that claims human Review revision but has no -unambiguous originating Review/preparation is -`legacy_revision_context_unrecoverable`; migration never fabricates a Review. - -## Artifact boundary - -REV consumes typed ART capabilities only. It never receives ArtifactStore, -provider adapters/references, scratch paths, or raw repository access. - -- Queue admission uses stabilized submission/checker facts from exact ART-owned - cutover contracts. -- Claim creates a normalized immutable ReviewPacketManifest and item rows only - after ART defines exact packet membership relations. JSON/opaque ID sets are - prohibited. -- Context content reads require an active exact lease for the exact Submission. - History is metadata-only; prior, sibling, later, expired, and consumed leases - grant no byte access. -- v0.1 reviewer findings/notes and contributor responses are REV-owned records; - they use no ART candidate/finalize port and no evidence-upload ActionId. Any - future uploaded evidence requires separate approved REV-owned intent and - exact ART/AUTH owner work. -- Core Review/CON transactions copy stabilized digest lineage and make no ART - call. - -ART currently has no scheduled owner chunks for packet read or server-derived -Submission artifact digest. Those are hard blockers. REV may -record required capability shapes but must not invent ART chunk IDs or start ART -work. - -## Contribution and outbox boundary - -CON owns ContributionPolicyVersion persistence, TaskAssignment/ReviewLease -freezes, ContributionRecord and award persistence, delivery records, and the -two-operation flush-only decision participant. REV owns Review, -FinalAcceptance, lifecycle orchestration, shared audit/outbox staging, and the -single commit. - -Exact merged CON gates are consumed by chunk ID, PR, SHA, migration head, typed -symbol, and tests. `WS-CON-001-03B` precedes the ReviewLease policy FK; -`WS-CON-001-02A` and `02C` precede Review/FinalAcceptance shared outbox/audit -persistence; `WS-CON-001-06` precedes claim freeze; `WS-CON-001-03C` and `07` -precede the first canonical decision commit. Proposed status is not readiness. - -## Authorization boundary - -Reads use request-scoped AUTH `require`; protected mutations use AUTH's exact -merged prepared protocol. REV does not query grants, register actions, provision -service identities, integrate evaluators, or change availability. - -Before REV begins full lifecycle implementation, WS-XINT-003-02C installs the -complete unavailable REV catalogue and fixed-service matrix, and -WS-XINT-003-02D publishes the closed PREP/read integration contracts. REV hidden -chunks depend on that readiness, not on active actions. REV owns canonical -loaders/composers and proves behavior while the real AUTH kernel continues to -deny unavailable actions; matching XINT activation follows exact hidden proof. - -Every external AUTH edge must name the owner chunk and prove merged PR/SHA, -typed actor/action/resource contracts, static service rows where applicable, -and denial/race tests. Placeholder names remain fail-closed planning labels, -not executable dependencies. All actions remain unavailable until AUTH merges -the matching feature-gated activation after hidden behavior. - -AUTH activation does not release a product route. `WS-REV-001-13C` remains the -sole product-router registration and final HTTP proof after complete integrated -conformance. - -## Persistence and immutability - -`Submission` remains the only versioned submission entity. Submission and -Review predecessor chains are exact N-1 and non-branching. Human identity fields -use canonical human ActorProfile IDs after the AUTH foundation. Service/system -actors remain explicitly typed and cannot occupy contributor/reviewer fields. - -Evidence binding identity and scope are immutable. Pre-decision evidence uses -an immutable slot/binding relation; attachment to a finding/response is a -separately appended immutable relation in the Review or submission transaction. -No row described as immutable is later updated set-once. - -PostgreSQL owns uniqueness, XOR, same-chain, actor-kind, status/provenance, -immutability, and deferred cross-row integrity. Services validate for useful -errors but do not substitute for database enforcement. - -## Chunk strategy - -PLAN3 is merged historical boundary correction. The entire 02A family, -02B, and 02C are retired historical records and are never executable by REV. -03P is reconciled into WS-XINT-003-02 and is not independently executable. -That chunk requires current-main refresh, risk routing, plan review, and exact -owner evidence. Queue persistence follows separately in 03A. - -The detailed order is maintained in `CHUNK_MAP.md`. The important boundaries -are: - -- Upstream owners supply Project Guide, Task, Submission, checker, AUTH, ART, - and CON facts through typed, proven handoffs; REV reports gaps and stops. -- 03A queue/lease base schema and immutable linkage only; 03B normalized packet - manifest after ART contract. -- 04A immutable review-chain persistence; 04B FinalAcceptance/task linkage and - shared audit/outbox persistence primitives. -- 05A online checker admission; 05B server-selected reviewer/admin reads. - Historical admission classification/scan belongs to 11C reconciliation. -- 06A claim/freeze; 06B release/decline/preferences; 06C expiry/lazy recovery. -- 07A lease-bounded context and packet; 07B reviewer finding/note records with - no reviewer artifact upload or evidence action. -- 08 pure decision schemas, validation, and typed participant inputs only. -- 09A1 Review-rooted preparation schema; 09A2 preparation resolver and Task - Context; 09A3 revision-obligation response records only (no separate - artifact upload or evidence action); 09A4 internal prepared human N+1 plus - the exact source XOR that consumes the owner's immutable checker-remediation - `remediation_source_checker_run_id`; - 09A5 replacement-assignment transfer; 09B replay/resolution/return routing. -- 10 first hidden canonical Review/FinalAcceptance/CON transaction. -- 11A privileged queue/lease commands; 11B PM repair/D6 close; 11C - reconciliation persistence/jobs; 11D true-legacy close and ART delegation. -- 12P1 projection; 12P2 projection/artifact reconciliation jobs; 12P3 reads, - notifications, metrics, and drain observation. -- 12A1-12A4 separately build hidden release controller, REV fences, CON fences, - and Operator transition/drain recovery. -- 13A preflight/manifests/drill harness; 13B pre-release docs/generated preparation; - 13C sole product router registration and final HTTP proof. - -## Release control - -Persisted lifecycle phase controls whether already-registered commands may -execute. It does not dynamically unregister FastAPI routes or rewrite AUTH -action/static-service catalogues. Scheduler shutdown is an operational action; -database fences remain the correctness boundary. - -Product reads and mutation classes are defined separately. A disabled phase may -allow bounded readiness/administrative reads while denying product mutations. -Forward reactivation reuses static router registration and AUTH mappings after -phase, drain, service, and dependency checks pass. - -Checker needs-revision routing is one server-derived checker-completion class: -it is allowed with checker completion through `revision_cutover_fenced` and -denied from `admission_fenced`. It creates only CheckerRun-rooted task state, -audit, and outbox under the existing locked task context. Human Review -preparation is an internal consequence of leased `review.decision` and shares -that completion class; it is never an independently phase-enabled command. - -Chunk 13C is the only product router-registration and active-release-document -point. Earlier chunks keep routes absent, build hidden composition, add reusable -drill scenarios, and may update only planned/pre-release documentation. +The TASK/CHECKER/ART handoff contains identifiers and verified facts only. REV +owns admission meaning, not checker output or artifact custody. ART's admission +chain through its final checker-output routing and the corresponding XINT +activation must provide the exact current-main manifest before `05A` starts. +REV-03B defines normalized packet semantics without waiting for ART-07A runtime; +ART-07A later consumes the lease/manifest and materializes bytes, and REV-07A +consumes that materialization. This ordering avoids a circular dependency. + +### Current cross-plan gates + +Owner plans are dependency evidence, not authority for REV to edit their work. +Some AUTH/XINT/CON status prose predates current main, so every consuming child +must recheck the implementation and signed merge history rather than trusting a +stale `Proposed` or `Active` label. + +| Required owner output | Producer | Current-main state at PLAN4 | REV consumer | +|---|---|---|---| +| Closed typed REV authorization/PREP schemas, actions unavailable | XINT-003-02D | Merged in PR #257 | Hidden REV services; later positive activation remains XINT-owned | +| Canonical reviewer ContributionPolicyVersion persistence target | CON-03B | Not evidenced merged; owner plan is stale and must be refreshed by CON | 03A2 | +| Reviewer-packet membership identifier/port contract, with no REV runtime dependency | ART-owned contract-only precursor to ART-07A | Missing exact published contract; report to ART owner | 03B | +| Shared lifecycle-audit participant | CON-02C | Not evidenced merged; generic audit persistence alone is insufficient | 04B | +| Final Submission/CheckerRun/verified-binding admission manifest | ART checker chain through ART-06B and XINT-06B | Not evidenced complete | 05A | +| Claim-time reviewer-policy lookup result used by REV to freeze its lease FK | CON-06 | Future after REV lease schema and CON prerequisites | 06A | +| Exact reviewer packet materialization | ART-07A, activated by XINT-002-07A | Future after merged REV lease/manifest | 07A | +| Atomic contribution/award decision participant | CON-07 | Future after REV-04B/09B and CON prerequisites | 10 | +| Shared dispatcher/handler registry | CON-02B | Not evidenced merged | 12P1 | +| CON cutoff/drain hooks | CON-03D/08A/08B/10B/11 as refreshed by CON | Future | 12A3 and 13C | + +The missing ART contract-only precursor is an ART-owner gap, not a new REV +chunk. REV-03B cannot start until ART publishes it. This explicit precursor +breaks the former ART-07A ↔ REV-03B cycle: ART publishes types first, REV +persists the semantic manifest, then ART-07A materializes it. + +### REV to CON + +REV invokes ordered typed operations. Every Review gets reviewer +`completed_review`; accept additionally gets submitter `accepted_submission` +from FinalAcceptance. CON owns policy, records, awards, and fulfillment. +REV exclusively owns ReviewLease persistence and lifecycle. The lease stores a +non-null immutable reference to CON's canonical reviewer +ContributionPolicyVersion; it does not duplicate policy fields or own policy +selection. CON never creates, updates, closes, or authorizes a lease. CON-03C +may consume merged REV Review/FinalAcceptance/ReviewLease schema, and REV-10 +waits for CON-07's mandatory flush-only participant. + +## Alternatives rejected + +- Waiting for all ART/CON work before any REV persistence. +- Building foreign behavior inside REV to unblock integration. +- One giant schema or decision PR. +- Public routes before recovery and lifecycle fences. +- A separate SubmissionVersion, artifact store, authorization protocol, audit + ledger, outbox, or contribution writer. +- Review evidence uploads in v0.1. ## Verification strategy -Every runtime chunk must run focused tests, Ruff, real-PostgreSQL isolated full -suite at the repository 78 percent floor, and at least 90 percent coverage for -materially changed backend subsystems. Migration chunks additionally prove one -head, preflight, upgrade, downgrade/re-upgrade where safe, protected-row refusal, -transactional failure behavior, and direct-SQL constraints. - -Every chunk runs stale Workstream/AUTH/ART/REV wording scans applicable on -current main, Markdown links, `git diff --check`, agent gates, and required -internal reviewer fanout. Test changes may not weaken, -skip, or rewrite existing checker-caused revision coverage. +Each child freezes exact commands at start. Required proof includes Ruff, +typecheck where configured, focused unit/service/API tests, PostgreSQL migration +and direct-SQL constraints, independent-session race tests, fault injection, +architecture scans, stale wording/link checks, at least 90 percent coverage for +materially changed subsystems, and GitHub-hosted repository coverage at or +above 78 percent. Full local suite runs are not required. ## Stop rule -Complete PLAN3 and stop. No runtime child starts automatically, and no retired 02A-family, -02B, or 02C contract may be revived as REV work. +This planning refresh starts no runtime child. After review and human approval, +start only `WS-REV-001-03A1`. Stop after its PR; do not begin 03A2 +automatically. diff --git a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/REVIEW_LOG.md b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/REVIEW_LOG.md index 877ce163a..5ff5873c4 100644 --- a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/REVIEW_LOG.md +++ b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/REVIEW_LOG.md @@ -1,5 +1,15 @@ # Internal Plan Review Log: WS-REV-001 +## WS-REV-001-PLAN4 Current-Main End-To-End Refresh - 2026-08-03 + +Architecture passed the full revised sequence and confirmed that 03A1 is a +safe REV-only first runtime child. QA/product and security/docs/CI found the +same stale background-execution phrase through the required authorization +wording scan and no lifecycle, cardinality, boundary, or chunk-order defect. +The phrase was replaced with current background-job terminology; every required +deterministic check then passed. Evidence is recorded in +`reviews/WS-REV-001-PLAN4-internal-review-evidence.md`. + ## WS-REV-001-PLAN3 External Review Repair - 2026-07-22 CodeRabbit and CI identified four valid documentation/evidence issues: retired diff --git a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/RISKS.md b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/RISKS.md index 3ce275342..328dddb9b 100644 --- a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/RISKS.md +++ b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/RISKS.md @@ -1,72 +1,29 @@ # Risks: WS-REV-001 Review And Revision Lifecycle -Duplicate policy models/writers are prohibited. Active-guide policy history is -protected by append-only versions, a draft-only final PREP guard, and database -update/delete refusal proof in XINT-003-02. - | ID | Risk | Severity | Mitigation | |---|---|---:|---| -| R0 | REV converts a consumed upstream dependency into feature ownership and edits Project Guide, Task intake, Checker, AUTH, ART, or CON internals | Critical | REV starts at final current `allow_review`; record missing typed owner contracts and stop. Boundary review blocks any REV chunk that edits upstream behavior rather than a declared participant owned by that subsystem. | - -Rows R50-R56 below are retained only as historical evidence of the superseded -02A/02B/02C plan. D28 and PLAN3 prohibit using them as REV implementation work. -| R1 | Parallel AUTH/ART changes make a planned interface stale | High | Every runtime chunk starts with a main-SHA dependency refresh and plan review; consume only merged contracts. | -| R2 | Revised reference activates Flow Node against locked AWS policy | High | Correct normative wording in the contract-adoption chunk before runtime implementation. | -| R3 | Duplicate `SubmissionVersion` fragments identity and history | High | Extend existing `Submission`; migration and architecture tests prohibit a duplicate table. | -| R4 | Reviewer claim or decision bypasses current authorization | Critical | Require transaction-aware centralized decisions, canonical resource loaders, revocation races, and security review. | -| R5 | Remote storage calls under database locks cause contention or ambiguous commits | High | Preflight outside locks, stabilize binding facts inside transactions, and project only post-commit. | -| R6 | Artifact outage is misclassified as contributor fault | Critical | Stable 503/integrity errors, no Review/task adverse state, outage audit, and failure-mode tests. | -| R7 | Queue and lease races create duplicate work or multiple reviewer capacity | Critical | PostgreSQL partial uniqueness, targeted row locks, database time, and real concurrent tests. | -| R8 | Revision replay mutates prior findings or misses blocking work | High | Immutable response/resolution rows, database uniqueness, full unresolved-finding validation, and chain tests. | -| R9 | Legacy revision policy fabricates `reject` | High | D6 plus a human decision on limit/deadline behavior before policy alignment. | -| R10 | A canonical Review or a FinalAcceptance created for an accept decision commits without required contributions/awards | Critical | Permit only schemas/pure validation before the CON participant; REV-10 creates the first Review-committing transaction with the mandatory flush-only participant and rolls back the entire unit on any failure. | -| R11 | Shared audit or outbox is duplicated badly | High | Freeze and merge the shared outbox contract before chunk 04; block rather than create a review-private replacement. | -| R12 | Reviewer endpoint leaks queue depth or enables cherry-picking | High | Server selects one offer; separate admin inspection; authorization and privacy tests. | -| R13 | Review snapshot becomes a competing source of truth | High | PostgreSQL-only canonical writes, deterministic projection, reauthorization on search, rebuild tests. | -| R14 | Large cross-domain PRs become unreviewable | High | Separate persistence, routing, leases, evidence, decisions, replay, recovery, projection, and proof chunks. | -| R15 | Existing docs continue to define conflicting finding/revision semantics | Medium | Contract-adoption and final documentation chunks update docs, templates, glossary, and reference precedence. | -| R16 | Migration numbering collides with parallel agents | High | Allocate migration identifiers only when the chunk starts from current main; never pre-reserve a number in this plan. | -| R17 | Operational timers rely on Celery delivery or web-server time for correctness | High | Database-time transitions, lazy recovery on requests, idempotent sweeps, and reconciliation. | -| R18 | Finding text or artifact details leak into logs/metrics | High | Bounded audit projections, no raw content/provider secrets, cardinality controls, and security review. | -| R19 | Half-built public routes expose claims or private context before recovery and operations are coherent | Critical | Keep lifecycle routers absent through 12A; AUTH activates exact actions only after hidden behavior, and 13 exposes the complete product set after joint readiness. | -| R20 | Cross-domain transactions deadlock under claim, decision, revocation, expiry, or reconciliation races | Critical | Publish an exact AUTH-first command-specific lock order, sort same-type rows, use bounded database-classified retries, and test both permutations with independent Postgres sessions. | -| R21 | Historical submissions are indiscriminately queued without current checker/artifact proof | High | No queue backfill in schema migration; later audited admission is limited to unambiguous latest eligible rows and fails closed otherwise. | -| R22 | Review duplicates task submission/checker/audit/outbox/job mechanics or creates repository cycles | High | Use caller-transaction task participants, typed checker admission/context ports, the shared audit ledger/dispatcher, canonical hashing, one explicit composition assembly, and existing Celery/session utilities with import-boundary tests. | -| R23 | Rebased submissions pass service checks but fail or drift at checker, queue, preparation, or contribution constraints | Critical | Replace task-equality FKs as one reviewed migration, bind checkers to Submission context, root each non-branching preparation episode in its exact human Review, persist the admitting CheckerRun, preserve distinct checker remediation context, and derive WS-CON only from constrained immutable lineage. | -| R24 | Invalid preparation or truly rootless human needs_revision state strands work indefinitely or tempts synthetic history repair | High | Keep exact CheckerRun remediation distinct from legacy, provide reason-bound successor repair for valid human episodes, fail closed on ambiguous human roots, and reserve Operator evidence-linked closure for genuinely unrecoverable history. | -| R25 | UUID-shaped external, legacy, or service identity is stored as a human reviewer/submitter | Critical | Require canonical `ActorProfile.id` FKs, human-kind and current-status revalidation, explicit actor-reference kinds in audit, and direct-SQL/cross-kind tests. | -| R26 | Forward/backward guide rebase silently changes compensation | Critical | Keep compensation outside preparation/Submission/checker context; freeze submitter terms on TaskAssignment and reviewer terms per ReviewLease; test both rebase directions. | -| R27 | Contribution lineage trusts caller `package_hash` or invents a parallel digest | Critical | Require the ART submission/checker cutover to persist server-derived verified `Submission.artifact_hash`; copy it to `ContributionRecord.artifact_hash` without an ART call. | -| R28 | Review routes release without the complete CON participant or from a stale manifest | Critical | Consume the exact merged core CON readiness manifest; CON owns its routes, while REV-13 exposes only REV surfaces after all required actions are AUTH-active. | -| R29 | AUTH authority-loss reassignment strands a Review-rooted revision episode or rewrites source attribution | Critical | Preserve reviewed-assignment lineage, append one atomic preparation successor for the replacement target assignment, deny the old contributor, and race replacement against repair/submission. | -| R30 | A hidden preparation migration blocks the still-public legacy revision route before coherent activation | Critical | REV-09A4 installs, backfills, validates, and enforces the hidden Submission source-XOR rule while `submission.create` remains unavailable. Amended AUTH-14 owns only public request acknowledgement, authorization cutover, and activation; REV-13 verifies and exposes the merged cutover and proves no raw IntegrityError. | -| R31 | Joint activation or shutdown partially fences review while task replacement or compensation delivery keeps mutating | Critical | Land one hidden persisted release controller through 12A1-12A4 while 12A remains non-executable, require shared/exclusive PostgreSQL advisory-lock fences across every named mutation class, capture an immutable CON-owned fulfillment-obligation cutoff after completion commands drain, allow only pre-cutoff completion work during delivery drain, resume from durable phase after crash, and use forward recovery rather than downgrade after protected rows exist. | -| R32 | AUTH dependency teardown regresses and silently commits feature-owned review mutations | Critical | Preserve merged AUTH-08 rollback-only teardown and require the request route or service command to own the explicit commit plus rollback fault injection in every consumer chunk. | -| R33 | Authorization decision-evidence persistence failure regresses to an unstructured 500 | High | Preserve merged AUTH-08 typed retryable 503 mapping and test that no review mutation or partial evidence survives. | -| R34 | A later AUTH or REV route change leaves canonical actor verification timestamps stale | Medium | Preserve AUTH-08's route-owned database-time semantics and successful/denied/failed existing-actor regression proof for both canonical timestamps. | -| R35 | REV or ART becomes a second action-availability writer | Critical | Enforce registration -> hidden behavior -> AUTH activation -> joint release; scan every chunk for feature-owned activation wording and verify separate AUTH manifests. | -| R36 | Hard-coded catalogue totals omit independently added actions | High | Treat 57/9/48 only as AUTH-08 history, 65/9/56 only as AUTH-09A history, 65/10/55 only as AUTH-09B history, and 65/12/53 only as AUTH-09C history; current trusted main after AUTH-09D-A is 65/15/50. Derive exact counts/SHA at each registration and activation gate, with the four REV proposals and ART binding action separately inventoried. | -| R37 | A generic service identity or human Operator executes protected review jobs | Critical | Use distinct fixed service ActorProfiles/static rows through AUTH-09E and prove cross-service plus human/service denial. | -| R38 | Reviewer revocation removes submitter/adjudicator authority or vice versa | Critical | Consume exact role-specific invalidation; REV mutates only review preference/lease/queue state and tests every independent-revocation direction. | -| R39 | Evidence finalization partially binds bytes after authority or lineage drift | Critical | Provider I/O precedes AUTH -> REV -> ART database finalization; one final AUTH evaluation; only an ART orphan candidate may survive failure. | -| R40 | Optional contribution-evidence storage blocks canonical Review or awards | High | Keep it outside core readiness as a separate asynchronous projection whose outage cannot change canonical truth. | -| R41 | Archival `closed/review_rejected` introduces a fourth terminal token | High | Active contract uses human `rejected` and administrative `cancelled` with bounded reasons; chunk 02 adds no undocumented `closed` status. | -| R42 | REV-07 starts before ART owns the missing review-evidence capability | Critical | Treat the unscheduled `WS-ART-001-REV-EVIDENCE` owner chunk as a hard external gate; REV neither implements ART internals nor substitutes v1/provider APIs. | -| R43 | REV assumes packet-read or `Submission.artifact_hash` from ART contracts that do not define them | Critical | Require separately approved ART/task-owner amendments and exact merged SHAs before REV-07/10; existing artifact-set context and caller `package_hash` do not satisfy either gate. | -| R44 | Submitter contribution is inferred directly from `Review.decision` and becomes coupled to REV semantics | Critical | When an immutable Review has decision `accept`, create one immutable REV-owned FinalAcceptance and require `accepted_submission.source_final_acceptance_id`; direct Review inference fails validation. | -| R45 | Duplicate or crossed FinalAcceptance recognizes the wrong task, Submission, submitter, reviewer, or policy context | Critical | Enforce unique task/Review/Submission plus composite same-chain FKs, immutable ReviewPolicy context, canonical human actors, and direct-SQL/concurrency negatives. | -| R46 | CON commits or stages shared audit/outbox independently from the REV request | Critical | CON flushes only contribution/award rows and returns typed audit/outbox inputs; REV stages shared records and the request route or service command owns one commit, with fault injection after every stage. | -| R47 | Future adjudication concerns leak policy, states, actions, or readiness dependencies into v0.1 | High | Keep only dormant role/interface compatibility wording; add no adjudication behavior or dependency, and prove the shipping path is Review -> FinalAcceptance -> ContributionRecord. | -| R48 | A prepared authority handle is replayed or substituted across sessions, actions, actors, or requests | Critical | REV recomposes final facts, then AUTH validates the opaque handle's exact bindings/current authority, consumes once, evaluates once, and stages evidence; prove rejected pre-consumption substitution preserves the legitimate handle for one later exact use, while stale/already-consumed and concurrent duplicate attempts remain invalid and stage no new state; separately prove evaluated denial rollback, clean AUTH evidence restaging, and restaging-failure atomicity. | -| R49 | Parallel AUTH and REV chunks both rename contributor fields or own the same migration | Critical | REV-02 waits for a separately reviewed and merged AUTH-owned schema-only contributor-field foundation; amended full AUTH-13/14 product cutovers remain downstream of REV-09A; allocate REV migrations only from then-current main and prohibit parallel schema edits. | -| R50 | Parent REV-02 or its original 02A child combines too many L1 database boundaries for reliable review | Critical | Parent 02 remains non-executable. Parent 02A is also split: 02A1 owns the Project/setup fence, 02A3 guide chronology, and 02A4 Task triplet screening; 02B and 02C retain their separate boundaries. Each executable child has separate review, merge memory, and explicit start. | -| R51 | Review preference or lease duration is invented from unrelated SLA data | High | Require two explicit positive human-approved defaults before 02B; never infer either from `sla_hours`, current timestamps, or archival examples. | -| R52 | Dormant terminal schema accidentally enables a human outcome without Review | Critical | 02B defines storage/constants only, adds no terminal transition edges or reject Review FK, and proves checker/limit/deadline paths create no terminal Task/Assignment or downstream effect. | -| R53 | Finalized Submission immutability blocks later ART-owned verified digest publication | High | 02C defines the finalization guard with an explicit future set-once `artifact_hash` exception owned by the approved ART/task amendment; it never permits overwrite or caller digest promotion. | -| R54 | Supported checker-caused revision is misclassified as legacy or silently expanded into human rebase policy because no Review exists | Critical | Preserve its exact CheckerRun-rooted task-context path, exclude human preparation/limits/D6, preserve the existing checker regression, and create no synthetic Review. | -| R55 | Concurrent submissions consume N and N+1 without an intervening revision origin | Critical | Persist unique immutable `remediation_source_checker_run_id` for checker N+1 and the preparation ID for human N+1; lock/revalidate the exact source and enforce the final XOR/direct-SQL constraints. Loser replays exactly or conflicts; N+2 requires a later committed human Review/preparation or final needs-revision CheckerRun. | -| R56 | Superseded guide reactivation ships under legacy role checks or an already-active incomplete AUTH evaluator | Critical | 02A keeps public denial; 02A2 builds hidden prepared/If-Match behavior while the action is unavailable, then its full manifest gates AUTH-12 cutover/activation. | -| R57 | Persisted release phase is mistaken for router/action/service deactivation | Critical | Keep static routing and AUTH membership owner-controlled; deny execution through mandatory phase fences, separate read/mutation classes and scheduler runbooks, and prove crash-resumable forward transitions. | -| R58 | Checker completion is allowed during cutover but checker needs-revision routing is phase-denied | Critical | Classify checker needs-revision routing with checker completion through `revision_cutover_fenced`; deny both from admission fencing, and test atomic rollback in every phase. | -| R59 | AUTH/ART/CON prose placeholders create circular or fictional dependencies | Critical | Require exact owner chunk ID, merged PR/SHA, migration head, typed symbol/manifest, and tests; distinguish contract amendment from later runtime activation/cutover. | -| R60 | Oversized parent contract hides multiple L1 migrations, commands, services, and release boundaries | High | L1 preimplementation review is a hard gate. Treat rejected parent 02A and the other declared parents as non-executable, then implement only the reviewed unique child sequence in CHUNK_MAP. | +| R1 | REV implements missing AUTH, ART, TASK, CHECKER, or CON behavior | Critical | Typed ports only; owner evidence gate; architecture review on every integration child. | +| R2 | Historical planning is mistaken for live authority | High | PLAN4, live chunk map, and active spec control; historical files are explicitly non-executable. | +| R3 | Duplicate Submission identity or artifact store appears | Critical | Reuse existing Submission and ART ports; architecture scans prohibit replacements. | +| R4 | Queue/lease races create duplicate work or multiple leases | Critical | Partial uniqueness, database time, row locks, and two-order PostgreSQL races. | +| R5 | Self-review or stale authority commits | Critical | Exact AUTH 02D contracts, PREP revalidation, locked final facts, revocation races. | +| R6 | Reviewer queue leaks backlog or enables cherry-picking | High | Active lease/one server-selected offer/none; separate privileged inspection. | +| R7 | Artifact outage becomes contributor fault | Critical | No adverse transition; typed unavailable/integrity results; recovery audit. | +| R8 | Remote I/O occurs under decision locks | Critical | Materialize before/after transaction; canonical decision uses IDs/digests only. | +| R9 | Review or revision history is rewritten or forks | Critical | Append-only rows, predecessor uniqueness, non-branching episode heads, direct-SQL proof. | +| R10 | Checker remediation is confused with human revision | Critical | Source XOR, separate participants, no synthetic Review/finding/contribution. | +| R11 | Decision partially commits without contribution effects | Critical | First Review commit only in chunk 10 with mandatory CON participant and fault injection. | +| R12 | Submitter contribution is inferred directly from Review | Critical | Accept-only REV FinalAcceptance is the sole CON submitter source. | +| R13 | Contribution terms rebase with guide context | Critical | Assignment and lease freezes remain independent of guide/revision context. | +| R14 | Public routes expose incomplete lifecycle | Critical | Routes remain absent until 13C; AUTH activation is hidden proof, not product release. | +| R15 | Timers or recovery depend on background-job delivery | High | Database-time truth, lazy recovery, idempotent sweeps, reconciliation. | +| R16 | Cross-domain lock order deadlocks | Critical | Command-specific published order, stable ID sorting, both-order tests. | +| R17 | Projection becomes canonical or blocks Review | High | Shared outbox, post-commit deterministic projection, rebuildable state. | +| R18 | Review text or identifiers leak through logs/metrics | High | Bounded audit fields, redaction, no bytes/digests/provider locators in metrics. | +| R19 | Far-future contracts freeze stale filenames/migrations | High | Skeletons only; exact contract refreshed at each start from current main. | +| R20 | Human revision limit/deadline semantics are guessed | Critical | Explicit human decision before 09A1; no inference from checker retries or SLA. | +| R21 | Full local testing consumes excessive time/resources | Medium | Focused local proof only; GitHub Actions runs full suite and coverage. | +| R22 | REV migrates its leases before CON's canonical policy-version FK target exists | Critical | REV retains complete lease ownership, but orders 03A2 after merged CON-03B so its non-null immutable FK is valid; no placeholder policy model or nullable retrofit. | +| R23 | REV packet semantics and ART packet materialization form a circular dependency | Critical | ART first publishes a contract-only membership port with no REV runtime dependency; REV-03B owns the normalized manifest; ART-07A consumes the merged lease/manifest; REV-07A consumes ART materialization. | +| R24 | Hidden REV tests imply an unavailable AUTH action can succeed | Critical | Before XINT activation, prove feature rules and unavailable denial separately; positive PREP/evaluator proof belongs to the matching XINT activation. | +| R25 | A stale owner-plan status is mistaken for merged capability | Critical | Each consumer child verifies signed merge history and exact runtime symbols; REV documents and escalates owner gaps without editing their plans. | diff --git a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/STATUS.md b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/STATUS.md index 6b29b2d3c..d51c2cb20 100644 --- a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/STATUS.md +++ b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/STATUS.md @@ -1,128 +1,45 @@ # Status: WS-REV-001 Review And Revision Lifecycle -WS-XINT-003-01 supersedes obsolete process gates for future REV-AUTH work and -reconciles REV-03P with AUTH-12D2. No runtime action is activated. - ## Current status -On 2026-07-22 a complete reread of the canonical Markdown and PDF specification -identified that the 02A family crossed the REV ownership boundary. REV begins -only when the current finalized checker result is `allow_review`; it consumes -the existing Submission and the same submitted/verified artifact set. Project -Guide setup, activation, Task intake, and upstream publication fencing belong to -their owning subsystems. REV reports gaps in those handoffs and does not repair -them. The attempted 02A1 runtime candidate was reverted in full. - -`WS-REV-001-PLAN3` is merged historical planning. It retires -02A/02A1/02A2/02A3/02A4/02B/02C as REV implementation authorization. The first -future policy work is the reconciled WS-XINT-003-02 writer cutover; 03P is not -an independent implementation path. Work starts through the repository's -ordinary intent/plan/bounded-change loop after an explicit user request. - -The historical text below records the superseded PLAN2/02A state and is not -current implementation authority. Trusted main at that time was `44f2467c`, which additionally -includes ART admission foundation PR #154 after REV PLAN2 PR #150, AUTH-09D-B -PR #152, and `WS-AUTH-001-CONTRIBUTOR-FOUNDATION` PR #153. The user explicitly -started parent 02A on 2026-07-19. L1 preimplementation review returned FAIL -before runtime edits because the contract combined three separately reviewable -database/concurrency boundaries. That attempted split is now retired. - -## Historical dependency snapshot - -Current trusted main is `14fa4316f7d984f2176657bfafd2a2dae56f944e` -with sole Alembic head `0033_authorization_read_rate_control`. The bullets below describe the -older PLAN2 snapshot and are not current runtime proof. - -Generated loop state naming retired 02A1 is historical and is not an -implementation gate. The canonical next cross-initiative sequence is the -WS-XINT-003 chunk map. - -- Single Alembic head: `0028_artifact_admission`. -- TaskAssignment and Submission expose canonical `contributor_id` with - ActorProfile foreign keys and human-kind database guards. -- All 24 REV lifecycle action dependencies remain unavailable. -- AUTH-09D-A merged through PR #148 at - `99ae4c963e53f317175dcb308b9e47c93ccf19ed` with reviewed head - `9c5ef8a1feffd6324acfd947e67042921955320b`. Its ActorProfile lifecycle - status/provenance and direct-SQL guards are trusted dependencies. -- The contributor foundation merged through PR #153 at `8d5eb15b` from reviewed - head `6a70b33f`, with migration `0027_contributor_foundation`, final reviewed - code candidate `0ca5a632`, and successful Backend, Agent Gates, and CodeRabbit - checks. Its field clean cut, human lineage, and active-human transaction - revalidation satisfy the former external 02A gate. -- ART admission/put-attempt foundation merged through PR #154 at `44f2467c` - from final head `c93f1a24`, advancing the sole migration head to - `0028_artifact_admission`. It changes no Project/setup writer and does not - supply review packet-read, review-evidence candidate/finalize, or - server-derived Submission artifact-digest capability. -- CON-01 merged its specification. CON runtime chunks 02A onward remain - proposed on trusted main. Any unmerged CON migration must rebase from the - then-current head before it is consumable. -- Sibling AUTH/ART/CON status files contain stale post-merge wording. REV records - actual merge facts but does not edit owner initiative memory. - -## Superseded PLAN2/02A record - -This section is retained solely as historical evidence. Every ownership or -start statement in it is void under D28 and PLAN3. - -- Parent 02A is a non-runtime split record. 02A1 owns the complete shared - Project/setup writer fence, 02A3 owns guide chronology/canonical approval, and - 02A4 owns Task triplet screening. -- Current runtime rejects an already-active activation candidate. 02A3 names - no-write active-repeat success as explicit additive behavior rather than - incorrectly describing it as existing behavior. -- Proposed 02A2 owns prepared-authorized, `If-Match` protected superseded-guide - reactivation after AUTH-PREP and AUTH-12. This preserves backward rebase - without broadening the legacy public route. -- Existing oversized parent contracts are non-executable split records. Only - the children in `CHUNK_MAP.md` may later receive implementation contracts. -- Chunk 08 is pure contract/validation only. Chunk 10 remains the first canonical - Review/FinalAcceptance/CON transaction. -- Controlled revision preparation remains task-owned and rooted in an exact - human `Review(needs_revision)`. Checker-caused `needs_revision` remains a - distinct supported CheckerRun path, keeps existing task context, and never - fabricates Review/finding/reviewer contribution or consumes human rebase/D6. -- Limit/deadline exhaustion cannot be repaired around; only exact D6 close may - terminate that frozen human revision episode. -- Persisted release phase denies command execution. It does not unregister - routers, change AUTH action availability/static membership, or replace - scheduler operations. - -## Canonical lifecycle - -- Every valid reviewer decision appends immutable Review history; findings and - later resolutions are also immutable. -- Every decision creates reviewer `completed_review` through CON. -- Accept alone creates immutable FinalAcceptance, accepts Task/completes exact - assignment, and creates submitter `accepted_submission` from that fact. -- Needs revision creates no FinalAcceptance/submitter contribution and atomically - appends the Review-rooted task-owned initial preparation. -- Reject blocks the exact reviewed Submission assignment and rejects Task; it - creates no FinalAcceptance/submitter contribution. -- Checker needs revision atomically records the final CheckerRun transition with - the Task's existing locked context and creates no Review, preparation, or CON - record. Corrected N+1 persists the unique server-derived - `remediation_source_checker_run_id`; later human N+1 instead persists its - preparation ID, never both. -- Adjudication and reputation mutation remain deferred and unimplemented. - -## Human-owned gates - -- Implement policy work only through reconciled WS-XINT-003-02 after its - current-main contract review and an explicit user request. -- Start 03A only after 03P and after its current-main refresh proves every exact - `allow_review`, Submission, artifact, and reviewer owner handoff. -- Exact human Review revision-round counting, deadline anchor, and boundary - before 09A1; checker retries are excluded unless a separate product/ADR - amendment is explicitly approved. -- Exact merged AUTH-14 contract amendment before 09A4 must leave REV ownership - of Submission revision-source columns/constraints intact and limit AUTH to - public request acknowledgement, authorization cutover, and activation. -- Every later external owner dependency and child start as listed in the map. - -## Stop condition - -PLAN3 is complete historical boundary correction. Do not resume any 02A-family, -02B, or 02C chunk. Future runtime work follows the current XINT-003 map and an -explicit user request. +PLAN4 end-to-end planning refresh is complete and internally reviewed from +current main `3479ee71`. No REV runtime module, table, route, action activation, +or product behavior exists. + +AUTH `WS-XINT-003-02A` through `02D` are merged. REV now has stable policy +lineage/mutation, complete unavailable action/principal registration, and typed +authorization contract models for every approved lifecycle action. + +## Boundary + +REV starts from an existing immutable Submission plus a durable final current +CheckerRun `allow_review` and exact verified ART binding facts. It owns queue, +lease, packet semantics, Review history, revision replay, FinalAcceptance, +recovery, projection, release control, and lifecycle orchestration. + +REV does not own Project/Task/Submission/Checker/AUTH/ART/CON internals. + +## Parallel safety + +- REV-03A1 queue/admission-idempotency persistence can begin after PLAN4 + approval without waiting for ART or CON runtime work. Later persistence + children wait for their named schema/port gates. +- ART gates only manifest/admission/packet consumers that need its final typed + facts; REV does not wait for ART-07A runtime to define packet semantics. +- REV owns 03A2 completely; CON-03B must merely exist first as its mandatory + policy-version FK target. CON-06 later supplies claim-time policy lookup; + CON-07 later supplies canonical decision contribution composition. +- ART must publish a contract-only packet-membership port before REV-03B. ART- + 07A then consumes the merged REV lease/manifest; this removes the former + circular gate. +- AUTH/XINT/CON planning status labels are partly stale. Future REV children + must verify exact current-main code and signed merges; REV will report those + owner-doc gaps rather than edit foreign plans. +- Missing external behavior is reported to its owner and never implemented in + REV. + +## Next step + +Await human approval. Then refresh and implement only `WS-REV-001-03A1` +queue/admission-idempotency persistence from then-current main. Stop before +03A2. diff --git a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-03-review-queue-lease-persistence.md b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-03-review-queue-lease-persistence.md index 69807154c..2e7989e75 100644 --- a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-03-review-queue-lease-persistence.md +++ b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-03-review-queue-lease-persistence.md @@ -7,8 +7,10 @@ parent. ## Children -- `WS-REV-001-03A` owns queue/lease base persistence and the exact merged - `WS-CON-001-03B` ContributionPolicyVersion FK. +- `WS-REV-001-03A` is a non-executable split record. `03A1` owns queue and + admission-idempotency persistence; `03A2` owns lease and preference + persistence. CON policy freeze is a later claim-time typed handoff and is not + a prerequisite for either base child. - `WS-REV-001-03B` is the sole owner of the normalized immutable ReviewPacketManifest/item models, schema, migration, repository contract, and persistence tests. It starts only after ART merges an exact packet-membership diff --git a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-03A-queue-lease-base-persistence.md b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-03A-queue-lease-base-persistence.md index e890a4c63..94a15ca20 100644 --- a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-03A-queue-lease-base-persistence.md +++ b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-03A-queue-lease-base-persistence.md @@ -1,84 +1,17 @@ -# Chunk Contract: WS-REV-001-03A - Queue And Lease Base Persistence +# Chunk Contract: WS-REV-001-03A — Queue And Lease Persistence Split ## Status -Proposed only. Not started and not implementation authorization. After 03P -merges, refresh/review this contract on exact current main and start it only -through a signed `Loop Memory Explicit Event`. +Non-executable parent split record. PLAN4 replaces the former combined +queue/lease child with 03A1 and 03A2. -## Parent +## Children -`WS-REV-001-03` Review Queue And Lease Persistence. +- `WS-REV-001-03A1` owns queue and admission-idempotency persistence only. +- `WS-REV-001-03A2` owns lease and preference persistence only. -## Goal +No implementation or PR may use this parent ID. -Persist the smallest REV-owned queue-entry and lease foundation for an existing -finalized Submission whose durable final current checker outcome is exactly -`allow_review`. +## Stop condition -## Risk - -L1: concurrent admission, reviewer authorization, immutable intake identity, -and audit lineage. - -## Required owner handoffs before start - -- Submission owner: finalized Submission identity, Task/contributor lineage, - immediate predecessor semantics, and submitted artifact membership. -- Checker owner: durable final/current status and exact `allow_review` outcome. -- ART owner: typed read access to the same submitted/verified artifact set; - REV does not copy, finalize, or mutate artifact custody. -- AUTH owner: canonical reviewer ActorProfile and permission facts. -Each handoff must be named by merged owner chunk, PR/SHA, typed symbol or -manifest, migration head where relevant, and focused proof. Any gap is reported -to the human and implemented by its owner, never by REV. - -## Allowed files - -To be fixed during the required current-main refresh. They may include only -REV-owned queue/lease models, migration, repository/service ports, focused -tests, and this initiative's evidence and merge-intent files. - -## Not allowed - -- Project Guide setup, publication, activation, chronology, or reactivation. -- Task intake/context stamping, Submission creation/finalization, CheckerRun - production, artifact custody, AUTH policy, or CON contribution implementation. -- Review decisions, findings, revision preparation, FinalAcceptance, routes, - adjudication, reputation, or frontend work. -- Starting implementation from this proposed contract. - -## Acceptance criteria - -- Persistence links only to an exact finalized Submission identity and preserves - its artifact membership identity; it implements no admission transition. -- Database constraints prevent multiple live queue identities for the same - reviewable Submission; online checker-triggered admission and its race - behavior remain owned by 05A. -- Lease persistence cannot authorize self-review and retains auditable actor and - timing facts without yet implementing claim/release behavior. -- Queue records link to the exact Submission and Task so later Review and - Submission predecessor chains remain fully traversable. -- No upstream-owned row or lifecycle transition is mutated. -- CON is not a 03A dependency. Its completed-review participant is required only - by the later canonical decision composition. - -## Verification - -To be made exact at start: focused model/migration/service tests, PostgreSQL -concurrency proof, downgrade/refusal proof, repository regression tests, the -agent gates, and full coverage through GitHub Actions. - -## Required reviewers - -Senior engineering, QA/test, security/auth, product/ops, architecture, -reuse/dedup, docs, test-delta, and CI integrity. - -## Human review focus - -Confirm that every input is an owner-proven handoff, that REV begins only at -`allow_review`, and that this chunk adds persistence without decision behavior. - -## Stop - -Do not implement without a signed start on the refreshed exact-current-main contract. +Use the two child contracts and stop after each child. diff --git a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-03A1-queue-admission-persistence.md b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-03A1-queue-admission-persistence.md new file mode 100644 index 000000000..b9eccad0e --- /dev/null +++ b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-03A1-queue-admission-persistence.md @@ -0,0 +1,106 @@ +# Chunk Contract: WS-REV-001-03A1 — Queue And Admission Persistence + +## Parent initiative + +`WS-REV-001` — Review And Revision Lifecycle. + +## Goal + +Add the smallest hidden REV-owned persistence foundation for one queue identity +per exact reviewable Submission and one idempotent admission operation, without +wiring checker admission or exposing behavior. + +## Why this chunk exists + +Queue identity and database invariants are independently reviewable and do not +require final ART packet or CON interfaces. Separating them from leases avoids +one oversized concurrency migration. + +## Risk class + +L1 database identity, immutable lineage, and future concurrent admission. + +## SLA + +No expedited SLA. + +## Allowed files + +Freeze exact migration name from then-current main; expected scope: + +```text +backend/app/modules/reviews/__init__.py +backend/app/modules/reviews/models.py +backend/app/modules/reviews/repository.py +backend/app/modules/reviews/schemas.py +backend/alembic/versions/_review_queue_foundation.py +backend/tests/test_alembic.py +backend/tests/test_review_queue_persistence.py +backend/tests/conftest.py (schema fingerprint/fixture registration only) +docs/architecture_data_model.md +.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/** +``` + +The preimplementation refresh must replace `` and confirm exact metadata +registration conventions before code. + +## Not allowed changes + +- Checker completion hooks, task transitions, automatic admission, queue reads, + selection, claims, leases, preferences, packets, Reviews, findings, + FinalAcceptance, revision, routes, jobs, or action activation. +- AUTH, ART, TASK, CHECKER, CON, audit, or outbox implementation. +- Artifact bytes, provider identifiers, contribution fields, grant snapshots, + or a competing Submission identity. + +## Acceptance criteria + +- `ReviewQueueEntry` references the exact existing Submission, Task, project, + admitting CheckerRun identity slot, immutable first-queued time, routing and + lifecycle generation fields needed by later behavior. +- Persistence supports open and preferred routing shapes but implements no + transition or selection rule. +- A separate admission-idempotency identity can reserve/record one admission + attempt without authorizing it or mutating upstream rows. +- Database constraints permit at most one queue identity per Submission and + reject cross-project/task/Submission lineage. +- No migration backfills historical submissions or fabricates CheckerRun/ART + facts. Required foreign facts may remain unpopulated only in explicitly + non-admitted setup shapes that cannot become pending. +- Queue history cannot be updated into a different Submission/task/project. +- Models contain no AUTH handle, token, grant query, ART locator/bytes, or CON + state. +- No router is registered and every REV lifecycle action remains unavailable. + +## Verification commands + +Freeze exact node IDs at start. Minimum proof: + +```text +cd backend && .venv/bin/alembic heads +cd backend && .venv/bin/pytest -q tests/test_alembic.py -k review_queue +cd backend && .venv/bin/pytest -q tests/test_review_queue_persistence.py +cd backend && .venv/bin/ruff check app/modules/reviews tests/test_review_queue_persistence.py tests/test_alembic.py +cd backend && .venv/bin/pytest --cov=app.modules.reviews.models --cov=app.modules.reviews.repository --cov-branch --cov-report=term-missing --cov-fail-under=90 -q tests/test_review_queue_persistence.py +python3 scripts/check_stale_review_contracts.py +python3 scripts/check_markdown_links.py +git diff --check +``` + +GitHub Actions runs the full sharded suite and repository coverage floor. + +## Required reviewers + +Architecture, security/auth, product/ops, QA/test, senior engineering, +reuse/dedup, docs, test-delta, and CI integrity. + +## Human review focus + +One queue identity, exact existing Submission lineage, no fabricated admission, +no external ownership, direct-SQL constraints, and safe downgrade/refusal. + +## Stop conditions + +Stop if current main lacks an exact FK target required for queue identity, if +the migration would require modifying upstream-owned rows, or if admission +behavior becomes necessary. Merge and stop before 03A2. diff --git a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-03A2-lease-preference-persistence.md b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-03A2-lease-preference-persistence.md new file mode 100644 index 000000000..f58b37b36 --- /dev/null +++ b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-03A2-lease-preference-persistence.md @@ -0,0 +1,72 @@ +# Chunk Contract: WS-REV-001-03A2 — Lease And Preference Persistence + +## Status + +Planning skeleton. Refresh only after 03A1 and CON-03B merge; do not start +automatically. + +## Parent initiative + +`WS-REV-001` — Review And Revision Lifecycle. + +## Goal + +Persist ReviewLease attempts and preferred-routing state with database-enforced +active-capacity invariants, without implementing claim, release, decline, or +timer behavior. + +REV owns this model, migration, repository, constraints, and every later lease +transition. CON neither persists nor manages leases. CON-03B is ordered first +only because this REV migration references its canonical policy-version table. + +## Why this chunk exists + +Lease uniqueness and preference chronology form a separate high-risk +concurrency boundary from queue identity. + +## Risk class and SLA + +L1 database concurrency; no expedited SLA. + +## Allowed files + +Refresh exact review model/repository/migration/test paths from post-03A1 main. + +## Not allowed changes + +No routes, AUTH evaluation, claims, transitions, timers, packet manifests, +Review decisions, ART/CON calls, or action activation. + +## Acceptance criteria + +- One active lease per queue entry and one globally per human reviewer through + PostgreSQL partial uniqueness. +- Every lease stores an immutable, non-null FK to CON's canonical reviewer + `ContributionPolicyVersion`; REV neither duplicates its fields nor selects a + substitute policy source. +- Completed attempts are immutable and retain reviewer, queue, frozen policy- + version reference, database timestamps, generation, and close provenance. +- Preference state preserves immutable queue age separately from availability + time and lease expiry. +- Canonical ActorProfile FKs and human-kind guards prevent service identities + occupying reviewer fields. +- No behavior is callable and every lifecycle action remains unavailable. + +## Verification commands + +Freeze exact migration, direct-SQL, concurrency, coverage, Ruff, stale-doc, and +GitHub full-suite commands at start. + +## Required reviewers + +Architecture, security/auth, product/ops, QA/test, senior engineering, +reuse/dedup, docs, test-delta, and CI integrity. + +## Human review focus + +Partial uniqueness, immutable attempts, exact CON policy-version FK, actor kind, +timer separation, and no claim behavior. + +## Stop conditions + +Merge and stop before packet persistence or claim behavior. diff --git a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-PLAN4-current-main-end-to-end-refresh.md b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-PLAN4-current-main-end-to-end-refresh.md new file mode 100644 index 000000000..403b93091 --- /dev/null +++ b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-PLAN4-current-main-end-to-end-refresh.md @@ -0,0 +1,81 @@ +# Chunk Contract: WS-REV-001-PLAN4 — Current-Main End-To-End Refresh + +## Parent initiative + +`WS-REV-001` — Review And Revision Lifecycle. + +## Goal + +Replace stale historical sequencing with one complete current-main plan after +merged AUTH 02D, preserving REV ownership and explicitly gating ART/TASK/ +CHECKER/CON integration. + +## Why this chunk exists + +Earlier plans corrected boundary crossings but predate immutable policy lineage, +policy mutation, complete REV catalogue/principals, and typed authorization +contracts. They also intermingle historical and live status. + +## Risk class + +L1 architecture and cross-subsystem lifecycle planning. + +## SLA + +No expedited SLA. + +## Allowed files + +```text +.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/** +docs/spec_review_lifecycle.md (only if a normative contradiction is found) +``` + +## Not allowed changes + +- Backend/runtime code, migrations, tests, CI, routes, catalogue, availability, + dependencies, roadmap, ART, AUTH, TASK, CHECKER, or CON owner plans. +- Editing immutable archival reference specifications. +- Starting a runtime child. + +## Acceptance criteria + +- The intent, discovery, plan, map, status, risks, decisions, and conformance + matrix describe one consistent path from `allow_review` through contribution. +- AUTH 02D is the stable authority boundary and no lifecycle action is described + as active. +- Queue persistence can proceed independently; any REV schema or behavior with + a foreign invariant remains gated on the exact merged owner contract (for + example the CON-03B table before the REV-owned ReviewLease migration can add + its required FK, and ART membership identifiers before the packet manifest). +- Existing Submission is preserved; no uploaded review evidence or adjudication + enters v0.1. +- Every Review creates a reviewer contribution through CON; accept alone creates + FinalAcceptance and the submitter contribution. +- Only 03A1 is proposed for the first later implementation start. Future chunks + remain skeletons until current-main refresh. + +## Verification commands + +```text +python3 scripts/check_stale_review_contracts.py +python3 scripts/check_stale_authorization_docs.py +python3 scripts/check_stale_artifact_contracts.py +python3 scripts/check_stale_workstream_wording.py +python3 scripts/check_markdown_links.py +git diff --check +``` + +## Required reviewers + +Architecture, security/auth, product/ops, QA/test, senior engineering, docs, +reuse/dedup, test-delta, and CI integrity. + +## Human review focus + +REV start/end boundary, independent core work, ART/CON intersections, immutable +history, contribution cardinality, and chunk size/order. + +## Stop conditions + +Planning only. Await human approval before starting 03A1. diff --git a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-PLAN4-internal-review-evidence.md b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-PLAN4-internal-review-evidence.md new file mode 100644 index 000000000..233257a4e --- /dev/null +++ b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-PLAN4-internal-review-evidence.md @@ -0,0 +1,67 @@ +# Internal Review Evidence: WS-REV-001-PLAN4 + +## Scope + +Current-main planning-only refresh of the complete REV lifecycle after merged +AUTH 02D at `3479ee71`. + +## Results + +- Architecture: PASS. REV begins at exact owner-supplied `allow_review` facts, + preserves all subsystem boundaries, and safely starts with 03A1 persistence. +- QA/product: one high stale-vocabulary verification failure; lifecycle, + contribution cardinality, checker-remediation separation, and chunk order had + no blocking finding. The stale phrase was corrected. +- Security/docs/CI: the same high stale-vocabulary verification failure; no + runtime, migration, test, CI, dependency, or product-doc scope drift. The + stale phrase was corrected. + +The corrected exact diff passes the failed authorization wording command and +the complete deterministic verification set. + +## End-to-end owner-plan reconciliation + +A second critical review traced AUTH/XINT, ART/XINT, CON, and REV production and +consumption gates. It found three valid planning defects: + +- 03A2's REV-owned migration had been incorrectly treated as schema-independent + even though its non-null ContributionPolicyVersion FK target comes from + CON-03B; +- ART-07A and REV-03B formed a packet-contract cycle without a contract-only + owner precursor; and +- audit/outbox/CON gates and positive AUTH proof were not distinguished + precisely enough from generic persistence or unavailable-action testing. + +The plan now orders REV-03A2 after CON-03B solely for that FK target, explicitly +retains all lease persistence/lifecycle ownership in REV, requires ART to publish the membership port +before REV-03B, orders REV manifest -> ART-07A materialization -> REV-07A read, +gates 04B on CON-02C, names CON-06/07 and later dispatcher/release dependencies, +and reserves positive authorization proof for matching XINT activation. It also +records stale owner-plan status as an owner gap that each REV consumer must +verify from signed current-main evidence rather than silently repair. + +The architecture re-review passed after two low cleanup findings (duplicate +risk IDs and conditional gate wording) were corrected. Security/docs/CI and +QA/product reported no blocking finding. QA's low stale parent-chunk reference +in the conformance matrix was corrected to 03A1, 05A, and 09A4. + +After human review identified ambiguous dependency wording, the boundary was +made explicit as owner/gives/receives/never-owns contracts plus exact admission, +claim, packet-read, and decision flows. Architecture and QA/product re-reviewed +the final wording and passed. REV owns ReviewLease persistence and lifecycle; +CON-03B is only the pre-existing FK target, and CON-06 only returns the policy +lookup result that REV writes as its own lease freeze. The final upstream +admission manifest is also explicitly future, not mistakenly described as +merged. + +## Deterministic evidence + +- `python3 scripts/check_stale_review_contracts.py` +- `python3 scripts/check_stale_authorization_docs.py` +- `python3 scripts/check_stale_artifact_contracts.py` +- `python3 scripts/check_stale_workstream_wording.py` +- `python3 scripts/check_markdown_links.py` +- `git diff --check` + +All passed after correction. This planning chunk changes no runtime code or +tests; GitHub exact-head checks remain required for a PR.