docs(xint): plan REV-AUTH end-to-end contract

[Abiorh001]

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

Pending GitHub Actions and CodeRabbit on the planning PR.

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.

Summary by CodeRabbit

• Documentation
  • Added comprehensive planning and contract documentation for end-to-end review and revision authorization.
  • Defined ownership boundaries, authorization rules, risk controls, validation requirements, and implementation sequencing.
  • Documented reviewer workflows, decisions, contributor responses, recovery, lifecycle controls, and release conformance.
  • Recorded review outcomes and required human approvals.
• Status
  • Planning is complete; no runtime behavior, permissions, or action availability changed.

[coderabbitai]

Warning

Review limit reached

@Abiorh001, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 49 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: a079cf18-b16e-4699-ab3f-e44be9291404

📥 Commits

Reviewing files that changed from the base of the PR and between f94bc17 and 456200d.

📒 Files selected for processing (2)

• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-09-conformance-release.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/reviews/WS-XINT-003-PLAN-external-review-response.md

📝 Walkthrough

Walkthrough

This PR adds the WS-XINT-003 REV-AUTH planning contract. It documents ownership, authorization protocols, staged activation chunks, verification requirements, risks, review outcomes, and release gates. It adds no runtime code and does not activate actions.

Changes

REV-AUTH planning contract

