diff --git a/.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/CHUNK_MAP.md b/.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/CHUNK_MAP.md new file mode 100644 index 00000000..f9687c1d --- /dev/null +++ b/.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`. diff --git a/.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/DECISIONS.md b/.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/DECISIONS.md new file mode 100644 index 00000000..02ab8cf9 --- /dev/null +++ b/.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. diff --git a/.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/DISCOVERY.md b/.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/DISCOVERY.md new file mode 100644 index 00000000..328039b3 --- /dev/null +++ b/.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. diff --git a/.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/INTENT.md b/.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/INTENT.md new file mode 100644 index 00000000..848c66f0 --- /dev/null +++ b/.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. diff --git a/.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/PLAN.md b/.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/PLAN.md new file mode 100644 index 00000000..640ff287 --- /dev/null +++ b/.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. diff --git a/.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/RISKS.md b/.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/RISKS.md new file mode 100644 index 00000000..34a91f8d --- /dev/null +++ b/.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 | 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 new file mode 100644 index 00000000..4847ffba --- /dev/null +++ b/.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 diff --git a/.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/chunks/WS-AUTH-002-01-four-public-docstrings.md b/.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/chunks/WS-AUTH-002-01-four-public-docstrings.md new file mode 100644 index 00000000..ff048103 --- /dev/null +++ b/.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. diff --git a/.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/chunks/WS-AUTH-002-PLAN-planning-intake.md b/.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/chunks/WS-AUTH-002-PLAN-planning-intake.md new file mode 100644 index 00000000..5690db5b --- /dev/null +++ b/.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. diff --git a/.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/reviews/WS-AUTH-002-PLAN-internal-review-evidence.md b/.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/reviews/WS-AUTH-002-PLAN-internal-review-evidence.md new file mode 100644 index 00000000..6275a37f --- /dev/null +++ b/.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/reviews/WS-AUTH-002-PLAN-internal-review-evidence.md @@ -0,0 +1,99 @@ +# Internal Review Evidence: WS-AUTH-002-PLAN + +## Chunk + +`WS-AUTH-002-PLAN` — Authorization Docstring Lint Correction Planning Intake + +open sub-agent sessions: none + +valid findings addressed: yes + +## Reviewed Revision + +Reviewed code SHA: 9b2677b01aee3842850292566ab8a4450cc6ba26 + +Reviewed at: 2026-07-25T09:06:31Z + +Reviewer run IDs: senior-engineering=/root/auth002_plan_senior; +QA/test=/root/auth002_plan_qa; security/auth=/root/auth002_plan_security; +product/ops=/root/auth002_plan_product; architecture=/root/auth002_plan_arch; +CI-integrity=/root/auth002_plan_ci; docs=/root/auth002_plan_docs; +reuse/dedup=/root/auth002_plan_reuse; +test-delta=/root/auth002_plan_testdelta + +## Reviewed Change + +- Added one planning-only `WS-AUTH-002` initiative tree and one schema-v2 merge + intent. +- Preserved `WS-AUTH-001-11` as the project visibility cutover rather than + falsely consuming it for a lint repair. +- Declared one inactive successor limited to four named public docstrings. +- Forbade runtime, validation, serialization structure, API structure, + database, migration, tests, workflow, package, configuration, and gate changes. +- Required exact Ruff 0.15.22 and unchanged docstring enforcement. +- Limited generated schema impact to description metadata from the three + Pydantic model docstrings; the helper docstring creates no schema metadata. + +## Plan Review + +PASS. The final L1 plan is narrow, testable, architecture-preserving, and +explicitly stopped pending a separate signed implementation start. + +## Reviewer Results + +| Reviewer | Result | Blocking findings | Notes | +|---|---:|---|---| +| senior engineering | PASS | None | Confirmed the minimal additive intake and one narrow successor. | +| QA/test | PASS | None | Confirmed exact scope, acceptance criteria, Ruff proof, and description-only schema effect. | +| security/auth | PASS | None | Confirmed no authorization behavior or gate weakening and preserved AUTH-11. | +| product/ops | PASS | None | Confirmed no Workstream product lifecycle, payment, or reputation changes. | +| architecture | PASS | None | Confirmed valid new-initiative intake and no architecture drift. | +| CI integrity | PASS WITH LOW RISKS | None | No CI file changes; exact Ruff and docstring gates pass unchanged. | +| docs | PASS | None | Confirmed accurate Pydantic/OpenAPI wording and complete planning docs. | +| reuse/dedup | PASS | None | Confirmed separate AUTH-002 is justified and no duplicate abstraction is introduced. | +| test delta | PASS | None | No tests, assertions, skips, or coverage controls change. | + +## Valid Findings Addressed + +- Committed the initially untracked review surface so reviewers and gates bind + the actual branch diff. +- Changed both contracts from P0 to the policy-correct P1 SLA. +- Replaced the inaccurate no-schema-change claim with an exact + description-metadata-only boundary. +- Distinguished the three Pydantic model descriptions from the helper + docstring, which does not enter generated schema. +- Added the exact Ruff 0.15.22 version assertion. +- Added test-delta review to the plan proof strategy. +- Added this aggregate review evidence and the adjacent PR trust bundle. + +## Commands Run + +```bash +python3 scripts/test_agent_gates.py +python3 scripts/update_post_merge_memory.py validate-merge-intent --base-ref origin/main +python3 scripts/check_markdown_links.py +python3 scripts/check_stale_workstream_wording.py +(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) +git diff --check origin/main...HEAD +``` + +All commands passed on the reviewed planning surface. The docstring tool passed +the unchanged 80 percent threshold at 84.3 percent overall while identifying +the four intended successor findings. + +## Remaining Risks + +- This PR does not fix the findings; it only establishes the reviewed and + signed boundary required to do so. +- `WS-AUTH-002-01` requires a separate explicit signed start after this intake + merges. +- PR #198 must consume the corrective implementation from trusted `main` and + rerun its exact-head checks. + +## Stop Condition + +The initiative remains stopped. No application implementation is authorized by +this planning-intake PR. diff --git a/.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/reviews/WS-AUTH-002-PLAN-pr-trust-bundle.md b/.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/reviews/WS-AUTH-002-PLAN-pr-trust-bundle.md new file mode 100644 index 00000000..d345914d --- /dev/null +++ b/.agent-loop/initiatives/WS-AUTH-002-authorization-docstring-lint-correction/reviews/WS-AUTH-002-PLAN-pr-trust-bundle.md @@ -0,0 +1,70 @@ +# PR Trust Bundle: WS-AUTH-002-PLAN + +## Chunk + +`WS-AUTH-002-PLAN` — Authorization Docstring Lint Correction Planning Intake + +## Intent and outcome + +Establish a narrow AUTH-owned corrective contract for four public-docstring +findings without weakening Ruff, docstring coverage, CI, or authorization +behavior. This PR is planning-only and does not apply the docstrings. + +## Design and scope + +- Adds exactly one new initiative planning tree and one merge intent. +- Names `WS-AUTH-002-01` as the same-initiative implementation successor. +- Leaves the initiative stopped and requires a separate explicit signed start. +- Preserves `WS-AUTH-001-11` as the unrelated project visibility cutover. +- Forbids runtime, schema structure, API structure, migration, test, workflow, + package, configuration, and gate changes. + +## Acceptance proof + +- The successor owns only `_reason`, `ProjectRoleGrantIssueBody`, + `ProjectRoleGrantRevokeBody`, and `ProjectRoleGrantMutationResponse` in one + AUTH schema module plus its evidence and merge intent. +- Exact Ruff 0.15.22 and the unchanged Ruff invocation pass. +- Unchanged docstring coverage passes at 84.3 percent overall. +- All 100 agent-gate regression tests pass. +- Merge-intent validation, Markdown links, stale wording, module compilation, + and whitespace checks pass. + +## Reviewer results + +Reviewed code SHA: 9b2677b01aee3842850292566ab8a4450cc6ba26 + +Reviewed at: 2026-07-25T09:06:31Z + +Open sub-agent sessions: none + +Valid findings addressed: yes + +| Reviewer | Result | +|---|---:| +| senior engineering | PASS | +| QA/test | PASS | +| security/auth | PASS | +| product/ops | PASS | +| architecture | PASS | +| CI integrity | PASS WITH LOW RISKS | +| docs | PASS | +| reuse/dedup | PASS | +| test delta | PASS | + +The CI low risk is informational: no CI file changes, and the exact existing +Ruff/docstring gates pass. There is no remaining blocking finding. + +## Remaining risks and sequence + +This planning PR intentionally leaves the four findings unresolved until its +successor is signed. After human-approved merge, dispatch `WS-AUTH-002-01`, +implement the four docstrings, run its full review/evidence loop, and merge that +corrective PR. Only then should PR #198 integrate trusted `main` and rerun +exact-head checks. + +## Human review focus + +Confirm the PR contains planning artifacts only, preserves AUTH-11, permits +exactly four docstrings, and cannot weaken Ruff or any CI/test gate. Only the +user may approve and merge this specific PR. diff --git a/.agent-loop/merge-intents/WS-AUTH-002-PLAN.json b/.agent-loop/merge-intents/WS-AUTH-002-PLAN.json new file mode 100644 index 00000000..e25f07d8 --- /dev/null +++ b/.agent-loop/merge-intents/WS-AUTH-002-PLAN.json @@ -0,0 +1,9 @@ +{ + "schema_version": 2, + "initiative_id": "WS-AUTH-002", + "chunk_id": "WS-AUTH-002-PLAN", + "chunk_title": "Authorization Docstring Lint Correction Planning Intake", + "next_chunk_id": "WS-AUTH-002-01", + "next_chunk_title": "Four Authorization Public Docstrings", + "next_requires_explicit_start": true +}