feat(auth): register project read catalogue foundation

[Abiorh001]

Chunk

WS-AUTH-001-11A — Project Read Catalogue And Projection Foundation

Goal

Register eleven project-read authorization actions as planned, add the two required read permissions and exact administrative role mappings, and establish migration/audit parity without activating any API route.

Human-approved intent

The user approved resuming this bounded AUTH-owned chunk after pulling and reconciling current main.

What changed

• Added project.setup_diagnostic.read and project.effective_policy.read.
• Added eleven planned AUTH-11 actions owned by 11B, 11C1, or 11C2.
• Granted both permissions only to Project Manager, Operator, and Audit Authority under existing scopes.
• Added migration 0035_project_read_evidence with guarded downgrade behavior.
• Added typed and PostgreSQL role/scope matrices, public catalogue count/schema fingerprint updates, migration round-trip/refusal tests, and aligned documentation.

Why it changed

Later project-read surfaces need stable AUTH-owned action, permission, ownership, and audit contracts before product routes can safely activate them.

Design chosen

Use the existing immutable authorization catalogue, role-policy matrix, administrative definition projection, and audit evidence constraints. All eleven actions remain planned so the authorization kernel denies them until their owning chunks activate the corresponding product surfaces.

Alternatives rejected

• Activating routes in 11A: violates product ownership and chunk scope.
• Reusing broad project.read for diagnostics/policy: loses least-privilege separation.
• Granting contributor or finance/access-admin roles: exceeds reviewed authority.
• Weakening PostgreSQL constraints or downgrade guards: unsafe for audit custody.

Scope control

No project module, actor router, route registration, token-role mapping, compatibility alias, fallback path, CI workflow, or coverage threshold changed.

Product behavior

No new endpoint is available. The eleven actions cannot produce allowed authorization evidence while planned.

Acceptance criteria proof

• 76 permissions, 81 actions, 22 active actions, and 59 planned actions.
• Exactly eleven AUTH-11 actions with the reviewed permission/owner pairs.
• Typed and PostgreSQL proof covers allowed roles, exact project fencing, excluded admin roles, and every contributor role.
• Migration upgrade/downgrade/re-upgrade and committed-forward-evidence refusal pass.
• Public catalogue count and schema fingerprint are updated.

Tests/checks run

• Ruff on authorization app and changed tests: passed.
• Catalogue-focused unit tests: 13 passed.
• Isolated PostgreSQL role/scope matrix: 1 passed.
• Isolated public authorization lifecycle regression: 1 passed.
• Isolated migration 0035 round-trip/refusal: 2 passed.
• Lightweight agent gates: 6 passed.
• Markdown links, stale wording, and git diff --check: passed.
• Full backend coverage is intentionally delegated to hosted Backend / test.

Test delta

Four substantive tests added; no tests removed, skipped, or weakened. Existing public totals, migration-head expectations, and schema fingerprint were updated to the new canonical catalogue.

CI integrity

No workflow, runner, dependency, lint, typecheck, or coverage configuration changed. Hosted CI must preserve the 78% repository floor and 90% authorization subsystem floor.

Reviewer results

PASS: senior engineering, QA/test, security/auth, product/ops, architecture, CI integrity, docs, reuse/dedup, and test delta. QA's obsolete gate-command finding and docs' obsolete merge-intent finding were fixed and rechecked.

External review

Agent Gates, hosted Backend coverage, and CodeRabbit pass on final head 5bdea944; unresolved review threads: zero.

Remaining risks

Migration 0035 rewrites frozen audit vocabulary constraints; focused PostgreSQL proof and hosted full coverage both pass on the final head.

Follow-up work

11B/11C chunks may activate only their owned product surfaces. This PR does not begin them.

Human review focus

• Exact role/scope inclusion and exclusion.
• Eleven planned action/permission/owner mappings.
• Migration constraint replacement and downgrade refusal.
• Confirmation that no route becomes active.

Human merge ownership

• I can explain what changed and why.
• I reviewed the permission and migration boundaries.
• Required hosted checks and external review are complete.
• The user explicitly approves this PR for merge.

Summary by CodeRabbit

