diff --git a/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/CHUNK_MAP.md b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/CHUNK_MAP.md new file mode 100644 index 000000000..8d358dd19 --- /dev/null +++ b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/CHUNK_MAP.md @@ -0,0 +1,23 @@ +# Chunk Map: WS-XINT-003 REV-AUTH End-to-End Contract + +| 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-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 | +| `WS-XINT-003-06` | Activate `review.decision` only for the hidden atomic Review/FinalAcceptance/CON composition. | L1 | 05 plus REV decision and merged CON participant | +| `WS-XINT-003-07` | Activate human contributor response evidence; coordinate XINT-002-05D shared revision submission and XINT-002-07B ART-only response binding. | L1 | 06 plus REV revision behavior and XINT-002 owner waves | +| `WS-XINT-003-08R` | Register four missing privileged recovery/lifecycle ActionIds as planned with complete catalogue/migration parity; activate nothing. | L1 | 07 plus exact hidden-feature registration manifests | +| `WS-XINT-003-08A` | Activate Project Manager and Operator queue/revision recovery commands with exact scope and reasons. | L1 | 08R plus hidden REV recovery behavior | +| `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, +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, +principal class, service identity, or authorization protocol without returning +to planning. diff --git a/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/DECISIONS.md b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/DECISIONS.md new file mode 100644 index 000000000..11654b177 --- /dev/null +++ b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/DECISIONS.md @@ -0,0 +1,39 @@ +# Decisions: WS-XINT-003 REV-AUTH End-to-End Contract + +1. REV owns lifecycle meaning and persistence; AUTH owns authority evaluation, + PREP custody/consumption, and decision evidence. +2. Existing review/revision policy persistence is reconciled once. REV-03P and + AUTH-12D2 may not create duplicate models, routes, or writer services. +3. Queue visibility does not imply claim authority; claim does not imply packet + or decision authority without the exact active lease. +4. Reviewer authority requires the exact project reviewer grant and denies + self-review. Submitter/adjudicator/admin roles do not substitute. +5. `review.context.read` and `review.chain.read` expose bounded lease-scoped + facts. Neither grants generic artifact or historical-byte access. +6. Finding evidence, response evidence, and ART byte binding are separate + actions with separate human/service principals. Reviewer finding evidence + may activate before decision; contributor response evidence activates only + after `needs_revision` creates the exact obligation and preparation. +7. `review.decision` activates only after Review, findings/resolutions, + FinalAcceptance when accepting, Task/Assignment effects, CON records, audit, + and outbox are one fail-closed transaction. +8. Human Review revision and checker remediation remain separate closed + contexts even when they share submission preparation/create actions. +9. Project Managers repair only covered-project revision state; Operators use + distinct reason-bound recovery actions and never receive reviewer authority. +10. Both reconciliation identities share one ActionId and therefore one + activation wave; their server-derived modes and scopes remain distinct. +11. Each fixed service command has a closed identity/action matrix. Prepared handles + never enter Celery payloads. +12. XINT-002 retains sole custody of ART review actions and shared submission + preparation/create activation. XINT-003 owns activation of the human REV + context, finding, response, chain, and lifecycle actions. +13. WS-XINT-003-01 transfers the 19 registered planned REV action rows from the + historical placeholder AUTH-REV groups into one canonical planning custody + table and its waves without changing runtime `ActionOwner`, permissions, or + availability in 01. Runtime owner evidence changes only in each refreshed + activation chunk. XINT-002-owned rows are excluded from that transfer. +14. Registration/planning does not activate product behavior. Final route + release waits for complete conformance. +15. Obsolete signed-start, active-chunk, and merge-intent language in historical + REV planning does not govern current work under `AGENTS.md`. diff --git a/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/DISCOVERY.md b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/DISCOVERY.md new file mode 100644 index 000000000..9c8179d4f --- /dev/null +++ b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/DISCOVERY.md @@ -0,0 +1,191 @@ +# Discovery: WS-XINT-003 REV-AUTH End-to-End Contract + +## Canonical references + +- [Review lifecycle specification](../../../docs/spec_review_lifecycle.md) +- [Authorization service specification](../../../docs/spec_authorization_service.md) +- [Roles and permissions](../../../docs/operations_roles_permissions.md) +- [XINT-002 human-review revision owner](../WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-05D-human-review-revision.md) +- [XINT-002 review artifact owner](../WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-07-review-artifact-activation.md) + +## Baseline + +Discovery was performed from `origin/main` merge `99dc0b34`, after AUTH-12D. +This initiative begins read-only and changes no application behavior. + +## Current implementation and plans + +- `backend/app/modules/authorization/catalogue.py` already declares the review + queue, claim, release, preference, context, chain, evidence, decision, + registered recovery/reconciliation/projection, and ART review actions. The + four privileged lifecycle/recovery actions named below remain absent until + the availability-neutral 08R registration wave. +- Migrations `0018`, `0021`, `0022`, `0023`, `0036`, and `0041` contain + historical permission/action evidence and planned service mappings. Current + availability and exact migration parity must be derived, never copied from + historical counts in REV documents. +- `backend/app/modules/projects/models.py`, `schemas.py`, `repository.py`, and + `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. +- 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. +- `WS-REV-001` defines hidden behavior from durable final/current checker + `allow_review` admission through queue, lease, packet context, immutable + decisions/findings/resolutions, human revision preparation, contribution + integration, recovery, projection, and final release. +- `WS-XINT-002` owns `artifact.review_packet.materialize`, + `artifact.review_evidence.binding.create`, and human-review revision artifact + preparation/Submission binding. REV-AUTH must consume those exact merged + manifests rather than duplicate them. + +## Principal classes + +### Human reviewer + +Requires an active canonical human ActorProfile, active identity link, exact +project `reviewer` grant, no self-review conflict, and—after claim—one exact +active lease. Reviewer authority never comes from submitter/adjudicator grants, +an AdminRoleGrant alone, token roles, or queue visibility. + +### Contributor in human revision + +Requires an active exact-project submitter grant, active/replacement assignment, +the exact immutable human Review-rooted revision obligation and preparation +head/digest, predecessor Submission, required finding responses/evidence, +unexpired deadline, and remaining revision round. Checker remediation is a +separate CheckerRun-rooted variant. + +### Project Manager and Operator + +Project Managers configure policy and perform only exact covered-project repair +or obligation closure actions. Operators inspect bounded operational state and +perform explicitly reasoned recovery actions; they receive no reviewer decision +or artifact-read authority. + +### Fixed services + +Preference expiry, lease expiry, authority-invalidation reconciliation, general +review reconciliation, artifact-reference reconciliation, projection rebuild, +ART packet materialization, and ART evidence binding use separately admitted +fixed service identities and closed action matrices. A Celery payload carries +identifiers and provenance only, never a prepared handle or executable human +authority. + +## Canonical action inventory to reconcile + +Human reviewer actions: + +- `review.queue.read` +- `review.claim` +- `review.release` +- `review.decline_preference` +- `review.context.read` +- `review.chain.read` +- `review.finding_evidence.ingest` +- `review.decision` + +Contributor revision action: + +- `review.finding_response_evidence.ingest` +- shared XINT-002 `artifact.submission_bundle.prepare` and `submission.create` + with the closed human-review revision context + +Project Manager actions: + +- `project.review_policy.update` +- `project.revision_policy.update` +- `review.revision_context.repair` +- `review.revision_obligation.close` + +Operator/administrative actions: + +- `review.queue.inspect` +- `review.lease.force_release` +- `review.queue.routing.override` +- `review.queue.routing.correct` +- `review.queue.close` +- `review.revision_context.legacy_close` +- `review.lifecycle.activation.manage` + +Fixed-service actions: + +- `review.preference_expiry.run` +- `review.lease_expiry.run` +- `review.reconcile.run` with two separately admitted identities where the + product contract requires separate invalidation and general reconciliation +- `review.artifact_reference.reconcile` +- `review.projection.rebuild` +- XINT-002 `artifact.review_packet.materialize` +- XINT-002 `artifact.review_evidence.binding.create` + +## Required resource facts + +The union of typed feature-owned contexts includes actor and identity link, +project and exact role grant, task, assignment, finalized Submission and +predecessor, final/current CheckerRun admission, queue entry, preference, +ReviewLease and frozen policies, packet manifest and verified bindings, +predecessor Review, findings/responses/resolutions, decision request, revision +obligation and preparation head/digest, deadline/round, guide and policy +versions, lifecycle phase, operation/idempotency/request digest, session/root +transaction, and fixed-service identity where applicable. + +No single omnibus nullable context should represent every action. Each action +needs a closed typed context with only its valid shape. + +## Existing tests and gaps + +- `backend/tests/test_authorization.py` proves planned catalogue presence and + some role/service matrices, but not the complete live REV transaction chain. +- REV planning calls for PostgreSQL immutability, concurrency, replay, lease, + and decision/CON tests; most runtime modules and tests do not exist yet. +- XINT-002 covers artifact-side activation contracts but cannot prove reviewer + lease or revision-obligation semantics before REV implements them. +- Missing end-to-end proof includes self-review races, lease expiry versus + decision, revocation versus decision, stale packet/version, finding evidence + binding versus decision, predecessor advancement, revision deadline/round + exhaustion, replacement contributor authority, and recovery-vs-live-command + crossings. + +## Dependencies + +- AUTH-12D2 and REV-03P must be reconciled before either policy writer is built. +- 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. Its current combined review-artifact contract must split + response-evidence activation after the human revision obligation exists. +- CON atomic participant and FinalAcceptance integration must merge before + `review.decision` activation. +- Final product routes remain absent until the complete dependency conformance + wave passes. + +## Risks discovered + +- The current REV plan contains obsolete signed-start and generated-loop gates + contrary to current `AGENTS.md`; those statements are process history, not + implementation blockers. +- Historical action counts and owner chunk names are stale after many AUTH/ART + migrations and cannot be used as exact implementation inputs. +- `review.finding_evidence.ingest -> review.decision` and + `review.finding_response_evidence.ingest -> submission.create` share + permissions but remain distinct actions and resource shapes. +- `review.reconcile.run` serves separate fixed identities but has one global + ActionId availability. Both identities therefore remain planned until one + shared activation wave; service identity still determines server-derived mode + and scope after activation. +- `review.revision_context.repair`, `review.revision_context.legacy_close`, + `review.revision_obligation.close`, and `review.lifecycle.activation.manage` + are approved manifests but are absent from the current closed catalogue. They + require an availability-neutral registration wave before activation. + +## Unknowns to resolve at each activation wave + +- Exact merged feature symbol/manifest and migration head at chunk start. +- Whether one existing policy table can be cleanly adopted as immutable + versioned REV policy without schema replacement. +- Exact bounded fields for queue inspection and chain/context reads. +- Exact service identity names and provisioning state on then-current main. + +These are implementation-time evidence questions, not reasons to place product +lifecycle logic in AUTH. diff --git a/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/INTENT.md b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/INTENT.md new file mode 100644 index 000000000..9fb264c2d --- /dev/null +++ b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/INTENT.md @@ -0,0 +1,92 @@ +# Intent: WS-XINT-003 REV-AUTH End-to-End Contract + +## Problem being solved + +Review and revision authority is currently described across `WS-REV-001`, +`WS-AUTH-001`, and `WS-XINT-002`. The individual declarations do not yet form +one reviewed, executable chain from review-policy configuration through queue +admission, lease-scoped judgment, revision submission, recovery, and release. + +## Why this work matters + +Review decisions determine whether entrusted contributor work is accepted, +returned for revision, or rejected. A missing or over-broad authorization seam +could expose submission artifacts, permit self-review, accept a stale decision, +erase a revision obligation, or attribute judgment to the wrong actor. + +## Current behavior + +- Project review and revision policy tables already exist. +- AUTH has planned action and permission rows for most REV operations; none of + the review lifecycle actions is a complete active product surface. +- REV planning defines queue, lease, immutable Review/finding/resolution, + revision preparation, FinalAcceptance, recovery, and release behavior. +- XINT-002 separately owns artifact review-packet materialization, evidence + binding, and human-review submission-artifact preparation. +- REV-03P and AUTH-12D2 currently overlap in how policy persistence and mutation + cutover are described and must be reconciled before implementation. + +## Target behavior + +Every review or revision operation uses one registered ActionId, one exact +human or fixed-service principal, a feature-owned canonical resource context, +and the existing opaque transaction-bound prepared-authorization protocol. +Authority is revalidated after final locks and decision evidence commits in the +same transaction as the protected mutation. No generic artifact read, inherited +uploader authority, token role, serialized handle, or independent REV-local +authorization path exists. + +## Design chosen + +Create one cross-initiative contract that inventories the complete surface, +settles ownership, and sequences narrow activation waves behind merged hidden +REV, ART, Task/Submission/Checker, and CON behavior. Registration remains +separate from activation and product route release. + +## Alternatives considered + +- Continue adding AUTH requirements to individual REV chunks: rejected because + it repeats the ART-AUTH dependency failure and makes omissions likely. +- Put lifecycle rules in AUTH: rejected because AUTH evaluates authority and + must not own Review, lease, finding, policy, revision, or contribution state. +- Let REV query grants directly: rejected because it creates a second policy + engine and bypasses canonical denial evidence and revocation behavior. + +## Boundaries preserved + +- REV owns review/revision product semantics and canonical lifecycle rows. +- AUTH owns identity, permissions, candidates, evaluation, PREP custody, and + authorization evidence. +- ART owns verified bytes, review packet materialization, and evidence binding. +- Task/Submission/Checker owners supply exact upstream and resubmission facts. +- CON owns contribution rules and conditional award persistence. +- The request route or service command owns the transaction and commits once. + +## Expected risks + +Self-review, stale leases, cross-project access, predecessor advancement, +revision-limit bypass, generic artifact access, service impersonation, +duplicate policy writers, partial decision/contribution commits, replay, and +operator recovery broadening. + +## What must not change + +- Stored Review decisions remain exactly `accept`, `needs_revision`, `reject`. +- Checker-caused `needs_revision` remains distinct from human Review revision. +- No adjudication, reputation mutation, frontend, or generic artifact-download + authority is added. +- No compatibility path is retained for old token-role or local authorization. + +## How this will be proven + +Catalogue and surface parity, PostgreSQL concurrency and immutability tests, +crossed revocation/staleness races, exact-handle denial matrices, atomic +decision/CON rollback tests, fixed-service all-pairs denial, artifact access +tests, API contract drills, at least 90 percent changed-subsystem coverage, and +the hosted repository-wide coverage floor. + +## Human decisions required + +No new product decision is required to plan the dependency. Before runtime +implementation, the human must approve the reconciled chunk sequence and any +change to existing REV policy semantics. diff --git a/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/PLAN.md b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/PLAN.md new file mode 100644 index 000000000..8db94fa4d --- /dev/null +++ b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/PLAN.md @@ -0,0 +1,108 @@ +# Plan: WS-XINT-003 REV-AUTH End-to-End Contract + +## Approach + +Deliver one reconciliation foundation followed by narrow feature-backed +activation waves: + +1. Reconcile policy ownership, the complete catalogue, permissions, principal + classes, fixed-service matrix, surface manifests, and planned availability. +2. Cut over review/revision policy configuration through one persistence path: + REV owns semantics; AUTH-12D2 owns authorization and PREP consumption. +3. Activate concealed reviewer current-work, claim/release/preference, and timer + services only after REV queue/lease behavior exists. +4. Amend XINT-002-07 into two ART-only owner waves: packet materialization and + reviewer-evidence binding after lease readiness, then response-evidence + binding only after a human revision obligation exists. XINT-003 activates + the corresponding human REV actions and never takes custody of ART actions. +5. Activate bounded `review.chain.read` after the packet/context owner wave. +6. Activate `review.decision` only after the complete hidden atomic + Review/FinalAcceptance/CON composition exists. +7. Let XINT-002-05D activate shared human-review revision preparation/Submission + actions and XINT-002-07B extend ART response binding. XINT-003 separately + activates contributor response authority against exact obligation facts. +8. Register the four missing privileged lifecycle/recovery actions as planned, + then activate Project Manager/Operator recovery and fixed service jobs with + reason-bound least privilege and crossed-race proof. +9. Run complete conformance, then permit REV's single product-route release. + +## Universal mutation protocol + +Every durable mutation follows this order: + +1. Verify the external token and resolve canonical actor/identity link, or + resolve one fixed admitted service identity. +2. Perform cheap preflight authority before sensitive bytes or expensive work. +3. Prepare an opaque, non-serializable handle in the caller-owned root + transaction, bound to actor/service, identity link where human, ActionId, + request digest, idempotency key, session, and root transaction. +4. Lock AUTH authority first, then feature idempotency/lifecycle rows in the + action's documented order. +5. Recompose exact current feature facts using typed feature-owned loaders. +6. Consume the handle once against the final resource context and stage bounded + decision evidence. +7. Apply the protected REV/Task/Submission/CON/audit/outbox mutation and commit + once. Provider I/O and projection occur only after commit where applicable. + +Copied, serialized, forged, replayed, wrong-session, wrong-transaction, +wrong-action, wrong-actor/service, cross-project, cross-task, cross-submission, +cross-lease, cross-review, stale-policy, stale-packet, stale-predecessor, expired, +revoked, or already-consumed capabilities fail closed with no partial product +mutation. + +## Read protocol + +Reads still evaluate current authority and canonical feature scope. +Administrative queue-inspection lists filter before counts/cursors. Reviewer +context and chain reads require the exact +active lease and disclose only bounded metadata plus the current packet. +Historical artifact bytes are not implied by chain visibility. Reauthorization +is required before returning a replayed mutation result. + +## Ownership model + +- AUTH code contains no REV repositories or lifecycle branching. +- REV code contains no grant queries, token-role checks, or alternate policy + evaluator. +- Typed feature contexts are composed beside their owning repositories and + presented to AUTH through the established authorization interfaces. +- ART services execute byte materialization/binding under their own authority; + they do not inherit reviewer, contributor, or uploader authority. +- CON participates flush-only in the caller transaction and never authorizes + the reviewer. + +## Policy ownership reconciliation + +The existing policy persistence is adopted or migrated once; it is not +duplicated. REV-03P defines immutable/versioned policy semantics and validation. +AUTH-12D2 protects the two mutation routes and supplies authorization evidence. +The implementing chunk must explicitly retire overlapping legacy writer paths +and update both contracts together. + +## Verification strategy + +- exact catalogue/permission/action/matrix and route/command parity; +- migration single-head, upgrade, downgrade/refusal, and direct-SQL proof; +- PostgreSQL concurrency barriers for every crossed authority/lifecycle race; +- property/table-driven prepared-handle denial matrices; +- atomic Review/FinalAcceptance/CON/audit/outbox fault injection; +- all-pairs fixed-service denial and Celery serialization scans; +- bounded read/redaction/concealment tests; +- focused coverage at or above 90 percent for changed subsystems; +- GitHub-hosted full suite preserving the repository-wide 78 percent floor; +- architecture, security, product/ops, QA, senior, reuse, docs, test-delta, and + CI-integrity reviews as applicable. + +## Alternatives rejected + +Separate per-REV-chunk AUTH invention, direct REV grant reads, a generic review +resource context, a generic artifact download permission, and activation before +hidden behavior are rejected. + +## Stop boundary + +This planning amendment creates no runtime code and activates no action. Chunks +02 through 09 are non-implementable planning skeletons until a current-main +refresh replaces every file/command placeholder with exact boundaries and the +user explicitly requests that chunk. Planning complete does not start runtime +work. diff --git a/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/REVIEW_LOG.md b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/REVIEW_LOG.md new file mode 100644 index 000000000..f81b0ee3b --- /dev/null +++ b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/REVIEW_LOG.md @@ -0,0 +1,44 @@ +# Review Log: WS-XINT-003 REV-AUTH End-to-End Contract + +## Initial review round + +Architecture, security, product/ops, QA, and senior engineering returned FAIL; +docs returned PASS WITH CONDITIONS. Valid findings were: + +- duplicate custody of XINT-002 packet/evidence and revision submission actions; +- response evidence incorrectly sequenced before human revision preparation; +- four privileged actions lacked a registration-only wave; +- two services sharing `review.reconcile.run` were split across activation; +- reviewer current-work and atomic packet-manifest semantics were incomplete; +- contributor Task Context, checker remediation, lifecycle recovery, and + contribution/award conformance proof were incomplete; +- future planning skeletons were not clearly marked non-implementable; and +- canonical AUTH/role docs and links were missing from reconciliation scope. + +The draft was revised to address every item. A second focused review round is +required before the planning PR is considered ready. + +## Final review round + +- Architecture: PASS after the human-REV versus XINT-002 ART/shared-submission + custody split, 08R registration seam, and single `review.reconcile.run` wave. +- Security: PASS WITH LOW RISKS; the response-evidence lifecycle order and + privileged registration gaps are resolved. Its informational discovery + wording note was corrected. +- Product/ops: PASS WITH LOW RISKS; reviewer current-work, atomic packet + manifest, contributor Task Context, checker remediation, CON source integrity, + and shutdown/crash/reactivation proof are explicit. Its low wording note was + corrected. +- QA: PASS WITH LOW RISKS; dependencies, global ActionId activation, 08R, denial + proof, and non-implementable skeleton labeling are testable. Its informational + XINT-002 wording note was corrected. +- Senior engineering: PASS WITH LOW RISKS; planning custody versus runtime owner + evidence and XINT-002 boundaries are explicit. Its low wording note was + corrected. +- Docs: PASS; canonical docs scope, links, terminology, and current process + wording are aligned. + +No reviewer finding remains open. + +External CI and CodeRabbit results belong to the planning PR trust bundle and +external-review response. diff --git a/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/RISKS.md b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/RISKS.md new file mode 100644 index 000000000..ab710bbdc --- /dev/null +++ b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/RISKS.md @@ -0,0 +1,19 @@ +# Risks: WS-XINT-003 REV-AUTH End-to-End Contract + +| Risk | Severity | Control | +|---|---|---| +| Duplicate REV/AUTH policy writers | Critical | Reconcile REV-03P and AUTH-12D2 before runtime work; one persistence path. | +| Self-review or wrong-project review | Critical | Exact reviewer grant, contributor conflict check, project/task/submission binding, final revalidation. | +| Queue read becomes decision authority | Critical | Separate actions and progressively stronger queue, lease, packet, evidence, and decision contexts. | +| Stale/expired/revoked lease commits judgment | Critical | AUTH-first lock plus final lease/grant/actor/link recomposition and crossed races. | +| Reviewer receives generic artifact access | Critical | Exact packet manifest and fixed materializer action; no download permission. | +| Evidence bytes are bound under human authority | Critical | Separate human ingest and fixed ART binding capabilities committed with exact evidence lineage. | +| Partial Review/CON/Task state | Critical | One transaction, ordered flush-only CON participant, exhaustive fault injection. | +| Human revision bypasses findings/deadline/round | Critical | Exact obligation/preparation/predecessor locks and closed revision context. | +| Checker remediation is mistaken for human Review revision | Critical | Separate CheckerRun-rooted context and mutually exclusive persisted source. | +| Operator recovery broadens product authority | Critical | Distinct reason-bound actions, bounded reads, no decision/artifact authority. | +| Service identities collapse into a catch-all service | Critical | Closed enums, constraints, static matrices, provisioning, admission, all-pairs denial. | +| Serialized prepared authority is replayed by Celery | Critical | Opaque non-serializable handles and static payload scanners/tests. | +| Activation precedes hidden feature readiness | Critical | Planned-by-default catalogue and exact merged feature manifest gates. | +| Historical counts/contracts are treated as current | High | Derive parity from current migrations/catalogue at every chunk start. | +| One PR becomes unreviewable | High | Narrow activation waves and explicit allowed/not-allowed files per chunk. | diff --git a/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/STATUS.md b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/STATUS.md new file mode 100644 index 000000000..ec987abb9 --- /dev/null +++ b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/STATUS.md @@ -0,0 +1,27 @@ +# Status: WS-XINT-003 REV-AUTH End-to-End Contract + +## Current status + +Planning complete after focused internal review. No runtime code or action +availability is changed. + +## Baseline + +- Planning branch began from `origin/main` at `99dc0b34` after AUTH-12D merged. +- Existing REV actions remain planned/unreleased as product surfaces. +- XINT-002 remains the owner of review artifact materialization/binding and + human-review submission-artifact activation. + +## Main finding + +REV-03P and AUTH-12D2 overlap around review/revision policy persistence and +mutation. The first implementation wave must settle one persistence path: +REV-owned semantics with AUTH-owned mutation authorization. + +## Next step + +Open and review the planning PR. Do not implement `WS-XINT-003-01` until the +planning PR merges and the user explicitly requests that chunk from a refreshed +current-main contract. + +Planning complete. Awaiting human approval before implementation. diff --git a/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-01-contract-reconciliation.md b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-01-contract-reconciliation.md new file mode 100644 index 000000000..851ef46d9 --- /dev/null +++ b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-01-contract-reconciliation.md @@ -0,0 +1,91 @@ +# Chunk Contract: WS-XINT-003-01 — REV-AUTH Contract Reconciliation + +## Status + +Proposed. Do not implement until the user explicitly requests it from current +main. Activates no action. + +## Goal + +Reconcile the complete review/revision authorization catalogue and settle the +REV-03P/AUTH-12D2 policy ownership collision before runtime implementation. + +## Risk class + +L1 authorization and product-policy architecture. + +## Allowed files + +```text +.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/** +.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/{PLAN,CHUNK_MAP,STATUS,DECISIONS,RISKS}.md +.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-12D2-guide-bound-policy-mutations.md +.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/ACTIVATION_CUSTODY.md +.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/{PLAN,CHUNK_MAP,STATUS,DECISIONS,RISKS}.md +.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-03P-review-revision-policy-persistence.md +.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/CHUNK_MAP.md +.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-05D-human-review-revision.md +.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-07-review-artifact-activation.md +docs/operations_authorization_service.md +docs/spec_authorization_service.md +docs/spec_review_lifecycle.md +docs/operations_roles_permissions.md +``` + +## Not allowed + +```text +backend application code +Alembic migrations +action activation or service provisioning +review/revision product behavior +compatibility aliases or duplicate policy paths +``` + +## Acceptance criteria + +- One canonical table enumerates every human, Project Manager, Operator, and + fixed-service action, permission, principal, resource family, surface owner, + hidden-feature dependency, and activation wave. +- The table classifies every action as registered planned, missing-to-register, + externally owned by XINT-002, or out of scope; canonical AUTH and role docs + are updated or explicitly confirmed. +- The 19 registered planned REV rows move from historical placeholder AUTH-REV + activation groups to exact XINT-003 waves in the planning custody table + without any permission, availability, catalogue `ActionOwner`, or runtime + change in 01. Each refreshed activation chunk updates its runtime owner + evidence together with activation. XINT-002-owned ART materialization/binding + and shared submission-artifact rows remain with XINT-002. +- REV-03P owns immutable/versioned policy semantics and AUTH-12D2 owns mutation + authorization; both contracts name one persistence and writer path. +- Historical counts and signed-start/process-gate language are corrected where + they could misdirect current implementation. +- XINT-002 artifact/revision boundaries are referenced by exact existing chunk + IDs and are not duplicated. XINT-002-07 is split so response evidence cannot + activate before the human revision obligation exists. +- The XINT-002 split is ART-only: it owns packet materialization, evidence + binding, and shared submission-artifact actions. Human REV action activation + remains in the XINT-003 waves. +- Every later activation remains planned and fail closed. + +## Verification commands + +```bash +python3 scripts/check_stale_workstream_wording.py +python3 scripts/check_markdown_links.py +git diff --check +``` + +## Required reviewers + +Architecture, security/auth, product/ops, QA/test, senior engineering, docs, +and reuse/dedup. + +## Human review focus + +Confirm complete action coverage, one policy owner/writer path, correct +cross-initiative ownership, and absence of premature activation. + +## Stop condition + +Merge the contract reconciliation and stop. Do not begin policy runtime work. diff --git a/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-02-policy-mutation-activation.md b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-02-policy-mutation-activation.md new file mode 100644 index 000000000..4eef0b96b --- /dev/null +++ b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-02-policy-mutation-activation.md @@ -0,0 +1,52 @@ +# Chunk Contract: WS-XINT-003-02 — Review And Revision Policy Mutation Activation + +## Status + +Non-implementable planning skeleton after 01. Before implementation, refresh on +current main with exact allowed files and commands, then require an explicit +user request for this chunk. + +## Goal + +Implement one immutable/versioned policy persistence path and authorize the two +covered-project policy mutation routes through the existing PREP protocol. + +## Risk class + +L1 policy and authorization mutation. + +## Allowed files + +Must be enumerated exactly at current-main start. Only policy-owned project/REV +models, repository/service/routes, AUTH typed contexts/catalogue parity, +migration, focused tests, docs, and this initiative's evidence may be included. + +## Not allowed + +Queue, lease, Review, finding, revision execution, artifact, CON, adjudication, +reputation, frontend, duplicate policy tables, or legacy writer compatibility. + +## Acceptance criteria + +- Only a covered Project Manager with the exact project grant may update the + review or revision policy for that project and guide lineage. +- The actions remain distinct: `project.review_policy.update` and + `project.revision_policy.update`. +- Final PREP consumption binds actor/link/grant, project, guide/version, + existing/reserved policy identity, operation, request digest, idempotency, + session, transaction, and server-validated policy facts. +- Cross-project, stale guide, wrong policy/action, revoked, replayed, copied, or + concurrent changed requests deny with no policy/audit partial state. +- The previous embedded or duplicate writer path is removed without backward + compatibility. +- No review lifecycle action is activated. + +## Verification + +Focused PostgreSQL policy/authorization/migration/concurrency tests, Ruff, +90-percent changed-subsystem coverage, hosted full coverage, API contract proof, +and all required L1 reviewers. + +## Stop condition + +Merge and stop before queue/lease activation. diff --git a/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-03A-reviewer-lease-activation.md b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-03A-reviewer-lease-activation.md new file mode 100644 index 000000000..8e13201fe --- /dev/null +++ b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-03A-reviewer-lease-activation.md @@ -0,0 +1,49 @@ +# Chunk Contract: WS-XINT-003-03A — Reviewer Queue And Lease Activation + +## Status and risk + +Non-implementable planning skeleton after 02. Refresh exact files and commands +on current main before an explicit user request. L1 reviewer authority and concurrency. + +## Goal + +Activate concealed reviewer current-work through `review.queue.read`, plus +`review.claim`, `review.release`, and `review.decline_preference` against merged +hidden REV queue/lease behavior. + +## Allowed files + +Enumerate exact REV queue/lease, AUTH context/composer/catalogue parity, migration, +route, test, documentation, and evidence files at current-main start. + +## Not allowed + +Decision, finding, artifact byte, revision submission, contribution, recovery, +or lifecycle-release behavior; issuer role claims or direct grant queries in REV. + +## Acceptance criteria + +- Reviewer current-work returns exactly the active lease, one server-selected + offer, or none. It never exposes the backlog. It requires an active exact- + project reviewer grant and conceals self-authored submissions. +- Claim locks AUTH authority, queue, submission contributor lineage, preference, + and reviewer global lease state before atomically creating exactly one lease, + one immutable `ReviewPacketManifest`, and freezing exact review/contribution + policy facts. The manifest binds queue, lease, Submission, final/current + CheckerRun/results, stamped context, and verified ART bindings. +- One reviewer holds at most one active lease globally and one submission has at + most one active lease; crossed claims have one winner. +- Release and preference decline require the owning active lease/reviewer and + are idempotent without rewriting history. +- Revocation, suspension, wrong project/role, self-review, stale queue, copied + handle, and replay deny with no lease mutation. + +## Verification and reviewers + +PostgreSQL concurrency, PREP denial, concealment, route parity, focused +90-percent coverage, hosted full coverage; architecture, security, product/ops, +QA, senior, reuse, docs, test-delta, and CI-integrity review. + +## Stop + +Merge and stop before timer/service activation. diff --git a/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-03B-lease-service-activation.md b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-03B-lease-service-activation.md new file mode 100644 index 000000000..692bdffc5 --- /dev/null +++ b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-03B-lease-service-activation.md @@ -0,0 +1,42 @@ +# Chunk Contract: WS-XINT-003-03B — Lease Timer Services + +## Status and risk + +Non-implementable planning skeleton after 03A. Refresh exact files and commands +on current main before an explicit user request. L1 fixed-service authority. + +## Goal + +Activate only `review.preference_expiry.run` and `review.lease_expiry.run`. +Both `review.reconcile.run` identities remain planned until 08B. + +## Allowed files + +Enumerate exact REV timer commands, Celery command registration, AUTH +service identity/matrix/context parity, migration, tests, docs, and evidence at +current-main start. + +## Not allowed + +Generic scheduler identity, serialized prepared handles, human authority in job +payloads, decision/revision behavior, or manual Operator execution of fixed services. + +## Acceptance criteria + +- Each command runs only as its separately admitted fixed service identity with + exact action membership and canonical row scope. +- Payloads contain identifiers/provenance only; fixed services prepare fresh authority + and re-read current state inside a new transaction. +- Expiry versus claim/release/decision races have deterministic + lock order and exactly one valid terminal effect. +- Retry is idempotent and cross-service/action/lease/project requests deny. +- All-pairs identity denial and Celery registration/payload scans pass. + +## Verification and reviewers + +Focused service-command/PostgreSQL race/matrix tests, Ruff, coverage and hosted gates; +architecture, security, product/ops, QA, senior, CI, reuse, docs, test-delta. + +## Stop + +Merge and stop before packet/context reads. diff --git a/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-04-review-context-activation.md b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-04-review-context-activation.md new file mode 100644 index 000000000..e5f2630aa --- /dev/null +++ b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-04-review-context-activation.md @@ -0,0 +1,48 @@ +# Chunk Contract: WS-XINT-003-04 — Review Context And Finding Authority Activation + +## Status and risk + +Non-implementable planning skeleton after 03B. Refresh exact files and commands +on current main before an explicit user request. L1 confidential artifact access. + +## Goal + +Activate human `review.context.read` and `review.finding_evidence.ingest` against +the exact lease/packet/finding context. Amend XINT-002-07A to own only fixed +`artifact.review_packet.materialize` and reviewer-evidence binding. XINT-002-07B +remains ART-only and extends response binding after a human revision obligation +exists. + +## Allowed files + +Enumerate exact REV context/finding service, AUTH composers/activation parity, +XINT-002 ART-only contract amendments, routes, tests, canonical specs, docs, and +evidence files at current-main start. + +## Not allowed + +Contributor response authority, decision/revision implementation, XINT-003 +ownership of ART actions, XINT-002 ownership of human REV actions, or generic +artifact authority. + +## Acceptance criteria + +- Human reviewer context/finding authority is limited to the exact leased + Submission and canonical immutable packet manifest/bindings. +- Lease expiry/release/reassignment, actor/link/grant revocation, version drift, + packet replacement, cross-resource, and wrong service/action deny bytes. +- Materializer and binding services use separate fixed identities and cannot + claim, decide, submit, or inherit reviewer authority. +- The ART materializer/binder receives only its fixed-service actions. Future + 07B response evidence requires exact `Review(needs_revision)`, obligation, + preparation head/digest, contributor assignment, predecessor, response, + deadline, and round; CheckerRun remediation is ineligible. + +## Verification and reviewers + +PostgreSQL read/evidence races, PREP denial, ART service separation, coverage, +hosted gates, and full L1 reviewers. + +## Stop + +Merge and stop before chain-read activation. diff --git a/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-05-review-evidence-activation.md b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-05-review-evidence-activation.md new file mode 100644 index 000000000..524224f71 --- /dev/null +++ b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-05-review-evidence-activation.md @@ -0,0 +1,40 @@ +# Chunk Contract: WS-XINT-003-05 — Bounded Review Chain Read Activation + +## Status and risk + +Non-implementable planning skeleton after 04 and merged XINT-002-07A. Refresh +exact files and commands on current main before an explicit user request. L1 +confidential history access. + +## Goal + +Activate only `review.chain.read` for the exact active lease. Evidence and ART +binding actions remain owned by XINT-002-07A/07B. + +## Allowed files + +Enumerate exact REV chain-read service/repository, AUTH context/activation +parity, route, tests, docs, and evidence at current-main start. + +## Not allowed + +Generic artifact or historical-byte authority, evidence mutation, decision, +Submission creation, recovery, or unbounded reviewer backlog/history. + +## Acceptance criteria + +- Chain reads require the exact active lease/reviewer and disclose only bounded + relationship metadata for the leased task/Submission chain. +- Historical artifact bytes remain inaccessible unless independently present + in the current exact packet manifest. +- Expired/released/reassigned leases, revocation, cross-project/task/submission, + stale packet/version, wrong action, and replayed disclosure deny or conceal. + +## Verification and reviewers + +PostgreSQL read/race tests, concealment/redaction matrix, immutability, coverage +and hosted gates; full L1 reviewer set. + +## Stop + +Merge and stop before decision activation. diff --git a/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-06-review-decision-activation.md b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-06-review-decision-activation.md new file mode 100644 index 000000000..da68dd2b4 --- /dev/null +++ b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-06-review-decision-activation.md @@ -0,0 +1,52 @@ +# Chunk Contract: WS-XINT-003-06 — Atomic Review Decision Activation + +## Status and risk + +Non-implementable planning skeleton after 05. Refresh exact files and commands +on current main before an explicit user request. Requires merged hidden REV +decision plus CON participant. L1 +canonical judgment, contribution, and conditional-compensation integrity. + +## Goal + +Activate `review.decision` for exactly `accept`, `needs_revision`, or `reject`. + +## Allowed files + +Enumerate exact REV decision composition, AUTH final context/activation parity, +CON typed participant wiring, route, tests, docs, and evidence at start. CON may +only flush the typed facts prepared by REV/AUTH; it performs no authority +evaluation, decision, or lifecycle work. REV retains decision and lifecycle +ownership. + +## Not allowed + +New decision values, adjudication, reputation, generic artifact access, optional +CON participant, manual FinalAcceptance route, or post-commit canonical repair. + +## Acceptance criteria + +- Final PREP consumption binds reviewer/link/grant, lease/queue, project/task, + assignment, exact Submission and predecessor Review, frozen policies, packet + and evidence facts, decision/findings/resolutions, request/idempotency, session, + and transaction. +- Every decision appends immutable Review/finding/resolution history and exactly + one reviewer contribution. Accept alone creates FinalAcceptance, accepts the + Task/completes assignment, and creates submitter contribution. Needs revision + creates the exact initial human revision preparation. Reject creates neither + FinalAcceptance nor submitter contribution. +- Review, lifecycle effects, CON rows/awards, audit, and outbox commit once or + roll back together. The CON participant is flush-only and cannot authorize, + decide, advance lifecycle state, or commit independently. +- Decision versus expiry/revocation/evidence drift/duplicate request races are + deterministic and fail closed. + +## Verification and reviewers + +Exhaustive branch/fault-injection/concurrency/idempotency tests, 90-percent +coverage, hosted full suite; architecture, security, product/ops, QA, senior, +CON/payment-focused, reuse, docs, test-delta, CI integrity. + +## Stop + +Merge and stop before revision resubmission activation. diff --git a/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-07-human-revision-activation.md b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-07-human-revision-activation.md new file mode 100644 index 000000000..ed146944c --- /dev/null +++ b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-07-human-revision-activation.md @@ -0,0 +1,53 @@ +# Chunk Contract: WS-XINT-003-07 — Human Revision And Response Authority Activation + +## Status and risk + +Non-implementable planning skeleton after 06. Refresh exact files and commands +on current main before an explicit user request. L1 replacement Submission +authority and immutable predecessor lineage. + +## Goal + +Activate human `review.finding_response_evidence.ingest` against the exact +obligation/preparation. Coordinate XINT-002-05D as sole owner of shared artifact +preparation/`submission.create` and XINT-002-07B as sole owner of ART response +binding. XINT-002 owns no human REV action. + +## Allowed files + +Enumerate exact REV preparation/obligation, Task/Submission participant, AUTH +closed context, XINT-002 ART ports, routes, tests, docs, evidence at start. + +## Not allowed + +Checker-remediation conflation, guide/policy rebasing outside approved REV +rules, deadline/round bypass, mutable findings, synthetic Review, or a second +submission authorization protocol. + +## Acceptance criteria + +- Contributor Task Context read returns only the validated current preparation + head/digest and frozen or approved rebased context; it never falls back to a + stale or moving guide context. +- Authority binds the exact Review(needs_revision), unresolved blocking + findings, immutable responses/evidence, active preparation head/digest, + predecessor Submission, active/replacement assignment, project/task, locked + or approved rebased guide/policies, deadline, and remaining round. +- Predecessor advancement, preparation replacement, finding changes, + expiry/limit exhaustion, revocation, cross-project/task/submission, copied or + replayed handles deny without storage intent or provider I/O. +- Exactly one N+1 Submission consumes one preparation/obligation; concurrent + attempts have one winner and preserve all prior immutable history. +- Human and checker revision sources remain mutually exclusive. +- XINT-002-07B response evidence activates only after the obligation and + preparation exist and denies every CheckerRun-rooted remediation shape; this + statement refers to ART binding, while XINT-003 owns the human action. + +## Verification and reviewers + +Concurrency, predecessor/rebase/deadline/round/replacement-contributor matrices, +ART fault injection, coverage and hosted gates; full L1 reviewer set. + +## Stop + +Merge the coordination/activation evidence and stop before privileged recovery. diff --git a/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-08A-review-recovery-activation.md b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-08A-review-recovery-activation.md new file mode 100644 index 000000000..d8de05ff5 --- /dev/null +++ b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-08A-review-recovery-activation.md @@ -0,0 +1,45 @@ +# Chunk Contract: WS-XINT-003-08A — Human And Operator Recovery Activation + +## Status and risk + +Non-implementable planning skeleton after 08R. Refresh exact files and commands +on current main before an explicit user request. REV recovery behavior must +remain hidden. L1 privileged lifecycle recovery. + +## Goal + +Activate bounded queue inspection, force release, routing override/correction, +queue close, revision-context repair/legacy close, and revision-obligation close. + +## Allowed files + +Enumerate exact REV recovery commands, AUTH contexts/candidates, routes, audit, +tests, docs, migration parity, and evidence at current-main start. + +## Not allowed + +Operator review decisions, generic project or artifact authority, fabricated +Review/reject, history rewrite, silent repair, or broad recovery permission. + +## Acceptance criteria + +- Each command has its own ActionId, typed resource, exact Project Manager or + Operator candidate, canonical reason, idempotency, and bounded audit event. +- Covered Project Managers repair/close only their exact project and cannot use + Operator legacy/queue powers. Operators cannot decide reviews or mutate + ordinary project policy. +- Recovery locks and revalidates the exact stale/broken condition; live valid + commands win or conflict deterministically without dual effects. +- Reads conceal/redact before counts; mutations preserve immutable history and + never create synthetic judgment or contribution. +- No route or command exists until 08R's exact planned catalogue rows, + permission mappings, migration parity, and denial tests have merged. + +## Verification and reviewers + +Role/scope/reason matrices, crossed live-vs-recovery races, audit/redaction, +coverage/hosted gates; full L1 reviewer set. + +## Stop + +Merge and stop before remaining service activation. diff --git a/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-08B-review-service-activation.md b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-08B-review-service-activation.md new file mode 100644 index 000000000..df99be7e1 --- /dev/null +++ b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-08B-review-service-activation.md @@ -0,0 +1,48 @@ +# Chunk Contract: WS-XINT-003-08B — Review Service And Lifecycle Control Activation + +## Status and risk + +Non-implementable planning skeleton after 08A. Refresh exact files and commands +on current main before an explicit user request. REV jobs/projection/control +must remain hidden. L1 fixed-service and release-control authority. + +## Goal + +Activate the single `review.reconcile.run` ActionId once for both separately +admitted authority-invalidation and general reconciliation identities, plus +`review.artifact_reference.reconcile`, `review.projection.rebuild`, and +reason-bound `review.lifecycle.activation.manage`. + +## Allowed files + +Enumerate exact REV jobs/controller, Celery command registration, AUTH identity/matrix +and Operator context, migrations, tests, docs, evidence at start. + +## Not allowed + +Catch-all service, human authority in payloads, prepared-handle serialization, +canonical truth in projections, provider-specific access in REV, or route +release before conformance. + +## Acceptance criteria + +- Each fixed service uses its admitted identity and closed action membership; general + and invalidation reconciliation identities remain distinguishable. +- Jobs are batched, resumable, idempotent, and reauthorize each transaction. +- Projection/reconciliation never becomes canonical judgment and ART repair is + delegated through exact typed ports. +- Lifecycle control requires an Operator, exact phase/preconditions/reason, and + cannot bypass dependency readiness or drain/fence state. +- All-pairs denial, Celery payload/registration, crash/retry, and crossed + controller/job tests pass. +- No lifecycle-control command exists until 08R registers its exact planned + action with migration/catalogue parity. + +## Verification and reviewers + +Service-command/matrix/retry/control tests, coverage and hosted gates; architecture, +security, product/ops, QA, senior, CI, reuse, docs, test-delta. + +## Stop + +Merge and stop before end-to-end conformance/release. diff --git a/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-08R-lifecycle-action-registration.md b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-08R-lifecycle-action-registration.md new file mode 100644 index 000000000..1fbd16b7c --- /dev/null +++ b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-08R-lifecycle-action-registration.md @@ -0,0 +1,46 @@ +# Chunk Contract: WS-XINT-003-08R — Privileged Lifecycle Action Registration + +## Status and risk + +Non-implementable planning skeleton after 07. Refresh exact files and commands +on current main before an explicit user request. L1 privileged action catalogue. + +## Goal + +Register exactly four approved actions as planned and unavailable: +`review.revision_context.repair -> project.task.manage`, +`review.revision_obligation.close -> project.task.manage`, +`review.revision_context.legacy_close -> operations.reconcile.run`, and +`review.lifecycle.activation.manage -> operations.reconcile.run`. + +## Allowed files + +At current-main refresh, enumerate only AUTH catalogue/runtime resource types, +one then-current migration, authorization/migration tests, canonical AUTH/REV +docs, and initiative evidence. + +## Not allowed + +Action activation, routes, service commands, REV recovery/control behavior, new +PermissionIds, broad permission remapping, identities, or compatibility aliases. + +## Acceptance criteria + +- Exact ActionId enum, ActionDefinition owner/permission/planned availability, + typed closed resource context, SQL evidence parity, and docs are added for + only the four actions. +- Migration proves prior-head/fresh upgrade, single head, downgrade/re-upgrade, + protected-evidence refusal, and no existing mapping/availability drift. +- Candidates match reviewed manifests: covered Project Manager for repair and + obligation close; Operator for legacy close and lifecycle control. +- Static tests prove no route/command declares the actions and evaluation + remains unavailable. + +## Verification and reviewers + +Catalogue/runtime/migration/direct-SQL parity and denial tests, Ruff, focused +90-percent coverage, hosted full suite; full L1 reviewer set. + +## Stop + +Merge and stop before 08A activation. diff --git a/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-09-conformance-release.md b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-09-conformance-release.md new file mode 100644 index 000000000..1dcfff6f2 --- /dev/null +++ b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-09-conformance-release.md @@ -0,0 +1,54 @@ +# Chunk Contract: WS-XINT-003-09 — REV-AUTH Conformance And Release + +## Status and risk + +Non-implementable planning skeleton after 02 through 08B. Refresh exact files +and commands on current main before an explicit user request. L1 coherent +product release. + +## Goal + +Prove the complete review/revision authorization chain and permit REV's one +planned product-router release point without adding new behavior. + +## Allowed files + +Exact conformance/drill tests, route composition and manifests, release docs, +AUTH/REV status/evidence, and narrowly required defects found by the proof. + +## Not allowed + +New actions, permissions, roles, services, lifecycle states, compatibility +paths, feature expansion, adjudication, reputation, or unreviewed defect work. + +## Acceptance criteria + +- Static manifests prove every review/revision route and command has exactly one + active ActionId and every action has exactly its intended principal/surface. +- End-to-end drills cover policy configuration; checker admission; queue/claim; + packet/context; evidence; all three decisions; human revision N+1 and return; + distinct CheckerRun-rooted remediation that creates no Review, finding, + preparation, or reviewer contribution and returns through checker admission; + revocation/expiry/reassignment; Project Manager/Operator recovery; fixed-service + retry; projection; artifact outage/integrity failure; contribution/award + source integrity with no reputation side effect; controlled shutdown, drain, + crash resume, coherent reactivation; and lifecycle release. +- The universal mutation matrix proves forged, copied, replayed, and already- + consumed handles; wrong session, transaction, action, actor, or fixed service; + cross-project, task, Submission, lease, or Review; self-review and wrong role; + stale lease, packet, predecessor, preparation, or policy; expired or revoked + authority; and concurrent consumption all fail closed with no partial + product, CON, audit, or outbox state. +- No token-role, direct grant-query, generic artifact-read, serialized PREP, or + alternate authorization path remains. +- Hosted full coverage, per-subsystem floors, internal reviewers, CodeRabbit, + and GitHub checks pass on the exact head before human merge. + +## Verification and reviewers + +Complete hosted suite/API drills, stale scans, markdown links, migration-head +proof, all L1 internal reviewers, and external PR review. + +## Stop + +Human merge only. Do not begin a later initiative automatically. diff --git a/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/reviews/WS-XINT-003-PLAN-external-review-response.md b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/reviews/WS-XINT-003-PLAN-external-review-response.md new file mode 100644 index 000000000..5caf3e3bb --- /dev/null +++ b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/reviews/WS-XINT-003-PLAN-external-review-response.md @@ -0,0 +1,30 @@ +# External Review Response: WS-XINT-003 Planning + +## GitHub Actions + +The first Agent Gates run failed because +`scripts/check_stale_authorization_docs.py` found retired human-worker and +token-role wording. The failed reviewed artifact was head `44aa60a3` in Agent +Gates run [30663559758](https://github.com/Flow-Research/workstream/actions/runs/30663559758). +Commit `2c17bc36` replaced those phrases with exact fixed-service and issuer- +claim terminology. The scanner passed locally and replacement exact-head Agent +Gates run [30663651764](https://github.com/Flow-Research/workstream/actions/runs/30663651764) +passed on head `2c17bc36`. The final reviewed planning head `85c94f0e` then +passed Agent Gates run +[30663969053](https://github.com/Flow-Research/workstream/actions/runs/30663969053). + +## CodeRabbit + +CodeRabbit posted four actionable comments: + +1. Make CON's flush-only boundary explicit: accepted. The decision contract now + states CON only flushes typed REV/AUTH-prepared facts and performs no + authorization, decision, lifecycle, or independent commit. +2. Repair incomplete 08A/08B requirement sentences: accepted and corrected. +3. Replace retired worker vocabulary: accepted and already addressed by + `2c17bc36`. +4. Record the failed GitHub Actions gate rather than calling it pending: + accepted. The trust bundle now records the failure, correction, and + replacement Agent Gates pass separately from final Backend status. + +No CodeRabbit finding was dismissed or silenced. diff --git a/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/reviews/WS-XINT-003-PLAN-pr-trust-bundle.md b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/reviews/WS-XINT-003-PLAN-pr-trust-bundle.md new file mode 100644 index 000000000..2f512543f --- /dev/null +++ b/.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/reviews/WS-XINT-003-PLAN-pr-trust-bundle.md @@ -0,0 +1,113 @@ +# PR Trust Bundle: WS-XINT-003 Planning + +## Chunk + +`WS-XINT-003-PLAN` — REV-AUTH End-to-End Contract Planning. + +## Goal + +Define one fail-closed authorization chain for the complete human review and +revision lifecycle before implementing AUTH-12D2 or REV runtime behavior. + +## Human-approved intent + +The human requested the same end-to-end AUTH dependency review for REV that was +previously completed for ART, while preserving the existing ART-AUTH custody. + +## What changed + +Added intent, discovery, plan, decisions, risks, status, review evidence, chunk +map, and twelve planning/chunk contracts under `WS-XINT-003`. + +## Why it changed + +REV authority was distributed across AUTH, REV, and XINT-002 contracts. The +review found a concrete REV-03P/AUTH-12D2 policy ownership collision, missing +privileged action registration, globally shared action availability, and an +unsafe response-evidence order. + +## Design chosen + +REV owns lifecycle semantics; AUTH owns identity/evaluation/PREP/evidence; ART +and shared submission-artifact actions remain with XINT-002; CON remains a +flush-only atomic participant. Registration and activation remain separate. + +## Alternatives rejected + +Per-REV-chunk AUTH invention, direct grant reads in REV, generic contexts, +generic artifact access, duplicate policy writers, and activation before hidden +feature readiness. + +## Scope control + +Planning Markdown only. No backend code, migration, action availability, route, +worker, or product behavior changed. Chunks 02-09 are explicitly +non-implementable until refreshed with exact current-main files and commands. + +## Product behavior + +Unchanged. Review routes/actions remain unavailable. + +## Acceptance criteria proof + +- Complete human, Project Manager, Operator, and fixed-service inventory. +- One policy persistence/writer path required. +- Exact reviewer current-work, self-review denial, lease/packet/evidence, + decision, revision, recovery, and conformance boundaries specified. +- XINT-002 ART/shared-submission custody preserved. +- Four missing privileged actions receive registration-only wave 08R. +- Both `review.reconcile.run` identities activate in one global ActionId wave. + +## Tests/checks run + +- `python3 scripts/check_markdown_links.py` +- `python3 scripts/check_stale_workstream_wording.py` +- `git diff --check` + +No runtime tests are applicable to a planning-only Markdown change. Hosted CI +must still pass on the exact PR head. + +## Test delta + +No tests changed or weakened. Later chunk contracts require PostgreSQL races, +PREP denial matrices, service all-pairs denial, atomic fault injection, focused +90-percent coverage, and hosted repository coverage. + +## CI integrity + +No workflow, package, Ruff, pytest, coverage threshold, exclusion, or skip was +changed. + +## Reviewer results + +Architecture and docs: PASS. Security, product/ops, QA, and senior engineering: +PASS WITH LOW RISKS; every low/informational wording risk was also corrected. + +## External review + +The initial Agent Gates run failed because the authorization-specific stale-doc +scanner found retired human-worker vocabulary. Commit `2c17bc36` replaced it +with exact fixed-service terminology; the local scanner and replacement +exact-head Agent Gates then passed. Backend exact-head CI remains required. +CodeRabbit completed substantive review with four comments: two already fixed +by `2c17bc36`, and two addressed by the following corrective commit. Final +exact-head statuses must be recorded before human merge. + +## Remaining risks + +Future activation chunks must refresh exact owner manifests, files, migration +head, commands, and runtime owner evidence from then-current main. + +## Follow-up work + +After human merge and explicit request, execute `WS-XINT-003-01`. AUTH-12D2 and +REV-03P runtime work must wait for that ownership/custody reconciliation. + +## Human review focus + +Review policy ownership, the XINT-002 boundary, response-evidence sequencing, +08R registration, single-wave reconciliation activation, and chunk order. + +## Human merge ownership + +Only the human may merge this PR.