diff --git a/.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/STATUS.md b/.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/STATUS.md index 4847ffba..fb2b7d86 100644 --- a/.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/STATUS.md +++ b/.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 diff --git a/.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/reviews/WS-AUTH-002-01-internal-review-evidence.md b/.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/reviews/WS-AUTH-002-01-internal-review-evidence.md new file mode 100644 index 00000000..3aca7fd7 --- /dev/null +++ b/.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. diff --git a/.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/reviews/WS-AUTH-002-01-pr-trust-bundle.md b/.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/reviews/WS-AUTH-002-01-pr-trust-bundle.md new file mode 100644 index 00000000..026cff65 --- /dev/null +++ b/.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. diff --git a/.agent-loop/merge-intents/WS-AUTH-002-01.json b/.agent-loop/merge-intents/WS-AUTH-002-01.json new file mode 100644 index 00000000..7f80c14e --- /dev/null +++ b/.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 +} diff --git a/backend/app/modules/authorization/project_role_schemas.py b/backend/app/modules/authorization/project_role_schemas.py index 53e24da7..2df2c3a1 100644 --- a/backend/app/modules/authorization/project_role_schemas.py +++ b/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