diff --git a/.agent-loop/CURRENT_STATE.md b/.agent-loop/CURRENT_STATE.md index c8e7cb9fd..31921fd57 100644 --- a/.agent-loop/CURRENT_STATE.md +++ b/.agent-loop/CURRENT_STATE.md @@ -28,10 +28,10 @@ authority; these records do not grant or withhold it. | Initiative | Durable state on `main` | Remaining boundary | |---|---|---| -| [WS-ARCH-001](initiatives/WS-ARCH-001-modular-monolith-boundaries/STATUS.md) | Complete through `WS-ARCH-001-02H`; CP01A-CP03B establish hidden CON adapter-binding behavior and exact Finance Authority activation; PLAN4 continues incremental debt retirement | Prepare CP04's executable hidden ContributionPolicy behavior contract; PLAN4 keeps debt retirement delivery-coupled without blocking features on unrelated frozen debt; the wider PLAN2 path still targets durable `allow_review`, and `02I` remains later | +| [WS-ARCH-001](initiatives/WS-ARCH-001-modular-monolith-boundaries/STATUS.md) | Complete through `WS-ARCH-001-02H`; CP01A-CP03B establish hidden CON adapter-binding behavior and exact Finance Authority activation; CP04 is split into executable contracts | Implement CP04A hidden ContributionPolicy read/create/update-draft behavior; CP04B then owns publish/retire, and the wider PLAN2 path still targets durable `allow_review` | | [WS-ART-001](initiatives/WS-ART-001-immutable-artifact-storage/STATUS.md) | Active delivery initiative; verified ready-admission publication, hidden preparation, consumption and binding are merged through ARCH-02H | Implement exact post-submit materialization only after the unified guide/checker and PLAN2 public contracts are executable; live cutover remains later | | [WS-AUTH-001](initiatives/WS-AUTH-001-workstream-authorization-service/STATUS.md) | Active delivery initiative; project-policy authority and unified compilation authorization are merged through `12I` | POL-03B consumes 12I next; remaining AUTH activation chunks wait for their exact hidden owner behavior | -| [WS-CON-001](initiatives/WS-CON-001-contribution-compensation-boundary/STATUS.md) | Active delivery initiative; CP03B completes hidden adapter-binding behavior and exact Finance Authority activation; ContributionPolicy persistence and shared lifecycle audit foundations are merged | Prepare CP04 hidden ContributionPolicy behavior; later complete guide-activation validation/persistence before task readiness, preserving immutable attempt lineage through Submission and ReviewLease | +| [WS-CON-001](initiatives/WS-CON-001-contribution-compensation-boundary/STATUS.md) | Active delivery initiative; CP03B completes hidden adapter-binding behavior and exact Finance Authority activation; ContributionPolicy persistence and shared lifecycle audit foundations are merged | Implement CP04A hidden policy draft behavior, then CP04B publication/retirement; later complete guide-activation validation/persistence before task readiness | | [WS-AUTH-003](initiatives/WS-AUTH-003-module-boundary-recovery/STATUS.md) | AUTH boundary foundation and first public-capability proof through POL-03A are merged | Repair each touched AUTH capability through `authorization.api` and shrink the canonical AUTH ledger | | [WS-POL-003](initiatives/WS-POL-003-unified-project-guide-compilation/STATUS.md) | Active delivery initiative; hidden compilation custody and AUTH-12I activation are merged | Implement POL-03B authorized compilation persistence, then continue the reviewed dependency order | | [WS-REV-001](initiatives/WS-REV-001-review-revision-lifecycle/STATUS.md) | Independent foundations through queue admission and reviewer-lease persistence are merged through `03A2`; schema/packet foundations may continue behind their own gates | Live admission/claim requires canonical 04E `allow_review`; ReviewLease copies the admitted Submission's immutable attempt policy version, and the first Review commit requires CON-03C/07 atomic contribution/award behavior | @@ -101,8 +101,8 @@ AUTH unavailable registration, hidden CON binding/policy behavior, exact AUTH activations, CON validation, PROJECT guide binding, TASK attempt lineage, and clean v0.1 legacy economic-path removal in that order. CP02 and CP03A are merged, and CP03B is complete with the four exact hidden Finance Authority -actions active. Later CP04-CP09 children remain -non-executable until their current-main contracts are expanded. +actions active. CP04A/CP04B now have executable contracts; later CP05-CP09 +remain non-executable until their current-main contracts are expanded. - WS-ARCH-001-PLAN3 is planned; its planning merge changed no runtime behavior. - WS-ARCH-001-CP01 is a planned split and non-executable. @@ -123,7 +123,10 @@ non-executable until their current-main contracts are expanded. consume the public AUTH API and same-owner private wiring is confined to the exact AUTH adapter root. No compensation delivery or fulfillment behavior is activated. -- WS-ARCH-001-CP04 is proposed and non-executable. +- WS-ARCH-001-CP04 is a planned non-executable parent. CP04A and CP04B have + executable contracts; CP04A is the next implementation boundary. +- WS-ARCH-001-CP04A is planned and is the next hidden policy-draft boundary. +- WS-ARCH-001-CP04B is planned after CP04A for hidden publication/retirement. - WS-ARCH-001-CP05 is proposed and non-executable. - WS-ARCH-001-CP06 is proposed and non-executable. - WS-ARCH-001-CP07 is proposed and non-executable. diff --git a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/CHUNK_MAP.md b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/CHUNK_MAP.md index 50278e12f..b428b4af5 100644 --- a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/CHUNK_MAP.md +++ b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/CHUNK_MAP.md @@ -25,7 +25,9 @@ | `WS-ARCH-001-CP03` | Adapter-binding activation coordination parent | L1 | Planned split into CP03A/CP03B; non-executable | | `WS-ARCH-001-CP03A` | Closed adapter target identity and PROJECTS/ACTORS owner eligibility | L1 | Merged through PR #340; actions remain unavailable | | `WS-ARCH-001-CP03B` | AUTH exact Finance Authority adapter-binding activation | L1 | Complete; four exact hidden actions active through public ports, with private wiring confined to the AUTH adapter root | -| `WS-ARCH-001-CP04` | CON hidden ContributionPolicy behavior | L1 | Proposed skeleton after merged CP03B evidence | +| `WS-ARCH-001-CP04` | Hidden ContributionPolicy behavior coordination parent | L1 | Planned split into CP04A/CP04B; non-executable | +| `WS-ARCH-001-CP04A` | CONTRIBUTIONS public API and hidden read/create/update-draft behavior | L1 | Planned executable contract; first CP04 implementation | +| `WS-ARCH-001-CP04B` | Hidden ContributionPolicy publish/retire behavior | L1 | Planned executable contract after merged CP04A | | `WS-ARCH-001-CP05` | AUTH exact ContributionPolicy activation | L1 | Proposed skeleton after CP04 evidence | | `WS-ARCH-001-CP06` | CON guide-activation/revision policy-validation port | L1 | Proposed skeleton after CP05 | | `WS-ARCH-001-CP07` | PROJECT guide-bound ContributionPolicyVersion persistence | L1 | Proposed skeleton after CP06 | @@ -52,8 +54,9 @@ feature contract crosses more than one reviewable mutation boundary. The 02A-02I sequence is the executable split of parent 02, subject to plan review and human approval. -CP04-CP09 and chunks 03A-04F are non-executable planning skeletons. Before implementation, -each must be replaced with a current-main contract that names exact allowed and +CP04 is a non-executable split parent; CP04A and CP04B are executable contracts. +CP05-CP09 and chunks 03A-04F are non-executable planning skeletons. Before implementation, +each remaining skeleton must be replaced with a current-main contract that names exact allowed and not-allowed files, migration head, runnable commands, reviewers, and the public types it extends. Their sequencing is approved here; their current text does not authorize code changes. CP03 is split/non-executable; CP03A and CP03B are diff --git a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/DECISIONS.md b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/DECISIONS.md index a0c38af37..1aeaa4f39 100644 --- a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/DECISIONS.md +++ b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/DECISIONS.md @@ -158,3 +158,18 @@ authorization; create/suspend/resume use one domain-specific opaque prepare/consume/close port backed by AUTH only in CP03B. CP03A owns the exact adapter target identity and PROJECTS/ACTORS eligibility prerequisite. CON never imports AUTH internals or translates the CON-owned `instrument_type` value. + +## D20: CP04 splits editable drafts from irreversible publication + +`app.modules.contributions` owns ContributionPolicy lifecycle truth; +`app.modules.compensation` owns adapter-binding and instrument identity. CP04A +introduces the contributions public API, hidden read/create/update-draft +behavior, and shared mutation recovery. CP04B adds publish and retire after +CP04A merges. All actions remain unavailable until CP05 and neither child adds +a route. + +Draft updates replace one complete two-rule graph. Publication authorizes only +the digest recomputed from locked server-owned rows and exact active +unit/binding facts. Retirement affects future selection without rewriting +previously frozen lineage. No compatibility or alternate economic-policy path +is introduced. diff --git a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/DISCOVERY.md b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/DISCOVERY.md index 85e8c5fcf..3254bfce7 100644 --- a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/DISCOVERY.md +++ b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/DISCOVERY.md @@ -202,3 +202,55 @@ remain non-executable until refreshed against current `main`. repository evidence requiring a compatibility alias, deployed-history backfill, or guessed legacy-row conversion. - No open pull request currently owns this sequence. + +## CP04 current-main discovery after CP03B + +Observations: + +- Policy persistence is owned by `app.modules.contributions`, not the + adapter-binding `app.modules.compensation` module. The existing policy, + version, rule, and award-definition ORM graph has no public contributions + API, repository, or lifecycle service. +- Database guards already enforce complete two-rule publication, explicit + unpaid/compensated shapes, immutable published/retired content, + project/unit/binding ownership, exact numeric bounds, and one active policy + per project. Existing tests manipulate ORM rows directly; they do not prove + application commands, authorization ordering, idempotent recovery, or + concealed cross-project denial. +- CP01B registered exactly five typed AUTH actions and fact digests: read, + create draft, update draft, publish, and retire. They remain unavailable; no + additional policy action or permission is required. +- `contributions/schemas.py` imports the private + `compensation.schemas.CompensationInstrumentType`. CP04 touches this edge and + must expose the closed enum through COMPENSATION's public API, then remove the + private import without transferring behavior ownership. +- No durable policy mutation-operation reservation or immutable lifecycle event + currently supports unknown-commit recovery. Final-row uniqueness alone + cannot stop concurrent requests from both consuming authorization. + +Resolved design: + +- CP04 is a non-executable parent split into CP04A and CP04B. CP04A owns the + public policy API, read/create/update-draft behavior, and shared durable + operation/event foundation. CP04B owns publish and retire. +- A project has at most one open draft version. Draft creation creates a new + aggregate/version when none is reusable, or the next version on the current + non-retired aggregate. Exact duplicate recovery returns the immutable result + only after current read authorization. +- Draft update replaces the complete two-rule graph atomically. It never + patches published content and never creates ContributionRecords or awards. +- Publish first acquires the operation fence and checks immutable replay + recovery; only a new operation then locks the aggregate, version, rules, + definitions, units, and adapter bindings, recomputes canonical digest/binding + facts from server-owned rows, consumes/closes PREP before mutation, and makes + the exact version current. Exact recovery returns the immutable event result + and performs no row mutation or second AUTH consumption. +- Retire targets the exact current published version and prevents future + selection without rewriting any frozen downstream history. + +Implementation-time unknowns: + +- the next Alembic revision identifier; +- the exact boundary/structural debt entries on then-current main; +- whether existing baseline guards need a narrow correction in addition to the + required operation/event persistence. diff --git a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/INTENT.md b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/INTENT.md index cdd5d5343..c61d29561 100644 --- a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/INTENT.md +++ b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/INTENT.md @@ -66,3 +66,10 @@ compatibility or invented historical migration work. PLAN3 changes planning only. It does not register an action, activate a route, write policy behavior, mutate schema, or start a runtime child. + +CP04 planning succeeds when editable draft behavior and irreversible +publication are separately reviewable, every mutation is replay-safe and +transaction-bound, publication authority is derived only from locked +server-owned graph facts, and production remains deny-default until CP05. +It does not authorize a route, guide/task/review write, contribution/award +creation, fulfillment, or compatibility path. diff --git a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/PLAN.md b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/PLAN.md index 724965116..49af82986 100644 --- a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/PLAN.md +++ b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/PLAN.md @@ -369,3 +369,26 @@ adapter-binding registration. CON validates policy facts; PROJECTS owns guide writes; CP08 supplies TASK-owned persistence/public facts; ARCH-03B alone owns Task readiness, claim, assignment, and Submission command writes; REV later copies only the immutable Submission policy stamp. + +CP04 is split at the irreversible lifecycle boundary: + +```text +CP04A public API + read/create/update-draft + mutation recovery foundation +-> CP04B publish/retire + immutable lifecycle proof +-> CP05 exact AUTH activation +``` + +Both children remain hidden, route-unreachable, and production deny-default +because all five actions stay unavailable until CP05. Every mutation uses one +ordering: + +```text +root transaction -> request digest -> operation fence -> recovery check +-> owner and eligibility locks -> prepare -> consume -> close in finally +-> product mutation + immutable event -> flush without commit +``` + +No policy row is staged before successful consumption and closure. Publish +recomputes the complete graph digest after locking server-owned rules, +definitions, units, and bindings. Retire disables future selection only and +never rewrites frozen downstream lineage. diff --git a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/RISKS.md b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/RISKS.md index 4e0828277..3232bdd0e 100644 --- a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/RISKS.md +++ b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/RISKS.md @@ -25,6 +25,10 @@ | Review decision commits without mandatory contribution consequences | Critical | Stable REV schema precedes CON-03C/07; every decision atomically creates reviewer ContributionRecord/awards and accept additionally creates FinalAcceptance plus submitter record/awards | | Composition root absorbs domain decisions | High | Composition opens the unit of work and wires transaction-bound ports only; TASK command owns Submission sequencing and each target port enforces its own invariants | | Policy behavior starts before exact AUTH registration | Critical | CP01A and CP01B register their separate typed unavailable authority before CP02/CP04 behavior; CP03B/CP05 activate only after their hidden proof and exact prerequisites | +| Policy mutation consumes AUTH before an operation race is fenced | Critical | CP04A installs one transaction-scoped operation fence and immutable recovery event used by every CP04 mutation; recovery requires current read authorization and creates no second effect/evidence | +| Publication authorizes caller-supplied economic content | Critical | CP04B locks the complete graph and referenced unit/binding rows, recomputes canonical facts from server-owned state, and consumes PREP before mutation | +| Draft update races publication or leaves a partial graph | Critical | CP04A replaces the complete two-rule graph atomically; CP04B holds the same custody through publication and database guards reject incomplete/mixed state | +| Retirement rewrites active work or historical awards | Critical | Retirement disables future selection only; frozen guide/task/assignment/Submission/ReviewLease/contribution/award lineage remains immutable | | Binding management inherits retirement, fulfillment, callback, or delivery authority | Critical | CP01A through CP03 exclude all action-bearing identities and authority for retirement, fulfillment, callback, and delivery; CP03A adds only the closed target-only `workstream.compensation.adapter` identity with no action, permission, route, evaluator, or service-matrix row | | CON writes PROJECT or TASK aggregates | Critical | CP06 returns immutable validation facts only; CP07 and CP08 own their respective writes | | Consolidated v0.1 schema gains fake compatibility debt | High | CP09 performs a clean current-baseline cut and forbids aliases, dual paths, and invented backfills | diff --git a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/STATUS.md b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/STATUS.md index 6b8cd5129..0ec9aa2c7 100644 --- a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/STATUS.md +++ b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/STATUS.md @@ -57,8 +57,8 @@ registered/unavailable. CP02 is merged with hidden CON behavior while its AUTH actions remain unavailable; CP03 is split, CP03A is merged, and CP03B is complete with four exact hidden Finance Authority actions - active, while CP04-CP09 remain - non-executable skeletons. + active. CP04 is split into executable CP04A/CP04B contracts, while CP05-CP09 + remain non-executable skeletons. - [WS-ARCH-001-PLAN4](chunks/WS-ARCH-001-PLAN4-incremental-debt-retirement.md) is planned and changes no runtime. It makes the existing incremental strangler operational: unrelated frozen debt cannot block delivery, new debt is @@ -93,7 +93,12 @@ actions are active only for covered human Finance Authority, nested adapters consume the public AUTH API, and private wiring remains at the AUTH adapter root without delivery or fulfillment behavior. -- WS-ARCH-001-CP04 is proposed: hidden ContributionPolicy behavior. +- WS-ARCH-001-CP04 is a planned non-executable parent split into CP04A hidden + read/create/update-draft behavior and CP04B hidden publish/retire behavior. +- WS-ARCH-001-CP04A is planned with an executable hidden policy-draft contract + and is next. +- WS-ARCH-001-CP04B is planned with an executable hidden publish/retire + contract after CP04A. - WS-ARCH-001-CP05 is proposed: exact ContributionPolicy activation. - WS-ARCH-001-CP06 is proposed: CON policy-validation port. - WS-ARCH-001-CP07 is proposed: PROJECT guide binding. diff --git a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/chunks/WS-ARCH-001-CP04-con-policy-behavior.md b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/chunks/WS-ARCH-001-CP04-con-policy-behavior.md index 79440a4e0..546489106 100644 --- a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/chunks/WS-ARCH-001-CP04-con-policy-behavior.md +++ b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/chunks/WS-ARCH-001-CP04-con-policy-behavior.md @@ -1,17 +1,19 @@ # Chunk Contract: WS-ARCH-001-CP04 — Hidden ContributionPolicy Behavior -Status: proposed non-executable skeleton after merged CP03B evidence. Risk: L1. +Status: planned non-executable parent after merged CP03B evidence. Risk: L1. -CON implements hidden ContributionPolicy read/draft/update/publish/retire -behavior using the existing persistence aggregate, exact binding lifecycle, and -opaque PREP protocol. Explicit unpaid and compensated rules remain distinct. -Routes remain absent and policy actions unavailable. PROJECT guide activation, -TASK readiness, claim, assignment, Submission, REV, awards, and AUTH edits are -excluded. +CONTRIBUTIONS implements hidden ContributionPolicy behavior through two bounded +children using the existing persistence aggregate, COMPENSATION-owned binding +lifecycle, and opaque PREP protocol. CP04A owns the public API, shared mutation +recovery, read, create draft, and complete draft replacement. CP04B owns +publication and retirement against the locked graph. -After hidden proof merges, a separate AUTH activation chunk activates only the -exact policy actions. +Routes remain absent and policy actions unavailable. PROJECT guide activation, +TASK readiness/claim/assignment/Submission, REV, ContributionRecord, +CompensationAward creation, fulfillment, and AUTH edits are excluded. CP05 +activates only the five registered actions after both children merge. ## Merge state - Outcome on merge: `planned` +- This is a split parent; no implementation targets it directly. diff --git a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/chunks/WS-ARCH-001-CP04A-con-policy-draft-behavior.md b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/chunks/WS-ARCH-001-CP04A-con-policy-draft-behavior.md new file mode 100644 index 000000000..762397721 --- /dev/null +++ b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/chunks/WS-ARCH-001-CP04A-con-policy-draft-behavior.md @@ -0,0 +1,186 @@ +# Chunk Contract: WS-ARCH-001-CP04A — Hidden ContributionPolicy Draft Behavior + +## Goal + +Expose the CONTRIBUTIONS-owned public policy capability and implement hidden, +route-unreachable read, create-draft, and complete update-draft behavior. Add +the shared durable mutation-operation/event foundation used by CP04A and CP04B. +Production authorization denies by default and all five policy actions remain +planned/unavailable. + +## Preconditions, risk and outcome + +- CP01B unavailable policy registration and CP03B adapter-binding activation + are merged. +- Current main still contains the discovered structural policy graph and guards. +- Risk: L1. + +## Merge state + +- Outcome on merge: `planned` +- The later CP04A implementation PR changes this outcome to `complete`. + +## Allowed files + +```text +backend/app/modules/contributions/api/** +backend/app/modules/contributions/{schemas.py,models.py,repository.py,service.py} +backend/app/modules/compensation/api/{__init__.py,policy_bindings.py} (instrument type and locked binding facts only) +backend/app/modules/compensation/policy_binding_service.py (owner implementation only) +backend/app/modules/projects/api/{__init__.py,contribution_policy.py} (policy-project eligibility contract only) +backend/app/modules/projects/contribution_policy.py (owner implementation only) +backend/app/adapters/contributions/__init__.py (same-owner composition only) +backend/app/adapters/projects/__init__.py (PROJECTS-owned policy-project eligibility only) +backend/app/db/models.py (metadata parity only if required) +backend/alembic/versions/.py +backend/alembic/env.py (head parity only) +backend/tests/contributions/** +backend/tests/architecture/** (exact boundary/API proof only) +backend/tests/test_alembic.py (head/schema parity only) +backend/tests/test_contributions.py (preserved DB regressions only; no new primary behavior container) +backend/scripts/{behavior_ownership.py,module_boundaries.py,run_test_lanes.py} (exact parity only) +.ci/behavior-ownership/** (exact CP04A targets only) +.ci/module-boundaries/private-edge-debt.v1.json (remove touched contributions->compensation.schemas edge only) +.agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/TEST_STRUCTURE_DEBT.json (generated parity; no new debt) +docs/{architecture_data_model.md,roadmap_status.md,spec_contribution_compensation.md} +.agent-loop/CURRENT_STATE.md +.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/{CHUNK_MAP.md,STATUS.md,DISCOVERY.md} +.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/{CHUNK_MAP.md,STATUS.md,AUTHORIZATION_HANDOFF.md} +.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/chunks/WS-ARCH-001-CP04A-con-policy-draft-behavior.md +.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/reviews/WS-ARCH-001-CP04A-*.md +``` + +Replace the migration placeholder with the then-current single Alembic +successor before implementation. + +## Not allowed + +```text +AUTH catalogue/evaluator/grant/action activation changes +public routes or Celery jobs +publish or retire behavior +ProjectGuide, TASK, Submission, REV, ContributionRecord, CompensationAward, fulfillment, callback, delivery or reputation behavior +cross-module private imports, compatibility aliases, generic service locators or a second authorization protocol +commits inside repositories/services or serialized prepared handles +``` + +## Public contract and behavior + +- Add immutable requests/results/views, stable concealed errors, and Protocol + ports under `app.modules.contributions.api`; expose no ORM/session/repository. +- Expose COMPENSATION's closed instrument enum and a transaction-held lookup + for exact active same-project adapter-binding facts through its public API + and owner-side service; remove the exact private schemas import from + CONTRIBUTIONS. COMPENSATION remains the only owner of adapter-binding and + instrument lifecycle truth. `ProjectCompensationUnit` stays + CONTRIBUTIONS-owned and is locked by the policy repository. +- Add and consume a PROJECTS-owned public transaction-held policy-project + eligibility port. CONTRIBUTIONS decides when policy lifecycle requires that + fence; PROJECTS only validates and retains its own eligibility state. +- Read requires exact project/policy/optional-version authorization and returns + immutable server-owned graph facts. +- Create-draft holds a project policy fence. It creates version 1 on a new + aggregate when none is reusable, otherwise the next version on the current + non-retired aggregate. Reject more than one open draft per project. +- Update-draft locks the exact project/policy/version and replaces the entire + graph: one `accepted_submission` and one `completed_review` rule; unpaid has + zero definitions; compensated has one or two unique money/project-points + definitions with canonical positive quantities. +- Update locks its CONTRIBUTIONS-owned same-project active units and consumes + the COMPENSATION public lookup for active adapter-binding identities as early + validation; CP04B revalidates both under publication locks. It never imports + COMPENSATION models, repository, service, or private schemas. +- Every mutation carries `operation_id` and `request_digest`, acquires a + transaction advisory fence before product locks/AUTH, and persists one + immutable recoverable event. +- Event types are exactly `draft_created`, `draft_updated`, `published`, and + `retired`. Each event stores `event_id`, `operation_id`, `request_digest`, + `event_type`, `actor_profile_id`, `project_id`, `policy_id`, `version_id`, + `version_number`, nullable `prior_current_version_id`, nullable + `prior_current_version_number`, `from_policy_status`, `to_policy_status`, + `from_version_status`, `to_version_status`, and database-owned `occurred_at`. + The immutable mutation result contains the same fields, so recovery never + reconstructs success from mutable current state. +- Exact duplicate recovery returns the immutable original result only after + current read authorization. Mismatch or failed authorization is concealed. +- The domain-facing authorization port is opaque and production deny-default; + test fakes may prove hidden behavior without activating an action. + +## Mandatory mutation order + +```text +caller-owned root transaction -> request digest -> operation fence +-> recovery check -> owner and eligibility locks -> prepare -> consume +-> close exactly once in finally -> product mutation + immutable event +-> flush, never commit +``` + +Denial, conflict, close failure, database failure, and rollback produce no +partial graph, event, reusable authority, or allowed evidence. + +## Acceptance criteria + +- [ ] Public API/implementation add no private cross-module edge. +- [ ] PROJECTS and COMPENSATION eligibility is consumed only through their + public transaction-held ports, with owner fences retained through mutation. +- [ ] Read/create/update remain route-unreachable and production deny-default. +- [ ] Operation fencing proves duplicate recovery and distinct-operation races + without double AUTH consumption. +- [ ] PREP denial/exception/wrong actor/session/transaction/copy/replay, close + failure, and post-close database failure fail atomically. +- [ ] PostgreSQL proves immutable operation events, exact attribution, + transition shape, operation uniqueness, and rejection of mutation/deletion/ + truncation. +- [ ] One primary behavior per test; no new test or production file reaches 500 + lines; touched frozen debt does not grow. +- [ ] Focused changed CONTRIBUTIONS/COMPENSATION coverage is at least 90%; + hosted repository coverage is not weakened. + +## Verification + +### Acceptance-to-test map + +| Criterion | Required future proof | Execution custody | +|---|---|---| +| Read remains concealed, route-unreachable, and production deny-default | `tests/contributions/test_policy_read.py::{test_read_denies_without_composed_authority,test_read_conceals_cross_project_and_missing_policy}` and `tests/contributions/test_policy_routes_absent.py::test_policy_routes_are_not_registered` | focused local command and hosted CI | +| Create/update hold owner fences and produce one complete graph | `tests/contributions/test_policy_draft_create.py`, `tests/contributions/test_policy_draft_update.py` | focused local command and hosted CI | +| PREP denial, exception, wrong actor/session/transaction, copy/replay, and close failure precede product mutation | `tests/contributions/test_policy_authorization_atomicity.py` with one primary failure behavior per test and an in-consume assertion that no policy/event row is staged | focused local command and hosted CI | +| Exact duplicate recovery returns the immutable original result only after current read authorization | `tests/contributions/test_policy_operation_recovery.py::{test_exact_duplicate_recovers_after_authorized_read,test_digest_mismatch_is_concealed,test_revoked_read_cannot_recover,test_recovery_creates_no_second_effect_or_evidence}` | focused local command and hosted CI | +| Distinct operations cannot race into duplicate open drafts or consume AUTH twice | `tests/contributions/test_policy_draft_concurrency.py` using independent PostgreSQL sessions and operation ids | hosted PostgreSQL lane only | +| Operation events are immutable, attributed, transition-valid, and cannot be mutated, deleted, or truncated | `tests/contributions/test_policy_event_postgresql.py` using direct SQL negative cases | hosted PostgreSQL lane only | +| Product/database failure after close rolls back product rows and staged participant evidence; closed authority stays unusable | `tests/contributions/test_policy_authorization_atomicity.py::{test_post_close_database_failure_rolls_back_all_effects,test_closed_authority_cannot_be_reused}` | focused local command and hosted PostgreSQL lane | +| No new oversized behavior container or weak aggregate test is introduced | test-structure boundary validation plus one-primary-behavior inspection for every named module above | local gate and hosted preflight | + +The focused pytest command must name every non-hosted-only module above. Hosted +CI must additionally run `test_policy_draft_concurrency.py` and +`test_policy_event_postgresql.py` against real PostgreSQL; SQLite or mocked-lock +substitution is not acceptance evidence. + +```bash +cd backend && .venv/bin/ruff check app/modules/contributions app/modules/compensation/api app/modules/compensation/policy_binding_service.py app/modules/projects/api app/modules/projects/contribution_policy.py app/adapters/contributions app/adapters/projects tests/contributions +cd backend && .venv/bin/python -m pytest -q tests/contributions/test_policy_read.py tests/contributions/test_policy_routes_absent.py tests/contributions/test_policy_draft_create.py tests/contributions/test_policy_draft_update.py tests/contributions/test_policy_authorization_atomicity.py tests/contributions/test_policy_operation_recovery.py tests/architecture/test_module_boundaries.py tests/test_alembic.py +cd backend && .venv/bin/python -m pytest -q tests/contributions --cov=app.modules.contributions --cov=app.modules.compensation.api --cov=app.modules.compensation.policy_binding_service --cov-report=term-missing --cov-fail-under=90 +cd backend && .venv/bin/python -m scripts.module_boundaries validate --protected-base +cd backend && .venv/bin/python -m scripts.test_structure_boundary validate --policy ../.agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/TEST_STRUCTURE_POLICY.md --ledger ../.agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/TEST_STRUCTURE_DEBT.json +python3 scripts/check_active_state_projections.py +python3 scripts/check_chunk_state_sync.py --base-ref +python3 scripts/check_markdown_links.py +git diff --check +``` + +Hosted CI additionally runs `tests/contributions/test_policy_draft_concurrency.py` +and `tests/contributions/test_policy_event_postgresql.py` with real PostgreSQL, +then owns complete semantic-lane and repository aggregate coverage proof; the +focused commands above own the remaining changed CP04A surface. + +## Required reviewers + +Architecture, security/auth, product/operations, QA, test-delta, CI integrity, +senior engineering, reuse/dedup, and documentation. + +## Human review focus and stop conditions + +Confirm aggregate ownership, complete replacement semantics, operation fencing, +PREP ordering, recovery, and absence of activation/routes. Stop and amend if +implementation needs another action, permission, route, foreign aggregate +write, or lifecycle state. diff --git a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/chunks/WS-ARCH-001-CP04B-con-policy-publication-behavior.md b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/chunks/WS-ARCH-001-CP04B-con-policy-publication-behavior.md new file mode 100644 index 000000000..805c6ec3e --- /dev/null +++ b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/chunks/WS-ARCH-001-CP04B-con-policy-publication-behavior.md @@ -0,0 +1,156 @@ +# Chunk Contract: WS-ARCH-001-CP04B — Hidden ContributionPolicy Publication + +## Goal + +Implement hidden publish and retire behavior using CP04A's public API, +operation/recovery custody, and opaque authorization port. Keep all policy +actions unavailable and add no route or downstream product behavior. + +## Preconditions, risk and outcome + +- CP04A is merged and current-main discovery is replayed. +- Risk: L1. + +## Merge state + +- Outcome on merge: `planned` +- The later CP04B implementation PR changes this outcome to `complete`; CP05 + then becomes next. + +## Allowed files + +```text +backend/app/modules/contributions/api/** +backend/app/modules/contributions/{models.py,repository.py,service.py} +backend/app/adapters/contributions/__init__.py +backend/alembic/versions/.py (only if schema proof requires correction) +backend/alembic/env.py (head parity only if migration exists) +backend/tests/contributions/** +backend/tests/architecture/** (exact boundary proof only) +backend/tests/test_alembic.py (only with migration) +backend/scripts/{behavior_ownership.py,run_test_lanes.py} (exact parity only) +.ci/behavior-ownership/** (exact CP04B targets only) +.agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/TEST_STRUCTURE_DEBT.json (generated parity; no new debt) +docs/{architecture_data_model.md,roadmap_status.md,spec_contribution_compensation.md} +.agent-loop/CURRENT_STATE.md +.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/{CHUNK_MAP.md,STATUS.md,DISCOVERY.md} +.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/{CHUNK_MAP.md,STATUS.md,AUTHORIZATION_HANDOFF.md} +.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/chunks/WS-ARCH-001-CP04B-con-policy-publication-behavior.md +.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/reviews/WS-ARCH-001-CP04B-*.md +``` + +## Not allowed + +```text +AUTH activation/evaluator/grant/catalogue changes +public routes, ProjectGuide/TASK/Submission/REV mutations +ContributionRecord, CompensationAward creation, fulfillment, callback, delivery or reputation behavior +caller-supplied publication truth, compatibility paths, service commits or serialized PREP handles +``` + +## Publish contract + +- Fence operation recovery before product locks or AUTH. +- Lock exact aggregate, draft version, both rules, definitions, referenced + project units, and adapter bindings through the CP04A public owner ports; + retain all owner fences through publication. +- Require a complete graph and active same-project units/bindings with exact + instrument alignment. +- Recompute canonical rules/definitions digest and sorted unique binding ids + from locked rows; require exact equality with typed AUTH facts. +- Consume and close PREP before changing version/policy state. +- Publish the version and make it current atomically. If another version is + currently published, retire that prior version in the same transaction with + exact actor/time attribution before installing the new current version. + Prior content and every downstream frozen reference remain immutable. +- One `published` operation event represents that entire atomic replacement. + Its nullable `prior_current_version_id` and + `prior_current_version_number` identify the automatically retired version; + the event's `actor_profile_id` and database-owned `occurred_at` are also the + exact `retired_by` and `retired_at` attribution stored on that prior version; + no second `retired` operation event is emitted. An explicit retire command + emits one `retired` event. Recovery returns only these immutable event facts, + never mutable aggregate state. +- Serialize same-project publication so the one-active-policy race has a + deterministic winner before AUTH consumption. + +## Retire contract + +- Target only the aggregate's exact current published version. +- Lock and verify expected state before AUTH; consume/close PREP, then retire + policy and version with exact actor/time attribution and one immutable event. +- Block future guide selection without rewriting any guide, task, assignment, + Submission, ReviewLease, ContributionRecord, or award history. +- A retired aggregate is terminal. A later policy requires a new aggregate and + normal draft/publish flow; no compatibility resurrection path exists. + +## Acceptance criteria + +- [ ] Publish/retire remain hidden and production deny-default. +- [ ] Publish facts equal digest/binding facts recomputed from locked rows. +- [ ] Concurrent child mutation, binding suspension, unit retirement, + competing publication, revocation, replay, cross-project use, wrong session/ + transaction, close failure, and rollback fail closed without mutation. +- [ ] Replacement publication retires exactly the prior current version while + preserving its content and frozen downstream references; aggregate retirement + is terminal. +- [ ] Exact duplicate recovery requires current read authorization and creates + no new evidence/effect. +- [ ] PostgreSQL rejects immutable graph mutation, lifecycle skips, forged + attribution/events, event mutation/deletion/truncation, and incomplete publish. +- [ ] No new file reaches 500 lines; one primary behavior per test; no frozen + debt growth; focused coverage remains at least 90%. +- [ ] CP05 alone becomes the next activation boundary. + +## Verification + +### Acceptance-to-test map + +| Criterion | Required future proof | Execution custody | +|---|---|---| +| Publish/retire remain concealed, route-unreachable, and production deny-default | `tests/contributions/test_policy_publication_authorization.py::{test_publish_denies_without_composed_authority,test_retire_denies_without_composed_authority}` and `tests/contributions/test_policy_routes_absent.py::test_policy_routes_are_not_registered` | focused local command and hosted CI | +| Publish consumes exact server-recomputed graph digest and binding ids | `tests/contributions/test_policy_publish.py::{test_publish_uses_locked_server_owned_graph,test_caller_supplied_graph_mismatch_denies}` | focused local command and hosted CI | +| PREP denial/exception/wrong actor/session/transaction/copy/replay/close failure occurs before lifecycle mutation | `tests/contributions/test_policy_publication_authorization.py` with one primary failure behavior per test and an in-consume assertion that no lifecycle change/event is staged | focused local command and hosted CI | +| Replacement publication atomically retires the prior current version with matching actor/time and emits one recoverable `published` event | `tests/contributions/test_policy_publish.py::{test_replacement_publication_is_one_atomic_event,test_replacement_preserves_prior_content_and_frozen_references}` | focused local command and hosted PostgreSQL lane | +| Exact duplicate recovery returns immutable event facts only after current read authorization | `tests/contributions/test_policy_publication_recovery.py` covering publish and retire duplicates, digest mismatch, revoked read, and no second effect/evidence | focused local command and hosted CI | +| Cross-project publish facts (policy, version, unit, or adapter binding) and retire targets (policy or exact current version) fail closed with concealed denial, no lifecycle mutation, and no staged AUTH evidence or other side effect | Focused service proof in `tests/contributions/test_policy_publication_authorization.py::{test_cross_project_policy_publish_is_concealed_without_effect,test_cross_project_version_publish_is_concealed_without_effect,test_cross_project_unit_publish_is_concealed_without_effect,test_cross_project_binding_publish_is_concealed_without_effect,test_cross_project_policy_retire_is_concealed_without_effect,test_cross_project_current_version_retire_is_concealed_without_effect}`; transaction/row-custody proof in `tests/contributions/test_policy_publication_cross_project_postgresql.py` using independently committed cross-project rows and direct assertions that lifecycle state/events and AUTH evidence remain absent | named focused tests run locally and in hosted CI; `test_policy_publication_cross_project_postgresql.py` runs in the hosted PostgreSQL lane only | +| Child mutation, binding suspension, unit retirement, and competing publication cannot cross held owner fences | `tests/contributions/test_policy_publication_concurrency.py` using independent PostgreSQL sessions and deterministic commit ordering | hosted PostgreSQL lane only | +| PostgreSQL rejects incomplete publication, lifecycle skips, forged attribution, event mutation/deletion/truncation, and stale prior-current identity | `tests/contributions/test_policy_lifecycle_postgresql.py` using direct SQL negative cases | hosted PostgreSQL lane only | +| Explicit retirement is terminal and cannot rewrite frozen downstream lineage or resurrect the aggregate | `tests/contributions/test_policy_retire.py::{test_retire_blocks_future_selection_without_rewriting_history,test_retired_aggregate_cannot_be_resurrected}` | focused local command and hosted CI | +| Database failure after close rolls back lifecycle state and staged AUTH evidence; closed authority remains unusable | `tests/contributions/test_policy_publication_authorization.py::{test_post_close_failure_rolls_back_all_effects,test_closed_publication_authority_cannot_be_reused}` | focused local command and hosted PostgreSQL lane | + +The focused pytest command must name every non-hosted-only module above. Hosted +CI must additionally run `test_policy_publication_concurrency.py` and +`test_policy_publication_cross_project_postgresql.py` and +`test_policy_lifecycle_postgresql.py` against real PostgreSQL; mock locks or an +in-memory database do not satisfy the contract. + +```bash +cd backend && .venv/bin/ruff check app/modules/contributions app/modules/compensation/api app/modules/compensation/policy_binding_service.py app/adapters/contributions tests/contributions +cd backend && .venv/bin/python -m pytest -q tests/contributions/test_policy_publication_authorization.py tests/contributions/test_policy_routes_absent.py tests/contributions/test_policy_publish.py tests/contributions/test_policy_publication_recovery.py tests/contributions/test_policy_retire.py tests/architecture/test_module_boundaries.py tests/test_alembic.py +cd backend && .venv/bin/python -m pytest -q tests/contributions --cov=app.modules.contributions --cov-report=term-missing --cov-fail-under=90 +cd backend && .venv/bin/python -m scripts.module_boundaries validate --protected-base +cd backend && .venv/bin/python -m scripts.test_structure_boundary validate --policy ../.agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/TEST_STRUCTURE_POLICY.md --ledger ../.agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/TEST_STRUCTURE_DEBT.json +python3 scripts/check_active_state_projections.py +python3 scripts/check_chunk_state_sync.py --base-ref +python3 scripts/check_markdown_links.py +git diff --check +``` + +Hosted CI additionally runs +`tests/contributions/test_policy_publication_concurrency.py` and +`tests/contributions/test_policy_publication_cross_project_postgresql.py` and +`tests/contributions/test_policy_lifecycle_postgresql.py` with real PostgreSQL, +then owns complete semantic-lane and repository aggregate coverage proof. + +## Required reviewers + +Architecture, security/auth, product/operations, QA, test-delta, CI integrity, +senior engineering, reuse/dedup, and documentation. + +## Human review focus and stop conditions + +Confirm server-owned publication truth, complete lock order, PREP-before-effect, +immutable history, and no activation/downstream behavior. Stop and amend if a +new action, permission, lifecycle state, foreign write, or compatibility path +is required. diff --git a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/reviews/WS-ARCH-001-CP04-external-review-response.md b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/reviews/WS-ARCH-001-CP04-external-review-response.md new file mode 100644 index 000000000..53aa6d8de --- /dev/null +++ b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/reviews/WS-ARCH-001-CP04-external-review-response.md @@ -0,0 +1,42 @@ +# WS-ARCH-001-CP04 External Review Response + +## Comments addressed + +- `EXT-CP04-001` High: review evidence named `445944a` after the PR head moved to + `769e15e`. Valid. The committed evidence and trust bundle now label the old + result historical and require fresh exact-head reviewer mirrors in the PR + body. +- `EXT-CP04-002` High: CP04A/CP04B verification used broad pytest commands + without criterion-to-test ownership. Valid. Both contracts now map each + security/product criterion to named future test modules and distinguish local + proof from hosted-only PostgreSQL/concurrency proof. +- `CR-CP04-001` Low: `DISCOVERY.md` summarized publication as starting with + aggregate locks even though the executable contracts fence the operation and + check immutable recovery first. Valid. The summary now states the exact + fence/recovery-before-lock/PREP order and preserves no-second-effect recovery. +- `EXT-CP04-003` High: CP04B required cross-project publish/retire denial but + did not name future proof for policy, version, unit, and adapter-binding + publish mismatches or both policy and exact-current-version retire targets. + Valid. CP04B now names focused concealed-denial/no-effect tests for those + command-specific facts and a separate hosted-only PostgreSQL + transaction/row-custody module. + +## Comments deferred + +None. + +## Human decisions needed + +None beyond normal approval and merge ownership. + +## Commands rerun + +Final-head state, wording, Markdown-link, diff, affected upgraded internal +reviews, hosted CI, and thread-aware external-review checks must be rerun after +this correction. + +## Remaining risks + +CodeRabbit has not yet supplied a fresh substantive final-head review. Future +CP04A/CP04B implementation must satisfy the named test matrices; this planning +correction does not itself prove runtime behavior. diff --git a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/reviews/WS-ARCH-001-CP04-plan-review-evidence.md b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/reviews/WS-ARCH-001-CP04-plan-review-evidence.md new file mode 100644 index 000000000..1b8e0fe2b --- /dev/null +++ b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/reviews/WS-ARCH-001-CP04-plan-review-evidence.md @@ -0,0 +1,71 @@ +# WS-ARCH-001-CP04 Plan Review Evidence + +## Evidence status + +historical — not current approval evidence + +This record describes the earlier planning review at `445944a`. Main was later +merged into the PR branch, producing `769e15e` and invalidating exact-head +freshness. It must not be used as current reviewer approval. Fresh reviewer +receipts remain private advisory-session evidence under the upgraded protocol; +the PR body may mirror their verdicts only when it names the exact reviewed +head. + +## Reviewed target + +- Base and merge-base: `66814dc749ba1353f03efc9453b3204a456b7bee` +- Reviewed planning head: `445944a29107d844c4f4cf6020525c026334375d` +- Worktree: clean at every final reviewer start and end snapshot + +## Reviewed intent + +Replace the combined CP04 skeleton with two executable, current-main contracts +without activating ContributionPolicy authority or adding product routes. + +```text +CP04A hidden read/create/update-draft behavior and shared recovery custody +-> CP04B hidden publish/retire behavior +-> CP05 exact AUTH activation +``` + +## Findings resolved + +- Restored canonical planned merge-state projections for CP04, CP04A, and CP04B. +- Kept `ProjectCompensationUnit` owned and locked by CONTRIBUTIONS while exposing + only COMPENSATION-owned adapter-binding facts through a public owner port. +- Added a PROJECTS-owned transaction-held policy-project eligibility port. +- Narrowed all private composition to exact owner adapter roots. +- Defined one immutable operation-event/result shape for duplicate recovery. +- Defined replacement publication as one atomic `published` event whose prior + version identity and actor/time also provide exact retirement attribution. +- Added exact CP04B verification commands and focused 90 percent coverage proof. +- Reconciled ARCH, AUTH, CON, current-state, handoff, and roadmap sequencing. + +## Historical reviewer results + +| Track | Historical result at `445944a` | Remaining blocker at that head | +|---|---|---| +| Architecture | pass | none | +| Security / authorization | pass | none | +| Product / operations | pass | none | +| QA | pass | none | +| Test delta | pass | none | +| CI integrity | pass | none | +| Senior engineering | pass | none | +| Reuse / dedup | pass | none | +| Documentation | pass | none | + +## Deterministic evidence + +- active-state projection check: pass; +- atomic chunk-state synchronization: pass; +- stale authorization wording scan: pass; +- stale Workstream wording scan: pass; +- changed Markdown links: pass; +- `git diff --check`: pass. + +These historical results do not authorize merge. This planning change adds no +runtime code, migration, action activation, +evaluator, grant, route, worker, policy mutation, guide binding, task behavior, +review behavior, ContributionRecord, award, fulfillment, delivery, or +reputation behavior. diff --git a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/reviews/WS-ARCH-001-CP04-pr-trust-bundle.md b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/reviews/WS-ARCH-001-CP04-pr-trust-bundle.md new file mode 100644 index 000000000..a5436c253 --- /dev/null +++ b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/reviews/WS-ARCH-001-CP04-pr-trust-bundle.md @@ -0,0 +1,139 @@ +# WS-ARCH-001-CP04 Planning PR Trust Bundle + +## Chunk + +`WS-ARCH-001-CP04` planning split into executable future contracts CP04A and +CP04B. + +## Goal + +Produce bounded executable contracts for ContributionPolicy behavior before any +implementation starts. + +## Human-approved intent + +Establish only the minimum ContributionPolicy foundation needed before returning +to task readiness and canonical `allow_review`; do not implement the wider CON +lifecycle in this initiative. + +## Scope + +- Keep CP04 as a planned non-executable coordination parent. +- Add CP04A for the CONTRIBUTIONS public API, hidden read/create/update-draft + behavior, owner ports, and shared durable operation recovery. +- Add CP04B for hidden publish/retire behavior against locked server-owned graph + facts and immutable lifecycle evidence. +- Keep all five ContributionPolicy actions unavailable until CP05. +- Reconcile current ARCH, AUTH, CON, handoff, status, and roadmap records. + +## What changed + +CP04A now owns hidden policy read/create/update-draft behavior and shared +operation recovery. CP04B owns irreversible publish/retire behavior. Both +contracts name exact owner boundaries, transaction ordering, acceptance tests, +and hosted-only PostgreSQL/concurrency proof. + +## Why it changed + +The former single CP04 skeleton mixed editable draft behavior with irreversible +publication. The split bounds review and implementation risk while retaining one +linear path to CP05 activation. + +## Design chosen + +`CP04A -> CP04B -> CP05`, with PROJECTS retaining project eligibility, +CONTRIBUTIONS retaining policy/unit truth, COMPENSATION retaining binding truth, +and opaque AUTH PREP consumed before product mutation. + +## Alternatives rejected + +- One combined implementation PR: too broad across editable and irreversible behavior. +- Caller-supplied publication truth: unsafe against stale or forged economic facts. +- Private cross-module imports or a second AUTH protocol: violates the modular boundary. + +## Non-goals + +No runtime implementation, migration, route, Celery job, AUTH activation, +ProjectGuide mutation, task/assignment/submission behavior, review behavior, +ContributionRecord, CompensationAward, fulfillment, callback, delivery, or +reputation behavior is added. + +## Product behavior + +None becomes live in this planning PR. All five policy actions remain +unavailable and no route or worker is added. + +## Key safety decisions + +- Every mutation fences `operation_id` before owner locks or AUTH consumption. +- PROJECTS retains project eligibility; CONTRIBUTIONS retains policy and unit + truth; COMPENSATION retains adapter-binding truth. +- PREP is opaque, transaction-bound, closed before product mutation, and never + serialized. +- Publication facts are recomputed from locked server-owned rows. +- Replacement publication preserves old content and frozen downstream lineage, + with exact prior-version retirement attribution in one immutable event. +- Retirement is terminal; no compatibility resurrection path exists. + +## Acceptance criteria proof + +The CP04A and CP04B contracts include criterion-to-test matrices for PREP +atomicity, concealed recovery, route absence, concurrency, immutable events, +cross-project publish/retire denial without lifecycle or AUTH side effects, +replacement publication, and terminal retirement. PostgreSQL-only proof is +explicitly assigned to hosted semantic lanes while named focused denial tests +remain runnable locally. + +## Tests/checks run + +Deterministic state, wording, Markdown-link, and diff checks are required on the +final head. Hosted CI owns the repository-wide exact-head gates. + +## Test delta + +Planning only; no runtime tests are added yet. The future test inventory is +explicit in both executable contracts, with one primary behavior per test and +no new file reaching 500 lines. + +## CI integrity + +No CI workflow or threshold is weakened. Full hosted lanes and aggregate +coverage remain mandatory. + +## Reviewer results + +The earlier nine-reviewer result at `445944a29107d844c4f4cf6020525c026334375d` +is historical because main was merged afterward. Fresh exact-head results must +be mirrored in the PR body after all upgraded reviewers complete; this committed +bundle does not claim current reviewer approval. + +## External review + +Fresh substantive review of PR head `769e15e0c6d947d471e626a2362c8adfdf9df53f` +found stale review evidence and missing acceptance-to-test mappings. A later +review found the missing CP04B cross-project proof mapping, and CodeRabbit found +the publication-order summary drift. All four findings were replayed as valid +and addressed in the contract, discovery record, and external-review response. +CodeRabbit substantive final-head review remains unavailable unless it reviews +the resulting final head. + +## Remaining risks + +Future implementation must prove the named PostgreSQL races and direct-SQL +guards; planning text alone is not runtime evidence. + +## Follow-up work + +After human merge, implement CP04A only. CP04B follows after CP04A merges; CP05 +alone activates the five actions. + +## Human review focus + +Confirm the CP04A/CP04B split, owner boundaries, operation/PREP ordering, +replacement-publication audit semantics, absence of routes and activation, and +the linear `CP04A -> CP04B -> CP05` dependency. + +## Human merge ownership + +Only an authorized human may merge this planning PR. CP04A implementation must +not begin until this plan merges. diff --git a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/CHUNK_MAP.md b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/CHUNK_MAP.md index fe6190c78..abe30625f 100644 --- a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/CHUNK_MAP.md +++ b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/CHUNK_MAP.md @@ -18,7 +18,7 @@ may proceed concurrently; open pull requests show transient ownership. ## Chunks `WS-ARCH-001/CHUNK_MAP.md` owns the ordered cross-module sequence -`WS-ARCH-001-CP01A -> CP01B -> CP01C -> CP02 -> CP03A -> CP03B -> CP04 -> CP05`; the AUTH entries below +`WS-ARCH-001-CP01A -> CP01B -> CP01C -> CP02 -> CP03A -> CP03B -> CP04A -> CP04B -> CP05`; the AUTH entries below project only AUTH-owned registration and activation responsibilities from that sequence. @@ -31,7 +31,7 @@ sequence. | `WS-ARCH-001-CP03` | Adapter-binding activation parent | L1 | Split into CP03A/CP03B; non-executable | | `WS-ARCH-001-CP03A` | Adapter target identity and owner eligibility prerequisite | L1 | Merged through PR #340; actions remain unavailable | | `WS-ARCH-001-CP03B` | Exact Finance Authority adapter-binding activation | L1 | Complete; four exact hidden actions active only for covered human Finance Authority | -| `WS-ARCH-001-CP05` | Exact ContributionPolicy activation | L1 | Proposed after merged CP04 hidden proof | +| `WS-ARCH-001-CP05` | Exact ContributionPolicy activation | L1 | Proposed after merged CP04A/CP04B hidden proof | | `WS-AUTH-001-PLAN` | Authorization Service Planning | L0 | Merged through PR #91 as `ad6d644` | | `WS-AUTH-001-01` | Adopt Authorization Baseline And Repository Contracts | L1 | Merged through PR #93 as `772af1d` | | `WS-AUTH-001-02` | Verified Issuer Token And JWKS Boundary | L1 | Merged through PR #107 as `060b780` | diff --git a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/STATUS.md b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/STATUS.md index c98ebf5b7..bc769bc1f 100644 --- a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/STATUS.md +++ b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/STATUS.md @@ -50,7 +50,7 @@ not current start requirements. CP03A is merged through PR #340 with only the target identity and owner eligibility while actions remain unavailable; CP03B is complete and activates only CP02's four exact Finance Authority boundaries. CP05 later activates - only CP04's merged hidden policy behavior. Fulfillment callback authority + only CP04A/CP04B's merged hidden policy behavior. Fulfillment callback authority remains separate and cannot be bundled into adapter-binding registration. Open pull requests are the transient-work view. This status page does not name diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/AUTHORIZATION_HANDOFF.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/AUTHORIZATION_HANDOFF.md index 24d88c050..c0152724c 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/AUTHORIZATION_HANDOFF.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/AUTHORIZATION_HANDOFF.md @@ -48,7 +48,7 @@ protocol and one caller-owned commit. | `CP01A` binding registration | exact binding actions, typed contexts, custody and permission mapping; retirement/callback/fulfillment excluded | register unavailable first | | `CP01B` policy registration | exact `contribution.policy.*` actions, typed contexts, custody and permission mapping | register unavailable after CP01A and before hidden services | | `CP03A/CP03B` binding prerequisite/activation | exact adapter target identity and owner eligibility, then exact CP02-proven binding actions only | keep unavailable through CP03A; activate in CP03B | -| `CP05` policy activation | exact CP04-proven policy actions only | activate after hidden proof | +| `CP05` policy activation | exact CP04A/CP04B-proven policy actions only | activate after both hidden proofs | | `CP06-CP08` validation and owner persistence | existing guide activation authority; later TASK readiness/claim authority remains TASK/AUTH-owned | CON validates only; PROJECT/TASK own writes | | `06` former review-claim lookup | none | planned retirement; REV copies the admitted Submission's immutable attempt version, verifies Task/Assignment only for equality, and performs no CON/current-policy lookup | | `07` review decision participant | existing planned `review.decision` contract | REV owns composition/commit; AUTH later activates | @@ -89,7 +89,7 @@ CP01C corrects binding identity and lifecycle-generation facts before CP02. CP02 is merged with hidden CON behavior. CP03A installs the exact target identity and owner eligibility without activation; CP03B is complete and activates only the four exact CP02 Finance Authority boundaries. CP05 later -activates only CP04's hidden proof. Before CON +activates only CP04A/CP04B's merged hidden proof. Before CON `02B`, AUTH must deliver the complete dispatcher identity/admission/action contract. That later dispatcher work must not delay the persistence and transaction-participant foundations now needed by REV. 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 45a39aa90..a1ec5b927 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 @@ -64,7 +64,7 @@ PLAN4 -> 02C ----------------------------------> REV-04B REV-04B + 03B -> 03C -> 03D -CP01A -> CP01B -> CP01C -> CP02 -> CP03A -> CP03B -> CP04 -> CP05 -> CP06 -> CP07 -> CP08 +CP01A -> CP01B -> CP01C -> CP02 -> CP03A -> CP03B -> CP04A -> CP04B -> CP05 -> CP06 -> CP07 -> CP08 CP08 -> WS-ARCH-001-03A/03B replacement behavior -> WS-ARCH-001-03C activation -> CP09 task-locked policy lineage -> assignment -> Submission-stamped attempt lineage -> allow_review -> ReviewLease REV revision lineage + 03C/03D + CP06/CP08 -> 07 -> REV-10 first Review commit 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 8865ae312..e69f4f62f 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 @@ -86,8 +86,8 @@ historical-row backfill or compatibility behavior. immutable lifecycle history while all four AUTH actions remain unavailable. CP03A is merged through PR #340 with target identity and owner eligibility while actions remain unavailable. CP03B completes Finance Authority activation. - CP04-CP05 - remain non-executable policy behavior/activation skeletons. + CP04 is a non-executable split parent; CP04A and CP04B are executable policy + behavior contracts. CP05 remains the non-executable activation skeleton. - CP06-CP09: validation, owner schema lineage, and clean legacy removal wait for the preceding public behavior. No historical-row classification is required unless current-main discovery proves real deployed data exists. @@ -119,8 +119,7 @@ CP08/ARCH-03B replacement path. ## Immediate next action CON-02C merged through PR #277. REV-04B may consume its shared lifecycle-audit -participant after REV's earlier gates merge. Prepare CP04's executable hidden -ContributionPolicy behavior contract. CP03B keeps adapter-binding behavior -hidden and route-unreachable while activating only its four covered Finance -Authority actions. +participant after REV's earlier gates merge. Implement CP04A's hidden +ContributionPolicy read/create/update-draft behavior, then CP04B's hidden +publish/retire behavior. All five policy actions remain unavailable until CP05. Open pull requests determine transient CON work. diff --git a/docs/roadmap_status.md b/docs/roadmap_status.md index d99ae0eaa..237097986 100644 --- a/docs/roadmap_status.md +++ b/docs/roadmap_status.md @@ -139,8 +139,9 @@ review. Their presence does not change the implemented-on-`main` list above. route-unreachable adapter-binding behavior and immutable lifecycle history. CP03A is complete with the target identity and owner eligibility. CP03B is complete with exact hidden Finance Authority read/PREP - activation for those four actions. The remaining order is CP04 hidden ContributionPolicy behavior, - then CP05 ContributionPolicy activation; + activation for those four actions. CP04 is a non-executable split parent. + The remaining order is CP04A hidden read/create/update-draft behavior, + CP04B hidden publish/retire behavior, then CP05 ContributionPolicy activation; expose CON validation; then bind one exact published, complete, binding-valid ContributionPolicyVersion at guide activation, and lock it on each task before that task becomes claimable. TaskAssignment