docs(xint): split policy persistence and activation

.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-12D2-guide-bound-policy-mutations.md

@@ -15,18 +15,22 @@ Add separately authorized routes for review and revision policy records after
 
 This contract is reconciled with REV-03P by WS-XINT-003-01. REV owns the
 immutable/versioned policy semantics; AUTH owns the mutation authorization,
-PREP consumption, and decision evidence. Chunk WS-XINT-003-02 implements the
-single path below; neither parent contract may build an alternate writer.
+PREP consumption, and decision evidence. XINT-003-02A first adopts inactive
+append-only persistence and removes the unused legacy paths; 02B implements and
+activates the single path below. Neither parent contract may build an alternate
+writer.
 
 ## One writer path
 
-- Surviving API: separate `PUT /projects/{project_id}/review-policy` and
-  `PUT /projects/{project_id}/revision-policy` routes in
-  `backend/app/modules/projects/router.py`, each declaring its exact primary
-  ActionId.
-- Surviving service: new `ProjectPolicyMutationService` methods
+- Surviving API in 02B: separate
+  `PUT /projects/{project_id}/guides/{guide_id}/review-policy` and
+  `PUT /projects/{project_id}/guides/{guide_id}/revision-policy` routes in
+  `backend/app/modules/projects/policy_mutation_router.py`, each declaring its
+  exact primary ActionId.
+- Surviving service in 02B: new `ProjectPolicyMutationService` methods
   `replace_review_policy()` and `replace_revision_policy()`.
-- Surviving repository: new append-only
+- Surviving repository primitives introduced inactive in 02A and consumed only
+  by 02B: append-only
   `ProjectRepository.add_review_policy_version()` and
   `ProjectRepository.add_revision_policy_version()` methods over the existing
   `ReviewPolicy` and `RevisionPolicy` tables/models, upgraded as necessary for
@@ -37,6 +41,8 @@ single path below; neither parent contract may build an alternate writer.
   `ProjectService._revision_policy_model()`.
 - No compatibility route, alias, second model/table, fallback constructor, or
   dual repository path survives.
+- Replay custody is the generalized project-mutation ledger shared with guide
+  mutations; a policy-only or in-memory replay path is forbidden.
 
 Policies may be appended or replaced only while the exact guide version is a
 draft. Activation freezes the selected policy versions: active-guide policy
@@ -61,7 +67,11 @@ P1
 ```text
 backend/app/modules/projects/models.py
 backend/app/modules/projects/repository.py
-backend/app/modules/projects/router.py
+backend/app/modules/projects/policy_mutation_router.py
+backend/app/modules/projects/policy_mutation_service.py
+backend/app/modules/projects/project_mutation_repository.py
+backend/app/modules/projects/guide_mutation_repository.py
+backend/app/modules/projects/guide_mutation_service.py
 backend/app/modules/projects/schemas.py
 backend/app/modules/projects/service.py
 backend/app/modules/projects/authorization_reads.py

.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/CHUNK_MAP.md

@@ -1,7 +1,8 @@
 # Chunk Map: WS-REV-001 Review And Revision Lifecycle
 
-REV-03P is reconciled into WS-XINT-003-02 and is not an independent policy
-writer. AUTH activation follows the exact XINT-003 waves.
+REV-03P is reconciled into WS-XINT-003-02A persistence and 02B mutation
+activation and is not an independent policy writer. AUTH activation follows the
+exact XINT-003 waves.
 
 ## Rule
 
@@ -27,9 +28,9 @@ typed symbol/manifest, and tests.
 | `WS-REV-001-02B` | Locked Review Policy And Dormant Task Lifecycle Compatibility | L1 | Historical | Superseded; any upstream gap is reported to its owner |
 | `WS-REV-001-02C` | Submission Attribution, Context, And Immutable Lineage | L1 | Historical | Superseded as an ownership chunk; REV consumes owner-supplied Submission lineage |
 | `WS-REV-001-PLAN3` | Allow-Review Boundary Reset | L1 | Historical | Merged boundary correction |
-| `WS-REV-001-03P` | Review And Revision Policy Persistence | L1 | Reconciled into `WS-XINT-003-02` | Planning input only; never executable independently |
+| `WS-REV-001-03P` | Review And Revision Policy Persistence | L1 | Reconciled into `WS-XINT-003-02A` and `02B` | Planning input only; never executable independently |
 | `WS-REV-001-03` | Review Queue And Lease Persistence | L1 | PLAN3 | Non-executable split record |
-| `WS-REV-001-03A` | Queue And Lease Base Persistence | L1 | merged `WS-XINT-003-02`; exact `allow_review`, Submission/artifact, and actor handoffs | Proposed contract; requires current-main refresh and explicit user request |
+| `WS-REV-001-03A` | Queue And Lease Base Persistence | L1 | merged `WS-XINT-003-02B`; exact `allow_review`, Submission/artifact, and actor handoffs | Proposed contract; requires current-main refresh and explicit user request |
 | `WS-REV-001-03B` | Normalized Review Packet Manifest Persistence | L1 | 03A; exact ART packet-membership owner chunk merged | Proposed; owner chunk unscheduled |
 | `WS-REV-001-04` | Review Chain Persistence | L1 | 03B | Non-executable split record |
 | `WS-REV-001-04A` | Immutable Review Chain And Decision Request Persistence | L1 | 03B; current actor constraints | Proposed; no contract yet |
@@ -76,7 +77,7 @@ typed symbol/manifest, and tests.
 
 ```text
 PLAN -> 01 -> 02(parent) -> PLAN2 -> 02A(historical, superseded)
