From ab16a1d7cf96f5e0dffc4c0b4ca7277f902b291b Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Sat, 25 Jul 2026 18:30:31 +0100 Subject: [PATCH 1/6] docs(auth): split project read cutover plan --- .../CHUNK_MAP.md | 16 +- .../DECISIONS.md | 34 ++++ .../DISCOVERY.md | 28 ++++ .../STATUS.md | 8 +- .../WS-AUTH-001-11-project-read-cutover.md | 158 ++++++++++-------- ...1-11A-project-read-catalogue-foundation.md | 90 ++++++++++ ...-001-11B-project-identity-actor-context.md | 92 ++++++++++ ...001-11C1-project-setup-diagnostic-reads.md | 91 ++++++++++ ...1C2-effective-policy-active-guide-reads.md | 89 ++++++++++ .agent-loop/merge-intents/WS-AUTH-001-11.json | 9 + 10 files changed, 538 insertions(+), 77 deletions(-) create mode 100644 .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11A-project-read-catalogue-foundation.md create mode 100644 .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11B-project-identity-actor-context.md create mode 100644 .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11C1-project-setup-diagnostic-reads.md create mode 100644 .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11C2-effective-policy-active-guide-reads.md create mode 100644 .agent-loop/merge-intents/WS-AUTH-001-11.json diff --git a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/CHUNK_MAP.md b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/CHUNK_MAP.md index d493e52c..2b7def8b 100644 --- a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/CHUNK_MAP.md +++ b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/CHUNK_MAP.md @@ -46,7 +46,11 @@ stopped. | `WS-AUTH-001-10B1` | Durable Authorization Read Rate Control | L1 | Proposed successor after 10B planning merge/memory | | `WS-AUTH-001-10B2` | Privacy-Safe Project Role Grant Reads | L1 | Proposed after 10B1 | | `WS-AUTH-001-10C` | Project Role Grant Mutations | L1 | Proposed after 10B2 | -| `WS-AUTH-001-11` | Project Identity, Guide, Source, And Visibility Cutover | L1 | Proposed | +| `WS-AUTH-001-11` | Project Read Cutover Planning Parent | L1 | Signed start run `30167274426`; planning split authored, no runtime implementation | +| `WS-AUTH-001-11A` | Project Read Catalogue And Projection Foundation | L1 | Proposed successor; migration `0035`, no active surface | +| `WS-AUTH-001-11B` | Project Identity And Actor Context Cutover | L1 | Proposed after 11A | +| `WS-AUTH-001-11C1` | Project Setup Diagnostic Read Cutover | L1 | Proposed after 11B | +| `WS-AUTH-001-11C2` | Effective Policy And Active Guide Read Cutover | L1 | Proposed after 11C1 | | `WS-AUTH-001-12` | Project Policy And Setup Mutation Cutover | L1 | Proposed | | `WS-AUTH-001-13` | Task Management And Assignment Cutover | L1 | Proposed | | `WS-AUTH-001-14` | Submission, Checker, And Audit Visibility Cutover | L1 | Proposed | @@ -114,6 +118,10 @@ WS-AUTH-001-PLAN -> WS-AUTH-001-10B2 -> WS-AUTH-001-10C -> WS-AUTH-001-11 +-> WS-AUTH-001-11A +-> WS-AUTH-001-11B +-> WS-AUTH-001-11C1 +-> WS-AUTH-001-11C2 -> WS-AUTH-001-12 -> WS-AUTH-001-13 -> WS-AUTH-001-14 @@ -152,7 +160,11 @@ WS-AUTH-001-PLAN transfer follows 09E and changes only owner metadata and availability-neutral parity. PREP then establishes AUTH-first locking and caller-owned commit before sensitive product/review mutations. -- Chunks 11-15 migrate bounded complete product/system surfaces. +- Parent chunk 11 is planning-only and splits the hard project-read cutover + into 11A catalogue/evidence, 11B identity/context, 11C1 setup diagnostics, + and 11C2 effective policy/guide reads. Each child removes token-role + authority from its complete surface family; no compatibility path remains. +- Chunks 12-15 migrate bounded complete product/system surfaces. - Artifact upload, read, retention, release/delete, replication, integrity, and reconciliation remain mechanically owned by the artifact subsystem but must receive centralized AUTH decisions. Chunk 07A owns the permission/action diff --git a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/DECISIONS.md b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/DECISIONS.md index a1a4f17a..d02a1838 100644 --- a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/DECISIONS.md +++ b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/DECISIONS.md @@ -743,3 +743,37 @@ and missing or cross-project grants have one identical public response. No route catches and discards `AuthorizationDenied`, no response exposes a total, and no candidate or grant row is queried before canonical resolution and authorization succeed. AUTH-10C follows only after 10B2. + +## D34: Split project-read catalogue, identity, diagnostics, and effective views + +Status: accepted planning resolution on 2026-07-25 after exact AUTH-11 surface +discovery. + +AUTH-11 becomes a planning-only parent. The current project API has ten GET +routes and no project collection/list route. The promised self authorization- +context route does not yet exist. The inherited contract also combined minimal +contributor identity, sensitive setup diagnostics, and composite guide/policy +responses, which cannot share one safe disclosure rule. + +AUTH-11 therefore splits into four sequential same-initiative children. 11A +registers eleven planned actions and owns migration `0035`; it activates no +surface. 11B activates exact-project identity and introduces the self +authorization-context surface. 11C1 activates setup and draft diagnostic +reads. 11C2 activates effective policy and active-guide reads with an explicit +principal-specific projection. Every activated surface is a hard cutover from +token roles to local grants; no fallback, alias, or dual authorization path is +allowed. + +Project identity and active-guide actions use the existing `project.read` +permission. 11A adds the narrow read-only `project.setup_diagnostic.read` and +`project.effective_policy.read` permissions for Project Manager, Operator, and +Audit Authority under their existing scopes. Finance Authority and Access +Administrator do not receive them. The actor-context action uses the existing +self-profile read permission. Active exact-project +submitter, reviewer, and adjudicator grants imply only the minimal project +identity projection unless a later child explicitly proves a narrower safe +active-guide view. Contributors do not receive diagnostic/policy access from +`project.read`; authority derives from the registered permission/scope matrix, +never token roles. This preserves the operating requirement that Operator and +Audit inspect setup through authorized API projections rather than direct +database access without conflating read authority with management. diff --git a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/DISCOVERY.md b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/DISCOVERY.md index 2755a021..d1c24e25 100644 --- a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/DISCOVERY.md +++ b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/DISCOVERY.md @@ -390,3 +390,31 @@ need an independently reviewable contract and production-code budget. - New service identities require an exact owning-feature manifest, closed enum and matrix extension, database constraint migration, controlled provisioning, AUTH-09E admission reuse, and cross-service negative proof. + +## AUTH-11 exact project-read delta (2026-07-25) + +- The current project router exposes ten GET routes and no project collection + or list route. The inherited count/cursor requirement therefore described no + existing surface and is removed. +- All ten reads currently rely on `require_any_role()` with token roles + `admin` or `project_manager`; none has a registered primary project-read + ActionId declaration. +- `GET /api/v1/actors/me/authorization-context?project_id=...` is intentionally + absent today and remains AUTH-11 work carried forward from D32. +- The current Alembic head is `0034_project_role_issue_evidence`; the next + available migration for the project-read action-evidence delta is `0035`. +- `PermissionId.PROJECT_READ` and `PermissionId.ACTOR_PROFILE_READ_SELF` + already exist. Existing guide/effective-policy permissions are management + authorities and cannot accurately represent read-only Operator/Audit + inspection. 11A therefore adds exactly two read permissions for setup + diagnostics and effective policy, preventing generic project-read holders + from inheriting sensitive data or read consumers from inheriting mutations. +- Project identity is a minimal response suitable for an active exact-project + contributor grant. Setup runs, sufficiency reports, draft artifact policies, + checker setup, and the existing composite active-guide response include + diagnostics, provenance, configuration, or payment data and cannot inherit + that contributor disclosure rule. +- The safe boundary is four sequential chunks: planned catalogue/evidence; + identity plus self context; admin-only setup diagnostics; and effective + policy/active-guide projection. Each runtime child hard-removes token-role + authority from every surface it owns. diff --git a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/STATUS.md b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/STATUS.md index 587663f9..ad326c31 100644 --- a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/STATUS.md +++ b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/STATUS.md @@ -111,7 +111,7 @@ or consumer feature action is active. ## Active planning chunk -None. `WS-AUTH-001-XINT` merged through PR #140. +None. ## Active implementation chunk @@ -156,7 +156,11 @@ None. | `WS-AUTH-001-REV-CUSTODY` | Merged | `codex/ws-auth-001-rev-custody` | #160 | Merged as `fe0e4492` on 2026-07-20; all 19 REV actions remain planned. | | `WS-AUTH-001-PREP` | Merged | `codex/ws-auth-001-prep` | #162 | Merged as `c559d556` on 2026-07-21; adds no feature consumer or activation. | | `WS-AUTH-001-10` | Proposed | - | - | Project contributor grants. | -| `WS-AUTH-001-11` | Proposed | - | - | Project identity/guide/source/read cutover. | +| `WS-AUTH-001-11` | Planning split authored | `codex/ws-auth-001-11-project-read-cutover` | - | Exact hard-cutover inventory split into 11A, 11B, 11C1, and 11C2; signed automation remains the live-state authority. | +| `WS-AUTH-001-11A` | Proposed | - | - | Project-read action catalogue and migration `0035`; no activation. | +| `WS-AUTH-001-11B` | Proposed | - | - | Project identity and self authorization-context cutover. | +| `WS-AUTH-001-11C1` | Proposed | - | - | Setup and draft diagnostic read cutover. | +| `WS-AUTH-001-11C2` | Proposed | - | - | Effective policy and active-guide read cutover. | | `WS-AUTH-001-12` | Proposed | - | - | Project policy/setup mutation cutover. | | `WS-AUTH-001-13` | Proposed | - | - | Task management and assignment cutover. | | `WS-AUTH-001-14` | Proposed | - | - | Submission/checker/audit visibility cutover. | diff --git a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11-project-read-cutover.md b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11-project-read-cutover.md index bfcb2c69..0d3720c5 100644 --- a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11-project-read-cutover.md +++ b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11-project-read-cutover.md @@ -1,9 +1,13 @@ -# Chunk Contract: WS-AUTH-001-11 - Project Identity, Guide, Source, And Visibility Cutover +# Chunk Contract: WS-AUTH-001-11 - Project Read Cutover Planning Parent ## Status -Proposed and inactive. The exact project read/list ActionId inventory and -then-current migration mapping delta must be added before implementation review. +Planning-only parent authorized by successful signed explicit-start workflow +run `30167274426` on exact trusted-main SHA +`bba4ba5f171a4438b072740707a5cf8bde49d9af`. Runtime implementation is +prohibited. Signed automation remains the live-state authority; authored +`STATUS.md` does not mirror conversational activity. This chunk defines the +complete hard-cutover inventory and four separately started L1 children. ## Parent initiative @@ -11,14 +15,16 @@ then-current migration mapping delta must be added before implementation review. ## Goal -Move project identity reads, guide/source reads, setup-status visibility, and -policy-summary queries from token roles to scoped local permissions without -changing project setup mutations. +Replace token-role authorization on every current project GET surface with +registered local authority, without retaining a fallback or changing project +mutations. This parent resolves the design and sequencing only. ## Why this chunk exists -Separating query/visibility cutover from policy mutations keeps project -authorization reviewable and proves anti-IDOR filtering before write cutover. +The inherited contract combined catalogue migration, a new actor-context API, +minimal contributor projection, and sensitive setup/policy/guide disclosures. +Those boundaries need independent evidence and review. The split preserves a +hard cutover while keeping each runtime change reviewable. ## Approved plan reference @@ -37,85 +43,89 @@ P1 ## Allowed files ```text -backend/app/modules/projects/router.py -backend/app/modules/projects/service.py -backend/app/modules/projects/repository.py -backend/app/modules/projects/schemas.py -backend/app/modules/authorization/** -backend/app/modules/audit/** -backend/alembic/versions/_*.py -backend/app/api/deps/auth.py -backend/tests/test_projects.py -backend/tests/test_auth.py -backend/tests/test_alembic.py -backend/scripts/api_contract_e2e.py -docs/operations_authorization_service.md .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/** .agent-loop/merge-intents/WS-AUTH-001-11.json -.agent-loop/LOOP_STATE.md -.agent-loop/WORK_QUEUE.md -.agent-loop/REVIEW_LOG.md ``` ## Not allowed ```text -project create/update, guide/source mutation, policy approval, activation +backend/** +runtime authorization or route changes +permission or action activation +compatibility aliases, token-role fallback, or dual authorization paths +project create/update, guide/source mutation, policy approval, or activation task/submission/checker authorization -issuer-role fallback or authorization pagination after unfiltered counts ``` +## Exact surface and action inventory + +Targets preserve the current project/guide/child-resource hierarchy. Project +identity and active-guide actions map to existing `PermissionId.PROJECT_READ`. +11A introduces the read-only `project.setup_diagnostic.read` and +`project.effective_policy.read` permissions so inspection never borrows a +management permission. Project Manager, Operator, and Audit Authority receive +those permissions under their existing scopes; Finance Authority, Access +Administrator, and contributor grants do not. The actor-context action maps to +existing `PermissionId.ACTOR_PROFILE_READ_SELF`. + +| ActionId | Surface | Target and principal boundary | Child | +|---|---|---|---| +| `project.read` | `GET /api/v1/projects/{project_id}` | exact project; eligible admin grants or active exact-project submitter/reviewer/adjudicator grant | 11B | +| `actor.authorization_context.read` | new `GET /api/v1/actors/me/authorization-context?project_id=...` | self actor plus canonical project; disclose only effective caller authority for that project | 11B | +| `project.setup_run.read` | `GET /api/v1/projects/{project_id}/guides/{guide_id}/setup-runs/latest` | exact project and child guide/version/setup run; `project.setup_diagnostic.read` | 11C1 | +| `project.guide_sufficiency_report.list` | `GET /api/v1/projects/{project_id}/guides/{guide_id}/sufficiency-reports` | exact project and child guide/version; `project.setup_diagnostic.read` | 11C1 | +| `project.guide_sufficiency_report.read` | `GET /api/v1/projects/{project_id}/guides/{guide_id}/sufficiency-reports/{report_id}` | exact project, guide/version, and child report; `project.setup_diagnostic.read` | 11C1 | +| `project.submission_artifact_policy.list` | `GET /api/v1/projects/{project_id}/guides/{guide_id}/submission-artifact-policies` | exact project and child guide/version; `project.effective_policy.read` | 11C1 | +| `project.submission_artifact_policy.read` | `GET /api/v1/projects/{project_id}/guides/{guide_id}/submission-artifact-policies/{policy_id}` | exact project, guide/version, and child policy; `project.effective_policy.read` | 11C1 | +| `project.post_submit_checker_policy_setup.read` | `GET /api/v1/projects/{project_id}/guides/{guide_id}/post-submit-checker-policy/setup` | exact project and child guide/version; `project.effective_policy.read` | 11C1 | +| `project.effective_submission_artifact_policy.read` | `GET /api/v1/projects/{project_id}/guides/{guide_id}/effective-submission-artifact-policy` | exact project and child guide/version; `project.effective_policy.read` | 11C2 | +| `project.pre_submit_checker_policy.read` | `GET /api/v1/projects/{project_id}/guides/{guide_id}/pre-submit-checker-policy` | exact project and child guide/version; `project.effective_policy.read` | 11C2 | +| `project.active_guide.read` | `GET /api/v1/projects/{project_id}/active-guide` | exact project; explicit safe projection by principal class | 11C2 | + +There is no project collection/list route in the current API. Count/cursor +criteria from the inherited contract are removed rather than inventing a new +surface. + +## Child sequence + +1. `WS-AUTH-001-11A` registers the eleven actions as planned, adds action-aware + evidence parity in migration `0035`, and activates no route. +2. `WS-AUTH-001-11B` activates project identity and the new self authorization + context. It defines the minimal contributor projection and concealed + exact-project denial. +3. `WS-AUTH-001-11C1` hard-cuts the six setup and draft diagnostic reads to + admin-grant authority. +4. `WS-AUTH-001-11C2` hard-cuts the three effective policy/guide reads and + defines any contributor-safe active-guide projection explicitly. + +Each child requires its own signed explicit start. No child may preserve +`require_any_role()` or token roles on any surface it activates. + ## Acceptance criteria -- Project Managers read only covered projects; system scope covers all projects - only for registered Project Manager permissions. -- Operator, Finance Authority, and Audit Authority receive only their defined - minimal project views. -- Access Administrator and contributor grants do not imply project-management - visibility. -- An active submitter, reviewer, or adjudicator grant independently allows the - minimal `project.read` projection for its exact project, without management - fields or permissions. Each role has exact-project allow, cross-project deny, - minimal-field, concealed-not-found, and pre-filtered count/cursor tests. -- The adjudicator grant supplies no adjudication action in this chunk; it adds - only the same minimal exact-project read projection. -- One actor may hold all three rows. A decision records the exact matched grant, - never a synthetic combined role. Revoking one role preserves minimal - `project.read` when another eligible exact-project role remains, and changes - no AdminRoleGrant. -- Canonical project scope is resolved before filtering, counts, and cursors. -- Every migrated project read/list route declares one primary registered action - and its canonical project or collection-parent target; permission strings and - secondary role policy do not live in the router. -- Generated OpenAPI/command manifest-delta tests prove every protected project - read/list surface migrated here has exactly one active `ActionId` declaration. -- Before runtime edits, the contract enumerates every new ActionId, existing - PermissionId mapping, canonical target, principal class, facts, guards, and - surface. The then-current migration updates typed/PostgreSQL action-evidence parity and - proves prior-head upgrade, downgrade, re-upgrade, and fresh replay. -- ProjectRepository remains the canonical project/guide/source persistence - query owner and returns domain records. The project application service or a - feature-owned resource loader composes ResourceContext; persistence does not - depend on authorization DTOs, and authorization does not re-query project - tables through a parallel repository. -- Hidden project/resource existence is not leaked through errors or totals. -- No migrated query uses `require_any_role()` or token roles. -- Full backend suite and API contract drill pass. +- The complete current project GET inventory and the deferred actor-context + surface are assigned exactly once. +- Generated OpenAPI/route-manifest proof matches every literal existing path to + exactly one action owner and includes project, guide, and child identifiers. +- Every action has an exact PermissionId mapping, canonical target, + principal boundary, owning child, and disclosure boundary. +- The current migration head `0034_project_role_issue_evidence` is recorded; + AUTH-11A alone reserves `0035` for the two new read permissions, exact role + mappings, action registration, and evidence parity. +- The four child contracts state hard-cutover, concealment, evidence, + migration, and verification requirements without compatibility behavior. +- This parent changes no runtime or feature availability. +- The merge intent names only `WS-AUTH-001-11A` as the same-initiative + successor; it does not start that child. ## Verification commands ```bash -(cd backend && .venv/bin/python -m ruff check app tests scripts) -(cd backend && WORKSTREAM_DATABASE_URL= .venv/bin/python -m pytest -q \ - tests/test_authorization.py tests/test_auth.py tests/test_projects.py \ - --cov=app.modules.authorization --cov-report=term-missing --cov-fail-under=90) -(cd backend && WORKSTREAM_DATABASE_URL= .venv/bin/python -m pytest -q) -(cd backend && WORKSTREAM_DATABASE_URL= .venv/bin/python scripts/api_contract_e2e.py) -(cd backend && WORKSTREAM_DATABASE_URL= .venv/bin/alembic upgrade head) -(cd backend && WORKSTREAM_DATABASE_URL= .venv/bin/alembic downgrade -1) -(cd backend && WORKSTREAM_DATABASE_URL= .venv/bin/alembic upgrade head) +python3 scripts/update_post_merge_memory.py validate-merge-intent --base-ref origin/main python3 scripts/check_stale_workstream_wording.py python3 scripts/check_markdown_links.py +python3 scripts/test_agent_gates.py git diff --check ``` @@ -133,10 +143,12 @@ git diff --check ## Human review focus -Review query scope, minimal disclosure, pagination/count concealment, and that -mutation behavior is untouched. +Review the exact action ownership, the absence of token-role fallback, the +contributor/admin disclosure split, and whether the four children are bounded +enough for independent L1 proof. ## Stop conditions -Stop if safe query cutover requires changing setup mutations or accepting a -token-role fallback. +Stop if any current GET route is unowned, if a child requires dual authority, +or if safe contributor disclosure cannot be specified without changing a +mutation or another product subsystem. diff --git a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11A-project-read-catalogue-foundation.md b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11A-project-read-catalogue-foundation.md new file mode 100644 index 00000000..f740e726 --- /dev/null +++ b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11A-project-read-catalogue-foundation.md @@ -0,0 +1,90 @@ +# Chunk Contract: WS-AUTH-001-11A - Project Read Catalogue And Projection Foundation + +## Status + +Proposed and inactive. Requires a separate signed explicit start. + +## Goal + +Register the eleven AUTH-11 actions as planned and establish typed projection +contracts without activating any API route. + +## Risk and SLA + +L1 / P1 + +## Allowed files + +```text +backend/app/modules/authorization/** +backend/app/modules/audit/** +backend/alembic/versions/0035_project_read_action_evidence.py +backend/tests/test_authorization.py +backend/tests/test_alembic.py +docs/operations_authorization_service.md +docs/operations_roles_permissions.md +docs/spec_authorization_service.md +.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/** +.agent-loop/merge-intents/WS-AUTH-001-11A.json +``` + +## Not allowed + +```text +backend/app/modules/projects/** +backend/app/modules/actors/router.py +route activation or token-role changes +compatibility aliases or fallback paths +``` + +## Acceptance criteria + +- Register exactly the eleven actions enumerated by parent AUTH-11, initially + unavailable and owned by 11B, 11C1, or 11C2 as assigned there. +- Add exactly `PROJECT_SETUP_DIAGNOSTIC_READ` and + `PROJECT_EFFECTIVE_POLICY_READ`. Grant both to Project Manager, Operator, and + Audit Authority under their existing compatible scopes; do not grant them to + Finance Authority, Access Administrator, or contributor roles. +- Map project identity and active guide to existing `PROJECT_READ`, setup and + sufficiency diagnostics to `PROJECT_SETUP_DIAGNOSTIC_READ`, draft/effective + policy reads to `PROJECT_EFFECTIVE_POLICY_READ`, and actor context to the + existing self-profile read permission. +- Define only AUTH-owned action/resource-context contracts here. Product + response projections remain with their owning 11B/11C application layers. +- Migration `0035` adds the two typed/PostgreSQL permissions, exact role + mappings, and action-evidence parity and proves upgrade from `0034`, + downgrade, re-upgrade, and fresh replay. +- Typed and PostgreSQL matrix tests prove both permissions for Project Manager, + system Operator, and covered Audit Authority, and prove their absence for + Finance Authority, Access Administrator, and all contributor roles. +- Generated action/permission/owner parity tests pass and no route becomes + available. +- Authorization spec and operations/role documentation describe both new + permissions, exact role/scope mappings, planned action owners, and continued + unavailability. + +## Verification + +```bash +(cd backend && .venv/bin/python -m ruff check app tests scripts) +(cd backend && WORKSTREAM_DATABASE_URL= .venv/bin/python -m pytest -q tests/test_authorization.py tests/test_alembic.py --cov=app.modules.authorization --cov-report=term-missing --cov-fail-under=90) +(cd backend && WORKSTREAM_DATABASE_URL= .venv/bin/alembic upgrade head) +(cd backend && WORKSTREAM_DATABASE_URL= .venv/bin/alembic downgrade -1) +(cd backend && WORKSTREAM_DATABASE_URL= .venv/bin/alembic upgrade head) +python3 scripts/test_agent_gates.py +git diff --check +``` + +Hosted `Backend / test` is mandatory before merge and must preserve the full +semantic lanes, API E2E, repository-wide 78 percent floor, and applicable +authorization subsystem 90 percent floor. + +## Required reviewers + +Senior engineering, QA/test, security/auth, product/ops, architecture, CI +integrity, docs, reuse/dedup, and test delta. + +## Stop conditions + +Stop if registration requires route activation, any permission beyond the two +explicitly named read permissions, or edits to historical migrations. diff --git a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11B-project-identity-actor-context.md b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11B-project-identity-actor-context.md new file mode 100644 index 00000000..6f314032 --- /dev/null +++ b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11B-project-identity-actor-context.md @@ -0,0 +1,92 @@ +# Chunk Contract: WS-AUTH-001-11B - Project Identity And Actor Context Cutover + +## Status + +Proposed and inactive after 11A. Requires a separate signed explicit start. + +## Goal + +Hard-cut project identity reads to local grants and add a self authorization- +context query that reports only the caller's effective authority for one +canonical project. + +## Risk and SLA + +L1 / P1 + +## Allowed files + +```text +backend/app/modules/projects/** +backend/app/api/routes/auth.py +backend/app/api/router.py +backend/app/modules/actors/** +backend/app/modules/authorization/** +backend/app/modules/audit/** +backend/tests/test_projects.py +backend/tests/test_auth.py +backend/tests/test_authorization.py +backend/scripts/api_contract_e2e.py +.github/workflows/backend.yml +docs/operations_authorization_service.md +docs/operations_roles_permissions.md +docs/operations_project_operating_manual.md +docs/spec_authorization_service.md +.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/** +.agent-loop/merge-intents/WS-AUTH-001-11B.json +``` + +## Not allowed + +```text +project mutation or setup/policy/guide routes +token-role fallback or dual authorization +grant mutation +project collection/list API +``` + +## Acceptance criteria + +- Activate only `project.read` and `actor.authorization_context.read`. +- Resolve the canonical project before authorization; unknown, cross-project, + unauthorized, inactive-grant, and out-of-scope requests are concealed by the + action-aware public denial contract. +- Eligible scoped admin grants receive the registered project identity view. + Active exact-project submitter, reviewer, and adjudicator grants independently + receive only the minimal project identity projection. +- The context response is self-only, exact-project, derived from current local + grants and action availability, and cannot advertise planned/inactive actions. +- Routers declare one primary ActionId and target; policy stays in the kernel or + feature policy layer. Both routes contain no `require_any_role()` or token- + role authority after cutover. +- Exact-project allow, cross-project deny, role revocation independence, + minimal-field, concealed-not-found, audit, invalidation, and live API tests + pass. +- Authorization spec, role matrix, project operating manual, and authorization + operations docs describe the new context route/schema, project projections, + concealed denial, and hard removal of token-role authority. + +## Verification + +```bash +(cd backend && .venv/bin/python -m ruff check app tests scripts) +(cd backend && WORKSTREAM_DATABASE_URL= .venv/bin/python -m pytest -q tests/test_authorization.py tests/test_auth.py tests/test_projects.py --cov=app.modules.authorization --cov=app.modules.actors --cov=app.modules.projects --cov-report=term-missing --cov-fail-under=90) +(cd backend && WORKSTREAM_DATABASE_URL= .venv/bin/python scripts/api_contract_e2e.py) +python3 scripts/test_agent_gates.py +git diff --check +``` + +Hosted `Backend / test` is mandatory before merge and must preserve the full +semantic lanes, API E2E, repository-wide 78 percent floor, and applicable +actor/authorization subsystem 90 percent floors. This child adds a protected +`app/modules/projects/*` 90 percent coverage report to that hosted gate. + +## Required reviewers + +Senior engineering, QA/test, security/auth, product/ops, architecture, CI +integrity, docs, reuse/dedup, and test delta. + +## Stop conditions + +Stop if safe context derivation requires exposing raw grants or if either route +would retain token-role authority. diff --git a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11C1-project-setup-diagnostic-reads.md b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11C1-project-setup-diagnostic-reads.md new file mode 100644 index 00000000..df983341 --- /dev/null +++ b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11C1-project-setup-diagnostic-reads.md @@ -0,0 +1,91 @@ +# Chunk Contract: WS-AUTH-001-11C1 - Project Setup Diagnostic Read Cutover + +## Status + +Proposed and inactive after 11B. Requires a separate signed explicit start. + +## Goal + +Hard-cut the six setup and draft diagnostic GET surfaces assigned by AUTH-11 +from token roles to scoped administrative grants. + +## Risk and SLA + +L1 / P1 + +## Allowed files + +```text +backend/app/modules/projects/** +backend/app/modules/authorization/** +backend/app/modules/audit/** +backend/tests/test_projects.py +backend/tests/test_authorization.py +backend/scripts/api_contract_e2e.py +.github/workflows/backend.yml +docs/operations_authorization_service.md +docs/operations_roles_permissions.md +docs/operations_project_operating_manual.md +docs/spec_authorization_service.md +.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/** +.agent-loop/merge-intents/WS-AUTH-001-11C1.json +``` + +## Not allowed + +```text +project or policy mutation +project identity, actor-context, effective-policy, or active-guide routes +contributor access to setup diagnostics +token-role fallback or dual authorization +``` + +## Acceptance criteria + +- Activate exactly the six 11C1 actions listed in the parent contract. +- Canonical project and child-resource ownership are resolved before disclosure; + unauthorized, nonexistent, and cross-project resources share the action-aware + concealed public response. +- Same-project cross-guide identifiers and report/policy identifiers bound to a + different guide are denied with that same concealed response. +- Setup/sufficiency actions require `PROJECT_SETUP_DIAGNOSTIC_READ`; policy + and checker-setup actions require `PROJECT_EFFECTIVE_POLICY_READ`. Covered + Project Manager and Audit Authority grants and system Operator grants allow + their read-only projections. Finance Authority, Access Administrator, and + contributor grants deny. No read permission implies a mutation permission. +- ProjectRepository remains persistence owner and returns domain records; the + application layer composes authorization context without a parallel project + repository in AUTH. +- Every migrated route declares exactly one primary action and contains no + `require_any_role()` or token-role authorization. +- Per-action scope, child-binding, concealed-denial, audit, invalidation, and + live API contract tests pass, including positive Project Manager/Operator/ + Audit and negative Finance/Access Administrator/contributor cases. +- Authorization spec, role matrix, project operating manual, and authorization + operations docs match the six action mappings, read-only projections, + concealment behavior, and removal of token-role authority. + +## Verification + +```bash +(cd backend && .venv/bin/python -m ruff check app tests scripts) +(cd backend && WORKSTREAM_DATABASE_URL= .venv/bin/python -m pytest -q tests/test_authorization.py tests/test_projects.py --cov=app.modules.authorization --cov=app.modules.projects --cov-report=term-missing --cov-fail-under=90) +(cd backend && WORKSTREAM_DATABASE_URL= .venv/bin/python scripts/api_contract_e2e.py) +python3 scripts/test_agent_gates.py +git diff --check +``` + +Hosted `Backend / test` is mandatory before merge and must preserve the full +semantic lanes, API E2E, repository-wide 78 percent floor, and applicable +authorization subsystem 90 percent floor. The protected +`app/modules/projects/*` 90 percent report introduced by 11B remains mandatory. + +## Required reviewers + +Senior engineering, QA/test, security/auth, product/ops, architecture, CI +integrity, docs, reuse/dedup, and test delta. + +## Stop conditions + +Stop if a diagnostic surface cannot be concealed without changing its mutation +lifecycle or if any route would retain token-role authority. diff --git a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11C2-effective-policy-active-guide-reads.md b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11C2-effective-policy-active-guide-reads.md new file mode 100644 index 00000000..01b0d2a9 --- /dev/null +++ b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11C2-effective-policy-active-guide-reads.md @@ -0,0 +1,89 @@ +# Chunk Contract: WS-AUTH-001-11C2 - Effective Policy And Active Guide Read Cutover + +## Status + +Proposed and inactive after 11C1. Requires a separate signed explicit start. + +## Goal + +Hard-cut effective artifact policy, pre-submit checker policy, and active-guide +reads to local authority with explicit principal-specific disclosure. + +## Risk and SLA + +L1 / P1 + +## Allowed files + +```text +backend/app/modules/projects/** +backend/app/modules/authorization/** +backend/app/modules/audit/** +backend/tests/test_projects.py +backend/tests/test_authorization.py +backend/scripts/api_contract_e2e.py +.github/workflows/backend.yml +docs/operations_authorization_service.md +docs/operations_roles_permissions.md +docs/operations_project_operating_manual.md +docs/spec_authorization_service.md +.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/** +.agent-loop/merge-intents/WS-AUTH-001-11C2.json +``` + +## Not allowed + +```text +project, guide, source, or policy mutation +setup diagnostic or actor-context routes +raw payment or internal diagnostic disclosure to contributors +token-role fallback or dual authorization +``` + +## Acceptance criteria + +- Activate exactly the three 11C2 actions listed in the parent contract. +- Effective policy actions require `PROJECT_EFFECTIVE_POLICY_READ`; covered + Project Manager/Audit grants and system Operator grants receive only their + read projections, while Finance and Access Administrator grants deny. + Active-guide access requires `PROJECT_READ` plus its principal-specific + projection. Any contributor access to active-guide content requires an explicit + response schema that omits payment, provenance, draft setup, and internal + diagnostic fields; absence of such a proven schema means contributors deny. +- Effective policy queries cannot reveal draft or cross-project configuration. +- Same-project cross-guide identifiers are denied with the same concealed + response as unauthorized and nonexistent resources. +- Canonical project resolution and authorization precede sensitive assembly; + concealed denial is identical for unauthorized and nonexistent resources. +- Every migrated route declares exactly one primary action and contains no + `require_any_role()` or token-role authorization. +- Principal-specific field allowlists, scope, concealed denial, audit, + invalidation, and live API contract tests pass. +- Authorization spec, role matrix, project operating manual, and authorization + operations docs match effective-policy and active-guide schemas, principal + projections, concealment, and removal of token-role authority. + +## Verification + +```bash +(cd backend && .venv/bin/python -m ruff check app tests scripts) +(cd backend && WORKSTREAM_DATABASE_URL= .venv/bin/python -m pytest -q tests/test_authorization.py tests/test_projects.py --cov=app.modules.authorization --cov=app.modules.projects --cov-report=term-missing --cov-fail-under=90) +(cd backend && WORKSTREAM_DATABASE_URL= .venv/bin/python scripts/api_contract_e2e.py) +python3 scripts/test_agent_gates.py +git diff --check +``` + +Hosted `Backend / test` is mandatory before merge and must preserve the full +semantic lanes, API E2E, repository-wide 78 percent floor, and applicable +authorization subsystem 90 percent floor. The protected +`app/modules/projects/*` 90 percent report introduced by 11B remains mandatory. + +## Required reviewers + +Senior engineering, QA/test, security/auth, product/ops, architecture, CI +integrity, docs, reuse/dedup, and test delta. + +## Stop conditions + +Stop if contributor-safe projection cannot be proven or if cutover requires a +mutation, compatibility response, or token-role authority. diff --git a/.agent-loop/merge-intents/WS-AUTH-001-11.json b/.agent-loop/merge-intents/WS-AUTH-001-11.json new file mode 100644 index 00000000..0611666e --- /dev/null +++ b/.agent-loop/merge-intents/WS-AUTH-001-11.json @@ -0,0 +1,9 @@ +{ + "chunk_id": "WS-AUTH-001-11", + "chunk_title": "Project Read Cutover Planning Parent", + "initiative_id": "WS-AUTH-001", + "next_chunk_id": "WS-AUTH-001-11A", + "next_chunk_title": "Project Read Catalogue And Projection Foundation", + "next_requires_explicit_start": true, + "schema_version": 2 +} From 00881971894c19d5b57512e2352e04bfa073c804 Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Sat, 25 Jul 2026 19:07:05 +0100 Subject: [PATCH 2/6] docs(auth): record AUTH-11 review evidence --- ...WS-AUTH-001-11-internal-review-evidence.md | 74 ++++++++++++++ .../reviews/WS-AUTH-001-11-pr-trust-bundle.md | 97 +++++++++++++++++++ 2 files changed, 171 insertions(+) create mode 100644 .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-internal-review-evidence.md create mode 100644 .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-pr-trust-bundle.md diff --git a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-internal-review-evidence.md b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-internal-review-evidence.md new file mode 100644 index 00000000..943a716c --- /dev/null +++ b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-internal-review-evidence.md @@ -0,0 +1,74 @@ +# WS-AUTH-001-11 Internal Review Evidence + +Reviewed code SHA: `ab16a1d7cf96f5e0dffc4c0b4ca7277f902b291b` + +Reviewed planning SHA: `ab16a1d7cf96f5e0dffc4c0b4ca7277f902b291b` + +Reviewed against trusted main: `03a05eeb8f129e0d5f226cc5c058965f43590a81` + +Reviewed at: `2026-07-25T18:55:00Z` + +Reviewer run IDs: `auth11_senior`, `auth11_qa`, `auth11_security`, +`auth11_product`, `auth11_arch`, `auth11_ci`, `auth11_docs`, `auth11_reuse`, +and `auth11_testdelta` + +Reviewer tracks: senior engineering, QA/test, security/auth, product/ops, +architecture, CI integrity, docs, reuse/dedup, and test delta + +## Scope + +AUTH-11 is a planning-only parent. It inventories ten existing project GET +surfaces plus one deferred self authorization-context route, records D34, and +splits runtime work into 11A, 11B, 11C1, and 11C2. It changes no runtime, +migration, route, test, workflow, action availability, or product behavior. + +## Deterministic evidence + +- Merge-intent validation: PASS for `WS-AUTH-001-11`; only 11A is named and a + fresh explicit start is required. +- Stale Workstream wording: PASS. +- Markdown links: PASS for all nine changed Markdown files. +- Agent gates: PASS, 100 tests. +- `git diff --check`: PASS. +- Changed files remain inside the planning-parent allowed paths. +- No CI, package, test, dependency, coverage threshold, or skip changed. + +## Reviewer results + +| Reviewer | Result | Blocking findings | Notes | +|---|---|---|---| +| senior engineering | PASS AFTER FIXES | none | Literal routes, actor-route ownership, executable commands, and child stop conditions are exact. | +| QA/test | PASS AFTER FIXES | none | Cross-project, cross-guide, child binding, role matrix, OpenAPI, migration, and hosted proof are testable. | +| security/auth | PASS AFTER FIXES | none | No token-role fallback; permissions and projections preserve least privilege. | +| product/ops | PASS AFTER FIXES | none | Read-only Operator/Audit API inspection remains available without database access or mutation authority. | +| architecture | PASS AFTER FIXES | none | Catalogue, project application, repository, actor route, and child ownership boundaries are coherent. | +| CI integrity | PASS AFTER FIXES | none | Hosted full suite, 78 percent global, and applicable 90 percent subsystem floors remain mandatory. | +| docs | PASS AFTER FIXES | none | Every runtime child names required authorization, role, and project operations documentation. | +| reuse/dedup | PASS | none | Existing catalogue, policy matrix, resource-context, kernel, and project repository patterns remain canonical. | +| test delta | PASS | none | Planning parent changes no tests or thresholds; child proof requirements strengthen coverage. | + +## Findings resolved + +The first review rejected invented project-only paths that omitted `guide_id`, +an unavailable actor router path, a nonexistent merge-intent command, and broad +reuse of `project.read` for sensitive data. Repairs now use literal mounted +paths and project/guide/child bindings, the existing auth router composition, +the canonical validator, and two narrow read-only permissions. + +Product review then identified that denying Operator/Audit would force setup +inspection outside the API. 11A now introduces exactly +`project.setup_diagnostic.read` and `project.effective_policy.read` for Project +Manager, system Operator, and covered Audit Authority. Finance Authority, +Access Administrator, and contributors deny. Read access never implies +management. Final contract consistency, role-matrix proof, documentation, and +signed-state wording findings were repaired and re-reviewed at the exact SHA. + +Valid findings addressed: yes + +Open sub-agent sessions: none after evidence publication + +## Remaining gate + +GitHub Agent Gates, external CodeRabbit review, and explicit human review remain. +After merge, signed memory must stop with 11A named but inactive; 11A requires a +fresh protected explicit start on exact current `main`. diff --git a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-pr-trust-bundle.md b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-pr-trust-bundle.md new file mode 100644 index 00000000..3e5bf2fa --- /dev/null +++ b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-pr-trust-bundle.md @@ -0,0 +1,97 @@ +# WS-AUTH-001-11 PR Trust Bundle + +## Chunk + +`WS-AUTH-001-11` — Project Read Cutover Planning Parent + +Merge intent: `.agent-loop/merge-intents/WS-AUTH-001-11.json` + +## Goal and human-approved intent + +Replace token-role authority on the project read surface with local grants as a +hard cutover. The user explicitly rejected backward compatibility and approved +starting AUTH-11. Signed explicit-start workflow run `30167274426` succeeded. + +## What changed and why + +- D34 makes AUTH-11 planning-only and assigns one complete surface family to + each of 11A, 11B, 11C1, and 11C2. +- The inventory matches all ten current project GET routes and the deferred + self authorization-context route, including project/guide/child bindings. +- 11A registers eleven actions and adds two read-only permissions plus role and + evidence parity in migration `0035`, without route activation. +- 11B cuts over project identity and self authorization context. +- 11C1 cuts over six setup/draft diagnostic reads. +- 11C2 cuts over three effective-policy/active-guide reads. + +## Design chosen + +Project identity continues to use `project.read`. Setup diagnostics and +effective policy receive distinct read-only permissions so Project Manager, +system Operator, and covered Audit Authority can inspect through safe API +projections without gaining mutations. Finance Authority, Access Administrator, +and contributors do not receive those sensitive permissions. Contributors may +receive only minimal exact-project identity unless 11C2 later proves a safe +active-guide schema. + +## Alternatives rejected + +- One combined runtime cutover was too broad for L1 review. +- Token-role fallback or dual authorization would violate the hard cutover. +- Mapping sensitive reads to generic `project.read` would overexpose data. +- Reusing management permissions for inspection would conflate reads and writes. +- Denying Operator/Audit inspection would force unsupported database access. + +## Scope and product behavior + +This PR changes planning/process artifacts and one merge intent only. It adds no +runtime behavior, migration, route, action activation, test, workflow, or +dependency. Signed automation remains canonical live state. + +## Acceptance criteria proof + +The plan records literal routes, exact ActionIds, resource targets, permission +mappings, role/scope projections, concealment requirements, migration custody, +coverage floors, documentation ownership, child sequencing, and stop rules. +Only 11A is named as successor, and it remains inactive. + +## Tests/checks run + +- Merge-intent validator: PASS. +- Stale wording scan: PASS. +- Markdown link scan: PASS. +- Agent gates: 100 PASS. +- Diff integrity: PASS. + +No local four-hour backend suite was run for this documentation-only parent. +Every runtime child requires the hosted GitHub `Backend / test` full suite, +semantic lanes, API E2E, 78 percent repository coverage, and applicable 90 +percent subsystem reports before merge. + +## Test delta and CI integrity + +No tests, workflows, package scripts, dependencies, skips, or thresholds +changed. QA and test-delta reviewers confirmed that future role, scope, +cross-project, cross-guide, child-binding, concealment, OpenAPI, migration, and +live API proof is explicit. + +## Reviewer results and external review + +All nine required internal tracks passed the exact planning SHA +`ab16a1d7cf96f5e0dffc4c0b4ca7277f902b291b` after fixes: senior engineering, +QA/test, security/auth, product/ops, architecture, CI integrity, docs, +reuse/dedup, and test delta. CodeRabbit and hosted GitHub checks remain external +gates after PR publication. + +## Remaining risks and follow-up + +The principal risk is accidental projection broadening during runtime work. +Each child therefore needs a separate signed start and exact-head L1 review. +11A must land before 11B; 11B before 11C1; and 11C1 before 11C2. + +## Human review focus and merge ownership + +Review the eleven-action inventory, two read-only permissions, Operator/Audit +inspection boundary, contributor minimal projection, literal resource binding, +and absence of token-role fallback. The user retains final approval authority +for this specific PR and merge. From ed0f58732fd76388ec32309fccd37c4ad377ffad Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Sat, 25 Jul 2026 19:14:03 +0100 Subject: [PATCH 3/6] docs(auth): repair stale authorization wording --- .../DECISIONS.md | 6 ++-- .../DISCOVERY.md | 5 ++- .../WS-AUTH-001-11-project-read-cutover.md | 4 +-- ...-001-11B-project-identity-actor-context.md | 4 +-- ...001-11C1-project-setup-diagnostic-reads.md | 6 ++-- ...1C2-effective-policy-active-guide-reads.md | 4 +-- ...WS-AUTH-001-11-external-review-response.md | 35 +++++++++++++++++++ .../reviews/WS-AUTH-001-11-pr-trust-bundle.md | 7 ++-- 8 files changed, 54 insertions(+), 17 deletions(-) create mode 100644 .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-external-review-response.md diff --git a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/DECISIONS.md b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/DECISIONS.md index d02a1838..55294043 100644 --- a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/DECISIONS.md +++ b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/DECISIONS.md @@ -760,9 +760,9 @@ registers eleven planned actions and owns migration `0035`; it activates no surface. 11B activates exact-project identity and introduces the self authorization-context surface. 11C1 activates setup and draft diagnostic reads. 11C2 activates effective policy and active-guide reads with an explicit -principal-specific projection. Every activated surface is a hard cutover from -token roles to local grants; no fallback, alias, or dual authorization path is -allowed. +principal-specific projection. Every activated surface uses local grants as +the sole product-authority source; no fallback, alias, or dual authorization +path is allowed. Project identity and active-guide actions use the existing `project.read` permission. 11A adds the narrow read-only `project.setup_diagnostic.read` and diff --git a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/DISCOVERY.md b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/DISCOVERY.md index d1c24e25..cd422de3 100644 --- a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/DISCOVERY.md +++ b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/DISCOVERY.md @@ -396,9 +396,8 @@ need an independently reviewable contract and production-code budget. - The current project router exposes ten GET routes and no project collection or list route. The inherited count/cursor requirement therefore described no existing surface and is removed. -- All ten reads currently rely on `require_any_role()` with token roles - `admin` or `project_manager`; none has a registered primary project-read - ActionId declaration. +- All ten reads currently rely on the superseded request-claim gate; none has a + registered primary project-read ActionId declaration. - `GET /api/v1/actors/me/authorization-context?project_id=...` is intentionally absent today and remains AUTH-11 work carried forward from D32. - The current Alembic head is `0034_project_role_issue_evidence`; the next diff --git a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11-project-read-cutover.md b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11-project-read-cutover.md index 0d3720c5..299626a4 100644 --- a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11-project-read-cutover.md +++ b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11-project-read-cutover.md @@ -99,8 +99,8 @@ surface. 4. `WS-AUTH-001-11C2` hard-cuts the three effective policy/guide reads and defines any contributor-safe active-guide projection explicitly. -Each child requires its own signed explicit start. No child may preserve -`require_any_role()` or token roles on any surface it activates. +Each child requires its own signed explicit start. No child may preserve the +superseded request-claim authority path on any surface it activates. ## Acceptance criteria diff --git a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11B-project-identity-actor-context.md b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11B-project-identity-actor-context.md index 6f314032..dd4dce74 100644 --- a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11B-project-identity-actor-context.md +++ b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11B-project-identity-actor-context.md @@ -57,8 +57,8 @@ project collection/list API - The context response is self-only, exact-project, derived from current local grants and action availability, and cannot advertise planned/inactive actions. - Routers declare one primary ActionId and target; policy stays in the kernel or - feature policy layer. Both routes contain no `require_any_role()` or token- - role authority after cutover. + feature policy layer. Both routes use local grants as their sole product- + authority source after cutover. - Exact-project allow, cross-project deny, role revocation independence, minimal-field, concealed-not-found, audit, invalidation, and live API tests pass. diff --git a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11C1-project-setup-diagnostic-reads.md b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11C1-project-setup-diagnostic-reads.md index df983341..cfc2f5f0 100644 --- a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11C1-project-setup-diagnostic-reads.md +++ b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11C1-project-setup-diagnostic-reads.md @@ -7,7 +7,7 @@ Proposed and inactive after 11B. Requires a separate signed explicit start. ## Goal Hard-cut the six setup and draft diagnostic GET surfaces assigned by AUTH-11 -from token roles to scoped administrative grants. +to scoped local administrative grants as the sole product-authority source. ## Risk and SLA @@ -56,8 +56,8 @@ token-role fallback or dual authorization - ProjectRepository remains persistence owner and returns domain records; the application layer composes authorization context without a parallel project repository in AUTH. -- Every migrated route declares exactly one primary action and contains no - `require_any_role()` or token-role authorization. +- Every migrated route declares exactly one primary action and uses local + grants as its sole product-authority source. - Per-action scope, child-binding, concealed-denial, audit, invalidation, and live API contract tests pass, including positive Project Manager/Operator/ Audit and negative Finance/Access Administrator/contributor cases. diff --git a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11C2-effective-policy-active-guide-reads.md b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11C2-effective-policy-active-guide-reads.md index 01b0d2a9..84bb0caa 100644 --- a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11C2-effective-policy-active-guide-reads.md +++ b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-11C2-effective-policy-active-guide-reads.md @@ -55,8 +55,8 @@ token-role fallback or dual authorization response as unauthorized and nonexistent resources. - Canonical project resolution and authorization precede sensitive assembly; concealed denial is identical for unauthorized and nonexistent resources. -- Every migrated route declares exactly one primary action and contains no - `require_any_role()` or token-role authorization. +- Every migrated route declares exactly one primary action and uses local + grants as its sole product-authority source. - Principal-specific field allowlists, scope, concealed denial, audit, invalidation, and live API contract tests pass. - Authorization spec, role matrix, project operating manual, and authorization diff --git a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-external-review-response.md b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-external-review-response.md new file mode 100644 index 00000000..8557bf54 --- /dev/null +++ b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-external-review-response.md @@ -0,0 +1,35 @@ +# WS-AUTH-001-11 External Review Response + +## Comments addressed + +- GitHub Agent Gates run `30169027253` failed the stale-authorization + documentation scan because new planning prose repeated superseded helper and + request-claim vocabulary. The wording now states the canonical invariant: + local grants are the sole product-authority source after each hard cutover. +- No scanner rule, exception, historical-path allowlist, or CI behavior changed. + +## Comments deferred + +None. + +## Human decisions needed + +None. The repair preserves the already reviewed hard-cutover intent and changes +no action, permission, role, route, or resource design. + +## Commands rerun + +```text +python3 scripts/check_stale_authorization_docs.py +python3 scripts/check_internal_review_evidence.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 +python3 scripts/test_agent_gates.py +git diff --check +``` + +## Remaining risks + +Hosted Agent Gates must pass on the repaired exact head. Backend full-suite and +CodeRabbit checks remain independently required. diff --git a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-pr-trust-bundle.md b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-pr-trust-bundle.md index 3e5bf2fa..1b9d8f31 100644 --- a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-pr-trust-bundle.md +++ b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-pr-trust-bundle.md @@ -80,8 +80,11 @@ live API proof is explicit. All nine required internal tracks passed the exact planning SHA `ab16a1d7cf96f5e0dffc4c0b4ca7277f902b291b` after fixes: senior engineering, QA/test, security/auth, product/ops, architecture, CI integrity, docs, -reuse/dedup, and test delta. CodeRabbit and hosted GitHub checks remain external -gates after PR publication. +reuse/dedup, and test delta. GitHub Agent Gates then identified stale legacy +authorization vocabulary in the new prose; the wording was repaired without +changing design or weakening the scanner, and the response is recorded in +`WS-AUTH-001-11-external-review-response.md`. CodeRabbit and repaired hosted +checks remain external gates. ## Remaining risks and follow-up From 600c50b7fb824c947cb114f9cac6d89346ead285 Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Sat, 25 Jul 2026 19:20:32 +0100 Subject: [PATCH 4/6] docs(auth): bind repaired AUTH-11 evidence --- .../reviews/WS-AUTH-001-11-internal-review-evidence.md | 10 +++++++--- .../reviews/WS-AUTH-001-11-pr-trust-bundle.md | 4 ++-- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-internal-review-evidence.md b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-internal-review-evidence.md index 943a716c..5d8145d6 100644 --- a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-internal-review-evidence.md +++ b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-internal-review-evidence.md @@ -1,17 +1,21 @@ # WS-AUTH-001-11 Internal Review Evidence -Reviewed code SHA: `ab16a1d7cf96f5e0dffc4c0b4ca7277f902b291b` +Reviewed code SHA: `ed0f58732fd76388ec32309fccd37c4ad377ffad` -Reviewed planning SHA: `ab16a1d7cf96f5e0dffc4c0b4ca7277f902b291b` +Reviewed planning SHA: `ed0f58732fd76388ec32309fccd37c4ad377ffad` Reviewed against trusted main: `03a05eeb8f129e0d5f226cc5c058965f43590a81` -Reviewed at: `2026-07-25T18:55:00Z` +Reviewed at: `2026-07-25T19:20:00Z` Reviewer run IDs: `auth11_senior`, `auth11_qa`, `auth11_security`, `auth11_product`, `auth11_arch`, `auth11_ci`, `auth11_docs`, `auth11_reuse`, and `auth11_testdelta` +External wording repair re-review: the same nine tracks re-reviewed the repair +from `ab16a1d7` through exact SHA `ed0f5873`; the sole reported blocker was this +evidence rebinding, resolved by this evidence-only update. + Reviewer tracks: senior engineering, QA/test, security/auth, product/ops, architecture, CI integrity, docs, reuse/dedup, and test delta diff --git a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-pr-trust-bundle.md b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-pr-trust-bundle.md index 1b9d8f31..82f6d953 100644 --- a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-pr-trust-bundle.md +++ b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-pr-trust-bundle.md @@ -77,8 +77,8 @@ live API proof is explicit. ## Reviewer results and external review -All nine required internal tracks passed the exact planning SHA -`ab16a1d7cf96f5e0dffc4c0b4ca7277f902b291b` after fixes: senior engineering, +All nine required internal tracks passed the repaired exact planning SHA +`ed0f58732fd76388ec32309fccd37c4ad377ffad` after fixes: senior engineering, QA/test, security/auth, product/ops, architecture, CI integrity, docs, reuse/dedup, and test delta. GitHub Agent Gates then identified stale legacy authorization vocabulary in the new prose; the wording was repaired without From 81e470306f81edafb8cb592dd53d036ee07ba7e7 Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Sat, 25 Jul 2026 19:22:17 +0100 Subject: [PATCH 5/6] docs(auth): address AUTH-11 external review --- .../CHUNK_MAP.md | 5 +++-- .../WS-AUTH-001-11-external-review-response.md | 6 ++++++ .../WS-AUTH-001-11-internal-review-evidence.md | 6 ++++-- .../reviews/WS-AUTH-001-11-pr-trust-bundle.md | 11 ++++++----- 4 files changed, 19 insertions(+), 9 deletions(-) diff --git a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/CHUNK_MAP.md b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/CHUNK_MAP.md index 2b7def8b..c7048133 100644 --- a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/CHUNK_MAP.md +++ b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/CHUNK_MAP.md @@ -162,8 +162,9 @@ WS-AUTH-001-PLAN locking and caller-owned commit before sensitive product/review mutations. - Parent chunk 11 is planning-only and splits the hard project-read cutover into 11A catalogue/evidence, 11B identity/context, 11C1 setup diagnostics, - and 11C2 effective policy/guide reads. Each child removes token-role - authority from its complete surface family; no compatibility path remains. + and 11C2 effective policy/guide reads. 11A activates no surface. Runtime + children 11B, 11C1, and 11C2 each make local grants the sole authority for + their complete surface family; no compatibility path remains. - Chunks 12-15 migrate bounded complete product/system surfaces. - Artifact upload, read, retention, release/delete, replication, integrity, and reconciliation remain mechanically owned by the artifact subsystem but must diff --git a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-external-review-response.md b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-external-review-response.md index 8557bf54..bdcc84a1 100644 --- a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-external-review-response.md +++ b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-external-review-response.md @@ -7,6 +7,12 @@ request-claim vocabulary. The wording now states the canonical invariant: local grants are the sole product-authority source after each hard cutover. - No scanner rule, exception, historical-path allowlist, or CI behavior changed. +- CodeRabbit correctly noted that catalogue-only 11A cannot remove route + authority. `CHUNK_MAP.md` now assigns the hard runtime cutover only to 11B, + 11C1, and 11C2. +- CodeRabbit's evidence-integrity comment is addressed: the bundle now records + the initial hosted failure, the repaired local passes, twelve changed + Markdown files, and the fact that the hosted rerun remains required. ## Comments deferred diff --git a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-internal-review-evidence.md b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-internal-review-evidence.md index 5d8145d6..4e51dcc9 100644 --- a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-internal-review-evidence.md +++ b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-internal-review-evidence.md @@ -30,9 +30,11 @@ migration, route, test, workflow, action availability, or product behavior. - Merge-intent validation: PASS for `WS-AUTH-001-11`; only 11A is named and a fresh explicit start is required. +- Stale authorization documentation: PASS after canonical wording repair; the + initial hosted run failed and no scanner rule or exception was weakened. - Stale Workstream wording: PASS. -- Markdown links: PASS for all nine changed Markdown files. -- Agent gates: PASS, 100 tests. +- Markdown links: PASS for all twelve changed Markdown files. +- Local agent gates: PASS, 100 tests; repaired hosted rerun remains external. - `git diff --check`: PASS. - Changed files remain inside the planning-parent allowed paths. - No CI, package, test, dependency, coverage threshold, or skip changed. diff --git a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-pr-trust-bundle.md b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-pr-trust-bundle.md index 82f6d953..e8f28f5d 100644 --- a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-pr-trust-bundle.md +++ b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-pr-trust-bundle.md @@ -57,11 +57,12 @@ Only 11A is named as successor, and it remains inactive. ## Tests/checks run -- Merge-intent validator: PASS. -- Stale wording scan: PASS. -- Markdown link scan: PASS. -- Agent gates: 100 PASS. -- Diff integrity: PASS. +- Merge-intent validator: local PASS. +- Stale authorization and Workstream wording scans: local PASS after wording + repair; the original hosted stale-authorization run failed. +- Markdown link scan: local PASS for twelve changed Markdown files. +- Agent gates: 100 local tests PASS; repaired hosted rerun remains required. +- Diff integrity: local PASS. No local four-hour backend suite was run for this documentation-only parent. Every runtime child requires the hosted GitHub `Backend / test` full suite, From 275a0ddc970e4b276801b0a5dfa04a316d82e400 Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Sat, 25 Jul 2026 19:31:44 +0100 Subject: [PATCH 6/6] docs(auth): bind CodeRabbit repair evidence --- .../reviews/WS-AUTH-001-11-internal-review-evidence.md | 10 +++++----- .../reviews/WS-AUTH-001-11-pr-trust-bundle.md | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-internal-review-evidence.md b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-internal-review-evidence.md index 4e51dcc9..27214020 100644 --- a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-internal-review-evidence.md +++ b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-internal-review-evidence.md @@ -1,8 +1,8 @@ # WS-AUTH-001-11 Internal Review Evidence -Reviewed code SHA: `ed0f58732fd76388ec32309fccd37c4ad377ffad` +Reviewed code SHA: `81e470306f81edafb8cb592dd53d036ee07ba7e7` -Reviewed planning SHA: `ed0f58732fd76388ec32309fccd37c4ad377ffad` +Reviewed planning SHA: `81e470306f81edafb8cb592dd53d036ee07ba7e7` Reviewed against trusted main: `03a05eeb8f129e0d5f226cc5c058965f43590a81` @@ -12,9 +12,9 @@ Reviewer run IDs: `auth11_senior`, `auth11_qa`, `auth11_security`, `auth11_product`, `auth11_arch`, `auth11_ci`, `auth11_docs`, `auth11_reuse`, and `auth11_testdelta` -External wording repair re-review: the same nine tracks re-reviewed the repair -from `ab16a1d7` through exact SHA `ed0f5873`; the sole reported blocker was this -evidence rebinding, resolved by this evidence-only update. +External repair re-review: the same nine tracks re-reviewed the wording repair +and CodeRabbit correction through exact SHA `81e47030`; the sole final gate was +this evidence rebinding, resolved by this evidence-only update. Reviewer tracks: senior engineering, QA/test, security/auth, product/ops, architecture, CI integrity, docs, reuse/dedup, and test delta diff --git a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-pr-trust-bundle.md b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-pr-trust-bundle.md index e8f28f5d..5a90a2a3 100644 --- a/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-pr-trust-bundle.md +++ b/.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-11-pr-trust-bundle.md @@ -79,7 +79,7 @@ live API proof is explicit. ## Reviewer results and external review All nine required internal tracks passed the repaired exact planning SHA -`ed0f58732fd76388ec32309fccd37c4ad377ffad` after fixes: senior engineering, +`81e470306f81edafb8cb592dd53d036ee07ba7e7` after fixes: senior engineering, QA/test, security/auth, product/ops, architecture, CI integrity, docs, reuse/dedup, and test delta. GitHub Agent Gates then identified stale legacy authorization vocabulary in the new prose; the wording was repaired without