docs(auth): add project-role mutation docstrings

.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/STATUS.md

@@ -1,8 +1,7 @@
 # Status: WS-AUTH-002 — Authorization Docstring Lint Correction
 
-- Phase: planning intake
+- Phase: implementation
 - Active planning chunk: none
-- Active implementation chunk: none
-- Proposed planning chunk: `WS-AUTH-002-PLAN`
-- Reviewed implementation successor: `WS-AUTH-002-01`
-- Gate: stopped pending planning-intake merge and a separate explicit start
+- Active implementation chunk: `WS-AUTH-002-01`
+- Completed planning chunk: `WS-AUTH-002-PLAN`
+- Gate: implementation review and hosted evidence

.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/reviews/WS-AUTH-002-01-internal-review-evidence.md

@@ -0,0 +1,94 @@
+# Internal Review Evidence: WS-AUTH-002-01
+
+## Chunk
+
+`WS-AUTH-002-01` — Four Authorization Public Docstrings
+
+open sub-agent sessions: none
+
+valid findings addressed: yes
+
+## Reviewed Revision
+
+Reviewed code SHA: 66eeccb5ef70c68b2080b6fc34180a9dae50680c
+
+Reviewed at: 2026-07-25T10:11:07Z
+
+Reviewer run IDs: senior-engineering=/root/auth002_01_senior;
+QA/test=/root/auth002_01_qa; security/auth=/root/auth002_01_security;
+product/ops=/root/auth002_01_product; architecture=/root/auth002_01_arch;
+CI-integrity=/root/auth002_01_ci; docs=/root/auth002_01_docs;
+reuse/dedup=/root/auth002_01_reuse;
+test-delta=/root/auth002_01_testdelta
+
+## Reviewed Change
+
+- Added a concise docstring to the canonical project-role mutation reason
+  validator.
+- Added concise issue-body, revoke-body, and mutation-response model docstrings.
+- Changed no validation, serialization structure, API structure, authorization,
+  persistence, migration, test, workflow, package, or CI behavior.
+- Updated only the active initiative status and added one terminal merge intent
+  outside the source file.
+
+## Reviewer Results
+
+| Reviewer | Result | Blocking findings | Notes |
+|---|---:|---|---|
+| senior engineering | PASS WITH LOW RISKS | None | Required evidence is present; hosted proof remains an external gate. |
+| QA/test | PASS WITH LOW RISKS | None | Source and schema checks pass; hosted DB/full-suite proof remains an external gate. |
+| security/auth | PASS | None | AST without docstrings is identical and no authorization behavior changed. |
+| product/ops | PASS | None | Wording accurately describes existing issue, revoke, and response behavior. |
+| architecture | PASS | None | Boundary is exact and AUTH-11 remains untouched. |
+| CI integrity | PASS WITH LOW RISKS | None | Evidence gate passes; hosted exact-head proof remains required. |
+| docs | PASS | None | Four docstrings and evidence artifacts are accurate and complete. |
+| reuse/dedup | PASS | None | Reused adjacent AUTH schema wording conventions without refactoring. |
+| test delta | PASS WITH LOW RISKS | None | No tests, assertions, skips, or coverage controls changed; hosted proof remains required. |
+
+## Valid Findings Addressed
+
+- Added this required implementation review evidence file.
+- Added the adjacent PR trust bundle.
+- Recorded the local database setup limitation instead of suppressing it.
+- Kept hosted PostgreSQL, full backend, coverage, and API E2E proof as pending
+  external gates rather than claiming local success.
+
+## Commands Run
+
+```bash
+(cd backend && .venv/bin/python -m ruff check app tests scripts)
+(cd backend && test "$(.venv/bin/python -m ruff --version)" = "ruff 0.15.22")
+(cd backend && .venv/bin/docstr-coverage --config .docstr.yaml)
+(cd backend && .venv/bin/python -m py_compile app/modules/authorization/project_role_schemas.py)
+(cd backend && .venv/bin/python -m pytest -q tests/test_authorization.py -k project_role)
+python3 scripts/update_post_merge_memory.py validate-merge-intent --base-ref origin/main
+python3 scripts/check_internal_review_evidence.py
+python3 scripts/check_markdown_links.py
+python3 scripts/check_stale_workstream_wording.py
+git diff --check origin/main...HEAD
+```
+
+Ruff 0.15.22, docstring coverage, compilation, merge-intent validation,
+Markdown links, stale wording, and whitespace checks pass. Docstring coverage
+increases from 84.3 to 84.5 percent with the unchanged 80 percent threshold.
+The focused test command completed 71 passing tests; two database-backed tests
+could not enter setup because this worktree has no
+`WORKSTREAM_TEST_DATABASE_URL`. GitHub's Postgres-backed exact-head test is the
+authoritative remaining proof and must pass before merge.
+
+Independent reviewers also proved that, after stripping docstrings, the Python
+AST is identical to `origin/main`. The three Pydantic model schemas differ only
+by top-level description metadata; after removing descriptions, their JSON
+Schema structures are equal. The helper docstring creates no schema metadata.
+
+## Remaining Risks
+
+- Hosted Backend, API E2E, database-backed tests, coverage gates, Agent Gates,
+  and CodeRabbit remain required on the final PR head.
+- This terminal corrective chunk declares no successor and must not start or
+  consume `WS-AUTH-001-11`.
+
+## Stop Condition
+
+Stop at human review after hosted exact-head checks pass. Only the user may
+approve and merge the corrective PR.