Layer / File(s)	Summary
Contract baseline .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/{INTENT,DISCOVERY,DECISIONS,RISKS,STATUS,REVIEW_LOG}.md, .../reviews/*	Defines the authorization model, current findings, ownership boundaries, action inventory, operational decisions, risks, planning status, and review evidence.
Shared authorization protocol .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/PLAN.md, .../chunks/WS-XINT-003-01-contract-reconciliation.md, .../WS-XINT-003-02-policy-mutation-activation.md	Defines policy reconciliation, PREP authorization, durable-mutation handling, read rules, ownership boundaries, verification requirements, and the non-activation boundary.
Reviewer workflow activation .../chunks/WS-XINT-003-03A-reviewer-lease-activation.md, .../WS-XINT-003-03B-lease-service-activation.md, .../WS-XINT-003-04-review-context-activation.md, .../WS-XINT-003-05-review-evidence-activation.md	Defines staged reviewer queue, lease, timer, context, and bounded evidence activation contracts.
Decision, recovery, and lifecycle activation .../chunks/WS-XINT-003-06-review-decision-activation.md, .../WS-XINT-003-07-human-revision-activation.md, .../WS-XINT-003-08A-review-recovery-activation.md, .../WS-XINT-003-08B-review-service-activation.md, .../WS-XINT-003-08R-lifecycle-action-registration.md	Defines review outcomes, revision responses, recovery operations, reconciliation services, and planned lifecycle actions.
Conformance and release .../CHUNK_MAP.md, .../chunks/WS-XINT-003-09-conformance-release.md	Defines chunk dependencies, end-to-end verification, failure-mode checks, and human-controlled release conditions.

Estimated code review effort: 2 (Simple) | ~15 minutes

Possibly related PRs

• Flow-Research/workstream#23: Establishes the initiative planning and review-evidence structure used by this PR.
• Flow-Research/workstream#93: Defines the authorization baseline for grants, identities, recovery controls, and fail-closed behavior referenced by this plan.
• Flow-Research/workstream#144: Defines related REV/AUTH/CON transaction boundaries and flush-only CON behavior.

Suggested reviewers: abiorh-claw

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the documentation change and the REV-AUTH end-to-end contract planning scope.
Description check	✅ Passed	The description covers the main template sections and provides clear scope, design, validation, review, risk, and follow-up information.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/ws-xint-003-rev-auth-end-to-end

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
@.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-06-review-decision-activation.md:
- Around line 16-17: Update the contract text covering CON participant wiring
and atomic commit to explicitly state that CON only flushes REV/AUTH-prepared
typed facts; it must perform no authority evaluation, decision, or lifecycle
work. Clarify that REV retains ownership of decision and lifecycle behavior,
including the corresponding section also covered by this review.

In
@.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-08A-review-recovery-activation.md:
- Around line 5-8: Replace the incomplete requirement sentence in
.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-08A-review-recovery-activation.md
lines 5-8 with “REV recovery behavior must remain hidden,” and replace it in
.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-08B-review-service-activation.md
lines 5-8 with “REV jobs/projection/control must remain hidden.”

In @.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/DECISIONS.md:
- Around line 26-27: Replace the stale human-worker terminology with the
accepted fixed-service term in both documentation sites: update “fixed worker”
in .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/DECISIONS.md lines
26-27 and “catch-all worker” in
.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/RISKS.md line 15,
preserving the surrounding contract and risk statements.

In
@.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/reviews/WS-XINT-003-PLAN-pr-trust-bundle.md:
- Around line 86-88: Update the “External review” section to record GitHub
Actions as blocked due to the failed exact-head check from
scripts/check_stale_authorization_docs.py, which found HUMAN_WORKER_VOCABULARY.
Update the stale authorization documentation, rerun the exact-head checks, and
document the resulting status before human merge; keep CodeRabbit’s pending
status separate.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 216bae25-6923-46ec-b941-0384e0aaacdb

📥 Commits

Reviewing files that changed from the base of the PR and between 99dc0b3 and 44aa60a.

📒 Files selected for processing (21)

• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/CHUNK_MAP.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/DECISIONS.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/DISCOVERY.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/INTENT.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/PLAN.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/REVIEW_LOG.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/RISKS.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/STATUS.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-01-contract-reconciliation.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-02-policy-mutation-activation.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-03A-reviewer-lease-activation.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-03B-lease-service-activation.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-04-review-context-activation.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-05-review-evidence-activation.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-06-review-decision-activation.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-07-human-revision-activation.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-08A-review-recovery-activation.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-08B-review-service-activation.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-08R-lifecycle-action-registration.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-09-conformance-release.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/reviews/WS-XINT-003-PLAN-pr-trust-bundle.md

[Abiorh001]

Final exact-head status for 85c94f0e:

• Agent Gates: passed
• Backend full suite/coverage: passed (15m32s)
• CodeRabbit substantive review: completed; all four actionable comments addressed
• CodeRabbit incremental review: rate-limited after the corrective commits; GitHub reports the CodeRabbit check as passed
• Internal architecture, security, product/ops, QA, senior engineering, and docs reviews: passed; no open finding remains
• Branch: 0 commits behind origin/main; worktree clean

The initial stale-authorization-doc failure is preserved in the trust bundle/external response, together with its corrective commit and replacement passing gate. No runtime behavior or action availability is changed. Human approval/merge remains required.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
@.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-09-conformance-release.md:
- Around line 36-39: Update the release matrix in
WS-XINT-003-09-conformance-release.md to cover every universal fail-closed
mutation case listed in PLAN.md, including forged,
wrong-session/transaction/action/actor/service,
cross-task/submission/lease/review, stale-policy, expired or revoked authority,
and already-consumed handles. Add explicit conformance cases or otherwise
eliminate each listed gap while preserving the required no-partial-state
outcome.

In
@.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/reviews/WS-XINT-003-PLAN-external-review-response.md:
- Around line 5-9: Update the Agent Gates review record around the documented
failed and replacement runs to include the exact reviewed PR head, such as
85c94f0e where applicable, plus unique identifiers or references for both the
failed and replacement passes. Preserve the existing failure cause and
successful replacement outcome while making the evidence traceable to the exact
reviewed artifact.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f84e1b9d-858a-47b1-b8c4-5604b1161a6e

📥 Commits

Reviewing files that changed from the base of the PR and between 44aa60a and f94bc17.

📒 Files selected for processing (22)

• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/CHUNK_MAP.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/DECISIONS.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/DISCOVERY.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/INTENT.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/PLAN.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/REVIEW_LOG.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/RISKS.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/STATUS.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-01-contract-reconciliation.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-02-policy-mutation-activation.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-03A-reviewer-lease-activation.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-03B-lease-service-activation.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-04-review-context-activation.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-05-review-evidence-activation.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-06-review-decision-activation.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-07-human-revision-activation.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-08A-review-recovery-activation.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-08B-review-service-activation.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-08R-lifecycle-action-registration.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-09-conformance-release.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/reviews/WS-XINT-003-PLAN-external-review-response.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/reviews/WS-XINT-003-PLAN-pr-trust-bundle.md

🚧 Files skipped from review as they are similar to previous changes (17)

• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-08B-review-service-activation.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/INTENT.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-08R-lifecycle-action-registration.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-08A-review-recovery-activation.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/reviews/WS-XINT-003-PLAN-pr-trust-bundle.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-04-review-context-activation.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-07-human-revision-activation.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-05-review-evidence-activation.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-03B-lease-service-activation.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/REVIEW_LOG.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-06-review-decision-activation.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-03A-reviewer-lease-activation.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/STATUS.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-01-contract-reconciliation.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-02-policy-mutation-activation.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/RISKS.md
• .agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/DECISIONS.md