--> PLAN3(boundary reset) -> WS-XINT-003-02 (03P planning input)
+-> PLAN3(boundary reset) -> WS-XINT-003-02A -> WS-XINT-003-02B (03P planning input)
 -> 03(parent) -> 03A -> 03B
 -> 04(parent) -> 04A -> 04B
 -> 05(parent) -> 05A -> 05B
@@ -129,6 +130,6 @@ configuration, or coverage changes add CI integrity.
 ## Stop condition
 
 PLAN3 is complete. Never resume 02A, 02A1, 02A2, 02A3, 02A4, 02B, or 02C as
-REV implementation. Policy work proceeds only through `WS-XINT-003-02`; later
-REV feature chunks require current-main contract refresh and an explicit user
-request under the ordinary engineering loop.
+REV implementation. Policy work proceeds only through `WS-XINT-003-02A` and
+then `WS-XINT-003-02B`; later REV feature chunks require current-main contract
+refresh and an explicit user request under the ordinary engineering loop.

.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/STATUS.md

@@ -15,9 +15,9 @@ them. The attempted 02A1 runtime candidate was reverted in full.
 
 `WS-REV-001-PLAN3` is merged historical planning. It retires
 02A/02A1/02A2/02A3/02A4/02B/02C as REV implementation authorization. The first
-future policy work is the reconciled WS-XINT-003-02 writer cutover; 03P is not
-an independent implementation path. Work starts through the repository's
-ordinary intent/plan/bounded-change loop after an explicit user request.
+future policy work is reconciled WS-XINT-003-02A persistence adoption followed
+by 02B prepared writer activation; 03P is not an independent implementation
+path. Work follows the repository's ordinary intent/plan/bounded-change loop.
 
 The historical text below records the superseded PLAN2/02A state and is not
 current implementation authority. Trusted main at that time was `44f2467c`, which additionally
@@ -109,8 +109,8 @@ start statement in it is void under D28 and PLAN3.
 
 ## Human-owned gates
 
-- Implement policy work only through reconciled WS-XINT-003-02 after its
-  current-main contract review and an explicit user request.
+- Implement policy work only through reconciled WS-XINT-003-02A and 02B, one
+  reviewed PR at a time. Do not begin 02B automatically after 02A.
 - Start 03A only after 03P and after its current-main refresh proves every exact
   `allow_review`, Submission, artifact, and reviewer owner handoff.
 - Exact human Review revision-round counting, deadline anchor, and boundary

.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-03P-review-revision-policy-persistence.md

@@ -2,8 +2,9 @@
 
 ## Status
 
-Reconciled planning input to `WS-XINT-003-02`. It is not an independent
-implementation path.
+Reconciled planning input to `WS-XINT-003-02A` and `02B`. It is not an
+independent implementation path. PR #195 is preservation evidence only and
+must not merge its historical migration or writer architecture.
 
 ## Goal
 
@@ -12,7 +13,8 @@ later routing, lease, decision, and human revision behavior.
 
 REV owns field semantics, version identity, draft/active immutability, and the
 facts later lifecycle code consumes. AUTH-12D2 owns authority, PREP, evidence,
-and the only mutation surface. The shared implementation is XINT-003-02.
+and the only mutation surface. The shared implementation is XINT-003-02A for
+inactive persistence adoption and 02B for the sole authorized writer.
 
 ## Canonical persistence path
 
@@ -39,9 +41,9 @@ L1: policy immutability, duration/limit semantics, and later decision authority.
 
 ## Allowed files
 
-The exact current-main project models, migration, policy schemas, canonical
-writer service/repository, AUTH PREP integration, focused tests, and initiative
-evidence must be fixed in the refreshed XINT-003-02 contract.
+Exact files are fixed separately in the reviewed XINT-003-02A and 02B child
+contracts. 02A owns current-head migration and inactive append-only persistence;
+02B owns AUTH PREP integration and the only public writer.
 
 ## Not allowed
 