.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/reviews/WS-AUTH-002-01-pr-trust-bundle.md

@@ -0,0 +1,73 @@
+# PR Trust Bundle: WS-AUTH-002-01
+
+## Chunk
+
+`WS-AUTH-002-01` — Four Authorization Public Docstrings
+
+## Outcome
+
+The four AUTH-owned docstring findings are corrected without weakening Ruff,
+docstring coverage, tests, CI, or authorization behavior.
+
+## Exact scope
+
+- `_reason` documents its existing canonical mutation-reason validation.
+- `ProjectRoleGrantIssueBody` documents the existing issuance request.
+- `ProjectRoleGrantRevokeBody` documents the existing revocation request.
+- `ProjectRoleGrantMutationResponse` documents the existing stable mutation
+  result.
+- `STATUS.md` records the active implementation review gate.
+- One terminal schema-v2 merge intent declares no successor.
+
+No validator, field, model configuration, route, service, repository,
+migration, test, workflow, package, or CI configuration changed.
+
+## Proof
+
+- Ruff 0.15.22: pass.
+- Ruff `check app tests scripts`: pass.
+- Docstring coverage: pass at 84.5 percent, up from 84.3 percent.
+- Python compilation: pass.
+- Merge-intent, Markdown-link, stale-wording, and whitespace gates: pass.
+- Focused project-role tests: 71 pass; two setup-only errors correctly report
+  the absent local database URL and remain for hosted Postgres proof.
+- AST comparison without docstrings: identical.
+- Pydantic schemas: description-only metadata delta; structural equality after
+  descriptions are removed.
+
+## Internal review
+
+Reviewed code SHA: 66eeccb5ef70c68b2080b6fc34180a9dae50680c
+
+Reviewed at: 2026-07-25T10:11:07Z
+
+Open sub-agent sessions: none
+
+Valid findings addressed: yes
+
+| Reviewer | Result |
+|---|---:|
+| senior engineering | PASS WITH LOW RISKS |
+| QA/test | PASS WITH LOW RISKS |
+| security/auth | PASS |
+| product/ops | PASS |
+| architecture | PASS |
+| CI integrity | PASS WITH LOW RISKS |
+| docs | PASS |
+| reuse/dedup | PASS |
+| test delta | PASS WITH LOW RISKS |
+
+The fixes add only the required evidence and trust bundle. No implementation
+changed after the reviewed code SHA.
+
+## Remaining external gates
+
+GitHub Backend, database-backed full-suite and coverage proof, API E2E, Agent
+Gates, and CodeRabbit must pass on the final exact head. Local database setup
+errors are not presented as test success and are not silenced.
+
+## Human review focus
+
+Confirm the source diff is exactly four docstrings, no quality gate changed,
+and the terminal merge intent declares no successor. Only the user may approve
+and merge this specific PR.

.agent-loop/merge-intents/WS-AUTH-002-01.json

@@ -0,0 +1,9 @@
+{
+  "schema_version": 2,
+  "initiative_id": "WS-AUTH-002",
+  "chunk_id": "WS-AUTH-002-01",
+  "chunk_title": "Four Authorization Public Docstrings",
+  "next_chunk_id": null,
+  "next_chunk_title": null,
+  "next_requires_explicit_start": true
+}

backend/app/modules/authorization/project_role_schemas.py

@@ -15,6 +15,8 @@
 
 
 def _reason(value: str) -> str:
+    """Validate one canonical project-role mutation reason."""
+
     if (
         value != value.strip()
         or not 1 <= len(value.encode("utf-8")) <= 500
@@ -28,6 +30,8 @@ def _reason(value: str) -> str:
 
 
 class ProjectRoleGrantIssueBody(BaseModel):
+    """Request body for one project-role grant issuance."""
+
     model_config = _STRICT
 
     target_actor_profile_id: UUID
@@ -37,12 +41,16 @@ class ProjectRoleGrantIssueBody(BaseModel):
 
 
 class ProjectRoleGrantRevokeBody(BaseModel):
+    """Request body for one project-role grant revocation."""
+
     model_config = _STRICT
 
     reason: Reason
 
 
 class ProjectRoleGrantMutationResponse(BaseModel):
+    """Stable project-role grant state returned after a mutation."""
+
     model_config = ConfigDict(extra="forbid", frozen=True)
 
     id: UUID