docs(auth): plan four-docstring lint correction

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

@@ -0,0 +1,8 @@
+# Chunk Map: WS-AUTH-002 — Authorization Docstring Lint Correction
+
+| Chunk | Purpose | Dependency | State |
+|---|---|---|---|
+| `WS-AUTH-002-PLAN` | Establish the reviewed corrective boundary | none | proposed |
+| `WS-AUTH-002-01` | Add the four AUTH-owned public docstrings | PLAN merged and explicit signed start | inactive |
+
+No later chunk is declared. PR #198 integration remains owned by `WS-CI-001`.

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

@@ -0,0 +1,16 @@
+# Decisions: WS-AUTH-002 — Authorization Docstring Lint Correction
+
+## D1 — Preserve AUTH-11
+
+Use a separate AUTH-owned corrective initiative because AUTH-11 represents a
+different security-sensitive product cutover.
+
+## D2 — Documentation-only repair
+
+Resolve the findings with four concise docstrings. Do not change validation,
+tests, configuration, or CI.
+
+## D3 — Trusted-main sequencing
+
+Merge the correction before PR #198 integrates `main`; then require new
+exact-head checks on PR #198.

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

@@ -0,0 +1,26 @@
+# Discovery: WS-AUTH-002 — Authorization Docstring Lint Correction
+
+## Observed state
+
+- PR #194 merged project-role grant mutations into `main`.
+- PR #198 is the CI semantic-lane change that must consume the correction.
+- Ruff 0.15.22 passes `ruff check app tests scripts`; the Ruff gate is healthy.
+- CodeRabbit's docstring lint identifies exactly four missing public docstrings
+  in `backend/app/modules/authorization/project_role_schemas.py`:
+  `_reason`, `ProjectRoleGrantIssueBody`, `ProjectRoleGrantRevokeBody`, and
+  `ProjectRoleGrantMutationResponse`.
+- `WS-AUTH-001` is stopped after `WS-AUTH-001-10C` with `WS-AUTH-001-11` as its
+  declared successor. AUTH-11 is a security-sensitive product cutover and must
+  not be falsely consumed for this correction.
+
+## Relevant verification
+
+- `backend/.venv/bin/python -m ruff check app tests scripts`
+- `backend/.venv/bin/docstr-coverage --config .docstr.yaml`
+- Python compilation of the one changed module
+- stale-wording, Markdown-link, internal-evidence, and whitespace gates
+
+## Risks
+
+The main risk is scope laundering: using a lint correction to alter validation
+or weaken a gate. A one-source-file allowlist and explicit non-goals prevent it.

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

@@ -0,0 +1,26 @@
+# Intent: WS-AUTH-002 — Authorization Docstring Lint Correction
+
+## Human goal
+
+Correct the four AUTH-owned public-docstring findings that appear when PR #198
+consumes the project-role mutation code from `main`, without weakening Ruff,
+docstring coverage, CI, or authorization behavior.
+
+## Success state
+
+The four findings in `project_role_schemas.py` are resolved by concise,
+behavior-accurate docstrings. The exact Ruff gate and docstring tooling remain
+unchanged, the corrective PR merges independently, and PR #198 can consume the
+result from trusted `main`.
+
+## Non-goals
+
+- No runtime, validation, API, schema, migration, or test behavior changes.
+- No broad docstring cleanup.
+- No Ruff, docstring, coverage, workflow, or branch-protection changes.
+- No work from `WS-AUTH-001-11`.
+
+## Human direction
+
+The repository owner directed a narrow AUTH-owned corrective chunk, followed by
+a fresh `main` integration and exact-head checks on PR #198.

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

@@ -0,0 +1,34 @@
+# Plan: WS-AUTH-002 — Authorization Docstring Lint Correction
+
+## Approach
+
+1. Land this planning-only intake with one reviewed implementation successor.
+2. Start `WS-AUTH-002-01` through the signed explicit-event workflow.
+3. Add concise public docstrings to only the four reported symbols.
+4. Run exact Ruff and docstring checks plus repository evidence gates.
+5. Run required internal reviewers and publish one corrective PR.
+6. After human-approved merge, allow PR #198 to pull trusted `main` and rerun
+   exact-head checks.
+
+## Rejected alternatives
+
+- Do not weaken or exclude Ruff/docstring rules.
+- Do not fold the correction into PR #198 because AUTH owns the affected file.
+- Do not consume `WS-AUTH-001-11`; that chunk owns a different authorization
+  cutover and its completion evidence must remain truthful.
+- Do not perform unrelated missing-docstring cleanup.
+
+## Preserved boundaries
+
+The implementation changes documentation only. Pydantic validation,
+serialization structure, authorization semantics, database state, migrations,
+and CI configuration remain unchanged. Generated JSON Schema/OpenAPI may gain
+only description metadata sourced from the Pydantic model docstrings; no
+structural contract delta is permitted.
+
+## Proof strategy
+
+Review the exact source diff, run Ruff 0.15.22 and docstring coverage, compile
+the module, run deterministic repository gates, and require senior, QA,
+security, product, architecture, docs, reuse, CI-integrity, and test-delta
+review.

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

@@ -0,0 +1,9 @@
+# Risks: WS-AUTH-002 — Authorization Docstring Lint Correction
+
+| Risk | Control |
+|---|---|
+| Ruff or docstring enforcement is weakened | Configuration and workflow files are forbidden |
+| Runtime validation changes under a lint label | Only docstrings may change in the source file |
+| AUTH-11 is incorrectly consumed | A separate corrective initiative preserves AUTH-11 state |
+| Broad cleanup delays PR #198 | Exactly four named symbols are in scope |
+| PR #198 consumes an unmerged patch | Integration waits for trusted-main merge |

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

