From 5cadec30459a589dd645c441a15eab3594228070 Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Tue, 28 Jul 2026 09:28:10 +0100 Subject: [PATCH 1/2] plan(auth): split guide activation gates --- .../CHUNK_MAP.md | 6 +- .../WS-XINT-002-art-auth-end-to-end/STATUS.md | 10 +++ .../chunks/WS-XINT-002-04-guide-activation.md | 63 --------------- ...WS-XINT-002-04A-guide-ingest-activation.md | 77 +++++++++++++++++++ ...T-002-04B-guide-read-binding-activation.md | 70 +++++++++++++++++ .../reviews/WS-XINT-002-03-pr-trust-bundle.md | 5 +- 6 files changed, 164 insertions(+), 67 deletions(-) delete mode 100644 .agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04-guide-activation.md create mode 100644 .agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04A-guide-ingest-activation.md create mode 100644 .agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04B-guide-read-binding-activation.md diff --git a/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/CHUNK_MAP.md b/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/CHUNK_MAP.md index ec7f36fe..3ad31193 100644 --- a/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/CHUNK_MAP.md +++ b/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/CHUNK_MAP.md @@ -5,7 +5,8 @@ | `WS-XINT-002-01` | Reconcile the entire ART catalogue, permissions, owners, migration parity, and fixed-service matrix while every new action stays planned. | L1 | approved plan | | `WS-XINT-002-02` | Close the reusable PREP-to-ART operation interface: opaque prepared authority on durable mutation requests, no obsolete upload-session port, and no action activation. | L1 | 01 | | `WS-XINT-002-03` | Activate verifier, scheduler scan, and put resolver services from merged ART recovery evidence. | L1 | 02 plus ART 02C/02D evidence | -| `WS-XINT-002-04` | Activate guide ingest, guide binding, and guide read in evidence-ordered substeps. | L1 | 02 plus ART 03A/03B evidence | +| `WS-XINT-002-04A` | Activate Project Manager guide ingest through the one opaque PREP seam. | L1 | 02 plus merged ART 03A PREP-compatible evidence | +| `WS-XINT-002-04B` | Activate fixed-service guide binding and guide read. | L1 | 04A plus merged ART 03B evidence | | `WS-XINT-002-05A` | Activate initial contributor bundle preparation and durable ready admission. | L1 | 02 plus ART 04A-C evidence | | `WS-XINT-002-05B` | Activate fresh human Submission creation plus fixed artifact binding with exactly-once admission consumption. | L1 | 05A plus ART 05/TASK evidence | | `WS-XINT-002-05C` | Activate checker-remediation submission preparation/creation against one final CheckerRun. | L1 | 05B plus checker remediation evidence | @@ -14,7 +15,8 @@ | `WS-XINT-002-07` | Activate lease-scoped review packets and finding/response evidence binding. | L1 | 02 plus merged ART/REV manifests | | `WS-XINT-002-08` | Prove complete catalogue, least privilege, revocation, replay, concurrency, audit, and live lifecycle conformance. | L1 | 03-07 including 05A-D | -Chunks 03-07 may be split only by the evidence boundaries named above. A split +Chunks 03-07 may be split only by the evidence boundaries named above. The +guide wave is therefore fixed as 04A after ART-03A and 04B after ART-03B. A split cannot add catalogue values, permissions, identities, matrix rows, or a second runtime protocol; such a discovery is contract drift and returns to planning. Each activation chunk owns its exact feature resource contexts, non-forgeable diff --git a/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/STATUS.md b/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/STATUS.md index 1f6d8167..eb4f5719 100644 --- a/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/STATUS.md +++ b/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/STATUS.md @@ -6,6 +6,16 @@ - `WS-XINT-002-01` is merged on `main` at merge commit `89956cff`; the closed ART catalogue and fixed-service matrix are reconciled without activating any new action. +- `WS-XINT-002-02` is merged on `main` at merge commit `f4cebb08`; durable ART + mutation requests use the opaque transaction-bound PREP interface. +- `WS-XINT-002-03` is merged on `main` at merge commit `4336664a`; verifier, + scheduler scan, and put-resolver authority are active with hosted artifact + coverage at 90.02 percent. +- Guide activation is split into `WS-XINT-002-04A` ingest and + `WS-XINT-002-04B` read/binding. 04A cannot implement or activate until + ART-03A is rebased onto the merged opaque PREP interface and merged; the + preserved ART worktree's raw-context/local-authority seam is not activation + evidence. This file records only durable merged state and reviewed delivery order. It does not describe a branch as “in progress”, “merge-pending”, or “active”; diff --git a/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04-guide-activation.md b/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04-guide-activation.md deleted file mode 100644 index d7853771..00000000 --- a/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04-guide-activation.md +++ /dev/null @@ -1,63 +0,0 @@ -# Chunk Contract: WS-XINT-002-04 Guide Authorization Activation - -## Goal - -Activate guide ingest after ART-03A evidence, then guide binding/read after -ART-03B evidence, without weakening the ART-03C clean cut. - -## Risk class - -L1. - -## Allowed files - -```text -backend/app/modules/authorization/** -backend/app/modules/artifacts/authorization.py -backend/app/modules/artifacts/service.py -backend/app/modules/projects/** -backend/tests/test_authorization.py -backend/tests/test_guide_artifacts.py -backend/tests/test_artifact_admission.py -docs/spec_authorization_service.md -docs/spec_artifact_storage_service.md -.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/** -``` - -## Not allowed - -Submission/review behavior, provider redesign, token roles, generic guide -download, or new catalogue values. - -## Acceptance criteria - -- Ingest requires an exact Project Manager grant and locks actor/link, project, - draft guide, snapshot/item, policy generation, request digest, and operation. -- Final PREP consumption occurs before capacity/put intent commit and provider - I/O; revoke/stale/cross-project/replay cases deny atomically. -- Guide binding/read use separate fixed identities and exact verified content, - binding role, guide item, and setup generation. -- Activation is split at the 03A/03B evidence boundary if both manifests are not - already merged; no later action is enabled early. - -## Verification - -```bash -(cd backend && .venv/bin/python -m ruff check app tests scripts) -(cd backend && WORKSTREAM_TEST_DATABASE_URL= .venv/bin/pytest tests/test_authorization.py tests/test_guide_artifacts.py tests/test_artifact_admission.py -q --cov=app.modules.authorization --cov=app.modules.artifacts --cov=app.modules.projects --cov-report=term-missing --cov-fail-under=90) -python3 scripts/check_stale_authorization_docs.py -python3 scripts/check_stale_artifact_contracts.py -python3 scripts/check_markdown_links.py -git diff --check -``` - -The exact PR head must pass `Backend / test` and `Agent Gates / agent-gates`. - -## Required reviewers - -Senior engineering, QA/test, security/auth, product/ops, architecture, CI -integrity, docs, reuse/dedup, and test delta. - -## Human review focus - -Manager-only ingest, separate service authority, exact generations, and clean cut. diff --git a/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04A-guide-ingest-activation.md b/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04A-guide-ingest-activation.md new file mode 100644 index 00000000..3d5955b5 --- /dev/null +++ b/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04A-guide-ingest-activation.md @@ -0,0 +1,77 @@ +# Chunk Contract: WS-XINT-002-04A Guide Ingest Authorization Activation + +## Goal + +Activate only `artifact.guide_source.ingest` after merged ART-03A evidence uses +the one opaque, transaction-bound PREP interface from WS-XINT-002-02. + +## Risk class + +L1. + +## Entry gate + +- ART-03A is rebased onto current `main`, merged, and reviewed. +- Its durable mutation request carries `PreparedAuthorizationHandle`; raw + `AuthorizationContext` and an ART-local alternate authority protocol are not + mutation authority. +- The hidden route remains deny-only until this chunk installs the exact AUTH + adapter and changes only guide ingest availability. + +## Allowed files + +```text +backend/app/modules/authorization/** +backend/app/modules/artifacts/authorization.py +backend/tests/test_authorization.py +backend/tests/test_guide_artifacts.py +backend/tests/test_artifact_admission.py +docs/spec_authorization_service.md +docs/spec_artifact_storage_service.md +.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/** +``` + +## Not allowed + +ART byte/admission implementation, project routes or lifecycle behavior, +guide binding/read, submission/review behavior, provider redesign, token roles, +generic guide download, new catalogue values, or a second authority protocol. + +## Acceptance criteria + +- Initial authority requires the exact active Project Manager grant for the + project and occurs before scratch or request-body byte intake. +- Final PREP consumption recomposes and locks actor/link, grant, project, draft + guide, snapshot/item, operation identity, request digest, and server-computed + digest, byte count, and media type in the caller-owned root transaction. +- Consumption occurs before capacity/put-intent commit and provider I/O; + authorization evidence and the protected mutation commit atomically once. +- Revoked actor/link/grant, cross-project lineage, stale guide/snapshot/item, + replay, copied or serialized handle, cross-session/root/action/resource use, + and replaced transaction deny atomically without capacity, put, provider, or + allowed-audit effects. +- Only `artifact.guide_source.ingest` becomes active. Guide read and binding + remain planned until WS-XINT-002-04B consumes merged ART-03B evidence. + +## Verification + +```bash +(cd backend && .venv/bin/python -m ruff check app tests scripts) +(cd backend && WORKSTREAM_TEST_DATABASE_URL= .venv/bin/pytest tests/test_authorization.py tests/test_guide_artifacts.py tests/test_artifact_admission.py -q --cov=app.modules.authorization --cov=app.modules.artifacts --cov=app.modules.projects --cov-report=term-missing --cov-fail-under=90) +python3 scripts/check_stale_authorization_docs.py +python3 scripts/check_stale_artifact_contracts.py +python3 scripts/check_markdown_links.py +git diff --check +``` + +The exact PR head must pass `Backend / test` and `Agent Gates / agent-gates`. + +## Required reviewers + +Senior engineering, QA/test, security/auth, product/ops, architecture, CI +integrity, docs, reuse/dedup, and test delta. + +## Human review focus + +Manager-only ingest, one opaque PREP seam, final locked lineage and byte facts, +denial atomicity, and ingest-only availability. diff --git a/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04B-guide-read-binding-activation.md b/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04B-guide-read-binding-activation.md new file mode 100644 index 00000000..fdf4ca68 --- /dev/null +++ b/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04B-guide-read-binding-activation.md @@ -0,0 +1,70 @@ +# Chunk Contract: WS-XINT-002-04B Guide Read And Binding Authorization Activation + +## Goal + +Activate fixed-service guide binding and guide read only after merged ART-03B +evidence, without weakening the ART-03C clean cut. + +## Risk class + +L1. + +## Entry gate + +- WS-XINT-002-04A is merged. +- ART-03B hidden binding/materialization behavior and exact resource manifest + are merged and reviewed. + +## Allowed files + +```text +backend/app/modules/authorization/** +backend/app/modules/artifacts/authorization.py +backend/tests/test_authorization.py +backend/tests/test_guide_artifacts.py +docs/spec_authorization_service.md +docs/spec_artifact_storage_service.md +.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/** +``` + +## Not allowed + +Human ingest behavior, ART byte/admission implementation, project lifecycle +changes, submission/review behavior, provider redesign, token roles, generic +guide download, new catalogue values, or ART-03C legacy removal. + +## Acceptance criteria + +- `artifact.guide_source.binding.create` is available only to the fixed + artifact-binding identity for exact verified content, binding role, guide + source item, and setup generation. +- `artifact.guide_source.read` is available only to the fixed guide-reader + identity for the exact bound guide content and setup generation. +- Replaced binding, stale setup generation, wrong identity, cross-guide, + cross-project, replay, and revoked service authority deny atomically. +- No generic artifact-download permission or human-to-service authority + inheritance is introduced. +- ART-03C remains a separate clean-cut gate. + +## Verification + +```bash +(cd backend && .venv/bin/python -m ruff check app tests scripts) +(cd backend && WORKSTREAM_TEST_DATABASE_URL= .venv/bin/pytest tests/test_authorization.py tests/test_guide_artifacts.py -q --cov=app.modules.authorization --cov=app.modules.artifacts --cov=app.modules.projects --cov-report=term-missing --cov-fail-under=90) +python3 scripts/check_stale_authorization_docs.py +python3 scripts/check_stale_artifact_contracts.py +python3 scripts/check_markdown_links.py +git diff --check +``` + +The exact PR head must pass `Backend / test` and `Agent Gates / agent-gates`. + +## Required reviewers + +Senior engineering, QA/test, security/auth, product/ops, architecture, CI +integrity, docs, reuse/dedup, and test delta. + +## Human review focus + +Separate fixed identities, exact verified-content and generation binding, +least privilege, and preservation of the ART-03C clean cut. diff --git a/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/reviews/WS-XINT-002-03-pr-trust-bundle.md b/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/reviews/WS-XINT-002-03-pr-trust-bundle.md index 98e929c6..f7dc615d 100644 --- a/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/reviews/WS-XINT-002-03-pr-trust-bundle.md +++ b/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/reviews/WS-XINT-002-03-pr-trust-bundle.md @@ -68,5 +68,6 @@ digest persistence. The user retains merge approval for this specific PR. ## Next gate -`WS-XINT-002-04` is only the declared same-initiative successor. It does not -start automatically and requires a fresh explicit trusted-main event. +`WS-XINT-002-04A` is the next bounded implementation contract. It activates +only guide ingest after merged PREP-compatible ART-03A evidence; guide read and +binding remain separately gated by `WS-XINT-002-04B` and ART-03B evidence. From 794c175db100fdf2e73d03dc68df09e2bac442c9 Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Tue, 28 Jul 2026 09:44:52 +0100 Subject: [PATCH 2/2] docs(auth): tighten guide activation contracts --- .../WS-XINT-002-04A-guide-ingest-activation.md | 12 ++++++++++-- ...NT-002-04B-guide-read-binding-activation.md | 18 ++++++++++++++++-- 2 files changed, 26 insertions(+), 4 deletions(-) diff --git a/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04A-guide-ingest-activation.md b/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04A-guide-ingest-activation.md index 3d5955b5..7e5a1fbf 100644 --- a/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04A-guide-ingest-activation.md +++ b/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04A-guide-ingest-activation.md @@ -21,14 +21,20 @@ L1. ## Allowed files ```text -backend/app/modules/authorization/** +backend/app/modules/authorization/catalogue.py +backend/app/modules/authorization/kernel.py +backend/app/modules/authorization/prepared.py +backend/app/modules/authorization/repository.py +backend/app/modules/authorization/runtime.py backend/app/modules/artifacts/authorization.py backend/tests/test_authorization.py backend/tests/test_guide_artifacts.py backend/tests/test_artifact_admission.py docs/spec_authorization_service.md docs/spec_artifact_storage_service.md -.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/** +.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/reviews/WS-XINT-002-04A-internal-review.md +.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/reviews/WS-XINT-002-04A-pr-trust-bundle.md +.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/reviews/WS-XINT-002-04A-external-review-response.md ``` ## Not allowed @@ -36,6 +42,8 @@ docs/spec_artifact_storage_service.md ART byte/admission implementation, project routes or lifecycle behavior, guide binding/read, submission/review behavior, provider redesign, token roles, generic guide download, new catalogue values, or a second authority protocol. +This contract, the chunk map, and other planning files are not editable by the +04A implementation PR; any required scope change returns to planning review. ## Acceptance criteria diff --git a/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04B-guide-read-binding-activation.md b/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04B-guide-read-binding-activation.md index fdf4ca68..65dd308d 100644 --- a/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04B-guide-read-binding-activation.md +++ b/.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04B-guide-read-binding-activation.md @@ -18,13 +18,19 @@ L1. ## Allowed files ```text -backend/app/modules/authorization/** +backend/app/modules/authorization/catalogue.py +backend/app/modules/authorization/kernel.py +backend/app/modules/authorization/prepared.py +backend/app/modules/authorization/repository.py +backend/app/modules/authorization/runtime.py backend/app/modules/artifacts/authorization.py backend/tests/test_authorization.py backend/tests/test_guide_artifacts.py docs/spec_authorization_service.md docs/spec_artifact_storage_service.md -.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/** +.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/reviews/WS-XINT-002-04B-internal-review.md +.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/reviews/WS-XINT-002-04B-pr-trust-bundle.md +.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/reviews/WS-XINT-002-04B-external-review-response.md ``` ## Not allowed @@ -32,6 +38,8 @@ docs/spec_artifact_storage_service.md Human ingest behavior, ART byte/admission implementation, project lifecycle changes, submission/review behavior, provider redesign, token roles, generic guide download, new catalogue values, or ART-03C legacy removal. +This contract, the chunk map, and other planning files are not editable by the +04B implementation PR; any required scope change returns to planning review. ## Acceptance criteria @@ -40,6 +48,12 @@ guide download, new catalogue values, or ART-03C legacy removal. source item, and setup generation. - `artifact.guide_source.read` is available only to the fixed guide-reader identity for the exact bound guide content and setup generation. +- Both actions require exact prepared-authority validation and single-use + consumption before any provider read or binding write. Stale, replayed, + revoked, mismatched, cross-session, cross-action, or cross-resource authority + denies before I/O. +- Successful binding state and bounded authorization evidence commit atomically + in the caller-owned root transaction before later provider reads. - Replaced binding, stale setup generation, wrong identity, cross-guide, cross-project, replay, and revoked service authority deny atomically. - No generic artifact-download permission or human-to-service authority