From cc1df21eda776a77ce3b0545501b9c6ee72759e7 Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Tue, 4 Aug 2026 19:37:46 +0100 Subject: [PATCH] docs(art): resequence legacy precheck clean cut --- .../CHUNK_MAP.md | 11 +- .../DECISIONS.md | 16 ++- .../PLAN.md | 13 +- .../REVIEW_LOG.md | 12 ++ .../RISKS.md | 2 +- .../STATUS.md | 16 ++- ...WS-ART-001-04A4-legacy-precheck-removal.md | 60 +++------ ...-ART-001-04B1-default-checker-catalogue.md | 2 +- .../WS-ART-001-05B-submission-api-cutover.md | 42 +++++- ...-legacy-precheck-clean-cut-resequencing.md | 74 +++++++++++ ...-ART-001-PLAN5-internal-review-evidence.md | 41 ++++++ .../WS-ART-001-PLAN5-pr-trust-bundle.md | 125 ++++++++++++++++++ docs/architecture_checker_framework.md | 11 +- docs/architecture_data_model.md | 11 +- docs/architecture_lockdown.md | 5 +- docs/current_system_data_flow.html | 2 +- ...ssion_artifact_policy_drives_pre_submit.md | 11 +- docs/glossary.md | 2 +- docs/operations_project_operating_manual.md | 4 +- docs/spec_authorization_service.md | 4 +- docs/template_checker_policy.md | 5 +- docs/template_submission_artifact_policy.md | 7 +- docs/template_submission_packet.md | 4 +- 23 files changed, 382 insertions(+), 98 deletions(-) create mode 100644 .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-PLAN5-legacy-precheck-clean-cut-resequencing.md create mode 100644 .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/reviews/WS-ART-001-PLAN5-internal-review-evidence.md create mode 100644 .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/reviews/WS-ART-001-PLAN5-pr-trust-bundle.md diff --git a/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/CHUNK_MAP.md b/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/CHUNK_MAP.md index 1a0526fcd..1550d7135 100644 --- a/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/CHUNK_MAP.md +++ b/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/CHUNK_MAP.md @@ -23,19 +23,20 @@ they cross multiple L1 boundaries. | Chunk | Goal | Risk | Entry gate/status | |---|---|---:|---| | `WS-ART-001-PLAN3` | Reconcile the complete remaining v0.1 custody chain and AUTH/REV/CON handoffs. | L1 | Merged planning | -| `WS-ART-001-PLAN4` | Define the central default pre-submission checker catalogue, disable semantics, and split execution contract. | L1 | Planning complete; internal review passed; PR pending | +| `WS-ART-001-PLAN4` | Define the central default pre-submission checker catalogue, disable semantics, and split execution contract. | L1 | Merged PR #271 | +| `WS-ART-001-PLAN5` | Correct legacy-precheck removal sequencing so the old public and internal paths are deleted only with the admission-backed Submission cutover. | L1 | Planning complete; PR pending | | `WS-ART-001-03C` | Clean-cut legacy guide identity/excerpts and make the verified same-generation pipeline live. | L1 | Merged PR #249 | | `WS-ART-001-04A1` | Remove legacy multi-step contributor intake reachability and schema without adding the replacement route. | L1 | Merged PR #264 | | `WS-ART-001-04A2` | Add bounded one-outer-ZIP intake and archive-safety inspection in private scratch. | L1 | Merged PR #266 | | `WS-ART-001-04A3` | Add canonical semantic manifest, executable normalization, and unchanged-work gate. | L1 | Merged PR #268 | -| `WS-ART-001-04A4` | Remove the legacy independently invocable caller-owned submission-precheck route and contract. | L1 | Proposed after PLAN4 | -| `WS-ART-001-04B1` | Add the single versioned checker catalogue and compile one effective execution plan from platform defaults plus locked project policy. | L1 | Proposed after 04A4 | +| `WS-ART-001-04A4` | Former early removal of the legacy independently invocable caller-owned submission-precheck route and contract. | L1 | Superseded by PLAN5; complete removal belongs to 05B | +| `WS-ART-001-04B1` | Add the single versioned checker catalogue and compile one effective execution plan from platform defaults plus locked project policy. | L1 | Proposed after PLAN5 | | `WS-ART-001-04B2` | Materialize the sealed manifest tree once and execute the mandatory platform/default catalogue phases. | L1 | Proposed after 04B1 | | `WS-ART-001-04B3` | Execute locked project-policy rules through the same plan and persist one bounded immutable evidence set. | L1 | Proposed after 04B2 | | `WS-ART-001-04C1` | Reauthorize and atomically persist capacity plus durable put intent, then write the checked ZIP once. | L1 | Proposed after XINT-06A | | `WS-ART-001-04C2` | Reuse verification/recovery to publish one capacity-charged ready admission and compose the hidden continuous endpoint. | L1 | Proposed after 04C1 | | `WS-ART-001-05A` | Atomically consume ready admission into one immutable Submission and binding under fresh human/service authority. | L1 | Proposed after XINT-05A | -| `WS-ART-001-05B` | Remove legacy package URI/hash/manifest authority and cut live API/automatic post-submit dispatch to the verified binding. | L1 | Proposed after XINT-05B | +| `WS-ART-001-05B` | Atomically cut the live Submission API/dispatch to verified admission and remove the complete legacy standalone/internal precheck and caller-owned package contract. | L1 | Proposed after XINT-05B | | `WS-ART-001-06A` | Persist post-submit checker input snapshot and integrity-checking materialization. | L1 | Proposed after 05B | | `WS-ART-001-06B` | Store/bind checker outputs and preserve checker-owned routing. | L1 | Proposed after 06A | | `WS-ART-001-07A` | Add lease-scoped exact-binding reviewer packet materialization without review lifecycle ownership. | L1 | Proposed after 06B plus hidden REV manifest | @@ -49,7 +50,7 @@ they cross multiple L1 boundaries. ```text AUTH-04B implementation [merged PR #245] -> ART-03C --> ART-04A1 -> 04A2 -> 04A3 -> PLAN4 -> 04A4 -> 04B1 -> 04B2 -> 04B3 +-> ART-04A1 -> 04A2 -> 04A3 -> PLAN4 -> PLAN5 -> 04B1 -> 04B2 -> 04B3 -> XINT-06A pre-submit materializer activation -> ART-04C1 -> 04C2 -> XINT-05A contributor preparation activation diff --git a/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/DECISIONS.md b/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/DECISIONS.md index 5adc85abe..abde8baff 100644 --- a/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/DECISIONS.md +++ b/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/DECISIONS.md @@ -577,10 +577,16 @@ must not silently remain universal blocking rules; the implementing chunk must classify them as narrowly high-confidence blocking checks, advisory checks, or project-specific policy and prove the migration. -## D55 - Legacy Standalone Precheck Is Removed Before Catalogue Execution +## D55 - Legacy Precheck Is Removed Only With Admission-Backed Submission Cutover The existing caller-owned `/submission-precheck` request cannot prove the exact -uploaded ZIP or sealed server manifest and would create a second execution API. -04A4 removes its route, schemas, service entry point, and OpenAPI surface before -04B1 installs the authoritative catalogue. Pre-production accepts this clean-cut -gap; there is no compatibility alias, redirect, or caller-manifest adapter. +uploaded ZIP or sealed server manifest and must not survive the authoritative +cutover. Removing its shared service before admission-backed Submission creation +exists would either permit unchecked legacy Submission creation or preserve a +hidden compatibility seam. PLAN5 therefore supersedes early chunk 04A4. The +legacy route and the mandatory internal legacy Submission guard remain frozen +while 04B1-04C2 and 05A build the replacement. ART-05B removes the route, +schemas, public service entry point, internal guard, and caller-owned package +contract together when verified admission consumption becomes the only live +Submission path. No alias, redirect, fallback, or caller-manifest adapter is +allowed. diff --git a/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/PLAN.md b/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/PLAN.md index 6a7958513..7549b9e2e 100644 --- a/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/PLAN.md +++ b/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/PLAN.md @@ -714,7 +714,7 @@ AUTH-04B implementation/activation [merged PR #245] -> ART-04A1 legacy contributor-intake removal -> ART-04A2 bounded outer-ZIP safety/intake -> ART-04A3 semantic manifest + unchanged-work gate --> ART-04A4 legacy standalone precheck clean cut +-> PLAN5 legacy-precheck clean-cut resequencing -> ART-04B1 default-checker catalogue and effective-plan contract -> ART-04B2 sealed scratch materialization and platform-default execution -> ART-04B3 locked-project execution and immutable bounded evidence @@ -724,7 +724,7 @@ AUTH-04B implementation/activation [merged PR #245] -> XINT-05A contributor preparation activation -> ART-05A atomic Submission/binding/admission consumption -> XINT-05B Submission/binding activation --> ART-05B legacy Submission transport/API + automatic dispatch clean cut +-> ART-05B admission-backed Submission/API/dispatch cutover plus complete legacy precheck removal -> ART-06A post-submit checker snapshot/materialization -> ART-06B checker output binding and routing -> XINT-06B post-submit/output activation @@ -742,6 +742,15 @@ No intermediate HTTP route, durable upload session, scratch handle, local path, or prepared authorization crosses those PR boundaries. 04C2 alone composes the hidden endpoint after every internal dependency exists. +PLAN5 supersedes the former early 04A4 removal. The legacy standalone precheck +route and its internal `TaskService.create_submission` safety guard remain +temporary legacy behavior only until the verified-admission Submission path is +ready. They receive no new features or compatibility adapters. ART-05B then +deletes the route, public schemas/service entry point, internal guard, and +caller-owned package/hash/manifest contract in the same clean-cut transaction +and API migration that makes admission consumption authoritative. There is no +interval in which unchecked legacy Submission creation is reachable. + XINT-06 must split because live preparation requires the fixed pre-submit materializer before XINT-05A can safely activate the human preparation action. The later 06B activation owns only post-submit materialization plus checker diff --git a/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/REVIEW_LOG.md b/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/REVIEW_LOG.md index 6c7b4c450..b1ae31df3 100644 --- a/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/REVIEW_LOG.md +++ b/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/REVIEW_LOG.md @@ -334,3 +334,15 @@ repair. Architecture additionally required authority-neutral shared result identity and complete platform/default dispatch mapping; both were repaired before final publication. + +## WS-ART-001-PLAN5 + +- Preimplementation discovery found that PLAN4's proposed 04A4 deletion shared + its service with the mandatory guard inside live legacy Submission creation. +- Architecture review passed only with resequencing; security and product/ops + reviews blocked the original contract because it could permit unchecked + Submission creation, break the live path, or create a private compatibility + seam. +- The correction supersedes 04A4, makes 04B1 the next implementation chunk, and + assigns the complete standalone/public/internal/caller-package clean cut to + the admission-backed 05B Submission cutover. diff --git a/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/RISKS.md b/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/RISKS.md index 3a7a2632d..8e6c10555 100644 --- a/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/RISKS.md +++ b/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/RISKS.md @@ -71,4 +71,4 @@ | A disabled mandatory checker is treated as a pass | Critical | Mandatory security, integrity, and accountability entries fail preparation closed when disabled; only advisory entries may be disabled while execution continues, with explicit evidence. | | Broad filename heuristics block legitimate generic projects | High | Keep only narrowly high-confidence universal exclusions blocking; classify ambiguous patterns as advisory or project-specific and test false-positive boundaries. | | Project policy or task parameters toggle platform availability | Critical | Catalogue availability is startup-validated deployment state; project policy can add or narrow rules but never disable or downgrade Workstream defaults. | -| Legacy caller-owned precheck remains beside the new catalogue | Critical | 04A4 removes the route/schema/service/OpenAPI surface before 04B1; no alias or adapter may preserve independent execution. | +| Legacy caller-owned precheck survives or is removed before its replacement is safe | Critical | Freeze it while hidden 04B1-05A builds the authoritative path; 05B atomically removes the route/schema/public service/internal guard and caller package contract as admission-backed Submission becomes live. No alias or adapter may preserve independent execution. | diff --git a/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/STATUS.md b/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/STATUS.md index 84402929a..0a85f1945 100644 --- a/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/STATUS.md +++ b/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/STATUS.md @@ -116,13 +116,15 @@ authoritative. ART-04A2 merged through PR #266. ART-04A3 merged through PR #268 and provides canonical server-derived semantic manifests, executable normalization, and fail-closed unchanged-work comparison. -`WS-ART-001-PLAN4` is the planning-only correction, implemented with all -required internal L1 review tracks passing. It replaces the -oversized 04B contract with 04A4 legacy standalone-precheck removal, 04B1 -catalogue/effective-plan composition, 04B2 sealed materialization plus mandatory -platform/default execution, and 04B3 locked-project execution plus immutable -bounded evidence. No runtime behavior or AUTH availability changes in PLAN4; -hosted PR gates and human merge remain pending. +`WS-ART-001-PLAN4` merged through PR #271. Discovery for its proposed 04A4 +implementation proved the early clean cut unsafe because live legacy Submission +creation still calls the shared precheck service and the verified-admission +replacement is not yet available. PLAN5 is the active planning correction: it +supersedes 04A4, makes 04B1 the next implementation chunk, and assigns complete +legacy route/public-service/internal-guard/caller-package removal to the 05B +admission-backed Submission cutover. All required internal L1 reviews pass after +repair; local documentation and agent gates pass. No runtime behavior or AUTH +availability changes in PLAN5; hosted PR review remains pending. ## Gate diff --git a/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-04A4-legacy-precheck-removal.md b/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-04A4-legacy-precheck-removal.md index d2adea2e2..9bca335d9 100644 --- a/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-04A4-legacy-precheck-removal.md +++ b/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-04A4-legacy-precheck-removal.md @@ -1,67 +1,43 @@ # Chunk Contract: WS-ART-001-04A4 - Legacy Standalone Precheck Removal -Initiative: `WS-ART-001` | Risk: L1 | Status: Proposed after PLAN4 approval +Initiative: `WS-ART-001` | Risk: L1 | Status: Superseded by PLAN5 Artifact contract phase: `upload_admission` ## Goal -Remove the independently invocable caller-owned submission-precheck API before -the authoritative server-derived catalogue path is installed. This is a clean -cut with no replacement route in this chunk. +Historical contract only. PLAN5 proved that removing the shared precheck service +before admission-backed Submission creation exists would create an unchecked +legacy Submission path or force a forbidden compatibility seam. No runtime work +is authorized by this contract. Complete removal is reassigned to 05B. ## Allowed Files -- checker router/service/schema removal for - `/api/v1/tasks/{task_id}/submission-precheck`; -- removal of pre-submit-only legacy request/response helpers and registry - membership after proof that no durable/post-submit caller uses them; -- OpenAPI, route-negative, import/reachability, docs, and focused tests; -- CI only to preserve exact existing coverage gates. +- none; this contract is retained only as durable planning history. ## Not Allowed -- new catalogue, checker execution, ZIP/scratch changes, provider I/O, durable - evidence/admission/Submission, compatibility alias, redirect, or fallback; -- removal of compiler primitives or durable/post-submit checker behavior needed - by 04B1/04B3 and later ART-06; -- AUTH availability/grant changes or public replacement endpoints. +- any runtime implementation under the 04A4 identifier; +- partial route-only or service-only removal; +- a private compatibility replacement for the shared legacy guard. ## Acceptance Criteria -- route and OpenAPI schema are absent and return the canonical not-found result; -- caller-owned `artifact_hash_manifest`, package/provider references, and legacy - packet shape cannot reach a pre-submit service through HTTP or internal public - methods; -- no alias, redirect, compatibility parser, or second registry survives; -- constrained compiler primitives and durable post-submit runner behavior remain - available for 04B1 reuse; -- import/reachability tests prove no product composition root exposes the old - path; -- no artifact, task, Submission, checker-run, audit, or AUTH behavior is added; -- focused subsystem coverage is at least 90 percent and repository coverage - remains at least 78 percent. +- canonical PLAN, CHUNK_MAP, DECISIONS, RISKS, STATUS, and 05B contract assign + the complete clean cut to 05B; +- 04B1 follows PLAN5 without an intervening partial-removal implementation. ## Verification -```bash -(cd backend && .venv/bin/pytest tests/test_submission_precheck_removal.py tests/test_openapi_contract.py tests/test_checker_runner.py -q) -(metadata_dir="$(mktemp -d)" && trap 'rm -rf "$metadata_dir"' EXIT && (cd backend && WORKSTREAM_TEST_ADMIN_DATABASE_URL=postgresql+asyncpg://workstream:workstream@localhost:5433/postgres .venv/bin/python scripts/run_isolated_tests.py --metadata-json "$metadata_dir/result.json" --timeout-seconds 12600 -- .venv/bin/python -m pytest -q --ignore=tests/test_isolated_database_runner.py --cov=app --cov-report=term-missing --cov-fail-under=78)) -(cd backend && .venv/bin/coverage report --include='app/modules/checkers/*,app/api/router.py' --precision=2 --fail-under=90) -(cd backend && .venv/bin/ruff check app tests) -python3 scripts/check_stale_artifact_contracts.py -python3 scripts/check_stale_workstream_wording.py -python3 scripts/check_markdown_links.py -PYTHONPATH=. python3 scripts/test_lightweight_agent_gates.py -``` +Documentation gates only; no application tests are authorized by this +superseded contract. ## Required Reviewers -Senior engineering, architecture, QA/test, security/auth, product/ops, -reuse/dedup, CI integrity, test delta, and docs. +Architecture, security/auth, product/ops, senior engineering, QA/test, docs, +reuse/dedup, CI integrity, and test delta review PLAN5. ## Human Review Focus -- Is the old API truly unreachable rather than hidden behind an alias? -- Were reusable compiler/post-submit capabilities preserved? -- Does this chunk introduce no replacement behavior? +- Does the resequencing prevent both unchecked legacy Submission creation and a + long-lived compatibility seam? diff --git a/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-04B1-default-checker-catalogue.md b/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-04B1-default-checker-catalogue.md index deef71f95..e998d1571 100644 --- a/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-04B1-default-checker-catalogue.md +++ b/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-04B1-default-checker-catalogue.md @@ -1,6 +1,6 @@ # Chunk Contract: WS-ART-001-04B1 - Default Checker Catalogue -Initiative: `WS-ART-001` | Risk: L1 | Status: Proposed after PLAN4 approval +Initiative: `WS-ART-001` | Risk: L1 | Status: Proposed after PLAN5 Artifact contract phase: `upload_admission` diff --git a/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-05B-submission-api-cutover.md b/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-05B-submission-api-cutover.md index 58b79b847..f8af32de9 100644 --- a/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-05B-submission-api-cutover.md +++ b/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-05B-submission-api-cutover.md @@ -4,13 +4,16 @@ Parent initiative: `WS-ART-001` | Risk: L1 | Status: Proposed after XINT-05B ## Goal -Make verified admission consumption the only contributor Submission path and -dispatch post-submit work using immutable identifiers rather than package data. +Make verified admission consumption the only contributor Submission path, +dispatch post-submit work using immutable identifiers rather than package data, +and remove the complete legacy standalone and internal precheck path once and +for all. ## Allowed Files -Submission schemas/router/service, exact legacy field migration/removal, -post-submit dispatch payloads, API examples, focused tests/docs/CI evidence. +Submission and checker schemas/routers/services, exact legacy field and precheck +removal, post-submit dispatch payloads, API examples, focused tests/docs/CI +evidence. ## Not Allowed Changes @@ -21,14 +24,37 @@ generic artifact download, AUTH catalogue/availability, or compatibility paths. - the public request accepts an admission identity, not URI/hash/manifest facts; - caller-owned package identity fields are unreachable and removed safely; +- `/api/v1/tasks/{task_id}/submission-precheck`, its OpenAPI schemas, and its + public service entry point are absent and return canonical not-found; +- the legacy internal `TaskService.create_submission` precheck guard is removed + in the same cutover because Submission creation can consume only an exact + verified ready admission; +- no alias, redirect, fallback, private compatibility service, caller-owned + manifest input, or second checker registry survives; +- pending, failed, expired, stale, consumed, cross-task, cross-project, and + otherwise non-ready admissions cannot create a Submission or dispatch work; +- mixed admission-plus-legacy package requests fail closed rather than choosing + one authority source; +- concurrent consumption of one ready admission creates exactly one Submission, + one binding, one admission transition, and one downstream dispatch; +- exact idempotent replay returns the original business effect while conflicting + replay fails with the stable domain conflict; - response exposes immutable Submission/binding identities without provider URLs; - Celery payloads contain durable identifiers/version facts only; - old and new paths cannot coexist or create duplicate business effects. ## Verification Commands -Focused API, schema, migration, dispatch, replay, stale-field, coverage, and -hosted Backend/Agent Gates. +- focused API/schema tests prove admission-only creation and reject legacy + `package_uri`, `package_hash`, `artifact_hash_manifest`, and mixed requests; +- PostgreSQL state-matrix and concurrency tests prove non-ready/cross-resource + rejection, exact replay, one consumption, one Submission, and one dispatch; +- route/OpenAPI/import-reachability tests prove the removed + `/api/v1/tasks/{task_id}/submission-precheck` route, schemas, public service + method, aliases, redirects, fallbacks, compatibility path, and second registry + are absent; +- migration, stale-field, focused 90 percent subsystem coverage, repository 78 + percent coverage, and hosted Backend/Agent Gates pass. ## Required Reviewers @@ -37,4 +63,6 @@ reuse/dedup, test delta, and docs. ## Human Review Focus And Stop Conditions -Review the clean cut and API compatibility impact. Stop before checker changes. +Review the complete clean cut, proof that unchecked Submission creation is +impossible, and API compatibility impact. Do not change authoritative catalogue +definitions or checker semantics in this cutover. diff --git a/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-PLAN5-legacy-precheck-clean-cut-resequencing.md b/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-PLAN5-legacy-precheck-clean-cut-resequencing.md new file mode 100644 index 000000000..68dc8d79a --- /dev/null +++ b/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-PLAN5-legacy-precheck-clean-cut-resequencing.md @@ -0,0 +1,74 @@ +# Chunk Contract: WS-ART-001-PLAN5 — Legacy Precheck Clean-Cut Resequencing + +Parent initiative: `WS-ART-001` | Risk: L1 | Status: Planning complete; PR pending + +## Goal + +Correct PLAN4 sequencing so Workstream removes the complete legacy contributor +precheck path only when verified admission consumption becomes the sole live +Submission path. + +## Why This Chunk Exists + +Implementation discovery found that live `TaskService.create_submission` still +uses the same checker service as the standalone caller-owned precheck route. +Deleting that service before the admission-backed replacement exists would +either permit unchecked legacy Submission creation, break the live path, or +require a forbidden compatibility seam. The clean cut therefore belongs to +05B, after 04B1-04C2, AUTH activation, and 05A provide the replacement. + +## Allowed Files + +- ART initiative PLAN, CHUNK_MAP, STATUS, RISKS, DECISIONS, REVIEW_LOG, and chunk + contracts; +- canonical checker, artifact-policy, data-model, authorization, and roadmap + documentation where sequencing is stated; +- planning review evidence and PR trust bundle; +- CI metadata only when needed to preserve existing documentation gates. + +## Not Allowed Changes + +- application code, migrations, runtime schemas, routes, services, or tests; +- AUTH action availability or grants; +- partial removal or replacement of the legacy precheck; +- catalogue, execution, admission, Submission, checker, review, or contribution + behavior. + +## Acceptance Criteria + +- 04A4 is explicitly superseded and authorizes no runtime implementation; +- 04B1 is the next ART implementation chunk; +- 05B owns removal of the standalone route, OpenAPI schemas, public service + entry point, internal legacy Submission guard, and caller-owned package facts; +- the legacy path remains frozen and receives no new features or adapters; +- no unchecked Submission path, alias, redirect, fallback, private + compatibility service, or second checker registry is introduced; +- canonical sequencing and risk records agree; +- required L1 planning reviewers approve the correction. + +## Verification Commands + +```bash +git diff --check +python3 scripts/check_stale_artifact_contracts.py +python3 scripts/check_stale_workstream_wording.py +python3 scripts/check_markdown_links.py +PYTHONPATH=. python3 scripts/test_lightweight_agent_gates.py +``` + +## Required Reviewers + +Architecture, security/auth, product/ops, senior engineering, QA/test, docs, +reuse/dedup, CI integrity, and test delta. + +## Human Review Focus + +- Does this produce one complete deletion rather than a partial cleanup? +- Is legacy safety preserved until verified admission is authoritative? +- Is 04B1 unblocked without adding runtime scope to this planning PR? + +## Stop Conditions + +Stop if the replacement path is assumed live before 04C2, 05A, and required +AUTH activation merge, or if any runtime behavior is needed to make the plan +internally consistent. diff --git a/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/reviews/WS-ART-001-PLAN5-internal-review-evidence.md b/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/reviews/WS-ART-001-PLAN5-internal-review-evidence.md new file mode 100644 index 000000000..48567eaf1 --- /dev/null +++ b/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/reviews/WS-ART-001-PLAN5-internal-review-evidence.md @@ -0,0 +1,41 @@ +# WS-ART-001 PLAN5 Internal Review Evidence + +Reviewed change: planning-only legacy-precheck clean-cut resequencing + +## Result + +| Track | Final result | Disposition | +|---|---|---| +| Architecture | PASS | Complete deletion coherently belongs to the admission-backed 05B cutover. | +| Security/auth | PASS WITH LOW RISKS | Stale 04B1 entry-gate wording repaired; fail-closed sequencing preserved. | +| Product/ops | PASS | Active docs now distinguish frozen legacy behavior from the post-05B target. | +| Senior engineering | PASS WITH LOW RISKS | 04B1 gate and PLAN5 shorthand normalized. | +| QA/test | PASS | 05B now carries explicit state, replay, concurrency, dispatch, and reachability proof. | +| Docs | PASS | Current architecture, glossary, operations, templates, and data-flow wording aligned. | +| Reuse/dedup | PASS | No duplicate path/registry ownership or conflicting active wording remains. | +| CI integrity | PASS WITH CONDITIONS | No CI changes or weakening; exact 05B commands/include paths must be locked before 05B implementation. | +| Test delta | PASS | No tests changed; future proof obligations moved rather than removed. | + +## Findings Repaired + +- Replaced the unsafe early 04A4 deletion with a planning-only supersession. +- Assigned route, OpenAPI schema, public service, internal guard, and + caller-owned package removal to one 05B cutover. +- Added explicit non-ready/cross-resource admission rejection, mixed-request, + replay, concurrency, single-dispatch, and import-reachability obligations. +- Corrected current-state docs that prematurely claimed the standalone route + was already absent. +- Made 04B1 depend on PLAN5 rather than PLAN4 alone. + +## Deterministic Evidence + +```text +git diff --check: pass +stale artifact contract scan: pass +stale Workstream wording scan: pass +Markdown link check: pass +lightweight agent gates: pass +``` + +No application code, migration, route, service, schema, workflow, or executable +test changed. diff --git a/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/reviews/WS-ART-001-PLAN5-pr-trust-bundle.md b/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/reviews/WS-ART-001-PLAN5-pr-trust-bundle.md new file mode 100644 index 000000000..9e4266fdc --- /dev/null +++ b/.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/reviews/WS-ART-001-PLAN5-pr-trust-bundle.md @@ -0,0 +1,125 @@ +# WS-ART-001 PLAN5 PR Trust Bundle + +## Chunk + +`WS-ART-001-PLAN5` — Legacy Precheck Clean-Cut Resequencing + +## Goal + +Remove the complete legacy contributor precheck once and for all without ever +exposing unchecked Submission creation or preserving a compatibility seam. + +## Human-Approved Intent + +The user explicitly chose complete legacy removal and approved updating the +plan now instead of keeping a partial private path. + +## What Changed + +- superseded proposed runtime chunk 04A4; +- made 04B1 the next ART implementation chunk; +- expanded 05B to remove the standalone route, schemas, public service entry, + internal legacy guard, and caller-owned package authority together; +- aligned canonical architecture, AUTH, glossary, operations, template, and + current-data-flow wording; +- strengthened 05B state, replay, concurrency, dispatch, and reachability proof. + +## Why It Changed + +Live legacy `TaskService.create_submission` still uses the same precheck service +as the standalone route. Early service deletion would permit unchecked +Submission creation, break the live path, or require a forbidden compatibility +service. The verified-admission replacement is not live until later chunks. + +## Design Chosen + +Freeze the legacy path without extending it while 04B1-04C2 and 05A build the +authoritative replacement. At 05B, make verified admission consumption the only +Submission path and delete every legacy entry and caller-owned identity field in +the same cutover. + +## Alternatives Rejected + +- Early complete deletion: replacement is not live. +- Route-only deletion with private legacy service: creates a partial cleanup and + a compatibility seam. +- Dual old/new paths: permits authority ambiguity and duplicate business effects. + +## Scope Control + +Planning and documentation only. No application code, database migration, +runtime schema, route, service, workflow, AUTH availability, or executable test +changed. + +## Product Behavior + +No product behavior changes in PLAN5. Current legacy behavior remains frozen +until 05B; the target behavior remains one continuous ZIP preparation and +admission-backed Submission path. + +## Acceptance Criteria Proof + +- 04A4 is superseded and authorizes no runtime work. +- 04B1 is explicitly next after PLAN5. +- 05B owns the entire legacy clean cut. +- No alias, fallback, private compatibility service, or second registry is + planned. +- Current and target-state documentation are explicitly distinguished. + +## Tests And Checks Run + +```text +git diff --check +python3 scripts/check_stale_artifact_contracts.py +python3 scripts/check_stale_workstream_wording.py +python3 scripts/check_markdown_links.py +PYTHONPATH=. python3 scripts/test_lightweight_agent_gates.py +``` + +All passed. + +## Test Delta + +No executable tests changed. Future 05B obligations were strengthened to cover +admission states, cross-resource denial, mixed requests, replay, concurrency, +single dispatch, route/OpenAPI absence, and import/public-service reachability. + +## CI Integrity + +No workflow or gate changed. Existing 90 percent subsystem and 78 percent +repository coverage requirements remain. Exact 05B shell commands and include +paths must be locked before 05B implementation. + +## Reviewer Results + +Architecture, product/ops, QA, docs, reuse, and test delta: PASS. Security and +senior engineering: PASS WITH LOW RISKS after repairs. CI integrity: PASS WITH +CONDITIONS applying only before future 05B implementation. + +## External Review + +GitHub CI and CodeRabbit begin after this planning branch is pushed. + +## Remaining Risks + +The frozen legacy path still exists until 05B, but receives no new behavior and +remains mandatory for legacy Submission safety. 05B must not begin until the +verified-admission replacement and required AUTH activation are merged. + +## Follow-Up Work + +After human merge, implement only 04B1. Do not start 04B2 automatically. + +## Human Review Focus + +- Is one complete 05B deletion preferable to partial early cleanup? +- Are all legacy surfaces named in the 05B contract? +- Does the sequence preserve checked Submission creation at every point? + +## Human Merge Ownership + +- [ ] I can explain what changed. +- [ ] I can explain why it changed. +- [ ] I know what could break. +- [ ] I accept the remaining risks. +- [ ] I explicitly approve this PR for merge. diff --git a/docs/architecture_checker_framework.md b/docs/architecture_checker_framework.md index b90928ffb..67610222f 100644 --- a/docs/architecture_checker_framework.md +++ b/docs/architecture_checker_framework.md @@ -229,9 +229,9 @@ Workstream default submission artifact rules require: - safe relative artifact paths - production artifact hashes shaped as `sha256:<64 lowercase hex>` - pre-cutover only: validated caller-supplied storage references and manifest; - `WS-ART-001-04A4` removes the standalone caller-owned precheck, and - `WS-ART-001-05B` removes the remaining Submission fields so checkers consume - Workstream artifact bindings only + `WS-ART-001-05B` removes the standalone caller-owned precheck, its internal + legacy Submission guard, and the remaining Submission fields together so + checkers consume Workstream artifact bindings only - no credentials, signed URLs, query strings, raw local filesystem paths, or token-bearing references - narrowly high-confidence sensitive-file exclusions such as `.env`, `.git`, exact known credential/private-key files, `.pem`, and `.key`; broad @@ -247,8 +247,9 @@ contributor pipeline. Tasks lock references to the shared project's compiled che bundle hash. It runs inside continuous submission-bundle preparation before Workstream creates a submission. Failures return the bounded same-request code `pre_submission_checker_failed` with status, eligibility, and structured -pass/fail/warning details. There is no standalone preflight route, and this is -not a review decision value. +pass/fail/warning details. Until ART-05B, the old standalone preflight route is +frozen legacy behavior and is not an authoritative result for the new path. +ART-05B removes it completely; this result is not a review decision value. Pre-submit results do not create durable `CheckerRun` records, do not move a task to `review_pending`, and do not return review decision values: `accept`, `needs_revision`, or `reject`. diff --git a/docs/architecture_data_model.md b/docs/architecture_data_model.md index de07fdec7..374e9038f 100644 --- a/docs/architecture_data_model.md +++ b/docs/architecture_data_model.md @@ -779,17 +779,18 @@ The generated checker order is deterministic: 8. contributor attestation validation 9. low-quality artifact warnings -The legacy standalone `/tasks/{id}/submission-precheck` path is superseded. -Pre-submit runs only inside the same process-local preparation request that owns -the uploaded ZIP and bounded scratch generation: +At the ART-05B cutover, the legacy standalone +`/tasks/{id}/submission-precheck` path is removed. Pre-submit then runs only +inside the same process-local preparation request that owns the uploaded ZIP +and bounded scratch generation: ```text POST /api/v1/tasks/{id}/submission-bundle-preparations 422 DomainError(code="pre_submission_checker_failed", details={status, eligible_to_submit, results}) ``` -No independent precheck route or client-owned manifest can reproduce the -authoritative result. `POST /api/v1/tasks/{id}/submissions` consumes the verified ready +After that cutover no independent precheck route or client-owned manifest can +reproduce the authoritative result. `POST /api/v1/tasks/{id}/submissions` consumes the verified ready admission and does not receive scratch paths or rerun the pre-submit plan. Blocking pre-submit failures prevent submission creation, create no submission diff --git a/docs/architecture_lockdown.md b/docs/architecture_lockdown.md index 99265240c..924871bd1 100644 --- a/docs/architecture_lockdown.md +++ b/docs/architecture_lockdown.md @@ -132,8 +132,9 @@ attempt ID, effective-plan hash, terminal status, pass/warning/failure counts, and a bounded ordered list of catalogue ID/version plus stable outcome code. It excludes filenames, archive paths, scratch/provider references, credentials, raw checker output, evidence content, and free-form or unbounded messages. This -is audit evidence, not a product review decision. No independently invocable -preflight route exists. +is audit evidence, not a product review decision. The independently invocable +legacy preflight route remains frozen until ART-05B removes it together with the +legacy Submission path; it is never an alternate authority for this flow. Tasks lock to the active guide version at creation or screening time before entering `READY`. Material guide changes require a new guide version. diff --git a/docs/current_system_data_flow.html b/docs/current_system_data_flow.html index 83e0cf785..0aa3cd0bd 100644 --- a/docs/current_system_data_flow.html +++ b/docs/current_system_data_flow.html @@ -515,7 +515,7 @@