@@ -77,5 +79,5 @@ reuse/dedup, docs, test-delta, and CI integrity.
 
 ## Stop
 
-Do not implement this parent contract independently. Refresh and implement only
-WS-XINT-003-02 after an explicit user request.
+Do not implement this parent contract independently. Implement only one reviewed
+XINT-003-02 child at a time, beginning with 02A, and stop after each PR.

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

@@ -6,8 +6,8 @@ This table is the planning source of truth for the v0.1 review and human-revisio
 
 | ActionId | PermissionId | Principal and scope | Resource family | Surface owner | State | Activation wave |
 |---|---|---|---|---|---|---|
-| `project.review_policy.update` | `project.review_policy.manage` | Project Manager grant for exact project | draft guide + ReviewPolicy version | project/REV semantics; AUTH mutation | registered planned | `WS-XINT-003-02` |
-| `project.revision_policy.update` | `project.review_policy.manage` | Project Manager grant for exact project | draft guide + RevisionPolicy version | project/REV semantics; AUTH mutation | registered planned | `WS-XINT-003-02` |
+| `project.review_policy.update` | `project.review_policy.manage` | Project Manager grant for exact project | exact draft guide + ReviewPolicy version | project/REV semantics; AUTH mutation | registered planned | persistence prerequisite `02A`; activation `WS-XINT-003-02B` |
+| `project.revision_policy.update` | `project.review_policy.manage` | Project Manager grant for exact project | exact draft guide + RevisionPolicy version | project/REV semantics; AUTH mutation | registered planned | persistence prerequisite `02A`; activation `WS-XINT-003-02B` |
 | `review.queue.read` | `review.queue.read` | reviewer grant; exact project; self-review denied | concealed current-work view | REV | registered planned | `WS-XINT-003-03A` |
 | `review.claim` | `review.claim` | reviewer grant; exact project; self-review denied | queue entry + global reviewer lease state | REV | registered planned | `WS-XINT-003-03A` |
 | `review.release` | `review.release` | owning reviewer and active lease | ReviewLease | REV | registered planned | `WS-XINT-003-03A` |
@@ -64,8 +64,8 @@ These actions are not XINT-003 custody. Generic artifact download, adjudication,
 
 | ActionId | Exact prerequisite behavior/manifest |
 |---|---|
-| `project.review_policy.update` | existing policy records plus refreshed REV-03P/AUTH-12D2 contract; implemented only by `WS-XINT-003-02` |
-| `project.revision_policy.update` | existing policy records plus refreshed REV-03P/AUTH-12D2 contract; implemented only by `WS-XINT-003-02` |
+| `project.review_policy.update` | merged inactive `WS-XINT-003-02A` persistence; implemented and activated only by `WS-XINT-003-02B` |
+| `project.revision_policy.update` | merged inactive `WS-XINT-003-02A` persistence; implemented and activated only by `WS-XINT-003-02B` |
 | `review.queue.read` | merged hidden REV-05 concealed current-work view |
 | `review.claim` | merged hidden REV-05 queue admission and REV-06 atomic lease behavior |
 | `review.release` | merged hidden REV-06 lease release behavior |

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

@@ -3,8 +3,10 @@
 | Chunk | Purpose | Risk | Dependency |
 |---|---|---|---|
 | `WS-XINT-003-01` | Reconcile policy ownership, complete REV catalogue, permissions, surfaces, resource families, and fixed-service matrix while actions stay planned. | L1 | approved plan |
-| `WS-XINT-003-02` | Join REV policy semantics/persistence to AUTH-12D2 prepared policy mutation cutover and remove duplicate writer paths. | L1 | 01 plus refreshed REV-03P/AUTH-12D2 |
-| `WS-XINT-003-03A` | Activate concealed reviewer current-work plus claim/release/preference with exact project grant, self-review denial, global lease limit, and atomic lease/packet-manifest freeze. | L1 | 02 plus hidden REV queue/lease behavior |
+| `WS-XINT-003-02` | Non-executable split record joining REV policy persistence to AUTH mutation custody. | L1 | 01 plus refreshed REV-03P/AUTH-12D2 |
+| `WS-XINT-003-02A` | Adopt immutable/versioned REV policy persistence on the current migration head and remove the four dead legacy writer/construction callables; activate nothing. | L1 | 01 and current-main persistence review |
+| `WS-XINT-003-02B` | Add the sole policy mutation service/routes, consume AUTH PREP, append immutable policy versions, record decision evidence atomically, and activate only the two policy actions. | L1 | merged 02A |
+| `WS-XINT-003-03A` | Activate concealed reviewer current-work plus claim/release/preference with exact project grant, self-review denial, global lease limit, and atomic lease/packet-manifest freeze. | L1 | merged 02B plus hidden REV queue/lease behavior |
 | `WS-XINT-003-03B` | Activate preference and lease expiry fixed services only. | L1 | 03A plus hidden timer behavior |
 | `WS-XINT-003-04` | Activate human `review.context.read` and reviewer finding evidence while consuming XINT-002-07A's ART-only packet/materialization/binding capability. | L1 | 03B plus hidden REV packet/evidence manifests and XINT-002-07A |
 | `WS-XINT-003-05` | Activate only bounded `review.chain.read`, consuming the active REV context and XINT-002 packet/materialization boundary. | L1 | 04 plus merged XINT-002-07A |
