From 66eeccb5ef70c68b2080b6fc34180a9dae50680c Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Sat, 25 Jul 2026 10:55:44 +0100 Subject: [PATCH 1/3] docs(auth): document project role mutation schemas --- .../STATUS.md | 9 ++++----- .agent-loop/merge-intents/WS-AUTH-002-01.json | 9 +++++++++ .../app/modules/authorization/project_role_schemas.py | 8 ++++++++ 3 files changed, 21 insertions(+), 5 deletions(-) create mode 100644 .agent-loop/merge-intents/WS-AUTH-002-01.json 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/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 From b1f213559c230b0897f8a5f922a1aa9047e23da0 Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Sat, 25 Jul 2026 11:12:00 +0100 Subject: [PATCH 2/3] docs(auth): record four-docstring review evidence --- ...WS-AUTH-002-01-internal-review-evidence.md | 94 +++++++++++++++++++ .../reviews/WS-AUTH-002-01-pr-trust-bundle.md | 73 ++++++++++++++ 2 files changed, 167 insertions(+) create mode 100644 .agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/reviews/WS-AUTH-002-01-internal-review-evidence.md create mode 100644 .agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/reviews/WS-AUTH-002-01-pr-trust-bundle.md 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..012ab081 --- /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 AFTER FIXES | None | Required evidence and trust bundle added after confirming the minimal source diff. | +| QA/test | PASS AFTER FIXES | None | Source and schema checks pass; hosted DB/full-suite proof remains an external gate. | +| security/auth | PASS AFTER FIXES | 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 AFTER FIXES | None | Evidence gate repaired; CI configuration and enforcement are unchanged. | +| docs | PASS AFTER FIXES | None | Four docstrings are accurate; required evidence artifacts added. | +| reuse/dedup | PASS | None | Reused adjacent AUTH schema wording conventions without refactoring. | +| test delta | PASS AFTER FIXES | None | No tests, assertions, skips, or coverage controls changed; evidence added. | + +## 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..715d3815 --- /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 AFTER FIXES | +| QA/test | PASS AFTER FIXES | +| security/auth | PASS AFTER FIXES | +| product/ops | PASS | +| architecture | PASS | +| CI integrity | PASS AFTER FIXES | +| docs | PASS AFTER FIXES | +| reuse/dedup | PASS | +| test delta | PASS AFTER FIXES | + +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. From 09852d8b1799fc1a945600741e767f3238c9b3fa Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Sat, 25 Jul 2026 11:16:40 +0100 Subject: [PATCH 3/3] docs(auth): bind final corrective review results --- .../WS-AUTH-002-01-internal-review-evidence.md | 12 ++++++------ .../reviews/WS-AUTH-002-01-pr-trust-bundle.md | 12 ++++++------ 2 files changed, 12 insertions(+), 12 deletions(-) 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 index 012ab081..3aca7fd7 100644 --- 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 @@ -35,15 +35,15 @@ test-delta=/root/auth002_01_testdelta | Reviewer | Result | Blocking findings | Notes | |---|---:|---|---| -| senior engineering | PASS AFTER FIXES | None | Required evidence and trust bundle added after confirming the minimal source diff. | -| QA/test | PASS AFTER FIXES | None | Source and schema checks pass; hosted DB/full-suite proof remains an external gate. | -| security/auth | PASS AFTER FIXES | None | AST without docstrings is identical and no authorization behavior changed. | +| 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 AFTER FIXES | None | Evidence gate repaired; CI configuration and enforcement are unchanged. | -| docs | PASS AFTER FIXES | None | Four docstrings are accurate; required evidence artifacts added. | +| 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 AFTER FIXES | None | No tests, assertions, skips, or coverage controls changed; evidence added. | +| test delta | PASS WITH LOW RISKS | None | No tests, assertions, skips, or coverage controls changed; hosted proof remains required. | ## Valid Findings Addressed 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 index 715d3815..026cff65 100644 --- 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 @@ -47,15 +47,15 @@ Valid findings addressed: yes | Reviewer | Result | |---|---:| -| senior engineering | PASS AFTER FIXES | -| QA/test | PASS AFTER FIXES | -| security/auth | PASS AFTER FIXES | +| senior engineering | PASS WITH LOW RISKS | +| QA/test | PASS WITH LOW RISKS | +| security/auth | PASS | | product/ops | PASS | | architecture | PASS | -| CI integrity | PASS AFTER FIXES | -| docs | PASS AFTER FIXES | +| CI integrity | PASS WITH LOW RISKS | +| docs | PASS | | reuse/dedup | PASS | -| test delta | PASS AFTER FIXES | +| test delta | PASS WITH LOW RISKS | The fixes add only the required evidence and trust bundle. No implementation changed after the reviewed code SHA.