From 37b2c8b4a7ffb30f1622f6876a112177cca34c69 Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Tue, 4 Aug 2026 16:51:55 +0100 Subject: [PATCH] docs(contribution): reconcile revision policy rebase --- .../CHUNK_MAP.md | 5 +- .../CONFORMANCE_MATRIX.md | 2 +- .../DECISIONS.md | 19 ++ .../INTENT.md | 4 + .../PLAN.md | 6 +- .../RISKS.md | 1 + .../SOURCE_MANIFEST.md | 9 +- .../STATUS.md | 35 ++-- ...-economic-terms-cutover-and-task-freeze.md | 18 +- ...review-lease-contribution-policy-freeze.md | 3 +- ...c-review-contribution-award-participant.md | 14 +- ...01-PLAN5-revision-rebase-reconciliation.md | 171 ++++++++++++++++++ .../CHUNK_MAP.md | 2 +- .../CONFORMANCE_MATRIX.md | 2 +- .../DECISIONS.md | 24 +-- .../PLAN.md | 7 + .../RISKS.md | 2 +- .../STATUS.md | 7 + ...V-001-09A-revision-context-resubmission.md | 8 +- ...ribution-integration-hidden-composition.md | 8 +- README.md | 12 +- docs/architecture_data_model.md | 62 ++++--- docs/architecture_lifecycle_state_machine.md | 23 ++- docs/architecture_lockdown.md | 24 ++- docs/architecture_system_architecture.md | 3 +- ...ion_0003_project_guides_are_first_class.md | 23 ++- docs/decision_0010_revision_context_rebase.md | 80 ++++++-- ...0016_contribution_compensation_boundary.md | 8 +- docs/glossary.md | 10 +- docs/operations_payment_reputation.md | 5 + docs/operations_project_operating_manual.md | 14 +- docs/operations_queue_policy.md | 12 +- docs/operations_reviewer_workflow.md | 11 +- docs/operations_revision_replay.md | 38 ++-- docs/principles.md | 8 +- docs/product_first_user_flows.md | 7 +- docs/product_principles.md | 10 +- docs/risk_register.md | 5 +- docs/roadmap_implementation_backlog.md | 7 +- docs/spec_contribution_compensation.md | 25 ++- docs/spec_review_lifecycle.md | 42 +++-- docs/template_project_guide.md | 6 +- docs/template_review_packet.md | 2 + docs/template_revision_replay.md | 11 +- docs/template_submission_packet.md | 8 +- docs/template_task.md | 7 +- 46 files changed, 611 insertions(+), 199 deletions(-) create mode 100644 .agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-PLAN5-revision-rebase-reconciliation.md diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/CHUNK_MAP.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/CHUNK_MAP.md index 338798796..8e068abc1 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/CHUNK_MAP.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/CHUNK_MAP.md @@ -11,23 +11,24 @@ signed-loop records do not make behavior live. | `PLAN`-`PLAN3` | Original boundary and cross-initiative planning | Historical planning | | `01` | Canonical specification and ADR 0016 | Merged PR #144 | | `02A` | Shared transactional outbox persistence/append | Merged PR #155; migration 0029 | +| `03A` | Adapter-binding persistence | Merged PR #267; migration 0053 | ## Current reconciliation | Chunk | Goal | Risk | Status | |---|---|---:|---| | `PLAN4` | Reconcile current main, ART/AUTH/REV changes, open PRs, and end-to-end order | L1 | Merged PR #261 | +| `PLAN5` | Reconcile complete-context human needs-revision rebase across guide, policy, REV, and CON contracts | L1 | Active specification chunk; no runtime | ## Core runtime chunks | Chunk | Goal | Entry gate | Status | |---|---|---|---| -| `03A` | Adapter-binding persistence | PLAN4 accepted; refreshed after ART PR #264 | Active schema-only chunk; migration 0053 | | `03B` | Contribution-policy persistence | 03A | Proposed; unblocks REV-03A2 FK | | `02C` | Shared lifecycle-audit participant | PLAN4; current AuditEvent contract | Proposed; independent of dispatcher; required before REV-04B | | `04A` | Hidden adapter-binding service | 03A + exact AUTH registration/PREP contract | Blocked on AUTH registration | | `04B` | Hidden contribution-policy service | 03B + 04A + exact AUTH registration/PREP contract | Blocked on AUTH registration | -| `05A` | Legacy semantic cutover + TaskAssignment policy freeze | 04B + task/assignment authority contract + row-classification decision | Proposed | +| `05A` | Legacy semantic cutover + initial TaskAssignment policy freeze and guarded human-revision rebase support | 04B + task/assignment/revision authority contract + row-classification decision | Proposed | | `05B` | Legacy economic schema removal | 05A zero-consumer proof | Proposed | | `06` | Reviewer policy lookup/freeze participant | 05B + REV lease contract/caller facts | Proposed; CON never owns lease | | `03C` | ContributionRecord/CompensationAward persistence | 03B + merged REV Review/ReviewLease/FinalAcceptance targets | Proposed after REV-04B | diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/CONFORMANCE_MATRIX.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/CONFORMANCE_MATRIX.md index 6857d50ac..aeea95d9d 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/CONFORMANCE_MATRIX.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/CONFORMANCE_MATRIX.md @@ -8,7 +8,7 @@ | Authorization | AUTH + each feature | current AUTH actor/grant/fixed-service/PREP and REV-readiness foundations, with current repository migrations through ART-owned `0050`; provisioning grants no service execution; CON mappings, identities, and static rows are absent on current main; every future artifact requires exact AUTH-owned registration and activation evidence, exact grant/static row, fixed-service admission, prepared handle bound to session/action/actor-ref/idempotency/request digest with substitution non-consumption, planned denial, and no local role logic | AUTH activation + CON-11 | | Final acceptance | REV + 03C,07 | accept creates one immutable FinalAcceptance per task/Review/Submission; needs_revision/reject create none; no create API/action, reopen, replacement, or adjudication path | joint live drill | | Contribution cardinality | 03C,07 + REV | one completed_review per valid Review with direct Review/lease lineage; one accepted_submission per FinalAcceptance with assignment lineage; mutually exclusive sources; revision Reviews distinct; automated outcomes create none | joint live drill | -| Policy freeze | 05A,06 + task/REV | exact submitter/reviewer fields; published version; no drift; publish/suspend races both orders | joint live drill | +| Policy freeze and human revision rebase | 05A,06,07 + task/REV | exact submitter/reviewer fields; published version; no publication-time drift; accept/reject use current-attempt freezes; human needs_revision keeps/rebases/blocks the complete context atomically, updates only the next-attempt submitter selector, preserves the completed lease/history, and each next lease freezes then-current reviewer terms; publish/suspend/rebase races both orders | joint live drill | | Award evaluation | 03C,07 | matching frozen ContributionRule; unpaid creates none; at most one money/points; exact NUMERIC(38,18) definition copy; ISO 4217/project-scoped unit equality; no float, conversion, or rounding; replay stable | joint live drill | | Atomic REV/CON | 07 + REV | reviewer operation before branch; accept-only submitter operation after FinalAcceptance/accepted effects; stabilized digest; REV stages audit/outbox; CON flushes contributions/awards; zero ART calls; complete rollback | REV-10 + joint live drill | | Outbox isolation | 02A,02B | stable event/task IDs; claim fencing; retry/dead-letter/replay; dispatcher cannot inherit feature authority; handler returns typed outcome | CON-11 | diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/DECISIONS.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/DECISIONS.md index ee9e19b29..01313fefe 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/DECISIONS.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/DECISIONS.md @@ -72,3 +72,22 @@ fulfillment. Runtime reputation scoring remains deferred. PLAN4 changes planning records only. The recommended next implementation is 03A, and it begins only after human approval from then-current main. + +## D13 — Human revision rebases complete current context + +Publication or activation never silently changes an active assignment, +Submission, or ReviewLease. Accept and reject finish under the versions frozen +for that attempt. After a human `needs_revision`, revision preparation compares +the complete applicable current Project Guide/source activation, +submission-artifact policy, pre-submit and post-submit checker policies, review +policy, revision policy, task-template/task-execution context, and +ContributionPolicyVersion. It atomically keeps unchanged components or rebases +all changed components for the next attempt. +The completed reviewer contribution retains its lease-frozen policy; the +revised submitter attempt uses the rebased assignment policy; and the next +ReviewLease independently freezes the then-current reviewer policy. Prior +Submissions, Reviews, ContributionRecords, and CompensationAwards remain +immutable. Incomplete or inconsistent current context blocks rather than +publishing a mixed version set. The Review, reviewer contribution/award, task +and assignment effects, initial preparation or blocked outcome, audit/outbox, +and contributor-visible state commit once or roll back together. diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/INTENT.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/INTENT.md index b288264f6..0ded59323 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/INTENT.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/INTENT.md @@ -31,6 +31,10 @@ operational claims with a capability-ordered plan, now refreshed through ## Success state - ContributionPolicyVersion is the only award-policy authority. +- Publication never silently changes an active attempt. Human + `needs_revision` is the only in-progress boundary that atomically rebases + every changed applicable next-attempt context component, including the + submitter ContributionPolicyVersion; completed history remains immutable. - TaskAssignment freezes the submitter policy version before work. - REV-owned ReviewLease freezes the reviewer policy version before review. - ContributionRecord and CompensationAward rows are immutable and replay-safe. diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/PLAN.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/PLAN.md index 33a663718..7c348f524 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/PLAN.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/PLAN.md @@ -41,8 +41,10 @@ CON-03B, while later REV-04B waits for CON-02C. exact binding actions/contexts and keeps them unavailable until hidden proof. 6. `04B` adds hidden contribution-policy behavior under the same registration-before-behavior-before-activation sequence. -7. `05A` removes semantic use of retired guide-bound economic terms and freezes - the submitter ContributionPolicyVersion on TaskAssignment. +7. `05A` removes semantic use of retired guide-bound economic terms, initially + freezes the submitter ContributionPolicyVersion on TaskAssignment, and + supplies the guarded update boundary later consumed by human revision + preparation for complete next-attempt rebase. 8. `05B` removes the now-unreachable legacy economic schema after an approved deterministic row classification and zero-consumer proof. diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/RISKS.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/RISKS.md index 3b0712e3d..ec66b10ff 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/RISKS.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/RISKS.md @@ -7,6 +7,7 @@ | CON invents AUTH identifiers or authority | Privilege escalation and dual authorization paths | AUTH exclusively registers contexts, actions, identities, matrices, evaluators, PREP, and activation. | | REV/CON ownership blurs at policy freeze | CON could own ReviewLease or REV could own contribution policy | CON returns a policy-version lookup result; REV alone writes and transitions its lease. | | ART/provider work enters review transaction | Availability coupling and broken atomicity | REV supplies stable artifact identity/hash; CON performs zero provider or ART calls. | +| Human revision mixes new guide/policies with stale contribution terms or rewrites completed awards | Incoherent contributor obligations and corrupted economic history | One task-owned complete-context preparation keeps/rebases/blocks atomically; only the next-attempt TaskAssignment selector changes; completed lease/contribution/award history remains immutable. | | Planning evidence is treated as runtime | Wrong migration or dependency assumptions | Treat ART #249 as merged ART runtime and REV #258 as merged planning evidence only; refresh main before every implementation. | | Migration collision with ART/REV | Broken linear history | Allocate only from the then-current Alembic head; no number is reserved in planning. | | Legacy economic rows are guessed | Corrupted award policy lineage | Require explicit deterministic classification or fail closed before 05A/05B. | diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/SOURCE_MANIFEST.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/SOURCE_MANIFEST.md index 79ad41379..31e8446a7 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/SOURCE_MANIFEST.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/SOURCE_MANIFEST.md @@ -2,8 +2,8 @@ ## Reconciliation baseline -- Current `main`: `b47a7e64f7d75cda8a0681d1aff3bf0c4a5be4aa`. -- Current migration head: `0052_legacy_intake_removal`. +- Current `main`: `cda59fc32e3a60e1e2c337cae7ebeaa94b95e12b`. +- Current migration head: `0053_compensation_bindings`. - Current capability ledger: `docs/roadmap_status.md`. - Current contribution process: `AGENTS.md`, `CONTRIBUTING.md`, and `.agent-loop/README.md`. Historical signed-start and merge-intent records are @@ -21,6 +21,7 @@ - `docs/spec_authorization_service.md` - `docs/spec_artifact_storage_service.md` - `docs/decision_0009_review_decisions_are_canonical.md` +- `docs/decision_0010_revision_context_rebase.md` - `docs/decision_0012_workstream_authorization_service.md` - `docs/decision_0013_immutable_artifact_storage_boundary.md` - `docs/decision_0014_external_service_adapter_convention.md` @@ -36,8 +37,8 @@ persistence/append only; no dispatcher exists. - `backend/app/modules/audit/**`: existing shared audit foundation; no typed lifecycle participant yet. -- `backend/app/modules/compensation/**` and migration `0053` add only the - in-review adapter-binding schema; no creation/lifecycle service exists. +- `backend/app/modules/compensation/**` and merged migration `0053` add only the + adapter-binding schema; no creation/lifecycle service exists. - Review queue persistence now exists; ReviewLease, Review, and FinalAcceptance lifecycle implementation remain absent. diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/STATUS.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/STATUS.md index a463ddc9d..a5d94ecdc 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/STATUS.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/STATUS.md @@ -2,13 +2,13 @@ ## Current baseline -- Reconciled main: `b47a7e64f7d75cda8a0681d1aff3bf0c4a5be4aa`. -- Alembic head on main: `0052_legacy_intake_removal`. -- CON-01 and CON-02A are merged. -- CON-03A adapter-binding persistence is the active implementation chunk and - allocates linear migration `0053_compensation_bindings`. -- Runtime contains shared outbox persistence and the in-review compensation - binding schema only; contribution, +- Reconciled main: `cda59fc32e3a60e1e2c337cae7ebeaa94b95e12b`. +- Alembic head on main: `0053_compensation_bindings`. +- CON-01, CON-02A, and CON-03A are merged; 03A merged in PR #267. +- PLAN5 is the active documentation/specification reconciliation for the + human-confirmed complete-context `needs_revision` rebase rule. +- Runtime contains shared outbox persistence and the schema-only compensation + binding foundation; contribution, dispatcher, fulfillment, operations, and CON API behavior remain absent. - The pre-existing local deletion of the archival reference PDF is user-owned and excluded from this planning change. @@ -46,13 +46,14 @@ schema work. Current dependency analysis yields: 1. PLAN4 planning reconciliation. 2. CON-03A adapter-binding persistence. -3. CON-03B contribution-policy persistence, unblocking REV-03A2. -4. CON-02C lifecycle-audit participant before REV-04B. -5. Hidden policy/binding behavior and legacy clean cut as AUTH contracts become +3. PLAN5 complete-context human revision-rebase reconciliation. +4. CON-03B contribution-policy persistence, unblocking REV-03A2. +5. CON-02C lifecycle-audit participant before REV-04B. +6. Hidden policy/binding behavior and legacy clean cut as AUTH contracts become available. -6. Contribution/award persistence after REV provides stable FK targets. -7. Atomic REV/CON participant after both sides' lineage exists. -8. Dispatcher and fulfillment later, after exact AUTH service registration. +7. Contribution/award persistence after REV provides stable FK targets. +8. Atomic REV/CON participant after both sides' lineage exists. +9. Dispatcher and fulfillment later, after exact AUTH service registration. ## Current blockers @@ -69,7 +70,7 @@ schema work. Current dependency analysis yields: ## Immediate next action -Finish CON-03A schema evidence and review, publish it without the user-owned PDF -deletion, and stop at its PR checkpoint. Binding creation remains deferred to -04A after AUTH approves the exact adapter identity/capability contract; do not -start 03B or another CON chunk automatically. +Finish PLAN5 canonical reconciliation and stop at its PR checkpoint. It changes +no runtime. After human merge approval, 03B remains the next proposed runtime +chunk; binding creation remains deferred to 04A after AUTH approves the exact +adapter identity/capability contract. diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-05A-legacy-economic-terms-cutover-and-task-freeze.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-05A-legacy-economic-terms-cutover-and-task-freeze.md index c5c836ca0..7bd9723ab 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-05A-legacy-economic-terms-cutover-and-task-freeze.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-05A-legacy-economic-terms-cutover-and-task-freeze.md @@ -4,8 +4,10 @@ Remove the retired guide-bound economic contract from every semantic consumer, classify existing rows, and freeze the active published -ContributionPolicyVersion on each successful new TaskAssignment. Physical dead- -schema removal belongs to 05B. +ContributionPolicyVersion on each successful new TaskAssignment. Supply the +same guarded current-version selection contract for later task-owned human +revision preparation; publication itself never mutates an assignment. Physical +dead-schema removal belongs to 05B. ## Risk @@ -40,8 +42,10 @@ provider/artifact calls; unrelated checker behavior ## Acceptance criteria -- [ ] Every new TaskAssignment has immutable non-null - `submitter_contribution_policy_version_id`. +- [ ] Every new TaskAssignment has non-null + `submitter_contribution_policy_version_id`, initially frozen at claim and + mutable only by the explicit audited task-owned human revision preparation + path. Direct or publication-driven updates are rejected. - [ ] Exact merged Submission.task_assignment_id lineage is preserved; no parallel submission identity is added. - [ ] No runtime/API/setup/task/checker/review consumer treats retired guide- @@ -63,7 +67,11 @@ provider/artifact calls; unrelated checker behavior manifest proves the freeze, canonical guards, rollback, and real-kernel unavailable behavior before activation. - [ ] Missing/invalid policy fails with no assignment/task/audit/outbox partial - state. Later publication never updates an assignment. + state. Later publication never updates an assignment. A later human + needs-revision preparation locks and validates the complete current context, + keeps an unchanged version or updates a changed valid version for the next + attempt, and records prior/next lineage atomically through the task-owned + lifecycle. - [ ] Publish versus claim and binding-state versus claim pass both lock orders without deadlock or mixed versions. - [ ] Existing rows follow the approved deterministic classification and cannot diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-06-review-lease-contribution-policy-freeze.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-06-review-lease-contribution-policy-freeze.md index 44fe78a87..7949d3cf7 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-06-review-lease-contribution-policy-freeze.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-06-review-lease-contribution-policy-freeze.md @@ -4,7 +4,8 @@ Deliver the narrow CON policy lookup/freeze participant that REV invokes inside the review-claim transaction. Reviewer award eligibility is frozen before -review work begins. +review work begins. Each new lease selects the version then current; publication +and prior task revision preparation never rewrite an existing lease. ## Risk diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-07-atomic-review-contribution-award-participant.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-07-atomic-review-contribution-award-participant.md index 750f544d5..574e05f46 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-07-atomic-review-contribution-award-participant.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-07-atomic-review-contribution-award-participant.md @@ -48,7 +48,8 @@ TaskAssignment contribution-source lineage, submitter, or submitter policy. The submitter operation exists only after REV creates FinalAcceptance and applies accepted task/assignment effects. It receives exact locked FinalAcceptance, TaskAssignment, versioned Submission, project/task, submitter -ActorProfile, assignment-frozen submitter ContributionPolicyVersion, the same +ActorProfile, submitter ContributionPolicyVersion selected on the assignment +for that exact prepared attempt, the same authorization/request/correlation lineage, and stabilized artifact hash. It never uses direct Review/ReviewLease contribution-source fields. @@ -69,8 +70,9 @@ never uses direct Review/ReviewLease contribution-source fields. - [ ] Repeated idempotent decision returns the same rows; a later revision Review creates a distinct reviewer contribution; automated outcomes create none. -- [ ] Reviewer uses lease-frozen policy; submitter uses assignment-frozen - policy. Matching explicit unpaid rule creates no award; compensated rule +- [ ] Reviewer uses lease-frozen policy; submitter uses the assignment policy + selected for the exact attempt, including any prior human-revision rebase. + Matching explicit unpaid rule creates no award; compensated rule creates at most one money and one project-points award copied from immutable definitions. - [ ] CON copies the supplied stabilized digest exactly into @@ -93,6 +95,12 @@ never uses direct Review/ReviewLease contribution-source fields. audit/outbox step rolls back Review/FinalAcceptance/task/assignment/ contribution/award/audit/outbox together. The reviewer operation never commits independently and no post-commit repair path exists. +- [ ] Needs revision composes the task-owned complete-context preparation after + the reviewer operation in the same caller transaction. The reviewer + contribution keeps its lease freeze; preparation may update only the next- + attempt assignment selector. Review, reviewer award, task/assignment effects, + preparation or blocked result, audit/outbox, and visibility roll back + together. CON-07 does not own the rebase. - [ ] No FinalAcceptance create action/API exists. Static/runtime proof finds no adjudication policy, grant/action, queue/lease, state, decision, contribution, conditional branch, readiness check, or initiative dependency. diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-PLAN5-revision-rebase-reconciliation.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-PLAN5-revision-rebase-reconciliation.md new file mode 100644 index 000000000..ababa2322 --- /dev/null +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-PLAN5-revision-rebase-reconciliation.md @@ -0,0 +1,171 @@ +# Chunk Contract: WS-CON-001-PLAN5 - Revision Rebase Reconciliation + +## Goal and risk + +Adopt the human-confirmed rule that a human-review `needs_revision` transition +is the only in-progress synchronization boundary for all changed applicable +Project Guide and policy versions. Preserve frozen context during assignment, +submission, and an active ReviewLease; atomically prepare the next attempt from +the complete current valid context; and never mutate completed history. + +This is an L1 product-policy and cross-subsystem specification change. It +changes no runtime, schema, migration, API, authorization registration, or +workflow behavior. + +## Human intent ledger + +### Problem being solved + +Canonical documents already rebase Project Guide context after a human +`needs_revision`, but explicitly keep submitter ContributionPolicy terms frozen +for the lifetime of the TaskAssignment. That mixes old and new governing +context in the next revision attempt. + +### Why this matters + +The contributor and next reviewer must use one coherent current project +context after revision preparation, while the completed Review and every prior +Submission, ContributionRecord, and CompensationAward remain auditable and +immutable. + +### Target behavior and design chosen + +- Publication or activation alone never mutates active work. +- `accept` and `reject` finish under the exact assignment, Submission, and + ReviewLease context already frozen for that attempt. +- A human `needs_revision` creates the current reviewer contribution under the + completed lease-frozen version, then revision preparation compares the + complete applicable current context: Project Guide/source activation, + submission-artifact policy, pre-submit and post-submit checker policies, + review policy, revision policy, task-template/task-execution context, and + ContributionPolicyVersion. +- The next-attempt context keeps unchanged components and atomically replaces + every changed component with the complete current valid version, forward or + backward where reactivation is allowed. +- The TaskAssignment stores the authoritative rebased submitter + ContributionPolicyVersion for the next attempt; the next ReviewLease + independently freezes the then-current reviewer ContributionPolicyVersion. +- Missing, incomplete, inconsistent, crossed-project, revoked, or unsafe + current context blocks preparation; no mixed context may be published. +- Checker-caused remediation remains distinct and does not perform this human + revision rebase. + +### Alternatives rejected + +- Lifetime assignment freeze: rejected because revised work could use an old + economic policy while every other project contract has moved. +- Silent publication-time mutation: rejected because it changes active work + without a lifecycle checkpoint. +- Retroactive history rewrite: rejected because completed work and earned + awards must remain immutable. + +### Boundaries and non-goals + +REV/task owns revision preparation and TaskAssignment/Submission/ReviewLease +lineage. CON owns ContributionPolicy selection/freeze validation and consumes +the authoritative frozen version. This chunk adds no runtime implementation, +new state, public route, permission/action, compensation calculation, or ART +provider behavior. + +### Proof strategy + +Contradiction scans, Markdown links, stale wording gates, exact diff review, +and focused security, product/ops, architecture, and docs review must pass. + +## Allowed files + +```text +docs/decision_0010_revision_context_rebase.md +docs/decision_0003_project_guides_are_first_class.md +docs/decision_0016_contribution_compensation_boundary.md +README.md +docs/glossary.md +docs/architecture_lockdown.md +docs/architecture_data_model.md +docs/product_principles.md +docs/principles.md +docs/risk_register.md +docs/product_first_user_flows.md +docs/roadmap_implementation_backlog.md +docs/spec_review_lifecycle.md +docs/spec_contribution_compensation.md +docs/architecture_lifecycle_state_machine.md +docs/architecture_system_architecture.md +docs/operations_revision_replay.md +docs/operations_queue_policy.md +docs/operations_reviewer_workflow.md +docs/operations_project_operating_manual.md +docs/operations_payment_reputation.md +docs/template_project_guide.md +docs/template_review_packet.md +docs/template_submission_packet.md +docs/template_revision_replay.md +docs/template_task.md +.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/{INTENT.md,PLAN.md,CHUNK_MAP.md,STATUS.md,RISKS.md,DECISIONS.md,CONFORMANCE_MATRIX.md,SOURCE_MANIFEST.md} +.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-PLAN5-revision-rebase-reconciliation.md +.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-05A-legacy-economic-terms-cutover-and-task-freeze.md +.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-06-review-lease-contribution-policy-freeze.md +.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-07-atomic-review-contribution-award-participant.md +.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/reviews/WS-CON-001-PLAN5-*.md +.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/{PLAN.md,CHUNK_MAP.md,STATUS.md,DECISIONS.md,RISKS.md,CONFORMANCE_MATRIX.md} +.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-09A-revision-context-resubmission.md +.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-10-contribution-integration-hidden-composition.md +.agent-loop/REVIEW_LOG.md only WS-CON-001-PLAN5 result +``` + +## Not allowed + +```text +backend or frontend runtime and tests +migrations, schemas, APIs, workflows, dependencies, CI, or coverage controls +AUTH/ART runtime contracts or service identities +archival/imported reference specifications +roadmap spreadsheet or CSV exports +the user-owned local PDF deletion +``` + +## Acceptance criteria + +- [x] ADR 0010 is the authoritative complete-context human revision-rebase + decision, ADR 0016 agrees with it, and neither contains a contribution-policy + exclusion. +- [x] Assignment/Submission/ReviewLease context remains immutable until a + human `needs_revision`; publication alone causes no drift. +- [x] Accept/reject use frozen current-at-attempt context. +- [x] The completed needs-revision Review and reviewer contribution use the + completed lease-frozen version. +- [x] Revision preparation compares the complete applicable active context: + Project Guide/source activation, submission-artifact policy, pre-submit and + post-submit checker policies, review policy, revision policy, task-template/ + task-execution context, and ContributionPolicyVersion. It publishes one + atomic kept/rebased/blocked next-attempt context. +- [x] The human `needs_revision` Review, reviewer contribution/award, task and + assignment effects, initial preparation or blocked outcome, audit/outbox + effects, and contributor-visible state commit once or roll back together. +- [x] The next submitter attempt uses the rebased ContributionPolicyVersion and + the next ReviewLease independently freezes the then-current reviewer version. +- [x] Prior Submissions, Reviews, ContributionRecords, and Awards are never + rebased or rewritten. +- [x] Checker-caused remediation remains a distinct no-human-rebase path. +- [x] Canonical docs contain no contradictory lifetime TaskAssignment freeze or + contribution-terms-never-rebase instruction. + +## Verification + +```bash +git diff --check +python3 scripts/check_markdown_links.py +python3 scripts/check_stale_workstream_wording.py +python3 scripts/check_stale_authorization_docs.py +python3 -m unittest -v scripts.test_lightweight_agent_gates +rg contradiction scan for revision rebase and frozen contribution terms +``` + +## Review and stop + +Required focused review: security/auth, product/ops, architecture, and docs. +CI-integrity and test-delta are unrelated because no CI or test file may +change. Human review should focus on the atomic +rebase boundary, immutable historical economic truth, and cross-subsystem +ownership. Stop at the planning/specification PR checkpoint; do not implement +runtime behavior or begin 03B automatically. 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 f7ae099ac..8c13fd930 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 @@ -22,7 +22,7 @@ PLAN4 is the current-main end-to-end refresh after merged AUTH 02D. | `WS-REV-001-07B` | Immutable reviewer notes/findings | 07A | Skeleton; no evidence upload | | `WS-REV-001-08` | Pure decision validator/effect plan | 07B | Skeleton; no canonical write | | `WS-REV-001-09A1` | Review-rooted revision episode/preparation persistence | 08 + human round/deadline decision | Skeleton | -| `WS-REV-001-09A2` | TASK revision participant and context resolver | 09A1 | Skeleton | +| `WS-REV-001-09A2` | TASK complete-context revision participant and resolver | 09A1 + CON current-version selection contract | Skeleton | | `WS-REV-001-09A3` | Contributor finding-response records | 09A2 | Skeleton; no evidence upload | | `WS-REV-001-09A4` | Human prepared N+1 and checker-source XOR | 09A3 + TASK/ART submission cutover | Skeleton | | `WS-REV-001-09A5` | Replacement-assignment preparation successor | 09A4 + AUTH replacement contract | Skeleton | diff --git a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/CONFORMANCE_MATRIX.md b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/CONFORMANCE_MATRIX.md index e6213da8c..e3a0e1557 100644 --- a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/CONFORMANCE_MATRIX.md +++ b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/CONFORMANCE_MATRIX.md @@ -11,7 +11,7 @@ No row is complete from prose or an unmerged owner contract. | Leases | 03A2, 03B, 06A-C, 11A/C | One active lease globally; canonical reviewer; packet manifest; reviewer ContributionPolicyVersion freeze; release/decline/expiry/revocation/lazy recovery and both-order races | Claim/release/expiry/reclaim/revocation through exact admitted service identities | | Review history | 04A-B, 08, 10 | Every decision/finding/resolution immutable; exact predecessor/assignment lineage; reviewer CON operation before branch; accept-only FinalAcceptance and submitter operation; reject exact assignment; atomic rollback | Real accept/needs_revision/reject HTTP/database/audit/CON agreement and changed replay denial | | Revision paths | 09A1-A5, 09B, 10, 11B-D | Human Review revision creates one immutable non-branching preparation before readable state; REV consumes owner-supplied checker remediation lineage, keeps task context, creates no Review/preparation/CON record for checker-only remediation, and never classifies it as legacy | Separate checker and human drills both reach corrected N+1 without policy or lineage drift | -| Revision context | 09A1-A5, 09B | Review-rooted preparation consumes owner-supplied immutable Submission/current-context facts; kept/rebased/blocked; exact head acknowledgement; one winner per head; replacement successor; no contribution-policy rebase; checker path bypasses human preparation | Human context display, checker rerun, prior-reviewer preference, resolution, final decision; checker correction returns open | +| Revision context | 09A1-A5, 09B | Review-rooted preparation consumes owner-supplied immutable Submission/current-context facts; complete guide/policy context kept/rebased/blocked atomically, including prior/next submitter ContributionPolicyVersion; exact head acknowledgement; one winner per head; replacement successor; completed lease/contribution/award history immutable; checker path bypasses human preparation | Human context display, checker rerun, prior-reviewer preference, resolution, final decision; checker correction returns open | | Limits/deadlines | 09A1-A4, 11B | Human-approved round/deadline semantics only; DB time and frozen episode facts; checker retries excluded; repair cannot bypass exhaustion; D6 close only | Before/equal/after, exact replay/races, checker D6 denial, no synthetic Review/CON record | | Reject/admin close | 10, 11B/D | Human reject only from Review; exact assignment blocked/task rejected. PM/Operator closes use canonical cancelled reasons and create no Review/CON | Authorized/denied/cross-project/rollback proof; no `closed` token | | Artifact packet access | 03B, 07A, 11D | Active-exact-lease packet bytes; metadata-only history; no reviewer/response evidence candidate/finalize path; no raw store/provider access | Local/MinIO/S3 packet-owner conformance plus outage/integrity no-adverse-outcome drill | diff --git a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/DECISIONS.md b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/DECISIONS.md index f8d4cd058..5a3ffcbac 100644 --- a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/DECISIONS.md +++ b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/DECISIONS.md @@ -405,17 +405,19 @@ enter human grant evaluation, borrow Operator authority, or occupy a human FK. Shared outbox dispatch retains its separately owned identity. Authorization and audit retain actor kind so UUID shape never implies human authority. -### D17 - Contribution Policy Freeze Is Independent Of Revision Context - -Legacy compensation-context state is removed by WS-CON. It is not retained in the -final Project Guide, Submission, CheckerRun, Task Context, or -RevisionContextPreparation contract, and it is not replaced by the current -moving `ContributionPolicyVersion`. - -Submitter `ContributionPolicyVersion` freezes once on the exact TaskAssignment; -reviewer `ContributionPolicyVersion` freezes separately on each ReviewLease. Forward or backward guide -rebase changes neither an existing assignment freeze nor an existing lease -freeze. A later lease may independently freeze the then-current reviewer terms. +### D17 - Contribution Policy Freeze Rebases Only At Human Revision Boundary + +Legacy compensation-context state is removed by WS-CON and no moving selector +may silently change an active attempt. Task claim initially freezes the +submitter `ContributionPolicyVersion`; each ReviewLease independently freezes +the reviewer version. Accept and reject use those exact versions. + +After a human `needs_revision`, complete-context preparation keeps an unchanged +submitter version or atomically rebases a changed valid version on the +continuing TaskAssignment for the next attempt, with prior/next lineage in the +preparation. The completed Review and reviewer contribution retain the old +lease freeze. A later lease independently freezes the reviewer version then +current. Prior history is never rewritten. ### D18 - Authority-Loss Replacement Preserves Source And Changes Target 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 203a2a030..faa41522a 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 @@ -247,6 +247,13 @@ selection. CON never creates, updates, closes, or authorizes a lease. CON-03C may consume merged REV Review/FinalAcceptance/ReviewLease schema, and REV-10 waits for CON-07's mandatory flush-only participant. +On human `needs_revision`, REV composes the task-owned complete-context +preparation after the reviewer CON operation in the same transaction. The +completed reviewer record keeps its lease-frozen policy. Preparation may keep +or rebase the continuing TaskAssignment's submitter policy for the next +attempt, and the next ReviewLease independently freezes the reviewer version +then current. REV owns orchestration and lineage, not CON policy selection. + ## Alternatives rejected - Waiting for all ART/CON work before any REV persistence. 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 328dddb9b..5ce1be9cb 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 @@ -14,7 +14,7 @@ | R10 | Checker remediation is confused with human revision | Critical | Source XOR, separate participants, no synthetic Review/finding/contribution. | | R11 | Decision partially commits without contribution effects | Critical | First Review commit only in chunk 10 with mandatory CON participant and fault injection. | | R12 | Submitter contribution is inferred directly from Review | Critical | Accept-only REV FinalAcceptance is the sole CON submitter source. | -| R13 | Contribution terms rebase with guide context | Critical | Assignment and lease freezes remain independent of guide/revision context. | +| R13 | Human revision publishes mixed guide/policy context or rewrites completed economic history | Critical | One complete-context preparation keeps/rebases all applicable components atomically; completed lease/contribution/award history remains immutable; checker remediation performs no human rebase. | | R14 | Public routes expose incomplete lifecycle | Critical | Routes remain absent until 13C; AUTH activation is hidden proof, not product release. | | R15 | Timers or recovery depend on background-job delivery | High | Database-time truth, lazy recovery, idempotent sweeps, reconciliation. | | R16 | Cross-domain lock order deadlocks | Critical | Command-specific published order, stable ID sorting, both-order tests. | 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 47b83fac7..427e68d36 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,6 +2,13 @@ ## Current status +WS-CON-001-PLAN5 is the active cross-specification input for revision behavior: +a human `needs_revision` atomically keeps/rebases/blocks the complete applicable +next-attempt guide and policy context, including the submitter +ContributionPolicyVersion. Existing Submissions, Reviews, leases, +ContributionRecords, and awards remain immutable; checker remediation remains +distinct. + `WS-REV-001-03A1` implements the hidden queue/admission persistence foundation. PR #262 is reconciled with trusted main `2feaf47d`; ART retains migration 0050 and REV owns its exact 0051 successor. The chunk adds no REV route, action diff --git a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-09A-revision-context-resubmission.md b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-09A-revision-context-resubmission.md index 18a339a63..28c4417f3 100644 --- a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-09A-revision-context-resubmission.md +++ b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-09A-revision-context-resubmission.md @@ -12,7 +12,11 @@ CheckerRun-rooted path and is not treated as legacy. RevisionContextPreparation persistence after human approval of exact round/ deadline semantics. - `WS-REV-001-09A2`: task-owned preparation participant and guide-context - resolver plus Task Context read. The participant uses 09A1 persistence and + resolver plus Task Context read. It resolves the complete applicable current + guide/source, submission/checker, review, revision, task-execution, and + submitter ContributionPolicy context; keeps unchanged components, rebases all + changed valid components together, or blocks the whole preparation. The + participant uses 09A1 persistence and flushes through the caller's session; decision transaction composition and the single commit remain in chunk 10. - `WS-REV-001-09A3`: human Review finding responses/evidence only. @@ -28,7 +32,7 @@ CheckerRun-rooted path and is not treated as legacy. AUTH-13 owns public command/cutover/activation after its contract amendment. Checker remediation creates no Review/finding/reviewer contribution, performs no -guide rebase, consumes no human revision round/deadline, and returns to open +human complete-context rebase, consumes no human revision round/deadline, and returns to open routing. Human Review revision requires blocking-finding responses and later prefers the prior reviewer. diff --git a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-10-contribution-integration-hidden-composition.md b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-10-contribution-integration-hidden-composition.md index 31173ea26..5110f65c7 100644 --- a/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-10-contribution-integration-hidden-composition.md +++ b/.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-10-contribution-integration-hidden-composition.md @@ -151,9 +151,11 @@ reputation scoring reviewer record to the actual Review author. The v1 Review/findings remain unchanged, and only accepted v2 creates FinalAcceptance and its submitter record. -- Forward/backward guide rebase leaves TaskAssignment ContributionPolicyVersion - unchanged; each Review uses its lease freeze; reviewer award eligibility is - decision-neutral for the same frozen rule. +- Human revision preparation keeps an unchanged TaskAssignment + ContributionPolicyVersion or atomically rebases a changed valid current + version with the complete next-attempt context. The completed Review uses its + lease freeze; each later lease freezes the reviewer version then current; + reviewer award eligibility remains decision-neutral for the same frozen rule. - Chain reads expose bounded relationship metadata only. Historical artifact bytes remain inaccessible without the active exact packet manifest. - Internal API contracts use `/api/v1` and stable errors, but production OpenAPI diff --git a/README.md b/README.md index 62bccd4dd..7f22912d9 100644 --- a/README.md +++ b/README.md @@ -227,7 +227,7 @@ status. Current changes receive review through [CONTRIBUTING.md](CONTRIBUTING.md - [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 Uses The Active Project Guide](docs/decision_0010_revision_context_rebase.md) +- [ADR 0010: Human Revision Rebase Uses The Complete Active Project Context](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) @@ -393,16 +393,18 @@ Workstream is built as durable operational infrastructure: Governance: - project rules live in guides and policies, not chat memory -- guide and policy versions are locked per task so rules do not drift silently +- guide and policy versions are frozen for each active attempt so rules do not + drift silently; only human `needs_revision` preparation atomically rebases + changed applicable versions for the next attempt - out-of-band guidance is not enforceable until it becomes a guide, policy, template, or checker contract update Lifecycle and revision: - status is a ledger, not a loose label - 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 +- revision context is prepared from the complete active Project Guide and + policy context before resubmission; exact component matches are kept, every + changed valid component is rebased together, and unsafe mixed context blocks Artifacts, evidence, and auditing: diff --git a/docs/architecture_data_model.md b/docs/architecture_data_model.md index 116d200a1..06dcea066 100644 --- a/docs/architecture_data_model.md +++ b/docs/architecture_data_model.md @@ -1025,10 +1025,10 @@ Fields: - `created_at` 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. +not synthesize a reject Review. Complete next-attempt context selection is +deterministic: exact prior component matches keep, every changed valid active +guide/policy component rebases together, and missing or unsafe active context +blocks for manager repair. ## ContributionPolicy @@ -1321,9 +1321,10 @@ task/project state. The contributor does not provide submission version, evidenc ids, checker results, checker run ids, guide versions, source snapshots, effective project policy ids/hashes, pre-submit checker ids/bundle hashes, post-submit checker policy ids/versions/hashes, exact review policy identities, -or exact revision policy identities. Submitter award eligibility remains governed by the -immutable TaskAssignment-frozen `ContributionPolicyVersion` and is not restated -on the submission. +or exact revision policy identities. Submitter award eligibility is governed by +the TaskAssignment-selected `ContributionPolicyVersion` for the exact attempt +and is not contributor-supplied. Human revision preparation records prior/next +policy lineage before it may update that selector; publication alone cannot. Version 1 has neither revision-source field. Every later version has exactly one: a checker-remediation version stores the server-derived @@ -1633,17 +1634,25 @@ Fields: - `prior_locked_guide_id` - `prior_locked_guide_version` - `prior_locked_guide_activation_sequence` +- `prior_locked_guide_source_snapshot_id` and hash - `next_locked_guide_id` - `next_locked_guide_version` - `next_locked_guide_activation_sequence` +- `next_locked_guide_source_snapshot_id` and hash +- prior and next locked submission-artifact-policy identity and hash - `prior_locked_effective_project_submission_artifact_policy_hash` - `next_locked_effective_project_submission_artifact_policy_hash` +- prior and next locked pre-submit-checker policy identity, version, and hash - `prior_locked_pre_submit_checker_bundle_hash` - `next_locked_pre_submit_checker_bundle_hash` +- prior and next locked post-submit-checker policy identity, version, and hash - `prior_locked_review_policy_id`, generation, and hash - `next_locked_review_policy_id`, generation, and hash - `prior_locked_revision_policy_id`, generation, and hash - `next_locked_revision_policy_id`, generation, and hash +- prior and next locked task-template and task-execution policy context +- `prior_submitter_contribution_policy_version_id` +- `next_submitter_contribution_policy_version_id` - `outcome`: `kept | rebased | blocked` - `direction`: `forward | backward | null` - `context_digest` @@ -1659,21 +1668,30 @@ Purpose: This immutable Review-rooted record is created atomically before a contributor can observe human-review-caused revision. Checker remediation retains the Task's -locked context and creates no preparation. 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 history show prior/next identity, activation -sequence, direction, reason, and change summary. No ContributionPolicyVersion is -stored in this preparation. +locked context and creates no preparation. Preparation compares the prior +Submission's complete stamped context with every applicable currently active +Project Guide and policy selector: guide identity/version/activation sequence, +source snapshot, submission-artifact policy, effective project policy, +pre-submit and post-submit checker policies, ReviewPolicy, RevisionPolicy, +task-template/task-execution context, and the submitter +ContributionPolicyVersion selected by CON. An exact component match is kept; +every changed valid component is rebased together for the next attempt. Missing, +incomplete, inconsistent, crossed-project, revoked, or otherwise unsafe context +blocks the whole preparation for manager repair. Task Context returns only the +validated complete chain head. No context rebase occurs during active review; +the reviewer reads the context stamped on the leased Submission. + +Publication never silently rebases award eligibility during an active attempt. +After a human `needs_revision`, revision preparation records prior and next +submitter `ContributionPolicyVersion` references and atomically updates the +continuing TaskAssignment when the complete current next-attempt context +changes. The completed reviewer contribution retains its ReviewLease-frozen +version; each new ReviewLease independently freezes the then-current reviewer +version. + +The contributor and reviewer history show prior/next guide, policy—including +ContributionPolicyVersion—identity, activation sequence where applicable, +direction, reason, and change summary. ## FinalAcceptance diff --git a/docs/architecture_lifecycle_state_machine.md b/docs/architecture_lifecycle_state_machine.md index 20e2ad22f..1b11b15c9 100644 --- a/docs/architecture_lifecycle_state_machine.md +++ b/docs/architecture_lifecycle_state_machine.md @@ -163,17 +163,24 @@ Required before entering: Before the contributor resumes from a human Review, Workstream appends one immutable Review-rooted RevisionContextPreparation in the same transaction that -enters `needs_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 Project Manager repair. Checker-caused remediation +enters `needs_revision`. It compares the complete prior stamped context with +the active applicable guide/source, submission/checker, review, revision, +task-execution, and submitter ContributionPolicy context. Exact component +matches keep; every changed valid component rebases together. Missing, +inconsistent, revoked, or unsafe context blocks the whole preparation for +Project Manager repair. The continuing TaskAssignment receives the selected +submitter policy only for the next attempt; the completed Review and lease do +not change. Checker-caused remediation remains a distinct CheckerRun-rooted path, keeps the Task's locked context, and creates no Review, ReviewFinding, preparation, reviewer contribution, or synthetic human actor. Its corrected Submission persists the unique immutable `remediation_source_checker_run_id` for the exact predecessor CheckerRun; a later retry cannot rewrite that causal lineage. -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. +A revision context rebase never mutates the prior submitted attempt or +completed contribution/award. It prepares and stamps only the next attempt. The +contributor and reviewer must see prior and next versions and the complete +guide/policy change summary. ### ACCEPTED @@ -285,9 +292,9 @@ submission v2 -> accepted Each resubmission must link to the prior submission it supersedes. 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. +human revision may rebase every changed valid component to the complete current +applicable context. The immutable preparation records that next-attempt context +and never rewrites an earlier Submission, Review, contribution, or award. ## Revision Replay diff --git a/docs/architecture_lockdown.md b/docs/architecture_lockdown.md index dcf1879cb..d329255cc 100644 --- a/docs/architecture_lockdown.md +++ b/docs/architecture_lockdown.md @@ -137,12 +137,12 @@ 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. +After a human `needs_revision` Review, preparation compares the complete prior +stamped context with all applicable current guide and policy selectors. Exact +component matches keep; every changed valid component rebases together; +incomplete, inconsistent, revoked, or unsafe context blocks for manager repair. +Task Context returns the frozen preparation. No rebase occurs during review; +the reviewer uses the context stamped on the leased Submission. ### Task Contract @@ -163,10 +163,14 @@ reviewing auditable: - deadline or SLA when applicable - source type and source reference when imported -Compensation is not task-guide context. TaskAssignment freezes the active -published submitter `ContributionPolicyVersion`; ReviewLease independently -freezes the reviewer version. Either rule may be explicitly unpaid and therefore -create no award. +Compensation remains an independently owned CON policy, but its selected version +is part of the complete governing work context. Task claim initially freezes +the submitter `ContributionPolicyVersion`; ReviewLease independently freezes the +reviewer version. Publication never silently changes an active attempt. A human +`needs_revision` atomically rebases every changed applicable next-attempt +context component, including the submitter version, while the completed lease +and prior history remain immutable. Either rule may be explicitly unpaid and +therefore create no award. ### Human Accountability diff --git a/docs/architecture_system_architecture.md b/docs/architecture_system_architecture.md index 801a718f3..8307e9c21 100644 --- a/docs/architecture_system_architecture.md +++ b/docs/architecture_system_architecture.md @@ -211,7 +211,8 @@ Owns: - immutable RevisionContextPreparation chains - SubmissionFindingResponse and FindingResolution lineage -- exact Project Guide keep/forward/backward/block classification +- complete Project Guide/policy context keep/forward/backward/block + classification, including prior/next submitter ContributionPolicyVersion - resubmission and preferred-return linkage ### Artifact Service Boundary diff --git a/docs/decision_0003_project_guides_are_first_class.md b/docs/decision_0003_project_guides_are_first_class.md index 1f0065059..7e97d6fe4 100644 --- a/docs/decision_0003_project_guides_are_first_class.md +++ b/docs/decision_0003_project_guides_are_first_class.md @@ -69,12 +69,13 @@ 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. +Submission's complete stamped context with the project's complete applicable +active Project Guide, submission/checker, review, revision, task-execution, and +submitter ContributionPolicy context. Exact component matches are kept, every +changed valid component is rebased together, and missing or unsafe context +blocks the whole preparation for manager repair. RevisionPolicy does not select +a stale context. 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 @@ -83,10 +84,12 @@ implementation. Rules that affect submission intake must be encoded in `PreSubmitCheckerPolicy`. Chat messages and informal notices are not enforceable rules until they are moved into those contracts. -Publication of a `ContributionPolicyVersion` is independent of guide activation. A -`TaskAssignment` freezes the active submitter `ContributionPolicyVersion`, and -a `ReviewLease` independently freezes the active reviewer version. Guide or -revision-context changes never silently replace either frozen version. +Publication of a `ContributionPolicyVersion` is independent of guide +activation and never silently changes active work. Task claim initially freezes +the submitter version on `TaskAssignment`; human revision preparation may +atomically rebase it with the rest of the next-attempt context. Each +`ReviewLease` independently freezes the reviewer version then current and is +never rewritten. ## Consequences diff --git a/docs/decision_0010_revision_context_rebase.md b/docs/decision_0010_revision_context_rebase.md index bdd686afb..99d62e6e5 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 Uses The Active Project Guide +# ADR 0010: Human Revision Rebase Uses The Complete Active Project Context ## Status @@ -13,8 +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 must use the Project Guide that is active when revision - preparation freezes the next-attempt context +- a revised attempt must use the complete applicable project context active + when revision preparation freezes the next attempt - the contributor and reviewer must be able to see what changed ## Decision @@ -26,18 +26,34 @@ versions stamped on that submission. 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. - -Preparation compares the prior Submission's stamped guide identity and -activation sequence with the project's currently active guide pair: - -- 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. +`TaskAssignment` stores only `task_id` for guide-context linkage, while its +separate submitter ContributionPolicyVersion selector follows the guarded rule +below. Every Submission stamps the exact guide identity, version, and immutable +per-project activation sequence used for that attempt. + +Preparation compares the prior Submission's stamped context with the complete +currently active applicable project context: + +- Project Guide identity, version, source snapshot, and activation sequence; +- effective SubmissionArtifactPolicy; +- generated pre-submit and approved post-submit checker policies; +- ReviewPolicy and RevisionPolicy; +- task-template and task-execution policy context; and +- the submitter ContributionPolicyVersion selected by CON. + +For every component: + +- an exact identity/version/activation match keeps the prior value; +- any changed internally consistent active value rebases the next attempt and + records forward or backward direction where chronology applies, including an + older intentionally reactivated version; +- a missing, incomplete, crossed-project, internally inconsistent, revoked, + suspended where new freezes are prohibited, or unsafe value blocks the whole + preparation for covered Project Manager repair. + +Preparation publishes one complete context. It cannot rebase the guide while +retaining a stale submitter contribution policy or otherwise mix components +from incompatible contexts. Version strings are never ordered. RevisionPolicy supplies limit and deadline inputs but does not choose a stale guide over the currently active authority. @@ -49,6 +65,9 @@ Every revision context preparation must record its outcome. When the next attemp - prior stamped guide identity, version, and activation sequence - next frozen guide identity, version, activation sequence, source snapshot, and task-execution policy context +- prior and next effective submission-artifact, pre-submit checker, + post-submit checker, review, revision, task-template/task-execution, and + submitter ContributionPolicyVersion references - outcome `kept`, `rebased`, or `blocked` and forward/backward direction where applicable - rebase reason - guide or policy change summary shown to the contributor @@ -65,6 +84,27 @@ 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. +Publication or activation alone never mutates an active assignment, prepared +attempt, Submission, or ReviewLease. `accept` and `reject` finish under the +exact context already frozen for that attempt. Human `needs_revision` is the +only in-progress synchronization boundary for the complete next-attempt +context. + +The ReviewLease that produced `needs_revision` and its reviewer +`completed_review` ContributionRecord remain governed by that lease's frozen +reviewer ContributionPolicyVersion. Revision preparation updates the continuing +TaskAssignment's submitter ContributionPolicyVersion to the selected current +version for the next attempt and records the prior/next lineage. The next +ReviewLease independently freezes the reviewer ContributionPolicyVersion then +current. Prior Submissions, Reviews, ContributionRecords, and +CompensationAwards are never rewritten. + +The human `needs_revision` Review, reviewer contribution and applicable award, +task and assignment effects, initial kept/rebased/blocked preparation, audit and +outbox effects, and contributor-visible state commit once or roll back together. +Checker-caused remediation remains a separate CheckerRun-rooted path and does +not perform this human revision rebase. + Out-of-band guidance has no acceptance force until it is encoded in one of: - project guide @@ -85,13 +125,15 @@ Positive: - guide and policy updates can improve future revisions without mutating prior submissions - repeated lessons become durable guide, checker, review, revision, or template changes -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. +- contributors receive one coherent current context after a human revision + boundary instead of new guide requirements paired with stale economic terms +- completed reviewer and award history remains governed by its original + ReviewLease freeze Tradeoff: - revision preparation needs an explicit audit record +- TaskAssignment policy lineage needs an explicit guarded rebase rather than a + lifetime immutable selector - 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_0016_contribution_compensation_boundary.md b/docs/decision_0016_contribution_compensation_boundary.md index da1646314..c3b596e24 100644 --- a/docs/decision_0016_contribution_compensation_boundary.md +++ b/docs/decision_0016_contribution_compensation_boundary.md @@ -53,7 +53,13 @@ money and/or project-points `ContributionAwardDefinition` rows. TaskAssignment freezes the submitter policy version during authorized task claim. ReviewLease independently freezes the reviewer policy version during -authorized review claim. Later publication changes only new work. +authorized review claim. Later publication alone changes only new work and +never mutates an active attempt. After a human `needs_revision`, the task-owned +revision preparation atomically rebases a changed submitter policy together +with every changed applicable next-attempt context component. The completed +Review and reviewer award retain the prior lease freeze; the next ReviewLease +freezes the reviewer version then current. Prior contributions and awards are +never rewritten. The retired guide-bound economic-policy aggregate and all semantic and physical consumers are removed through CON-05A/05B. No alias, fallback, dual read/write, diff --git a/docs/glossary.md b/docs/glossary.md index 1bc0141dd..1c6b54918 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -319,10 +319,12 @@ 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. +Submission; source and target TaskAssignments; prior and next Project +Guide/source, submission/checker, review, revision, task-execution, and +submitter ContributionPolicy versions; context digest; change summary; and +`kept`, `rebased`, or `blocked` result. A human revision rebase records forward +or backward direction where applicable and publishes one complete next-attempt +context without rewriting prior work. ## FinalAcceptance diff --git a/docs/operations_payment_reputation.md b/docs/operations_payment_reputation.md index cc8d2acb3..2f51c969f 100644 --- a/docs/operations_payment_reputation.md +++ b/docs/operations_payment_reputation.md @@ -68,6 +68,11 @@ Default: `ContributionPolicyVersion` decides whether it creates an award - `needs_revision` and `reject` create no FinalAcceptance, submitter contribution, or submitter award +- the completed needs-revision reviewer record uses its ReviewLease-frozen + version; successful complete-context preparation may update the continuing + TaskAssignment's submitter version only for the next attempt, while prior + records and awards remain immutable +- each next ReviewLease independently freezes the reviewer version then current - fulfillment is recorded only by an authenticated adapter callback bound to the award's frozen adapter binding - a fulfilled award requires an immutable receipt, exact quantity, and external diff --git a/docs/operations_project_operating_manual.md b/docs/operations_project_operating_manual.md index 81b36b03d..41ef74619 100644 --- a/docs/operations_project_operating_manual.md +++ b/docs/operations_project_operating_manual.md @@ -66,6 +66,12 @@ activated as separate guide-policy context. Contribution policy is project-level and independently published by its owning authority. Checker policy records are generated by Workstream setup and exposed as generated setup output. +Publication never silently changes an active attempt. After a human +`needs_revision`, revision preparation compares the complete applicable active +guide and policy context and atomically rebases every changed valid component, +including the submitter ContributionPolicyVersion, for the next attempt. The +completed ReviewLease and all prior history remain immutable. + Project setup operators inspect setup state through API endpoints, not direct database queries. Project identity and the caller's self-authorization context follow the exact local-grant rules below. The three setup-diagnostic and three @@ -310,11 +316,11 @@ 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. -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 +For human-review revision, Workstream compares the prior Submission's complete +stamped context with every applicable current guide and policy selector. Exact +component matches keep; every changed valid component rebases together; unsafe context blocks. Task Context returns the frozen preparation, and the contributor -sees the prior/next versions, direction, and change summary before resubmitting. +sees 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 diff --git a/docs/operations_queue_policy.md b/docs/operations_queue_policy.md index b1706fb17..c17d3d05f 100644 --- a/docs/operations_queue_policy.md +++ b/docs/operations_queue_policy.md @@ -162,9 +162,11 @@ Contributor-facing lane for fixable issues from automated checks, pre-review gat Policy: - 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 + Submission's complete governing context with the currently active applicable + guide/source, submission/checker, review, revision, task-execution, and + submitter ContributionPolicy context +- exact component matches keep; every changed valid component rebases together; + unsafe or incomplete context blocks the whole preparation 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 @@ -258,10 +260,10 @@ Every operating day starts with: | `SUBMITTED -> EVALUATION_PENDING` | immutable submission version, locked post-submit checker policy id/version/hash/body copied from the task context | | `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 -> NEEDS_REVISION` | immutable Review, at least one blocking ReviewFinding, reviewer `completed_review` under the completed lease freeze, atomic complete-context kept/rebased/blocked preparation for the next attempt; 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 -> SUBMITTED` | exact complete-context preparation head/digest, replacement Submission stamped with its selected guide/policy context, 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 | diff --git a/docs/operations_reviewer_workflow.md b/docs/operations_reviewer_workflow.md index bde361c6e..1b6b1eef3 100644 --- a/docs/operations_reviewer_workflow.md +++ b/docs/operations_reviewer_workflow.md @@ -11,6 +11,10 @@ REV-13 joint release complete. `spec_review_lifecycle.md` is normative. 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 same rule applies to every stamped policy version. A human +`needs_revision` initiates complete-context preparation only after this Review; +the current Review and reviewer contribution retain the active lease's frozen +context. The reviewer must have an exact active project `reviewer` grant represented by canonical human `ActorProfile.id`. Submitter, adjudicator, administrative, or @@ -98,7 +102,7 @@ AUTH prepared authority and final evaluation -> consume ReviewLease and close ReviewQueueEntry -> CON reviewer operation -> accept: FinalAcceptance + task effects + CON submitter operation - needs_revision: task effect only + needs_revision: task effect + complete-context preparation reject: assignment block + task effect -> REV stages shared audit/outbox -> commit once @@ -147,6 +151,11 @@ Each blocking finding must have: Recording `needs_revision` sets the Task to `needs_revision`, keeps the same TaskAssignment `active`, and creates no FinalAcceptance or submitter contribution. The reviewer `completed_review` still commits atomically. +In that same transaction, task-owned preparation keeps unchanged context or +rebases every changed applicable guide/policy component—including the +TaskAssignment submitter ContributionPolicyVersion—for the next attempt. An +unsafe or incomplete component blocks contributor visibility; no mixed context +is exposed. ## Reject diff --git a/docs/operations_revision_replay.md b/docs/operations_revision_replay.md index 9378a21cd..9b7356667 100644 --- a/docs/operations_revision_replay.md +++ b/docs/operations_revision_replay.md @@ -19,21 +19,31 @@ rooted resubmission path using the Task's existing locked context; it does not fabricate a Review, finding, preparation, reviewer contribution, or human actor. 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: - -- exact pair match: `kept`; -- any different valid active pair: `rebased` with `forward` or `backward`; +compares the prior Submission's complete stamped governing context with the +currently active applicable Project Guide/source, submission-artifact, +pre-submit/post-submit checker, review, revision, task-template/task-execution, +and submitter ContributionPolicy context: + +- every exact component match: `kept`; +- all changed valid active components: `rebased` together, with `forward` or + `backward` recorded where the component is ordered; - missing, incomplete, inconsistent, revoked, or unsafe context: `blocked`. -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. - -ContributionPolicyVersion is independent. The TaskAssignment freeze and each -ReviewLease freeze never change because guide context rebases. +The preparation keeps every exact component match and rebases every changed +valid component as one selected context. Any missing, incomplete, inconsistent, +revoked, or unsafe component blocks the whole preparation. It freezes the +selected context, context digest, prior Submission, originating Review, source +and target TaskAssignments, prior/next submitter ContributionPolicyVersion, and +change summary. Task Context returns the validated head, not moving selectors. +No rebase occurs during review; the reviewer reads the context stamped on the +leased Submission. + +The completed reviewer contribution uses the originating ReviewLease freeze. +The continuing TaskAssignment is updated only by successful human revision +preparation for the next submitter attempt, and each later ReviewLease +independently freezes the reviewer version then current. The decision, +reviewer contribution/award, task/assignment effects, preparation or blocked +outcome, audit/outbox, and visible state commit once or roll back together. ## Submitter Response @@ -55,7 +65,7 @@ ReviewFinding response or resolution. ## Resubmission And Checks A human-Review Submission N+1 acknowledges the exact preparation head/digest, -links its immediate predecessor, and stamps the frozen context. A checker- +links its immediate predecessor, and stamps the complete frozen context. A checker- remediation Submission N+1 instead binds the exact final needs-revision CheckerRun and the Task's existing locked context; it carries no preparation or ReviewFinding response. Both paths rerun the normal finalization and checker diff --git a/docs/principles.md b/docs/principles.md index 3d73c4c39..d8f84e4d9 100644 --- a/docs/principles.md +++ b/docs/principles.md @@ -86,10 +86,10 @@ frozen preparation, responds to every unresolved blocking finding, and submits a replacement version. The system preserves immutable findings, responses, evidence, and later resolutions. -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 +Prior Submissions keep their stamped context. Preparation compares the complete +prior context with all applicable current guide and policy selectors: exact +components keep, every changed valid component rebases together, and unsafe +context blocks. Task Context returns the frozen preparation. No rebase occurs during review. ## 6. Compensation Follows Contribution diff --git a/docs/product_first_user_flows.md b/docs/product_first_user_flows.md index e7c4d5e76..fba60f66e 100644 --- a/docs/product_first_user_flows.md +++ b/docs/product_first_user_flows.md @@ -160,9 +160,10 @@ Acceptance: 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. +2. Workstream prepares immutable context from every applicable currently active + Project Guide and policy selector. +3. Exact prior component matches keep; every changed valid component rebases + together; unsafe context blocks the whole preparation. 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. diff --git a/docs/product_principles.md b/docs/product_principles.md index 6e313194d..e915869aa 100644 --- a/docs/product_principles.md +++ b/docs/product_principles.md @@ -39,11 +39,11 @@ checker policy, review policy, revision policy, contribution policy, or task template. 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. +revision preparation compares the complete prior context with all applicable +current guide and policy selectors: exact components keep, every changed valid +component rebases together, 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 diff --git a/docs/risk_register.md b/docs/risk_register.md index 92ce6e69c..aea9bd3c3 100644 --- a/docs/risk_register.md +++ b/docs/risk_register.md @@ -33,8 +33,9 @@ A task can be sent back for revision after the project guide or policies changed Mitigation: - 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 +- exact stamped guide/policy component matches keep context; every changed + valid active component rebases together; unsafe context blocks the whole + preparation - Task Context returns the frozen preparation; reviewer context uses the exact leased Submission stamp without a separate rebase - every rebase records an audit event diff --git a/docs/roadmap_implementation_backlog.md b/docs/roadmap_implementation_backlog.md index f8c0f0141..ccfd074d8 100644 --- a/docs/roadmap_implementation_backlog.md +++ b/docs/roadmap_implementation_backlog.md @@ -66,6 +66,9 @@ and REV-13 joint release; this backlog does not activate an endpoint or job. - assign skill tags - freeze submitter ContributionPolicyVersion on TaskAssignment and reviewer version on ReviewLease +- after human `needs_revision`, atomically keep/rebase/block the complete + next-attempt context and update only the continuing assignment's submitter + version when it changed - change status only through allowed transitions - record status audit event - block direct `SUBMITTED -> ACCEPTED` @@ -116,8 +119,8 @@ and REV-13 joint release; this backlog does not activate an endpoint or job. - create replay for resubmission - 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 +- prepare the next attempt from the complete active Project Guide and policy + context using the deterministic keep/rebase/block rule ### Compensation And Reputation diff --git a/docs/spec_contribution_compensation.md b/docs/spec_contribution_compensation.md index 1b5b93e95..d119c9fe7 100644 --- a/docs/spec_contribution_compensation.md +++ b/docs/spec_contribution_compensation.md @@ -434,6 +434,15 @@ TaskAssignment.submitter_contribution_policy_version_id The participant flushes only and never commits. The task subsystem owns claim composition and status effects. +After a human `needs_revision`, the task-owned revision-preparation participant +locks the complete current next-attempt context and calls CON to select and +validate the current published submitter ContributionPolicyVersion. An +unchanged version is kept; a changed valid version atomically replaces the +TaskAssignment selector for the next attempt and records prior/next lineage in +the immutable preparation. A missing, incomplete, crossed-project, ambiguous, +or binding-ineligible version blocks the whole preparation. Publication alone +never performs this update. + ### Reviewer freeze During authorized review claim, REV locks its queue and ReviewLease facts @@ -456,8 +465,12 @@ only the freeze capability. - Suspension races MUST be resolved with explicit locks and both-order tests. - Missing, draft, ambiguous, crossed-project, or incomplete policy state fails before the assignment or lease commits. -- Revision-context rebase MUST NOT rebase submitter award eligibility. Each new - ReviewLease independently freezes the reviewer version then current. +- Human revision preparation MUST rebase changed submitter award eligibility + together with every changed applicable next-attempt context component. The + completed Review and reviewer contribution keep the prior ReviewLease freeze; + each new ReviewLease independently freezes the reviewer version then current. +- Accept and reject never rebase. They evaluate the exact assignment and lease + versions frozen for the current attempt. ## Atomic Review-To-Contribution Transaction @@ -522,8 +535,16 @@ Task.status = needs_revision TaskAssignment.status remains active no FinalAcceptance no submitter operation +task-owned complete-context preparation keeps/rebases/blocks the next attempt ``` +The Review, reviewer contribution/award, task and assignment effects, initial +preparation or blocked outcome, audit/outbox rows, and contributor-visible state +commit once or roll back together. The preparation may update the continuing +TaskAssignment's submitter policy selector for future work; it never changes +the completed Review, its reviewer policy, or any prior Submission, +ContributionRecord, or CompensationAward. + Reject: ```text diff --git a/docs/spec_review_lifecycle.md b/docs/spec_review_lifecycle.md index e4a564a60..61f6f2f1a 100644 --- a/docs/spec_review_lifecycle.md +++ b/docs/spec_review_lifecycle.md @@ -237,8 +237,11 @@ Task. 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. +or policy publication changes neither freeze during an active attempt. After a +human `needs_revision`, complete-context preparation may atomically update the +continuing TaskAssignment to the current valid submitter version for the next +attempt. A later lease freezes the then-current reviewer terms without +rewriting an earlier lease. ## Checker Admission @@ -484,24 +487,29 @@ Controlled revision preparation applies only after an immutable human `Review(needs_revision)`. Checker-caused remediation remains the distinct CheckerRun-rooted path above and performs no guide rebase or human finding replay. -Revision preparation compares the prior Submission's stamped guide identity and -activation sequence with the project's currently active Project Guide pair: +Revision preparation compares the prior Submission's complete stamped context +with the project's complete currently active applicable guide and policy +context: -- 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. +- exact component identity/version/activation match: `kept`; +- every changed internally consistent active component: `rebased` together, + recording `forward` or `backward` where applicable, including intentional + reactivation of an older version; +- any missing, incomplete, revoked, internally inconsistent, crossed-project, + or unsafe active component: the whole context is `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. +next-attempt guide/source, submission/checker, review, revision, +task-template/task-execution, and submitter ContributionPolicy context; context +digest; outcome; direction; change summary; source and target TaskAssignment; +preparation sequence; preparing actor/process; and audit link. It records prior +and next submitter ContributionPolicyVersion and atomically updates the +continuing assignment when that selector changed. 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 @@ -520,6 +528,14 @@ 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. +The needs-revision Review and its reviewer contribution/award use the completed +ReviewLease's frozen policy. The next Submission uses the complete prepared +context, and the next ReviewLease independently freezes the reviewer policy +then current. Accept and reject perform no rebase. The Review, reviewer +contribution/award, task and assignment effects, initial preparation or blocked +outcome, audit/outbox effects, and contributor-visible state commit once or +roll back together. + ## Finding Replay And Resubmission For a human-review origin, every unresolved blocking ReviewFinding requires one diff --git a/docs/template_project_guide.md b/docs/template_project_guide.md index 12d3e36e6..40f5934a4 100644 --- a/docs/template_project_guide.md +++ b/docs/template_project_guide.md @@ -233,8 +233,10 @@ Record only project-owner-supplied business terms and their durable source: This section is informational. It is not an active contribution award rule. Workstream publishes `ContributionPolicyVersion` independently, and `TaskAssignment` and -`ReviewLease` freeze their applicable versions. Revision context never rebases -compensation. +`ReviewLease` freeze their applicable versions for the current attempt. After a +human `needs_revision`, complete-context preparation records and applies any +changed submitter ContributionPolicyVersion for the next attempt; each next +ReviewLease independently freezes the reviewer version then current. ## Lessons Learned diff --git a/docs/template_review_packet.md b/docs/template_review_packet.md index bde0037f8..9ff201a08 100644 --- a/docs/template_review_packet.md +++ b/docs/template_review_packet.md @@ -88,6 +88,8 @@ Accept-only effects: - ContributionRecord ID/type `accepted_submission`: - source FinalAcceptance ID and TaskAssignment ID: - submitter-frozen ContributionPolicyVersion: +- revision-prepared submitter ContributionPolicyVersion lineage, when this is a + post-`needs_revision` attempt: - CompensationAward ID or explicit unpaid result: `needs_revision` and `reject` contain no FinalAcceptance or submitter diff --git a/docs/template_revision_replay.md b/docs/template_revision_replay.md index af916d086..f9089af11 100644 --- a/docs/template_revision_replay.md +++ b/docs/template_revision_replay.md @@ -23,13 +23,18 @@ | direction | `forward`, `backward`, or `null` | | prior guide ID/version/activation sequence | `` | | next guide ID/version/activation sequence | `` | -| frozen source snapshot and task-execution policies | `` | +| prior/next source, submission/checker, review, revision, and task-execution policies | `` | +| prior submitter ContributionPolicyVersion | `` | +| next submitter ContributionPolicyVersion | `` | | 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. +not perform a separate rebase. The completed reviewer contribution retains the +originating ReviewLease freeze. This preparation records and atomically applies +the complete selected next-attempt context, including a changed submitter +ContributionPolicyVersion; the next ReviewLease independently freezes the +reviewer version then current. ## Immutable Finding Responses diff --git a/docs/template_submission_packet.md b/docs/template_submission_packet.md index 95a83def9..c95202671 100644 --- a/docs/template_submission_packet.md +++ b/docs/template_submission_packet.md @@ -45,9 +45,11 @@ the task's locked context. The contributor does not provide those ids, versions, hashes, or internal policy bodies in the submission packet. -Compensation is not submission input. The server uses the immutable -TaskAssignment submitter ContributionPolicyVersion freeze and the ReviewLease -reviewer freeze during contribution creation. +Compensation is not submission input. The server uses the TaskAssignment +submitter ContributionPolicyVersion selected for this prepared attempt and the +ReviewLease reviewer freeze during contribution creation. Only a prior human +`needs_revision` preparation may have rebased the assignment selector; project +publication or submission input cannot change it. Workstream runs pre-submit checks from the locked project pre-submit checker policy before creating the submission. Preflight failures return `PreSubmitCheckResponse` with structured diff --git a/docs/template_task.md b/docs/template_task.md index 6cdc4e831..13d12ab6d 100644 --- a/docs/template_task.md +++ b/docs/template_task.md @@ -77,8 +77,11 @@ directly. ## Assignment Compensation Snapshot These values are server-owned and appear only after TaskAssignment creation. -The TaskAssignment freezes the active published ContributionPolicyVersion; task -creators do not provide award fields directly. +The TaskAssignment initially freezes the active published +ContributionPolicyVersion; task creators do not provide award fields directly. +Publication cannot change an active attempt. A successful human +`needs_revision` preparation may atomically record and apply a changed current +version for the next attempt. - submitter contribution policy version id: - contribution type: `accepted_submission`