@@ -15,7 +17,8 @@
 | `WS-XINT-003-08B` | Activate both identities for the single `review.reconcile.run` ActionId together, plus artifact-reference, projection, and lifecycle-control surfaces. | L1 | 08A plus hidden REV jobs/projection/control |
 | `WS-XINT-003-09` | Prove end-to-end least privilege, revocation, replay, concurrency, atomicity, artifact isolation, and coherent route release. | L1 | 02-08B |
 
-Chunks 02 through 09 are planning skeletons, not implementation-ready contracts,
+Chunk 02B and chunks 03A through 09 are planning skeletons, not
+implementation-ready contracts,
 until refreshed on current main with exact allowed files and commands. Each row
 maps to one PR unless its current-main contract is split into smaller
 children before implementation. A split cannot add a new permission, action,

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

@@ -43,3 +43,11 @@
     reconciled REV-03P/AUTH-12D2 contracts.
 17. XINT-002-07A is the only review-evidence binding availability transition;
     07B adds response-slot evaluator shape without changing availability.
+18. XINT-003-02 is split into 02A persistence adoption and 02B prepared mutation
+    activation. 02A is merge-safe because the four retired callables have no
+    current-main call sites and both ActionIds remain planned. 02B is the only
+    external writer and policy-action availability transition.
+19. PR #195 is preservation evidence, not a merge base or authorization source.
+    Valid policy semantics and PostgreSQL proofs must be recreated from current
+    head 0045; its historical 0034 migration, old writer path, merge intent, and
+    signed-start records are not adopted.

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

@@ -12,8 +12,9 @@
 
 ## Baseline
 
-Discovery was performed from `origin/main` merge `99dc0b34`, after AUTH-12D.
-This initiative begins read-only and changes no application behavior.
+Initial discovery was performed from `origin/main` merge `99dc0b34`, after
+AUTH-12D. The 02 refresh re-ran discovery at merge `ad8da7e5`, after PRs #236
+and #237. This refresh changes planning only and no application behavior.
 
 ## Current implementation and plans
 
@@ -30,6 +31,21 @@ This initiative begins read-only and changes no application behavior.
   `service.py` contain existing `ReviewPolicy` and `RevisionPolicy` behavior.
   `backend/app/modules/projects/authorization_reads.py` locks and composes these
   policies into current project authorization facts.
+- Current Alembic head is `0045_guide_metadata_authority`; the old PR #195
+  migration descended from historical head 0033 and is preservation input, not
+  a mergeable migration.
+- `ProjectRepository.upsert_review_policy()`,
+  `upsert_revision_policy()`, `ProjectService._review_policy_model()`, and
+  `_revision_policy_model()` remain in current code but have no call sites.
+  Their removal is therefore a clean-cut deletion, not a compatibility break.
+- `ActionId.PROJECT_REVIEW_POLICY_UPDATE` and
+  `PROJECT_REVISION_POLICY_UPDATE`, their catalogue mappings, and their strict
+  typed resource contexts already exist. Both actions remain planned and the
+  PREP service does not yet accept them.
+- `GuideMutationService` and `guide_mutation_router.py` provide the current
+  project-scoped PREP/idempotency/decision-evidence composition convention.
+  Policy mutation must reuse that convention without turning guide mutation
+  into a generic service locator or retaining a second writer path.
 - AUTH-12D2 proposes separate review-policy and revision-policy mutation routes.
   REV-03P also proposes policy persistence. This is an ownership collision:
   there must be one persistence model and one mutation path.
@@ -153,6 +169,9 @@ needs a closed typed context with only its valid shape.
 ## Dependencies
 
 - AUTH-12D2 and REV-03P must be reconciled before either policy writer is built.
+- The reconciled implementation is split: 02A can merge because it activates
+  no route/action and removes only unused mutation callables; 02B is the only
+  action-availability and external-writer transition.
 - REV hidden feature chunks must merge before matching AUTH action activation.
 - XINT-002 remains the sole activation owner for ART review-artifact actions and
   shared human-review submission actions. WS-XINT-003-01 split the combined