• New Features

  • Added read-only permissions for project setup diagnostics and effective-policy inspection.
  • Added related project-read actions to the authorization catalogue.
  • Updated eligible administrative roles to include the new project-read permissions.
  • Expanded the permission catalogue from 74 to 76 entries.

• Documentation

  • Updated authorization, role, permission, and operations documentation with the new permissions, actions, role assignments, and catalogue totals.

• Bug Fixes

  • Improved migration safeguards when reverting authorization evidence changes.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds two project-read permissions and related planned actions, assigns the permissions to selected admin roles, introduces Alembic audit-evidence parity with guarded downgrade behavior, and updates tests, schema fingerprints, workstream metadata, and authorization documentation.

Changes

Project-read authorization

Layer / File(s)	Summary
Catalogue and role policy backend/app/modules/authorization/catalogue.py, backend/app/modules/authorization/policy.py, backend/app/modules/authorization/admin_schemas.py, backend/app/modules/authorization/admin_service.py	Adds project-read permissions, actions, owners, planned action definitions, updated catalogue counts, role assignments, and dynamic permission totals.
Audit evidence migration backend/alembic/versions/0035_project_read_action_evidence.py	Adds PostgreSQL constraint updates for project-read evidence and prevents downgrade when matching evidence rows exist.
Authorization and migration validation backend/tests/*	Updates expected counts and revisions, adds migration round-trip and downgrade-safety tests, and verifies admin-role and PostgreSQL scope matrices.
Documentation and workstream updates .agent-loop/initiatives/..., docs/*	Updates implementation status, verification metadata, catalogue totals, role assignments, and AUTH-11A activation documentation.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant AdminAuthorization
  participant PermissionCatalogue
  participant AuditEvidenceMigration
  participant PostgreSQLAuditEvents
  AdminAuthorization->>PermissionCatalogue: resolve project-read permissions
  PermissionCatalogue->>AuditEvidenceMigration: provide action and permission mappings
  AuditEvidenceMigration->>PostgreSQLAuditEvents: update audit evidence constraints
  PostgreSQLAuditEvents-->>AuditEvidenceMigration: check existing evidence rows during downgrade
  AuditEvidenceMigration-->>AdminAuthorization: preserve or remove project-read parity

Loading

Possibly related PRs

• Flow-Research/workstream#126: Introduced the closed authorization catalogue and action-aware audit parity extended by this change.
• Flow-Research/workstream#131: Established the authorization admin and role-policy surfaces updated here.
• Flow-Research/workstream#186: Related to the public-schema fingerprint machinery updated in this change.

Suggested reviewers: abiorh-claw

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 41.38% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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.
Title check	✅ Passed	The title clearly matches the main change: registering project read authorization catalogue foundation.
Description check	✅ Passed	The description is mostly complete and covers goal, changes, rationale, design, scope, tests, and risks, though some template sections are missing or merged.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/ws-auth-001-11a-project-read-catalogue

---

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: 1

🤖 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 `@docs/operations_authorization_service.md`:
- Around line 676-680: The active-action breakdown in the catalogue summary must
enumerate all 22 active actions, including the five omitted AUTH-10 actions:
three AUTH-10B reads and two AUTH-10C mutations. Update the breakdown near the
referenced summary while preserving the existing counts and ensuring it matches
the catalogue and docs/spec_authorization_service.md.

🪄 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: 68be6981-b1cf-47ed-9ef3-b35de3f4bd86

📥 Commits

Reviewing files that changed from the base of the PR and between 22e8a8a and 9098cc2.

📒 Files selected for processing (13)

• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11A-project-read-catalogue-foundation.md
• backend/alembic/versions/0035_project_read_action_evidence.py
• backend/app/modules/authorization/admin_schemas.py
• backend/app/modules/authorization/admin_service.py
• backend/app/modules/authorization/catalogue.py
• backend/app/modules/authorization/policy.py
• backend/tests/conftest.py
• backend/tests/test_alembic.py
• backend/tests/test_auth.py
• backend/tests/test_authorization.py
• docs/operations_authorization_service.md
• docs/operations_roles_permissions.md
• docs/spec_authorization_service.md