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 e57cef7e2..9fc91c80e 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 @@ -10,20 +10,20 @@ explicit start signal. | Chunk | Title | Risk | Gate | Status | |---|---|---:|---|---| -| `WS-REV-001-PLAN` | Review And Revision Lifecycle Planning | L1 | None | Active; post-AUTH-09A current-main reconciliation in review | -| `WS-REV-001-01` | Canonical Contract Adoption And Dependency Conformance | L1 | Plan approval; current-main refresh; merged WS-XINT-001 handoffs, AUTH PR #140 planning contracts, and AUTH-09A fixed-service foundation | Proposed | +| `WS-REV-001-PLAN` | Review And Revision Lifecycle Planning | L1 | None | Merged through PR #128 at trusted main `0302bcf854a565d429e232ad6b076a1931ea74e4` | +| `WS-REV-001-01` | Canonical Contract Adoption And Dependency Conformance | L1 | Plan approval; current-main refresh; merged WS-XINT-001 handoffs, AUTH PR #140 planning contracts, AUTH-09A/09B foundations, and CON-01 canonical contract adoption | Active on `codex/ws-rev-001-01` | | `WS-REV-001-02` | Locked Review Policy And Task Lifecycle Alignment | L1 | AUTH canonical actor foundation; separately reviewed and merged AUTH-owned schema-only contributor-field foundation that breaks the current AUTH-13/14 <-> REV-09A cycle; ART submission commitment contract stable; canonical rejected/cancelled lifecycle amendment; D6 behavior approved | Proposed | | `WS-REV-001-03` | Review Queue And Lease Persistence | L1 | 02 merged; WS-CON ContributionPolicyVersion persistence merged | Proposed | | `WS-REV-001-04` | Immutable Review, Final Acceptance, Findings, And Replay Persistence | L1 | 03 merged; shared transactional-outbox persistence and caller-transaction lifecycle-audit participant merged at exact refreshed SHAs | Proposed | | `WS-REV-001-05` | Checker Admission, Preferred Routing, And Queue Views | L1 | 04; ART v2 submission/checker cutover; AUTH-10 reviewer grants and AUTH-11 project visibility; registered actions remain planned; hidden manifest later gates `WS-AUTH-001-REV-05` | Proposed | -| `WS-REV-001-06` | Atomic Claims, Release, Preference, And Timers | L1 | 05; merged `WS-AUTH-001-REV-CUSTODY` and `WS-AUTH-001-PREP`; merged AUTH-09A foundation plus AUTH-09B/09E and exact expiry identity extensions from the merged REV-01 manifest; WS-CON ReviewLease ContributionPolicyVersion freeze participant; hidden manifest later gates `WS-AUTH-001-REV-06` | Proposed | +| `WS-REV-001-06` | Atomic Claims, Release, Preference, And Timers | L1 | 05; merged `WS-AUTH-001-REV-CUSTODY` and `WS-AUTH-001-PREP`; merged AUTH-09A foundation and AUTH-09B provisioning capability plus exact expiry identity extensions/provisioning and AUTH-09E admission from the merged REV-01 manifest; WS-CON ReviewLease ContributionPolicyVersion freeze participant; hidden manifest later gates `WS-AUTH-001-REV-06` | Proposed | | `WS-REV-001-07` | Artifact-Backed Review Context And Finding Evidence | L1 | 06; merged PREP consumer contract; approved and merged ART-owner amendment for v2 packet-read; separately approved `WS-ART-001-REV-EVIDENCE` candidate/finalize capability; `WS-AUTH-001-ART-REV-EVIDENCE-REG` plus exact binding service row; hidden manifests later gate `WS-AUTH-001-REV-07` and `WS-AUTH-001-ART-REV-EVIDENCE` | Proposed | | `WS-REV-001-08` | Decision, Final Acceptance, And Task-Effect Contract | L1 | 07; merged PREP consumer contract; Review persistence and the accept-only FinalAcceptance write remain disabled until 10; complete hidden REV+CON composition later gates `WS-AUTH-001-REV-08` | Proposed | | `WS-REV-001-09A` | Revision Context Preparation And Resubmission | L1 | 08; ADR 0010 adopted; retired compensation-context field removal merged; schema-only contributor-field foundation; PREP; registered planned `submission.create`; hidden manifest later gates `WS-AUTH-001-REV-09A` and amended AUTH-13/14 product cutovers | Proposed | | `WS-REV-001-09B` | Finding Replay, Resolution, And Return Routing | L1 | 09A | Proposed | | `WS-REV-001-10` | Final Acceptance, WS-CON Atomic Integration, And Hidden Composition | L1 | 09B; PREP; approved and merged ART/task-owner `Submission.artifact_hash` amendment; merged CON FinalAcceptance-sourced lineage schema and two-operation flush-only contribution/award participant; no mandatory contribution-evidence projection; completion later gates `WS-AUTH-001-REV-08` | Proposed | -| `WS-REV-001-11` | Admin Overrides, Reviewer-Revocation Recovery, And Reconciliation | L1 | 10; AUTH invalidation; `WS-AUTH-001-REV-REG` registered/planned from the merged REV-01 manifest; PREP; merged AUTH-09A foundation plus AUTH-09B/09E and exact invalidation/reconciliation identity extensions from that manifest; ART Operator recovery port; hidden manifest later gates `WS-AUTH-001-REV-11` | Proposed | -| `WS-REV-001-12` | Snapshot Projection, Notifications, And Observability | L1 | 11; ART projection port; outbox foundation; PREP; merged AUTH-09A foundation plus AUTH-09B/09E and exact artifact-reference/projection identity extensions from the merged REV-01 manifest; hidden manifest later gates `WS-AUTH-001-REV-12` | Proposed | +| `WS-REV-001-11` | Admin Overrides, Reviewer-Revocation Recovery, And Reconciliation | L1 | 10; AUTH invalidation; `WS-AUTH-001-REV-REG` registered/planned from the merged REV-01 manifest; PREP; merged AUTH-09A foundation and AUTH-09B capability plus exact invalidation/reconciliation identity extensions/provisioning and AUTH-09E admission from that manifest; ART Operator recovery port; hidden manifest later gates `WS-AUTH-001-REV-11` | Proposed | +| `WS-REV-001-12` | Snapshot Projection, Notifications, And Observability | L1 | 11; ART projection port; outbox foundation; PREP; merged AUTH-09A foundation and AUTH-09B capability plus exact artifact-reference/projection identity extensions/provisioning and AUTH-09E admission from the merged REV-01 manifest; hidden manifest later gates `WS-AUTH-001-REV-12` | Proposed | | `WS-REV-001-12A` | Joint Lifecycle Release-Control Foundation | L1 | 12 review drain-observation port; exact core WS-CON hidden-readiness manifest; `WS-AUTH-001-REV-REG`; PREP; CON obligation-writer, dispatch, and callback fence hooks plus fulfillment/outbox drain-cutoff and observation port; complete additive manifests later gate `WS-AUTH-001-REV-LIFECYCLE` | Proposed | | `WS-REV-001-13` | Coherent Public Release, Live API Drill, And Release Proof | L1 | 12A; amended full AUTH-13/14 product cutovers; AUTH-14 `submission.create` active with prepared-revision proof; `WS-AUTH-001-REV-CUSTODY`; exact `WS-AUTH-001-REV-05/06/07/08/09A/11/12`, `WS-AUTH-001-REV-LIFECYCLE`, and ART evidence actions active after hidden behavior; ART/CON/outbox live readiness | Proposed | @@ -117,6 +117,7 @@ workflow, script, dependency, or coverage gate changes. ## Stop condition -Planning is approved and merged AUTH PR #140/AUTH-08/AUTH-09A/ART-02A2 contracts are reconciled. -Publication still requires final exact-snapshot review and evidence binding. Do -not start 01 automatically; its merge-intent gate remains separate. +Planning is approved and merged AUTH PR #140/AUTH-08/AUTH-09A plus +ART-02A2/ART-02A3 contracts are reconciled. Finish, review, and merge Chunk 01 +with explicit human approval, then stop. Do not start Chunk 02 automatically; +its merge-intent gate remains separate. 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 123263cf0..ba3ebe6a1 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 @@ -75,12 +75,13 @@ before producing the reconciled active contract. `ActorProfile.id`, not external subject, email, legacy typed-profile ID, or role labels. Review authority requires the independent exact-project `reviewer` grant; `submitter` and `adjudicator` grants do not substitute. -- AUTH-09A now supplies the fixed-service enum/schema/migration and the closed - seven-identity ART matrix, but it provisions no service actor and admits no - service token. Protected review jobs still require AUTH-09B provisioning, - AUTH-09E admission, and separately reviewed enum/constraint/matrix extensions - for each of REV's six exact identities. A generic system-principal or - fabricated human is not allowed. +- AUTH-09A supplies the fixed-service enum/schema/migration and the closed + seven-identity ART matrix. Merged AUTH-09B supplies controlled provisioning + only for that closed registry and admits no service token. Protected review + jobs still require separately reviewed enum/constraint/matrix extensions for + each of REV's six exact identities, provisioning through the merged AUTH-09B + capability, and AUTH-09E admission. A generic system-principal or fabricated + human is not allowed. - `review.queue.override` is present in the merged 74-PermissionId catalogue; the review actions mapped to it remain planned/inactive. Artifact recovery already uses the registered `artifact.verification_job.retry` action and ART-owned @@ -105,9 +106,10 @@ contracts assign the final `TaskAssignment.contributor_id` and counts from current trusted main and account for its delta independently. REV feature chunks build hidden behavior and typed facts; exact AUTH activation custodians alone integrate evaluators and change availability. Current trusted - main contains 65 ActionIds: 9 active and 56 planned. The eight AUTH-09A - additions do not change the 24 REV dependencies, all of which remain - unavailable. + main after AUTH-09C contains 65 ActionIds: 12 active and 53 planned. + AUTH-09B activated `actor.service.provision`; AUTH-09C activates only the two + bounded actor-registry reads. No REV identity or action was added, and all 24 + REV dependencies remain unavailable. The merged AUTH plan contains an execution cycle: full AUTH-13/14 require prepared revision/replacement behavior owned by REV-09A, while REV-02 needs @@ -137,9 +139,9 @@ route-owned transaction. Its internal evidence records 275 focused behavior tests, 90.17 percent branch-aware focused coverage, and 17 isolated Alembic tests. Final PR checks passed Backend, Agent Gates, and CodeRabbit. REV runtime chunks must preserve these merged invariants and still wait for the later AUTH - definition-of-done gate owned by each consumer, AUTH-09B/09E plus the exact - REV identity extensions for protected service callers, and the matching AUTH - activation checkpoint. Reads consume + definition-of-done gate owned by each consumer, exact REV identity extensions + and provisioning through merged AUTH-09B, AUTH-09E admission for protected + service callers, and the matching AUTH activation checkpoint. Reads consume request-scoped `AuthorizationService.require`; mutations consume the future authority-first prepared protocol and exactly one final evaluation without importing grant persistence into the review module. @@ -147,19 +149,21 @@ chunks must preserve these merged invariants and still wait for the later AUTH ## Artifact boundary - `ArtifactContent`, immutable `ArtifactBinding`, `ArtifactReplica`, operation - receipts, upload staging, a provider-neutral `ArtifactStore`, and a - LocalStorage adapter exist. -- Current ArtifactStore v1 operations cover store, recover committed store, - open, stat, verify, retain, release, and receipt lookup. They are discovery - state only: WS-XINT-001 requires ART v2 as the sole future provider boundary, - and REV must not consume the v1 provider contract. + receipts, upload staging, the byte-only provider-neutral ART v2 + `ArtifactStore`, and `LocalStorageAdapter` exist. - Merged ART-02A2 PR #129 at trusted main `9a04434e2f23c5dec8939dadb943bba4d85110c0`, final head `32aab89262a3944f305e9e5dc4c65a2d31e2e144`, adds an inactive `PreparedArtifact`/`CommittedArtifactSource` boundary, bounded private `ArtifactScratchManager`, deterministic cleanup mechanics, and shared bounded - file locking. Active ArtifactStore v1, provider selection, schema, routes, and - lifecycle behavior remain unchanged. + file locking. Those preparation types remain internal ART mechanics. +- Merged ART-02A3 PR #141 at trusted main + `a10d9018007d2e847b4870e9b26cbd24e24c7bb4`, final branch head + `7606798e751abf40218d23886779c3659b76e974`, removes ArtifactStore v1 and + activates the byte-only v2 LocalStorage clean cut, namespace fencing, typed + product capabilities, migration, and scratch-cleanup wiring. It does not + implement S3/MinIO, submission/checker artifact cutovers, review packet read, + or review-evidence candidate/finalize behavior. - ART scratch is bounded private ephemeral processing state, not artifact storage or a product reference. REV never imports ART preparation/scratch types, persists their paths or ledger identities, or creates a second scratch @@ -302,9 +306,10 @@ chunks must preserve these merged invariants and still wait for the later AUTH - Exact merged AUTH service, resource-context, invalidation, and system-actor interfaces. -- Exact later merged ART v2, S3, admission, verification/publication, read, +- Exact later merged ART S3, admission, verification/publication, read, binding, intake, retention, recovery, service-scope, checker, and projection - interfaces. ART-02A2 does not provide those product capabilities. + interfaces. ART-02A3 provides the byte foundation and typed composition + boundary, not those review-facing capabilities. - Exact WS-CON policy-freeze and transaction-participant interfaces. - Whether a shared outbox foundation lands before the first review consumer. - Production timer schedule and operational alert thresholds. 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 d9f8c7d12..6bc2268ae 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 @@ -79,7 +79,8 @@ After the exact owning AUTH gates merge, WS-REV consumes: - one exact active project `reviewer` grant for human review. Separate `submitter`, `adjudicator`, and administrative grants never substitute, and revoking reviewer authority never mutates another grant; -- AUTH-09B provisioning and AUTH-09E fixed-service admission for protected jobs. +- exact REV identity extensions, controlled provisioning through merged + AUTH-09B, and AUTH-09E fixed-service admission for protected jobs. Preference expiry, lease expiry, reviewer-authority invalidation reconciliation, general review reconciliation, artifact-reference reconciliation, and projection rebuild @@ -154,9 +155,11 @@ The four additive ActionIds and their closed mappings are registered together by and 12A; `WS-AUTH-001-REV-LIFECYCLE` later integrates their evaluators and activates them together. They add no PermissionId. The AUTH-08 runtime snapshot contained 57 actions: 9 active and 48 planned. That is historical provenance, -not a fixed future total. Current trusted main after AUTH-09A contains 65 -actions: 9 active and 56 planned; its eight additions are unrelated to the 24 -unavailable REV dependencies. +not a fixed future total. Current trusted main after AUTH-09C contains 65 +actions: 12 active and 53 planned. AUTH-09B activates +`actor.service.provision`; AUTH-09C activates only `actor.profile.read` and +`actor.identity_link.read`. Neither adds a REV identity or action, and all 24 +REV dependencies remain unavailable. WS-XINT-001 separately proposes `artifact.review_evidence.binding.create -> artifact.binding.create` for the ART binding service. Every later AUTH registration or activation chunk derives @@ -178,19 +181,19 @@ merged and proven. WS-REV consumes: - stable verification/availability facts and deterministic projection storage; - LocalStorage and MinIO conformance with AWS S3 as production provider. -Merged ART-02A2 PR #129 at trusted main -`9a04434e2f23c5dec8939dadb943bba4d85110c0`, final branch head -`32aab89262a3944f305e9e5dc4c65a2d31e2e144`, establishes only the inactive -committed-source and private scratch-preparation foundation. Its active -ArtifactStore v1 state is not a REV interface: ART v2 must be the sole provider -boundary before any REV artifact consumer starts. `ArtifactScratchManager`, `PreparedArtifact`, and -`CommittedArtifactSource` are ART-internal preparation mechanics, not REV -capabilities or durable product references; review code never imports or stores -them. Later ART-owned v2, S3, submission/checker binding cutovers, admission, +Merged ART-02A2 PR #129 established the committed-source/private-scratch +foundation. Merged ART-02A3 PR #141 at trusted main +`a10d9018007d2e847b4870e9b26cbd24e24c7bb4`, final branch head +`7606798e751abf40218d23886779c3659b76e974`, removes v1 and activates the +byte-only ART v2 LocalStorage clean cut and typed product capability boundary. +`ArtifactScratchManager`, `PreparedArtifact`, `CommittedArtifactSource`, and the +raw byte store are ART-internal mechanics, not REV capabilities or durable +product references; review code never imports or stores them. Later ART-owned +S3/MinIO, submission/checker binding cutovers, admission, verification/publication, packet read, evidence candidate/finalize, projection, and live-proof chunks remain hard gates. ART owns candidate retention and -Operator recovery; REV does not consume v1 verify/retain/release, raw -ArtifactStore, `artifact.binding.read`, or a generic artifact-retrieval action. +Operator recovery; REV does not consume the raw store, +`artifact.binding.read`, or a generic artifact-retrieval action. The current merged ART plan does not yet assign two other exact XINT requirements to an approved owner chunk: a narrow active-lease packet-read port @@ -218,11 +221,15 @@ PermissionId substitutes. ### Contribution gate -The merged WS-XINT `REV_CON_HANDOFF.md` remains the trusted-main boundary, with -the human-approved 2026-07-17 amendment that `FinalAcceptance` is the sole -submitter-acceptance source and REV, rather than CON, stages shared audit/outbox -records. Any sibling WS-CON worktree remains discovery evidence until its owning -contracts merge to trusted main. +Merged CON-01 at `e118e33afcd89b8ee78ecfc8f0e0d585ae0ee4b9` publishes +`docs/spec_contribution_compensation.md` and ADR 0016 as the canonical CON +boundary. They require FinalAcceptance as the sole submitter-acceptance source, +REV-owned decision orchestration and sole commit, ordered flush-only CON +operations, and REV staging of shared audit/outbox inputs returned by CON. The +older WS-XINT `REV_CON_HANDOFF.md` remains historical supporting handoff +material; it no longer outranks the merged CON contract. CON-01 implements no +runtime, so its later persistence, freeze, lineage, and participant chunks still +gate canonical Review composition. The cross-initiative sequence is explicit: 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 fd7ac66d7..6769f57c5 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 @@ -625,3 +625,263 @@ updates the discovered migration/test inventory and preserves the previously reviewed PREP, FinalAcceptance, transaction ownership, revision rebase, and no- adjudication boundaries. The exact `7a76da2` approval predates this rebase and must be replaced by fresh exact-SHA review and evidence before publication. + +## WS-REV-001-01 Start And Plan Review - 2026-07-17 + +PR #128 merged as trusted main +`0302bcf854a565d429e232ad6b076a1931ea74e4`, and the user explicitly started +`WS-REV-001-01` from that exact base on branch `codex/ws-rev-001-01`. + +The initial L1 plan review passed with conditions. The contract was amended to +name the complete active-document surface, forbid all four archival inputs, +require literal hashes plus exact trusted-base diffs, specify the fail-closed +scanner classifier and fixtures, publish exact four-action and six-service +manifests, reconcile initiative state, and require exact-SHA internal evidence +plus a changed-path audit. The amended contract then passed plan re-review. + +Deterministic evidence later exposed random WeasyPrint font-subset bytes. The +render scope was amended to include `render_pdf.sh`, fix the PDF identifier, +and embed full fonts. Plan re-review then found that the renderer rewrote four +unchanged context PNGs outside Chunk 01 scope. The renderer now compares pixels +through temporary outputs and preserves existing target bytes when unchanged; +verification also binds all four paths to trusted base `0302bcf`. Consecutive +renders produced identical lifecycle PDF and PNG hashes without changing a +context image. The repaired L1 contract passed final plan review. + +Implementation remains specification and gate work only. No runtime endpoint, +authorization availability, artifact capability, contribution behavior, +adjudication behavior, or reputation mutation is introduced. + +## WS-REV-001-01 First Exact-SHA Review - 2026-07-17 + +Candidate `06548c56e9db63e7f73c581c2c974a3ce798ba2f` passed deterministic +evidence but failed senior engineering, architecture, QA/test, product/ops, +docs, test-delta, and CI-integrity review. Security/auth and reuse/dedup passed. + +The valid findings and repairs are: + +- Added active ADR 0003, the Project Guide template, and three README-linked + roadmaps to Chunk 01. They now remove automatic revision rejection, + policy-selected latest-context rebase, legacy finding severity/closure, + direct Review-to-submitter contribution, active reputation, and product + second-review assumptions. +- Moved `task_assignment_id` from Assignment to immutable Submission, removed + policy-selected rebase fields, added ReviewEvidenceArtifact, and corrected + FinalAcceptance, contribution-source, blocking-finding, reputation, and + adjudication model invariants. +- Made the decision transaction commit before later revision preparation, + contributor response, replacement Submission, and checker work in both + sequence sources; regenerated the lifecycle image and architecture PDF. +- Added `NEEDS_REVISION -> CANCELLED`, prohibited direct acceptance from + revision, required CheckerRun-rooted automated revision, removed pre-submit + revision-lane wording, and made reject findings optional beside its bounded + human reason. +- Added planned/unavailable status to queue, first-user-flow, compensation, and + roadmap surfaces. Initiative state now finishes Chunk 01 and stops before 02. +- Replaced filename-only scanner admission with fail-closed classification for + every docs file, exact reference/archive handling, local structural + exceptions only, and adversarial tests for keyword decoys, unrelated + negation, legacy severity, direct contribution, and unclassified copies. + +The repaired scanner passes across the full active docs tree and the expanded +agent-gate suite passes 85 tests. A new exact-SHA review is required; the failed +candidate is historical evidence only. + +The roadmap scope amendment also records that neither ignored local roadmap +export existed at start or after repair. The contract fails closed if an XLSX or +CSV appears without its paired export, exact one-sheet name, current Workstream +definition, and ignored/untracked status. No spreadsheet file is committed. +The expanded L1 chunk contract then passed final plan re-review with no +remaining scope or proof blocker. + +A later repeat-render proof showed that ImageMagick SVG antialiasing can change +context-diagram pixels across invocations, which also changes the composed PDF. +The renderer default now rebuilds only Chunk 01's lifecycle PNG and PDF; full +context regeneration requires explicit `--all`. The four context images are +restored and remain trusted-base bound. + +## WS-REV-001-01 Second Exact-SHA Review And Repair - 2026-07-17 + +Candidate `0a0be1acd870f769ac5d27661a01d45ce3b402b6` failed the grouped +senior-engineering/architecture, QA/product/test-delta, and +security/docs/CI-integrity reviews. Reuse/dedup remained passing. The failed +candidate is historical evidence only. + +The valid findings produced this repair: + +- reconciled all three active roadmaps and the Project Guide template to + immutable finding responses/resolutions, decision-specific evidence, the + FinalAcceptance contribution matrix, payable-only awards, and deferred + reputation; +- removed remaining automatic-reject, mandatory second-review, overturned- + decision, and adjudication-like product semantics from active decision, + risk, data-model, operations, and diagram surfaces; +- expanded the fail-closed scanner and adversarial fixtures for spaced legacy + closure, plural automatic rejection, unconditional payment, passive + reputation, direct-contribution decoys containing FinalAcceptance, and mixed + reviewer-rebase negation; +- separated concealed `review.queue.read`, `review.claim`, and + `review.decision` operations, with fresh token verification, AUTH PREP, + canonical lock/recomposition order, exact handle validation/consumption, + evaluation, and staged evidence before the first feature mutation; and +- regenerated the two context diagrams whose v0.1 reputation content changed, + while the Workstream context and future identity/payment/reputation images + remain byte-bound to trusted base. + +The amended L1 contract added the affected active sources and generated files +to allowed scope. Its final plan re-review passed after the renderer was made +portable and deterministic: it requires the repository-standard PlantUML +1.2026.6 jar, verifies SHA-256 +`89948f14c93756c7a3fb7b69078ff37e8489fd79dd430c582b931e2f65358690`, +uses that jar unconditionally, fixes `SOURCE_DATE_EPOCH`, strips lifecycle PNG +metadata, and exposes explicit `--review-context` source-to-SVG-to-PNG +rendering. Two complete pinned render passes produced identical SVG, PNG, and +PDF hashes. + +The repaired stale-review and stale-workstream gates pass, the expanded agent +gate suite passes all 85 tests, archival literal hashes remain exact, and both +local roadmap exports remain absent. A new committed exact-SHA candidate and +full internal reviewer fanout are still required before PR publication. + +## WS-REV-001-01 CON PR #142 Main Reconciliation - 2026-07-17 + +Candidate `9b2fc11c12e8c0cb19914c9772f95ba4e9814688` later passed all nine +required reviewer tracks and its evidence gate. Before publication, CON planning +PR #142 merged to main at `a947b8693a97bdb94c9dc63202a51e197834d613` from +branch head `4b13c3ee28ecddd7c92be70ad2059c130604f9d1`. + +`git pull --no-rebase origin main` exposed conflicts in 15 shared active +documents. The reconciliation retains CON's exact reviewer/submitter operation +shapes, frozen-policy award rules, source constraints, and joint transaction +boundary while preserving REV's blocking/advisory finding model, optional +reject findings, deterministic revision preparation, deferred reputation, and +no-adjudication v0.1 boundary. The newly supplied CON reference Markdown is an +exact historical path in the fail-closed review scanner: it is a noncanonical +working transcription, not an archival or runtime-authority input. + +PR #142 contains planning and documentation only. It activates no CON or REV +runtime behavior. Because current-main reconciliation changed review-relevant +files, the earlier exact-SHA PASS is historical and a fresh full reviewer pass +is required on the merge candidate. + +## WS-REV-001-01 Current-Main Candidate Repair - 2026-07-17 + +Exact candidate `1c7c3e75cffbe91a44d5cd10d333a5ec0fcf1fd4` passed the +current-main plan review but failed the first full reviewer fanout. Senior +engineering, architecture, QA, and product/ops found that three active +operational workflows inverted or ambiguously described the canonical reviewer +CON operation, FinalAcceptance, task-effect, and submitter CON operation order. +They also found an optional human simulation inserted into automated checker +admission, an undefined disputed-reject owner, and missing planned/unavailable +review-lifecycle status in the operator workflow. + +The repair aligns every numbered accept workflow to Review and lease/queue +closure -> reviewer CON operation -> FinalAcceptance -> accepted task and +completed assignment -> submitter CON operation. Submitted-work admission is +now a mandatory durable CheckerRun decision; human judgment begins only with an +immutable Review. Terminal-reject sampling is explicitly non-mutating and has +no dispute, reopen, or adjudication path. Focused scanner fixtures and +structural workflow-order tests prevent recurrence. Candidate `1c7c3e75` is +historical failure evidence; a new exact-SHA full reviewer fanout is required. + +The first repair candidate `e2797fb1` then failed the repair-cycle plan gate: +the two structural tests were not registered in the custom runner, payment +wording left task effects versus the submitter operation implicit, and a global +accept-order regex rejected valid branch-scoped prose. The follow-up registers +both tests, raises the executed gate count, asserts the complete payment order, +and removes the overbroad regex while retaining exact human-admission and +disputed-reject protections. + +Candidate `76ed3c14` passed the repaired plan gate and eight of nine full-review +tracks. The docs track then found two remaining active-flow contradictions: +Flow 4 used severity/no-blocker shorthand instead of exact durable, final, +current `allow_review` admission, and generic Flow 6 applied Review-rooted +revision records to checker-caused remediation. The repair binds Flow 4 and +Flow 5 to the exact admitting CheckerRun, keeps setup/provenance defects on +`evaluation_pending` / `task_setup_blocked`, scopes Flow 6 to immutable +`Review(needs_revision)`, and states that checker remediation has only +CheckerResult lineage and returns through the normal submission/checker spine. +The registered structural test now covers these distinctions. + +The follow-up plan gate accepted the active prose and required the regression +to bind Flow 5's verified facts and every checker-forbidden Review record or +reviewer contribution explicitly. The final fixture scopes those assertions to +the checker-remediation `creates no` clause. + +## WS-REV-001-01 AUTH-09B Main Reconciliation - 2026-07-18 + +After candidate `df098f203fae4982806568dcc25a81043d9f7211` passed all nine +tracks, AUTH-09B PR #143 advanced main to +`053242b90d927ace3fab92eeca72da27a61cecec`. The branch pulled that merge +cleanly. Only `scripts/test_agent_gates.py` overlapped, and Git retained both +AUTH's new gates and REV's registered 87-test baseline without conflict. + +AUTH-09B activates only `actor.service.provision`, changing the current +catalogue snapshot to 74 PermissionIds and 65 ActionIds split into 10 active and +55 planned. It supplies controlled provisioning for AUTH's existing closed +identity registry but adds none of REV's six future identities, admits no +service token, and activates no review action. All 24 REV action dependencies +remain unavailable. The prior exact-SHA PASS is historical; the reconciled +candidate requires fresh deterministic and full reviewer evidence against +`053242b`. + +## WS-REV-001-01 PR #145 Initial External Gate - 2026-07-18 + +PR #145 opened from head `9ad0420e`. GitHub Agent Gates failed only at the +schema-v2 merge-intent validator because the existing `WS-REV-001-02` contract +heading omitted the successor title declared by the exact REV-01 merge intent. +The repair adds that exact title to the heading without changing successor +scope or starting Chunk 02. CodeRabbit reported a review-limit cooldown and +produced no findings. + +## WS-REV-001-01 CON-01 Main Reconciliation - 2026-07-18 + +While PR #145 replacement Backend was running, CON-01 PR #144 advanced main to +`e118e33afcd89b8ee78ecfc8f0e0d585ae0ee4b9`. The branch pulled it and resolved +one `architecture_data_model.md` conflict by retaining the exact shared +FinalAcceptance fields plus explicit canonical reviewer ActorProfile and +immutable ReviewPolicy foreign-key semantics. + +CON-01 now publishes `docs/spec_contribution_compensation.md` and ADR 0016 as +canonical CON authority. It confirms REV's one-commit transaction, ordered +reviewer/accept-only submitter operations, FinalAcceptance-only submitter +trigger, frozen policies, and no ART call. It adds no runtime. The prior PR +candidate and replacement checks are historical; fresh exact-SHA internal and +external gates are required against `e118e33`. + +The first CON-01 reconciliation plan gate found one stale central PLAN paragraph +that still called the older WS-XINT handoff current and treated CON as unmerged +sibling evidence. The repair names merged CON-01 `e118e33`, its active +specification, and ADR 0016 as canonical authority while retaining XINT only as +historical supporting context and preserving every downstream runtime gate. + +## WS-REV-001-01 Final Scope Verification Repair - 2026-07-18 + +After ART-02A3 reconciliation and a fresh nine-track PASS, CodeRabbit correctly +reported that the final path listing did not fail on unexpected scope. Candidate +`7742730` added a committed path allowlist and documented why trusted current +main `a10d901` defines PR scope while planning base `0302bcf` remains the +archival byte-integrity anchor. + +Internal security/docs/CI review then found that path-only comparison could not +distinguish an approved modification from deleting the same path. Candidate +`7785b832` replaces it with an exact 71-entry +`git diff --name-status --no-renames` A/M manifest. The exact comparison +passes; simulated status change, removal, rename as D+A, and addition each fail. +All deterministic gates and all nine exact-SHA reviewer tracks pass. The proof +is intentionally chunk-specific rather than a permanent global CI rule pinned +to one historical main SHA. + +## WS-REV-001-01 AUTH-09C Main Reconciliation - 2026-07-18 + +AUTH-09C PR #146 advanced main to `0ffdabf3`. The branch merged it and resolved +the sole conflict in `scripts/test_agent_gates.py` by adopting main's current +AUTH-09C and merged ART-02A3 assertions while retaining REV's pre-merge ART +phase checks in their fallback branches. No test or assertion was removed. + +AUTH-09C keeps 74 PermissionIds and 65 ActionIds, activating only +`actor.profile.read` and `actor.identity_link.read` and moving the split to +12 active / 53 planned. It adds no REV identity or action; all 24 REV +dependencies remain unavailable. The trusted PR-scope base is now +`0ffdabf3dbb77e4e066683fde1a095d744ff1f43`. Fresh deterministic evidence and +all nine exact-SHA reviewer tracks are required. 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 b9046629b..de15fb4a1 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 @@ -37,7 +37,7 @@ | 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 and 65/9/56 only as the AUTH-09A current-main snapshot; derive exact counts/SHA at each registration and activation gate, with the four REV proposals and ART binding action separately inventoried. | +| 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, and 65/10/55 only as AUTH-09B history; current trusted main after AUTH-09C is 65/12/53. 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. | diff --git a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/SOURCE_MANIFEST.md b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/SOURCE_MANIFEST.md index 632697e5c..de639876e 100644 --- a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/SOURCE_MANIFEST.md +++ b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/SOURCE_MANIFEST.md @@ -4,7 +4,7 @@ | File | SHA-256 | Status | |---|---|---| -| `docs/reference_specs/WS-REV-001-review-lifecycle-specification.md` | `fffadc271c267801250b044edc570e515a250eff48afdc64f9c1f8753e6ab058` | Canonical revised archival input; includes Markdown-only section 4.6 action mapping; not yet actively adopted | +| `docs/reference_specs/WS-REV-001-review-lifecycle-specification.md` | `fffadc271c267801250b044edc570e515a250eff48afdc64f9c1f8753e6ab058` | Canonical revised archival input; includes Markdown-only section 4.6 action mapping; adopted through the reconciled active contract without editing this file | | `docs/reference_specs/WS-REV-001-review-lifecycle-specification.pdf` | `8c053bc752a7b0c64e04b3eda1873bb5dbc02bbdfef84bd17d07cbbf01bce2fd` | Canonical revised archival companion; does not contain Markdown section 4.6 and is not a generated twin | ## Normative repository constraints @@ -74,18 +74,33 @@ PR #140 changes planning and authorization documentation only. Its runtime snapshot was 74 PermissionIds and 57 ActionIds, with 9 active and 48 planned; none of the 24 REV lifecycle dependencies was active. -AUTH-09A PR #132 then merged to current trusted main +AUTH-09A PR #132 then merged to its trusted main `299363af5d9e8a68bcc9b17457188048483caeed` from reviewed code `fe61df64fbf82a1f6871c380e6fc1986a4f12205` and final branch head `d4b65400d35c1036f8d6f15bb81fe5e0b81f10be`. It advances the migration head to `0023`, adds the common fixed-service schema and seven ART identities with eleven exact memberships, and registers eight planned AUTH-09 route actions. -The current catalogue is therefore 74 PermissionIds and 65 ActionIds: 9 active +The AUTH-09A catalogue was therefore 74 PermissionIds and 65 ActionIds: 9 active and 56 planned. It provisions no actor, admits no service token, and does not add any of REV's six identities. Later gates derive counts from then-current trusted main, and the separate ART evidence-binding proposal is not counted among the 24 REV dependencies. +AUTH-09B PR #143 later merged to then-current trusted main +`053242b90d927ace3fab92eeca72da27a61cecec` from final branch head +`9ee5646`. It activates only `actor.service.provision`, producing 74 +PermissionIds and 65 ActionIds split into 10 active and 55 planned. The +controlled route may provision only identities already present in AUTH's closed +registry. It adds none of REV's six identities, admits no service token, and +activates no review action; all 24 REV dependencies remain unavailable. + +AUTH-09C PR #146 later merged to current trusted main +`0ffdabf3dbb77e4e066683fde1a095d744ff1f43` from final branch head +`a3d6babc`. It keeps 74 PermissionIds and 65 ActionIds while activating only +`actor.profile.read` and `actor.identity_link.read`, moving the split to 12 +active and 53 planned. It adds no REV identity or action, and all 24 REV +dependencies remain unavailable. + ## Dependency specifications and plans - `docs/reference_specs/WS-AUTH-001-actor-profile-role-and-authorization-service-specification.md` @@ -94,6 +109,36 @@ among the 24 REV dependencies. - `.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/` - `.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/` +## Merged CON planning authority + +WS-CON-001 planning PR #142 merged to current main +`a947b8693a97bdb94c9dc63202a51e197834d613` from final branch head +`4b13c3ee28ecddd7c92be70ad2059c130604f9d1`. Its PLAN3 reconciliation is now +the repository-owned CON planning authority. It confirms: + +- one reviewer `completed_review` operation before the REV decision branch; +- one accept-only `accepted_submission` operation after REV creates + FinalAcceptance and applies accepted task/assignment effects; +- operation-specific typed inputs rather than one nullable omnibus request; +- one REV-owned caller transaction and no ART call or mandatory evidence + projection in the core decision path; and +- no adjudication dependency. + +PR #142 changes planning and shared active documentation only. Its CON runtime +chunks remain proposed/inactive and continue to gate REV implementation. + +## Merged CON canonical contract + +CON-01 PR #144 later merged to current trusted main +`e118e33afcd89b8ee78ecfc8f0e0d585ae0ee4b9`. It publishes +`docs/spec_contribution_compensation.md` and ADR 0016 as repository-owned CON +authority. It preserves the ordered reviewer and accept-only submitter +operations, FinalAcceptance-only submitter trigger, frozen-policy rules, +REV-owned sole commit, and no-ART core transaction. CON-01 changes no runtime, +migration, AUTH/ART/REV-owned contract, or archival reference input. Its later +implementation chunks still own policy persistence, ContributionRecord, +CompensationAward, the flush-only participant, and fulfillment behavior. + AUTH-07A/07B discovery was refreshed against merged AUTH-08 PR #131 at trusted-main `aa0fdcd6912e66609e39a2fbd7b65f67be6c62f3`, whose final branch head is `0832358a0262805f553d05b50b0d778e6e6ad995`. AUTH-08 retains the minimal @@ -111,11 +156,15 @@ independent runtime gates before their corresponding REV behavior is released. ART discovery was refreshed against merged ART-02A2 PR #129 at trusted-main `9a04434e2f23c5dec8939dadb943bba4d85110c0`, final branch head -`32aab89262a3944f305e9e5dc4c65a2d31e2e144`. The chunk adds only inactive -committed-source/private-scratch preparation. Its current ArtifactStore v1 state -is not a REV interface. REV consumes none of its scratch/source types or raw -store methods. Later ART v2, S3, submission/checker binding cutovers, packet -read, review-evidence candidate/finalize, projection, and live-proof contracts, +`32aab89262a3944f305e9e5dc4c65a2d31e2e144`. That chunk adds only +committed-source/private-scratch preparation. ART discovery was then refreshed +against merged ART-02A3 PR #141 at trusted main +`a10d9018007d2e847b4870e9b26cbd24e24c7bb4`, final branch head +`7606798e751abf40218d23886779c3659b76e974`. ART-02A3 removes v1 and activates +the byte-only v2 LocalStorage store, namespace fence, and typed product +capability composition. REV consumes none of the scratch/source types or raw +store methods. S3/MinIO, submission/checker binding cutovers, packet read, +review-evidence candidate/finalize, projection, and live-proof contracts, including a separately approved `WS-ART-001-REV-EVIDENCE` owner chunk, remain dependency gates. @@ -135,8 +184,8 @@ WS-REV: - `/home/abiorh/flow/workstream-con-001/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/JOINT_RELEASE_HANDOFF.md` - `/home/abiorh/flow/workstream-con-001/docs/reference_specs/WS-CON-001-contribution-record-and-compensation-boundary-specification.md` -These paths are dated discovery only. Merged WS-XINT -`REV_CON_HANDOFF.md` supersedes their conflicting mandatory evidence-projection, +These paths are dated discovery only. Merged WS-XINT `REV_CON_HANDOFF.md` and +merged CON PR #142 supersede their conflicting mandatory evidence-projection, policy naming, activation, and core ART-dependency assumptions. Owning WS-CON runtime contracts must still merge before a REV gate consumes them. @@ -151,3 +200,23 @@ unchanged, records their provenance/status differences, and creates `docs/spec_review_lifecycle.md` as the reconciled active normative contract. Neither WS-REV archival file nor either WS-IMP archival file is edited to express active repository policy. + +## Chunk 01 adoption base + +Planning merged through PR #128 at trusted main +`0302bcf854a565d429e232ad6b076a1931ea74e4`. The user explicitly started +`WS-REV-001-01` from that exact commit. Chunk 01 makes +`docs/spec_review_lifecycle.md` the active normative contract while the four +archival files remain literal-hash and trusted-base-diff protected inputs. + +The active contract, its four-action registration manifest, and its six-service +identity manifest become immutable inputs for downstream AUTH gates only after +this chunk is reviewed and merged. Until their owning chunks and AUTH activation +gates complete, every review-lifecycle action and endpoint remains unavailable. + +After the initial exact-SHA review, the branch pulled merged CON PR #142 at +`a947b8693a97bdb94c9dc63202a51e197834d613`. The original `0302bcf` start and +archive-integrity proofs remain fixed. The branch then pulled merged AUTH-09B +PR #143 at `053242b90d927ace3fab92eeca72da27a61cecec` and merged CON-01 PR +#144 at `e118e33afcd89b8ee78ecfc8f0e0d585ae0ee4b9`; final PR scope and +exact-SHA review use the newest merged-main boundary. 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 3bf13fb0e..10932fe0b 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 @@ -2,166 +2,126 @@ ## Current status -`WS-REV-001-PLAN` is active on `codex/ws-rev-001-plan`; no runtime chunk is -active. On 2026-07-17 the branch rebased without conflict onto trusted main -`299363af5d9e8a68bcc9b17457188048483caeed`, merge commit for AUTH-09A PR #132. -That merge follows AUTH reconciliation PR #140 and implements migration `0023`, -the common fixed-service enum/schema, seven ART service identities, eleven -static ART memberships, and eight planned AUTH-09 route actions. It provisions -no actor, admits no service token, activates no action, and adds no REV service -identity. The earlier exact-snapshot review at `7a76da2` predates this rebase and -is historical. Refreshed normative snapshot -`12a781b2c4e8e8bb3378e3c4cb4f7c32ac9ba5be` passed all nine internal review -tracks; fresh external evidence remains required before PR #128 can merge. - -The revised WS-REV Markdown/PDF pair remains byte-preserved at canonical paths -with recorded provenance. It is archival input, not authority for stale combined -roles, feature-owned action activation, provider contracts, contribution-policy -naming, or task status tokens that conflict with merged active repository -decisions. - -## Reconciled dependency state - -- AUTH-08 remains a historical implemented checkpoint: 74 PermissionIds and 57 - ActionIds, with 9 active and 48 planned. Current trusted main after AUTH-09A - contains 74 PermissionIds and 65 ActionIds, with 9 active and 56 planned. Its - rollback-only dependency teardown, typed authorization-evidence 503, and - canonical timestamp behavior remain required regression invariants. -- The 24 REV lifecycle dependencies are registered planned `submission.create`, - 19 registered planned review actions, and four approved but unregistered REV - lifecycle actions. None is active. The separate unregistered - `artifact.review_evidence.binding.create` ART action is not one of the 24. - Exact counts, custodians, availability, and SHAs are derived at each later AUTH - registration or activation gate. -- PR #140 defines the exact AUTH sequence and ownership. AUTH-09A is now merged; - AUTH-09B through AUTH-09E, availability-neutral - `WS-AUTH-001-REV-CUSTODY`, `WS-AUTH-001-PREP`, and later AUTH product contracts, - feature-gated `WS-AUTH-001-REV-REG`, per-feature `WS-AUTH-001-REV-05/06/07/08/09A/11/12` - activation, and `WS-AUTH-001-REV-LIFECYCLE` for the four additions. Hidden REV - schema, pure validation, resource facts, guards, and behavior may proceed when - their exact data/participant contracts exist while actions remain unavailable. - Each committing sensitive mutation waits for PREP; REV-13 waits for every exact - activation and is the only product-surface release. -- AUTH-09A's fixed-service foundation is reusable, but its closed set and matrix - contain only seven ART identities and eleven ART memberships. Each of REV's - six service identities still needs the immutable REV-01 manifest, a separately - reviewed AUTH enum/constraint/matrix extension, AUTH-09B provisioning, and - AUTH-09E admission. No catch-all service authority exists. -- PR #140 also exposes one blocking AUTH graph defect: full AUTH-13/14 currently - require prepared revision/replacement behavior owned by downstream REV-09A. - Before REV-02 starts, AUTH must split and merge a schema-only contributor-field - foundation. REV-09A then supplies hidden behavior; amended full AUTH-13/14 - cutovers and AUTH-14 `submission.create` activation follow before REV-13. -- Project contributor grants are independent `submitter`, `reviewer`, and - `adjudicator`. REV consumes only reviewer authority/invalidation; adjudication - remains unavailable. -- ART-02A2 remains preparation-only. REV waits for ART v2 submission/checker - cutovers, narrow packet read, separately approved review-evidence - candidate/finalize behavior, exact binding service action, projection, and - live proof. The current merged ART plan does not schedule - `WS-ART-001-REV-EVIDENCE`, so REV-07 is blocked until ART adds and merges that - owner chunk. The ART plan also does not yet assign the exact active-lease - packet-read port or server-derived `Submission.artifact_hash` persistence; - those require approved owner amendments before REV-07/10. REV never consumes - ArtifactStore v1, scratch, provider, or ART repository APIs. -- Merged `REV_CON_HANDOFF.md` plus the human-approved 2026-07-17 amendment - controls contribution integration. REV owns immutable FinalAcceptance and - creates it only for accept; CON must supply ContributionPolicyVersion freezes - and one mandatory participant with two ordered flush-only operations. The - reviewer operation runs before every decision branch; the submitter operation - runs only after FinalAcceptance exists for `accept`. Submitter - `accepted_submission` consumes FinalAcceptance rather than inferring - `Review.decision`. REV stages shared audit and outbox rows; the request route or - service command commits once. Core - creation copies stabilized versioned Submission `artifact_hash` lineage, - performs no ART call, and has no mandatory contribution-evidence projection. -- REV-12A also waits for CON-owned mandatory fence hooks on every fulfillment - obligation writer, dispatch, and callback path; a monotonic root ordinal; and - a same-session drain-cutoff/observation port. The exclusive cutoff transition - waits for prior writers, and `delivery_draining` permits only completion of - same-generation roots at or below the stored cutoff. -- The current canonical lifecycle uses `rejected` for human reject and - `cancelled` with bounded reasons for approved administrative closure; REV will - not introduce archival `closed/review_rejected` as a new status token. - -## Reconciled plan state - -The reconciliation updates intent, discovery, decisions, plan, chunk map, -conformance, CON integration, risks, source manifest, every affected chunk -contract, review log, trust bundle, and exact-SHA internal evidence. Required -changes include: - -- AUTH registration -> hidden behavior -> AUTH activation -> REV product release; -- AUTH-first prepared mutation choreography; -- exact fixed-service identity rows and independent reviewer grants; -- REV-owned ReviewPacketManifest and ReviewEvidenceArtifact; -- ART v2 packet/evidence ports and exact binding action; -- first canonical Review commit only with the CON participant; and -- removal of CON router ownership and optional evidence projection from REV-13. - -The first final review of snapshot `a916692` found executable-graph, external -dependency ownership, cross-project concealment, coverage, claim-order, and -artifact-error ambiguities. Those findings were repaired in `93955f1`; its -second review found a duplicated scanner workaround and one stale integration- -fence sentence. Both are repaired through literal proof commands, a narrow -tested technical-path/CLI classifier, and consistent pre-12A/released fence -wording. Immutable snapshot -`341d920496fbf7586d95a1c00bf8a6e575b9b157` then passed every required final -review track with no findings. The later human-approved FinalAcceptance -amendment reopens planning review; that older evidence remains historical and -must not be used to publish the amended snapshot. Earlier AUTH/ART dependency -review files remain dated evidence; their old future-count assumptions do not -override WS-XINT. The FinalAcceptance amendment initially failed transaction -ordering and proof-matrix review, then failed on one obsolete omnibus CON input -and one incomplete negative-source constraint. Both findings were repaired. -CodeRabbit's latest refresh then found an unreachable fulfillment-drain phase. -The repaired contract now fences every CON obligation writer before ordinal -allocation, captures an immutable cutoff after prior writers drain, permits only -pre-cutoff completion work, and retains audited same-root recovery for denied -already-claimed dispatch. Snapshot -`86ee0a5e263ac306b3bf195a9fb9043aa5439416` passed senior engineering, -QA/test, security/auth, product/ops, architecture, docs, reuse/dedup, test-delta, -and CI integrity with no findings before the PR #140 rebase. It is historical -evidence and does not approve the current snapshot. - -After the PR #140 reconciliation, snapshots `777468d`, `4084cd4`, and `2146b8c` -failed internal review on dependency cycles, PREP ownership/replay semantics, -transaction ownership, and residual AUTH-13/14 cutover ownership. Every valid -finding is recorded in `REVIEW_LOG.md` and repaired. Exact snapshot -`7a76da2a79243cf61936d3bc7cf2606a82f0b5d8` passed senior engineering, QA/test, -security/auth, product/ops, architecture, docs, reuse/dedup, test-delta, and CI -integrity with no findings. No runtime chunk is active. - -That approval predates merged AUTH-09A PR #132 and is historical after the -rebase onto `299363a`. Refreshed normative snapshot `12a781b` passed all nine -required tracks after the AUTH-09A, catalogue, service-identity, migration, and -guide-authority reconciliation plus the archival-provider adoption clarification. -Its evidence is bound in the PLAN review file. - -## Human clarification retained - -- Keep ADR 0010 and one Project Guide context through the task pipeline. -- Exact match between the prior Submission's stamped guide identity/activation - sequence and the project's currently active guide keeps context. Any different - internally consistent active identity/sequence pair, including an older - reactivated guide, causes a controlled forward or backward rebase; an - internally inconsistent pair or missing, incomplete, or unsafe active context - blocks preparation. -- Reviewer uses the context stamped on the exact leased Submission and performs - no separate guide rebase. -- LocalStorage is development, MinIO proves the protocol, AWS S3 is production, - and Flow Node remains deferred. -- Artifact bytes are restricted to the exact active leased packet; bounded chain - metadata remains available to authorized participants. -- Every decision appends an immutable Review, and every submitted finding and - later resolution is immutable. Every Review creates reviewer contribution. - When the decision is `accept`, REV also creates one immutable FinalAcceptance; - only that fact creates submitter contribution. Guide rebase never changes the - frozen ContributionPolicyVersion. +`WS-REV-001-PLAN` merged through PR #128 at trusted main +`0302bcf854a565d429e232ad6b076a1931ea74e4`. The user explicitly started +`WS-REV-001-01`, which is active on `codex/ws-rev-001-01` from that exact base. +No runtime review or revision behavior is active in this chunk. + +While Chunk 01 was under review, CON planning PR #142 merged to main at +`a947b8693a97bdb94c9dc63202a51e197834d613`. The branch pulled that merge and +reconciled its shared active documents. PR #142 changes planning/contracts only; +no CON runtime behavior became active. + +AUTH-09B PR #143 then merged to main at +`053242b90d927ace3fab92eeca72da27a61cecec`. The branch pulled it cleanly; +only the shared agent-gate test file overlapped. AUTH-09B activates controlled +`actor.service.provision`, not service admission or any REV action. + +CON-01 PR #144 then merged to main at +`e118e33afcd89b8ee78ecfc8f0e0d585ae0ee4b9`. The branch reconciled its +`architecture_data_model.md` overlap by retaining the exact shared +FinalAcceptance fields and ActorProfile/ReviewPolicy lineage. CON-01 publishes +the active CON contract and ADR 0016 but changes no runtime. + +ART-02A3 PR #141 then merged to main at +`a10d9018007d2e847b4870e9b26cbd24e24c7bb4`. It atomically removes +ArtifactStore v1 and activates the byte-only ART v2 LocalStorage clean cut plus +typed product capability composition. It does not implement S3/MinIO, +submission/checker artifact cutovers, lease-scoped review packet reads, or +review-evidence candidate/finalize behavior. + +AUTH-09C PR #146 then merged to main at +`0ffdabf3dbb77e4e066683fde1a095d744ff1f43`. The sole REV conflict was in the +shared agent-gate lifecycle assertions. The resolution retains REV's +branch-sensitive ART proof while adopting main's merged ART-02A3 and AUTH-09C +state. AUTH-09C activates only two bounded actor-registry reads and no REV +action. + +Chunk 01 adopts `docs/spec_review_lifecycle.md` as the active normative +contract, preserves the supplied WS-REV and WS-IMP archival Markdown/PDF bytes, +reconciles active documentation, and adds a fail-closed stale review-contract +gate. It changes no backend, migration, AUTH, ART, or CON runtime code. + +## Dependency state + +- AUTH-08 remains the historical 74-PermissionId, 57-ActionId snapshot: 9 + active and 48 planned. Current trusted main after AUTH-09C has 74 + PermissionIds and 65 ActionIds: 12 active and 53 planned. +- All 24 REV lifecycle action dependencies remain unavailable: planned + `submission.create`, 19 planned review actions, and four approved but + unregistered REV additions. The separately proposed ART evidence-binding + service action is not included in those 24. +- AUTH owns registration, service identity admission, evaluator integration, + activation, and prepared-mutation authority. REV publishes immutable feature + manifests and hidden behavior evidence; it does not activate actions. +- Merged AUTH-09B supplies controlled provisioning only for identities already + in AUTH's closed registry. None of REV's six identities exists yet; their + exact extensions, provisioning, AUTH-09E admission, and feature activation + remain downstream gates. +- Merged AUTH-09C supplies only bounded system-authorized actor-profile and + identity-link reads. It adds no REV identity or action and changes none of + REV's lifecycle, lease, artifact, or contribution boundaries. +- Merged ART-02A3 supplies the active byte-only ART v2 store beneath typed + product capabilities. Review still consumes only later approved packet-read + and evidence candidate/finalize ports; it never imports the raw byte store, + ART scratch/source types, a concrete provider, or repository APIs. +- Merged CON-01 publishes the canonical frozen-policy, ContributionRecord, + FinalAcceptance trigger, award, and ordered two-operation participant + contracts. It implements none of them. +- Later CON chunks must provide frozen contribution-policy persistence and the + ordered flush-only participant before a canonical Review can commit. Every + valid Review creates reviewer contribution; only an accept-created + FinalAcceptance creates submitter contribution. +- AUTH-owned contributor-field foundations, ART submission commitment and + packet-read contracts, CON persistence/participant contracts, and the + remaining per-chunk gates stay external prerequisites exactly as listed in + `CHUNK_MAP.md`. + +## Canonical lifecycle boundary + +- Every valid reviewer decision appends an immutable Review. Submitted findings + and later finding resolutions are also immutable history. +- `accept` additionally creates one internal immutable FinalAcceptance. The + submitter `accepted_submission` contribution consumes that fact rather than + inferring acceptance from `Review.decision`. +- `needs_revision` prepares a controlled next-attempt context. An exact match + with the currently active Project Guide identity and activation sequence keeps + context; any different internally consistent active pair rebases forward or + backward; missing or inconsistent active context blocks preparation. +- The reviewer always uses the Project Guide context stamped on the exact leased + Submission and never performs a separate review-guide rebase. +- `reject` blocks the submitter assignment and sets the Task to `rejected`. + Approved administrative revision-obligation closure uses `cancelled` with a + bounded reason. +- Adjudication remains disabled and unimplemented in v0.1. Reputation mutation + is deferred to its owning future initiative. Interfaces retain typed lineage + so either can be added later without changing the immutable Review contract. + +## Chunk 01 evidence state + +Candidate `6da45b2765de68dc5a0628024bdfeacb98d1ea85` passed all nine required +tracks against trusted current main +`053242b90d927ace3fab92eeca72da27a61cecec`: senior engineering, QA/test, +security/auth, product/ops, architecture, docs, reuse/dedup, test delta, and CI +integrity. All 80 current-main agent tests and seven REV additions are retained; +87 agent-gate tests and the deterministic contract gates pass. + +Chunk 01 is published as PR #145. CodeRabbit's nine actionable findings and one +Markdown lint nit were repaired without runtime or successor-scope expansion. +After ART-02A3 PR #141 advanced main, the branch merged and reconciled its +active byte-only v2 LocalStorage clean cut while retaining every later +review-facing ART gate. Candidate +`e239282e7d2a2b4d46137707f673f76fda55e4b8` passed the plan gate and all nine +internal reviewer tracks against +`0ffdabf3dbb77e4e066683fde1a095d744ff1f43`; 87 agent gates, Ruff, scanners, +links, checksums, renderer checks, merge-intent validation, and the exact +71-entry A/M reviewed-scope comparison pass. Status-change, removal, +rename-as-D+A, and addition probes fail closed. Replacement GitHub checks are +required after push. This chunk activates no review action or endpoint and does +not authorize merge. ## Stop condition -PR #128 may be refreshed only from the final reviewed branch with passing gates -and exact-SHA evidence. It still requires explicit human merge approval. Do not -start `WS-REV-001-01` or any runtime implementation; merge intent requires a -separate post-merge start. +After Chunk 01 is reviewed, merged with explicit human approval, and automated +merge memory records it, stop. Do not start `WS-REV-001-02` without a separate +explicit user instruction. diff --git a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-01-canonical-contract-adoption.md b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-01-canonical-contract-adoption.md index ac9aa5761..7aa2d0b02 100644 --- a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-01-canonical-contract-adoption.md +++ b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-01-canonical-contract-adoption.md @@ -14,15 +14,16 @@ L1 specification and architecture boundary. ## Allowed files ```text -docs/reference_specs/WS-REV-001-review-lifecycle-specification.md only to preserve recorded revised archival bytes -docs/reference_specs/WS-REV-001-review-lifecycle-specification.pdf only to preserve recorded revised archival bytes -docs/reference_specs/WS-IMP-001-workstream-v0.1-coding-agent-implementation-specification.md only to preserve recorded archival bytes -docs/reference_specs/WS-IMP-001-workstream-v0.1-coding-agent-implementation-specification.pdf only to preserve recorded archival bytes docs/reference_specs/README.md docs/reference_specs/SHA256SUMS docs/spec_review_lifecycle.md +docs/architecture_data_model.md docs/architecture_lockdown.md docs/architecture_lifecycle_state_machine.md +docs/architecture_system_architecture.md +docs/decision_0001_core_scope.md +docs/decision_0002_db_first_not_blockchain_first.md +docs/decision_0003_project_guides_are_first_class.md docs/decision_*.md only when an approved decision requires it docs/glossary.md docs/principles.md @@ -33,17 +34,34 @@ docs/operations_queue_policy.md docs/operations_payment_reputation.md docs/operations_operator_workflow.md docs/operations_project_operating_manual.md +docs/operations_roles_permissions.md docs/product_first_user_flows.md docs/risk_register.md +docs/roadmap_30_day_master_plan.md +docs/roadmap_day_by_day_execution_plan.md +docs/roadmap_implementation_backlog.md +docs/roadmap_pilot_plan.md +docs/roles_permissions.md docs/template_review_packet.md docs/template_revision_replay.md docs/template_prior_feedback_checklist.md docs/template_task_status.md +docs/template_project_guide.md +docs/spec_chunk_3_project_guide_foundation.md docs/architecture_brief/task_lifecycle_sequence.puml docs/architecture_brief/workstream_architecture_brief.md docs/architecture_brief/workstream_architecture_brief.pdf docs/architecture_brief/images/task_lifecycle_sequence.png +docs/architecture_brief/images/backend_v01_components.png +docs/architecture_brief/images/workstream_v01_container.png +docs/architecture_brief/render_pdf.sh docs/diagrams/task_lifecycle_sequence.md +docs/diagrams/backend_v01_components.md +docs/diagrams/backend_v01_components.puml +docs/diagrams/rendered/backend_v01_components.svg +docs/diagrams/workstream_v01_container.md +docs/diagrams/workstream_v01_container.puml +docs/diagrams/rendered/workstream_v01_container.svg README.md scripts/check_stale_review_contracts.py scripts/check_stale_artifact_contracts.py @@ -59,6 +77,10 @@ scripts/test_agent_gates.py backend/app/** backend/alembic/** backend/tests/** +docs/reference_specs/WS-REV-001-review-lifecycle-specification.md +docs/reference_specs/WS-REV-001-review-lifecycle-specification.pdf +docs/reference_specs/WS-IMP-001-workstream-v0.1-coding-agent-implementation-specification.md +docs/reference_specs/WS-IMP-001-workstream-v0.1-coding-agent-implementation-specification.pdf AUTH, ART, or CON runtime implementation modification or replacement of any supplied archival reference byte new provider choice @@ -70,6 +92,9 @@ frontend work - The supplied revised WS-REV Markdown/PDF pair and the WS-IMP pair remain byte-for-byte unchanged, separately hashed, and provenance-labelled as archival inputs. No `(2)` duplicate filename or one-sided pair edit remains. + Verification compares each literal archival hash and byte diff to trusted + base `0302bcf854a565d429e232ad6b076a1931ea74e4`, so changing an archive and its + checksum line together cannot pass. - Provenance explicitly records that the newest revised Markdown contains section 4.6's closed action/permission table while its PDF companion does not; adoption reconciles that difference without editing either archival file. @@ -102,18 +127,21 @@ frontend work - The active contract records merged AUTH-08 as 74 PermissionIds and 57 ActionIds split into 9 active actions and 48 planned actions. It identifies that count as historical. It records current trusted main after - AUTH-09A as 74 PermissionIds and 65 ActionIds split into 9 active and 56 - planned, and does not describe the authorization kernel as absent or treat - any of the 24 REV dependencies as active. + AUTH-09C as 74 PermissionIds and 65 ActionIds split into 12 active and 53 + planned; AUTH-09B activated `actor.service.provision`, and AUTH-09C activates + only `actor.profile.read` and `actor.identity_link.read`. It does not + describe the authorization kernel as absent, claim a REV service identity was + added, or treat any of the 24 REV dependencies as active. - The active contract records AUTH-08's rollback-only dependency teardown, typed authorization-evidence `503` mapping, and route-owned canonical verification timestamps as required regression invariants. Chunk 01 changes no AUTH implementation. -- The active contract records merged ART-02A2 as inactive committed-source and - private scratch preparation only. Review code never consumes - `ArtifactScratchManager`, `PreparedArtifact`, or `CommittedArtifactSource`, - persists scratch state, or treats ART-02A2 as reviewer read/intake readiness. - Chunk 01 changes no ART implementation. +- The active contract records merged ART-02A2 as the committed-source/private- + scratch foundation and merged ART-02A3 as the active byte-only v2 LocalStorage + clean cut. Review code never consumes `ArtifactScratchManager`, + `PreparedArtifact`, `CommittedArtifactSource`, or the raw byte store, persists + scratch state, or treats the store cutover as reviewer packet-read/evidence- + intake readiness. Chunk 01 changes no ART implementation. - The active contract's dependency inventory contains 24 non-executable review-lifecycle dependencies: registered planned `submission.create`, 19 registered planned review actions, and four approved but unregistered additions. The four @@ -137,9 +165,13 @@ frontend work dependency. Registration may then add four planned rows before REV-11/12A implementation; it activates nothing and does not claim hidden behavior exists. - The same active contract publishes six separate service identity-to-ActionId - manifests for preference expiry, lease expiry, authority-invalidation - reconciliation, general reconciliation, artifact-reference reconciliation, - and projection. AUTH may create separately reviewed identity-specific extension + manifests: `workstream.review.preference_expiry -> review.preference_expiry.run`, + `workstream.review.lease_expiry -> review.lease_expiry.run`, + `workstream.review.authority_invalidation_reconciliation -> review.reconcile.run`, + `workstream.review.reconciliation -> review.reconcile.run`, + `workstream.review.artifact_reference_reconciliation -> review.artifact_reference.reconcile`, + and `workstream.review.projection -> review.projection.rebuild`. AUTH may create + separately reviewed identity-specific extension contracts from that immutable manifest before the consuming REV chunk. Those extensions build on AUTH-09A's common schema but add exact enum, database constraint, matrix, provisioning, and admission coverage; AUTH-09A's seven ART @@ -149,11 +181,32 @@ frontend work noncanonical API prefix, full reviewer backlog, legacy severity, synthetic reject, direct payment/reputation, and bypass wording without scanning archival bytes as - active policy. + active policy. Its durable active-path classifier discovers tracked, staged, + untracked, and newly added documentation, excludes archival inputs by exact + path rather than broad directory suppression, and fails on an unclassified + active document. Every tracked or untracked Markdown, PlantUML, and HTML + documentation file is classified fail closed; only exact supplied archives, + exact reviewed historical records, and the explicit non-product + engineering-review protocol bypass active product scanning. + Table-driven regression fixtures cover every prohibited category, adversarial + lexical decoys, exact archival exclusion, unclassified-document rejection, + and fail-closed invocation from `scripts/test_agent_gates.py`. - Active reviewer/revision/queue/contribution flow docs and templates are reconciled now as contract/status documentation, clearly distinguishing planned unavailable endpoints from implemented behavior; the scanner has no temporary allowlist or exception that can outlive this chunk. +- The architecture brief render is byte-reproducible for the generated PDF and + lifecycle PNG. The render command fixes the PDF identifier and embeds full + fonts so repeated WeasyPrint runs do not create random subset names. Default + rendering rebuilds only Chunk 01's lifecycle PNG and PDF. This chunk uses + explicit source-specific rendering for the two reconciled context diagrams; + the other two context images remain trusted-base bound. +- The three active roadmap documents are reconciled. Discovery at chunk start + found neither ignored local export at `sheets/workstream_roadmap.xlsx` nor + `sheets/workstream_roadmap.csv`, and final verification records the same + absence. If either appears before completion, both must be updated together, + the XLSX must contain only `WorkStream RoadMap`, both exports must contain the + current Workstream definition, and no `sheets/` file may be committed. - Principles, lifecycle-state, and project-operating docs state the same deterministic one-guide rebase rule and the WS-CON creation matrix. Every valid decision appends an immutable Review; every submitted finding and later @@ -177,7 +230,7 @@ frontend work evidence commit with no feature/shared audit/outbox effects. - The active contract defines REV-owned `ReviewPacketManifest` and `ReviewEvidenceArtifact`, ART v2 packet-read/candidate-finalize boundaries, - exact binding service action, and no raw ArtifactStore version-1/provider access. + exact binding service action, and no raw byte-store/provider access. - The active contract maps XINT's conceptual `SubmissionVersion.artifact_hash` to a server-derived verified `artifact_hash` on the existing versioned `Submission`, copied to `ContributionRecord.artifact_hash`; caller @@ -196,9 +249,26 @@ frontend work - Human reject uses canonical task `rejected`; approved administrative revision-obligation closure uses `cancelled` with a bounded reason. No active `closed/review_rejected` status token is introduced. +- Initiative state records PLAN merged through PR #128 at trusted main + `0302bcf854a565d429e232ad6b076a1931ea74e4`, marks Chunk 01 active, and + reconciles `STATUS.md`, `CHUNK_MAP.md`, and `SOURCE_MANIFEST.md`. Generated + loop memory is not edited manually. ## Verification +The final PR-scope check intentionally uses trusted current main +`0ffdabf3dbb77e4e066683fde1a095d744ff1f43`, rather than the original planning +base `0302bcf854a565d429e232ad6b076a1931ea74e4`. Current main includes reviewed +sibling AUTH, CON, and ART changes that are dependencies of this chunk but are +not part of its PR scope. The committed reviewed-scope manifest records each +path's exact added or modified status. Rename detection is disabled so a rename +appears as a deletion plus an addition; any addition, deletion, rename, or +status change fails closed. This pinned comparison is a required local and +reviewer proof for this chunk, not a permanent repository-wide CI rule tied to +one historical base. Archival byte-integrity checks continue to use the +original planning base because those supplied inputs must remain unchanged +across the entire initiative. + ```text python3 scripts/check_stale_artifact_contracts.py python3 scripts/check_stale_authorization_docs.py @@ -206,17 +276,34 @@ python3 scripts/check_stale_review_contracts.py python3 scripts/check_markdown_links.py python3 scripts/check_stale_workstream_wording.py sha256sum -c docs/reference_specs/SHA256SUMS +printf '%s %s\n' \ + fffadc271c267801250b044edc570e515a250eff48afdc64f9c1f8753e6ab058 docs/reference_specs/WS-REV-001-review-lifecycle-specification.md \ + 8c053bc752a7b0c64e04b3eda1873bb5dbc02bbdfef84bd17d07cbbf01bce2fd docs/reference_specs/WS-REV-001-review-lifecycle-specification.pdf \ + e2116bce55fda1cce46a93e64bedcb47133d3898c1d4a51863385803e9dac210 docs/reference_specs/WS-IMP-001-workstream-v0.1-coding-agent-implementation-specification.md \ + 12f094e49c5c80f117e42d0f7f962b843f34508ab58d7f1d8def5f50fef532ed docs/reference_specs/WS-IMP-001-workstream-v0.1-coding-agent-implementation-specification.pdf | sha256sum -c - +git diff --exit-code 0302bcf854a565d429e232ad6b076a1931ea74e4 -- docs/reference_specs/WS-REV-001-review-lifecycle-specification.md docs/reference_specs/WS-REV-001-review-lifecycle-specification.pdf docs/reference_specs/WS-IMP-001-workstream-v0.1-coding-agent-implementation-specification.md docs/reference_specs/WS-IMP-001-workstream-v0.1-coding-agent-implementation-specification.pdf git check-attr diff merge text -- docs/reference_specs/*.pdf | awk '$3 != "unset" {bad=1} END {exit bad}' -./docs/architecture_brief/render_pdf.sh -git diff --exit-code -- docs/architecture_brief/workstream_architecture_brief.pdf docs/architecture_brief/images/task_lifecycle_sequence.png +: "${PLANTUML_JAR:?Set PLANTUML_JAR to the pinned PlantUML 1.2026.6 jar}" +printf '%s %s\n' 89948f14c93756c7a3fb7b69078ff37e8489fd79dd430c582b931e2f65358690 "$PLANTUML_JAR" | sha256sum -c - +java -jar "$PLANTUML_JAR" -version | grep -F "PlantUML version 1.2026.6" +./docs/architecture_brief/render_pdf.sh --review-context +./docs/architecture_brief/render_pdf.sh --review-context +git diff --exit-code -- docs/diagrams/rendered/backend_v01_components.svg docs/diagrams/rendered/workstream_v01_container.svg docs/architecture_brief/images/backend_v01_components.png docs/architecture_brief/images/workstream_v01_container.png docs/architecture_brief/workstream_architecture_brief.pdf docs/architecture_brief/images/task_lifecycle_sequence.png +git diff --exit-code 0302bcf854a565d429e232ad6b076a1931ea74e4 -- docs/architecture_brief/images/future_identity_payment_reputation.png docs/architecture_brief/images/workstream_context.png +test ! -e sheets/workstream_roadmap.xlsx +test ! -e sheets/workstream_roadmap.csv +test -z "$(git ls-files sheets/)" python3 scripts/test_agent_gates.py +python3 scripts/check_internal_review_evidence.py +test -z "$(git status --porcelain=v1 --untracked-files=all)" +git diff --name-status --no-renames 0ffdabf3dbb77e4e066683fde1a095d744ff1f43...HEAD | LC_ALL=C sort -k2,2 -k1,1 | diff -u .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-01-reviewed-scope.txt - git diff --check ``` ## Required reviewers Senior engineering, QA/test, security/auth, product/ops, architecture, docs, -reuse/dedup, and CI integrity if scanners change. +reuse/dedup, test delta, and CI integrity because scanner/tests change. ## Human review focus diff --git a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02-review-policy-task-alignment.md b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02-review-policy-task-alignment.md index b03130aea..aca85f1d9 100644 --- a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02-review-policy-task-alignment.md +++ b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02-review-policy-task-alignment.md @@ -1,4 +1,4 @@ -# Chunk Contract: WS-REV-001-02 +# Chunk Contract: WS-REV-001-02 - Locked Review Policy And Task Lifecycle Alignment ## Goal diff --git a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-07-review-context-finding-evidence.md b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-07-review-context-finding-evidence.md index 39731dd86..16f7c3fd6 100644 --- a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-07-review-context-finding-evidence.md +++ b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-07-review-context-finding-evidence.md @@ -50,10 +50,11 @@ production `/api/v1` review-router registration `review.decision`; the active owned lease and exact server-derived evidence scope are lifecycle/resource guards. Pre-intake denial creates no ART candidate, binding, or receipt. -- Merged ART-02A2 is preparation-only and does not satisfy this chunk's ART - gate. REV imports no ART scratch/source implementation. Chunk start requires - ART v2 submission/checker cutovers, a separately approved and merged ART-owner - amendment for the currently unassigned narrow packet-read port, and a +- Merged ART-02A2 supplies preparation and ART-02A3 supplies the byte-only v2 + LocalStorage clean cut; neither satisfies this chunk's review-facing ART gate. + REV imports no ART scratch/source or raw-store implementation. Chunk start + requires ART submission/checker cutovers, a separately approved and merged + ART-owner amendment for the currently unassigned narrow packet-read port, and a separately approved/merged `WS-ART-001-REV-EVIDENCE` candidate/finalize capability with canonical ART facts, guards, orphan retention, and tests. - Binding finalization requires separately registered planned action diff --git a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-13-live-drill-docs-release.md b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-13-live-drill-docs-release.md index ab90629d3..adf39c073 100644 --- a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-13-live-drill-docs-release.md +++ b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-13-live-drill-docs-release.md @@ -134,8 +134,9 @@ AUTH-13/14 command, participant-binding, task-submission behavior, or migration derives exact counts and SHAs from current trusted main, separately inventories the four additive REV actions and `artifact.review_evidence.binding.create`, and rejects missing/extra or early - activation. Neither historical 57/9/48 nor current-main AUTH-09A 65/9/56 is a - fixed expected total for this later release gate. + activation. Historical 57/9/48, 65/9/56, and AUTH-09B 65/10/55 plus + current-main AUTH-09C 65/12/53 are snapshots, not fixed expected totals for + this later release gate. AUTH-14 proof specifically covers one `submission.create` action for initial and prepared revision submission, the merged REV-09A preparation/replay participant, final locked-fact recomposition, misuse/denial behavior, and no diff --git a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-01-external-review-response.md b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-01-external-review-response.md new file mode 100644 index 000000000..92de4c867 --- /dev/null +++ b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-01-external-review-response.md @@ -0,0 +1,88 @@ +# WS-REV-001-01 External Review Response + +## PR + +- PR: `#145` +- Initial published head: `9ad0420e4c8f3ce0933a85fc75f133a340f91fcd` +- Reviewed repair candidate: `e239282e7d2a2b4d46137707f673f76fda55e4b8` +- Trusted base: `0ffdabf3dbb77e4e066683fde1a095d744ff1f43` + +## Comments Addressed + +- GitHub Agent Gates failed in `validate-merge-intent` because the declared + successor title did not match the first heading of the existing + `WS-REV-001-02` chunk contract. +- The successor heading now uses the canonical schema-v2 form and exactly + matches `Locked Review Policy And Task Lifecycle Alignment` from + `.agent-loop/merge-intents/WS-REV-001-01.json`. +- CodeRabbit's nine actionable comments were addressed: explicit pinned + PlantUML precondition; four-source `--all` rendering; FinalAcceptance as an + accept side effect; exact durable/final/current CheckerRun transition guards; + complete TaskAssignment attribution; both ART v2 storage passages; exact + checker routing outcomes; valid Markdown table cells; and explicit + `auto_reject_after_limit=false` configuration with runtime enforcement owned + by `WS-REV-001-02`. +- Its Markdown lint nit was addressed by reflowing the PR reference so a line + no longer begins with `#143`. +- The revision scanner now permits the required false configuration while + rejecting unquoted, quoted, JSON, and backticked truthy forms. The first + repair candidate's Ruff formatting failure was also corrected. +- ART-02A3 PR #141 later advanced main. The branch merged it, resolved the sole + glossary overlap by preserving both exact byte-store operations and narrow + typed product capabilities, and corrected Ruff formatting in four merged ART + gate assertions. Fresh exact-SHA internal review passed. +- CodeRabbit's later scope-verification comment was valid in requiring a + fail-closed comparison. The repair intentionally retains trusted current main + as the PR-scope base, documents why the original planning base is reserved + for archival immutability, and compares exact added/modified statuses against + a committed 71-entry manifest with rename detection disabled. +- Internal repair review then found that the first path-only manifest could not + distinguish an approved modification from deleting the same path. The final + status-aware manifest closes that gap; adversarial status-change, removal, + rename-as-delete-plus-add, and unreviewed-addition probes all fail. +- AUTH-09C PR #146 later advanced main. The branch resolved the sole conflict in + `scripts/test_agent_gates.py` by retaining all 80 main tests and seven REV + tests: main's AUTH-09C/merged ART assertions are current, and REV's earlier + ART phases remain fallback branches. The active REV contract now records + AUTH-09C's exact 65-action, 12-active, 53-planned snapshot without activating + any of the 24 unavailable REV dependencies. +- Internal plan review found three remaining records that called AUTH-09B's + 65/10/55 snapshot current. They now label AUTH-09B historical, AUTH-09C + 65/12/53 current, and future release counts dynamic. +- CodeRabbit's AUTH-09C follow-up correctly found that a committed-range scope + comparison alone ignores staged, unstaged, and untracked content. The final + verification now requires an entirely clean porcelain-v1 worktree before the + exact 71-entry comparison; isolated probes cover all three dirty states. +- Its Markdown-heading finding was repaired by keeping `PR #146` inline, and + its nit was addressed by naming the exact trusted-main and reviewed-code + operands in the evidence. + +## Comments Deferred + +- None. The ART comment's highlighted lower passage was already correct, but + its body identified an earlier raw `ArtifactStore` stack bullet; that earlier + occurrence was also updated rather than dismissing the finding as stale. + +## Human Decisions Needed + +- None. The repairs preserve the approved Chunk 01 contract and do not start + or implement Chunk 02. + +## Commands Rerun + +- `python3 scripts/update_post_merge_memory.py validate-merge-intent --base-ref origin/main` +- `python3 scripts/test_agent_gates.py` +- Ruff format/lint for both changed Python gate files. +- Stale artifact, authorization, review, and Workstream wording scanners. +- Markdown links, reference checksums, pinned PlantUML rendering, table-column + checks, scope checks, and `git diff --check`. +- Exact `--name-status --no-renames` manifest comparison plus adversarial + status-change, removal, rename, and addition probes. +- Exact-SHA plan gate and all nine required internal reviewer tracks. + +## Remaining Risks + +- Replacement GitHub checks and any CodeRabbit follow-up on the final repaired + PR head remain required after push. +- Runtime concurrency, rollback, and AUTH/ART/CON integration remain owned by + later implementation chunks. diff --git a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-01-internal-review-evidence.md b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-01-internal-review-evidence.md new file mode 100644 index 000000000..4416d4669 --- /dev/null +++ b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-01-internal-review-evidence.md @@ -0,0 +1,112 @@ +# WS-REV-001-01 Internal Review Evidence + +Reviewed code SHA: `e239282e7d2a2b4d46137707f673f76fda55e4b8` + +Trusted main SHA: `0ffdabf3dbb77e4e066683fde1a095d744ff1f43` + +Reviewed at: `2026-07-18T09:40:12Z` + +Reviewer run IDs: `/root/rev01_senior_arch_reuse`, `/root/rev01_qa_product_test`, `/root/rev01_security_docs_ci` + +Open sub-agent sessions: none + +Valid findings addressed: yes + +## Reviewer Results + +| Reviewer | Result | Blocking findings | Notes | +|---|---|---|---| +| Senior engineering | PASS | None | AUTH-09B is historical, AUTH-09C is current, and future catalogue counts remain dynamic | +| QA/test | PASS | None | All 80 main tests plus seven REV tests, exact 71-entry scope, and 87 executed gates verified | +| Security/auth | PASS | None | AUTH-09C activates only two bounded reads; all 24 REV dependencies remain unavailable | +| Product/ops | PASS | None | AUTH reconciliation changes no review lifecycle, runtime scope, or Chunk 02 behavior | +| Architecture | PASS | None | REV/AUTH/ART/CON ownership and current-main versus archival-base separation remain correct | +| Docs | PASS | None | AUTH-09C 65/12/53 current state and historical catalogue provenance are consistent | +| Reuse/dedup | PASS | None | Git status output and existing gates are reused without a parallel global scope mechanism | +| Test delta | PASS | None | All 80 trusted-main tests are AST-identical; seven REV tests add coverage | +| CI integrity | PASS | None | Conflict resolution preserves every gate, workflow, threshold, and exact A/M scope check | + +## Finding Disposition + +Earlier exact-SHA reviews are historical after the CON PR #142 and AUTH-09B +PR #143 main merges and the subsequent repair cycles. Every valid finding was +repaired before this review: FinalAcceptance field/provenance drift, canonical +transaction ordering, planned availability, automated exact CheckerRun +admission, checker versus Review-rooted revision lineage, non-mutating reject +sampling, executable structural regression coverage, and exact AUTH-09B +provisioning/action availability. PR #145's initial CI finding also aligned the +successor heading to the reviewed schema-v2 merge-intent title without starting +Chunk 02. CON-01's active specification and ADR 0016 were then adopted as +canonical CON authority without claiming runtime or removing downstream gates. +Candidate `694c02ac` received a fresh complete review rather than inheriting any +earlier approval. CodeRabbit then reported nine actionable findings and one +Markdown lint nit. The repair made FinalAcceptance an accept side effect, +strengthened exact CheckerRun transition guards, clarified TaskAssignment +attribution, aligned both ART v2 storage passages, generated all `--all` +PlantUML sources before conversion, repaired template tables, required explicit +false revision-limit auto-reject configuration with runtime enforcement deferred +to Chunk 02, and narrowed the scanner to reject truthy forms without rejecting +the required false form. A first repair candidate failed CI integrity only on +Ruff formatting; that mechanical defect was corrected. Candidate `f2493df` +then passed the plan gate and all nine reviewer tracks from fresh exact-SHA +review. ART-02A3 PR #141 later advanced main to `a10d901`, replacing v1 with +the active byte-only v2 LocalStorage clean cut. The branch merged that main, +combined ART's exact byte operations with REV's narrow typed-capability rule, +and retained S3/MinIO, submission/checker cutover, packet-read, and evidence +candidate/finalize as later gates. Candidate `3572835` failed only because four +merged ART assertions were not Ruff-formatted. Candidate `ca6b46b` contains the +mechanical repair and passed the plan gate and all nine reviewer tracks against +the new trusted main. CodeRabbit's next review correctly required the final +PR-scope listing to fail closed. Candidate `7742730` added a path-only +allowlist and documented why trusted current main, rather than the planning +base, defines current PR scope. Internal security/docs/CI review then found the +path-only form could not distinguish an approved modification from deletion of +that same file. Candidate `7785b832` replaces it with an exact +`--name-status --no-renames` A/M manifest. All 71 statuses match, while +adversarial status-change, removal, rename-as-D+A, and addition probes fail. +Candidate `5af0adc` adds only the required accurate review-log entry, and a +final exact-SHA review passed the plan gate and all nine tracks. AUTH-09C +PR #146 later advanced main to `0ffdabf3`. The branch resolved the single shared +agent-gate conflict without removing or semantically changing any of main's 80 +tests and retained all seven REV additions. Candidate `f1004158` passed eight +tracks, but plan/senior review found three records that still called AUTH-09B's +65/10/55 snapshot current. Candidate `a184e411` labels AUTH-09B historical, +AUTH-09C 65/12/53 current, and later release totals dynamic. Fresh exact-SHA +review passed the plan gate and all nine tracks. CodeRabbit then found that the +committed-range manifest could not detect a dirty worktree. Candidate +`e239282e` adds the required clean porcelain-v1 precondition. Isolated staged, +unstaged, and untracked probes fail as required, and all nine exact-SHA tracks +pass. + +## Deterministic Evidence + +- `python3 scripts/test_agent_gates.py`: 87 passed. +- All stale artifact, authorization, review-contract, and Workstream wording + scanners passed. +- Markdown link validation passed for 56 changed Markdown files. +- Ruff format and lint passed for both changed Python gate files. +- All reference-spec checksums passed; the WS-REV and WS-IMP archival pairs are + byte-identical to trusted base. +- PlantUML 1.2026.6 matched SHA-256 + `89948f14c93756c7a3fb7b69078ff37e8489fd79dd430c582b931e2f65358690`. + Pinned `--review-context` and isolated `--all` renders succeeded. The `--all` + run proved all four SVG sources render before conversion; out-of-scope future + diagram output was not committed. Prior repeated review-context renders + remained byte-identical, and visual inspection found no clipping or overlap. +- The two unrelated context images remain byte-identical to trusted base. +- Both local roadmap exports remain absent and no `sheets/` file is tracked. +- Exactly one merge-intent file exists for this chunk and `git diff --check` + passed. +- The committed 71-entry reviewed-scope manifest exactly matches + `git diff --name-status --no-renames 0ffdabf3dbb77e4e066683fde1a095d744ff1f43...e239282e7d2a2b4d46137707f673f76fda55e4b8`. + The clean-worktree prerequisite passes; simulated staged, unstaged, untracked, + status-change, removal, rename, and addition states fail the proof. + +## Residual Risks + +Runtime concurrency, database constraints, rollback behavior, and live +AUTH/ART/CON integration remain obligations of later implementation chunks. +The regex scanner is intentionally conservative and may need new fixtures for +future valid or prohibited phrasing. Rendering is pinned and repeat-checked, +but still relies on the documented host Pandoc, WeasyPrint, ImageMagick, JRE, +and font environment. diff --git a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-01-pr-trust-bundle.md b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-01-pr-trust-bundle.md new file mode 100644 index 000000000..58872d6aa --- /dev/null +++ b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-01-pr-trust-bundle.md @@ -0,0 +1,163 @@ +# WS-REV-001-01 PR Trust Bundle + +## Chunk + +`WS-REV-001-01`: Canonical Contract Adoption And Dependency Conformance. + +## Goal + +Preserve the supplied WS-REV and WS-IMP archival pairs byte-for-byte, adopt one +reconciled active review/revision contract, and align every active contract and +gate before runtime implementation. + +## Human-Approved Intent + +Every valid reviewer decision, submitted finding, and later resolution is +immutable. Accept additionally creates FinalAcceptance, which alone sources the +submitter contribution. Needs-revision prepares the next attempt against the +current Project Guide when required. Adjudication and reputation mutation are +not v0.1 behavior. + +## What Changed + +- Added `docs/spec_review_lifecycle.md` as the active normative contract. +- Reconciled architecture, ADRs, operations, templates, roadmaps, and diagrams. +- Added a fail-closed stale review-contract scanner and adversarial gate tests. +- Added registered structural regressions for canonical accept ordering, + CheckerRun admission, and checker-versus-human revision lineage. +- Preserved and proved all supplied archival inputs. +- Added deterministic pinned rendering for the lifecycle and two changed + context diagrams. +- Reconciled merged AUTH-09B's controlled provisioning capability and exact + `65 / 10 active / 55 planned` catalogue without activating any REV identity + or action. +- Reconciled merged AUTH-09C's two bounded actor-registry reads and exact + `65 / 12 active / 53 planned` catalogue while keeping all 24 REV + dependencies unavailable. +- Reconciled merged CON-01's active specification and ADR 0016 while retaining + its no-runtime status and downstream persistence/participant gates. +- Reconciled merged ART-02A3's active byte-only v2 LocalStorage clean cut while + preserving later S3, submission/checker, packet-read, and evidence gates. +- Addressed external lifecycle, checker-admission, ART terminology, rendering, + template, and revision-policy findings without expanding runtime scope. +- Added an exact 71-entry A/M scope manifest so additions, deletions, renames, + and status drift fail the final Chunk 01 review comparison. + +## Why It Changed + +Merged AUTH, ART, CON, and WS-XINT boundaries superseded parts of the archival +specification and older active docs. Runtime work needs one exact contract with +no contradictory status, transaction, identity, storage, or contribution +semantics. + +## Design Chosen + +REV owns immutable Review and FinalAcceptance facts plus lifecycle +orchestration. AUTH owns prepared authority and activation. ART v2 owns bytes +and typed artifact capabilities. CON joins the REV-owned caller transaction as +an ordered flush-only participant. The route or service command commits once. + +## Alternatives Rejected + +Editing archival inputs, direct Review-to-submitter contribution, review-time +guide rebasing, raw ArtifactStore access, CON-owned commits, synthetic reject, +mandatory payment, v0.1 adjudication/reputation, and early action activation +were rejected because they violate approved ownership or lifecycle boundaries. + +## Scope Control + +This is an L1 specification/architecture chunk. It changes no backend, +migration, frontend, AUTH, ART, or CON runtime implementation. All changed paths +and their exact added/modified statuses are listed by the chunk contract's +reviewed-scope manifest; exactly one merge intent is present. + +## Product Behavior + +No endpoint or action becomes available. The contract fixes the future behavior +for concealed current-work reads, claims, immutable decisions, accept, +needs-revision, reject, revision preparation, evidence access, contributions, +and payable-only awards. + +## Acceptance Criteria Proof + +Literal archive hashes and trusted-base diffs pass. Active documents and +roadmaps are scanner-clean. AUTH PREP and lock ordering are exact. Diagrams and +the architecture PDF reproduce byte-for-byte with the pinned renderer. Local +roadmap exports remain absent. + +## Tests/Checks Run + +`87 agent gate tests passed`; exact status-scope comparison and adversarial +status/removal/rename/addition probes, Ruff format/lint, four stale-contract +families, Markdown links, archive checksums/base diffs, PDF attributes, pinned +double render, spreadsheet absence, merge-intent count, and `git diff --check` +passed. + +## Test Delta + +The agent-gate suite gains table-driven prohibited-category coverage, +adversarial lexical decoys, exact archival classification, and fail-closed +discovery coverage. No test or assertion was removed or weakened. + +## CI Integrity + +No workflow, package script, coverage threshold, or existing gate was weakened. +This chunk adds a mandatory scanner invoked by the existing agent-gate suite. + +## Reviewer Results + +The plan gate and all nine required reviewer tracks passed exact SHA +`e239282e7d2a2b4d46137707f673f76fda55e4b8` against trusted main +`0ffdabf3dbb77e4e066683fde1a095d744ff1f43`: senior engineering, QA/test, +security/auth, product/ops, architecture, docs, reuse/dedup, test delta, and CI +integrity. No blocking findings remain. + +## External Review + +PR #145's initial Agent Gates run found a successor-heading/merge-intent title +mismatch, which was repaired without starting Chunk 02. After its cooldown, +CodeRabbit reported nine actionable findings and one Markdown lint nit. All +were addressed: accept ordering, exact checker guards, TaskAssignment and ART +wording, renderer source generation, template table structure, PlantUML +preconditions, and explicit false revision-limit configuration. The resulting +scanner also rejects quoted and unquoted truthy variants. The prior published +backend and Agent Gates runs passed. ART-02A3 then advanced main and was +reconciled through a fresh exact-SHA internal loop; replacement checks on the +new head remain external gates. CodeRabbit's later fail-closed scope comment +was addressed with an exact status manifest and an explicit current-main versus +archival-base rationale. Internal review caught and repaired the first +path-only version before publication. External checks supplement internal +review and do not replace it. + +AUTH-09C then advanced main and conflicted only in the shared agent-gate +lifecycle test. The resolution preserves all 80 main tests plus seven REV tests, +adopts the merged AUTH/ART state, and retains the earlier ART fallback branches. +Three stale catalogue-provenance statements found internally were corrected +before the final exact-SHA review. + +CodeRabbit then identified the dirty-worktree gap in the committed-range scope +proof. The final command requires a clean staged, unstaged, and untracked state +before comparing exact path statuses; isolated negative probes and a fresh +nine-track exact-SHA review pass. + +## Remaining Risks + +Runtime database, concurrency, rollback, and dependency integration proof is +deferred to its owning implementation chunks. Scanner fixtures may need updates +when future terminology changes. + +## Follow-Up Work + +`WS-REV-001-02` is the same-initiative successor but requires a separate +explicit human start after this PR merges and automated merge memory records it. + +## Human Review Focus + +Confirm archival provenance, active-contract precedence, AUTH/ART/CON ownership, +FinalAcceptance lineage, rebase semantics, unavailable v0.1 boundaries, and the +absence of unintended runtime work. + +## Human Merge Ownership + +Only the human may approve and merge this PR. Internal and external PASS results +do not authorize merge. diff --git a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-01-reviewed-scope.txt b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-01-reviewed-scope.txt new file mode 100644 index 000000000..fe3feb2dc --- /dev/null +++ b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-01-reviewed-scope.txt @@ -0,0 +1,71 @@ +M .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/CHUNK_MAP.md +M .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/DISCOVERY.md +M .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/PLAN.md +M .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/REVIEW_LOG.md +M .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/RISKS.md +M .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/SOURCE_MANIFEST.md +M .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/STATUS.md +M .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-01-canonical-contract-adoption.md +M .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-02-review-policy-task-alignment.md +M .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-07-review-context-finding-evidence.md +M .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-13-live-drill-docs-release.md +A .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-01-external-review-response.md +A .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-01-internal-review-evidence.md +A .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-01-pr-trust-bundle.md +A .agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/reviews/WS-REV-001-01-reviewed-scope.txt +A .agent-loop/merge-intents/WS-REV-001-01.json +M README.md +M docs/architecture_brief/images/backend_v01_components.png +M docs/architecture_brief/images/task_lifecycle_sequence.png +M docs/architecture_brief/images/workstream_v01_container.png +M docs/architecture_brief/render_pdf.sh +M docs/architecture_brief/task_lifecycle_sequence.puml +M docs/architecture_brief/workstream_architecture_brief.md +M docs/architecture_brief/workstream_architecture_brief.pdf +M docs/architecture_data_model.md +M docs/architecture_lifecycle_state_machine.md +M docs/architecture_lockdown.md +M docs/architecture_system_architecture.md +M docs/decision_0001_core_scope.md +M docs/decision_0002_db_first_not_blockchain_first.md +M docs/decision_0003_project_guides_are_first_class.md +M docs/decision_0009_review_decisions_are_canonical.md +M docs/decision_0010_revision_context_rebase.md +M docs/decision_0012_workstream_authorization_service.md +M docs/decision_0013_immutable_artifact_storage_boundary.md +M docs/decision_0015_project_contributor_roles_are_independent.md +M docs/diagrams/backend_v01_components.md +M docs/diagrams/backend_v01_components.puml +M docs/diagrams/rendered/backend_v01_components.svg +M docs/diagrams/rendered/workstream_v01_container.svg +M docs/diagrams/task_lifecycle_sequence.md +M docs/diagrams/workstream_v01_container.md +M docs/diagrams/workstream_v01_container.puml +M docs/glossary.md +M docs/operations_operator_workflow.md +M docs/operations_payment_reputation.md +M docs/operations_project_operating_manual.md +M docs/operations_queue_policy.md +M docs/operations_reviewer_workflow.md +M docs/operations_revision_replay.md +M docs/operations_roles_permissions.md +M docs/principles.md +M docs/product_first_user_flows.md +M docs/product_principles.md +M docs/reference_specs/README.md +M docs/reference_specs/SHA256SUMS +M docs/risk_register.md +M docs/roadmap_30_day_master_plan.md +M docs/roadmap_day_by_day_execution_plan.md +M docs/roadmap_implementation_backlog.md +M docs/roadmap_pilot_plan.md +M docs/roles_permissions.md +M docs/spec_chunk_3_project_guide_foundation.md +A docs/spec_review_lifecycle.md +M docs/template_prior_feedback_checklist.md +M docs/template_project_guide.md +M docs/template_review_packet.md +M docs/template_revision_replay.md +M docs/template_task_status.md +A scripts/check_stale_review_contracts.py +M scripts/test_agent_gates.py diff --git a/.agent-loop/merge-intents/WS-REV-001-01.json b/.agent-loop/merge-intents/WS-REV-001-01.json new file mode 100644 index 000000000..8575ab333 --- /dev/null +++ b/.agent-loop/merge-intents/WS-REV-001-01.json @@ -0,0 +1,9 @@ +{ + "chunk_id": "WS-REV-001-01", + "chunk_title": "Canonical Contract Adoption And Dependency Conformance", + "initiative_id": "WS-REV-001", + "next_chunk_id": "WS-REV-001-02", + "next_chunk_title": "Locked Review Policy And Task Lifecycle Alignment", + "next_requires_explicit_start": true, + "schema_version": 2 +} diff --git a/README.md b/README.md index c7f14122b..d174488ac 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ It is not a workspace and it is not blockchain-first. Operators can work with any local tools, human-agent workflow, or external execution environment. Workstream owns the project guide, task queue, submission packet, automated checks, human review, revision loop, contribution record, conditional -compensation award and fulfillment state, and reputation record. +compensation award and fulfillment state, and reputation signals. Workstream is source-agnostic, but v0.1 is manual-first. External origin onboarding, source adapters, automated routing, owner-agent execution workspaces, and on-chain settlement remain later adapters until the internal evaluation loop is proven. @@ -28,10 +28,10 @@ Project Guide -> Platform Checkers -> Human Review -> Needs Revision / Accepted / Rejected --> Final Acceptance on Accepted +-> FinalAcceptance on Accepted -> Contribution Record -> Compensation Award / Fulfillment when payable --> Reputation Update +-> Reputation projection when separately implemented -> Lessons Learned ``` @@ -49,13 +49,14 @@ Different projects speak different domain languages, but serious task evaluation - every submission has required artifacts, evidence references, hashes, and contributor attestation - every invalid submission packet is blocked before submission creation - every submission passes automated checks before human review -- every review creates a decision -- every revision must close prior feedback +- every valid human decision appends an immutable Review; submitted findings + and later resolutions are immutable +- every revision responds to unresolved blocking feedback without rewriting it - every valid human review creates a reviewer contribution - every accepted Review creates one immutable FinalAcceptance - every submitter accepted_submission contribution consumes FinalAcceptance - every payable contribution updates compensation fulfillment; all contributions - can update reputation + may feed a separately implemented reputation projection Workstream turns that operating knowledge into reusable infrastructure. @@ -89,6 +90,7 @@ Workstream turns that operating knowledge into reusable infrastructure. - [Workspace And Packet Convention](docs/operations_workspace_packet_convention.md) - [Reviewer Workflow](docs/operations_reviewer_workflow.md) - [Revision Replay](docs/operations_revision_replay.md) +- [Review And Revision Lifecycle](docs/spec_review_lifecycle.md) - [Roles And Permissions](docs/operations_roles_permissions.md) - [Authorization Service](docs/spec_authorization_service.md) - [Immutable Artifact Storage](docs/spec_artifact_storage_service.md) @@ -133,7 +135,7 @@ Workstream turns that operating knowledge into reusable infrastructure. - [ADR 0007: Execution Is Async-First](docs/decision_0007_async_first_execution.md) - [ADR 0008: Files Use An Object-Storage Abstraction](docs/decision_0008_object_storage_abstraction.md) - [ADR 0009: Review Decisions Are Canonical](docs/decision_0009_review_decisions_are_canonical.md) -- [ADR 0010: Revision Context Rebase Is Controlled By Policy](docs/decision_0010_revision_context_rebase.md) +- [ADR 0010: Revision Context Rebase Uses The Active Project Guide](docs/decision_0010_revision_context_rebase.md) - [ADR 0011: Submission Artifact Policy Drives Pre-Submit Intake](docs/decision_0011_submission_artifact_policy_drives_pre_submit.md) - [ADR 0012: Workstream Owns Product Authorization](docs/decision_0012_workstream_authorization_service.md) - [ADR 0013: Immutable Artifact Storage Boundary](docs/decision_0013_immutable_artifact_storage_boundary.md) @@ -259,9 +261,10 @@ Run checks Review packet Record review decision: accept, needs_revision, or reject Create reviewer contribution for every valid human review -On accept, create FinalAcceptance then create the submitter contribution only from it +For accept, create FinalAcceptance +Use FinalAcceptance as the sole source of the submitter contribution Record compensation status only for payable contribution awards -Update reputation from review outcome +Project reputation only after its separate implementation Review lessons learned ``` @@ -282,8 +285,10 @@ Governance: Lifecycle and revision: - status is a ledger, not a loose label -- revisions replay prior findings one by one -- revision context is prepared before resubmission when guide or policy versions change +- revisions append one response and later resolution per required prior finding +- revision context is prepared from the active Project Guide before + resubmission; exact stamped identity/activation-sequence match keeps context, + and any different valid active pair rebases forward or backward Artifacts, evidence, and auditing: @@ -294,8 +299,7 @@ Artifacts, evidence, and auditing: Contribution and compensation: - every valid human review creates a reviewer contribution from locked evidence -- accepted work creates an immutable FinalAcceptance, which is the sole source - for the submitter contribution +- for an accept decision, FinalAcceptance alone sources the submitter contribution - only payable contributions create immutable awards and fulfillment tracking; explicit unpaid rules create none - compensation fulfillment is recorded separately from task acceptance diff --git a/docs/architecture_brief/images/backend_v01_components.png b/docs/architecture_brief/images/backend_v01_components.png index 38276d6ce..527ca4770 100644 Binary files a/docs/architecture_brief/images/backend_v01_components.png and b/docs/architecture_brief/images/backend_v01_components.png differ diff --git a/docs/architecture_brief/images/task_lifecycle_sequence.png b/docs/architecture_brief/images/task_lifecycle_sequence.png index a2df9e778..51657a884 100644 Binary files a/docs/architecture_brief/images/task_lifecycle_sequence.png and b/docs/architecture_brief/images/task_lifecycle_sequence.png differ diff --git a/docs/architecture_brief/images/workstream_v01_container.png b/docs/architecture_brief/images/workstream_v01_container.png index ea40dde59..510fff2bb 100644 Binary files a/docs/architecture_brief/images/workstream_v01_container.png and b/docs/architecture_brief/images/workstream_v01_container.png differ diff --git a/docs/architecture_brief/render_pdf.sh b/docs/architecture_brief/render_pdf.sh index 0757df90d..0f9f6b11b 100755 --- a/docs/architecture_brief/render_pdf.sh +++ b/docs/architecture_brief/render_pdf.sh @@ -3,34 +3,72 @@ set -euo pipefail cd "$(dirname "$0")" +expected_jar_sha="89948f14c93756c7a3fb7b69078ff37e8489fd79dd430c582b931e2f65358690" +export SOURCE_DATE_EPOCH="${SOURCE_DATE_EPOCH:-0}" + +: "${PLANTUML_JAR:?Set PLANTUML_JAR to PlantUML 1.2026.6}" +printf '%s %s\n' "$expected_jar_sha" "$PLANTUML_JAR" | sha256sum -c - +java -jar "$PLANTUML_JAR" -version | grep -F "PlantUML version 1.2026.6" + mkdir -p images convert_diagram() { local source="$1" local target="$2" - convert -background white -density 180 "$source" -resize '2400x2400>' "$target" + local rendered + rendered="$(mktemp "${target%.png}.tmp.XXXXXX.png")" + convert -background white -density 180 "$source" -resize '2400x2400>' "$rendered" + if [[ -f "$target" ]] && compare -metric AE "$rendered" "$target" null: >/dev/null 2>&1; then + rm -f "$rendered" + else + mv "$rendered" "$target" + fi } -convert_diagram ../diagrams/rendered/workstream_context.svg images/workstream_context.png -convert_diagram ../diagrams/rendered/workstream_v01_container.svg images/workstream_v01_container.png -convert_diagram ../diagrams/rendered/backend_v01_components.svg images/backend_v01_components.png -convert_diagram ../diagrams/rendered/future_identity_payment_reputation.svg images/future_identity_payment_reputation.png - -if command -v plantuml >/dev/null 2>&1; then - plantuml -tpng task_lifecycle_sequence.puml -elif [[ -n "${PLANTUML_JAR:-}" ]]; then - java -jar "$PLANTUML_JAR" -tpng task_lifecycle_sequence.puml -else - echo "PlantUML is required to regenerate task_lifecycle_sequence.png" >&2 - echo "Set PLANTUML_JAR=/path/to/plantuml.jar or install plantuml." >&2 - exit 1 -fi +render_plantuml() { + java -jar "$PLANTUML_JAR" "$@" +} + +case "${1:-}" in + "") ;; + --review-context) + pushd ../diagrams >/dev/null + render_plantuml -tsvg -o rendered \ + backend_v01_components.puml \ + workstream_v01_container.puml + popd >/dev/null + convert_diagram ../diagrams/rendered/backend_v01_components.svg images/backend_v01_components.png + convert_diagram ../diagrams/rendered/workstream_v01_container.svg images/workstream_v01_container.png + ;; + --all) + pushd ../diagrams >/dev/null + render_plantuml -tsvg -o rendered \ + workstream_context.puml \ + workstream_v01_container.puml \ + backend_v01_components.puml \ + future_identity_payment_reputation.puml + popd >/dev/null + convert_diagram ../diagrams/rendered/workstream_context.svg images/workstream_context.png + convert_diagram ../diagrams/rendered/workstream_v01_container.svg images/workstream_v01_container.png + convert_diagram ../diagrams/rendered/backend_v01_components.svg images/backend_v01_components.png + convert_diagram ../diagrams/rendered/future_identity_payment_reputation.svg images/future_identity_payment_reputation.png + ;; + *) + echo "usage: $0 [--review-context|--all]" >&2 + exit 2 + ;; +esac + +render_plantuml -tpng task_lifecycle_sequence.puml +mogrify -strip task_lifecycle_sequence.png mv task_lifecycle_sequence.png images/task_lifecycle_sequence.png pandoc workstream_architecture_brief.md \ --standalone \ --from markdown+raw_html \ --pdf-engine=weasyprint \ + --pdf-engine-opt=--pdf-identifier=57532d5245562d3030312d3031 \ + --pdf-engine-opt=--full-fonts \ --css brief.css \ --metadata title="Workstream Architecture Brief" \ --resource-path=".:images" \ diff --git a/docs/architecture_brief/task_lifecycle_sequence.puml b/docs/architecture_brief/task_lifecycle_sequence.puml index 6245416a6..1313e5fdd 100644 --- a/docs/architecture_brief/task_lifecycle_sequence.puml +++ b/docs/architecture_brief/task_lifecycle_sequence.puml @@ -24,7 +24,7 @@ participant "FastAPI\nBackend" as API participant "Flow Auth\nVerifier" as Auth participant "Workstream\nAuthorization" as Authorization database "Postgres" as DB -participant "Storage\nAbstraction" as Storage +participant "ART v2\nCapabilities" as Artifacts participant "Checker\nRunner" as Checks PM -> UI : create project, guide, tasks,\nsetup/checker/review/revision configuration @@ -72,35 +72,61 @@ API -> Auth : verify Flow token Auth --> API : verified external identity API -> Authorization : require submission create + candidate grant\n+ ownership/resource/lifecycle guards Authorization --> API : allowed with matched submitter grant -API -> Storage : store/read artifact references +API -> Artifacts : finalize verified artifact bindings API -> DB : create immutable submission version API -> Checks : run automated checks async -Checks -> Storage : read artifacts +Checks -> Artifacts : read exact authorized artifacts Checks -> DB : persist checker results -Reviewer -> UI : submit review decision -UI -> API : accept / needs_revision / reject +Reviewer -> UI : request current work +UI -> API : GET current work API -> Auth : verify Flow token Auth --> API : verified external identity API -> Authorization : resolve actor profile and project grants -Authorization -> Authorization : require review decision + candidate grant\n+ assignment/resource/lifecycle guards +Authorization -> Authorization : require review.queue.read\n+ resource/lifecycle guards Authorization --> API : allowed with matched reviewer grant -API -> DB : lock active ReviewLease with frozen reviewer\nContributionPolicyVersion -API -> DB : store review decision -API -> DB : create reviewer completed_review contribution\n+ applicable award when payable +API --> UI : active lease / one server-selected offer / none + +Reviewer -> UI : claim server-selected offer +UI -> API : POST claim +API -> Auth : verify Flow token +Auth --> API : verified external identity +API -> Authorization : PREP review.claim with exact request bindings +Authorization --> API : opaque single-use prepared handle +API -> DB : lock idempotency, lifecycle fence, queue;\nlock task, assignment, Submission, CheckerRun;\nrecompose canonical final facts +API -> Authorization : consume prepared handle and evaluate final facts +Authorization --> API : allowed; authorization evidence staged +API -> DB : freeze reviewer policy; create ReviewLease\n+ ReviewPacketManifest; commit once +API --> UI : exact leased Review Context + +Reviewer -> UI : submit accept / needs_revision / reject +UI -> API : POST decision + immutable findings/resolutions +API -> Auth : freshly verify Flow token +Auth --> API : verified external identity +API -> Authorization : PREP review.decision with exact request bindings +Authorization --> API : opaque single-use prepared handle +API -> DB : lock idempotency, lifecycle fence, queue, lease;\nlock task, assignment, Submission, predecessor/evidence;\nrecompose canonical final facts +API -> Authorization : consume prepared handle and evaluate final facts +Authorization --> API : allowed; authorization evidence staged +API -> DB : append immutable Review/findings/resolutions;\nconsume lease and close queue +API -> DB : CON reviewer completed_review\n+ applicable award when payable alt needs_revision - API -> DB : create revision requirements - Contributor -> UI : submit revision replay - UI -> API : new submission version - API -> Checks : rerun checks + API -> DB : task needs_revision; keep assignment active else accept - API -> DB : create submitter accepted_submission contribution + API -> DB : append FinalAcceptance; accept task; complete assignment + API -> DB : CON submitter accepted_submission from FinalAcceptance API -> DB : create applicable submitter award when payable - API -> DB : create reputation event else reject - API -> DB : store rejection findings - API -> DB : apply reviewer reputation effects\n+ no submitter contribution + API -> DB : block assignment; reject task\n+ no FinalAcceptance or submitter contribution +end +API -> DB : stage shared audit/outbox and commit once\n(no ART call in decision transaction) + +opt needs_revision after decision commit + API -> DB : in a later authorized transaction, append frozen\nRevisionContextPreparation + Contributor -> UI : submit finding responses + UI -> API : replacement Submission bound to preparation head + API -> Checks : rerun checks end @enduml diff --git a/docs/architecture_brief/workstream_architecture_brief.md b/docs/architecture_brief/workstream_architecture_brief.md index 187a548f7..9773a141d 100644 --- a/docs/architecture_brief/workstream_architecture_brief.md +++ b/docs/architecture_brief/workstream_architecture_brief.md @@ -20,14 +20,18 @@ Workstream is how Flow measures, certifies, and coordinates useful human-agent w ## Executive Summary -Workstream is the operating system for useful work inside Flow. It does not try to own every possible execution environment. Instead, it gives every project a guide, every task a locked policy context, every submission an evidence packet, every review a canonical decision and reviewer contribution, and every accepted task an additional submitter contribution before compensation and reputation events. +Workstream does not try to own every execution environment. It gives every +project a guide, every task a locked policy context, every Submission an +evidence packet, every valid human decision an immutable Review and reviewer +contribution, and every accepted task an immutable FinalAcceptance before the +submitter contribution and conditional compensation. The first 30 days are focused on proving the internal lifecycle: ```text Project Guide -> Task Queue -> Submission Packet -> Checks -> Review --> Revision / Acceptance / Rejection -> Contribution Record --> Compensation Award / Fulfillment -> Reputation Event +-> Revision / FinalAcceptance / Rejection -> Contribution Record +-> Compensation Award / Fulfillment -> deferred reputation projection ```
@@ -44,7 +48,7 @@ Current v0.1 is backend-first and internal-loop-first. External source adapters, | Postgres record database | Local, CI, and production-like development use Postgres as the record database. | | Object-storage abstraction | Local filesystem storage is allowed only behind the provider-neutral `ArtifactStore`; AWS S3 is the v0.1 hosted provider and MinIO is the local/CI protocol proof. | | Async-first execution | Long-running checker work does not block request/response paths. | -| Contribution before compensation | Every valid human Review creates a reviewer contribution; accepted work creates REV-owned FinalAcceptance, which alone sources the submitter contribution. Compensation and reputation attach afterward. | +| Contribution before compensation | Every valid human Review creates a reviewer contribution. FinalAcceptance is created only for accept and is the sole source of the submitter contribution. Compensation may attach afterward; reputation is deferred. |
@@ -58,9 +62,10 @@ The context diagram shows Workstream as one system inside the broader Flow ecosy ### What This Means -- Project managers, contributors, reviewers, adjudicators, operators, Finance +- Project managers, contributors, reviewers, operators, Finance Authorities, Access Administrators, and Audit Authorities interact with Workstream through their independent grants. +- Adjudicator grants are independent but authorize no v0.1 lifecycle or action. - Flow identity remains the human identity and auth source. - Postgres is the record database. - Storage sits behind an object-storage abstraction. @@ -84,7 +89,7 @@ The container view shows the first 30-day implementation. It is intentionally sm | Container | Responsibility | | --- | --- | -| React + Vite operations UI | Planned internal operations dashboard for project, task, submission, review, compensation fulfillment, and reputation workflows. | +| React + Vite operations UI | Planned internal operations dashboard for project, task, submission, review, and compensation fulfillment workflows. Reputation UI remains deferred. | | FastAPI backend | API contracts, workflow rules, auth dependency, lifecycle guards, module orchestration, and audit writes. | | Celery worker boundary | Durable project setup, checker, and background product-job execution. FastAPI background tasks are not the Workstream product-job boundary. | | Checker runner | Executes automated checks and stores checker results. | @@ -108,7 +113,7 @@ The backend component view zooms into the FastAPI container. It shows how the mo | Boundary | Responsibility | | --- | --- | | HTTP + auth boundary | Routers handle HTTP only. Actor resolution, permission checks, and Pydantic request/response validation stay at the boundary. | -| Workflow services | Project guide, task queue, submission, checker, review/revision, and contribution/compensation/reputation services own business rules. | +| Workflow services | Project guide, task queue, submission, checker, review/revision, and contribution/compensation services own business rules; reputation remains deferred. | | Shared domain rules | Lifecycle guards and audit writes stay shared instead of being scattered through routers. | | Persistence boundary | Repositories own SQLAlchemy async persistence and Postgres access. | | External ports/adapters | Flow auth, storage, and checker execution stay behind interfaces. | @@ -129,10 +134,10 @@ The sequence below shows the narrow v0.1 loop the system must prove before expan published contribution policy version to freeze. - A contributor submission creates a new immutable submission version; locked artifacts are not edited in place. - Review decisions are exactly `accept`, `needs_revision`, or `reject`. -- `needs_revision` starts a revision loop and must replay prior findings. -- Every valid human review creates a reviewer contribution; accepted work - additionally creates a submitter contribution before compensation or - reputation records. +- `needs_revision` preserves immutable findings, responses, preparations, and + later resolutions. +- Every valid human Review creates a reviewer contribution; accept additionally + creates FinalAcceptance, which alone sources the submitter contribution. - Compensation fulfillment status is separate from task acceptance.
@@ -180,7 +185,7 @@ Future ERC-8004, ERC-8183, x402, OmniClaw, and USDC integrations do not replace - human review and revision replay - contribution records - compensation award, receipt, and fulfillment projection records -- reputation events +- reputation events (later, separately approved) - audit events ### Later Adapter Boundaries @@ -194,9 +199,14 @@ Future ERC-8004, ERC-8183, x402, OmniClaw, and USDC integrations do not replace - OmniClaw settlement orchestration - USDC payout execution - marketplace discovery +- adjudication lifecycle, actions, queues, leases, and decisions ## Closing -Workstream v0.1 succeeds when it can run real internal work from project guide to reviewer/submitter contributions with evidence, checks, human review, revision discipline, conditional compensation awards, fulfillment status, and reputation events. +Workstream v0.1 succeeds when it can run real internal work from project guide +to reviewer/submitter contributions with evidence, checks, immutable human +review, revision discipline, FinalAcceptance, conditional compensation awards, +and fulfillment status. The active review contract is +`docs/spec_review_lifecycle.md`; its surfaces remain unavailable until REV-13. The system should expand only after that loop is proven. diff --git a/docs/architecture_brief/workstream_architecture_brief.pdf b/docs/architecture_brief/workstream_architecture_brief.pdf index da014810e..26811596f 100644 Binary files a/docs/architecture_brief/workstream_architecture_brief.pdf and b/docs/architecture_brief/workstream_architecture_brief.pdf differ diff --git a/docs/architecture_data_model.md b/docs/architecture_data_model.md index e9dfcf7c2..ce3dfedbb 100644 --- a/docs/architecture_data_model.md +++ b/docs/architecture_data_model.md @@ -42,16 +42,21 @@ Task CheckerRun CheckerResult ReadinessCertificate (later optional) + ReviewQueueEntry + ReviewLease + ReviewPacketManifest Review ReviewFinding + ReviewEvidenceArtifact + FindingResolution FinalAcceptance (accept only) - RevisionReplay RevisionContextPreparation + SubmissionFindingResponse ContributionRecord CompensationAward CompensationFulfillmentReceipt CompensationStatusProjection - ReputationEvent + ReputationEvent (deferred) AuditEvent ``` @@ -99,9 +104,11 @@ role-specific qualification snapshot, reason, and active/revoked state. Contributor is the umbrella human product term. A human may hold separate active `submitter`, `reviewer`, and `adjudicator` grants for the same project; -each is revoked independently. An adjudicator grant authorizes no adjudication -action until WS-REV defines the lifecycle and AUTH activates exact adjudication -actions. Celery, checker, setup, and background workers are internal services, +each is revoked independently. An adjudicator grant authorizes no v0.1 action. +The review lifecycle defines no adjudication policy, queue, state, decision, or +API; a future separately approved initiative owns any lifecycle definition, +authorization, and release. Celery, checker, +setup, and background workers are internal services, not human product roles. ### QualificationSnapshot @@ -898,7 +905,6 @@ Fields: - `id` - `project_id` - `guide_version` -- `requires_second_review` - `allowed_decisions` - `minimum_finding_fields` - `sla_hours` @@ -913,14 +919,15 @@ Fields: - `guide_version` - `max_revision_rounds` - `revision_deadline_hours` -- `auto_reject_after_limit` - `allowed_resubmission_states` -- `context_rebase_rule` -- `context_rebase_triggers` - `reviewer_reassignment_rule` - `created_at` -`context_rebase_rule` defines whether a revision attempt keeps prior context, rebases to current active context, or blocks for project-manager repair when guide or policy context changed. `context_rebase_triggers` names the guide or policy changes that require preparation before the contributor resumes. +Limit or deadline exhaustion blocks further preparation and submission; it does +not synthesize a reject Review. Project Guide context selection is deterministic, +not policy-selected: exact prior Submission identity/activation-sequence match +keeps context, any different valid active pair rebases forward or backward, and +missing or unsafe active context blocks for manager repair. ## ContributionPolicy @@ -1132,15 +1139,19 @@ Fields: - `id` - `task_id` +- `task_assignment_id` - `contributor_id` - `version` - `status` - `summary` - `package_uri` -- `package_hash` +- `package_hash` (legacy caller input, never canonical artifact lineage) +- `artifact_hash` (server-derived verified lineage) - `artifact_hash_manifest` - `contributor_attestation` - `locked_guide_version` +- `locked_guide_id` +- `locked_guide_activation_sequence` - `locked_guide_source_snapshot_id` - `locked_guide_source_snapshot_hash` - `locked_effective_project_submission_artifact_policy_id` @@ -1156,6 +1167,7 @@ Fields: - `submitted_at` - `locked_at` - `supersedes_submission_id` +- `revision_context_preparation_id` (revision submissions only) The contributor submission packet supplies the task id, summary, outputs, artifact hashes, evidence references, and contributor attestation. Workstream assigns the @@ -1346,12 +1358,33 @@ If added later, the readiness certificate records the exact checker run and arti For v0.1, the current `CheckerRun` is the readiness proof. If any submitted artifact changes, a new submission version and checker run are required. +## ReviewQueueEntry And ReviewLease + +`ReviewQueueEntry` immutably anchors one exact finalized Submission and its +current successful admitting CheckerRun. Mutable routing state carries +preferred/open/closed lifecycle, original queue age, and current preference. +The reviewer current-work API returns an active lease, one server-selected +offer, or none; it never exposes the full backlog. + +`ReviewLease` is the permanent identity of one claim attempt. It stores the +canonical human reviewer ActorProfile ID, queue/Submission lineage, database +lease times, disposition, and the independently frozen reviewer +ContributionPolicyVersion. PostgreSQL enforces one active lease per reviewer and +queue entry. + +`ReviewPacketManifest` is an immutable REV semantic projection over the exact +lease, Submission, admitting CheckerRun/results, stamped context, response +evidence, and ART binding IDs. It contains no bytes, digest, provider locator, +signed URL, receipt, scratch path, or AUTH matrix data. + ## Review Fields: - `id` - `submission_id` +- `review_lease_id` +- `predecessor_review_id` - `reviewer_id` - `decision` - `summary` @@ -1362,6 +1395,9 @@ Fields: - `created_at` - `completed_at` +The Review and its submitted findings/resolutions are immutable. Later rounds +append a new Review following the Submission predecessor chain. + Decision: - accept @@ -1374,51 +1410,42 @@ Fields: - `id` - `review_id` -- `severity` +- `finding_kind`: `blocking | advisory` - `area` - `issue` - `required_fix` -- `evidence_ref` - `created_at` -Severity: - -- low -- medium -- high - -## RevisionReplay +## ReviewEvidenceArtifact Fields: - `id` -- `task_id` -- `prior_submission_id` -- `new_submission_id` -- `created_by` +- `project_id` +- `review_id` (nullable, exactly one purpose owner) +- `review_finding_id` (nullable, exactly one purpose owner) +- `submission_finding_response_id` (nullable, exactly one purpose owner) +- `finding_resolution_id` (nullable, exactly one purpose owner) +- `artifact_binding_id` +- `evidence_purpose` +- `created_by_actor_id` - `created_at` -Each replay has items: - -- `prior_finding_id` -- `fix_summary` -- `evidence_ref` -- `contributor_claim_status` -- `reviewer_closure_status` +This immutable REV relation binds one ART-finalized ArtifactBinding to the exact +review, finding, response, or resolution evidence slot. Exactly one purpose owner is set, +all lineage is same-project and same-task, and the row stores no bytes, digest, +provider locator, signed URL, receipt, scratch path, or credentials. -Contributor claim status: +## SubmissionFindingResponse And FindingResolution -- fixed -- disputed -- not_applicable +`SubmissionFindingResponse` immutably binds one unresolved blocking finding to +the assigned submitter's response text, optional finalized evidence binding, +exact preparation head, and new Submission. Advisory responses are optional +unless locked policy requires them. -Reviewer closure status: - -- closed_fixed -- closed_rebutted -- partially_closed -- still_open -- obsolete +`FindingResolution` is appended by the later Review for each required prior +finding. Its result is `resolved`, `unresolved`, or `not_applicable`; it carries +bounded rationale/evidence and never edits the finding or response. ## RevisionContextPreparation @@ -1426,11 +1453,18 @@ Fields: - `id` - `task_id` +- `originating_review_id` +- `source_task_assignment_id` +- `target_task_assignment_id` - `prior_submission_id` - `prior_submission_version` - `next_submission_version` +- `prior_locked_guide_id` - `prior_locked_guide_version` +- `prior_locked_guide_activation_sequence` +- `next_locked_guide_id` - `next_locked_guide_version` +- `next_locked_guide_activation_sequence` - `prior_locked_effective_project_submission_artifact_policy_hash` - `next_locked_effective_project_submission_artifact_policy_hash` - `prior_locked_pre_submit_checker_bundle_hash` @@ -1439,7 +1473,11 @@ Fields: - `next_locked_review_policy_version` - `prior_locked_revision_policy_version` - `next_locked_revision_policy_version` -- `context_rebased` +- `outcome`: `kept | rebased | blocked` +- `direction`: `forward | backward | null` +- `context_digest` +- `predecessor_preparation_id` +- `preparation_sequence` - `rebase_reason` - `change_summary` - `prepared_by` @@ -1448,14 +1486,22 @@ Fields: Purpose: -This record is created before a contributor resumes a task in `NEEDS_REVISION` when guide or policy context must be checked for the next attempt. It does not mutate the prior submission. It records whether the next attempt keeps the prior context or rebases to the current active guide and policy context under revision policy. +This immutable Review-rooted record is created before a contributor resumes a +human-review revision. Exact prior Submission guide identity/activation-sequence +match with the currently active guide keeps context. Any different valid active +pair rebases forward or backward. Missing, inconsistent, revoked, or unsafe +context blocks for manager repair. Task Context returns the validated chain +head. No guide rebase occurs during review; the reviewer reads the context +stamped on the leased Submission. Revision preparation never rebases award eligibility. Submitter eligibility remains governed by the TaskAssignment-frozen `ContributionPolicyVersion`; each new ReviewLease independently freezes the then-current `ContributionPolicyVersion` for reviewer contributions. -The contributor and reviewer packets must show the prior version, next version, rebase reason, and change summary when `context_rebased = true`. +The contributor and reviewer history show prior/next identity, activation +sequence, direction, reason, and change summary. No ContributionPolicyVersion is +stored in this preparation. ## FinalAcceptance @@ -1476,9 +1522,10 @@ Purpose: This immutable REV-owned internal fact is created only inside the authorized `Review(accept)` transaction. Existing `Submission` is already the version identity, so the stored FK is `submission_id`; no SubmissionVersion entity or -`submission_version_id` alias is introduced. `policy_context_ref` is the exact -locked ReviewPolicy context for the accepted Review, and `recorded_by` is the -canonical reviewer ActorProfile. +`submission_version_id` alias is introduced. `recorded_by` is the canonical +human reviewer `ActorProfile.id` on the source Review and ReviewLease. +`policy_context_ref` is a foreign key to the exact immutable `ReviewPolicy.id` +whose project and guide version match the reviewed Submission context. PostgreSQL enforces `UNIQUE(task_id)`, `UNIQUE(source_review_id)`, and `UNIQUE(submission_id)` plus same-project/task/Submission/Review/submitter/ @@ -1521,8 +1568,8 @@ direct Review/lease sources. Partial unique constraints enforce one `completed_review` per Review and one `accepted_submission` per FinalAcceptance; database checks reject mixed or incomplete source shapes. The record carries the exact Submission, actor, frozen contribution policy, and -stabilized artifact-hash lineage. Compensation awards and reputation events may -reference it, but do not replace it. +stabilized artifact-hash lineage. Compensation awards may reference it but do +not replace it; reputation projection remains deferred. ## CompensationAward @@ -1613,12 +1660,13 @@ Event types: - revision_closed - contribution_recorded - compensation_fulfilled -- review_quality_audit_completed -- review_quality_issue_flagged +- review_quality_sampled +- review_feedback_flagged -Reviewer-quality events are non-mutating observations. They cannot reopen or -replace Review, FinalAcceptance, task, contribution, or award truth and are not -adjudication decisions. +This entire record is deferred to a separate reputation initiative. Future +review-quality inputs are offline non-product evidence: they cannot alter an +immutable Review, create another product decision, or introduce adjudication +state. ## AuditEvent @@ -1672,12 +1720,12 @@ open an independent session. registered scoped permission and cannot bypass missing task policy context - a submission must belong to a task - a review must belong to a submission -- an accepted task must have exactly one immutable FinalAcceptance bound to its - accepted Submission and source Review +- an accepted task must have exactly one FinalAcceptance linked to its accepting + Review and versioned Submission - every valid recorded human review must create one reviewer `completed_review` contribution -- every FinalAcceptance must create one submitter `accepted_submission` - contribution in the same transaction +- an accepted task must additionally create one submitter + `accepted_submission` contribution sourced from FinalAcceptance - `needs_revision` and `reject` must not create FinalAcceptance or a submitter contribution - FinalAcceptance is unique per task, source Review, and Submission and has no @@ -1687,9 +1735,8 @@ open an independent session. - no compensation award exists without its contribution record - a fulfilled award must have an immutable fulfillment receipt with the exact authorized quantity and external reference -- reputation events for accepted work must reference the submitter contribution -- reviewer-quality reputation events must reference the reviewer contribution, - Review, or audit source +- review-lifecycle v0.1 creates no reputation event; future reputation records + must consume canonical contribution/review lineage without mutating it - compensation award quantity is immutable after creation - failed fulfillment may later receive one valid fulfilled receipt; a fulfilled award is terminal and rejects conflicting callbacks @@ -1701,7 +1748,8 @@ open an independent session. - the current checker run is the v0.1 readiness proof for the submission version that cleared automated checks - a review cannot accept a submission if the checker run belongs to a different submission version - every status transition creates an audit event -- every needs-revision decision has at least one review finding +- every needs-revision decision has at least one unresolved blocking + ReviewFinding - every revision context rebase creates an audit event and preserves prior submission context - every accept decision cites evidence - repeated review/checker failures become ProjectLesson records diff --git a/docs/architecture_lifecycle_state_machine.md b/docs/architecture_lifecycle_state_machine.md index 9d25491f2..4598a3ae5 100644 --- a/docs/architecture_lifecycle_state_machine.md +++ b/docs/architecture_lifecycle_state_machine.md @@ -137,9 +137,11 @@ Automated checks passed or produced only non-blocking warnings. A human reviewer Required before entering: -- checker run exists for the exact submission version -- checker run references the same artifact hashes as the submission packet -- no unresolved blocking checker failure is open under the locked post-submit checker policy +- durable, final CheckerRun is current for the exact Submission version +- CheckerRun outcome is exactly `allow_review` +- CheckerRun references the same artifact hashes as the Submission packet +- no unresolved blocking checker failure is open under the locked post-submit + checker policy ### NEEDS_REVISION @@ -153,13 +155,19 @@ This state can be entered from: Required before entering: - from `EVALUATION_PENDING`: checker run id, blocking checker results, contributor-visible messages, and suggested fixes -- from `REVIEW_PENDING`: review decision id, at least one structured review - finding, reviewer `completed_review` contribution, and any applicable reviewer - award +- from `REVIEW_PENDING`: immutable `needs_revision` Review, at least one + unresolved blocking ReviewFinding, reviewer `completed_review` contribution, + and any applicable reviewer award - from `REVIEW_PENDING`: the same TaskAssignment remains `active`, with no FinalAcceptance or submitter contribution -Before the contributor resumes, Workstream prepares the next revision context. That preparation checks whether the active project guide or policy context changed since the prior submission was locked. Revision policy decides whether the next attempt keeps the prior context, rebases to the current active context, or is blocked for project-manager repair. +Before the contributor resumes from a human Review, Workstream appends an +immutable RevisionContextPreparation. Exact prior Submission guide +identity/activation-sequence match with the currently active guide keeps +context. Any different valid active pair rebases forward or backward. Missing, +inconsistent, revoked, or unsafe context blocks for Project Manager repair. +Checker-caused remediation remains CheckerResult-rooted and creates no Review +episode. A revision context rebase never mutates the prior submitted attempt. It only stamps the next submission attempt. The contributor and reviewer must see the prior version, the next version, and the guide or policy change summary. @@ -170,25 +178,25 @@ The submission is accepted. Required before entering: - accepted review decision -- one immutable FinalAcceptance bound to the accepted Review, existing - versioned Submission, task, submitter, recording reviewer, and locked - ReviewPolicy - no unresolved blocking checker failure under the locked post-submit checker policy - evidence present - reviewer cited evidence supporting acceptance -- no unresolved high or medium prior revision finding +- no unresolved blocking prior ReviewFinding - applicable submitter compensation evaluated from the TaskAssignment-frozen contribution policy Required side effects: - reviewer `completed_review` contribution created with the Review +- immutable FinalAcceptance created from the accepting Review and bound to the + existing versioned Submission, task, submitter, recording reviewer, and locked + ReviewPolicy - submitter `accepted_submission` contribution created from FinalAcceptance, the exact TaskAssignment, frozen policy lineage, and artifact hash; it is not inferred directly from Review.decision - applicable awards created independently from the reviewer and submitter contribution records -- reputation events reference the applicable contribution record +- reputation projection remains deferred ### REJECTED @@ -199,6 +207,8 @@ Required before entering: - rejection review decision - bounded human rejection reason - reviewer `completed_review` contribution and any applicable reviewer award +- the same-task TaskAssignment is blocked +- no FinalAcceptance or submitter contribution is created Required side effects: @@ -208,7 +218,9 @@ Required side effects: ### CANCELLED -The task is cancelled before acceptance. +The task is cancelled before acceptance. An authorized revision-limit/deadline +or legacy-context closure uses this state with a bounded reason, releases the +assignment, and creates no synthetic Review or contribution. ## Allowed Transitions @@ -227,6 +239,7 @@ REVIEW_PENDING -> ACCEPTED REVIEW_PENDING -> NEEDS_REVISION REVIEW_PENDING -> REJECTED NEEDS_REVISION -> SUBMITTED +NEEDS_REVISION -> CANCELLED DRAFT -> CANCELLED SCREENING -> CANCELLED READY -> CANCELLED @@ -238,13 +251,16 @@ IN_PROGRESS -> CANCELLED No administrative or recovery grant authorizes these transitions: -- `SUBMITTED -> REVIEW_PENDING` without checker run +- `EVALUATION_PENDING -> REVIEW_PENDING` without a durable, final, current CheckerRun + whose outcome is exactly `allow_review`, whose Submission version is exact, + and whose artifact binding is verified - `REVIEW_PENDING -> ACCEPTED` without review decision -- `REVIEW_PENDING -> ACCEPTED` without exactly one FinalAcceptance -- `REVIEW_PENDING -> ACCEPTED` without contribution record creation -- `NEEDS_REVISION -> ACCEPTED` without new submission or explicit finding closure +- `REVIEW_PENDING -> ACCEPTED` without Review, FinalAcceptance, and both required contribution-source checks +- `NEEDS_REVISION -> ACCEPTED` directly; a replacement Submission must pass + checker admission and receive a later accepting Review - `SUBMITTED -> ACCEPTED` directly -- `SUBMITTED -> NEEDS_REVISION` without checker run unless the submission packet cannot be parsed +- `SUBMITTED -> NEEDS_REVISION` directly without the persisted + `EVALUATION_PENDING` CheckerRun outcome - any transition based on artifacts whose hashes differ from the checker run - compensation projection `pending -> fulfilled` without an immutable payable award and fulfillment receipt @@ -264,31 +280,27 @@ submission v2 -> accepted Each resubmission must link to the prior submission it supersedes. -Each submitted version keeps its own locked guide and policy context. If a later revision is rebased to a newer active guide, that rebase is recorded as next-attempt preparation and does not rewrite earlier submission records. +Each submitted version keeps its own stamped guide and policy context. A later +revision may rebase forward or backward to the currently active guide. The +immutable preparation records that next-attempt context and never rewrites an +earlier Submission. ## Revision Replay -When a task enters NEEDS_REVISION, the next submission must include a revision replay: +After a human Review enters NEEDS_REVISION, the next submission must include one +immutable response for each unresolved blocking finding: ```text -Finding A -> fixed by change X -> evidence Y -> closed -Finding B -> fixed by change Z -> evidence W -> closed +ReviewFinding A -> SubmissionFindingResponse X -> evidence Y +ReviewFinding B -> SubmissionFindingResponse Z -> evidence W ``` -The contributor can claim each prior finding as: +The later Review appends one FindingResolution for each required prior finding: -- fixed -- disputed +- resolved +- unresolved - not_applicable -The reviewer can mark each prior finding: - -- closed_fixed -- closed_rebutted -- partially_closed -- still_open -- obsolete - ## Audit Requirements Every transition records: diff --git a/docs/architecture_lockdown.md b/docs/architecture_lockdown.md index d1e7bfd29..2fe0be76e 100644 --- a/docs/architecture_lockdown.md +++ b/docs/architecture_lockdown.md @@ -25,9 +25,10 @@ Project guide -> human review -> revision replay -> review decision: accept / needs_revision / reject +-> FinalAcceptance for accept only -> contribution record -> compensation award / fulfillment when payable --> reputation event +-> reputation integration (future, separate initiative) ``` ## Locked For v0.1 @@ -118,6 +119,17 @@ decision. Tasks lock to the active guide version at creation or screening time before entering `READY`. Material guide changes require a new guide version. +For guide and context resolution, TaskAssignment contributes only its `task_id`; +it still retains required contributor, assignment, status, and frozen submitter +contribution-policy attribution. Each immutable Submission stamps the exact +Project Guide identity, version, and activation sequence used by that attempt. +After a human `needs_revision` Review, exact stamped identity and +activation-sequence match with the currently active guide keeps context. Any +different valid active pair prepares a forward or backward rebase; incomplete, +inconsistent, revoked, or unsafe context blocks for manager repair. Task Context +returns the frozen preparation. No guide rebase occurs during review; the +reviewer uses the context stamped on the leased Submission. + ### Task Contract Every task must carry enough information to make claiming, checking, and @@ -153,14 +165,16 @@ In v0.1, this is enforced through: - immutable submission versions - checker results bound to artifact hashes - human review before acceptance -- reputation events tied to outcomes +- immutable Review, finding, response, and resolution history An explicit owner-agent execution workspace is later work. ### Immutable Artifact Storage Workstream stores guide material, submission artifacts, checker inputs, checker -logs, and checker outputs through the provider-neutral `ArtifactStore` port. +logs, checker outputs, and review evidence through ART v2 typed capabilities. +Product services do not import the raw ArtifactStore, provider, repository, or +scratch interfaces. ```text LocalStorageAdapter development and focused tests only @@ -181,6 +195,10 @@ credentials, object references, signed URLs, or direct-upload authority. v0.1 performs no physical deletion of completed artifacts. R2 and Flow Node are separate deferred adapter initiatives and are not v0.1 runtime dependencies. +An active ReviewLease authorizes artifact bytes only for its immutable +ReviewPacketManifest and exact Submission. Authorized chain history is bounded +metadata only. Decision and contribution creation perform no ART call. + ### Contribution Records Every valid recorded human Review creates an immutable reviewer @@ -193,8 +211,8 @@ FinalAcceptance or submitter contribution. Contribution records are separate from compensation status. Each record freezes its exact review, submission, actor, policy, and artifact-hash lineage. -Compensation awards and reputation events may attach to a contribution record, -but do not replace it. +Compensation awards may attach to a contribution record but do not replace it. +Reputation projection is deferred. FinalAcceptance is internal and REV-owned. It has no independent API/action, uses canonical `Submission.id` because each Submission row is already a @@ -216,6 +234,7 @@ These ideas remain architecture-compatible, but they are not part of the first b - ERC-8004 reputation writes - x402 micropayments - marketplace discovery +- adjudication lifecycle, queues, leases, decisions, and actions ## Canonical Names @@ -235,19 +254,11 @@ Use these names consistently: - `Project activation gate` - `Task screening gate` - `Submission quality gate` -- `contributor_claim_status` -- `reviewer_closure_status` - -Revision replay contributor claim statuses: - -- `fixed` -- `disputed` -- `not_applicable` - -Revision replay reviewer closure statuses: - -- `closed_fixed` -- `closed_rebutted` -- `partially_closed` -- `still_open` -- `obsolete` +- `ReviewQueueEntry` +- `ReviewLease` +- `ReviewPacketManifest` +- `ReviewFinding`: `blocking | advisory` +- `SubmissionFindingResponse` +- `FindingResolution`: `resolved | unresolved | not_applicable` +- `RevisionContextPreparation` +- `FinalAcceptance` diff --git a/docs/architecture_system_architecture.md b/docs/architecture_system_architecture.md index 8c5140f24..da2d4cf80 100644 --- a/docs/architecture_system_architecture.md +++ b/docs/architecture_system_architecture.md @@ -5,6 +5,10 @@ Workstream is organized around projects, tasks, submissions, checks, reviews, revisions, contributions, compensation, and reputation. +The review/revision component described below is a planned target contract. Its +routes remain unavailable until hidden REV behavior, exact AUTH activation, and +the REV-13 joint release complete. `docs/spec_review_lifecycle.md` is normative. + The architecture stays modular enough to support different project types without becoming abstract to the point that no project can use it. The visual architecture pack lives in [Architecture Diagrams](diagrams/README.md). It separates the 30-day v0.1 implementation from later adapter boundaries such as ERC-8004 agent identity and reputation, ERC-8183 task contract and escrow, x402 payment requests, OmniClaw settlement orchestration, and USDC settlement. @@ -21,7 +25,7 @@ Frontend Review queue Review page Compensation dashboard - Reputation dashboard + Reputation dashboard (deferred) Backend API Actor service @@ -35,7 +39,7 @@ Backend API Revision service Contribution and compensation service Evidence service - Reputation service + Reputation service (deferred) Storage Postgres for records @@ -59,7 +63,9 @@ Approved stack: - Backend API: Python with FastAPI - ORM, migrations, and API schemas: SQLAlchemy 2.x async + Alembic + Pydantic schemas - Database: Postgres -- File storage: local development can use filesystem-backed storage only behind the provider-neutral `ArtifactStore`; AWS S3 is the v0.1 hosted provider and MinIO is the local/CI protocol proof +- Artifact storage: product services use ART v2 typed, provider-neutral + capabilities; local development may use the filesystem provider, AWS S3 is + the v0.1 hosted provider, and MinIO is the local/CI protocol proof - Auth: external Flow authentication token verification through an auth interface/adapter; Workstream does not own login, signup, password reset, password storage, or primary auth sessions - Jobs: async-first background execution through Celery-backed workers for product lifecycle jobs @@ -83,7 +89,7 @@ Frontend policy: The architecture avoids framework coupling in the domain model. Project, task, submission, checker, review, revision, contribution, compensation, reputation, -and audit behavior remain portable. +and audit behavior remain portable; reputation behavior remains deferred. Auth policy: @@ -181,46 +187,43 @@ Owns: Owns: -- review queue -- findings -- review decisions -- non-mutating post-decision reviewer-quality audit selections and observations -- reviewer audit history +- server-selected ReviewQueueEntry routing and ReviewLeases +- immutable ReviewPacketManifest and lease-bounded Review Context +- immutable Reviews, ReviewFindings, FindingResolutions, and FinalAcceptance +- decision orchestration, task effects, audit, and shared-outbox staging +- reviewer history and bounded authorized chain metadata ### Revision Service Owns: -- prior feedback replay -- fix summaries -- issue closure -- resubmission linkage +- immutable RevisionContextPreparation chains +- SubmissionFindingResponse and FindingResolution lineage +- exact Project Guide keep/forward/backward/block classification +- resubmission and preferred-return linkage -### Evidence Service +### Artifact Service Boundary Owns: -- file attachments -- logs -- hashes -- screenshots -- checker output -- reviewer notes -- artifact immutability after checker execution begins +- ART v2 immutable content, binding, verification, candidate/finalize, and recovery +- narrow active-lease packet read +- REV-owned packet membership and finding/response evidence semantics +- no provider or raw byte-only ArtifactStore import in review services ### Contribution And Compensation Service Owns: -- immutable reviewer `completed_review` and submitter `accepted_submission` - ContributionRecords +- immutable reviewer `completed_review` sourced from Review/ReviewLease +- immutable submitter `accepted_submission` sourced only from FinalAcceptance - project ContributionPolicy and immutable published versions - independently frozen TaskAssignment and ReviewLease policy-version references - immutable CompensationAwards for payable contribution rules only - immutable fulfillment receipts and rebuildable status projections - contribution and compensation outbox events -### Reputation Service +### Reputation Service (Deferred) Owns: @@ -246,7 +249,7 @@ Owns: Use Postgres for records. -Use the provider-neutral `ArtifactStore` for large files and evidence. During +Use ART v2 provider-neutral capabilities for large files and evidence. During local development, the implementation can store files on the local filesystem; hosted v0.1 uses AWS S3 and local/CI integration uses MinIO without changing submission or evidence semantics. @@ -261,7 +264,8 @@ Every important lifecycle action creates an append-only audit event. State is re Use explicit domain APIs rather than generic CRUD-only endpoints. -Examples: +Existing APIs follow the `/api/v1` prefix. The examples below are conceptual; +planned review/revision routes are not registered before REV-13. ```text POST /projects @@ -270,8 +274,9 @@ POST /tasks/:id/claim POST /tasks/:id/submit POST /submissions/:id/finalize # operational repair for the automatic checker gate GET /submissions/:id/checker-runs -POST /reviews/:id/decision -POST /submissions/:id/revision-replay +planned reviewer current-work read under /api/v1 +planned active-lease decision mutation under /api/v1 +planned revision submission through canonical task submission.create POST /contributions/:id/export POST /compensation-awards/:id/fulfillment-receipts ``` @@ -297,9 +302,9 @@ Audit events cover: - submission creation and finalization - checker runs - review decisions -- revision replay closure +- immutable revision responses and later finding resolutions - compensation award, delivery, and fulfillment transitions -- reputation events +- reputation events only after separate implementation - admin overrides ## Future Extension Points diff --git a/docs/decision_0001_core_scope.md b/docs/decision_0001_core_scope.md index c5ffaeca8..994f9b30e 100644 --- a/docs/decision_0001_core_scope.md +++ b/docs/decision_0001_core_scope.md @@ -21,9 +21,11 @@ Project Guide -> Needs Revision / Accepted / Rejected -> Contribution Record -> Conditional Compensation Award / Fulfillment --> Reputation Event ``` +Reputation is a separately approved future consumer of immutable review and +contribution lineage. It is not a v0.1 review-transaction side effect. + The same evaluation and contribution infrastructure can support many project domains if project-specific rules are configurable. ## Consequences @@ -39,7 +41,6 @@ The first version prioritizes: - evidence - contribution records - compensation awards and fulfillment records -- reputation ledger Deferred: @@ -48,5 +49,6 @@ Deferred: - marketplace discovery - blockchain settlement - external client billing +- reputation policy, events, scoring, and projections This keeps the build focused on the part that determines quality and acceptance. diff --git a/docs/decision_0002_db_first_not_blockchain_first.md b/docs/decision_0002_db_first_not_blockchain_first.md index d159afdef..2c7a80fe9 100644 --- a/docs/decision_0002_db_first_not_blockchain_first.md +++ b/docs/decision_0002_db_first_not_blockchain_first.md @@ -12,8 +12,9 @@ The first risk is not settlement. The first risk is whether the evaluation and c ## Decision -Use Postgres-backed contribution, compensation-award, fulfillment, and -reputation records for v0.1. +Use Postgres-backed contribution, compensation-award, and fulfillment records +for v0.1. Reputation policy, records, scoring, and projections remain deferred +to a separate initiative. Blockchain settlement comes later as an adapter behind compensation fulfillment. diff --git a/docs/decision_0003_project_guides_are_first_class.md b/docs/decision_0003_project_guides_are_first_class.md index 8d7202aac..1f0065059 100644 --- a/docs/decision_0003_project_guides_are_first_class.md +++ b/docs/decision_0003_project_guides_are_first_class.md @@ -60,9 +60,21 @@ from the pre-ADR-0012 runtime do not grant product authority. Blocking pre-submit failures prevent submission creation. They do not create durable post-submit checker runs and they do not create human review decisions. -Revision policy is not optional. It defines the revision loop contract, including revision limits, revision deadlines, allowed resubmission states, and automatic rejection behavior after the limit. - -Guide and policy changes do not silently mutate submitted attempts. A submitted attempt stays tied to the guide and policy versions stamped on that submission. When a task enters `NEEDS_REVISION`, revision policy controls whether the next attempt keeps the prior context or rebases to the latest active guide and policy context. +Revision policy is not optional. It defines revision limits, revision deadlines, +allowed resubmission states, and reviewer-return preference. Reaching a limit or +deadline blocks further preparation and submission; it never creates a reject +Review. A covered Project Manager may later use the reason-bound administrative +closure defined by the active review lifecycle contract. + +Guide and policy changes do not silently mutate submitted attempts. A submitted +attempt stays tied to the guide and policy versions stamped on that Submission. +After a human `needs_revision` Review, preparation compares the prior +Submission's stamped Project Guide identity and activation sequence with the +project's currently active pair. An exact match keeps context, any different +internally consistent active pair rebases forward or backward, and missing or +unsafe context blocks for manager repair. RevisionPolicy does not select among +those outcomes. The reviewer always uses the context stamped on the exact leased +Submission and performs no separate rebase. Rules that affect acceptance judgment may be encoded in the human-facing project guide, review policy, revision policy, task template, or checker diff --git a/docs/decision_0009_review_decisions_are_canonical.md b/docs/decision_0009_review_decisions_are_canonical.md index e8534b101..a3c085038 100644 --- a/docs/decision_0009_review_decisions_are_canonical.md +++ b/docs/decision_0009_review_decisions_are_canonical.md @@ -25,10 +25,18 @@ Display labels may render these as "Accept", "Needs revision", and "Reject", but `Escalated` is not a review decision value. -Disputes, second review, suspected fraud, compensation holds, or registered recovery -may create separate workflow records and audit events, but they do not replace +Every valid human decision appends one immutable `Review`. Every submitted +`ReviewFinding` and every later `FindingResolution` is immutable; later rounds +append history rather than updating it. An `accept` Review additionally creates +one internal immutable `FinalAcceptance`. Only that fact can source the +submitter `accepted_submission` ContributionRecord. `needs_revision` and +`reject` create no FinalAcceptance and no submitter contribution. + +Offline calibration, suspected fraud, compensation holds, or registered +recovery may create separate evidence or audit records, but they do not replace the reviewer decision contract. Authorization recovery never creates a review -decision. +decision. Adjudication is a future separately approved lifecycle and adds no +v0.1 decision or state. Checker routing recommendations use a separate contract. A checker can recommend that a submission is ready for review, needs contributor revision, needs checker retry handling, or cannot proceed because the task's locked setup is incomplete. A checker cannot accept or reject work. @@ -52,14 +60,19 @@ contributor-facing revision or human review can continue. - checker-caused revision: `outcome_source = auto_checker`, `review_decision_id = null` - human reviewer revision: `outcome_source = human_review`, `review_decision_id = ` +Checker-caused remediation follows CheckerResult lineage and does not enter the +Review-rooted revision-preparation chain. Only the human-review case creates the +immutable Review, findings, reviewer contribution, and +`RevisionContextPreparation` episode defined by the active review contract. + ## Consequences Positive: - task state transitions remain simple - review analytics can compare decisions across projects -- revision policy has one clear entry point -- compensation and reputation logic can depend on a stable decision set +- human revision preparation has one Review-rooted entry point +- contribution logic can depend on immutable Review and FinalAcceptance facts - automated checker routing cannot accidentally masquerade as human acceptance or rejection Tradeoff: diff --git a/docs/decision_0010_revision_context_rebase.md b/docs/decision_0010_revision_context_rebase.md index b905c46a6..bdd686afb 100644 --- a/docs/decision_0010_revision_context_rebase.md +++ b/docs/decision_0010_revision_context_rebase.md @@ -1,4 +1,4 @@ -# ADR 0010: Revision Context Rebase Is Controlled By Policy +# ADR 0010: Revision Context Rebase Uses The Active Project Guide ## Status @@ -13,7 +13,8 @@ If rule changes live only in Slack, chat, or memory, contributors can be punishe Workstream needs both fairness and correctness: - a submitted attempt must remain tied to the exact guide and policy versions it used -- a revised attempt may need the latest active guide and policy context before the contributor resumes +- a revised attempt must use the Project Guide that is active when revision + preparation freezes the next-attempt context - the contributor and reviewer must be able to see what changed ## Decision @@ -22,26 +23,47 @@ Submitted attempts are immutable. Each submission remains evaluated against the locked project guide, checker policy, review policy, and revision policy versions stamped on that submission. -When a task enters `NEEDS_REVISION`, Workstream runs a revision context preparation step before the contributor resumes. That step compares the submission's locked guide and policy context with the current active project guide and policy context. +After a human `needs_revision` Review, Workstream runs an immutable revision +context preparation step before the contributor resumes. The task pipeline owns +the one Project Guide context used by the submitter and reviewer. +`TaskAssignment` stores only `task_id`; every Submission stamps the exact guide +identity, version, and immutable per-project activation sequence used for that +attempt. -Revision policy controls whether the next attempt: +Preparation compares the prior Submission's stamped guide identity and +activation sequence with the project's currently active guide pair: -- keeps the prior locked context -- rebases to the current active guide and policy context -- is blocked for project-manager repair when the task setup is incomplete or unsafe +- an exact identity and activation-sequence match keeps the prior context; +- any different internally consistent active pair rebases the next attempt and + records forward or backward direction, including an older reactivated guide; +- a missing, incomplete, internally inconsistent, revoked, or unsafe active + pair blocks for covered Project Manager repair. + +Version strings are never ordered. RevisionPolicy supplies limit and deadline +inputs but does not choose a stale guide over the currently active authority. Every revision context preparation must record its outcome. When the next attempt keeps the prior context, Workstream records that no rebase occurred and why. When the next attempt is rebased, Workstream records: - task id - prior submission id and version -- prior locked guide and policy versions -- next locked guide and policy versions +- prior stamped guide identity, version, and activation sequence +- next frozen guide identity, version, activation sequence, source snapshot, + and task-execution policy context +- outcome `kept`, `rebased`, or `blocked` and forward/backward direction where applicable - rebase reason - guide or policy change summary shown to the contributor - actor or system process that prepared the revision context - audit event id -The contributor must see the old context, the new context, and the change summary before submitting the revised attempt when a rebase occurs. The reviewer packet must also show that the revised attempt used a different guide or policy context. +Task Context returns the immutable preparation head and digest rather than a +moving active-guide pointer. The contributor must see the old context, new +context, and change summary before submitting. Submission N+1 acknowledges and +stamps that preparation exactly. A later guide activation cannot silently drift +an already prepared attempt. + +No guide rebase occurs during review. The reviewer consumes the guide and policy +context stamped on the single Submission covered by the active ReviewLease. History +shows the guide transition without changing any prior Submission. Out-of-band guidance has no acceptance force until it is encoded in one of: @@ -63,13 +85,13 @@ Positive: - guide and policy updates can improve future revisions without mutating prior submissions - repeated lessons become durable guide, checker, review, revision, or template changes -Compensation never rebases through revision context. Submitter compensation -remains governed by the `ContributionPolicyVersion` frozen on the +Contribution terms never rebase through revision context. Submitter terms +remain governed by the `ContributionPolicyVersion` frozen on the `TaskAssignment`; every `ReviewLease` independently freezes the reviewer version active when that lease is created. Tradeoff: - revision preparation needs an explicit audit record -- revision replay must show context changes, not only finding closure +- revision replay must show context changes, immutable responses, and later resolutions - services must keep submitted-attempt immutability separate from next-attempt preparation diff --git a/docs/decision_0012_workstream_authorization_service.md b/docs/decision_0012_workstream_authorization_service.md index d3595d605..f555c0f53 100644 --- a/docs/decision_0012_workstream_authorization_service.md +++ b/docs/decision_0012_workstream_authorization_service.md @@ -81,8 +81,9 @@ independently granted. Contributor is the umbrella human product term. A contributor may hold separate exact-project `submitter`, `reviewer`, and `adjudicator` grants. The adjudicator -grant creates no adjudication capability until WS-REV defines the lifecycle and -AUTH activates exact adjudication actions. Celery, checker, setup, and +grant creates no adjudication capability in v0.1; a future separately approved +initiative must define the lifecycle before AUTH can register and activate any +exact adjudication action. Celery, checker, setup, and background workers are internal services, not human product roles. Administrative roles alone do not authorize submission, review, or adjudication. @@ -139,6 +140,8 @@ data are never stored as authority evidence. - WS-AUTH-001 and this ADR own actor identity, grants, authorization, and authority evidence. - WS-REV-001 owns review routing, leases, review decisions, and revision guards. +- `docs/spec_review_lifecycle.md` is the active review/revision implementation + contract; archival WS-REV files are non-executable inputs. - WS-CON-001 owns contribution and compensation boundaries. - Human review decisions remain exactly `accept`, `needs_revision`, and `reject`. diff --git a/docs/decision_0013_immutable_artifact_storage_boundary.md b/docs/decision_0013_immutable_artifact_storage_boundary.md index 354e70fe4..3a8f1ae6e 100644 --- a/docs/decision_0013_immutable_artifact_storage_boundary.md +++ b/docs/decision_0013_immutable_artifact_storage_boundary.md @@ -234,8 +234,21 @@ nullable shadow field, dual write, or fallback remains. ## Review Boundary WS-REV owns `ReviewPacketManifest` and `ReviewEvidenceArtifact`. Both reference -general `ArtifactBinding` records and consume the same immutable bytes. Semantic -search is outside WS-ART-001. +general `ArtifactBinding` records and consume the same immutable bytes. ART v2 +owns bytes, bindings, candidate/finalize intake, verification, retention, +provider execution, and recovery. REV owns exact packet membership and the +finding/response evidence relationship. + +Artifact bytes are readable only for the exact Submission packet covered by a +current active ReviewLease. Authorized history is bounded metadata only. Prior, +expired, consumed, sibling, later, cross-task, and cross-project leases cannot +read packet bytes. + +Review decision and canonical contribution creation perform no ART call or +provider I/O. They consume stabilized binding facts and copy the server-derived +Submission `artifact_hash`. REV never imports the raw byte-only ArtifactStore, +concrete providers, ART repositories, scratch state, `ArtifactScratchManager`, +`PreparedArtifact`, or `CommittedArtifactSource`. ## Precedence @@ -248,6 +261,8 @@ search is outside WS-ART-001. - ADR 0014 governs external adapter construction and injection. - `docs/spec_artifact_storage_service.md` is the canonical implementation contract. +- `docs/spec_review_lifecycle.md` is canonical for review packet membership, + lease-bounded disclosure, and evidence semantics. - Archival reference specifications are non-executable inputs. ## Consequences diff --git a/docs/decision_0015_project_contributor_roles_are_independent.md b/docs/decision_0015_project_contributor_roles_are_independent.md index ded959295..7be984fa7 100644 --- a/docs/decision_0015_project_contributor_roles_are_independent.md +++ b/docs/decision_0015_project_contributor_roles_are_independent.md @@ -31,7 +31,8 @@ act as the sole reviewer of their own work even when they separately hold a reviewer grant. The adjudicator grant is recognized now, but it authorizes no adjudication -operation until WS-REV defines the lifecycle and AUTH activates exact actions. +operation in v0.1. A future separately approved initiative must define the +lifecycle before AUTH can register and activate exact actions. ## Consequences @@ -39,8 +40,7 @@ operation until WS-REV defines the lifecycle and AUTH activates exact actions. role. - Submitter revocation is consumed by task-assignment reconciliation. - Reviewer revocation is consumed by review-lease and queue reconciliation. -- Adjudicator revocation is consumed by adjudication-assignment reconciliation - only after that lifecycle is enabled. +- Adjudicator revocation has no review-lifecycle consumer in v0.1. - Revoking one contributor role does not change another contributor role or an AdminRoleGrant. - The prior combined-role portion of Decision 0012 is superseded. Its identity, diff --git a/docs/diagrams/backend_v01_components.md b/docs/diagrams/backend_v01_components.md index b2ef7ca07..1a9b6e7d6 100644 --- a/docs/diagrams/backend_v01_components.md +++ b/docs/diagrams/backend_v01_components.md @@ -31,7 +31,10 @@ Projects and guides -> checker runs -> review and revision -> reviewer contribution for every valid Review --> submitter contribution only on accept +-> FinalAcceptance on accept only +-> submitter contribution sourced only from FinalAcceptance -> conditional compensation award and fulfillment status --> reputation event ``` + +Reputation remains a future separate consumer and is not written by the v0.1 +review lifecycle. diff --git a/docs/diagrams/backend_v01_components.puml b/docs/diagrams/backend_v01_components.puml index 685d5a411..077aa09b5 100644 --- a/docs/diagrams/backend_v01_components.puml +++ b/docs/diagrams/backend_v01_components.puml @@ -46,7 +46,7 @@ package "FastAPI Backend - Modular Monolith" as backend #F8FBFF { rectangle "Submission\nService\n----\nPackets, evidence,\nartifact manifest,\nversions, locking" as submission_service rectangle "Checker\nService\n----\nChecker runs,\nblocking results,\npre-review gate" as checker_service rectangle "Review + Revision\nService\n----\naccept,\nneeds_revision,\nreject, findings,\nrevision replay" as review_service - rectangle "Contribution /\nCompensation /\nReputation\nService\n----\nReviewer/submitter records,\naward fulfillment,\noutcome events" as ledger_service + rectangle "Contribution /\nCompensation\nService\n----\nReviewer/submitter records,\naward fulfillment" as ledger_service } package "Shared Domain Rules" as shared_rules #EDF2FF { diff --git a/docs/diagrams/rendered/backend_v01_components.svg b/docs/diagrams/rendered/backend_v01_components.svg index 786d8265c..11a3f2187 100644 --- a/docs/diagrams/rendered/backend_v01_components.svg +++ b/docs/diagrams/rendered/backend_v01_components.svg @@ -1,145 +1 @@ -Workstream v0.1 Backend Component ViewFastAPI Backend - Modular MonolithHTTP + Auth BoundaryWorkflow ServicesShared Domain RulesPersistence BoundaryExternal Ports + AdaptersAPI RouterHTTP onlyrequest -> serviceerror -> responseCurrent ActorDependencyBearer token ->ActorContextPermissionPoliciesRole and objectvisibility checksPydanticSchemasRequest/responsecontractsProject GuideServiceProjects, guides,checker/review/revisionpoliciesTask QueueServiceTask contract,screening, release,claim, assignment,state guardsSubmissionServicePackets, evidence,artifact manifest,versions, lockingCheckerServiceChecker runs,blocking results,pre-review gateReview + RevisionServiceaccept,needs_revision,reject, findings,revision replayContribution /Compensation /ReputationServiceReviewer/submitter records,award fulfillment,outcome eventsLifecycleGuardsAllowed task andsubmission transitionsAuditServiceAppend-onlyworkflow eventsRepositoriesProject, task,submission, checker,review, ledger,audit persistenceAuth VerifierInterfaceFlow AuthAdapterStorage PortLocal StorageAdapterChecker RunnerAdapterReact UI /API ClientExternalFlow AuthPostgresRecord databaseFile StoreEvidence andartifact objectsHTTP/JSONroute to domain servicesverify actorstate, audit, policy rulesread/write recordsstorage and checker executionverify tokenstore/read artifactsSQLAlchemy async \ No newline at end of file +Workstream v0.1 Backend Component ViewFastAPI Backend - Modular MonolithHTTP + Auth BoundaryWorkflow ServicesShared Domain RulesPersistence BoundaryExternal Ports + AdaptersAPI RouterHTTP onlyrequest -> serviceerror -> responseCurrent ActorDependencyBearer token ->ActorContextPermissionPoliciesRole and objectvisibility checksPydanticSchemasRequest/responsecontractsProject GuideServiceProjects, guides,checker/review/revisionpoliciesTask QueueServiceTask contract,screening, release,claim, assignment,state guardsSubmissionServicePackets, evidence,artifact manifest,versions, lockingCheckerServiceChecker runs,blocking results,pre-review gateReview + RevisionServiceaccept,needs_revision,reject, findings,revision replayContribution /CompensationServiceReviewer/submitter records,award fulfillmentLifecycleGuardsAllowed task andsubmission transitionsAuditServiceAppend-onlyworkflow eventsRepositoriesProject, task,submission, checker,review, ledger,audit persistenceAuth VerifierInterfaceFlow AuthAdapterStorage PortLocal StorageAdapterChecker RunnerAdapterReact UI /API ClientExternalFlow AuthPostgresRecord databaseFile StoreEvidence andartifact objectsHTTP/JSONroute to domain servicesverify actorstate, audit, policy rulesread/write recordsstorage and checker executionverify tokenstore/read artifactsSQLAlchemy async \ No newline at end of file diff --git a/docs/diagrams/rendered/workstream_v01_container.svg b/docs/diagrams/rendered/workstream_v01_container.svg index d66889381..422e50124 100644 --- a/docs/diagrams/rendered/workstream_v01_container.svg +++ b/docs/diagrams/rendered/workstream_v01_container.svg @@ -1 +1 @@ -Workstream v0.1 Container ViewPeopleWorkstream v0.1Durable RecordsProject ManagerFinance AuthorityHuman-AgentContributorReviewerOperatorAccess AdministratorReact + Vite Operations UIPlanned internaloperations dashboardFastAPI BackendModular monolith APIand workflow rulesAuthorization ServiceActor profiles, local grants,and capability checksCelery Worker BoundaryDurable project setup,checker, and product jobsChecker RunnerAutomated task andsubmission checksArtifact Storage ServiceAdmission, verification,binding, and provider portPostgresProjects, guides,tasks, submissions,checks, reviews,revisions, contribution,compensation, reputation,audit eventsPrivate Object StoreBehind ArtifactStoreLocal / MinIO / AWS S3Flow AuthToken issuer andhuman identity sourceusespublishes contribution policyusesusesusesadministers accessHTTP/JSONverify identity tokenauthorize capabilityprofiles and grantsSQLAlchemy asynctyped artifact operationsschedule workrun checksresultsmaterialize exact artifactsstore/read \ No newline at end of file +Workstream v0.1 Container ViewPeopleWorkstream v0.1Durable RecordsProject ManagerFinance AuthorityHuman-AgentContributorReviewerOperatorAccess AdministratorReact + Vite Operations UIPlanned internaloperations dashboardFastAPI BackendModular monolith APIand workflow rulesAuthorization ServiceActor profiles, local grants,and capability checksCelery Worker BoundaryDurable project setup,checker, and product jobsChecker RunnerAutomated task andsubmission checksArtifact Storage ServiceAdmission, verification,binding, and provider portPostgresProjects, guides,tasks, submissions,checks, reviews,revisions, contribution,compensation, audit eventsPrivate Object StoreBehind ArtifactStoreLocal / MinIO / AWS S3Flow AuthToken issuer andhuman identity sourceusespublishes contribution policyusesusesusesadministers accessHTTP/JSONverify identity tokenauthorize capabilityprofiles and grantsSQLAlchemy asynctyped artifact operationsschedule workrun checksresultsmaterialize exact artifactsstore/read \ No newline at end of file diff --git a/docs/diagrams/task_lifecycle_sequence.md b/docs/diagrams/task_lifecycle_sequence.md index 297136c29..779bd2107 100644 --- a/docs/diagrams/task_lifecycle_sequence.md +++ b/docs/diagrams/task_lifecycle_sequence.md @@ -1,13 +1,11 @@ # Task Lifecycle Sequence This sequence shows the v0.1 operating loop from project guide to reviewer and -submitter contributions, conditional compensation awards, fulfillment, and -reputation records. +submitter contributions, conditional compensation awards, and fulfillment. It is intentionally separate from the future identity and settlement diagram. -v0.1 records immutable awards, fulfillment receipts/projections, and reputation -events internally; it does not execute on-chain settlement or write portable -agent reputation. +v0.1 records immutable awards and fulfillment receipts/projections; reputation +events and portable reputation are deferred. ```mermaid sequenceDiagram @@ -21,7 +19,7 @@ sequenceDiagram participant Auth as Flow Auth Verifier participant Authorization as Workstream Authorization participant DB as Postgres - participant Storage as Storage Abstraction + participant Artifacts as ART v2 Capabilities participant Checks as Checker Runner PM->>UI: Create project, guide, tasks, and setup/checker/review/revision configuration @@ -72,41 +70,66 @@ sequenceDiagram Auth-->>API: Verified external identity API->>Authorization: require(submission.create, candidates, ownership/resource/lifecycle guards) Authorization-->>API: Allowed with matched submitter grant - API->>Storage: Store or reference artifacts through storage abstraction + API->>Artifacts: Finalize verified artifact bindings API->>DB: Create immutable submission version API->>DB: Lock submission version and audit submitter-owned finalization API->>Checks: Enqueue automated checks through Celery - Checks->>Storage: Read referenced artifacts + Checks->>Artifacts: Read exact authorized artifacts Checks->>DB: Persist checker run and results Checks->>DB: Keep task EVALUATION_PENDING while pre-review gate runs Checks->>DB: Move to REVIEW_PENDING, NEEDS_REVISION, or internal task_setup_blocked - Reviewer->>UI: Review packet - UI->>API: Submit review decision + Reviewer->>UI: Request current work + UI->>API: GET current work API->>Auth: Verify Flow token Auth-->>API: Verified external identity API->>Authorization: Resolve actor profile and project grants - Authorization->>Authorization: require(review.decision, candidates, assignment/resource/lifecycle guards) + Authorization->>Authorization: require(review.queue.read, resource/lifecycle guards) Authorization-->>API: Allowed AuthorizationContext with matched reviewer grant - API->>DB: Store decision: accept, needs_revision, or reject - API->>DB: Create reviewer completed_review contribution and applicable award + API-->>UI: Active lease, one server-selected offer, or none + + Reviewer->>UI: Claim server-selected offer + UI->>API: POST claim + API->>Auth: Verify Flow token + Auth-->>API: Verified external identity + API->>Authorization: PREP review.claim with exact request bindings + Authorization-->>API: Opaque single-use prepared handle + API->>DB: Lock idempotency, lifecycle fence, queue, Task, Assignment, Submission, and CheckerRun; recompose canonical final facts + API->>Authorization: Consume prepared handle and evaluate final facts + Authorization-->>API: Allowed; authorization evidence staged + API->>DB: Freeze reviewer policy; create ReviewLease and ReviewPacketManifest; commit once + API-->>UI: Exact leased Review Context + + Reviewer->>UI: Submit accept, needs_revision, or reject + UI->>API: POST decision with immutable findings/resolutions + API->>Auth: Freshly verify Flow token + Auth-->>API: Verified external identity + API->>Authorization: PREP review.decision with exact request bindings + Authorization-->>API: Opaque single-use prepared handle + API->>DB: Lock idempotency, lifecycle fence, queue, lease, Task, Assignment, Submission, predecessor, and evidence; recompose canonical final facts + API->>Authorization: Consume prepared handle and evaluate final facts + Authorization-->>API: Allowed; authorization evidence staged + API->>DB: Append Review/findings/resolutions; consume lease; close queue + API->>DB: CON reviewer completed_review and applicable award alt needs_revision - API->>DB: Create revision requirements from findings - Contributor->>UI: Submit revision replay - UI->>API: POST revision replay and new submission version - API->>DB: Link replay to prior findings - API->>Checks: Run checks again + API->>DB: Set needs_revision and keep assignment active else accept - API->>DB: Create submitter accepted_submission contribution + API->>DB: Append FinalAcceptance; accept task; complete assignment + API->>DB: CON submitter accepted_submission from FinalAcceptance API->>DB: Create applicable submitter CompensationAward - API->>DB: Create reputation event - API->>DB: Audit acceptance else reject - API->>DB: Store rejection decision and findings - API->>DB: Apply reviewer reputation effects; no submitter contribution - API->>DB: Audit rejection + API->>DB: Block assignment and reject task + API->>DB: No FinalAcceptance or submitter contribution + end + API->>DB: Stage shared audit/outbox and commit once; no ART call + + opt needs_revision after decision commit + API->>DB: In a later authorized transaction, append frozen RevisionContextPreparation + Contributor->>UI: Submit one response per unresolved blocking finding + UI->>API: Create replacement Submission bound to preparation head + API->>Checks: Run checks again end ``` @@ -116,8 +139,9 @@ sequenceDiagram `ContributionPolicyVersion` to freeze. - A contributor submission creates a new immutable submission version; locked artifacts are not edited in place. - Review decisions are exactly `accept`, `needs_revision`, or `reject`. -- `needs_revision` starts a revision loop and must replay prior findings. -- Every valid human review creates a reviewer contribution. Accepted work - additionally creates a submitter contribution before compensation or - reputation records. +- `needs_revision` commits the immutable Review and task effect first. Before + contributor access, Workstream appends frozen preparation and later requires + immutable responses and resolutions for prior blocking findings. +- Every valid human Review creates a reviewer contribution. Accept additionally + creates FinalAcceptance, which alone sources the submitter contribution. - Compensation fulfillment status is separate from task acceptance. diff --git a/docs/diagrams/workstream_v01_container.md b/docs/diagrams/workstream_v01_container.md index 088239ddd..fdcaed459 100644 --- a/docs/diagrams/workstream_v01_container.md +++ b/docs/diagrams/workstream_v01_container.md @@ -12,9 +12,9 @@ Source: [workstream_v01_container.puml](workstream_v01_container.puml) | Container | Responsibility | | --- | --- | -| React + Vite operations UI | Planned internal project, queue, task, submission, review, compensation, and reputation operations surfaces. | +| React + Vite operations UI | Planned internal project, queue, task, submission, review, and compensation operations surfaces. | | FastAPI backend | API contracts, workflow rules, auth dependency, lifecycle guards, module orchestration, audit writes. | -| Postgres | Record database for workflow state, policy context, submissions, checks, reviews, revisions, contribution records, compensation awards/receipts/projections, reputation events, and audit history. | +| Postgres | Record database for workflow state, policy context, submissions, checks, reviews, revisions, contribution records, compensation awards/receipts/projections, and audit history. Reputation remains a future separate consumer. | | Storage interface | Stable artifact boundary using local storage for focused development, MinIO for local/CI protocol proof, and AWS S3 for hosted v0.1. | | Celery worker boundary | Durable project setup, checker, and background product-job execution path. FastAPI background tasks are not the Workstream product-job boundary. | @@ -23,6 +23,6 @@ Source: [workstream_v01_container.puml](workstream_v01_container.puml) - Postgres is used locally, in CI, and in production-like development. - Workstream verifies Flow auth tokens and does not manage primary authentication. - Task rules lock to guide and policy versions so upstream changes do not silently mutate in-progress work. -- Task acceptance, contribution, compensation fulfillment, and reputation are - separate records. +- Task acceptance, contribution, and compensation fulfillment are separate + records. Future reputation cannot mutate them. - External origins, agent identity writes, task escrow, and settlement rails remain adapter boundaries until the internal loop is proven. diff --git a/docs/diagrams/workstream_v01_container.puml b/docs/diagrams/workstream_v01_container.puml index 7f3c79d02..534093e37 100644 --- a/docs/diagrams/workstream_v01_container.puml +++ b/docs/diagrams/workstream_v01_container.puml @@ -48,7 +48,7 @@ package "Workstream v0.1" #F8FBFF { } package "Durable Records" #F2FBF7 { - database "Postgres\n----\nProjects, guides,\ntasks, submissions,\nchecks, reviews,\nrevisions, contribution,\ncompensation, reputation,\naudit events" as postgres + database "Postgres\n----\nProjects, guides,\ntasks, submissions,\nchecks, reviews,\nrevisions, contribution,\ncompensation, audit events" as postgres rectangle "Private Object Store\nBehind ArtifactStore\n----\nLocal / MinIO / AWS S3" as file_store #E6FCF5 } diff --git a/docs/glossary.md b/docs/glossary.md index 89110d247..63c74a01b 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -122,14 +122,16 @@ and expiry. ## ReviewPacketManifest -The future WS-REV-owned, system-generated packet presented to an authorized -reviewer. It references general artifact bindings and is not implemented by the -WS-ART storage foundation. +The planned immutable WS-REV semantic projection for one exact queue entry, +active ReviewLease, Submission, admitting CheckerRun, stamped context, response +evidence, and ART binding IDs. Only the exact active lease authorizes its packet +bytes; authorized history exposes bounded metadata only. ## ReviewEvidenceArtifact -The future WS-REV-owned reviewer attachment record. It references a verified -general artifact binding and requires reviewer assignment/lease authority. +The planned immutable WS-REV semantic relation from a lease/finding or +preparation/response evidence slot to one ART-finalized binding. ART owns the +bytes and binding; REV owns the lifecycle purpose and lineage. ## AdminRoleGrant @@ -148,9 +150,10 @@ through separate active grants. The umbrella human product term for a person participating in Workstream. A contributor may have exact-project `submitter`, `reviewer`, and `adjudicator` grants as independent records. The adjudicator grant creates no adjudication -capability in v0.1 and creates no review-lifecycle or release dependency. -Celery, checker, setup, and background workers are internal services, not -human product roles. +capability in v0.1. A future separately approved initiative must define that +lifecycle before AUTH registers and activates any exact action. Celery, checker, +setup, and background workers are +internal services, not human product roles. ## Source @@ -219,9 +222,11 @@ A unit of work inside a project. ## Task Work Context -The contributor-safe API projection of a task's locked guide, project summary, -review policy, revision policy, and lifecycle state. It is read -from the task's stamped locked context and does not expose source snapshot +The contributor-safe API projection of a task's guide, project summary, review +policy, revision policy, and lifecycle state. Initial work reads the task's +locked context. Human-review revision reads the validated immutable +RevisionContextPreparation head and digest, not a moving active-guide pointer. +It does not expose source snapshot hashes, private source/import refs, compiled checker bundles, checker configs, Celery ids, or setup errors. @@ -260,13 +265,60 @@ The set of required and warning checks for a project phase. Pre-submit checker p The judgment layer where a reviewer accepts, rejects, or requests revision. -## Finding +## ReviewQueueEntry -A structured reviewer issue with severity, area, required fix, and evidence. +The planned durable admission record connecting one exact finalized Submission +and successful current CheckerRun to server-selected human-review routing. + +## ReviewLease + +The planned permanent identity of one reviewer claim attempt. It binds the +canonical human reviewer, queue entry, exact Submission packet, lease timing, +and independently frozen reviewer ContributionPolicyVersion. + +## Review + +The immutable result of one valid human decision under an active ReviewLease. +Stored decisions are exactly `accept`, `needs_revision`, or `reject`. Later +rounds append another Review rather than modifying history. + +## ReviewFinding + +A planned immutable structured issue submitted with a Review. Its lifecycle +meaning is `blocking` or `advisory` and it carries area, required change, +rationale, and optional finalized evidence. + +## SubmissionFindingResponse + +The immutable submitter response to one prior ReviewFinding, with response text +and optional finalized evidence. Every unresolved blocking finding requires one +response before revision submission. + +## FindingResolution + +The immutable later-review judgment for one prior finding and revised +Submission: `resolved`, `unresolved`, or `not_applicable`, with bounded rationale +and evidence. + +## RevisionContextPreparation + +The immutable Review-rooted next-attempt context. It records the prior +Submission, source and target TaskAssignments, active Project Guide identity, +version and activation sequence, frozen task-execution policies, context digest, +change summary, and `kept`, `rebased`, or `blocked` result. A rebase records +forward or backward direction. + +## FinalAcceptance + +The internal immutable accept-only fact linking one task, versioned Submission, +source Review, accepted submitter, recording reviewer, time, and ReviewPolicy. +It has no manual API or separate action and is the sole source of the submitter +`accepted_submission` ContributionRecord. ## Revision Replay -A resubmission record showing how each prior review finding was addressed. +The complete immutable response and resolution history connecting a prior +Review's findings to the next Submission and later Review. ## Evidence @@ -274,11 +326,13 @@ Proof supporting task completion or review decision. Examples: logs, hashes, tes ## Artifact Store -The provider-neutral typed capability through which Workstream stores and reads -private immutable bytes. Its v0.1 byte-only operations are `put`, read-only -`observe_put_result`, `open`, and `head`. `LocalStorageAdapter` implements it -for development and focused tests. `S3CompatibleArtifactStore` implements it -for MinIO integration and AWS S3 v0.1 production deployments. Providers do +The provider-neutral ART v2 byte boundary beneath Workstream's typed product +capabilities. Its v0.1 byte-only operations are `put`, read-only +`observe_put_result`, `open`, and `head`; product services consume narrow typed +capabilities rather than importing the raw store. `LocalStorageAdapter` +implements it for development and focused tests. +`S3CompatibleArtifactStore` implements it for MinIO integration and AWS S3 +v0.1 production deployments. Providers do not own Workstream authorization, binding, lifecycle, audit, or integrity decisions. @@ -322,7 +376,8 @@ rules create no award. ## Reputation Ledger -The outcome-based record of contributor and reviewer performance. +The deferred outcome-based projection of contributor and reviewer performance. +It is not a v0.1 review-transaction side effect. ## Contribution Record @@ -331,8 +386,8 @@ project context. `completed_review` is created for every valid recorded human Review and binds directly to that Review and ReviewLease. `accepted_submission` is created only from FinalAcceptance and the exact TaskAssignment; it is never inferred directly from `Review.decision`. -Compensation and reputation records may attach to either contribution type, but -do not replace the contribution record. +Compensation records may attach to either contribution type but do not replace +the contribution record; reputation projections remain deferred. ## Final Acceptance diff --git a/docs/operations_operator_workflow.md b/docs/operations_operator_workflow.md index 2ab5f2631..e7f8bbd84 100644 --- a/docs/operations_operator_workflow.md +++ b/docs/operations_operator_workflow.md @@ -1,5 +1,12 @@ # Operator Workflow +## Status + +Existing project and task operations retain their owning implementation status. +Review, revision, FinalAcceptance, and review-sourced contribution behavior +below is planned and unavailable until its owning REV/CON chunks, exact AUTH +activation, and REV-13 joint release complete. + ## Roles ### Project Manager @@ -45,7 +52,7 @@ Reads authorized immutable and operational evidence without mutation. 1. Project Manager: check the covered-project task queue. 2. Project Manager: create or release ready tasks under project lifecycle guards. 3. Project Manager: assign tasks under project policy. -4. Reviewer: review assigned checker-passed submission packets. +4. Reviewer: consume current work as active lease, one server-selected offer, or none. 5. Reviewer and Submitter: issue and respond to `needs_revision`; Project Manager observes the covered-project queue without recording either party's action. 6. Finance Authority: reconcile contribution-policy, award, delivery, and @@ -83,25 +90,29 @@ Reads authorized immutable and operational evidence without mutation. ## Revision Workflow -1. Read every reviewer finding. -2. Create fix summary per finding. -3. Attach evidence per fix. -4. Resubmit packet. -5. Checker verifies prior revision closure. -6. Reviewer confirms findings are closed. +1. Read the frozen RevisionContextPreparation and every unresolved blocking finding. +2. Append one SubmissionFindingResponse per required finding. +3. Attach finalized evidence where needed. +4. Resubmit against the exact preparation head/digest. +5. The normal checker spine reruns. +6. The later reviewer appends one FindingResolution per required finding. ## Acceptance Workflow 1. Reviewer accepts submission. -2. REV records the immutable Review and one internal FinalAcceptance for the - exact task, Submission, submitter, reviewer, and locked ReviewPolicy. -3. Task moves to ACCEPTED and the TaskAssignment completes. -4. Workstream records reviewer `completed_review` directly from Review and - submitter `accepted_submission` only from FinalAcceptance. -5. Frozen contribution policies create awards only for payable contributions; +2. REV appends the immutable Review and any submitted findings or resolutions, + consumes the ReviewLease, and closes the ReviewQueueEntry. +3. CON records reviewer `completed_review` directly from Review and evaluates + the ReviewLease-frozen contribution policy. +4. REV records one internal FinalAcceptance for the exact task, Submission, + submitter, reviewer, and locked ReviewPolicy. +5. REV moves the task to ACCEPTED and completes the TaskAssignment. +6. CON records submitter `accepted_submission` only from FinalAcceptance and + evaluates the TaskAssignment-frozen contribution policy. +7. Frozen contribution policies create awards only for payable contributions; explicit unpaid rules create none. -6. Reputation events are recorded from contribution facts. -7. Finance Authority follows delivery and fulfillment only for created awards. +8. Finance Authority follows post-commit delivery only for created awards. +9. Reputation projection remains deferred. The Review request owns one commit for Review, FinalAcceptance, task effects, contributions, awards, audit, and outbox. There is no manual FinalAcceptance @@ -114,8 +125,7 @@ command and no adjudication/reopen step in v0.1. 3. REV sets the Task to canonical `rejected`, blocks only the same-task TaskAssignment, and binds that block to the reject Review. It changes no actor grant or unrelated task. -4. Reputation event is recorded. -5. The frozen reviewer contribution award rule determines whether the resulting +4. The frozen reviewer contribution award rule determines whether the resulting `completed_review` contribution creates a `CompensationAward`; rejection creates no submitter `accepted_submission` contribution. @@ -123,6 +133,16 @@ For `needs_revision`, REV instead sets the Task to `needs_revision`, keeps the same TaskAssignment `active`, and creates no FinalAcceptance or submitter contribution. `closed/review_rejected` is not a canonical task state. +## Planned Revision Recovery + +- A covered Project Manager may append a revision-context repair successor. +- A covered Project Manager may explicitly cancel a reached limit/deadline + obligation; the system never auto-rejects it. +- An Operator may close only an evidence-linked legacy revision with no + Review/root. +- These commands remain unavailable until AUTH activation and REV-13. Operator + authority never records a human Review or adjudication decision. + ## Lessons Learned Every project maintains lessons learned: diff --git a/docs/operations_payment_reputation.md b/docs/operations_payment_reputation.md index 6e24d1e39..cc8d2acb3 100644 --- a/docs/operations_payment_reputation.md +++ b/docs/operations_payment_reputation.md @@ -1,5 +1,12 @@ # Compensation And Reputation +## Status + +Existing compensation records retain their owning implementation status. The +Review-, FinalAcceptance-, and revision-sourced behavior below is planned and +unavailable until its owning REV/CON chunks, exact AUTH activation, and REV-13 +joint release complete. Reputation behavior is deferred entirely. + ## Compensation Principle External fulfillment can be manual in the first version, but Workstream records @@ -7,12 +14,14 @@ the authorized award and immutable fulfillment result with the same discipline as automated settlement. Every valid recorded human Review creates a reviewer `completed_review` -contribution. `Review(accept)` first creates REV-owned FinalAcceptance; that -immutable fact is the sole source of a submitter `accepted_submission` -contribution. Compensation is evaluated independently for each record from its -frozen policy version; an explicit unpaid rule creates no award. Awards, -fulfillment receipts, projections, and reputation events attach to contributions -and never replace them. +contribution through the mandatory CON reviewer operation. After that operation, +the `Review(accept)` branch creates REV-owned FinalAcceptance, then sets the Task +to `accepted` and the TaskAssignment to `completed`, then runs the CON submitter +operation. FinalAcceptance is the sole source of that submitter +`accepted_submission` contribution. Compensation is evaluated independently +for each record from its frozen policy version; an explicit unpaid rule creates +no award. Awards, fulfillment receipts, and projections attach to contributions +and never replace them. Reputation events are deferred. ## Compensation Status Projection @@ -63,6 +72,8 @@ Default: award's frozen adapter binding - a fulfilled award requires an immutable receipt, exact quantity, and external reference +- canonical Review, FinalAcceptance, contributions, and eligible awards commit + once; external fulfillment begins only after commit through the outbox Review decisions, FinalAcceptance, contribution recognition, award creation, and fulfillment remain separate facts. FinalAcceptance has no manual API/action @@ -78,9 +89,13 @@ The dashboard must always show: - failed awards - fulfilled awards by instrument and unit -## Reputation Principle +## Deferred Reputation Principle + +Reputation policy, events, scoring, and projections are not implemented by the +v0.1 review lifecycle. The review decision transaction writes no reputation +side effect. The remaining sections are future product guidance only. -Reputation is not a badge. It is an outcome ledger. +When separately implemented, reputation is not a badge. It is an outcome ledger. It updates from: @@ -107,7 +122,7 @@ Track: - skill-specific quality - compensation fulfillment reliability -Suggested v0.1 contributor events: +Possible future contributor events: | Event | Default Delta | Notes | | --- | ---: | --- | @@ -123,24 +138,23 @@ Track: - completed reviews - decision distribution -- non-mutating quality-audit findings +- non-mutating offline quality-analysis findings - unclear feedback reports - average turnaround -- quality-audit agreement +- offline sampled-quality signals -Suggested v0.1 reviewer events: +Possible future reviewer events: | Event | Default Delta | Notes | | --- | ---: | --- | | clear_review | +2 | Structured findings or clear acceptance evidence. | | unclear_feedback | -2 | Finding lacks issue, evidence, or required fix. | -| review_quality_audit_completed | 0 | Records that the decision evidence was independently sampled. | -| review_quality_issue_flagged | -3 | Non-mutating audit found unsupported decision reasoning. | +| sampled_quality_concern | -3 | Offline evidence flags review quality without changing the product decision. | | missed_prior_finding | -2 | Resubmission accepted with unresolved prior issue. | -Quality-audit events may affect reputation only. They do not reopen Review, -replace FinalAcceptance, mutate task status or contributions, or create an -adjudication decision. +These are future reputation inputs only. Sampling creates no product Review, +decision, queue, lease, or adjudication state and cannot mutate existing review +history. ## Skill Tags diff --git a/docs/operations_project_operating_manual.md b/docs/operations_project_operating_manual.md index f6e459f40..0115915e2 100644 --- a/docs/operations_project_operating_manual.md +++ b/docs/operations_project_operating_manual.md @@ -232,7 +232,8 @@ The output is one of: Before review decision: -- read active guide version +- read the Project Guide identity/version/activation sequence stamped on the + exact leased Submission; no guide rebase occurs during review - read task acceptance criteria - inspect checker results - inspect evidence @@ -268,7 +269,16 @@ checker expectations, it must become the applicable guide, policy, template, or checker update before it is enforced. Chat and Slack messages can announce the change, but they are not the source of truth. -When a task already in `NEEDS_REVISION` is affected by a new guide or policy version, revision policy decides whether the next attempt is rebased. The contributor must see the prior version, next version, and change summary before resubmitting. +For human-review revision, Workstream compares the prior Submission's stamped +guide identity/activation sequence with the currently active Project Guide. +Exact match keeps; any different valid pair rebases forward or backward; unsafe +context blocks. Task Context returns the frozen preparation, and the contributor +sees the prior/next versions, direction, and change summary before resubmitting. + +The planned review/revision surface remains unavailable until its owning REV +chunks, exact AUTH activations, and REV-13 joint release. Every valid decision +appends an immutable Review and reviewer contribution. Accept additionally +creates FinalAcceptance, which alone sources the submitter contribution. Each lesson must have an action owner and one target: diff --git a/docs/operations_queue_policy.md b/docs/operations_queue_policy.md index bfc0dd956..84ec28eb6 100644 --- a/docs/operations_queue_policy.md +++ b/docs/operations_queue_policy.md @@ -1,5 +1,11 @@ # Queue Policy +## Status + +Review and revision lanes below are the planned v0.1 operating contract. Their +routes and jobs remain unavailable until the owning REV chunks, exact AUTH +activation, and REV-13 joint release complete. + ## Purpose The queue is the operational truth of Workstream. It tells the team what @@ -113,23 +119,26 @@ Policy: - retry and repair actions record matched grant/permission, reason, attempt, and immutable audit history -### Pre Review Gate +### Checker Admission Gate -Optional reviewer-simulation or adversarial readiness audit after automated checks and before normal human review. +Mandatory automated admission after post-submit checks and before human review. Owner: -- reviewer lead -- quality lead -- assigned simulation reviewer +- checker system Policy: -- use this for high-value tasks, new project types, disputed checker outcomes, or projects still being calibrated -- the gate records findings or explicitly clears the packet for normal review -- unresolved blocking issues go to `NEEDS_REVISION` when contributor-fixable or - remain blocked from review until the owning covered repair/retry action - succeeds +- only a durable, final, current `CheckerRun` outcome of `allow_review` admits + the exact immutable Submission +- admission records the exact CheckerRun and verified binding facts; retries, + superseded runs, and different Submissions cannot replace that anchor +- contributor-fixable checker failures may route the Task to `needs_revision` + but create no Review, ReviewFinding, or reviewer contribution +- setup or provenance defects remain blocked until the owning covered repair or + retry action succeeds +- human judgment begins only after admission and is recorded as an immutable + Review ### Review Pending @@ -141,7 +150,8 @@ Owner: Policy: -- reviewers only see this lane for normal work +- reviewer current work returns an active lease, one server-selected offer, or + none; reviewers never browse the complete lane - any critical- or high-severity checker failure in this lane is a system bug; no administrative grant can override it into review readiness @@ -151,20 +161,26 @@ Contributor-facing lane for fixable issues from automated checks, pre-review gat Policy: -- before the contributor resumes, Workstream prepares revision context against the active guide and policy records -- revision policy decides whether the next attempt keeps the prior locked context or rebases to the current active context -- a rebase must show the contributor the prior version, next version, and change summary +- after a human `needs_revision` Review, Workstream compares the prior + Submission guide identity/activation sequence with the currently active guide +- exact match keeps; any different valid pair rebases forward or backward; + unsafe context blocks for manager repair +- Task Context returns the frozen preparation and change summary; the reviewer + never rebases the leased Submission - out-of-band guidance is not enforceable until it is encoded into guide, policy, task template, or checker contracts Owner: - contributor -- operator +- covered Project Manager for planned repair/obligation closure; Operator only + for evidence-linked legacy recovery Policy: -- every task in this lane must have at least one structured finding -- resubmission must include revision replay +- checker-caused remediation carries CheckerResult lineage; human-review + revision carries an immutable Review and at least one blocking finding +- human-review resubmission includes one immutable response per unresolved + blocking finding ### Accepted @@ -190,16 +206,19 @@ Work is not acceptable and will not continue in the normal revision loop. Owner: -- project manager -- reviewer lead if disputed +- project manager for terminal-state observation +- authorized audit authority for non-mutating quality sampling only Policy: -- rejection requires evidence and guide-grounded reason +- rejection requires a bounded human, guide-grounded reason; structured + findings and finalized evidence are optional when they add useful support - the Task enters canonical `rejected`; only its same-task TaskAssignment is blocked and bound to the reject Review - no FinalAcceptance or submitter contribution is created; no actor grant or unrelated task changes +- quality sampling cannot reopen, adjudicate, replace, or change the immutable + Review, rejection, task state, assignment effect, or contribution lineage ### Compensation Fulfillment Follow-Up @@ -223,7 +242,7 @@ Every operating day starts with: 2. clear screening tasks or send them back to draft 3. inspect stale active tasks 4. clear checker failures -5. assign review pending tasks +5. monitor server-selected review offers and active leases 6. push needs revision tasks to contributors 7. reconcile payable awards with pending/failed fulfillment projections 8. record new lessons learned @@ -237,13 +256,13 @@ Every operating day starts with: | `READY -> CLAIMED` | active published ContributionPolicyVersion whose `accepted_submission` rule is explicit; TaskAssignment freezes that version | | `IN_PROGRESS -> SUBMITTED` | blocking pre-submit checks passed, submission packet, artifact hash manifest, evidence references, contributor attestation | | `SUBMITTED -> EVALUATION_PENDING` | immutable submission version, locked post-submit checker policy id/version/hash/body copied from the task context | -| `EVALUATION_PENDING -> REVIEW_PENDING` | checker run for exact submission version, readiness certificate, no blocking failures | -| `EVALUATION_PENDING -> NEEDS_REVISION` | checker run id, outcome source `auto_checker`, contributor-visible checker failures with severity, message, suggested fix | -| `REVIEW_PENDING -> NEEDS_REVISION` | review decision, at least one structured finding, TaskAssignment remains `active`, reviewer `completed_review` contribution and applicable reviewer award, no FinalAcceptance or submitter contribution, revision policy still permits revision | -| `REVIEW_PENDING -> ACCEPTED` | accepted Review, one FinalAcceptance for the exact task/Review/Submission, acceptance evidence refs, reviewer `completed_review` and FinalAcceptance-sourced submitter `accepted_submission` contributions, applicable awards | -| `REVIEW_PENDING -> REJECTED` | rejected Review, bounded human reason/finding, only the same-task TaskAssignment blocked with its source Review, reviewer `completed_review` contribution and applicable reviewer award; no FinalAcceptance, submitter contribution, grant change, or unrelated task effect | -| pre-submit feedback in `NEEDS_REVISION` | prior findings visible to contributor, revision deadline active, no new submission created | -| `NEEDS_REVISION -> SUBMITTED` | replacement submission packet, revision replay covering every high and medium prior finding, revision count under policy limit | +| `EVALUATION_PENDING -> REVIEW_PENDING` | durable, final, current CheckerRun for the exact Submission with outcome exactly `allow_review`, verified artifact bindings, no blocking failures | +| `EVALUATION_PENDING -> NEEDS_REVISION` | durable, final, current CheckerRun for the exact Submission with outcome exactly `needs_revision`, verified artifact bindings, outcome source `auto_checker`, contributor-visible checker failures with severity, message, suggested fix | +| `REVIEW_PENDING -> NEEDS_REVISION` | immutable Review, at least one blocking ReviewFinding, reviewer `completed_review`; no FinalAcceptance or submitter contribution | +| `REVIEW_PENDING -> ACCEPTED` | immutable accepting Review, FinalAcceptance, reviewer `completed_review`, submitter `accepted_submission` sourced from FinalAcceptance, applicable awards | +| `REVIEW_PENDING -> REJECTED` | immutable rejected Review, bounded reason, same-task assignment block, reviewer `completed_review`; no FinalAcceptance or submitter contribution | +| `NEEDS_REVISION -> SUBMITTED` | exact preparation head/digest, replacement Submission, response for every unresolved blocking finding, policy limit/deadline not reached | +| `NEEDS_REVISION -> CANCELLED` | covered manager limit/deadline closure or Operator legacy-context closure, bounded canonical reason, assignment release; no synthetic Review or contribution | | compensation `pending -> fulfilled` | immutable fulfillment receipt, external reference, and audit event | ## Lane Capacity @@ -251,7 +270,7 @@ Every operating day starts with: Each project defines capacity limits: - maximum active tasks per contributor -- maximum review-pending tasks per reviewer +- maximum active ReviewLeases per reviewer - maximum stale active age - maximum pending/failed payable-award fulfillment age @@ -260,7 +279,7 @@ Capacity limits prevent the queue from looking healthy while hidden work is stuc For early pilots, use conservative defaults: - contributor active task limit: 2 -- reviewer review-pending limit: 5 +- reviewer active ReviewLease limit: 1 - review SLA: 24 hours - compensation fulfillment reconciliation SLA: daily diff --git a/docs/operations_reviewer_workflow.md b/docs/operations_reviewer_workflow.md index 9617d522e..10259f50d 100644 --- a/docs/operations_reviewer_workflow.md +++ b/docs/operations_reviewer_workflow.md @@ -1,82 +1,111 @@ # Reviewer Workflow +## Status + +This is the planned v0.1 operating contract. Reviewer routes and jobs remain +unavailable until their hidden REV behavior, exact AUTH activation, and the +REV-13 joint release complete. `spec_review_lifecycle.md` is normative. + ## Reviewer Job -The reviewer decides whether a submission satisfies the task and project guide. +The reviewer decides whether one exact leased Submission satisfies the task and +the Project Guide context stamped on that Submission. No guide rebase occurs +during review, and the active-at-read-time guide does not replace stamped context. + +The reviewer must have an exact active project `reviewer` grant represented by +canonical human `ActorProfile.id`. Submitter, adjudicator, administrative, or +token-role authority does not substitute. No-self-review and lifecycle guards +still apply. -The reviewer does not spend time diagnosing basic packaging or schema failures. The checker framework handles that before review. +## Current Work And Claim -The reviewer is accountable for judgment, not task execution. A good review is specific enough that a contributor can either fix the issue or clearly dispute it. +The reviewer current-work operation returns an active lease, one server-selected +offer, or none. It never returns the complete backlog. A claim creates one +ReviewLease and immutable ReviewPacketManifest under PostgreSQL race guards. + +The reviewer may read artifact bytes only for the exact Submission packet named +by the current active lease. Authorized history contains bounded metadata, not +prior or unrelated artifact bytes. ## Review Inputs -Every review page shows: +The planned Review Context contains: -- project guide version -- task description -- acceptance criteria -- submission summary -- evidence items -- checker results -- prior review findings if resubmission -- revision replay if resubmission +- queue, lease, Submission, and admitting CheckerRun identity; +- stamped Project Guide identity, version, and activation sequence; +- task description and acceptance criteria; +- submission summary and exact packet bindings; +- checker results and bounded evidence; +- prior immutable Reviews and findings when relevant; +- revision preparation transition, submitter responses, and prior resolutions. ## Decisions -Allowed decisions: +Allowed decisions are exactly `accept`, `needs_revision`, and `reject`. -- accept -- needs_revision -- reject +Every valid decision appends one immutable Review. Every submitted finding and +later resolution is immutable. Every Review creates one reviewer +`completed_review` ContributionRecord and evaluates the ReviewLease-frozen +ContributionPolicyVersion, regardless of outcome. -Decision rules: +`accept` means the Submission satisfies its stamped context. It additionally +creates one immutable FinalAcceptance, accepts the task, completes the +TaskAssignment, and creates the submitter `accepted_submission` from +FinalAcceptance. There is no direct Review-to-submitter contribution inference. -- `accept` means the submission satisfies the project guide. The same - transaction creates internal FinalAcceptance, then creates the submitter - `accepted_submission` contribution only from that fact. Its frozen - contribution award rule independently decides whether that contribution - creates an award. -- `needs_revision` means the work is fixable and the reviewer can name concrete required changes. -- `reject` means the work is not reasonably salvageable or violates policy. +`needs_revision` means concrete blocking issues are fixable. It keeps the +TaskAssignment active, creates no FinalAcceptance, and creates no submitter +contribution. -## Finding Format +`reject` means the work is not reasonably salvageable or violates the governing +contract. It requires a bounded human reason, blocks the same-task assignment, +sets the task to `rejected`, and creates no FinalAcceptance or submitter +contribution. -Every finding includes: +## Findings -- severity -- area -- issue -- required fix -- evidence reference +A ReviewFinding contains: + +- lifecycle meaning: `blocking` or `advisory`; +- area; +- issue and rationale; +- required change for blocking findings; +- optional finalized evidence binding. -Severity: +`needs_revision` requires at least one unresolved blocking finding. Advisory +findings must not become preference-only acceptance requirements. Reject +requires its bounded reason; structured findings are optional when they add +useful evidence and are never fabricated merely to satisfy a field. -- high: blocks acceptance -- medium: fixed unless project policy says otherwise -- low: note or cleanup +## Revision Review -Finding areas are project-specific but normalized enough for reporting. +For a revised Submission, the reviewer checks each required immutable +SubmissionFindingResponse and appends one FindingResolution with result +`resolved`, `unresolved`, or `not_applicable`. The reviewer does not edit the +prior finding or response. -Common areas: +The revised Submission initially returns to the reviewer who requested the +revision. Preference expiry, decline, or authority invalidation opens the same +queue entry without resetting its age. -- task_spec -- output_quality -- evidence -- checker_failure -- originality -- package -- revision_replay -- guide_compliance +## Decision Transaction -## Accept +The route owns one transaction: -Use accept only when: +```text +AUTH prepared authority and final evaluation +-> append Review/findings/resolutions +-> consume ReviewLease and close ReviewQueueEntry +-> CON reviewer operation +-> accept: FinalAcceptance + task effects + CON submitter operation + needs_revision: task effect only + reject: assignment block + task effect +-> REV stages shared audit/outbox +-> commit once +``` -- task requirements are satisfied -- acceptance criteria are met -- evidence is sufficient -- no unresolved critical- or high-severity checker failure exists -- prior revision findings are closed if applicable +The transaction performs no Artifact Storage call. Any participant failure rolls +back all lifecycle, contribution, award, audit, and outbox effects. Accept must create: @@ -90,9 +119,9 @@ Accept must create: FinalAcceptance, not directly from Review.decision - any awards required by the separately frozen reviewer and submitter contribution policies -- reputation event -The reviewer cites the strongest evidence supporting acceptance, not only "looks good." +The reviewer cites the strongest evidence supporting acceptance, not only +"looks good." ## Needs Revision @@ -102,11 +131,13 @@ Use needs_revision when: - the submission is not acceptable yet - reviewer can describe concrete required fixes -Do not write vague feedback. Every issue must tell the contributor what is wrong and what must change. +Do not write vague feedback. Every blocking issue must tell the contributor +what is wrong and what must change. -Needs revision feedback must not introduce preference-only work. If the guide does not require it and acceptance is not blocked by it, keep it as a low-severity note. +Needs-revision feedback must not introduce preference-only work. If the guide +does not require it and acceptance is not blocked by it, record it as advisory. -Each high or medium finding must have: +Each blocking finding must have: - exact issue - why it blocks acceptance @@ -126,7 +157,8 @@ Use reject when: - the task cannot be salvaged by reasonable revision - the contributor submitted prohibited material -Use reject carefully. If the work can be reasonably corrected through one revision cycle, use `needs_revision`. +Use reject carefully. If the work can be reasonably corrected through one +revision cycle, use `needs_revision`. Recording `reject` sets the Task to canonical `rejected` with the bounded human reason and blocks only the same-task TaskAssignment with its source Review. It @@ -138,23 +170,21 @@ reviewer's `completed_review` contribution and evaluates the ReviewLease-frozen reviewer contribution policy. Neither decision creates a submitter contribution or submitter award. -## Reviewer Quality +## Offline Reviewer Quality Track: - review count - decision distribution -- non-mutating quality-audit findings +- non-mutating sampled-quality findings - unclear feedback reports - average turnaround -- quality-audit agreement +- repeated missed prior findings -Reviewer reputation matters because low-quality review damages the whole system. - -Reviewer quality events are generated when: +Offline quality evidence may be recorded when: - feedback is marked unclear -- a non-mutating quality audit finds unsupported acceptance/rejection reasoning +- non-mutating sampling finds unsupported acceptance/rejection reasoning - reviewer misses unresolved prior findings These quality signals never reopen or replace Review, FinalAcceptance, task, or @@ -162,31 +192,25 @@ ContributionRecord truth. V0.1 has no adjudication decision or queue. ## Reviewer Checklist -Before accepting: - -- task guide was followed -- acceptance criteria are satisfied -- evidence supports the claim -- checker results are acceptable -- no prior findings are open -- FinalAcceptance can be created exactly once for this task, source Review, and - existing versioned Submission -- reviewer and submitter contribution lineage can be created atomically -- both frozen contribution policies can be evaluated; explicit unpaid results - are valid and create no award - -Before needs revision: - -- each issue has a required fix -- severity is accurate -- feedback is actionable -- no unrelated refactor or preference is demanded - -Before rejection: - -- rejection reason is grounded in the guide -- evidence is cited -- task is not merely fixable +Before any decision: + +- confirm the exact active lease and packet; +- use the guide/policy context stamped on the Submission; +- verify the admitting CheckerRun belongs to that Submission; +- ground judgment in acceptance criteria and available evidence; +- check all required prior responses and resolutions; +- distinguish blocking requirements from advisory observations; +- confirm the decision-specific task, assignment, FinalAcceptance, and + contribution effects can commit atomically. +- confirm both frozen contribution policies can be evaluated and that an + explicit unpaid result is valid and creates no award. + +Before `needs_revision`, confirm every blocking issue has an actionable required +change and no unrelated preference is demanded. Before `reject`, confirm the +bounded reason is guide-grounded and the work is not reasonably fixable. + +Offline sampling and calibration may evaluate review quality, but they do not +create adjudication state, overturn a Review, or mutate immutable history. ## Non-Mutating Quality Sampling diff --git a/docs/operations_revision_replay.md b/docs/operations_revision_replay.md index 69219a2da..8c1962286 100644 --- a/docs/operations_revision_replay.md +++ b/docs/operations_revision_replay.md @@ -1,85 +1,92 @@ # Revision Replay -## Purpose +## Status And Purpose -Revision replay prevents the common failure where a task comes back, the contributor says it is fixed, and nobody can prove which reviewer issues were actually closed. +This is the planned v0.1 operating contract. Revision behavior remains +unavailable until its owning REV chunks, exact AUTH activation, and REV-13 joint +release complete. -Every resubmission after `NEEDS_REVISION` must map prior findings to concrete fixes. +Revision replay preserves an immutable answer to three questions: what the +reviewer required, how the submitter responded, and how a later reviewer +resolved each issue. No participant edits a prior Review, finding, response, or +resolution. -## Required Replay Fields +## Review-Rooted Preparation -For each prior finding: +Human revision begins only from an immutable `Review(needs_revision)`. Checker +remediation remains CheckerResult-rooted and does not fabricate a Review episode. -- prior finding id -- prior severity -- prior area -- required fix -- contributor fix summary -- evidence reference -- contributor claim status: `fixed`, `disputed`, or `not_applicable` +Before contributor access, Workstream appends a RevisionContextPreparation. It +compares the prior Submission's stamped Project Guide identity and activation +sequence with the currently active guide: -Reviewer closure status: +- exact pair match: `kept`; +- any different valid active pair: `rebased` with `forward` or `backward`; +- missing, incomplete, inconsistent, revoked, or unsafe context: `blocked`. -- `closed_fixed` -- `closed_rebutted` -- `partially_closed` -- `still_open` -- `obsolete` +The preparation freezes the selected guide/source/task-execution policy context, +context digest, prior Submission, originating Review, source and target +TaskAssignments, and change summary. Task Context returns the validated head, +not a moving live guide. No guide rebase occurs during review; the reviewer +reads the context stamped on the leased Submission. -## Contributor Rules +ContributionPolicyVersion is independent. The TaskAssignment freeze and each +ReviewLease freeze never change because guide context rebases. -The contributor must: +## Submitter Response -- address every high and medium finding -- attach evidence for every claimed fix -- explain any disputed finding directly -- avoid bundling multiple findings into vague "fixed all" notes +For each unresolved blocking ReviewFinding, the assigned submitter creates one +immutable SubmissionFindingResponse containing: -## Reviewer Rules +- finding ID; +- response text and concrete change summary; +- optional finalized evidence binding; +- exact preparation head ID and digest; +- target Submission and TaskAssignment lineage. -The reviewer must: +Advisory findings may be answered but do not block resubmission unless the locked +policy explicitly requires a response. Vague aggregate “fixed all” text cannot +replace per-finding responses. -- check each replay row -- mark closure status per finding -- only introduce new findings when they are real and guide-grounded -- avoid moving goalposts unless the new issue blocks acceptance +## Resubmission And Checks -## Blocking Policy +Submission N+1 acknowledges the exact preparation head/digest, links its +immediate predecessor, and stamps the frozen context. The normal finalization +and checker spine reruns. Only a current successful `allow_review` may create a +new queue entry. -A resubmission cannot move to `REVIEW_PENDING` when: +The queue initially prefers the reviewer who requested revision. Expiry, +decline, or invalidation opens the entry without resetting queue age. -- prior high finding has no replay row -- prior medium finding has no replay row -- replay row has no fix summary -- replay row has no evidence and project policy requires evidence +## Reviewer Resolution -Low findings can be left unresolved if the reviewer marks them as informational. +The later Review appends one FindingResolution for every required prior finding: -## Revision Context Preparation +- `resolved`; +- `unresolved`; +- `not_applicable`. -Before the contributor resumes a task in `NEEDS_REVISION`, Workstream prepares the next revision context. +Each resolution carries bounded rationale and optional evidence. It never edits +the original finding or submitter response. A new guide-grounded issue becomes a +new ReviewFinding on the later Review. -That preparation compares the prior submission's locked project guide and policy versions with the current active guide and policy versions. Revision policy decides whether the next attempt keeps the prior context, rebases to the latest active context, or is blocked for project-manager repair. +## Limits And Recovery -A rebase does not change the prior submission. It only defines the guide and policy context for the next submission attempt. +A reached revision limit or deadline blocks further preparation and +`submission.create`; it does not automatically reject or cancel the task. The +task remains `needs_revision` until a covered Project Manager explicitly invokes +the planned reason-bound obligation-close command. That administrative closure +uses task `cancelled`, releases the assignment, and creates no synthetic Review +or contribution. -When a rebase happens, the contributor must see: +A blocked or invalid Review-rooted preparation can be repaired only by appending +one successor through the planned covered-manager repair command. Legacy +`needs_revision` state with no Review/root requires an Operator evidence-linked +legacy close and cannot enter normal revision replay. -- prior guide and policy versions -- next guide and policy versions -- guide or policy change summary -- reason the next attempt was rebased +## Required Proof -The reviewer must see the same context change in the review packet. A reviewer cannot apply out-of-band guidance unless it was encoded into the guide, policy, task template, or checker contract that governed the attempt. - -## Replay Table - -| Prior Finding ID | Required Fix | Contributor Fix Summary | Evidence | Contributor Status | Reviewer Closure | -| --- | --- | --- | --- | --- | --- | -| `RF-001` | `` | `` | `` | `fixed` | `still_open` | - -## Operational Standard - -Revision replay is not optional paperwork. It is the memory of the system. - -If the replay is weak, the platform fails the resubmission before a reviewer spends time on it. +A revision cannot return to human review unless every unresolved blocking +finding has one response, the exact preparation is still current, Submission +lineage is immediate and same-task, evidence bindings are finalized, and the +new CheckerRun is current for that Submission. diff --git a/docs/operations_roles_permissions.md b/docs/operations_roles_permissions.md index c752d5faa..d36f87476 100644 --- a/docs/operations_roles_permissions.md +++ b/docs/operations_roles_permissions.md @@ -36,8 +36,8 @@ not permit claiming tasks, submitting work, or recording review decisions. | Grant | Scope | Purpose | |---|---|---| | Submitter | exact project | Minimal project read, queue/claim/start under task guards, own submission creation/read. | -| Reviewer | exact project | Minimal project read, review queue/claim/release/decision under review guards. | -| Adjudicator | exact project | Minimal project read; no adjudication capability until WS-REV defines the lifecycle and AUTH activates exact adjudication actions. | +| Reviewer | exact project | Minimal project read and the planned server-selected current-work/claim/release/decision capabilities under exact review guards. | +| Adjudicator | exact project | Minimal project read only; v0.1 has no adjudication lifecycle or action. | Contributor is the umbrella human product term. A contributor may hold independent exact-project Submitter, Reviewer, and Adjudicator grants. Celery, @@ -63,7 +63,7 @@ or the exact project; own means record-level ownership still applies. | Task queue/claim | no | operational projection only | management projection only | no | read covered | exact project under guards | no | no | | Submission create/read | no | operational projection only | management projection only | no | read covered | own assignment | read-for-review only | no | | Human review decision | no | no | no without reviewer grant | no | no | no | exact project under review guards | no | -| Adjudication action | no | no | no | no | no | no | no | unavailable; requires WS-REV contract plus AUTH action activation | +| Adjudication action | no | no | no | no | no | no | no | unavailable in v0.1; future separate initiative | | Compensation award read and delivery reconciliation | no | no | no | covered | read covered | no | no | no | | Fulfillment result recording | no | no | no | no; authenticated WS-CON adapter callback only | read covered | no | no | no | | Audit read/export | authority history system | operational system | project covered | finance covered | covered | own chain only | assigned chain only | no | @@ -104,6 +104,10 @@ Recovery is a separate, reasoned, audited path. | Submission gate repair | `operations.submission_gate.repair` | Operator | | Checker retry | `operations.checker.retry` | Operator | | Review lease force release | `review.lease.force_release` | Operator under WS-REV-001 | +| Revision-context repair | `project.task.manage` via planned `review.revision_context.repair` | Covered Project Manager | +| Revision-obligation close | `project.task.manage` via planned `review.revision_obligation.close` | Covered Project Manager | +| Legacy revision close | `operations.reconcile.run` via planned `review.revision_context.legacy_close` | Operator | +| Lifecycle release control | `operations.reconcile.run` via planned `review.lifecycle.activation.manage` | Operator | Every recovery mutation records the exact actor, matched grant/permission, project/resource, reason, bounded before/after state, request/correlation IDs, @@ -111,6 +115,10 @@ and immutable evidence. Recovery cannot erase checker results, rewrite submissions, create review decisions, alter contribution history, or bypass contribution award rules. +The review/revision rows above are contract declarations, not active runtime +capabilities. Their exact guards and release gates are defined in +`docs/spec_review_lifecycle.md`; no review route is exposed before REV-13. + ## Provisioning And Revocation The first Access Administrator is created once through a restricted local diff --git a/docs/principles.md b/docs/principles.md index 80616888a..70df466b9 100644 --- a/docs/principles.md +++ b/docs/principles.md @@ -12,7 +12,7 @@ Operators and agents may do the actual work outside Workstream. Workstream owns - revision replay - contribution records - compensation awards, fulfillment receipts, and projections -- reputation records +- reputation projections when separately implemented The first product is task evaluation and contribution infrastructure, not an execution IDE. @@ -61,12 +61,12 @@ Blocking pre-submit failures block submission creation before a submission versi Automated checks can enforce structure. Human reviewers decide whether the work is actually good, useful, original, and aligned with the project guide. -Reviewers must produce actionable findings: +Reviewers must produce actionable immutable findings: - what failed - why it matters - what must change -- severity +- blocking or advisory lifecycle meaning - evidence ## 5. Needs Revision Is A First-Class State @@ -77,21 +77,26 @@ Needs revision is not a side note. It is a formal loop: NEEDS_REVISION -> SUBMITTED -> EVALUATION_PENDING -> REVIEW_PENDING ``` -While a task is in `NEEDS_REVISION`, the assigned contributor can run pre-submit -feedback and submit a replacement version directly. The system must preserve -original feedback, fix notes, evidence, and closure. +While a task is in `NEEDS_REVISION`, the assigned contributor receives the +frozen preparation, responds to every unresolved blocking finding, and submits +a replacement version. The system preserves immutable findings, responses, +evidence, and later resolutions. -The system must also preserve guide and policy context. Prior submissions keep their locked context; revision policy decides whether the next attempt rebases to the latest active context before the contributor resumes. +Prior Submissions keep their stamped context. Preparation compares the prior +guide identity/activation sequence with the currently active guide: exact match +keeps, any different valid pair rebases forward or backward, and unsafe context +blocks. Task Context returns the frozen preparation. No guide rebase occurs +during review. ## 6. Compensation Follows Contribution The first version uses immutable contribution and compensation-award records with manually recorded fulfillment. Blockchain settlement comes later. -Every valid human review creates a reviewer contribution. Accepted work -additionally creates a submitter contribution. Compensation and reputation -updates attach to the applicable immutable contribution; explicit unpaid rules -create no award. +Every valid human Review creates a reviewer contribution. Accept additionally +creates FinalAcceptance, and only that fact creates the submitter contribution. +Compensation attaches to the applicable immutable contribution; explicit unpaid +rules create no award. Reputation remains a separately implemented projection. `CompensationAward` and `CompensationFulfillmentReceipt` records track: @@ -101,9 +106,10 @@ create no award. - delivery and fulfillment status - immutable fulfillment receipt and external reference -## 7. Reputation Must Be Earned From Outcomes +## 7. Future Reputation Must Be Earned From Outcomes -Reputation is not a profile badge. It is computed from work history: +When separately implemented, reputation is computed from work history rather +than assigned as a profile badge: - acceptance rate - revision rate diff --git a/docs/product_first_user_flows.md b/docs/product_first_user_flows.md index 71e459b6b..e7c4d5e76 100644 --- a/docs/product_first_user_flows.md +++ b/docs/product_first_user_flows.md @@ -1,5 +1,12 @@ # First User Flows +## Status + +The review and revision portions are the planned v0.1 contract and remain +unavailable until their owning REV chunks, exact AUTH activation, and REV-13 +joint release complete. Earlier project/task/submission/checker behavior keeps +its separately recorded implementation status. + The first user flows prove that Workstream can run real work from intake to acceptance. These flows come before any advanced routing or settlement. ## Flow 1: Project Manager Creates A Project @@ -103,32 +110,41 @@ Acceptance: 1. Checker runner validates the submission-stamped locked `PostSubmitCheckerPolicy` id/version/hash/body. 2. Runner executes enabled checks from that locked policy body. 3. Results are saved with `passed`, `warning`, or `failed`, plus severity, message, and evidence. -4. If contributor-fixable blocking failures exist, task enters `NEEDS_REVISION`. -5. If setup or provenance defects exist, the task stays in the internal operations queue. -6. If no blocking failures exist, task enters `REVIEW_PENDING`. +4. Contributor-fixable checker failures route the Task to `NEEDS_REVISION` with + `CheckerResult` lineage and no Review or reviewer contribution. +5. Setup or provenance defects keep the Task `evaluation_pending` on the + internal `task_setup_blocked` repair route. +6. Only a durable, final, current `CheckerRun` outcome of `allow_review` admits + the exact immutable Submission with verified binding facts and moves the + Task to `REVIEW_PENDING`. Acceptance: -- Critical- or high-severity failure blocks human review. +- A retry, superseded run, different Submission, non-final result, or outcome + other than `allow_review` cannot admit human review. - Warnings remain visible to reviewer. - Every checker result is timestamped. ## Flow 5: Reviewer Reviews Submission -1. Reviewer opens review queue. -2. Reviewer selects `REVIEW_PENDING` task. -3. Reviewer reads guide, task, submission, evidence, and checker results. -4. Reviewer enters structured findings. +1. Reviewer current work returns an active lease, one server-selected offer, or none. +2. Reviewer claims the offer and receives the exact ReviewPacketManifest. +3. Reviewer reads the leased Submission's stamped guide context, evidence, and checker results. +4. Reviewer enters immutable blocking/advisory findings where applicable. 5. Reviewer selects accept, needs_revision, or reject. -6. Workstream atomically creates the reviewer `completed_review` contribution; - `accept` also creates internal FinalAcceptance and then the submitter - `accepted_submission` contribution from that fact. +6. Workstream atomically appends Review history, consumes the lease, closes the + queue entry, and runs the CON reviewer operation for `completed_review`. +7. For `accept`, REV then creates internal FinalAcceptance, applies accepted + Task and completed Assignment effects, and runs the CON submitter operation + for `accepted_submission` from that fact. Acceptance: - Review cannot be submitted without a decision. -- needs_revision and reject require at least one finding. -- accept requires no unresolved critical- or high-severity checker failure. +- needs_revision requires at least one blocking finding; reject requires a + bounded human reason and may include findings. +- the leased Submission must retain its exact durable, final, current + `allow_review` CheckerRun admission and verified binding facts. - Every valid human decision has exactly one reviewer contribution. - Accept sets Task `accepted`, Assignment `completed`, and has exactly one FinalAcceptance and one submitter contribution. @@ -140,40 +156,49 @@ Acceptance: - FinalAcceptance has no manual API/action and no adjudication/reopen path. - Only accept has a submitter contribution. -## Flow 6: Revision Replay +## Flow 6: Human Review Revision Replay -1. Contributor opens needs-revision task. -2. Workstream prepares revision context from the revision policy. -3. Contributor sees prior guide/policy version, next guide/policy version, and any change summary when the task was rebased. -4. Contributor sees each finding as a checklist item. -5. Contributor adds fix note and evidence per finding. +1. Contributor opens a needs-revision task rooted in an immutable + `Review(needs_revision)`. +2. Workstream prepares immutable context from the currently active Project Guide. +3. Exact prior identity/activation-sequence match keeps; any different valid + active pair rebases forward or backward; unsafe context blocks. +4. Contributor sees the frozen preparation and each unresolved blocking finding. +5. Contributor appends one SubmissionFindingResponse and optional evidence per required finding. 6. Contributor resubmits. 7. Checkers rerun. -8. Reviewer closes or reopens each finding. +8. Reviewer appends one FindingResolution per required prior finding. + +Checker-caused remediation is separate: it retains `CheckerResult` lineage, +creates no Review, ReviewFinding, SubmissionFindingResponse, FindingResolution, +or reviewer contribution, and returns through the normal submission/checker +spine before human review. Acceptance: - Prior review remains visible. - Context changes are visible before the contributor revises. -- Each required finding has a closure state. +- Each required finding has an immutable response and later resolution. - Revision count is tracked against the locked revision policy. -- Resubmission is blocked or rejected when the revision policy limit or deadline says so. +- A reached limit/deadline blocks resubmission but never auto-rejects or + auto-closes the task; manager cancellation is a separate planned command. -## Flow 7: Accepted Work Creates Submitter Contribution +## Flow 7: Accepted Work, FinalAcceptance, And Submitter Contribution 1. Reviewer accepts task. -2. Task enters `ACCEPTED`. -3. The reviewer `completed_review` contribution already created with the Review +2. The reviewer `completed_review` contribution created after the Review remains immutable. -4. A submitter `accepted_submission` contribution is created from the accepted - submission, accepting review, frozen policy lineage, and artifact hash. -5. The frozen reviewer and submitter contribution policies independently create +3. REV creates immutable FinalAcceptance from the accepting Review. +4. The Task enters `ACCEPTED` and the TaskAssignment becomes `completed`. +5. The CON submitter operation creates `accepted_submission` only from + FinalAcceptance, TaskAssignment, frozen policy lineage, and artifact hash. +6. The frozen reviewer and submitter contribution policies independently create applicable awards; explicit unpaid rules create none. -6. Reputation and project projections update from the contribution records. +7. External fulfillment runs after commit; reputation projection is deferred. Acceptance: -- Accepted task cannot lack its submitter contribution record. +- Accepted task cannot lack FinalAcceptance or its submitter contribution record. - Every accepted Review cannot lack its reviewer contribution record. - A payable contribution cannot lack its immutable CompensationAward and fulfillment projection; an explicit unpaid policy creates no award. diff --git a/docs/product_principles.md b/docs/product_principles.md index 5eb1b6d19..e91460a95 100644 --- a/docs/product_principles.md +++ b/docs/product_principles.md @@ -13,7 +13,7 @@ Workstream owns: - review decision - revision history - compensation awards and fulfillment state -- reputation ledger +- reputation projection when separately implemented Workstream is source-agnostic, but v0.1 stays manual-first. External origin adapters and automated routing stay out until the internal loop works. @@ -30,15 +30,21 @@ rule matters, it belongs in the project guide, submission artifact policy, checker policy, review policy, revision policy, contribution policy, or task template. -When a guide or policy changes while work is already in progress, prior submitted attempts remain tied to their locked context. If the task returns for revision, revision policy decides whether the next attempt rebases to the latest active context, and the contributor must see what changed. +Prior submitted attempts remain tied to their stamped context. Human-review +revision preparation compares the prior Project Guide identity/activation +sequence with the currently active pair: exact match keeps, any different valid +pair rebases forward or backward, and unsafe context blocks. The contributor +sees the frozen result and the reviewer consumes the context stamped on the +leased Submission without rebasing. ## 3. Same Lifecycle, Different Domain Language Projects may differ by domain, language, task format, or review style. The lifecycle remains stable: ```text -Guide -> Task -> Submission -> Checker -> Review -> Revision/Decision --> Contribution -> Conditional Compensation Award/Fulfillment -> Reputation +Guide -> Task -> Submission -> Checker -> Review -> Revision/FinalAcceptance +-> Contribution -> Conditional Compensation Award/Fulfillment +-> deferred reputation projection ``` ## 4. Automated Checks Protect Human Review @@ -59,11 +65,16 @@ The system improves reviewer judgment. It does not pretend to replace it. Workstream allows humans to use agents and external tools, but the human contributor or owner is accountable for the submitted packet. -The first version enforces accountability through assignment ownership, contributor attestation, immutable submission versions, evidence, review decisions, and reputation events. A built-in owner-agent execution workspace is later work. +The first version enforces accountability through assignment ownership, +contributor attestation, immutable Submission versions, Reviews, findings, +responses, resolutions, and evidence. Reputation events and a built-in +owner-agent execution workspace are later work. ## 6. Revision Is A State, Not A Failure -Needs revision is a normal lifecycle state. The system must preserve feedback, require closure, and make resubmission easy to audit. +Needs revision is a normal lifecycle state. The system preserves immutable +feedback, requires one response per unresolved blocking finding and one later +resolution, and makes resubmission auditable. Revision must also preserve context. Contributors and reviewers need to know which guide and policy versions governed the prior attempt and which versions govern the next attempt. @@ -71,9 +82,9 @@ Revision must also preserve context. Contributors and reviewers need to know whi Every acceptance is backed by evidence. Evidence can include checker logs, test results, screenshots, file hashes, review notes, or before/after diffs. -## 8. Reputation Must Be Earned +## 8. Future Reputation Must Be Earned -Reputation comes from outcomes: +When separately implemented, reputation comes from outcomes: - accepted work - revision rate @@ -95,8 +106,8 @@ Even when fulfillment is manual, Workstream must track: - delivery and fulfillment status - immutable fulfillment receipt and external reference -Every valid human review creates a reviewer contribution. Accepted work also -creates a submitter contribution. Frozen contribution award rules create immutable +Every valid human Review creates a reviewer contribution. Accept also creates +FinalAcceptance, and only that fact creates a submitter contribution. Frozen contribution award rules create immutable awards only for payable contributions; explicit unpaid rules create no award. Fulfillment receipts and status projections track delivery separately. diff --git a/docs/reference_specs/README.md b/docs/reference_specs/README.md index aa36d0495..240df1d43 100644 --- a/docs/reference_specs/README.md +++ b/docs/reference_specs/README.md @@ -1,8 +1,10 @@ # Workstream Reference Specifications -The WS-ARCH/WS-AUTH/WS-CON/WS-IMP inputs were supplied on 2026-07-11. The -canonical WS-REV Markdown/PDF pair was replaced by the revised supplied pair on -2026-07-15 after duplicate `(2)` filenames were corrected. +The checksum-listed WS-ARCH/WS-AUTH/WS-CON/WS-IMP inputs were supplied on +2026-07-11. The canonical WS-REV Markdown/PDF pair was replaced by the revised +supplied pair on 2026-07-15 after duplicate `(2)` filenames were corrected. +The table below contains the eight inputs governed by the central +`SHA256SUMS` manifest. | File | Status | SHA-256 | |---|---|---| @@ -19,9 +21,24 @@ The same values remain machine-checkable in `SHA256SUMS` and are bound by the initiative source manifests. A checksum changes only when the human supplies a replacement archival input; reconciliation never edits archival content. +The WS-CON initiative also records two exact inputs pending its CON-01 +adoption: a revised `(2).pdf` archival input and a Markdown working +transcription. Their hashes and provenance live in the WS-CON source manifest. +The working transcription is historical, noncanonical material; it is neither +an archival input nor runtime authority. + +The revised WS-REV Markdown includes section 4.6's closed action/permission +table, while the supplied PDF companion does not. They are separately preserved +archival artifacts rather than generated twins. The repository reconciles that +difference in the active contract without editing either file. + These inputs are not the repository's reconciled runtime contract. In particular, Workstream retains the canonical `/api/v1` namespace even where an -archival input uses `/v1`. WS-AUTH-001 takes precedence over the current -token-role authorization bootstrap under accepted ADR 0012. The reconciled -canonical text lives in `docs/spec_authorization_service.md`; active repository -documentation points there without editing the eight archived files. +archival input uses the old root-level version-one namespace. WS-AUTH-001 takes +precedence over the current token-role authorization bootstrap under accepted +ADR 0012. The reconciled +canonical authorization text lives in `docs/spec_authorization_service.md`. +The active review/revision contract lives in `docs/spec_review_lifecycle.md`. +Active repository documentation points to those contracts without editing the +eight checksum-listed archival files or treating the CON working transcription +as authority. diff --git a/docs/reference_specs/SHA256SUMS b/docs/reference_specs/SHA256SUMS index 03658d7ec..b61ecf0f3 100644 --- a/docs/reference_specs/SHA256SUMS +++ b/docs/reference_specs/SHA256SUMS @@ -1,3 +1,4 @@ +# Immutable archival inputs only. Active review contract: docs/spec_review_lifecycle.md 547176dcedf41895ed896d5262a6ab8c6c029d71dac50bd17ed9da65f692b9b3 docs/reference_specs/WS-ARCH-001-workstream-v0.1-architecture-baseline.pdf 464a7afb032e950b83e8fdb8c04fafe0b9ebddf549c4475dca684946740869a9 docs/reference_specs/WS-AUTH-001-actor-profile-role-and-authorization-service-specification.md 69670ed59006b29cb7f60d12101cedf250c82a3488497f07d6c27e140aef1d2e docs/reference_specs/WS-AUTH-001-actor-profile-role-and-authorization-service-specification.pdf diff --git a/docs/risk_register.md b/docs/risk_register.md index 8cb5679bf..92ce6e69c 100644 --- a/docs/risk_register.md +++ b/docs/risk_register.md @@ -32,9 +32,11 @@ A task can be sent back for revision after the project guide or policies changed Mitigation: -- prior submissions remain tied to their locked guide and policy versions -- revision policy controls whether the next attempt rebases to current active guide and policy context -- contributor and reviewer packets show prior version, next version, rebase reason, and change summary +- prior Submissions remain tied to their stamped guide and policy context +- exact stamped guide identity/activation-sequence match keeps context; any + different valid active pair rebases forward or backward; unsafe context blocks +- Task Context returns the frozen preparation; reviewer context uses the exact + leased Submission stamp without a separate rebase - every rebase records an audit event ### R2: Weak Submissions Reach Review @@ -60,7 +62,9 @@ Contributors cannot close feedback that does not specify the issue, evidence, an Mitigation: -- structured findings required +- structured blocking/advisory findings +- immutable SubmissionFindingResponse and later FindingResolution +- offline reviewer calibration without mutating product history - reviewer quality metrics - post-decision non-mutating reviewer-quality audits @@ -74,9 +78,9 @@ Tasks repeatedly return for the same issue because prior feedback is not replaye Mitigation: -- mandatory revision replay -- checker verifies prior finding coverage -- reviewer marks closure per finding +- one immutable response per unresolved blocking finding +- checker readmission binds the exact replacement Submission and preparation +- later reviewer appends a resolution per required finding ### R5: Accepted Work Not Paid @@ -88,7 +92,8 @@ Payable awards and external fulfillment can drift apart if tracked manually. Mitigation: -- every valid Review creates its required contribution records atomically +- every valid Review creates reviewer contribution atomically; accept also + creates FinalAcceptance and the submitter contribution sourced from it - payable contributions create immutable awards; explicit unpaid rules create none - daily award/fulfillment reconciliation @@ -104,10 +109,10 @@ Bad review decisions can demoralize contributors and corrupt quality metrics. Mitigation: -- reviewer reputation -- non-mutating reviewer-quality sampling -- reviewer-quality signal tracking -- escalation process +- evidence-backed reviewer quality projections when separately implemented +- offline sampling and calibration +- immutable decision/finding history for future analysis +- no v0.1 adjudication or mutable overturn path ### R7: Fake Evidence @@ -156,7 +161,8 @@ Mitigation: - enforce state transitions in code - require checker run id before `REVIEW_PENDING` -- require review id before `ACCEPTED` +- require accepting Review, FinalAcceptance, and exact reviewer/submitter + contribution source shapes before `ACCEPTED` - require an immutable payable award, exact fulfillment receipt, and external reference before fulfillment status can become `fulfilled` - replace broad historical override language with registered, scoped, @@ -172,12 +178,14 @@ Reviewers can repeatedly approve weak work for favored contributors or skip evid Mitigation: -- sample accepted work for a non-mutating post-decision quality audit -- flag repeated contributor-reviewer pairs +- sample accepted work through offline quality analysis that creates no product + Review, decision, adjudication state, or authority +- flag repeated contributor-reviewer pairs for operator investigation - require evidence citation on accept -- track unsupported-decision quality signals -- require independent non-mutating quality audits for high-value or disputed - tasks; they cannot delay or replace the recorded decision +- record quality concerns as audit/operations evidence without overturning or + mutating the immutable Review +- include high-value or disputed tasks in configurable offline samples; sampling + cannot delay or replace the recorded decision ### R12: Bad Project Guides @@ -208,7 +216,8 @@ Mitigation: - project guides define banned low-quality patterns - checkers flag repeated boilerplate, placeholders, and fabricated helper artifacts - reviewers judge task-specific evidence, not formatting polish -- repeated pattern matches affect contributor reputation +- repeated pattern matches remain future reputation inputs only after separate + reputation implementation ### R14: Compensation Disputes diff --git a/docs/roadmap_30_day_master_plan.md b/docs/roadmap_30_day_master_plan.md index 559d25da0..1e8bfeebd 100644 --- a/docs/roadmap_30_day_master_plan.md +++ b/docs/roadmap_30_day_master_plan.md @@ -1,10 +1,21 @@ # 30-Day Master Plan +## Review Lifecycle Status + +The schedule is planning guidance, not a claim that review/revision routes are +live. Those surfaces remain unavailable until their approved WS-REV chunks, +exact AUTH activation, and REV-13 joint release complete. + ## Goal -Build the first serious version of Workstream: Flow's configurable task evaluation and contribution infrastructure that can run real internal projects from guide to contribution record, review decision, payment status, and reputation signal. +Build the first serious version of Workstream: Flow's configurable task +evaluation and contribution infrastructure that can run real internal projects +from guide to contribution record, review decision, and compensation status. -The output of the 30 days is not a demo-only UI. It is usable infrastructure with durable contribution records, project templates, automated checks, human review, revision replay, and payment/reputation ledgers. +The output of the 30 days is not a demo-only UI. It is usable infrastructure +with durable contribution records, project templates, automated checks, human +review, revision replay, and compensation award/fulfillment records. Reputation +is a separately approved later consumer. ## Scope @@ -18,8 +29,7 @@ In scope: - revision loop - evidence storage - contribution records -- payment ledger -- reputation ledger +- compensation award and fulfillment ledger - dashboards for current status - pilot with real tasks @@ -50,7 +60,8 @@ Payment status is separate: NONE -> PENDING -> PAYOUT_SUBMITTED -> PAID ``` -If a feature does not improve lifecycle correctness, review quality, evidence, payment tracking, or reputation, defer it. +If a feature does not improve lifecycle correctness, review quality, evidence, +or compensation tracking, defer it. Reputation is already deferred. ## Week 1: Foundation @@ -68,8 +79,7 @@ Deliverables: - roles and permissions matrix - submission record - evidence record -- payment policy context -- reputation dimensions +- contribution and compensation policy context - backend API smoke paths for project, task, assignment, and submission records - workspace/packet convention for the first project - modular monolith structure with clean router, service, repository, interface, and adapter boundaries @@ -101,7 +111,6 @@ Day 3: Day 4: - build worker and reviewer profiles -- define reputation dimensions - add assignment and claim logic Day 5: @@ -213,15 +222,14 @@ Objective: make human review auditable, consistent, and useful. Deliverables: -- review queue +- reviewer current work with an active lease, one server-selected offer, or none - review packet - finding model -- severity model +- blocking/advisory lifecycle model - accept / needs_revision / reject decisions - revision replay - revision context preparation and guide/policy rebase audit -- reviewer metrics -- second-review flag +- offline reviewer quality metrics without product adjudication state Day 11: @@ -232,11 +240,11 @@ Day 11: Day 12: - build finding model: - - severity + - lifecycle meaning: blocking or advisory - area - issue - required fix - - evidence reference + - immutable evidence relation to a finalized ART binding Day 13: @@ -250,7 +258,7 @@ Day 14: - prior issue - fix summary - evidence - - closed / still open + - immutable later resolution: `resolved | unresolved | not_applicable` Day 15: @@ -259,19 +267,21 @@ Day 15: Week 3 acceptance bar: -- reviewers cannot issue vague decisions without findings +- accept requires acceptance evidence; `needs_revision` requires an unresolved + blocking finding; reject requires a bounded human reason and findings remain + optional - every `needs_revision` has concrete fix requirements -- every resubmission must close prior feedback +- every resubmission must answer each unresolved blocking finding and preserve + later immutable resolution - accept, needs_revision, and reject decisions are auditable -## Week 4: Payment, Reputation, Pilot +## Week 4: Compensation, Pilot Objective: run real tasks and harden the operating loop. Deliverables: -- payment ledger -- reputation ledger +- compensation award and fulfillment ledger - project dashboard - worker dashboard - reviewer dashboard @@ -289,12 +299,8 @@ Day 16: Day 17: -- implement reputation updates: - - acceptance rate - - revision rate - - rejection rate - - review quality - - skill tags +- prove compensation outbox delivery, retry, callback, and immutable receipt + behavior; keep reputation out of the v0.1 transaction Day 18: @@ -324,8 +330,7 @@ Day 22: - accept/reject pilot tasks - create contribution records -- record payment outcomes -- update reputation +- record compensation outcomes when payable Day 23: @@ -378,7 +383,7 @@ Week 4 acceptance bar: - at least 10 real tasks entered - at least 5 complete submission cycles - at least 2 revision cycles -- payment and reputation records generated +- contribution records and conditional compensation records generated - one pilot report completed ## Success Metrics @@ -395,7 +400,7 @@ Operations: - at least 10 pilot tasks - at least 5 completed cycles - median review turnaround under 24 hours for pilot -- no accepted task without payment record +- no payable accepted contribution without its CompensationAward - no accepted task without contribution record Quality: @@ -404,7 +409,8 @@ Quality: - reviewer findings are actionable - revision replay closes prior feedback - accepted work can be audited later -- accepted work has contribution records before payment and reputation updates +- accepted work has FinalAcceptance-sourced contribution records before any + compensation fulfillment ## Main Risks diff --git a/docs/roadmap_day_by_day_execution_plan.md b/docs/roadmap_day_by_day_execution_plan.md index 5ea6261f9..2cd52e78d 100644 --- a/docs/roadmap_day_by_day_execution_plan.md +++ b/docs/roadmap_day_by_day_execution_plan.md @@ -1,5 +1,11 @@ # Day-by-Day Execution Plan +## Review Lifecycle Status + +The calendar is sequencing guidance, not implementation status. Review and +revision behavior remains planned and unavailable until its approved WS-REV +chunks, exact AUTH activation, and REV-13 joint release complete. + ## Purpose This is the execution calendar for the first 30 days. The master plan explains the strategy; this file defines what happens each day and what must be true before moving on. @@ -39,7 +45,7 @@ Exit criteria: - no task can exist without a project - no project can exist without a guide -- no accepted task can exist without payment and evidence concepts +- no accepted task can bypass contribution-policy evaluation or evidence lineage - no backend implementation starts without chunk specification and conditions of satisfaction ### Day 2: Project And Guide Records @@ -133,7 +139,9 @@ Exit criteria: ## Week 2: Checker System -Week 2 is backend-first checker infrastructure. Checker output is exposed through APIs, backend contract drills, and operational debug output. It does not build the product frontend, reviewer queue UI, review decision form, contribution records, payment records, or reputation updates. +Week 2 is backend-first checker infrastructure. Checker output is exposed +through APIs, backend contract drills, and operational debug output. It builds +none of the later product surfaces. Deferred reputation is outside Week 2. The core invariant is: @@ -232,7 +240,7 @@ Exit criteria: Deliver: -- reviewer queue +- reviewer current work with an active lease, one server-selected offer, or none - review page - checker result panel - task guide panel @@ -248,15 +256,16 @@ Deliver: - `Review` - `ReviewFinding` -- severity +- lifecycle meaning: `blocking | advisory` - area - issue - required fix -- evidence reference +- immutable `ReviewEvidenceArtifact` relation to finalized ART binding Exit criteria: -- `needs_revision` and `reject` require at least one finding +- `needs_revision` requires at least one unresolved blocking finding +- `reject` requires a bounded human reason; findings are optional - `accept` requires checklist confirmation - `accept` requires evidence references, not only a free-text approval @@ -265,8 +274,8 @@ Exit criteria: Deliver: - `review_pending -> needs_revision` -- feedback history -- task unlock for worker +- immutable finding/response/resolution history +- keep the TaskAssignment active for the assigned submitter - resubmission requirements Exit criteria: @@ -278,15 +287,16 @@ Exit criteria: Deliver: -- `RevisionReplay` -- `RevisionFix` -- closure status -- prior finding mapping +- `RevisionContextPreparation` +- `SubmissionFindingResponse` +- immutable later `FindingResolution` +- prior blocking-finding mapping Exit criteria: -- every prior high/medium finding is mapped to a fix or explicit dispute -- reviewer can mark closed/still open +- every unresolved blocking finding has one immutable response +- the later reviewer appends `resolved`, `unresolved`, or `not_applicable` + without editing prior history ### Day 15: Review Quality Metrics @@ -295,8 +305,7 @@ Deliver: - reviewer turnaround - decision distribution - unclear feedback flag -- overturned decision marker -- second-review marker +- offline sampled-quality marker with no product adjudication state Exit criteria: @@ -309,9 +318,9 @@ Exit criteria: Deliver: - `ContributionRecord` -- `PaymentRecord` -- accepted amount -- pending amount +- `CompensationAward` +- `CompensationFulfillmentReceipt` +- pending fulfillment projection - paid amount - payment status - payment reference @@ -320,22 +329,25 @@ Deliver: Exit criteria: -- accepted work creates a contribution record -- accepted work creates pending payment record +- every valid Review creates reviewer contribution +- for accepted work, FinalAcceptance alone sources the additional submitter + contribution +- only a payable contribution creates a CompensationAward and fulfillment + projection - paid payment status requires payment reference -### Day 17: Reputation Ledger +### Day 17: Compensation Delivery Proof Deliver: -- `ReputationEvent` -- worker quality events -- reviewer quality events -- skill-tag scoring +- outbox delivery and retry +- authenticated fulfillment callback +- immutable fulfillment receipt +- failed/pending/fulfilled projection recovery Exit criteria: -- accepted, needs revision, rejected, and review-quality events are recorded +- payable awards have exact delivery lineage; reputation remains deferred ### Day 18: Dashboards @@ -395,18 +407,18 @@ Deliver: - accepted decisions - rejected decision if warranted - contribution records -- payment records -- reputation events +- compensation awards/fulfillment records when payable Exit criteria: -- accepted work has evidence, contribution record, and pending payment +- accepted work has evidence and both required contribution source checks; + payable records alone have pending compensation fulfillment ### Day 23: Reviewer Audit Deliver: -- second-review audit on accepted/rejected tasks +- offline quality audit on accepted/rejected tasks with no new product decision - reviewer findings quality report Exit criteria: @@ -475,7 +487,7 @@ Deliver: Exit criteria: - no silent state changes -- no accepted task missing payment/evidence +- no accepted task bypasses evidence lineage or contribution-policy evaluation ### Day 29: Pilot Report diff --git a/docs/roadmap_implementation_backlog.md b/docs/roadmap_implementation_backlog.md index f26c0df45..270e729ab 100644 --- a/docs/roadmap_implementation_backlog.md +++ b/docs/roadmap_implementation_backlog.md @@ -1,5 +1,11 @@ # Implementation Backlog +## Review Lifecycle Status + +Review/revision entries describe planned, unavailable v0.1 work. They become +executable only through the approved WS-REV chunk order, exact AUTH activation, +and REV-13 joint release; this backlog does not activate an endpoint or job. + ## P0: Must Exist For v0.1 ### Backend Foundation @@ -91,38 +97,39 @@ ### Review -- review queue +- reviewer current work: active lease, one server-selected offer, or none - accept decision - needs-revision decision - reject decision -- structured findings +- immutable blocking/advisory findings - required fix per finding - require evidence citation for accept decisions - prevent self-review and conflict-of-interest review -- reviewer simulation gate for first-of-kind or high-value tasks +- keep offline quality sampling separate from product decisions ### Revision Replay - create replay for resubmission -- map each prior finding to a fix -- require evidence per fix -- reviewer closure status +- append one immutable response for each unresolved blocking finding +- append later `FindingResolution` values without editing the prior finding +- prepare the next attempt from the active Project Guide using the deterministic + keep/forward-rebase/backward-rebase/block rule ### Compensation And Reputation - reviewer contribution generated for every valid human Review; `accept` - additionally creates the submitter contribution -- compensation awards and reputation events reference the applicable - contribution record + additionally creates FinalAcceptance, which alone sources the submitter + contribution +- compensation awards reference the applicable contribution record; reputation + remains a separate future consumer - pending award fulfillment dashboard - fulfilled status with immutable receipt and external reference - future compensation issue/dispute workflow kept outside the v0.1 `CompensationStatusProjection` - new published `ContributionPolicyVersion` and `ContributionAwardDefinition` records for future amount changes; existing awards remain immutable -- contributor reputation events -- reviewer reputation events -- reviewer-pair anomaly flags +- reputation policy, events, and reviewer-pair anomaly behavior deferred to a + separately approved initiative - fast-accept-without-evidence flags ### Dashboards @@ -139,7 +146,7 @@ ## P1: Important After Core Loop Works -- second-review assignment +- separately approved future review-quality/adjudication workflow - reviewer disagreement tracking - registered Project Manager repair and Operator recovery controls - project guide approval workflow diff --git a/docs/roadmap_pilot_plan.md b/docs/roadmap_pilot_plan.md index 7394162a0..034e57ba8 100644 --- a/docs/roadmap_pilot_plan.md +++ b/docs/roadmap_pilot_plan.md @@ -62,7 +62,7 @@ Seed negative or edge-case packets during the pilot: - no submission without evidence - no review without checker results - no accepted task without contribution record -- no accepted task without payment record +- no payable accepted contribution without its CompensationAward - no manual status change without audit note ## Pilot Report diff --git a/docs/roles_permissions.md b/docs/roles_permissions.md index e41d1a250..a4d43126e 100644 --- a/docs/roles_permissions.md +++ b/docs/roles_permissions.md @@ -27,8 +27,9 @@ evaluates them against canonical resources and lifecycle guards. Contributor is the umbrella human product term. Independent exact-project Submitter, Reviewer, and Adjudicator grants determine candidate authority; one actor may hold all three rows. The adjudicator grant creates no adjudication -capability until WS-REV defines the lifecycle and AUTH activates exact -adjudication actions. Celery, checker, setup, and background workers are +capability in v0.1. A future separately approved initiative must define that +lifecycle before AUTH registers or activates exact adjudication actions. Celery, +checker, setup, and background workers are internal services, not human product roles. Administrative grants alone never authorize submission, review, or adjudication. @@ -37,14 +38,18 @@ authorize submission, review, or adjudication. - No actor administratively grants or revokes their own authority. - A submitter cannot be the sole reviewer for their own work. - Review decisions remain `accept`, `needs_revision`, or `reject` and require an - eligible exact-project reviewer grant plus review lifecycle guards. + exact active project reviewer grant, canonical human `ActorProfile.id`, and + all review lifecycle guards. No other grant substitutes. - Finance Authority cannot change review decisions or contribution records. - Audit Authority cannot mutate product state. ## Recovery Normal project repair uses covered Project Manager permission -`project.task.manage`. Operator recovery is limited to the registered +`project.task.manage`. The planned review/revision repair, obligation-close, +legacy-close, and lifecycle-control actions are unavailable until their owning +hidden behavior, AUTH activation, and REV-13 release. Existing Operator recovery +is limited to the registered permissions `operations.task.start_override`, `operations.submission_gate.repair`, `operations.checker.retry`, and the WS-REV-owned `review.lease.force_release`. @@ -52,3 +57,5 @@ WS-REV-owned `review.lease.force_release`. Recovery requires exact resource scope, a reason, matched grant/permission, and append-only evidence. It does not erase prior evidence or bypass immutable submission, review, contribution, or contribution award rules. + +The complete planned review contract is `docs/spec_review_lifecycle.md`. diff --git a/docs/spec_chunk_3_project_guide_foundation.md b/docs/spec_chunk_3_project_guide_foundation.md index 38e2aadb2..953350cc3 100644 --- a/docs/spec_chunk_3_project_guide_foundation.md +++ b/docs/spec_chunk_3_project_guide_foundation.md @@ -95,10 +95,13 @@ The v0.1 contract records: - maximum revision rounds - revision deadline in hours -- whether the task automatically rejects after the revision limit - states that allow resubmission - reviewer reassignment rule +Limit or deadline exhaustion blocks later preparation and submission. It never +creates a reject Review; the current active contract defines reason-bound +manager/Operator cancellation paths. + Activation requires a revision policy before the guide can become active. The active guide response returns revision policy beside submission artifact policy, checker policy, review policy, and payment policy so future task records can lock the full policy context. The Non-Scope section keeps only revision workflow execution out of this chunk, not revision policy itself. ## Submission Artifact Policy diff --git a/docs/spec_review_lifecycle.md b/docs/spec_review_lifecycle.md new file mode 100644 index 000000000..dc6c157eb --- /dev/null +++ b/docs/spec_review_lifecycle.md @@ -0,0 +1,780 @@ +# Review And Revision Lifecycle + +## Status And Authority + +This document is the active normative implementation contract for the planned +Workstream v0.1 human review and revision lifecycle. The lifecycle described +here is not yet available in the production API. Each owning REV chunk must +merge hidden behavior, AUTH must activate the exact registered actions, and +`WS-REV-001-13` must pass the joint release gate before any surface is exposed. + +The implementation sequence is defined by +`WS-REV-001-review-revision-lifecycle/CHUNK_MAP.md` under `.agent-loop`. This +contract defines product behavior and subsystem boundaries; it does not itself +implement a route, database table, job, authorization evaluator, artifact +capability, contribution participant, or frontend. + +## Precedence And Archival Inputs + +The supplied WS-REV and WS-IMP Markdown/PDF files under +`docs/reference_specs/` are immutable archival inputs. They are provenance, +not the reconciled runtime contract. Their hashes remain in +`docs/reference_specs/SHA256SUMS`. + +The revised WS-REV Markdown contains section 4.6's closed action/permission +table. Its supplied PDF companion does not. They are separately supplied +archival artifacts, not generated twins, and neither is edited to manufacture +agreement. This active contract reconciles that difference together with the +accepted repository ADRs, merged `WS-XINT-001` handoffs, and trusted-main AUTH, +ART, and CON planning contracts. + +When sources disagree, precedence is: + +1. accepted repository ADRs and architecture lockdown; +2. this active review lifecycle contract; +3. merged cross-initiative handoffs; +4. approved WS-REV chunk contracts; +5. archival reference specifications as historical design input. + +The canonical API namespace is `/api/v1`. Archival examples with the old +root-level version namespace do not create an alias. + +## v0.1 Boundary + +The shipping path is: + +```text +Project Guide -> Task -> Submission -> Checker admission -> Human Review +-> Revision or FinalAcceptance -> ContributionRecord +-> conditional CompensationAward -> asynchronous external fulfillment +``` + +Human review decisions are exactly: + +- `accept` +- `needs_revision` +- `reject` + +Adjudication is outside this initiative. The independent `adjudicator` project +grant remains recognized, but no adjudication action, queue, lease, policy, +state, decision, contribution type, readiness gate, or API is available in +v0.1. A future separately approved initiative may consume the immutable facts +defined here without changing their historical meaning. + +Frontend implementation is also outside this initiative. WS-REV first proves +the backend contract, lifecycle guards, operational recovery, and live API +behavior. + +## Canonical Identity And Authority + +Every persisted human lifecycle identity is the canonical active +`ActorProfile.id`. This includes the Submission contributor, TaskAssignment +contributor, preferred reviewer, ReviewLease reviewer, Review reviewer, finding +author, accepted submitter, recording reviewer, and human administrative actor. +External issuer/subject values, email, token roles, typed legacy profile IDs, +display labels, and UUID shape never substitute for actor identity or authority. + +Human review requires one exact active project `reviewer` ProjectRoleGrant plus +all resource, assignment, lifecycle, no-self-review, and actor-state guards. +Separate `submitter`, `adjudicator`, and administrative grants do not substitute. +Revoking reviewer authority does not revoke or mutate another grant. + +Read operations use the request-scoped +`AuthorizationService.require(ActionId, ResourceContext)`. REV owns canonical +resource loading and typed ResourceContext composition. REV does not import +AUTH repositories or models, read grants, reconstruct permission unions, +register actions, integrate evaluators, change `ActionOwner`, or change action +availability. + +### Current Work And Claim Choreography + +All of these endpoints remain planned and unavailable until the owning REV +chunks provide hidden behavior, AUTH registers and activates their dependencies, +and REV-13 releases the product surface. + +`GET /api/v1/reviews/current` is a concealed read, not a claim: + +```text +freshly verify the Flow token and resolve canonical ActorProfile.id +-> require(review.queue.read, exact project/resource/lifecycle context) +-> return the caller's active lease, one server-selected offer, or none +-> create no ReviewLease, packet manifest, queue mutation, or policy freeze +``` + +`POST /api/v1/reviews/claim` uses this exact AUTH-first order: + +```text +freshly verify the Flow token +-> AUTH PREP review.claim with exact request bindings +-> lock claim idempotency +-> lock the review lifecycle fence +-> lock ReviewQueueEntry +-> lock Task, TaskAssignment, Submission, and CheckerRun facts +-> recompose canonical final facts +-> AUTH validates all prepared-handle bindings, consumes the handle once, + evaluates exact current authority once, and stages bounded evidence +-> freeze the reviewer ContributionPolicyVersion and append ReviewLease plus + ReviewPacketManifest +-> stage audit/outbox rows and commit once +``` + +Any denial or race before the append follows the prepared-protocol rollback path +and creates no lease, manifest, policy freeze, audit, or product outbox effect. + +## Prepared Mutation Protocol + +Every protected review/revision mutation uses the AUTH-owned prepared protocol: + +```text +AUTH locks current authority and returns an opaque prepared handle +-> REV locks canonical feature rows +-> REV recomposes final typed facts +-> AUTH validates bindings and current authority, consumes once, evaluates once, + and stages bounded decision evidence +-> REV, task, ART, CON, audit, and outbox participants flush +-> the request route or service command commits once +``` + +The non-Pydantic, nonserializable handle is bound to the exact `AsyncSession`, +ActionId, actor-reference kind and ID, idempotency key, and canonical request +digest. Caller construction, serialization, forgery, or a wrong binding stages +no decision evidence, performs no feature mutation, and preserves the legitimate +unconsumed handle for its later exact first use. A stale or consumed handle, +including a losing concurrent duplicate, remains invalid and stages no new +state. Exactly one concurrent exact consumer may win. + +When an exactly bound handle reaches evaluation but current authority or policy +denies, the transaction owner rolls back the dirty caller transaction. AUTH +restages the unchanged bounded denial evidence in a clean transaction and the +route or service command commits that evidence once. No REV, task, ART, CON, +shared-audit, or shared-outbox effect survives. If restaging fails, nothing +commits. + +## Canonical Records + +The existing `Submission` is the versioned submission identity. Domain prose +may say “Submission version,” but no competing `SubmissionVersion` table is +created. Each finalized Submission stores immutable same-task predecessor +lineage, the exact TaskAssignment and canonical submitter that produced it, the +complete resolved guide/task-execution policy context, and the server-derived +verified `artifact_hash` supplied by the ART submission/checker cutover. +Caller `package_hash` is not trusted or silently renamed. + +REV adds these lifecycle records in later hidden chunks: + +- `ReviewQueueEntry` +- `ReviewLease` +- `ReviewPacketManifest` +- `Review` +- `ReviewFinding` +- `ReviewEvidenceArtifact` +- `RevisionContextPreparation` +- `SubmissionFindingResponse` +- `FindingResolution` +- `FinalAcceptance` +- review decision and administrative idempotency aggregates +- reconciliation findings and resolutions +- shared-outbox review projection inputs +- joint lifecycle release-control state + +Every valid reviewer decision appends one immutable Review. Every submitted +ReviewFinding and every later FindingResolution is immutable. Later rounds +append a new Submission, Review, findings, responses, and resolutions; they do +not edit prior judgment or evidence. No delete or edit endpoint exists for +these immutable records. + +Findings use lifecycle meaning `blocking` or `advisory`; they do not use the +retired generic review severities `high`, `medium`, or `low`. A +`needs_revision` decision requires at least one unresolved blocking finding. +A `reject` decision requires a bounded human reason; structured findings may +also be submitted but are not fabricated merely to satisfy a schema. + +## Policy Locks + +`ReviewPolicy` locks routing preference, lease duration, capacity, +no-self-review, finding/evidence, and decision rules. `RevisionPolicy` locks +revision limit and deadline inputs. Task execution context remains separate +from contribution terms. + +The submitter `ContributionPolicyVersion` freezes on the exact TaskAssignment. +The reviewer version freezes independently on each ReviewLease. Project Guide +rebase changes neither freeze. A later lease may freeze the then-current +reviewer terms without rewriting an earlier lease. + +## Checker Admission + +Only a durable, final, current post-submit CheckerRun outcome of `allow_review` +may admit the exact immutable Submission to human review. Admission records the +exact CheckerRun ID and verified binding facts. A retry, supersession, or +different Submission cannot silently replace that anchor. + +Checker routing is not human judgment. A checker may route contributor-fixable +problems to the user-facing task state `needs_revision`, but it creates no +Review, ReviewFinding, reviewer contribution, or Review-rooted revision episode. +Checker remediation follows its checker-result lineage and must pass the normal +submission/checker spine before human review. Human revision preparation below +is rooted only in an immutable `Review(decision=needs_revision)`. + +Queue schema migration performs no blanket historical backfill. A later audited +reconciliation may admit only an unambiguous latest finalized Submission with a +current successful `allow_review`, compatible `review_pending` task state, and +verified required bindings. Ambiguous legacy rows remain unqueued for explicit +operator remediation. + +## Server-Selected Current Work + +The reviewer cannot browse or choose from the full backlog. The current-work +operation returns exactly one of: + +- the reviewer's active lease; +- one server-selected next offer within the requested project; or +- none. + +If a reviewer holds an active lease in project A and requests project B, the +project-B response is none. It reveals neither project-A lease facts nor an +unclaimable project-B offer. Complete project queue inspection is a distinct +administrative capability. + +A revised Submission receives a time-bounded preference for the reviewer who +issued the prior `needs_revision` decision. Preference expiry, reviewer decline, +or authority invalidation opens the same queue entry to FIFO routing without +resetting its age. v0.1 permits at most one active ReviewLease per human +reviewer and one active lease per queue entry. + +Claim, release, decline, expiry, and invalidation transitions use PostgreSQL +database time, exact row locks, partial uniqueness, and stable race outcomes. +User claims do not use `SKIP LOCKED`; deterministic background batches may. + +## Review Packet And Artifact Boundary + +LocalStorage is development-only. MinIO proves the S3-compatible protocol in +local/CI. AWS S3 is the v0.1 hosted provider behind the provider-neutral +`S3CompatibleArtifactStore`. Cloudflare R2 and Flow Node remain deferred. + +REV consumes only narrow ART v2 typed product capabilities. It never imports +the raw byte-only `ArtifactStore`, a concrete provider, ART repositories, +`ArtifactScratchManager`, `PreparedArtifact`, `CommittedArtifactSource`, object +keys, provider URIs, scratch paths, receipts, or credentials. + +`ReviewPacketManifest` is an immutable REV semantic projection naming the exact +queue entry, lease, versioned Submission, admitting CheckerRun/results, stamped +guide or revision context, response-evidence relations, and ART binding IDs. It +stores no bytes, content digest, provider location, signed URL, scratch path, +receipt, or authorization-matrix data. + +An active ReviewLease authorizes artifact bytes only for the single Submission +packet named by its manifest. Prior, expired, consumed, sibling, later, +cross-task, and cross-project leases cannot read those bytes. Authorized chain +history may expose bounded binding ID, relation, media type, +verification/availability, and required/optional metadata, but never bytes, +content digest, provider locator, signed capability, receipt, replica detail, +service scope, or credential. + +Chain metadata is available only to the exact submitter represented in the +chain, the current leased reviewer, a prior reviewer who authored a Review and +still holds the exact project reviewer grant, or an explicitly authorized +Project Manager/Operator. Prior participation grants metadata history only; +artifact bytes still require the current active lease for the exact packet. + +## Review And Response Evidence + +Reviewer finding evidence and submitter response evidence use an ART-owned +two-phase candidate/finalize capability: + +```text +preflight authority +-> provider upload and verification outside lifecycle locks +-> AUTH prepares final human authority +-> REV locks exact lease/finding/response lineage +-> ART locks candidate/admission/binding state +-> REV recomposes final facts and AUTH evaluates once +-> ART binding and immutable ReviewEvidenceArtifact relation flush together +-> caller commits once +``` + +Authority loss, lease expiry, assignment loss, or preparation supersession may +leave only an ART-owned unbound candidate governed by ART retention. It creates +no canonical evidence relation or product effect. Decision and resubmission +revalidate evidence lineage again. + +ART owns bytes, candidates, bindings, verification, retention, provider +execution, and recovery. REV owns packet membership, evidence-slot purpose, and +the immutable relation from a finalized ArtifactBinding to the exact Review, +finding, response, or resolution evidence slot. Human bearer tokens and provider +locators never cross into storage calls. + +## Decision Transaction + +No canonical Review may commit without the mandatory WS-CON flush-only +participant. No production or test no-op participant exists. + +Every valid decision follows this order: + +```text +freshly verify the Flow token +-> AUTH PREP review.decision with exact request bindings +-> lock review idempotency +-> lock the review lifecycle fence +-> lock ReviewQueueEntry, ReviewLease, task, TaskAssignment, Submission, + predecessor Review, finding/resolution lineage, and stabilized binding facts +-> recompose canonical final facts +-> AUTH validates all prepared-handle bindings, consumes the handle once, + evaluates exact current authority once, and stages bounded evidence +-> append immutable Review, submitted findings, and resolutions +-> consume ReviewLease +-> close ReviewQueueEntry +-> CON reviewer operation creates completed_review and evaluates the + ReviewLease-frozen contribution rule +-> apply the exact decision branch +-> stage shared audit and outbox rows +-> request route or service command commits once +``` + +The decision transaction performs no ART capability call, provider I/O, or +contribution-evidence projection. It consumes the stabilized server-derived +Submission `artifact_hash` as lineage. + +### Accept + +```text +Review(accept) +-> append FinalAcceptance linked to the Review +-> Task.status = accepted +-> TaskAssignment.status = completed +-> CON submitter operation creates accepted_submission from FinalAcceptance +-> evaluate the TaskAssignment-frozen submitter contribution rule +-> stage audit/outbox +-> commit once +``` + +### Needs Revision + +```text +Review(needs_revision) +-> reviewer completed_review already created +-> Task.status = needs_revision +-> TaskAssignment remains active +-> no FinalAcceptance +-> no submitter ContributionRecord +-> commit once +``` + +### Reject + +```text +Review(reject) +-> reviewer completed_review already created +-> block the same-task TaskAssignment +-> Task.status = rejected with bounded human reason +-> no FinalAcceptance +-> no submitter ContributionRecord +-> commit once +``` + +Reject changes no other task, project grant, or contributor capability. Checker +outcomes, storage failures, revision limits, deadlines, withdrawals, and +administrative closure never synthesize a reject Review. + +Any failure in REV, task, CON, shared audit, or shared outbox staging rolls back +the Review, findings, resolutions, lease/queue transitions, task/assignment +effects, FinalAcceptance, contributions, awards, audit, and outbox together. + +## FinalAcceptance + +`FinalAcceptance` is an internal immutable REV fact created only as the +lifecycle consequence of an already-authorized `Review(accept)` transaction. +It has no public/manual creation API and no separate authorization action. + +Required lineage is: + +```text +id +project_id +task_id +submission_id +source_review_id +accepted_submitter_id +accepted_at +recorded_by +policy_context_ref +``` + +`submission_id` is the existing versioned Submission identity. +`accepted_submitter_id` is the canonical human ActorProfile on the Submission +and TaskAssignment. `recorded_by` is the canonical human ActorProfile on the +Review and ReviewLease. `policy_context_ref` identifies the immutable +ReviewPolicy governing that Submission. + +PostgreSQL enforces unique task, source Review, and Submission acceptance plus +same-chain project/task/submission/reviewer/submitter/policy integrity and +immutability. v0.1 has no reopen or replacement path. + +## Contribution And Compensation Boundary + +`docs/spec_contribution_compensation.md` and ADR 0016 are the canonical CON +contract authority. This section defines REV's orchestration obligations at that +boundary. Merged CON-01 publishes contracts only; it implements no policy +persistence, contribution record, award, participant, or fulfillment runtime. + +Every committed Review creates exactly one reviewer `completed_review` +ContributionRecord sourced directly from the Review and ReviewLease. Only +FinalAcceptance creates a submitter `accepted_submission` ContributionRecord. +CON never infers submitter acceptance from `Review.decision`. + +The CON participant exposes two operation-specific flush-only inputs: + +- reviewer input for every decision, containing Review, ReviewLease, reviewer, + lease-frozen ContributionPolicyVersion, Submission/project/task lineage, + AuthorizationDecision, request/correlation references, and stabilized + `artifact_hash`; it contains no FinalAcceptance or submitter-policy facts; +- submitter input only after accept creates FinalAcceptance and applies accepted + task effects, containing FinalAcceptance, TaskAssignment, submitter, + assignment-frozen ContributionPolicyVersion, and the same locked lineage. + +Database constraints keep the source shapes mutually exclusive and enforce one +`completed_review` per Review and one `accepted_submission` per +FinalAcceptance. Explicitly unpaid rules create no CompensationAward. Payable +money or project-points rules create immutable awards in the canonical +transaction as defined by CON. + +External points/payment delivery occurs after commit through the shared outbox +and adapter boundary. Delivery failure cannot roll back or change Review, +FinalAcceptance, ContributionRecord, CompensationAward, or task acceptance. +Reputation policy and reputation-event implementation are deferred; the review +transaction does not write a reputation side effect. + +## Controlled Revision Context + +ADR 0010 is additive to immutable revised submissions. The task pipeline owns +the single Project Guide context used for both task execution and human review. +TaskAssignment stores only `task_id`; it does not duplicate a guide/context +lock. Each Submission stamps the exact guide ID, version, immutable per-project +activation sequence, source snapshot, and task-execution policy IDs, versions, +and hashes used for that attempt. + +After a human `needs_revision` Review, revision preparation compares only the +prior Submission's stamped guide identity and activation sequence with the +project's currently active Project Guide pair: + +- exact identity and activation-sequence match: `kept`; +- any different internally consistent active pair: `rebased`, recording + `forward` or `backward`, including intentional reactivation of an older guide; +- missing, incomplete, revoked, internally inconsistent, or unsafe active + context: `blocked` for covered Project Manager repair. + +Version strings are never ordered. Activation sequence records chronology but +does not overrule which guide is currently active. + +`RevisionContextPreparation` is immutable and rooted in the exact +`needs_revision` Review and prior Submission. It freezes the complete selected +next-attempt guide/source/task-execution policy context, context digest, outcome, +direction, change summary, source TaskAssignment, currently authorized target +TaskAssignment, preparation sequence, preparing actor/process, and audit link. +It does not contain or rebase a ContributionPolicyVersion. + +Each episode forms one non-branching preparation chain: one root per Review, +one child per preparation, same task/review/source lineage across an edge, and +sequence increasing by exactly one. The head is the row with no successor. +Task Context selects that head and then validates it; it never falls back to an +older preparation when the head is blocked, corrupt, revoked, or stale. + +Task Context returns the frozen preparation, not a moving active-guide pointer. +A later guide activation cannot silently change a context already returned to +the submitter. Submission N+1 acknowledges the head ID and digest and stamps +that context exactly. If it is no longer valid, submission fails with an +explicit re-preparation requirement. + +No guide rebase occurs during review. The reviewer evaluates the exact guide and +task-execution context stamped on the single Submission covered by +the active lease. History shows the prior and new guide versions, direction, +and change summary. + +## Finding Replay And Resubmission + +For every unresolved blocking ReviewFinding, the assigned submitter creates one +immutable `SubmissionFindingResponse` with response text and optional finalized +evidence binding. Responses to advisory findings are optional unless the locked +policy explicitly requires them. + +Submission N+1 links its immediate predecessor, exact preparation head, +responses, evidence relations, and target TaskAssignment. The existing +finalization and checker spine reruns. A new current `allow_review` creates a +queue entry preferred to the reviewer who issued the prior revision request. + +The later Review appends one immutable `FindingResolution` for each required +prior finding with the canonical result `resolved`, `unresolved`, or +`not_applicable` and bounded rationale/evidence. It does not change the finding +or submitter response. + +Normal revision returns to the same assigned contributor. If that contributor +loses authority, the source Submission and TaskAssignment remain immutable. A +covered manager may assign a replacement against the durable revision +obligation and append one preparation successor whose target TaskAssignment is +the replacement. The old contributor cannot submit. + +## Revision Limits, Repair, And Legacy Recovery + +Reaching a revision limit or deadline blocks new revision preparation and +`submission.create` with a stable policy error. It does not automatically reject +or close the task. The task remains `needs_revision` and its assignment remains +active until an authorized explicit command. + +A covered Project Manager may use the planned, reason-bound, idempotent +`review.revision_obligation.close` command only after server-proven limit or +deadline exhaustion. It sets the task to canonical `cancelled`, releases the +assignment at database time, clears active-assignee projection, and closes any +queue entry as administratively cancelled. It creates no Review, +FinalAcceptance, ContributionRecord, award, fulfillment instruction, or +reputation effect. + +Blocked/revoked/invalid Review-rooted preparation is repaired only through the +planned `review.revision_context.repair` command. A covered Project Manager +acknowledges the exact current head ID/digest and reason; the command appends one +validated successor after project setup correction. It cannot edit history, +branch the chain, or create an episode root. + +A legacy task in `needs_revision` with no originating Review/root cannot use +normal repair. Reconciliation records the defect. An Operator may use the +planned evidence-linked `review.revision_context.legacy_close` command to set +the task `cancelled`, release the assignment, and close any queue with terminal +reason `legacy_revision_context_unrecoverable`. It creates no synthetic Review +or CON record. + +## Action Inventory And Activation Custody + +Merged AUTH-08 is historical provenance: 74 PermissionIds and 57 ActionIds, +with 9 active and 48 planned. Trusted main after merged AUTH-09C contains 74 +PermissionIds and 65 ActionIds, with 12 active and 53 planned. AUTH-09A added +the common fixed-service schema and seven ART identities with eleven +memberships. AUTH-09B activates `actor.service.provision` for identities +already in AUTH's closed registry. AUTH-09C activates only +`actor.profile.read` and `actor.identity_link.read`. Neither admits a +service token, activates a review action, or contains any of REV's six future +service identities. + +The review lifecycle currently depends on 24 unavailable actions: + +- registered planned `submission.create`; +- 19 registered planned review actions; and +- four approved but unregistered REV actions defined below. + +The proposed `artifact.review_evidence.binding.create -> +artifact.binding.create` service action is separate and is not one of the 24. +Future counts must be derived from trusted main at each AUTH gate; the four REV +actions and separate ART action are never collapsed into a promised total. + +The exact delivery order is: + +```text +AUTH planned registration and activation custody +-> required ART/CON capability plus REV hidden behavior and canonical facts +-> AUTH evaluator integration and exact action activation +-> REV-13 joint product-surface release +``` + +`WS-AUTH-001-REV-CUSTODY` transfers the 19 registered planned review rows to +seven exact AUTH activation groups without changing mappings, counts, or +availability. `WS-AUTH-001-PREP` supplies the prepared mutation protocol. +`WS-AUTH-001-REV-REG` registers the four additions below as planned. +`WS-AUTH-001-REV-05/06/07/08/09A/11/12` integrate and activate only their exact +merged hidden features. `WS-AUTH-001-REV-LIFECYCLE` activates the four additions +only after the REV-11 and REV-12A hidden manifests are complete. REV-13 alone +exposes the already-active coherent product surface. + +## Four-Action Registration Manifest + +Registration adds no PermissionId, activates nothing, and claims no hidden +behavior already exists. All human actors below are canonical ActorProfile IDs; +all mutations use AUTH PREP, final-fact recomposition, route/service-command +transaction ownership, one commit, exact idempotency, and transaction-time +revalidation. + +### `review.revision_context.repair` + +- Permission: existing `project.task.manage`. +- Candidate: active covered Project Manager grant only. +- Planned surface: `POST /api/v1/tasks/{task_id}/revision-context/repair`. +- Resource facts: exact project, task, current/source assignments, prior + Submission, originating `needs_revision` Review, episode, current head + ID/digest, and current guide/policy facts. +- Guards: covered project, exact Review-rooted episode, exact current blocked or + invalid head, nonterminal task, no crossed lineage, append one validated + successor only, no root/edit/branch. +- Transaction revalidation: authority, project, task, assignments, prior + Submission, Review, episode, head, and current guide/policies under canonical + locks. +- Hidden behavior dependency: `WS-REV-001-11` and the task-owned revision + participant. + +### `review.revision_context.legacy_close` + +- Permission: existing `operations.reconcile.run`. +- Candidate: Operator AdminRoleGrant only. +- Planned surface: + `POST /api/v1/admin/review-reconciliation/{finding_id}/legacy-revision-close`. +- Resource facts: exact unresolved + `legacy_revision_context_unrecoverable` finding, project, task, assignment, + optional queue, and server-proven absence of Review/root. +- Guards: exact unresolved current finding, legacy task still + `needs_revision`, no healthy Review-rooted obligation, exact replay only. +- Effects: task cancelled, assignment released, queue administratively closed; + no synthetic Review, FinalAcceptance, or CON record. +- Hidden behavior dependency: `WS-REV-001-11`. + +### `review.revision_obligation.close` + +- Permission: existing `project.task.manage`. +- Candidate: active covered Project Manager grant only; Operator authority does + not substitute. +- Planned surface: + `POST /api/v1/tasks/{task_id}/revision-obligation/close`. +- Resource facts: exact project, task, assignment, originating + `needs_revision` Review, current preparation head, frozen limit/deadline, and + server proof of the selected reached cause. +- Guards: exact current head/cause, task still `needs_revision`, and terminal + reason exactly `revision_limit_reached` or `revision_deadline_expired`; + missing, not-reached, stale, arbitrary, crossed, or cross-project input denies. +- Hidden behavior dependency: `WS-REV-001-11`. + +### `review.lifecycle.activation.manage` + +- Permission: existing `operations.reconcile.run`. +- Candidate: Operator AdminRoleGrant only; no service actor or background replay. +- Planned surface: authenticated lifecycle-control status and adjacent-phase + transition commands; REV-12A/13 lock the exact URI before exposure. +- Resource facts: operation, singleton ID, expected generation/current phase, + target phase, reviewed manifest digest, server-derived drain observations, + bounded batch/deadline, and reason. +- Guards: one canonical singleton, exact generation/phase/digest, legal adjacent + transition, required drain/cutoff readiness, exact replay or changed-replay + conflict. Lease force release keeps its own action. +- Transaction revalidation: prepared authority, shared/exclusive advisory fence, + row locks, final observations, one caller commit. +- Hidden behavior dependency: `WS-REV-001-12A`. + +## Fixed Service Identity Manifests + +Each identity is a distinct fixed service ActorProfile with its own exact static +ActionId membership. None exists through AUTH-09B. Each requires a separately +reviewed AUTH enum/database-constraint/static-matrix extension, controlled +provisioning through the merged AUTH-09B capability, AUTH-09E admission, +cross-service and human denial proof, and later exact action activation. An +extension or admission activates nothing by itself and no catch-all review +service exists. + +| Fixed service identity | Exact ActionId | PermissionId | Hidden consumer | Activation gate | +|---|---|---|---|---| +| `workstream.review.preference_expiry` | `review.preference_expiry.run` | `operations.timer.run` | REV-06 | `WS-AUTH-001-REV-06` | +| `workstream.review.lease_expiry` | `review.lease_expiry.run` | `operations.timer.run` | REV-06 | `WS-AUTH-001-REV-06` | +| `workstream.review.authority_invalidation_reconciliation` | `review.reconcile.run` | `operations.reconcile.run` | REV-11 | `WS-AUTH-001-REV-11` | +| `workstream.review.reconciliation` | `review.reconcile.run` | `operations.reconcile.run` | REV-11 | `WS-AUTH-001-REV-11` | +| `workstream.review.artifact_reference_reconciliation` | `review.artifact_reference.reconcile` | `operations.reconcile.run` | REV-12 | `WS-AUTH-001-REV-12` | +| `workstream.review.projection` | `review.projection.rebuild` | `operations.projection.rebuild` | REV-12 | `WS-AUTH-001-REV-12` | + +The two reconciliation identities intentionally have separate memberships for +the same ActionId. Execution mode and scope are server-derived, never selected +by the caller. + +## Planned API Surface + +All routes remain unavailable until REV-13. The final coherent `/api/v1` +surface includes separate capabilities for: + +- reviewer current work; +- claim, release, and decline preference; +- exact leased Review Context; +- authorized bounded chain history; +- finding and response evidence intake; +- review decision; +- Task Context revision preparation read; +- revision submission with responses; +- administrative queue inspection, routing correction, force release, + reconciliation, revision repair/closure, and lifecycle control. + +Request JSON never supplies authoritative project relationships, provider +paths, CIDs, URLs, service scopes, candidate roles, or permission unions. +Administrative commands require dedicated actions, exact resources, bounded +reasons, audit, and idempotency. + +## Reconciliation, Projection, And Notifications + +Preference/lease expiry, reviewer-authority invalidation, lifecycle +reconciliation, artifact-reference reconciliation, and projection rebuild are +idempotent fixed-service jobs. Correctness does not depend only on scheduled +delivery; commands reload current PostgreSQL state and lazy request-time +recovery reuses the same transition services where specified. + +The Review transaction appends one canonical shared-outbox projection event in +the same commit. Shared outbox owns claim/retry/dead-letter delivery state. ART +receipts are the only immutable projection delivery receipts. REV creates no +parallel delivery-status table. + +Projection and notifications execute after commit. Failure changes only shared +delivery state and never changes Review, FinalAcceptance, task, contribution, +award, or fulfillment truth. Read models are projections and never become +authority. + +## Joint Release Control + +REV-12A adds one hidden PostgreSQL-canonical +`JointLifecycleReleaseControl`. It uses compare-and-set phase history, +PostgreSQL advisory-lock fences, mandatory typed fence ports, and bounded drain +observations across review mutations, task submissions, queue admission, +authority-loss replacement, CON fulfillment-obligation writers, dispatch, and +callbacks. + +Activation and shutdown are generation-bound and crash resumable. Shutdown +fences new admission, drains admitted commands and leases, captures the +immutable fulfillment-obligation cutoff after prior writers drain, permits only +same-generation pre-cutoff completion work, then disables. Timeout leaves the +phase unchanged for forward retry. No background job replays human Operator +authority or advances a phase. Reactivation requires a newly reviewed manifest. + +This controller is product release state, not AUTH action availability. REV-12A +exposes no public route; AUTH activates the exact management action only after +the hidden manifests merge, and REV-13 exposes and drills it. + +## Error, Concurrency, And Idempotency Rules + +- Canonical resource mismatches and concealed resources use stable bounded + errors without cross-project disclosure. +- Expected uniqueness/claim races map to stable conflict or exact idempotent + replay responses. +- Decision idempotency binds actor, operation, lease, Submission, and canonical + payload; it is separate from AUTH authority idempotency. +- Administrative idempotency is a separate resource/payload aggregate and does + not widen decision idempotency. +- Database time governs lease, preference, revision deadline, and release time. +- Remote provider calls never occur while review decision locks are held. +- Only database-classified serialization/deadlock failures receive bounded + transaction retries. +- Rows of one type lock in ascending primary-key order under the cross-domain + lock order; audit and outbox append after state locks. + +## Implementation And Release Gates + +The lifecycle is delivered one explicitly approved PR-sized chunk at a time: + +```text +01 active contract and immutable registration/service manifests +02-04 policy/task alignment and hidden persistence +05-07 admission, routing, leases, context, and artifact evidence +08-10 decision/revision kernels and atomic FinalAcceptance/CON composition +11-12 recovery, reconciliation, projection, and observability +12A hidden joint release control and cross-domain fences +13 AUTH-active coherent API exposure and live proof +``` + +Each runtime chunk starts only after its exact AUTH, ART, CON, audit, outbox, and +task-owner dependencies are merged on trusted main. Missing typed capabilities +become separately approved owner chunks; REV does not implement them +opportunistically or add compatibility fallbacks. + +The final live proof covers first submit, checker admission, current-work +selection, claim/release/expiry, active-lease packet access, evidence intake, +`needs_revision`, kept/forward/backward/blocked preparation, response/resolution +replay, preferred return and takeover, accept with exactly one FinalAcceptance, +reject, reviewer revocation, manager repair and closure, legacy recovery, +provider outage/integrity failure, transaction rollback, contribution/award +source integrity, outbox retry, projection recovery, shutdown, crash resume, and +coherent reactivation. diff --git a/docs/template_prior_feedback_checklist.md b/docs/template_prior_feedback_checklist.md index b66c64497..5dd1a273a 100644 --- a/docs/template_prior_feedback_checklist.md +++ b/docs/template_prior_feedback_checklist.md @@ -1,31 +1,25 @@ # Prior Feedback Checklist Template -## Task +> Planned immutable response/resolution contract; not a mutable closure list. -## Prior Review +## Review Episode -## Feedback Items +- task ID: +- prior Submission ID: +- originating Review ID: +- preparation head ID/digest: -### Item 1 +## Required Responses -```text -original_feedback: -severity: -contributor_claim_status: fixed | disputed | not_applicable -fix_note: -evidence: -reviewer_closure_status: closed_fixed | closed_rebutted | partially_closed | still_open | obsolete -``` +| ReviewFinding ID | Kind | Required Change | SubmissionFindingResponse | Evidence Binding | +|---|---|---|---|---| +| `` | `blocking` or `advisory` | `` | `` | `` | -## Rebuttals +Every unresolved blocking finding requires exactly one response. Advisory +responses are optional unless locked policy says otherwise. -Use this section only when the original feedback is believed to be incorrect. +## Later Review Resolutions -```text -feedback_item: -rebuttal: -evidence: -requested_decision: close | waive -``` - -## Remaining Open Items +| ReviewFinding ID | FindingResolution | Rationale | Evidence Binding | +|---|---|---|---| +| `` | `resolved`, `unresolved`, or `not_applicable` | `` | `` | diff --git a/docs/template_project_guide.md b/docs/template_project_guide.md index dc52d2542..6ff1aed9d 100644 --- a/docs/template_project_guide.md +++ b/docs/template_project_guide.md @@ -148,11 +148,11 @@ Allowed decisions: Needs revision requires: -- concrete findings -- required fix per finding -- severity per finding +- at least one unresolved blocking finding +- concrete issue and required fix per blocking finding +- optional advisory findings that do not block acceptance -Post-decision non-mutating reviewer-quality audit sampling: +Offline post-decision reviewer-quality sampling only: - accepted sample rate: - rejected sample rate: @@ -160,9 +160,9 @@ Post-decision non-mutating reviewer-quality audit sampling: - high-value criterion defined by `ReviewPolicy`: - reviewer conflict of interest: -These criteria select quality audits only. They do not delay Review, +These criteria select non-product quality analysis only. They do not delay Review, FinalAcceptance, contribution creation, or task closure and do not create a -second decision or adjudication path. +second decision, reputation mutation, or adjudication path. - registered recovery operation used (permission, actor, reason, evidence): ## Revision Policy @@ -172,10 +172,18 @@ Define: - maximum revision rounds: - revision deadline hours: - allowed resubmission states: -- auto-reject after revision limit: -- missed deadline behavior: +- `RevisionPolicyInput.auto_reject_after_limit`: `false` (required explicitly + on project create/update; the backend schema default is not the v0.1 REV + contract) +- limit/deadline exhaustion behavior: block preparation and submission pending + reason-bound covered-manager closure; never synthesize reject - reviewer reassignment rule: +Revision-policy activation and task screening must reject an effective policy +whose `auto_reject_after_limit` value is not `false`. That runtime enforcement +belongs to `WS-REV-001-02`; until it activates, this template is a required +configuration precondition and does not claim the guard is available. + ## Acceptance Policy Accepted work must: @@ -184,7 +192,8 @@ Accepted work must: - satisfy acceptance criteria - pass blocking checks - include evidence -- close prior revision findings +- preserve one immutable response and later resolution for each required prior + blocking finding ## Rejection Policy diff --git a/docs/template_review_packet.md b/docs/template_review_packet.md index f0278ddf7..bde0037f8 100644 --- a/docs/template_review_packet.md +++ b/docs/template_review_packet.md @@ -1,105 +1,94 @@ # Review Packet Template -## Task +> Planned contract; no review route is exposed before REV-13. -`` +## Routing And Lease -## Submission - -`` - -## Reviewer - -`` - -## Routing And Independence - -- assigned reason: +- project ID: +- ReviewQueueEntry ID: +- ReviewLease ID: +- canonical reviewer ActorProfile ID: +- preferred/open routing reason: +- lease issued/expires at: - conflict-of-interest attestation: - contributor-reviewer pair risk: -- non-mutating quality audit selected: -- quality audit selection reason: - -Quality-audit selection cannot delay or replace the Review decision, -FinalAcceptance, task effects, or contribution transaction. +- offline non-mutating quality sampling selected: +- quality sampling reason: -## Decision +Quality sampling cannot delay or replace the Review decision, FinalAcceptance, +task effects, or contribution transaction. -`accept | needs_revision | reject` +## Exact Submission Packet -## Summary +- task ID: +- TaskAssignment ID: +- Submission ID/version: +- predecessor Submission ID: +- admitting CheckerRun ID: +- ReviewPacketManifest ID: +- server-derived Submission artifact hash: +- ART binding IDs: -Short decision summary. +Artifact bytes are available only for this exact active-lease packet. History is +bounded metadata only. -## Evidence Cited For Acceptance +## Stamped Context -Required when decision is `accept`. +- Project Guide ID/version/activation sequence: +- source snapshot reference: +- task-execution policy references: +- ReviewPolicy reference: +- RevisionPolicy reference: +- revision preparation ID/head/digest, when applicable: +- context outcome/direction/change summary, when applicable: -| Evidence ID | Artifact Hash | Claim Supported | -| --- | --- | --- | -| `` | `` | `` | +Use this stamped context. No guide rebase occurs during review. -## Findings - -| Severity | Area | Issue | Required Fix | Evidence | -| --- | --- | --- | --- | --- | -| high | `` | `` | `` | `` | - -## Checker Result Assessment - -State whether checker output supports the decision. - -## Prior Revision Closure - -For resubmissions, list whether prior findings are closed. +## Decision -## Revision Context +`accept | needs_revision | reject` -Required when reviewing a resubmission. +- immutable Review ID: +- predecessor Review ID: +- bounded summary: +- reject reason, required for reject: +- acceptance evidence, required for accept: -| Field | Value | -| --- | --- | -| context rebased | yes or no | -| prior guide version | `` | -| next guide version | `` | -| prior policy versions | `` | -| next policy versions | `` | -| change summary shown to contributor | `` | -| revision context audit event | `` | +## Immutable Findings -## Compensation Award Eligibility +| ReviewFinding ID | Kind | Area | Issue/Rationale | Required Change | Evidence Binding ID | +|---|---|---|---|---|---| +| `` | `blocking` or `advisory` | `` | `` | `` | `` | -State both determinations independently: +`needs_revision` requires at least one blocking finding. Reject requires its +bounded reason; findings are optional when they add useful evidence. -- reviewer `completed_review`: evaluate the ReviewLease-frozen - `ContributionPolicyVersion` for every valid recorded decision; an explicit - unpaid rule creates no award; -- submitter `accepted_submission`: evaluate the TaskAssignment-frozen - `ContributionPolicyVersion` only for `accept`; `needs_revision` and `reject` - create no submitter contribution or award. +## Prior Responses And Resolutions -## Contribution Records +| Prior Finding ID | SubmissionFindingResponse ID | Response Evidence | FindingResolution | Rationale | +|---|---|---|---|---| +| `` | `` | `` | `resolved`, `unresolved`, or `not_applicable` | `` | -Reviewer record, required for every valid recorded human Review: +## Contribution Effects -- contribution record id: -- contribution type: `completed_review` -- review id: -- review lease id: -- reviewer actor id: -- submission id and version: -- artifact hash: +Reviewer operation, required for every valid Review: -Submitter record, additionally required only when decision is `accept`: +- ContributionRecord ID/type `completed_review`: +- source Review ID and ReviewLease ID: +- reviewer-frozen ContributionPolicyVersion: +- CompensationAward ID or explicit unpaid result: -- contribution record id: -- contribution type: `accepted_submission` -- accepted submission id and version: -- accepting review id: -- submitter actor id: -- task assignment id: -- artifact hash: +Accept-only effects: -## Reviewer Confidence +- FinalAcceptance ID: +- source Review ID and Submission ID: +- accepted submitter ActorProfile ID: +- recording reviewer ActorProfile ID: +- TaskAssignment completed: +- ContributionRecord ID/type `accepted_submission`: +- source FinalAcceptance ID and TaskAssignment ID: +- submitter-frozen ContributionPolicyVersion: +- CompensationAward ID or explicit unpaid result: -`low | medium | high` +`needs_revision` and `reject` contain no FinalAcceptance or submitter +ContributionRecord. diff --git a/docs/template_revision_replay.md b/docs/template_revision_replay.md index 2557a1a2d..af916d086 100644 --- a/docs/template_revision_replay.md +++ b/docs/template_revision_replay.md @@ -1,58 +1,56 @@ # Revision Replay Template -## Task +> Planned contract; unavailable until REV/AUTH release gates complete. -## Prior Review +## Episode -## New Submission +- task ID: +- originating `needs_revision` Review ID: +- prior Submission ID/version: +- source TaskAssignment ID: +- target TaskAssignment ID: -## Revision Summary - -## Revision Context - -Contributor-visible fields: +## Revision Context Preparation | Field | Value | -| --- | --- | -| prior submission id | `` | -| prior submission version | `` | -| context rebased | yes or no | -| prior guide version | `` | -| next guide version | `` | -| prior submission artifact policy version | `` | -| next submission artifact policy version | `` | -| prior pre-submit checker bundle hash | `` | -| next pre-submit checker bundle hash | `` | -| prior post-submit checker policy version | `` | -| next post-submit checker policy version | `` | -| prior review policy version | `` | -| next review policy version | `` | -| prior revision policy version | `` | -| next revision policy version | `` | -| rebase reason | `` | -| change summary shown to contributor | `` | - -Compensation is not rebased here. Submitter compensation remains the immutable -TaskAssignment freeze; each later ReviewLease independently freezes its current -reviewer ContributionPolicyVersion. - -Reviewer and authorized recovery evidence fields: - -| Field | Value | -| --- | --- | -| audit event id | `` | - -## Finding Closure - -Every high and medium prior finding must have one row. A resubmission cannot move to review if any required finding is unmapped. - -| Prior Finding ID | Prior Severity | Area | Required Fix | Contributor Fix Summary | Evidence Ref | Contributor Claim Status | Reviewer Closure Status | -| --- | --- | --- | --- | --- | --- | --- | --- | -| `` | high / medium / low | `` | `` | `` | `` | fixed / disputed / not_applicable | closed_fixed / closed_rebutted / partially_closed / still_open / obsolete | - -## Checker Results After Revision - -| checker | status | severity | message | -| --- | --- | --- | --- | - -## Remaining Issues +|---|---| +| preparation ID | `` | +| preparation sequence | `` | +| predecessor preparation ID | `` | +| current head ID | `` | +| context digest | `` | +| outcome | `kept`, `rebased`, or `blocked` | +| direction | `forward`, `backward`, or `null` | +| prior guide ID/version/activation sequence | `` | +| next guide ID/version/activation sequence | `` | +| frozen source snapshot and task-execution policies | `` | +| change summary | `` | +| audit event ID | `` | + +The reviewer consumes the context stamped on the revised Submission and does +not perform a separate rebase. ContributionPolicyVersion is not part of this +preparation. + +## Immutable Finding Responses + +Every unresolved blocking finding requires one SubmissionFindingResponse. + +| ReviewFinding ID | Kind | Required Change | Response Text | Finalized Evidence Binding ID | +|---|---|---|---|---| +| `` | `blocking` or `advisory` | `` | `` | `` | + +## Later Immutable Resolutions + +Completed by the later Review without editing the finding or response. + +| ReviewFinding ID | Revised Submission ID | Result | Rationale | Evidence Binding ID | +|---|---|---|---|---| +| `` | `` | `resolved`, `unresolved`, or `not_applicable` | `` | `` | + +## Checker Readmission + +- revised Submission ID/version: +- acknowledged preparation head/digest: +- current CheckerRun ID: +- routing outcome: +- preferred prior reviewer ID: diff --git a/docs/template_task_status.md b/docs/template_task_status.md index 7a70bb7f1..e153dd199 100644 --- a/docs/template_task_status.md +++ b/docs/template_task_status.md @@ -1,73 +1,59 @@ # Task Status Template -## Task - -`` - -## Project - -`` - -## Current State - -`DRAFT | SCREENING | READY | CLAIMED | IN_PROGRESS | SUBMITTED | EVALUATION_PENDING | REVIEW_PENDING | NEEDS_REVISION | ACCEPTED | REJECTED | CANCELLED` +> Planned review/revision fields remain unavailable until their release gates. -## Locked Guide Version - -`` - -## Source - -- source type: `manual | markdown_import | csv_import` -- source reference: -- source payload hash: -- import batch id: - -## Owner +## Task -- task creator: -- contributor: -- reviewer: -- queue owner: +- task ID: +- project ID: +- current state: `DRAFT | SCREENING | READY | CLAIMED | IN_PROGRESS | SUBMITTED | EVALUATION_PENDING | REVIEW_PENDING | NEEDS_REVISION | ACCEPTED | REJECTED | CANCELLED` +- bounded terminal reason, when applicable: +- current TaskAssignment ID/status: +- canonical submitter ActorProfile ID: -## Latest Decision +## Guide And Submission Context -- decision: -- actor: -- timestamp: -- reason: -- linked evidence: +- task guide lock: +- latest Submission ID/version: +- Submission guide ID/version/activation sequence: +- server-derived artifact hash: +- current CheckerRun ID/outcome: -## Screening Rejection +## Review State -Use only when a draft/imported task fails before `READY`. +- ReviewQueueEntry ID/state: +- active ReviewLease ID: +- canonical reviewer ActorProfile ID: +- latest immutable Review ID/decision/reason: +- current revision preparation head ID/digest/outcome/direction: +- unresolved blocking ReviewFinding IDs: +- latest FindingResolution IDs: -- gate: `project_activation | task_screening | submission_quality` -- reason code: -- fix required: -- source task id: -- retry id: -- notification status: +## Accept State -External-origin webhook drop delivery is a future adapter concern. In v0.1 this section records internal screening/import rejection. +- FinalAcceptance ID, only on accept: +- source Review ID and Submission ID: +- accepted submitter ActorProfile ID: +- reviewer `completed_review` ContributionRecord ID: +- submitter `accepted_submission` ContributionRecord ID, sourced from + FinalAcceptance only: -## Contribution Records +## Reject Or Administrative Cancellation -- reviewer contribution record id: -- reviewer contribution type: `completed_review` -- review id and review lease id: -- submitter contribution record id, only on `accept`: -- submitter contribution type, only on `accept`: `accepted_submission` -- compensation award ids, when the frozen `ContributionRule` rows are payable: +- reject: source human Review ID, bounded reason, blocked TaskAssignment ID; +- revision obligation cancellation: `revision_limit_reached` or + `revision_deadline_expired`, released assignment, no synthetic Review; +- legacy revision cancellation: `legacy_revision_context_unrecoverable`, + evidence-linked reconciliation finding, no synthetic Review. -## Open Items +## Compensation -| Item | Owner | Severity | Due | Status | -| --- | --- | --- | --- | --- | -| `` | `` | `high` | `` | `open` | +- reviewer award ID or explicit unpaid result: +- submitter award ID or explicit unpaid result, accept only: +- fulfillment status remains separate from task/assignment state: ## History -| Time | State | Actor | Reason | -| --- | --- | --- | --- | -| `