docs(artifacts): reconcile submission bundle plan#197
Merged
abiorh-claw merged 26 commits intoJul 25, 2026
Conversation
📝 WalkthroughWalkthroughThis planning-only PR reconciles WS-ART-001 around one outer-ZIP submission bundle, bounded scratch, canonical manifests, immutable admission and binding, explicit AUTH handoffs, split successor chunks, updated public contracts, and revised agent-gate expectations. No runtime behavior is activated. ChangesWS-ART-001 immutable artifact storage
Estimated code review effort: 3 (Moderate) | ~25 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/INTENT.md (1)
31-40: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick winScope archive identities to Submission bundles.
The generic artifact chain adds “verified archive identity” and “canonical semantic-manifest commitment” before bindings for guides, checker inputs, logs, and outputs, but only contributor submissions are defined as outer ZIPs with semantic manifests. Keep those identities in the Submission-bundle branch, or explicitly define when they are applicable; otherwise non-ZIP artifacts inherit an impossible or ambiguous contract.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/INTENT.md around lines 31 - 40, Update the artifact-chain flow around “verified archive identity” and “canonical semantic-manifest commitment” so these requirements apply only to Submission bundles, which are defined as outer ZIPs with semantic manifests. Keep guide, checker-input, log, and output bindings on the generic immutable artifact path, or explicitly define their applicability without imposing ZIP or manifest requirements.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In
@.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-04A-upload-inspection-sealing.md:
- Around line 66-78: Resolve the contradiction between the 04A scope and the
`artifact.submission_bundle.prepare` declaration: move the contributor
route/action declaration and its AUTH mapping to 04C, or explicitly mark it as a
non-routable manifest entry that cannot be exposed or activated by 04A. Keep 04A
limited to internal seams and tests, with no contributor route available before
04C.
- Line 5: Change the artifact contract phase for chunk 04A from
guide_source_cutover to the submission-admission phase, matching the
artifact.submission_bundle.prepare flow. Leave the upload_admission phase
assignments for chunks 04B and 04C unchanged.
In @.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/PLAN.md:
- Around line 278-296: Update the “Server-Generated Submission Bundle Identity”
contract to define canonical path normalization, including path, case, and
Unicode rules, and require rejection of duplicate or colliding canonical paths.
Ensure collision validation occurs before prechecks, manifest generation,
materialization, or provider I/O so unchanged-work detection and the checked
tree use the same canonical paths.
In @.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/RISKS.md:
- Line 30: Update the legacy planned upload-session mitigation in RISKS.md to
state that ART-04A removes only ART-side reachability. Explicitly assign
retirement or unavailable-state proof for AUTH-owned ActionIds and routes to the
AUTH registration contract, and require that handoff before the single bundle
action activates.
In @.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/STATUS.md:
- Around line 50-53: Update the successor description in STATUS.md to call
WS-ART-001-03A the “only immediate successor” instead of the “only declared ART
successor,” while preserving the surrounding details about hidden guide-source
ingest, signed start, and AUTH behavior.
In `@docs/spec_artifact_storage_service.md`:
- Around line 141-144: The artifact storage specification uses inconsistent
ArtifactPutAttempt states. Define one canonical enum for attempt states,
separate it from replica states, and update all declarations, transitions, and
references—including replay_required and stored_pending_verification—to use only
the canonical vocabulary before implementation.
In `@docs/template_submission_artifact_policy.md`:
- Around line 101-102: Update the client-required fields in the template
submission artifact policy to remove the contributor-supplied artifact hash
manifest requirement, consistent with the one-ZIP submission rule. If manifest
information must remain documented, describe it as a server-generated output or
reference rather than client input, and align the surrounding requirements with
the storage and packet specifications.
---
Outside diff comments:
In @.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/INTENT.md:
- Around line 31-40: Update the artifact-chain flow around “verified archive
identity” and “canonical semantic-manifest commitment” so these requirements
apply only to Submission bundles, which are defined as outer ZIPs with semantic
manifests. Keep guide, checker-input, log, and output bindings on the generic
immutable artifact path, or explicitly define their applicability without
imposing ZIP or manifest requirements.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 7e39002a-6649-4ec0-9f33-d1c707d60e6c
📒 Files selected for processing (28)
.agent-loop/REVIEW_LOG.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/AUTH_HANDOFF.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/CHUNK_MAP.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/DECISIONS.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/INTENT.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/PLAN.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/RISKS.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/STATUS.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-03-guide-source-cutover.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-03A-guide-source-byte-ingest.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-03B-guide-source-binding-materialization.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-03C-guide-source-cutover-continuation.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-04A-upload-inspection-sealing.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-04B-pre-submit-admission.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-04C-verified-submission-bundle-admission.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-05-submission-artifact-cutover.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-06A-checker-input-materialization.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-07-recovery-live-proof.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-PLAN2-submission-bundle-reconciliation.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/reviews/WS-ART-001-PLAN2-internal-review-evidence.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/reviews/WS-ART-001-PLAN2-pr-trust-bundle.md.agent-loop/merge-intents/WS-ART-001-PLAN2.jsondocs/glossary.mddocs/spec_artifact_storage_service.mddocs/spec_authorization_service.mddocs/template_submission_artifact_policy.mddocs/template_submission_packet.mdscripts/test_agent_gates.py
There was a problem hiding this comment.
Actionable comments posted: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-03B-guide-source-binding-materialization.md (2)
32-38: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick winMake the AUTH handoff concrete.
Lines [32-38] only say that read/binding actions remain fail-closed, but the upstream contract requires the exact actions
artifact.guide_source.readandartifact.guide_source.binding.create, the mapping toartifact.binding.create, and evidence against the AUTH registry, static matrix, provisioned identities, and runtime admission. Without those details, implementations can satisfy this contract with incompatible action names or incomplete authorization checks.Proposed clarification
- fixed guide read/binding actions remain fail-closed until AUTH activation; +- guide reads use `artifact.guide_source.read`, binding creation uses + `artifact.guide_source.binding.create` mapped to `artifact.binding.create`, + and both remain fail-closed until AUTH activation; +- tests verify the canonical resource composers, guards, surface declarations, + AUTH registry, static matrix, provisioned identities, and runtime admission;🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-03B-guide-source-binding-materialization.md around lines 32 - 38, Make the AUTH handoff requirements explicit in the guide: name the exact actions artifact.guide_source.read and artifact.guide_source.binding.create, define their mapping to artifact.binding.create, and require evidence of authorization against the AUTH registry, static matrix, provisioned identities, and runtime admission. Update the fail-closed statement without changing the surrounding artifact integrity requirements.Source: Coding guidelines
60-67: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winAlign local verification with the declared CI gates.
The local coverage command at Lines [62-63] measures only
app.modules.projectsandapp.modules.artifacts, while the exact gates at Lines [45-55] also cover adapters, interfaces, core, workers,app/main.py, audit, routing, and project-agent modules. Local verification can therefore pass without checking most of the declared 90% gates; invoke the same scoped reports locally or explicitly document that only CI performs them.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-03B-guide-source-binding-materialization.md around lines 60 - 67, Update the local verification commands in the documented test workflow to include the same coverage scopes and 90% gates declared in the CI commands, including adapters, interfaces, core, workers, app/main.py, audit, routing, and project-agent modules. Preserve the existing test execution and other verification steps, or explicitly state that these scoped coverage checks are performed only by CI.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/template_preflight_evidence.md`:
- Around line 41-43: Update the evidence template fields around the manifest
reference/hash to separate verified admission or operation IDs from immutable
artifact-binding IDs, replacing the combined “verified admission/binding IDs”
field with explicit fields for each identity type. Keep the evidence-ID field
explicitly tied to both the verified admission and manifest.
In `@docs/template_project_guide.md`:
- Line 83: Update the ZIP contents wording in the project guide by replacing
“every required output/evidence file” with “every output and evidence file
required by the task,” leaving the surrounding requirement unchanged.
- Around line 83-91: Clarify the submission requirements around the “evidence”
bullet and the one-ZIP rule: explicitly state whether evidence consists of files
contained inside the required ZIP or server-generated metadata/references
outside the archive. Update the surrounding submission-bundle guidance so
clients know the expected submission shape, while preserving the existing
server-assigned manifest and version behavior.
- Around line 88-91: Update the artifact-manifest terminology in the submission
templates so the server-generated outer-ZIP manifest is consistently called
“SubmissionBundleManifest” or “submission-bundle manifest,” including
docs/template_submission_artifact_policy.md. Remove or explicitly define the
“semantic artifact manifest” wording to map to the canonical term, while
preserving the existing submission workflow description.
---
Outside diff comments:
In
@.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-03B-guide-source-binding-materialization.md:
- Around line 32-38: Make the AUTH handoff requirements explicit in the guide:
name the exact actions artifact.guide_source.read and
artifact.guide_source.binding.create, define their mapping to
artifact.binding.create, and require evidence of authorization against the AUTH
registry, static matrix, provisioned identities, and runtime admission. Update
the fail-closed statement without changing the surrounding artifact integrity
requirements.
- Around line 60-67: Update the local verification commands in the documented
test workflow to include the same coverage scopes and 90% gates declared in the
CI commands, including adapters, interfaces, core, workers, app/main.py, audit,
routing, and project-agent modules. Preserve the existing test execution and
other verification steps, or explicitly state that these scoped coverage checks
are performed only by CI.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 163b1c9c-4180-478d-975b-7ae2e9dd134c
📒 Files selected for processing (25)
.agent-loop/REVIEW_LOG.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/INTENT.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/PLAN.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/RISKS.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/STATUS.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-03-guide-source-cutover.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-03A-guide-source-byte-ingest.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-03B-guide-source-binding-materialization.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-03C-guide-source-cutover-continuation.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-04A-upload-inspection-sealing.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-04B-pre-submit-admission.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-04C-verified-submission-bundle-admission.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-05-submission-artifact-cutover.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-06A-checker-input-materialization.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-07-recovery-live-proof.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-PLAN2-submission-bundle-reconciliation.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/reviews/WS-ART-001-PLAN2-external-review-response.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/reviews/WS-ART-001-PLAN2-internal-review-evidence.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/reviews/WS-ART-001-PLAN2-pr-trust-bundle.mddocs/operations_queue_policy.mddocs/spec_artifact_storage_service.mddocs/template_preflight_evidence.mddocs/template_project_guide.mddocs/template_submission_artifact_policy.mdscripts/test_agent_gates.py
🚧 Files skipped from review as they are similar to previous changes (18)
- .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-03C-guide-source-cutover-continuation.md
- .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-06A-checker-input-materialization.md
- .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-03-guide-source-cutover.md
- .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-04C-verified-submission-bundle-admission.md
- .agent-loop/REVIEW_LOG.md
- .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/STATUS.md
- .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/reviews/WS-ART-001-PLAN2-internal-review-evidence.md
- .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-PLAN2-submission-bundle-reconciliation.md
- .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-07-recovery-live-proof.md
- .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-03A-guide-source-byte-ingest.md
- .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-04A-upload-inspection-sealing.md
- .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-05-submission-artifact-cutover.md
- .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/INTENT.md
- .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-04B-pre-submit-admission.md
- .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/PLAN.md
- docs/spec_artifact_storage_service.md
- .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/RISKS.md
- scripts/test_agent_gates.py
Abiorh001
force-pushed
the
codex/ws-art-001-plan2-submission-bundle-reconciliation
branch
from
July 25, 2026 10:16
8df30d0 to
f0a9cfe
Compare
There was a problem hiding this comment.
Actionable comments posted: 8
♻️ Duplicate comments (1)
docs/template_project_guide.md (1)
83-91: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick winClarify whether
evidenceis inside the ZIP.The one-ZIP requirement still says the archive contains all output/evidence files while the adjacent
evidencebullet reads like a separate contributor field. Remove that bullet if evidence is ZIP content, or explicitly define it as server-generated metadata/references. Also replace “every required output/evidence file” with “every output and evidence file required by the task.”Proposed wording
-- exactly one outer ZIP containing every required output/evidence file -- evidence +- exactly one outer ZIP containing every output and evidence file required by + the task🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/template_project_guide.md` around lines 83 - 91, Clarify the submission bundle requirements in the documented archive checklist: replace “every required output/evidence file” with “every output and evidence file required by the task,” and resolve the adjacent “evidence” bullet by removing it if evidence is ZIP content or explicitly defining it as server-generated metadata/references.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In
@.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-03C-guide-source-cutover-continuation.md:
- Around line 60-69: Update the Verification block to include the repository’s
required Markdown-link validation and canonical stale-wording scan alongside the
existing checks. Reuse the established CI commands or reference the canonical
validation command, ensuring the documented gates detect stale links and wording
before the successor passes.
In
@.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-PLAN2-submission-bundle-reconciliation.md:
- Around line 70-80: Clarify the lifecycle in the plan: 04C should publish
verified payloads as `ArtifactContent` in the `ready` admission state without
binding them to a Submission, while 05 later consumes `ready` admissions into
immutable Submission bindings. Update the conflicting bullets near the admission
publication and lifecycle descriptions, preserving the existing identity,
verification, receipt, and recovery abstractions.
In @.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/DECISIONS.md:
- Around line 282-295: Update the D31 canonical submission bundle identity text
to remove the duplicated “ownership” entry, leaving the excluded metadata list
as “comments, ownership, group...” while preserving all other wording and
behavior.
- Around line 269-280: Update decision D30 so “checker-failing” refers only to
failures during pre-submit or checker-gating checks before durable admission.
State that post-admission checker materialization/read failures preserve the
immutable object and admission, surface as an artifact or infrastructure result,
and do not imply rollback or deletion; keep the existing scratch and
ArtifactStore flow unchanged.
In
@.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/reviews/WS-ART-001-PLAN2-pr-trust-bundle.md:
- Around line 50-53: Update the AUTH sequencing statement in the trust-bundle
plan to separate registration from activation: require planned registration and
retirement of session actions before ART-04A, then require activation of the
exact bundle action only after ART-04C’s manifest/guard proof and before ART-05.
Do not imply activation is required for ART-04A.
In `@docs/spec_artifact_storage_service.md`:
- Around line 1163-1176: Expand the “Product Submission-Bundle APIs” section to
define the preparation POST contract: ZIP-byte upload content type, request
fields, bounded redacted response, client correlation/idempotency key, and exact
retry behavior before and after durable intent. Specify how retries observe the
same durable operation without exposing scratch paths or provider internals,
including the response when no durable intent exists, and align the contract
with the absence of a preparation-status GET route.
In `@scripts/check_stale_authorization_docs.py`:
- Around line 405-409: Update the Celery detection logic surrounding
exact_celery_module_path and exact_code_path so a command ending with workers
before the whitespace and worker options is recognized as an exact module path.
Ensure exact_code_path accepts workers as the final module component in commands
such as celery -A app.workers worker --loglevel=INFO, while preserving existing
handling for deeper module paths.
- Around line 397-415: Refine code_path_has_prose in the stale-authorization
parsing flow so command arguments and technical qualifiers such as “ --reload”
are not classified as prose after path stripping. Use delimiter-aware parsing or
explicit supported command forms, and add regression tests covering references
with arguments and qualifiers while preserving genuine prose detection and the
existing exact coverage/Celery exceptions.
---
Duplicate comments:
In `@docs/template_project_guide.md`:
- Around line 83-91: Clarify the submission bundle requirements in the
documented archive checklist: replace “every required output/evidence file” with
“every output and evidence file required by the task,” and resolve the adjacent
“evidence” bullet by removing it if evidence is ZIP content or explicitly
defining it as server-generated metadata/references.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 02066dd4-ec4a-4ffb-b1a5-a73afb7314ba
📒 Files selected for processing (33)
.agent-loop/REVIEW_LOG.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/AUTH_HANDOFF.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/CHUNK_MAP.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/DECISIONS.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/INTENT.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/PLAN.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/RISKS.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/STATUS.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-03-guide-source-cutover.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-03A-guide-source-byte-ingest.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-03B-guide-source-binding-materialization.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-03C-guide-source-cutover-continuation.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-04A-upload-inspection-sealing.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-04B-pre-submit-admission.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-04C-verified-submission-bundle-admission.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-05-submission-artifact-cutover.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-06A-checker-input-materialization.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-07-recovery-live-proof.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-PLAN2-submission-bundle-reconciliation.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/reviews/WS-ART-001-PLAN2-external-review-response.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/reviews/WS-ART-001-PLAN2-internal-review-evidence.md.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/reviews/WS-ART-001-PLAN2-pr-trust-bundle.md.agent-loop/merge-intents/WS-ART-001-PLAN2.jsondocs/glossary.mddocs/operations_queue_policy.mddocs/spec_artifact_storage_service.mddocs/spec_authorization_service.mddocs/template_preflight_evidence.mddocs/template_project_guide.mddocs/template_submission_artifact_policy.mddocs/template_submission_packet.mdscripts/check_stale_authorization_docs.pyscripts/test_agent_gates.py
🚧 Files skipped from review as they are similar to previous changes (22)
- .agent-loop/merge-intents/WS-ART-001-PLAN2.json
- .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-03B-guide-source-binding-materialization.md
- docs/operations_queue_policy.md
- .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-04C-verified-submission-bundle-admission.md
- .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/reviews/WS-ART-001-PLAN2-external-review-response.md
- docs/template_preflight_evidence.md
- .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-07-recovery-live-proof.md
- .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-05-submission-artifact-cutover.md
- docs/template_submission_packet.md
- .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-06A-checker-input-materialization.md
- .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-03A-guide-source-byte-ingest.md
- docs/template_submission_artifact_policy.md
- .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/INTENT.md
- .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/AUTH_HANDOFF.md
- docs/spec_authorization_service.md
- .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/reviews/WS-ART-001-PLAN2-internal-review-evidence.md
- .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/PLAN.md
- .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/STATUS.md
- .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-04B-pre-submit-admission.md
- .agent-loop/REVIEW_LOG.md
- .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-04A-upload-inspection-sealing.md
- scripts/test_agent_gates.py
Comment on lines
+60
to
+69
| ## Verification | ||
|
|
||
| ```bash | ||
| docker compose up -d --wait postgres redis minio | ||
| (cd backend && WORKSTREAM_TEST_DATABASE_URL=postgresql+asyncpg://workstream:workstream@localhost:5433/workstream_test .venv/bin/pytest tests/test_alembic.py tests/test_projects.py tests/test_project_setup.py tests/test_guide_artifacts.py tests/test_artifact_recovery.py -q --cov=app.modules.projects --cov=app.modules.artifacts --cov=app.workers --cov-report=term-missing --cov-fail-under=90) | ||
| (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 && WORKSTREAM_DATABASE_URL=postgresql+asyncpg://workstream:workstream@localhost:5433/workstream_test .venv/bin/python scripts/api_contract_e2e.py) | ||
| (cd backend && .venv/bin/ruff check app tests) | ||
| python3 scripts/check_stale_artifact_contracts.py | ||
| python3 scripts/test_agent_gates.py |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Include the required documentation validation gates.
This Markdown contract’s verification block omits the repository-required Markdown-link check and does not identify the canonical stale-wording scan. Add those existing CI checks, or reference the canonical validation command, so this successor cannot pass its documented gates with stale links or wording.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
@.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-03C-guide-source-cutover-continuation.md
around lines 60 - 69, Update the Verification block to include the repository’s
required Markdown-link validation and canonical stale-wording scan alongside the
existing checks. Reuse the established CI commands or reference the canonical
validation command, ensuring the documented gates detect stale links and wording
before the successor passes.
Source: Coding guidelines
Comment on lines
+70
to
+80
| - passing bytes are written once, independently read back, verified, published | ||
| as `ArtifactContent`, and bound to the Submission through existing ART | ||
| identity, put-attempt, verification-job, receipt, and recovery abstractions; | ||
| - the plan creates no candidate store, promotion, retention policy, duplicate | ||
| provider write, `ArtifactOutboxRecoveryAttempt`, or provider delete path; | ||
| - process loss before durable admission requires reupload; an ambiguous durable | ||
| put uses existing observation/recovery and never creates a Submission until | ||
| verified content is bindable; | ||
| - a verified admission may remain unbound through client abandonment; its | ||
| closed lifecycle is `ready -> consumed|stale`, every state stays charged to | ||
| existing completed-byte scopes, and v0.1 adds no expiry/release/delete process; |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Separate admission publication from Submission binding.
Lines [70-72] say every passing payload is bound to a Submission during admission, but lines [78-80] allow the verified admission to remain unbound in ready. Clarify that 04C publishes the verified ready admission and 05 later consumes it into the immutable Submission binding.
Proposed wording
-- passing bytes are written once, independently read back, verified, published
-- as `ArtifactContent`, and bound to the Submission through existing ART
-- identity, put-attempt, verification-job, receipt, and recovery abstractions;
+- passing bytes are written once, independently read back, verified, and
+ published as `ArtifactContent` through the existing ART identity,
+ put-attempt, verification-job, receipt, and recovery abstractions; the
+ resulting admission may remain `ready` and unbound until WS-ART-001-05
+ atomically consumes it into the Submission binding;📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| - passing bytes are written once, independently read back, verified, published | |
| as `ArtifactContent`, and bound to the Submission through existing ART | |
| identity, put-attempt, verification-job, receipt, and recovery abstractions; | |
| - the plan creates no candidate store, promotion, retention policy, duplicate | |
| provider write, `ArtifactOutboxRecoveryAttempt`, or provider delete path; | |
| - process loss before durable admission requires reupload; an ambiguous durable | |
| put uses existing observation/recovery and never creates a Submission until | |
| verified content is bindable; | |
| - a verified admission may remain unbound through client abandonment; its | |
| closed lifecycle is `ready -> consumed|stale`, every state stays charged to | |
| existing completed-byte scopes, and v0.1 adds no expiry/release/delete process; | |
| - passing bytes are written once, independently read back, verified, and | |
| published as `ArtifactContent` through the existing ART identity, | |
| put-attempt, verification-job, receipt, and recovery abstractions; the | |
| resulting admission may remain `ready` and unbound until WS-ART-001-05 | |
| atomically consumes it into the Submission binding; | |
| - the plan creates no candidate store, promotion, retention policy, duplicate | |
| provider write, `ArtifactOutboxRecoveryAttempt`, or provider delete path; | |
| - process loss before durable admission requires reupload; an ambiguous durable | |
| put uses existing observation/recovery and never creates a Submission until | |
| verified content is bindable; | |
| - a verified admission may remain unbound through client abandonment; its | |
| closed lifecycle is `ready -> consumed|stale`, every state stays charged to | |
| existing completed-byte scopes, and v0.1 adds no expiry/release/delete process; |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
@.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-PLAN2-submission-bundle-reconciliation.md
around lines 70 - 80, Clarify the lifecycle in the plan: 04C should publish
verified payloads as `ArtifactContent` in the `ready` admission state without
binding them to a Submission, while 05 later consumes `ready` admissions into
immutable Submission bindings. Update the conflicting bullets near the admission
publication and lifecycle descriptions, preserving the existing identity,
verification, receipt, and recovery abstractions.
Comment on lines
+282
to
+295
| ## D31 - Canonical Submission Bundle Identity | ||
|
|
||
| Workstream records both exact archive identity (server-computed SHA-256 and byte | ||
| count) and semantic tree identity. The semantic manifest commits to normalized | ||
| file/directory path, entry type, each file's SHA-256 and byte count, and the | ||
| normalized executable flag for regular files. It does | ||
| not commit to archive timestamps, compression method/level, comments, ownership, | ||
| or ownership, group, read/write/special bits, or other platform permission | ||
| metadata. Valid Unix execute bits are normalized into the sole semantic | ||
| permission flag; non-Unix/invalid mode metadata defaults it to false. Symlinks | ||
| and unsupported special entries are | ||
| rejected. Exact archive equality or semantic-manifest equality with the | ||
| immediate prior immutable Submission rejects before provider I/O. | ||
|
|
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Remove the duplicated “ownership” term.
Line 289 currently reads “comments, ownership, or ownership, group...”; remove the repeated term so the excluded metadata list is unambiguous.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/DECISIONS.md
around lines 282 - 295, Update the D31 canonical submission bundle identity text
to remove the duplicated “ownership” entry, leaving the excluded metadata list
as “comments, ownership, group...” while preserving all other wording and
behavior.
Comment on lines
+397
to
+415
| after_code_reference = re.sub( | ||
| r"^(?:[/.][A-Za-z0-9_.-]+)+", "", authority_suffix | ||
| ) | ||
| exact_coverage_path = bool( | ||
| exact_code_path | ||
| and re.search(r"coverage\s+report\s+--include=['\"]app/$", prefix) | ||
| and re.match(r"/\*['\"](?:\s|$)", suffix) | ||
| ) | ||
| exact_celery_module_path = bool( | ||
| exact_code_path | ||
| and re.search(r"(?:^|\n)[^;\n]*\bcelery\s+-A\s+app\.$", prefix) | ||
| and re.match(r"\s+worker\s+--", after_code_reference) | ||
| ) | ||
| code_path_has_prose = bool( | ||
| exact_code_path | ||
| and not exact_coverage_path | ||
| and not exact_celery_module_path | ||
| and re.search(r"[A-Za-z]", after_code_reference) | ||
| ) |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Do not treat every alphabetic suffix as prose.
For a valid technical reference such as backend/app/workers.py --reload, path stripping leaves --reload; code_path_has_prose then becomes true and Line 435 rejects the code path. This creates false positives in the CI stale-authorization gate. Use delimiter-aware parsing or explicit command forms, with regression tests for arguments and qualifiers.
Also applies to: 435-436
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@scripts/check_stale_authorization_docs.py` around lines 397 - 415, Refine
code_path_has_prose in the stale-authorization parsing flow so command arguments
and technical qualifiers such as “ --reload” are not classified as prose after
path stripping. Use delimiter-aware parsing or explicit supported command forms,
and add regression tests covering references with arguments and qualifiers while
preserving genuine prose detection and the existing exact coverage/Celery
exceptions.
Comment on lines
+405
to
+409
| exact_celery_module_path = bool( | ||
| exact_code_path | ||
| and re.search(r"(?:^|\n)[^;\n]*\bcelery\s+-A\s+app\.$", prefix) | ||
| and re.match(r"\s+worker\s+--", after_code_reference) | ||
| ) |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Make Celery matching work when workers is the final module component.
exact_celery_module_path is gated by exact_code_path, but exact_code_path only succeeds when text after workers starts with / or .. In the canonical command celery -A app.workers worker --loglevel=INFO, the suffix starts with whitespace, so this new branch is false and the technical reference can be reported as stale.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@scripts/check_stale_authorization_docs.py` around lines 405 - 409, Update the
Celery detection logic surrounding exact_celery_module_path and exact_code_path
so a command ending with workers before the whitespace and worker options is
recognized as an exact module path. Ensure exact_code_path accepts workers as
the final module component in commands such as celery -A app.workers worker
--loglevel=INFO, while preserving existing handling for deeper module paths.
Abiorh001
force-pushed
the
codex/ws-art-001-plan2-submission-bundle-reconciliation
branch
from
July 25, 2026 17:02
51f484d to
be62b74
Compare
abiorh-claw
self-requested a review
July 25, 2026 17:16
abiorh-claw
approved these changes
Jul 25, 2026
abiorh-claw
deleted the
codex/ws-art-001-plan2-submission-bundle-reconciliation
branch
July 25, 2026 17:19
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Workstream PR Trust Bundle
Chunk
WS-ART-001-PLAN2— Submission Bundle ReconciliationMerge intent:
.agent-loop/merge-intents/WS-ART-001-PLAN2.jsonGoal
Lock the planning contract that keeps one contributor ZIP identical across
prechecks, immutable storage, review, contribution, and delivery.
Signed Start Provenance
30100940860.bba4ba5f171a4438b072740707a5cf8bde49d9af.1dbc0d4e52c262844106ef9434c69139e38b33e9.be62b740e8476c11cca70b6dc66a8ad5dfd6cf92.What Changed
pre-submit checks, then admits it once through the existing immutable
ArtifactStorepath.normalized paths, hashes, sizes, entry types, and normalized executable intent.
ready -> consumed|stale; v0.1 adds no expiry, release, deletion, cleanup, orretention process.
again during atomic Submission/admission consumption.
PermissionIds; human authority never substitutes for service authority.
preserving TASK/REV ownership of Submission versions and review notes.
Alternatives Rejected
promotion copies.
opaque files unless a later locked Project Guide explicitly changes policy.
SubmissionVersion, recovery aggregate, or provider-write path.Scope Control
Planning memory, chunk contracts, canonical artifact/AUTH documentation and
templates, review evidence, merge intent, and deterministic agent-gate tests
only. No backend runtime, migration, provider, workflow, deployment, route
activation, or authorization availability changed.
Evidence
All nine required internal tracks pass on exact reviewed material: senior
engineering, QA/test, security/auth, product/ops, architecture, docs,
reuse/dedup, CI integrity, and test delta. Senior, QA, and CI integrity also
confirmed the final evidence-only HEAD contains no material drift.
Acceptance Criteria Proof
or authority to execute contributor content.
provider deletion, cleanup, or retention worker.
with no Submission, review, contribution, compensation, or reputation effect.
External Review
be62b740after integrating PR ci(backend): replace shards with exact-custody semantic lanes #198's CI/Ruffcustody repair and removing one obsolete ART contract read exposed by
F841..agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/reviews/WS-ART-001-PLAN2-external-review-response.md.Remaining Risks
operational evidence supports an increase.
implementation chunks.
Human Review Focus
remain REV-owned.
WS-ART-001-03Ais only a proposed successor and is not started here.Human Merge Ownership
Summary by CodeRabbit
New Features
Documentation
Chores