@@ -0,0 +1,8 @@
+# Status: WS-AUTH-002 — Authorization Docstring Lint Correction
+
+- Phase: planning intake
+- 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

.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/chunks/WS-AUTH-002-01-four-public-docstrings.md

@@ -0,0 +1,101 @@
+# Chunk Contract: WS-AUTH-002-01 — Four Authorization Public Docstrings
+
+## Parent initiative
+
+`WS-AUTH-002` — Authorization Docstring Lint Correction
+
+## Goal
+
+Resolve the four reported AUTH-owned docstring findings without changing
+runtime behavior or weakening any lint gate.
+
+## Why this chunk exists
+
+PR #198 must consume clean AUTH-owned source from trusted `main` before its
+exact-head checks can be trusted.
+
+## Approved plan reference
+
+- INTENT: `.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/INTENT.md`
+- PLAN: `.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/PLAN.md`
+- CHUNK_MAP: `.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/CHUNK_MAP.md`
+
+## Risk class
+
+L1
+
+## SLA
+
+P1
+
+## Start phase
+
+`implementation`
+
+## Allowed files
+
+```text
+backend/app/modules/authorization/project_role_schemas.py
+.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/STATUS.md
+.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/reviews/WS-AUTH-002-01-internal-review-evidence.md
+.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/reviews/WS-AUTH-002-01-pr-trust-bundle.md
+.agent-loop/merge-intents/WS-AUTH-002-01.json
+```
+
+## Not allowed
+
+```text
+runtime, validation, serialization structure, API structure, database, migration, or test changes
+Ruff, docstring, coverage, workflow, package, or CI configuration changes
+symbols other than _reason, ProjectRoleGrantIssueBody, ProjectRoleGrantRevokeBody,
+and ProjectRoleGrantMutationResponse
+unrelated docstring cleanup
+PR #198 branch changes
+```
+
+## Acceptance criteria
+
+- [ ] Each of the four named symbols has a concise behavior-accurate public docstring.
+- [ ] The source diff contains docstrings only.
+- [ ] Ruff 0.15.22 passes without configuration or invocation changes.
+- [ ] Docstring coverage passes without exclusions or threshold changes.
+- [ ] Generated schema changes, if any, are limited to description metadata
+      sourced from the three Pydantic model docstrings; the helper docstring
+      creates no schema metadata.
+- [ ] No test, runtime, API, schema, migration, or CI behavior changes.
+- [ ] Merge intent has no successor and leaves this corrective initiative stopped.
+
+## Verification commands
+
+```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)
+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
+```
+
+## Required reviewers
+
+- [ ] senior engineering
+- [ ] QA/test
+- [ ] security/auth
+- [ ] product/ops
+- [ ] architecture
+- [ ] CI integrity
+- [ ] docs
+- [ ] reuse/dedup
+- [ ] test delta
+
+## Human review focus
+
+Confirm the source change is exactly four docstrings and that no quality gate,
+validation rule, or authorization behavior changed.
+
+## Stop conditions
+
+Stop if resolving the findings requires code behavior, tests, configuration,
+workflow changes, or more than the four named docstrings.

.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/chunks/WS-AUTH-002-PLAN-planning-intake.md

@@ -0,0 +1,88 @@
+# Chunk Contract: WS-AUTH-002-PLAN — Authorization Docstring Lint Correction Planning Intake
+
+## Parent initiative
+
+`WS-AUTH-002` — Authorization Docstring Lint Correction
+
+## Goal
+
+Land one additive planning tree that declares the narrow corrective successor
+without activating or implementing it.
+
+## Why this chunk exists
+
+Trusted explicit starts require a reviewed contract on exact `main`; this
+planning-only intake establishes that contract without misusing AUTH-11.
+
+## Approved plan reference
+
+- INTENT: `.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/INTENT.md`
+- PLAN: `.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/PLAN.md`
+- CHUNK_MAP: `.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/CHUNK_MAP.md`
+
+## Risk class
+
+L1
+
+## SLA
+
+P1
+
+## Start phase
+
+`planning`
+
+## Allowed files
+
+```text
+.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/**
+.agent-loop/merge-intents/WS-AUTH-002-PLAN.json
+```
+
+## Not allowed
+
+```text
+application, test, migration, API, database, workflow, or configuration changes
+active-state claims or implementation
+Ruff, docstring, coverage, CI, review, or merge-gate weakening
+changes outside one additive initiative tree and one merge intent
+```
+
+## Acceptance criteria
+
+- [ ] The PR adds only one canonical initiative planning tree and one schema-v2 merge intent.
+- [ ] The intake contains no implementation and leaves the initiative stopped.
+- [ ] `WS-AUTH-002-01` is the same-initiative implementation successor and requires explicit start.
+- [ ] The implementation contract permits only four named docstrings and corrective evidence.
+- [ ] AUTH-11 and every existing initiative remain unchanged.
+
+## Verification commands
+
+```bash
+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
+```
+
+## Required reviewers
+
+- [ ] senior engineering
+- [ ] QA/test
+- [ ] security/auth
+- [ ] product/ops
+- [ ] architecture
+- [ ] CI integrity
+- [ ] docs
+- [ ] reuse/dedup
+- [ ] test delta
+
+## Human review focus
+
+Confirm this is planning-only, preserves AUTH-11, and makes weakening any lint
+or CI gate impossible in the successor.
+
+## Stop conditions
+
+Stop if the intake requires application changes, activates work, modifies an
+existing initiative, or weakens any quality gate.