Contributor claims and starts

6

Pre-submit intake checks run

-

Workstream runs one effective pre-submission plan against the uploaded outer ZIP in bounded scratch before creating a submission. Failed preparation returns bounded same-request pre_submission_checker_failed details; there is no standalone preflight route.

+

Workstream runs one effective pre-submission plan against the uploaded outer ZIP in bounded scratch before creating a submission. Failed preparation returns bounded same-request pre_submission_checker_failed details. The frozen legacy preflight route remains non-authoritative until ART-05B removes it with the legacy Submission path.

no submission yet no checker run yet diff --git a/docs/decision_0011_submission_artifact_policy_drives_pre_submit.md b/docs/decision_0011_submission_artifact_policy_drives_pre_submit.md index f7dae98e9..d946fe0fb 100644 --- a/docs/decision_0011_submission_artifact_policy_drives_pre_submit.md +++ b/docs/decision_0011_submission_artifact_policy_drives_pre_submit.md @@ -253,9 +253,10 @@ Blocking pre-submit failures prevent submission creation. When blocking pre-subm structured checker result for project operators - the response does not use review decision values: `accept`, `needs_revision`, or `reject` -The legacy standalone `/tasks/{id}/submission-precheck` contract is superseded. -Pre-submit checks now run only inside the continuous submission-bundle -preparation request against the exact uploaded ZIP in bounded scratch: +At the ART-05B cutover, the legacy standalone +`/tasks/{id}/submission-precheck` contract is removed. Pre-submit checks then +run only inside the continuous submission-bundle preparation request against +the exact uploaded ZIP in bounded scratch: ```text POST /api/v1/tasks/{id}/submission-bundle-preparations @@ -266,8 +267,8 @@ POST /api/v1/tasks/{id}/submission-bundle-preparations } ``` -There is no independently invocable precheck route and no reusable client-owned -manifest input. The bounded result is returned only to the authorized actor in +After that cutover there is no independently invocable precheck route and no +reusable client-owned manifest input. The bounded result is returned only to the authorized actor in that same request. A passing preparation later returns an admission identity; `POST /api/v1/tasks/{id}/submissions` consumes that verified ready admission under its separate fresh authority and does not rerun scratch-bound checks. diff --git a/docs/glossary.md b/docs/glossary.md index 80dec9224..2eefe70d0 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -225,7 +225,7 @@ The deterministic merge of Workstream's default submission artifact policy and t ## Pre-Submit Checker Policy -The server-generated project checker matrix produced from the effective project submission artifact policy and one immutable default-catalogue snapshot. The compiled bundle embeds the catalogue version, canonical manifest digest, ordered entry ID/version/configuration hashes, and enabled/disabled state. Its compiled bundle hash therefore commits transitively to that exact snapshot, and each task locks that hash before entering the contributor pipeline. Runtime uses the same snapshot to derive the effective-plan hash. It runs against the uploaded ZIP in bounded scratch before Workstream creates a submission. A failed preparation returns `pre_submission_checker_failed` with bounded same-request details. There is no standalone preflight route, and results never use review decision values: `accept`, `needs_revision`, or `reject`. +The server-generated project checker matrix produced from the effective project submission artifact policy and one immutable default-catalogue snapshot. The compiled bundle embeds the catalogue version, canonical manifest digest, ordered entry ID/version/configuration hashes, and enabled/disabled state. Its compiled bundle hash therefore commits transitively to that exact snapshot, and each task locks that hash before entering the contributor pipeline. Runtime uses the same snapshot to derive the effective-plan hash. It runs against the uploaded ZIP in bounded scratch before Workstream creates a submission. A failed preparation returns `pre_submission_checker_failed` with bounded same-request details. The old standalone preflight route remains frozen legacy behavior until ART-05B removes it with the legacy Submission path; it is not an alternate authority for this policy. Results never use review decision values: `accept`, `needs_revision`, or `reject`. ## pre_submission_checker_failed diff --git a/docs/operations_project_operating_manual.md b/docs/operations_project_operating_manual.md index 0a1f030aa..11d755c24 100644 --- a/docs/operations_project_operating_manual.md +++ b/docs/operations_project_operating_manual.md @@ -253,7 +253,9 @@ Before locking a submission packet: - effective project submission artifact policy is loaded - generated project pre-submit checker policy runs - failed submission-bundle preparation returns `pre_submission_checker_failed` with bounded same-request status, eligibility, and pass/fail/warning details -- no standalone preflight endpoint or client-owned manifest can reproduce the authoritative result +- until ART-05B, the frozen legacy preflight endpoint remains non-authoritative; + after the cutover no standalone endpoint or client-owned manifest can + reproduce the authoritative result - no submission row is created until blocking pre-submit checks pass - successful submission creation stamps the immutable submission boundary and queues the Celery pre-review gate - `/finalize` is an Operator repair/requeue endpoint under diff --git a/docs/spec_authorization_service.md b/docs/spec_authorization_service.md index 486d0e0c7..248c3b7c5 100644 --- a/docs/spec_authorization_service.md +++ b/docs/spec_authorization_service.md @@ -408,7 +408,7 @@ The paired artifact hidden-behavior matrix is closed: | `WS-ART-001-02D` | Operator binding/replica/receipt/verification-job/recovery-attempt/audit reads; the operations-domain `operations.artifact_storage_admission.read` action mapped to `operations.status.read`; verification retry; `artifact.verification.execute`; `artifact.pending_work.scan`; and `artifact.put_attempt.resolve` | | `WS-ART-001-03` | Hidden guide behavior for `artifact.guide_source.ingest -> artifact.guide_source.ingest`, `artifact.guide_source.read -> artifact.guide_source.read`, and `artifact.guide_source.binding.create -> artifact.binding.create`; AUTH activation custody is split between WS-XINT-002-04A and 04B below | | `WS-ART-001-04A` historical baseline | the former multi-step upload authority had no route/command and is deleted from the live catalogue by WS-XINT-002-01 without compatibility aliases | -| `WS-ART-001-04A1` through `04C2` | one hidden `artifact.submission_bundle.prepare` surface mapped to `submission.create`; 04A4 removes the legacy standalone precheck after 04A3, 04B1-04B3 implement the sole catalogue/materialization/evidence path, XINT-002-06A activates its fixed pre-submit materializer before 04C1, and the contributor action remains unavailable until complete 04C2 evidence and WS-XINT-002-05A | +| `WS-ART-001-04A1` through `04C2` | one hidden `artifact.submission_bundle.prepare` surface mapped to `submission.create`; 04B1-04B3 implement the sole catalogue/materialization/evidence path, XINT-002-06A activates its fixed pre-submit materializer before 04C1, and the contributor action remains unavailable until complete 04C2 evidence and WS-XINT-002-05A; 05B removes the frozen legacy precheck only when admission-backed Submission becomes authoritative | | `WS-ART-001-04B2` and `04B3` | hidden `artifact.pre_submit.checker_input.materialize` resource/guard usage mapped to `artifact.checker_input.materialize`; 04B2 owns exact sealed materialization and 04B3 consumes it in the complete effective plan | | `WS-ART-001-05` | `artifact.submission.binding.create` mapped to `artifact.binding.create` | | `WS-ART-001-06A` | `artifact.post_submit.checker_input.materialize` mapped to `artifact.checker_input.materialize` | @@ -417,7 +417,7 @@ The paired artifact hidden-behavior matrix is closed: WS-XINT-002-01 deletes the former multi-step authority and registers planned `artifact.submission_bundle.prepare -> submission.create`. No ART implementation may execute that ActionId while it remains planned. The mandatory order is -ART-04A1 -> 04A2 -> 04A3 -> PLAN4 -> 04A4 -> 04B1 -> 04B2 -> 04B3 -> +ART-04A1 -> 04A2 -> 04A3 -> PLAN4 -> PLAN5 -> 04B1 -> 04B2 -> 04B3 -> XINT-002-06A -> ART-04C1 -> 04C2 -> XINT-002-05A. This ensures fixed-service pre-submit materialization is active before contributor preparation can become live. diff --git a/docs/template_checker_policy.md b/docs/template_checker_policy.md index 5753b3d71..7d4f15403 100644 --- a/docs/template_checker_policy.md +++ b/docs/template_checker_policy.md @@ -73,8 +73,9 @@ PreSubmitCheckerPolicy = Failed continuous submission-bundle preparation returns `DomainError(code="pre_submission_checker_failed")` with bounded same-request -status, eligibility, and pass/fail/warning details. There is no standalone -preflight route. Pre-submit failures do not create durable +status, eligibility, and pass/fail/warning details. The old standalone +preflight route remains frozen until ART-05B removes it with the legacy +Submission path; it is not part of this effective policy. Pre-submit failures do not create durable `CheckerRun` records and do not return review decision values: `accept`, `needs_revision`, or `reject`. diff --git a/docs/template_submission_artifact_policy.md b/docs/template_submission_artifact_policy.md index e4f88f0da..32e8d9546 100644 --- a/docs/template_submission_artifact_policy.md +++ b/docs/template_submission_artifact_policy.md @@ -223,9 +223,10 @@ do not derive or compile their own checker by default. Failed submission-bundle preparation returns `pre_submission_checker_failed` with bounded same-request status, eligibility, -and pass/fail/warning details. No independently invocable preflight endpoint or -ID-addressed evidence-read route exists. These results never use review decision -values: `accept`, `needs_revision`, or `reject`. After verified preparation, +and pass/fail/warning details. The frozen legacy preflight endpoint remains +non-authoritative until ART-05B removes it with the legacy Submission path; no +ID-addressed evidence-read route exists. These results never use review decision values: +`accept`, `needs_revision`, or `reject`. After verified preparation, final Submission creation consumes the ready admission under fresh authority and does not rerun scratch-bound checks. diff --git a/docs/template_submission_packet.md b/docs/template_submission_packet.md index 6a207ae4c..0e6009bcb 100644 --- a/docs/template_submission_packet.md +++ b/docs/template_submission_packet.md @@ -57,7 +57,9 @@ returns `pre_submission_checker_failed` with bounded same-request structured details, creates no submission row, no submission version, and no submission-created audit event, and does not return review decision values: `accept`, `needs_revision`, or -`reject`. There is no standalone preflight endpoint. +`reject`. The frozen legacy standalone preflight endpoint remains temporary +until ART-05B removes it with the legacy Submission path; it is not an +authoritative result for this packet. ## Submission Bundle Manifest