From 7b578c3949e8f6acfc4a35fbe3b723ae4bdd1bd3 Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Mon, 22 Jun 2026 11:36:12 +0100 Subject: [PATCH 01/37] Plan submission artifact policy foundation --- .agent-loop/LOOP_STATE.md | 31 +- .agent-loop/WORK_QUEUE.md | 11 +- .../CHUNK_MAP.md | 273 ++++++++++++++++++ .../DECISIONS.md | 22 ++ .../DISCOVERY.md | 91 ++++++ .../INTENT.md | 98 +++++++ .../PLAN.md | 111 +++++++ .../RISKS.md | 10 + .../STATUS.md | 34 +++ ...1-submission-artifact-policy-foundation.md | 136 +++++++++ 10 files changed, 797 insertions(+), 20 deletions(-) create mode 100644 .agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md create mode 100644 .agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md create mode 100644 .agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DISCOVERY.md create mode 100644 .agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md create mode 100644 .agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md create mode 100644 .agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/RISKS.md create mode 100644 .agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md create mode 100644 .agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md diff --git a/.agent-loop/LOOP_STATE.md b/.agent-loop/LOOP_STATE.md index 12d1a6a..9681ba0 100644 --- a/.agent-loop/LOOP_STATE.md +++ b/.agent-loop/LOOP_STATE.md @@ -2,14 +2,14 @@ ## Current State -- Active initiative: none -- Active chunk: none -- Branch: `main` -- Status: `WS-ENG-001-01` merged through PR #23 on 2026-06-20; memory updated; no active chunk -- Merge commit: `b9fe19b96109e9786e1d6d89488abfbe68a05d4a` -- Reviewed code SHA: `b22b940ee50956c9c7bfd0e681ffac727b6ff82c` -- Current gate: stopped after merge memory update -- Next chunk: inactive +- Active initiative: `WS-POL-001` - Submission Artifact Policy Foundation +- Active planning chunk: `WS-POL-001-01` - Submission Artifact Policy Foundation +- Branch: `codex/submission-artifact-policy-loop-plan` +- Status: intent, discovery, plan, chunk map, and first chunk contract drafted; implementation has not started +- Merge commit: none for this initiative +- Reviewed code SHA: pending +- Current gate: awaiting human review of plan and first chunk contract; backend implementation is not approved +- Next chunk: inactive until `WS-POL-001-01` is approved and completed ## Operating Rule @@ -19,14 +19,15 @@ Workstream engineering chunks move through: Intent -> Discovery -> Plan -> Chunk Map -> Chunk Contract -> Implementation -> Evidence -> Internal Review -> PR -> Human Checkpoint -> Memory Update -> Stop ``` -The current chunk is process infrastructure only. It does not change Workstream -product behavior, database schema, API behavior, or frontend behavior. +The current initiative is Workstream product planning for submission intake +policy. The current branch changes loop planning artifacts only; it does not +change Workstream product behavior, database schema, API behavior, or frontend +behavior. ## Last Review State -- Internal reviewer tracks complete. -- Valid findings addressed. -- Open sub-agent sessions: none. -- Internal review evidence: `.agent-loop/initiatives/WS-ENG-001-codex-zero-trust-loop-bootstrap/reviews/WS-ENG-001-01-internal-review-evidence.md` -- External review response: `.agent-loop/initiatives/WS-ENG-001-codex-zero-trust-loop-bootstrap/reviews/WS-ENG-001-01-external-review-response.md` +- Last completed initiative: `WS-ENG-001` Codex zero-trust engineering loop bootstrap. - PR #23 merged into `main` on 2026-06-20. +- PR #24 updated post-merge loop memory on `main`. +- PR #25 added Terminal Benchmark example material under `examples/`. +- Current planning branch has no internal review evidence yet. diff --git a/.agent-loop/WORK_QUEUE.md b/.agent-loop/WORK_QUEUE.md index c47234f..dd12cb2 100644 --- a/.agent-loop/WORK_QUEUE.md +++ b/.agent-loop/WORK_QUEUE.md @@ -1,22 +1,23 @@ # Work Queue -## Active +## Active Planning | Chunk | Title | Risk | Status | |---|---|---:|---| -| None | No active chunk | - | Inactive | +| `WS-POL-001-01` | Submission Artifact Policy Foundation | L1 | Draft contract; awaiting human approval before implementation | ## Completed | Chunk | Title | Risk | Status | |---|---|---:|---| | `WS-ENG-001-01` | Codex-native zero-trust loop bootstrap | L1 | Merged through PR #23 on 2026-06-20 | +| `EXAMPLE-TERMINAL-BENCHMARK` | Terminal Benchmark example drill | L3 | Merged through PR #25 on 2026-06-21 | ## Proposed Next -No next chunk is active. After this bootstrap has landed, the next Workstream product -chunk must be planned through the loop and approved by the user before code -starts. +`WS-POL-001-01` is the proposed next Workstream product implementation chunk. +Only planning is active. Backend implementation must not start until the user +approves the chunk contract. ## Blocked diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md new file mode 100644 index 0000000..a4bbc62 --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md @@ -0,0 +1,273 @@ +# Chunk Map: WS-POL-001 - Submission Artifact Policy Foundation + +## Rules + +- One chunk fits in one reviewable PR. +- No chunk mixes policy modeling, pre-submit runtime rewiring, and post-submit + checker splitting unless explicitly approved. +- Every implementation chunk must use Postgres-backed tests. +- Worker-facing outcomes remain simple; internal route names stay internal. + +## Chunks + +### WS-POL-001-01: Submission Artifact Policy Foundation + +Goal: + +Add first-class `SubmissionArtifactPolicy` backend records and schemas, define +Workstream default submission artifact rules in code, and validate that project +policy cannot weaken defaults. + +Risk: + +L1 + +Depends on: + +Approved intent, discovery, plan, and this chunk contract. + +Allowed files: + +```text +backend/alembic/versions/** +backend/app/modules/projects/** +backend/tests/test_projects.py +docs/spec_chunk_3_project_guide_foundation.md +docs/template_submission_artifact_policy.md +.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/** +``` + +Not allowed: + +```text +backend/app/modules/tasks/** +backend/app/modules/checkers/** +backend/app/modules/submissions/** +.github/workflows/** +frontend or demos +payment/reputation/blockchain code +``` + +Acceptance criteria: + +- Dedicated submission artifact policy model/table exists. +- Project policy is scoped to project id + guide version. +- Workstream default policy is represented in code. +- Effective policy merge rejects attempts to weaken defaults. +- Guide activation requires valid submission artifact policy. +- Existing `evidence_policy` transitional behavior is not silently broken. + +Required reviewers: + +senior engineering, QA/test, security/auth, product/ops, architecture, docs, +reuse/dedup, test delta. + +Human review focus: + +Policy field names, default rule set, migration strategy, and whether +`evidence_policy` remains a temporary compatibility alias. + +### WS-POL-001-02: Generated PreSubmitCheckerPolicy + +Goal: + +Generate pre-submit checker policy from effective submission artifact policy and +expose it only as server-owned policy context. + +Risk: + +L1 + +Depends on: + +`WS-POL-001-01` + +Allowed files: + +```text +backend/app/modules/projects/** +backend/app/modules/checkers/** +backend/tests/test_projects.py +backend/tests/test_checkers.py +docs/spec_chunk_8_submission_artifact_policy_checkers.md +``` + +Not allowed: + +```text +submission creation runtime rewiring +post-submit lifecycle changes +payment/reputation/blockchain code +``` + +Acceptance criteria: + +- Pre-submit checker policy is generated, not client-supplied. +- Generated policy contains Workstream defaults plus project additions. +- Generated policy names match registered pre-submit checker behavior. +- Workers cannot provide checker names, severities, versions, or outcomes. + +Required reviewers: + +senior engineering, QA/test, security/auth, product/ops, architecture, docs, +reuse/dedup, test delta. + +Human review focus: + +Generated policy persistence/derivation choice and exact naming. + +### WS-POL-001-03: Submission Creation Uses Effective Policy + +Goal: + +Move submission creation pre-submit gate from transitional task fields to the +effective submission artifact policy and generated pre-submit checker policy. + +Risk: + +L1 + +Depends on: + +`WS-POL-001-02` + +Allowed files: + +```text +backend/app/modules/tasks/** +backend/app/modules/checkers/** +backend/tests/test_submissions.py +backend/tests/test_checkers.py +backend/scripts/week2_api_e2e.py +docs/spec_chunk_5_submission_packet_foundation.md +``` + +Not allowed: + +```text +human review implementation +payment/reputation/blockchain code +frontend +``` + +Acceptance criteria: + +- Blocking pre-submit failure creates no submission row. +- Blocking pre-submit failure creates no submission version. +- Blocking pre-submit failure creates no submitted transition. +- Blocking pre-submit failure creates no durable checker run. +- Passing pre-submit creates a submission stamped with locked policy context. + +Required reviewers: + +senior engineering, QA/test, security/auth, product/ops, architecture, docs, +reuse/dedup, test delta. + +Human review focus: + +No-row/no-version/no-transition guarantee and worker-safe feedback. + +### WS-POL-001-04: PostSubmitCheckerPolicy Split + +Goal: + +Separate post-submit checker policy naming/provenance from generated pre-submit +policy and transitional `locked_checker_policy_version`. + +Risk: + +L1 + +Depends on: + +`WS-POL-001-03` + +Allowed files: + +```text +backend/alembic/versions/** +backend/app/modules/projects/** +backend/app/modules/tasks/** +backend/app/modules/checkers/** +backend/tests/** +docs/spec_chunk_8_submission_artifact_policy_checkers.md +docs/spec_chunk_9_pre_review_gate.md +``` + +Not allowed: + +```text +human review decisions +payment/reputation/blockchain code +frontend +``` + +Acceptance criteria: + +- Pre-submit policy provenance and post-submit policy provenance are distinct. +- Durable checker runs use locked post-submit checker policy. +- Pre-submit feedback does not create durable checker records. +- API responses do not expose internal-only routes to workers. + +Required reviewers: + +senior engineering, QA/test, security/auth, product/ops, architecture, docs, +reuse/dedup, test delta. + +Human review focus: + +Field naming and migration safety. + +### WS-POL-001-05: Revision Resubmission And Real API Drill + +Goal: + +Prove a worker can receive `needs_revision`, run pre-submit feedback again, and +submit a new version using the same policy-driven path. + +Risk: + +L1 + +Depends on: + +`WS-POL-001-04` + +Allowed files: + +```text +backend/app/modules/tasks/** +backend/app/modules/checkers/** +backend/tests/** +backend/scripts/week2_api_e2e.py +examples/terminal_benchmark/** +docs/spec_chunk_9_pre_review_gate.md +``` + +Not allowed: + +```text +human review decision implementation +payment/reputation/blockchain code +frontend +``` + +Acceptance criteria: + +- Worker pre-submit feedback is allowed for `in_progress` and `needs_revision` + where the worker owns the task. +- Replacement submission creates a new version. +- Older submission versions remain immutable. +- Internal checker-caused `needs_revision` remains distinguishable from future + human-review-caused `needs_revision`. +- Real API drill covers clean pass, blocking pre-submit, post-submit + `needs_revision`, and fixed resubmission. + +Required reviewers: + +senior engineering, QA/test, security/auth, product/ops, architecture, docs, +reuse/dedup, test delta. + +Human review focus: + +Fair worker experience during revision and audit clarity. diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md new file mode 100644 index 0000000..7a54b1d --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md @@ -0,0 +1,22 @@ +# Decisions: WS-POL-001 - Submission Artifact Policy Foundation + +## Accepted + +- `ProjectGuide` remains human-facing instruction. +- `SubmissionArtifactPolicy` is the machine-readable intake contract. +- Workstream default submission artifact rules are non-bypassable. +- `EffectiveSubmissionArtifactPolicy` is default plus project policy. +- `PreSubmitCheckerPolicy` is generated from effective policy. +- Pre-submit checks block before submission creation. +- Post-submit/internal checks remain separate from pre-submit checks. +- Worker-facing task outcomes remain simple; internal routes stay internal. +- Stored review decision values remain exactly `accept`, `needs_revision`, and + `reject`. Display wording must not create new persisted tokens. + +## Pending Human Decisions + +- Exact default Workstream submission artifact policy fields. +- Whether generated pre-submit policy is persisted or derived on demand. +- Exact names for locked submission artifact policy version/hash fields. +- Compatibility plan for `ProjectGuide.evidence_policy`. +- Compatibility plan for task `required_files` and `required_evidence`. diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DISCOVERY.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DISCOVERY.md new file mode 100644 index 0000000..5b5c48a --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DISCOVERY.md @@ -0,0 +1,91 @@ +# Discovery: WS-POL-001 - Submission Artifact Policy Foundation + +Discovery is read-only. No product implementation has started for this +initiative. + +## Current Behavior + +The architecture docs already lock the target model: + +```text +SubmissionArtifactPolicy +-> EffectiveSubmissionArtifactPolicy +-> generated PreSubmitCheckerPolicy +-> pre-submit checks before submission creation +-> post-submit/internal checks after submission lock +``` + +The backend is still transitional: + +- `ProjectGuide.evidence_policy` represents submission artifact requirements. +- `WorkstreamTask.required_files` and `required_evidence` drive checker behavior. +- `Submission.locked_checker_policy_version` is used broadly for post-submit + checker context. +- Pre-submit feedback uses `task.required_files` and `task.required_evidence`. +- Post-submit durable checks use registered checker names and locked checker + policy. + +## Relevant Files/Modules + +| Path | Purpose | Notes | +|---|---|---| +| `docs/decision_0011_submission_artifact_policy_drives_pre_submit.md` | Accepted ADR for this initiative | Source of truth for policy-driven intake. | +| `docs/spec_chunk_5_submission_packet_foundation.md` | Submission packet target contract | Already says current code is transitional. | +| `docs/spec_chunk_8_submission_artifact_policy_checkers.md` | Pre-submit versus durable checker boundary | Names default pre-submit checks and routing. | +| `docs/spec_chunk_9_pre_review_gate.md` | Post-submit gate | Keeps internal checker routing separate from human review. | +| `backend/app/modules/projects/models.py` | Project guide and policies | `ProjectGuide.evidence_policy` is transitional. | +| `backend/app/modules/projects/schemas.py` | Project guide API schemas | Exposes `evidence_policy` today. | +| `backend/app/modules/projects/service.py` | Guide activation and policy validation | Activation currently checks `evidence_policy` and checker policy. | +| `backend/app/modules/tasks/models.py` | Task/submission models | Task stores required files/evidence; submission stores broad checker policy version. | +| `backend/app/modules/tasks/service.py` | Task lifecycle and locked context | Stamps locked guide/policy context onto tasks/submissions. | +| `backend/app/modules/checkers/runner.py` | Checker implementations | Pre-submit and durable checks share helper logic today. | +| `backend/app/modules/checkers/service.py` | Pre-submit and durable checker orchestration | Needs to consume generated pre-submit policy later. | + +## Current Tests + +| Test path | What it covers | Gaps | +|---|---|---| +| `backend/tests/test_projects.py` | Project guide activation and policy context | Does not test dedicated `SubmissionArtifactPolicy`. | +| `backend/tests/test_tasks.py` | Task lifecycle and assignment | Task required files/evidence remain transitional. | +| `backend/tests/test_submissions.py` | Submission packet creation/versioning | Does not yet prove effective policy provenance. | +| `backend/tests/test_checkers.py` | Pre-submit feedback, durable runs, routing | Uses task fields rather than generated pre-submit policy. | +| `backend/scripts/week2_api_e2e.py` | Real API checker/pre-review flow | Needs a future variant using dedicated policy records. | + +## Dependencies/Integrations + +- FastAPI async endpoints. +- SQLAlchemy 2.x async ORM. +- Alembic migrations. +- Pydantic schemas. +- Postgres as record database. +- Existing Flow token verification boundary. +- Existing checker runner registry. + +## Risks Discovered + +| Risk | Why it matters | Suggested handling | +|---|---|---| +| Policy/source drift | Guide prose, task fields, and checker policy can disagree. | Introduce policy objects first, then migrate runtime reads in later chunks. | +| Weakening defaults | Project policy could accidentally remove Workstream safety rules. | Implement non-bypassable default merge validation. | +| Big-bang rewrite | Changing project, task, submission, and checker runtime together is risky. | Split into reviewable chunks. | +| Version/hash ambiguity | Pre-submit policy is generated, so versioning needs careful naming. | Human review field names before migration. | +| Worker-facing confusion | Internal routes can leak if naming is sloppy. | Keep worker-facing state `needs_revision`; keep internal route fields internal. | + +## Unknowns/Questions For Human + +| Question | Why it matters | Needed before chunk? | +|---|---|---| +| Exact default artifact rules | Defines non-bypassable Workstream intake behavior. | Yes, before implementation chunk 1 completes. | +| Whether `evidence_policy` stays as backward-compatible alias | Affects API compatibility and migration scope. | Yes, before migration chunk. | +| Exact policy version/hash field names | Prevents future schema drift. | Yes, before schema migration. | +| Whether generated `PreSubmitCheckerPolicy` is persisted or derived on read | Affects data model and audit proof. | Yes, before chunk 2. | + +## Existing Conventions To Preserve + +- Async-first FastAPI and SQLAlchemy. +- Router, service, repository, schema separation. +- No Workstream-owned login/session/auth. +- Postgres-backed integration tests for lifecycle behavior. +- Review decision stored values only `accept`, `needs_revision`, `reject`. +- Internal checker routes are not review decisions. +- CodeRabbit and CI supplement, but do not replace, internal reviewer tracks. diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md new file mode 100644 index 0000000..fd05085 --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md @@ -0,0 +1,98 @@ +# INTENT: WS-POL-001 - Submission Artifact Policy Foundation + +## Problem Being Solved + +Workstream currently understands the product direction for submission intake, but +the backend still carries transitional fields such as `evidence_policy`, +`required_files`, `required_evidence`, and broad checker-policy version locking. + +That is not strong enough for the system we are building. A project guide is +human-facing instruction. It can explain expectations, examples, rubric, and +quality bar, but it must not be the only source of truth for what a worker is +allowed to submit. + +Submission intake needs a deterministic machine contract. + +## Human-Level Goal + +Make submission intake policy-driven: + +```text +ProjectGuide = human-facing instructions +SubmissionArtifactPolicy = machine-readable intake contract + +WorkstreamDefaultSubmissionArtifactPolicy ++ ProjectSubmissionArtifactPolicy += EffectiveSubmissionArtifactPolicy + +EffectiveSubmissionArtifactPolicy +-> generated PreSubmitCheckerPolicy +``` + +Workers submit draft packet fields. Workstream decides required artifacts, +evidence, hashes, storage reference rules, forbidden artifacts, and blocking +pre-submit feedback from the effective policy. + +## Why Now + +Week 1 and Week 2 established the core backend loop: + +- project and guide foundation +- task queue and assignment +- submission packet foundation +- checker contracts and runner registry +- pre-review gate +- checker trial and real API drills + +The next correctness gap is policy ownership. If we keep relying on task fields +and guide prose, different projects will drift and the pre-submit/post-submit +boundary will become confusing. + +## Success State + +After this initiative: + +- `SubmissionArtifactPolicy` is a first-class backend object. +- Workstream default submission artifact rules are defined in code. +- Project submission artifact policy cannot weaken Workstream defaults. +- Effective submission artifact policy is computed deterministically. +- Generated pre-submit checker policy is derived from effective policy. +- Submission creation uses the generated pre-submit policy before a submission + row is created. +- Post-submit/internal checker policy remains separate. +- Revision resubmission can run pre-submit feedback again without creating + confusing internal worker states. + +## Non-Goals + +- No human review decision implementation. +- No payment, contribution, reputation, blockchain, x402, ERC-8004, or ERC-8183 + work. +- No frontend implementation. +- No object-storage implementation beyond preserving the storage abstraction + boundary. +- No durable external checker worker infrastructure. +- No direct use of Terminal Benchmark example code in product runtime. + +## Business/Product/Engineering Context + +Workstream must be fair to workers and reliable for project managers. If a +submission requirement matters, it belongs in the approved guide and policy +context, not in Slack messages, hidden docs, or agent memory. + +The worker should get deterministic pre-submit feedback before a submission is +created. Internal checker routing can be richer, but worker-facing outcomes stay +simple. Stored review decision values remain exactly `accept`, +`needs_revision`, and `reject`; display labels may render those as accepted, +needs revision, and rejected where appropriate. + +## Human Judgment Required + +- Approve the chunk sequence before implementation. +- Approve the exact Workstream default submission artifact rules. +- Approve naming for new persisted fields and policy version/hash fields. +- Approve any migration strategy that changes existing transitional fields. + +## Initial Risk Class + +L1 - policy engine, task lifecycle, audit, and submission data boundaries. diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md new file mode 100644 index 0000000..e0a76d9 --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md @@ -0,0 +1,111 @@ +# Plan: WS-POL-001 - Submission Artifact Policy Foundation + +## Proposed Approach + +Implement policy-driven submission intake in narrow slices. + +First, add the policy foundation without changing the full submission runtime. +Then derive generated pre-submit policy. Then move submission creation to the +effective policy. Then split post-submit checker policy naming and provenance. +Finally, verify revision resubmission and real API flows. + +## Design Chosen + +The product model is: + +```text +ProjectGuide + human-facing instructions + +ProjectSubmissionArtifactPolicy + project-admin-approved machine-readable intake rules + +WorkstreamDefaultSubmissionArtifactPolicy + platform-owned, non-bypassable safety rules + +EffectiveSubmissionArtifactPolicy + deterministic merge of default + project policy + +PreSubmitCheckerPolicy + generated checker rules for draft packet intake + +PostSubmitCheckerPolicy + durable checker rules for locked submission review readiness +``` + +Pre-submit checks run before submission creation and do not create durable +checker records. Post-submit/internal checks run after submission lock and do +create durable checker records. + +## Alternatives Considered + +### Keep using guide prose and task fields + +Rejected because it leaves too much room for project drift and unfair worker +feedback. + +### Use project guide `evidence_policy` as the long-term object + +Rejected because the name is too narrow. The policy governs artifacts, hashes, +storage references, packaging, forbidden files, and attestation, not only +evidence. + +### Let project admins write checker names manually for pre-submit + +Rejected because pre-submit should be generated from the effective submission +artifact policy. Workers and project admins should not choose blocking checker +internals directly for intake. + +### Combine pre-submit and post-submit checker policy + +Rejected because pre-submit answers whether a packet can be submitted at all, +while post-submit answers whether a locked submission can move to human review. + +## Boundaries Preserved + +- Auth/session: still only verifies external Flow authentication tokens. +- Permission/policy: project managers/admins own project policy setup; workers + do not provide policy versions or checker names. +- Payment/execution: no payment or contribution records in this initiative. +- Persistence/data: schema changes land through Alembic and async SQLAlchemy. +- Presentation/API: backend-first; no frontend implementation. +- CI/deployment: no workflow weakening. + +## Rollout/Migration Strategy + +1. Add dedicated policy model/API while keeping transitional fields readable. +2. Compute effective policy in service code and validate defaults cannot weaken. +3. Generate pre-submit checker policy from effective policy. +4. Migrate submission creation to effective policy. +5. Split post-submit checker policy naming/provenance. +6. Retire or alias transitional `evidence_policy`, `required_files`, and + `required_evidence` usage after tests prove the new path. + +## Verification Strategy + +- Unit-level policy merge tests for default + project policy. +- Postgres-backed API tests for project policy creation and guide activation. +- Submission API tests proving blocking pre-submit failure creates no submission + row, version, task transition, durable checker run, or submission-created audit. +- Real API drill proving clean pass and `needs_revision` resubmission. +- Stale wording and Markdown link scans. + +## Review Strategy + +Required reviewers: + +- senior engineering: data model, lifecycle, service boundaries +- QA/test: Postgres-backed proof and regression coverage +- security/auth: storage refs, hash rules, unsafe path/URL rejection +- product/ops: worker/project-manager semantics and fairness +- architecture: policy/source-of-truth boundaries +- docs: naming and guide/policy wording +- reuse/dedup: avoid duplicate checker/policy logic +- test delta: ensure tests cover new behavior + +CI integrity is required only for chunks that touch workflows or test tooling. + +## Sequencing + +Start with policy foundation. Do not start submission runtime rewiring until the +policy object, defaults, and merge rules are accepted. diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/RISKS.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/RISKS.md new file mode 100644 index 0000000..8b94a1e --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/RISKS.md @@ -0,0 +1,10 @@ +# Risks: WS-POL-001 - Submission Artifact Policy Foundation + +| Risk | Impact | Mitigation | +|---|---|---| +| Big-bang lifecycle rewrite | High | Split policy, generation, submission runtime, post-submit split, and revision proof into separate chunks. | +| Default policy can be weakened | High | Validate effective policy rejects any project policy that removes or downgrades defaults. | +| Naming drift | High | Human review field names before migrations. | +| Worker-facing internal route leakage | Medium | Keep `task_setup_blocked` and `checker_retry` internal; expose `needs_revision` only when worker action is needed. | +| Backward compatibility drift | Medium | Keep transitional fields explicit until replacement is proven. | +| Insufficient real API proof | High | Require Postgres-backed API tests and real API drill before closing the initiative. | diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md new file mode 100644 index 0000000..c1ee0e6 --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md @@ -0,0 +1,34 @@ +# Status: WS-POL-001 - Submission Artifact Policy Foundation + +## Current Status + +Planning + +## Active Chunk + +`WS-POL-001-01` is drafted for human review. Implementation has not started. + +## Chunk Status + +| Chunk | Status | Branch | PR | Notes | +|---|---|---|---:|---| +| `WS-POL-001-01` | Draft contract | `codex/submission-artifact-policy-loop-plan` | - | Awaiting human approval before implementation. | +| `WS-POL-001-02` | Planned | - | - | Starts after policy foundation lands. | +| `WS-POL-001-03` | Planned | - | - | Moves submission creation to effective policy. | +| `WS-POL-001-04` | Planned | - | - | Splits post-submit checker policy provenance. | +| `WS-POL-001-05` | Planned | - | - | Proves revision resubmission and real API drill. | + +## Blockers + +| Blocker | Owner | Next action | +|---|---|---| +| Human approval of chunk sequence and first contract | User | Review this planning branch. | +| Exact default submission artifact policy fields | User + Codex | Confirm before implementation completes. | + +## Follow-Ups + +| Item | Source | Priority | +|---|---|---| +| Migrate `evidence_policy` wording to `SubmissionArtifactPolicy` | Discovery | High | +| Split pre-submit and post-submit policy provenance fields | Discovery | High | +| Add revision resubmission pre-submit proof | Discovery | High | diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md new file mode 100644 index 0000000..1c000ff --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md @@ -0,0 +1,136 @@ +# Chunk Contract: WS-POL-001-01 - Submission Artifact Policy Foundation + +## Parent Initiative + +WS-POL-001 - Submission Artifact Policy Foundation + +## Goal + +Add first-class backend support for `SubmissionArtifactPolicy` without rewiring +submission creation or durable checker execution yet. + +## Why This Chunk Exists + +The code still uses transitional `evidence_policy`, `required_files`, and +`required_evidence` fields. Before pre-submit checks can be generated from an +effective policy, Workstream needs a real policy object and non-bypassable +default policy validation. + +## Approved Plan Reference + +- INTENT: `.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md` +- PLAN: `.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md` +- CHUNK_MAP: `.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md` + +## Risk Class + +L1 + +## SLA + +P1 + +## Allowed Files + +```text +backend/alembic/versions/** +backend/app/modules/projects/** +backend/tests/test_projects.py +docs/spec_chunk_3_project_guide_foundation.md +docs/template_submission_artifact_policy.md +.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/** +``` + +## Not Allowed + +```text +backend/app/modules/tasks/** +backend/app/modules/checkers/** +backend/app/modules/submissions/** +.github/workflows/** +demos/** +examples/** +frontend/** +payment/reputation/blockchain code +object-storage implementation +human review implementation +``` + +## Implementation Boundaries + +- Routers only translate HTTP requests/responses and map domain errors. +- Services own policy merge rules, Workstream default validation, guide + activation checks, and permission-aware orchestration. +- Repositories only persist and query policy records. +- Schemas only define API input/output contracts and validation shape. + +## Acceptance Criteria + +- [ ] Dedicated `SubmissionArtifactPolicy` model/table exists. +- [ ] Policy rows are scoped by `project_id` and `guide_version`. +- [ ] Policy rows have a composite foreign key to `project_guides(project_id, version)`. +- [ ] Pydantic input/output schemas exist for project submission artifact policy. +- [ ] Project service can create/update the policy with a draft guide. +- [ ] Guide activation requires valid submission artifact policy. +- [ ] Workstream default submission artifact policy is represented in code. +- [ ] Workstream default policy requires `sha256:<64 lowercase hex>` artifact hashes where production hashes are required. +- [ ] Workstream default policy rejects raw signed URLs, query strings, local filesystem paths, credential-bearing references, and token-bearing storage references before persistence. +- [ ] Workstream default policy blocks default-forbidden secret/token artifacts even when a project policy lists them as required. +- [ ] Effective policy merge rejects project policy that weakens defaults. +- [ ] Existing `evidence_policy` transitional behavior is not silently broken. +- [ ] Postgres-backed tests cover create/update/activation/default-weakening cases. + +## Verification Commands + +```bash +cd backend && .venv/bin/python -m ruff check app tests +cd backend && WORKSTREAM_TEST_DATABASE_URL=postgresql+asyncpg://workstream:workstream@localhost:5433/workstream_test .venv/bin/python -m pytest tests/test_projects.py +python3 scripts/check_markdown_links.py +python3 scripts/check_stale_workstream_wording.py +python3 scripts/check_internal_review_evidence.py +python3 scripts/workstream_agent_gate.py --base origin/main --head HEAD --format json +git diff --check +``` + +## Required Reviewers + +Every listed reviewer must end with one exact result value: + +- `PASS` +- `PASS AFTER FIXES` +- `PASS WITH LOW RISKS` +- `N/A - with approved reason` + +Baseline: + +- [ ] senior engineering +- [ ] QA/test +- [ ] security/auth +- [ ] product/ops + +Conditional: + +- [ ] architecture +- [ ] docs +- [ ] reuse/dedup +- [ ] test delta +- [ ] CI integrity: `N/A - with approved reason` unless workflows or test tooling change + +## Human Review Focus + +- Are the policy field names precise enough? +- Are Workstream default rules complete enough for v0.1? +- Should `evidence_policy` remain a compatibility alias during migration? +- Should generated pre-submit policy be persisted in chunk 2 or derived on read? + +## Stop Conditions + +Stop and escalate if: + +- implementation needs to touch task/submission/checker runtime in this chunk +- policy version/hash naming is unclear +- default artifact rules need product decision +- migration requires destructive data changes +- CI/test weakening is required to pass +- same blocker remains after 2 repair attempts +- secrets or production data are needed From 1c9050838e79068c32d06200a326734b4bf923f2 Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Mon, 22 Jun 2026 11:49:01 +0100 Subject: [PATCH 02/37] Record submission policy planning review evidence --- .../WS-POL-001-01-internal-review-evidence.md | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 .agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md new file mode 100644 index 0000000..f425d1c --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md @@ -0,0 +1,55 @@ +# Internal Review Evidence: WS-POL-001-01 + +## Chunk + +WS-POL-001-01 + +open sub-agent sessions: none + +valid findings addressed: yes + +## Reviewed Revision + +Reviewed code SHA: 7b578c3949e8f6acfc4a35fbe3b723ae4bdd1bd3 + +Reviewed at: 2026-06-22T10:32:50Z + +Reviewer run IDs: 019eee8c-5c09-7603-bae4-2b2bc60f8dd3, 019eee8e-55e6-75b0-92dd-f5c44f80ad7b, 019eee91-1ff6-7552-8ce4-06a48f0ffac9, 019eee94-c99d-72a3-80f5-9b90ddd9c9d3, 019eee9a-b0eb-7020-880f-be0bfa1968f6, 019eeeca-bc88-7ce0-baec-6be4a8ca1f47, 019eeecb-f151-7433-a472-f3bcdaafda8f + +After reviewed SHA `7b578c3949e8f6acfc4a35fbe3b723ae4bdd1bd3`, only this internal review evidence file changed. + +## Reviewer Results + +| Reviewer | Result | Blocking findings | Notes | +|---|---:|---|---| +| senior engineering | PASS WITH LOW RISKS | None remaining | Planning artifacts are coherent, narrow, and do not start backend implementation. Active planning wording was clarified. | +| qa/test | PASS AFTER FIXES | None remaining | Unsafe unqualified pytest command was removed; remaining verification command uses `WORKSTREAM_TEST_DATABASE_URL` with `workstream_test`. | +| security/auth | PASS WITH LOW RISKS | None remaining | Flow auth boundary, storage-reference safety, non-bypassable defaults, and no blockchain/payment expansion are preserved. Default hash/storage/secret rules were added to the chunk contract. | +| product/ops | PASS WITH LOW RISKS | None remaining | Plan matches intent: ProjectGuide is human-facing, SubmissionArtifactPolicy is machine-readable, defaults are non-bypassable, and worker-facing outcomes stay simple. Stored token wording was clarified. | +| architecture | PASS WITH LOW RISKS | None remaining | Chunk sequencing preserves policy foundation, generated pre-submit policy, submission creation rewiring, and post-submit provenance split. Router/service/repository/schema boundaries were added to the contract. | +| docs | PASS WITH LOW RISKS | None remaining | Markdown links, stale wording, and naming passed after normalizing `PreSubmitCheckerPolicy` as the canonical name. | + +## Valid Findings Addressed + +- QA/test found an unsafe plain `pytest tests/test_projects.py` command that could target the non-test local database. The contract now uses only `WORKSTREAM_TEST_DATABASE_URL=.../workstream_test`. +- Security/auth requested explicit default policy acceptance criteria for hash rules, storage reference rejection, and default-forbidden secret/token artifacts. Those criteria were added. +- Senior engineering found `WORK_QUEUE.md` could confuse active planning with approved implementation. Loop wording now says active planning and explicitly blocks backend implementation until user approval. +- Product/ops found display wording could drift from stored review decision values. Intent and decisions now state stored values remain exactly `accept`, `needs_revision`, and `reject`. +- Architecture requested explicit responsibility boundaries. The chunk contract now states routers translate HTTP, services own policy/default validation, repositories persist/query, and schemas define IO contracts. +- Docs found `GeneratedPreSubmitCheckerPolicy` could look like a canonical token. The plan now uses canonical `PreSubmitCheckerPolicy` and describes it as generated. + +## Commands Run + +```bash +python3 scripts/check_loop_memory_state.py +python3 scripts/check_markdown_links.py +python3 scripts/check_stale_workstream_wording.py +python3 scripts/workstream_agent_gate.py --base origin/main --head HEAD --format json +git diff --check +``` + +## Remaining Risks + +- `WS-POL-001-01` is not approved for backend implementation yet. +- Exact Workstream default submission artifact policy fields remain a human decision before implementation can close. +- Generated `PreSubmitCheckerPolicy` persistence versus derived-on-read remains a human decision for chunk 2. From 709d6915cf5971efcf18f12e7ee55a881370b5e4 Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Mon, 22 Jun 2026 13:35:51 +0100 Subject: [PATCH 03/37] Address submission policy planning review nit --- .../CHUNK_MAP.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md index a4bbc62..abc33f5 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md @@ -152,10 +152,8 @@ frontend Acceptance criteria: -- Blocking pre-submit failure creates no submission row. -- Blocking pre-submit failure creates no submission version. -- Blocking pre-submit failure creates no submitted transition. -- Blocking pre-submit failure creates no durable checker run. +- Blocking pre-submit failure creates no submission row, submission version, + submitted transition, or durable checker run. - Passing pre-submit creates a submission stamped with locked policy context. Required reviewers: From fc48d235e521812a0a2dd34ed00b3ae47957cfef Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Mon, 22 Jun 2026 13:40:09 +0100 Subject: [PATCH 04/37] Record submission policy external review response --- .../WS-POL-001-01-external-review-response.md | 51 +++++++++++++++++++ .../WS-POL-001-01-internal-review-evidence.md | 14 +++-- 2 files changed, 61 insertions(+), 4 deletions(-) create mode 100644 .agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md new file mode 100644 index 0000000..3c6ee9a --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md @@ -0,0 +1,51 @@ +# External Review Response: WS-POL-001-01 + +## PR + +https://github.com/Flow-Research/workstream/pull/26 + +## Chunk + +`WS-POL-001-01` + +## Source + +CodeRabbit and GitHub checks. + +## Summary + +External review feedback was handled separately from internal sub-agent evidence. +CodeRabbit reported one readability nitpick in the chunk map. The finding was +valid, in scope, and fixed without changing the product contract. + +## External Findings + +| Source | Finding | Severity | Status | Response | +|---|---|---:|---:|---| +| CodeRabbit | `WS-POL-001-03` acceptance criteria repeated "Blocking pre-submit failure creates no..." across consecutive lines. | Low | Fixed | Consolidated the four no-side-effect guarantees into one sentence while preserving every distinct requirement. | +| GitHub checks | Agent Gates, Backend, Week 1 API Demo UI, and CodeRabbit status must pass. | High | Passing before fix; rerun pending after final push | Local gates passed before this evidence update. GitHub checks will rerun after push. | + +## Fix Plan + +- Keep the external CodeRabbit response in this `*-external-review-response.md` + artifact. +- Keep internal sub-agent review evidence in + `WS-POL-001-01-internal-review-evidence.md`. +- Apply only the wording consolidation requested by CodeRabbit. +- Re-run affected internal reviewer tracks before pushing. + +## Out-of-Scope Items To Defer + +None. + +## Evidence After Fixes + +```bash +gh pr view 26 --json number,title,state,isDraft,url,reviewDecision,reviews,comments,statusCheckRollup +python3 scripts/check_internal_review_evidence.py +python3 scripts/check_loop_memory_state.py +python3 scripts/workstream_agent_gate.py --base origin/main --head HEAD --format json +python3 scripts/check_markdown_links.py +python3 scripts/check_stale_workstream_wording.py +git diff --check +``` diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md index f425d1c..9aaa13e 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md @@ -10,13 +10,13 @@ valid findings addressed: yes ## Reviewed Revision -Reviewed code SHA: 7b578c3949e8f6acfc4a35fbe3b723ae4bdd1bd3 +Reviewed code SHA: 709d6915cf5971efcf18f12e7ee55a881370b5e4 -Reviewed at: 2026-06-22T10:32:50Z +Reviewed at: 2026-06-22T12:36:49Z -Reviewer run IDs: 019eee8c-5c09-7603-bae4-2b2bc60f8dd3, 019eee8e-55e6-75b0-92dd-f5c44f80ad7b, 019eee91-1ff6-7552-8ce4-06a48f0ffac9, 019eee94-c99d-72a3-80f5-9b90ddd9c9d3, 019eee9a-b0eb-7020-880f-be0bfa1968f6, 019eeeca-bc88-7ce0-baec-6be4a8ca1f47, 019eeecb-f151-7433-a472-f3bcdaafda8f +Reviewer run IDs: 019eee8c-5c09-7603-bae4-2b2bc60f8dd3, 019eee8e-55e6-75b0-92dd-f5c44f80ad7b, 019eee91-1ff6-7552-8ce4-06a48f0ffac9, 019eee94-c99d-72a3-80f5-9b90ddd9c9d3, 019eee9a-b0eb-7020-880f-be0bfa1968f6, 019eeeca-bc88-7ce0-baec-6be4a8ca1f47, 019eeecb-f151-7433-a472-f3bcdaafda8f, 019eef36-6dc2-7e81-9663-8d3a6aec2278, 019eef37-a7cb-7302-84ac-06531bf8b0fb, 019eef3a-3b6c-7a92-a094-15a2f24615ff, 019eef3c-bfbb-7ed1-acb2-112c6d34b455 -After reviewed SHA `7b578c3949e8f6acfc4a35fbe3b723ae4bdd1bd3`, only this internal review evidence file changed. +After reviewed SHA `709d6915cf5971efcf18f12e7ee55a881370b5e4`, only review evidence artifacts changed. ## Reviewer Results @@ -28,6 +28,10 @@ After reviewed SHA `7b578c3949e8f6acfc4a35fbe3b723ae4bdd1bd3`, only this interna | product/ops | PASS WITH LOW RISKS | None remaining | Plan matches intent: ProjectGuide is human-facing, SubmissionArtifactPolicy is machine-readable, defaults are non-bypassable, and worker-facing outcomes stay simple. Stored token wording was clarified. | | architecture | PASS WITH LOW RISKS | None remaining | Chunk sequencing preserves policy foundation, generated pre-submit policy, submission creation rewiring, and post-submit provenance split. Router/service/repository/schema boundaries were added to the contract. | | docs | PASS WITH LOW RISKS | None remaining | Markdown links, stale wording, and naming passed after normalizing `PreSubmitCheckerPolicy` as the canonical name. | +| senior engineering | PASS | None | Re-reviewed CodeRabbit wording consolidation; meaning was not weakened. | +| qa/test | PASS | None | Re-reviewed consolidated criteria; no-row, no-version, no-transition, and no-durable-checker-run remain testable. | +| product/ops | PASS | None | Re-reviewed consolidated criteria; worker-facing semantics remain simple and precise. | +| docs | PASS WITH LOW RISKS | None | Re-reviewed consolidated criteria; no adjacent docs required. | ## Valid Findings Addressed @@ -37,6 +41,7 @@ After reviewed SHA `7b578c3949e8f6acfc4a35fbe3b723ae4bdd1bd3`, only this interna - Product/ops found display wording could drift from stored review decision values. Intent and decisions now state stored values remain exactly `accept`, `needs_revision`, and `reject`. - Architecture requested explicit responsibility boundaries. The chunk contract now states routers translate HTTP, services own policy/default validation, repositories persist/query, and schemas define IO contracts. - Docs found `GeneratedPreSubmitCheckerPolicy` could look like a canonical token. The plan now uses canonical `PreSubmitCheckerPolicy` and describes it as generated. +- CodeRabbit found repetitive wording in `WS-POL-001-03` acceptance criteria. The repeated lines were consolidated without changing the no-row, no-version, no-transition, and no-durable-checker-run requirements. ## Commands Run @@ -46,6 +51,7 @@ python3 scripts/check_markdown_links.py python3 scripts/check_stale_workstream_wording.py python3 scripts/workstream_agent_gate.py --base origin/main --head HEAD --format json git diff --check +gh pr view 26 --json number,title,state,isDraft,url,reviewDecision,reviews,comments,statusCheckRollup ``` ## Remaining Risks From ef3bf0c3fbd393886f7a2b643da2c39ea4880c81 Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Mon, 22 Jun 2026 14:20:30 +0100 Subject: [PATCH 05/37] Update submission policy external review status --- .../WS-POL-001-01-external-review-response.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md index 3c6ee9a..18d2dc5 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md @@ -23,7 +23,8 @@ valid, in scope, and fixed without changing the product contract. | Source | Finding | Severity | Status | Response | |---|---|---:|---:|---| | CodeRabbit | `WS-POL-001-03` acceptance criteria repeated "Blocking pre-submit failure creates no..." across consecutive lines. | Low | Fixed | Consolidated the four no-side-effect guarantees into one sentence while preserving every distinct requirement. | -| GitHub checks | Agent Gates, Backend, Week 1 API Demo UI, and CodeRabbit status must pass. | High | Passing before fix; rerun pending after final push | Local gates passed before this evidence update. GitHub checks will rerun after push. | +| GitHub checks | Agent Gates, Backend, Week 1 API Demo UI, and CodeRabbit status must pass. | High | Passed | All GitHub checks passed after the final push. | +| CodeRabbit manual trigger | Manual `@coderabbitai review` was requested after the rate-limit window. | Informational | Complete | CodeRabbit replied "Review finished" and noted incremental review does not re-review already reviewed commits unless automatic reviews are paused. No new actionable findings were posted. | ## Fix Plan @@ -49,3 +50,13 @@ python3 scripts/check_markdown_links.py python3 scripts/check_stale_workstream_wording.py git diff --check ``` + +Final GitHub state after push: + +```text +agent-gates: pass +backend test: pass +week1 demo UI: pass +CodeRabbit status: pass +CodeRabbit manual trigger: review finished, no new actionable findings posted +``` From 0b94c7df1fb1fa2a9df926ddfd5cb81404bb448c Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Mon, 22 Jun 2026 20:16:02 +0100 Subject: [PATCH 06/37] Align submission artifact policy ownership docs --- .../CHUNK_MAP.md | 15 +++++-- .../DECISIONS.md | 9 ++++ .../DISCOVERY.md | 8 ++++ .../INTENT.md | 29 ++++++++++-- .../PLAN.md | 44 ++++++++++++++----- .../RISKS.md | 1 + ...1-submission-artifact-policy-foundation.md | 18 +++++++- docs/architecture_checker_framework.md | 12 ++++- docs/architecture_data_model.md | 25 ++++++++++- docs/architecture_lockdown.md | 10 ++++- docs/current_system_data_flow.html | 8 ++-- ...ion_0003_project_guides_are_first_class.md | 2 +- ...ssion_artifact_policy_drives_pre_submit.md | 22 +++++++++- docs/glossary.md | 12 ++++- docs/operations_project_operating_manual.md | 7 +-- .../operations_workspace_packet_convention.md | 5 ++- docs/product_first_user_flows.md | 23 +++++----- ...ec_chunk_5_submission_packet_foundation.md | 2 +- docs/spec_chunk_6_checker_contract_records.md | 13 ++++-- docs/spec_chunk_7_checker_runner_registry.md | 8 +++- ...k_8_submission_artifact_policy_checkers.md | 8 +++- docs/spec_week2_checker_framework.md | 11 +++-- docs/template_checker_policy.md | 5 ++- docs/template_project_guide.md | 5 +++ docs/template_submission_artifact_policy.md | 39 +++++++++++++++- docs/template_submission_packet.md | 6 ++- 26 files changed, 286 insertions(+), 61 deletions(-) diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md index abc33f5..606d6d0 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md @@ -7,6 +7,9 @@ checker splitting unless explicitly approved. - Every implementation chunk must use Postgres-backed tests. - Worker-facing outcomes remain simple; internal route names stay internal. +- Project owners provide setup material in plain language; Workstream derives + machine-readable submission artifact policy and actors with the `admin` or + `project_manager` role approve it. ## Chunks @@ -52,6 +55,8 @@ Acceptance criteria: - Dedicated submission artifact policy model/table exists. - Project policy is scoped to project id + guide version. +- Project policy records are Workstream-derived and approved by `admin` or + `project_manager`, not direct project owner-authored schema. - Workstream default policy is represented in code. - Effective policy merge rejects attempts to weaken defaults. - Guide activation requires valid submission artifact policy. @@ -64,8 +69,9 @@ reuse/dedup, test delta. Human review focus: -Policy field names, default rule set, migration strategy, and whether -`evidence_policy` remains a temporary compatibility alias. +Policy ownership, project-owner intake checklist, policy field names, default +rule set, migration strategy, and whether `evidence_policy` remains a temporary +compatibility alias. ### WS-POL-001-02: Generated PreSubmitCheckerPolicy @@ -154,6 +160,8 @@ Acceptance criteria: - Blocking pre-submit failure creates no submission row, submission version, submitted transition, or durable checker run. +- Blocking pre-submit failure returns `pre_submission_checker_failed` with + structured pass/fail/warning details, not review decision values. - Passing pre-submit creates a submission stamped with locked policy context. Required reviewers: @@ -163,7 +171,8 @@ reuse/dedup, test delta. Human review focus: -No-row/no-version/no-transition guarantee and worker-safe feedback. +No-row/no-version/no-transition guarantee and `pre_submission_checker_failed` +feedback shape. ### WS-POL-001-04: PostSubmitCheckerPolicy Split diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md index 7a54b1d..325f7c9 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md @@ -4,10 +4,18 @@ - `ProjectGuide` remains human-facing instruction. - `SubmissionArtifactPolicy` is the machine-readable intake contract. +- Project owners provide project setup material in plain language; + they do not author `SubmissionArtifactPolicy` directly. +- Workstream derives `ProjectSubmissionArtifactPolicy` from project material, + with internal agent assistance allowed, then requires approval by `admin` or + `project_manager` before guide activation. - Workstream default submission artifact rules are non-bypassable. - `EffectiveSubmissionArtifactPolicy` is default plus project policy. - `PreSubmitCheckerPolicy` is generated from effective policy. - Pre-submit checks block before submission creation. +- Blocking pre-submit feedback is `pre_submission_checker_failed` with + structured pass/fail/warning details; it is not `accept`, `needs_revision`, + or `reject`. - Post-submit/internal checks remain separate from pre-submit checks. - Worker-facing task outcomes remain simple; internal routes stay internal. - Stored review decision values remain exactly `accept`, `needs_revision`, and @@ -16,6 +24,7 @@ ## Pending Human Decisions - Exact default Workstream submission artifact policy fields. +- Exact v0.1 project-owner intake checklist for deriving project policy. - Whether generated pre-submit policy is persisted or derived on demand. - Exact names for locked submission artifact policy version/hash fields. - Compatibility plan for `ProjectGuide.evidence_policy`. diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DISCOVERY.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DISCOVERY.md index 5b5c48a..0eeca3c 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DISCOVERY.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DISCOVERY.md @@ -25,6 +25,12 @@ The backend is still transitional: - Post-submit durable checks use registered checker names and locked checker policy. +The product ownership boundary is also not explicit enough yet. Project owners +should provide guide material, task examples, rubrics, payment inputs, and +plain-language artifact expectations. Workstream should derive the +machine-readable project submission artifact policy from that material, then +require approval by `admin` or `project_manager` before guide activation. + ## Relevant Files/Modules | Path | Purpose | Notes | @@ -66,6 +72,7 @@ The backend is still transitional: | Risk | Why it matters | Suggested handling | |---|---|---| | Policy/source drift | Guide prose, task fields, and checker policy can disagree. | Introduce policy objects first, then migrate runtime reads in later chunks. | +| Project owner-authored schema burden | Asking project owners to write Workstream policy schema creates setup errors and unfair worker failures. | Workstream derives policy from project material and requires approval by `admin` or `project_manager`. | | Weakening defaults | Project policy could accidentally remove Workstream safety rules. | Implement non-bypassable default merge validation. | | Big-bang rewrite | Changing project, task, submission, and checker runtime together is risky. | Split into reviewable chunks. | | Version/hash ambiguity | Pre-submit policy is generated, so versioning needs careful naming. | Human review field names before migration. | @@ -76,6 +83,7 @@ The backend is still transitional: | Question | Why it matters | Needed before chunk? | |---|---|---| | Exact default artifact rules | Defines non-bypassable Workstream intake behavior. | Yes, before implementation chunk 1 completes. | +| Exact project-owner intake checklist | Defines what a company must provide so Workstream can derive policy. | Yes, before implementation chunk 1 completes. | | Whether `evidence_policy` stays as backward-compatible alias | Affects API compatibility and migration scope. | Yes, before migration chunk. | | Exact policy version/hash field names | Prevents future schema drift. | Yes, before schema migration. | | Whether generated `PreSubmitCheckerPolicy` is persisted or derived on read | Affects data model and audit proof. | Yes, before chunk 2. | diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md index fd05085..20163d9 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md @@ -21,6 +21,10 @@ Make submission intake policy-driven: ProjectGuide = human-facing instructions SubmissionArtifactPolicy = machine-readable intake contract +Project owner material +-> Workstream-derived ProjectSubmissionArtifactPolicy +-> approval by admin or project_manager + WorkstreamDefaultSubmissionArtifactPolicy + ProjectSubmissionArtifactPolicy = EffectiveSubmissionArtifactPolicy @@ -29,9 +33,20 @@ EffectiveSubmissionArtifactPolicy -> generated PreSubmitCheckerPolicy ``` -Workers submit draft packet fields. Workstream decides required artifacts, -evidence, hashes, storage reference rules, forbidden artifacts, and blocking -pre-submit feedback from the effective policy. +Project owners provide project material: guide text or documentation links, +task inputs, expected outputs, examples, acceptance criteria, rejection +criteria, review rubric, skill expectations, base payout or payment policy +inputs, confidentiality constraints, and plain-language artifact expectations. +They do not author Workstream's machine-readable submission policy schema +directly. + +Workstream derives the project submission artifact policy from that material, +using internal agent assistance where useful. A Workstream actor with the +`admin` or `project_manager` role reviews and approves the derived policy +before guide activation. Workers submit draft +packet fields. Workstream decides required artifacts, evidence, hashes, storage +reference rules, forbidden artifacts, and blocking pre-submit feedback from the +effective policy. ## Why Now @@ -53,6 +68,9 @@ boundary will become confusing. After this initiative: - `SubmissionArtifactPolicy` is a first-class backend object. +- `SubmissionArtifactPolicy` is Workstream-derived from project material and + approved by `admin` or `project_manager`, not authored directly by the + project owner. - Workstream default submission artifact rules are defined in code. - Project submission artifact policy cannot weaken Workstream defaults. - Effective submission artifact policy is computed deterministically. @@ -86,10 +104,15 @@ simple. Stored review decision values remain exactly `accept`, `needs_revision`, and `reject`; display labels may render those as accepted, needs revision, and rejected where appropriate. +Pre-submit feedback is not review. A blocking pre-submit result is presented as +`pre_submission_checker_failed` with structured pass/fail/warning details. It +does not create a submission and must not use review decision values. + ## Human Judgment Required - Approve the chunk sequence before implementation. - Approve the exact Workstream default submission artifact rules. +- Approve the required project-owner intake material for v0.1 project setup. - Approve naming for new persisted fields and policy version/hash fields. - Approve any migration strategy that changes existing transitional fields. diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md index e0a76d9..f658f8f 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md @@ -18,7 +18,7 @@ ProjectGuide human-facing instructions ProjectSubmissionArtifactPolicy - project-admin-approved machine-readable intake rules + Workstream-derived, admin-or-project-manager-approved machine-readable intake rules WorkstreamDefaultSubmissionArtifactPolicy platform-owned, non-bypassable safety rules @@ -33,9 +33,18 @@ PostSubmitCheckerPolicy durable checker rules for locked submission review readiness ``` -Pre-submit checks run before submission creation and do not create durable -checker records. Post-submit/internal checks run after submission lock and do -create durable checker records. +Project owners provide human-facing setup material. Workstream derives the +machine-readable project submission artifact policy from that material, then a +Workstream actor with the `admin` or `project_manager` role approves it. +Pre-submit checks run before submission +creation and do not create durable checker records. Post-submit/internal checks +run after submission lock and do create durable checker records. + +If no approved project submission artifact policy exists for the active guide, +guide activation fails and tasks using that guide cannot enter the ready worker +pipeline. The system must surface setup failure internally as task/project setup +incomplete rather than letting workers discover missing intake rules at submit +time. ## Alternatives Considered @@ -56,6 +65,13 @@ Rejected because pre-submit should be generated from the effective submission artifact policy. Workers and project admins should not choose blocking checker internals directly for intake. +### Make project owners author `SubmissionArtifactPolicy` directly + +Rejected because project owners should provide domain material, not internal +Workstream schema. Workstream owns derivation of the machine-readable contract, +and actors with the `admin` or `project_manager` role approve it before the +project can accept ready tasks. + ### Combine pre-submit and post-submit checker policy Rejected because pre-submit answers whether a packet can be submitted at all, @@ -64,8 +80,11 @@ while post-submit answers whether a locked submission can move to human review. ## Boundaries Preserved - Auth/session: still only verifies external Flow authentication tokens. -- Permission/policy: project managers/admins own project policy setup; workers - do not provide policy versions or checker names. +- Permission/policy: actors with the `admin` or `project_manager` role approve + project policy setup; workers do not provide policy versions or checker names. +- Project-owner boundary: project owners provide guide material, + examples, rubrics, payment inputs, and artifact expectations in plain + language; Workstream turns that material into approved policy. - Payment/execution: no payment or contribution records in this initiative. - Persistence/data: schema changes land through Alembic and async SQLAlchemy. - Presentation/API: backend-first; no frontend implementation. @@ -74,17 +93,20 @@ while post-submit answers whether a locked submission can move to human review. ## Rollout/Migration Strategy 1. Add dedicated policy model/API while keeping transitional fields readable. -2. Compute effective policy in service code and validate defaults cannot weaken. -3. Generate pre-submit checker policy from effective policy. -4. Migrate submission creation to effective policy. -5. Split post-submit checker policy naming/provenance. -6. Retire or alias transitional `evidence_policy`, `required_files`, and +2. Add the Workstream-owned derivation/approval boundary for project policy. +3. Compute effective policy in service code and validate defaults cannot weaken. +4. Generate pre-submit checker policy from effective policy. +5. Migrate submission creation to effective policy. +6. Split post-submit checker policy naming/provenance. +7. Retire or alias transitional `evidence_policy`, `required_files`, and `required_evidence` usage after tests prove the new path. ## Verification Strategy - Unit-level policy merge tests for default + project policy. - Postgres-backed API tests for project policy creation and guide activation. +- Tests proving a guide cannot activate without an approved project submission + artifact policy. - Submission API tests proving blocking pre-submit failure creates no submission row, version, task transition, durable checker run, or submission-created audit. - Real API drill proving clean pass and `needs_revision` resubmission. diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/RISKS.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/RISKS.md index 8b94a1e..4525eed 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/RISKS.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/RISKS.md @@ -4,6 +4,7 @@ |---|---|---| | Big-bang lifecycle rewrite | High | Split policy, generation, submission runtime, post-submit split, and revision proof into separate chunks. | | Default policy can be weakened | High | Validate effective policy rejects any project policy that removes or downgrades defaults. | +| Project owner schema burden | High | Project owners provide plain-language material; Workstream derives policy and actors with the `admin` or `project_manager` role approve it. | | Naming drift | High | Human review field names before migrations. | | Worker-facing internal route leakage | Medium | Keep `task_setup_blocked` and `checker_retry` internal; expose `needs_revision` only when worker action is needed. | | Backward compatibility drift | Medium | Keep transitional fields explicit until replacement is proven. | diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md index 1c000ff..dd5e637 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md @@ -16,6 +16,12 @@ The code still uses transitional `evidence_policy`, `required_files`, and effective policy, Workstream needs a real policy object and non-bypassable default policy validation. +Project owners must not be asked to author the Workstream policy schema +directly. They provide project setup material in plain language; Workstream +derives project submission artifact policy from that material, and a project +actor with the `admin` or `project_manager` role approves it before guide +activation. + ## Approved Plan Reference - INTENT: `.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md` @@ -60,7 +66,8 @@ human review implementation - Routers only translate HTTP requests/responses and map domain errors. - Services own policy merge rules, Workstream default validation, guide - activation checks, and permission-aware orchestration. + activation checks, Workstream-owned policy derivation boundaries, and + permission-aware orchestration. - Repositories only persist and query policy records. - Schemas only define API input/output contracts and validation shape. @@ -71,6 +78,13 @@ human review implementation - [ ] Policy rows have a composite foreign key to `project_guides(project_id, version)`. - [ ] Pydantic input/output schemas exist for project submission artifact policy. - [ ] Project service can create/update the policy with a draft guide. +- [ ] Project policy records include approval provenance showing the approved + machine policy was reviewed by `admin` or `project_manager`. +- [ ] Approval provenance includes derivation source, source material refs, + approval status, approver role, approver actor, approval timestamp, and + approved policy version or hash. +- [ ] Guide activation fails when no approved project submission artifact policy + exists for the guide version. - [ ] Guide activation requires valid submission artifact policy. - [ ] Workstream default submission artifact policy is represented in code. - [ ] Workstream default policy requires `sha256:<64 lowercase hex>` artifact hashes where production hashes are required. @@ -119,6 +133,8 @@ Conditional: ## Human Review Focus - Are the policy field names precise enough? +- Is the project-owner intake checklist precise enough for Workstream to derive + policy without making project owners author internal schema? - Are Workstream default rules complete enough for v0.1? - Should `evidence_policy` remain a compatibility alias during migration? - Should generated pre-submit policy be persisted in chunk 2 or derived on read? diff --git a/docs/architecture_checker_framework.md b/docs/architecture_checker_framework.md index 49d62bd..6eb4b8c 100644 --- a/docs/architecture_checker_framework.md +++ b/docs/architecture_checker_framework.md @@ -170,7 +170,10 @@ ProjectGuide -> Submission row only when blocking checks pass ``` -`ProjectGuide` is human-facing. `SubmissionArtifactPolicy` is machine-readable and approved by a project admin. Workstream combines that policy with the non-bypassable Workstream default submission artifact policy. +`ProjectGuide` is human-facing. `SubmissionArtifactPolicy` is machine-readable, +derived by Workstream from project owner material, and approved by a Workstream +actor with the `admin` or `project_manager` role. Workstream combines that +policy with the non-bypassable Workstream default submission artifact policy. Workstream default submission artifact rules require: @@ -185,7 +188,12 @@ Workstream default submission artifact rules require: Project policy adds required artifacts, evidence requirements, stricter forbidden artifacts, stricter packaging rules, and project-specific attestation requirements. -The generated `PreSubmitCheckerPolicy` runs before Workstream creates a submission. Blocking failures prevent submission creation and return worker-safe fixes. Pre-submit results do not create durable `CheckerRun` records and do not move a task to `review_pending`. +The generated `PreSubmitCheckerPolicy` runs before Workstream creates a +submission. Blocking failures prevent submission creation and return +`pre_submission_checker_failed` with structured pass/fail/warning details. +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`. Pre-submit checks are authoritative for intake. Post-submit checker runs are authoritative for review readiness. diff --git a/docs/architecture_data_model.md b/docs/architecture_data_model.md index 02f7ac6..9bfcf67 100644 --- a/docs/architecture_data_model.md +++ b/docs/architecture_data_model.md @@ -153,6 +153,10 @@ The guide is versioned and human-facing. It contains project instructions, quali Runtime enforcement uses machine-readable policies attached to the guide version. Workstream does not parse guide prose at submission time to decide which artifact checks to run. +Project owners provide setup material in plain language. Workstream derives +machine-readable project policy from that material, then a Workstream actor with +the `admin` or `project_manager` role approves it before the guide can activate. + Every task records the guide version active at creation or screening time before the task enters `READY`. Later source adapters must also lock the guide version during normalization before workers see the task. When a task is claimed or moved to `IN_PROGRESS`, its locked guide and policy context does not change silently. A newer upstream guide version can only affect unclaimed work or a controlled revision path when policy allows it and the audit log records the reason. @@ -181,7 +185,13 @@ Fields: - `required_attestation_terms` - `packaging_rules` - `created_by` +- `derivation_source` +- `source_material_refs` +- `approval_status` +- `approved_policy_hash` +- `approved_by_role` - `approved_by` +- `approved_at` - `created_at` Example: @@ -204,13 +214,20 @@ Example: "artifact_hash_algorithm": "sha256", "allowed_storage_schemes": ["local", "s3", "r2"], "forbidden_artifacts": ["secrets/**", ".env"], + "derivation_source": "workstream_agent", + "source_material_refs": ["project-guide:v1"], + "approval_status": "approved", + "approved_by": "flow-project-manager", + "approved_at": "2026-06-22T12:00:00Z", "packaging_rules": { "archive_required": true } } ``` -Project admins approve this policy. Workers do not supply it. +Workstream derives this policy from project owner material. A Workstream actor +with the `admin` or `project_manager` role approves it. Workers do not supply +it. Project policy can add stricter requirements, but it cannot weaken Workstream's default submission artifact policy. @@ -266,7 +283,11 @@ The generated checker order is deterministic: 8. worker attestation validation 9. low-quality artifact warnings -Blocking pre-submit failures prevent submission creation. A failed blocking pre-submit check creates no submission row, no submission version, no task transition to `submitted`, and no submission-created audit event. +Blocking pre-submit failures prevent submission creation. A failed blocking +pre-submit check returns `pre_submission_checker_failed` with structured +pass/fail/warning details, creates no submission row, no submission version, no +task transition to `submitted`, and no submission-created audit event. It does +not return review decision values. ## PostSubmitCheckerPolicy diff --git a/docs/architecture_lockdown.md b/docs/architecture_lockdown.md index 18d9622..c1402ba 100644 --- a/docs/architecture_lockdown.md +++ b/docs/architecture_lockdown.md @@ -77,9 +77,16 @@ Every active guide version must also have approved machine-readable policies: The guide may summarize or link to those policies, but the policies are the enforcement source. +Project owners provide setup material in plain language. Workstream derives +`ProjectSubmissionArtifactPolicy` from that material, and a Workstream actor +with the `admin` or `project_manager` role approves it before guide activation. + `SubmissionArtifactPolicy` defines what a worker must submit. Workstream combines it with the non-bypassable Workstream default submission artifact policy to create the effective submission artifact policy. Workstream generates `PreSubmitCheckerPolicy` from that effective policy. -Blocking pre-submit failures prevent submission creation. They return worker-safe fixes and create no submission row, no submission version, no task transition to `submitted`, and no submission-created audit event. +Blocking pre-submit failures prevent submission creation. They return +`pre_submission_checker_failed` with structured pass/fail/warning details and +create no submission row, no submission version, no task transition to +`submitted`, and no submission-created audit event. Tasks lock to the active guide version at creation or screening time before entering `READY`. Material guide changes require a new guide version. @@ -150,6 +157,7 @@ Use these names consistently: - `EffectiveSubmissionArtifactPolicy` - `PreSubmitCheckerPolicy` - `PostSubmitCheckerPolicy` +- `pre_submission_checker_failed` - `Project activation gate` - `Task screening gate` - `Submission quality gate` diff --git a/docs/current_system_data_flow.html b/docs/current_system_data_flow.html index 8ef365f..c1bd13c 100644 --- a/docs/current_system_data_flow.html +++ b/docs/current_system_data_flow.html @@ -470,8 +470,8 @@

Flow token enters API

2 -

Project guide is drafted

-

The project manager creates the human-facing project guide, submission artifact policy, and all policy context needed before tasks can run.

+

Project guide and policy are prepared

+

The project owner provides guide material and artifact expectations. Workstream derives the submission artifact policy, then an admin or project_manager approves it before tasks can run.

Project ProjectGuide v1 @@ -482,7 +482,7 @@

Project guide is drafted

3

Guide activation locks contract

-

Activation validates submission artifact policy, generated pre-submit policy, registered post-submit checker names, review decisions, revision states, and payment policy.

+

Activation validates approved submission artifact policy, generated pre-submit policy, registered post-submit checker names, review decisions, revision states, and payment policy.

status=active one active guide @@ -514,7 +514,7 @@

Worker claims and starts

6

Pre-submit intake checks run

-

Workstream runs generated pre-submit checks from the effective submission artifact policy before creating a submission row.

+

Workstream runs generated pre-submit checks from the effective submission artifact policy before creating a submission row. Blocking failures return pre_submission_checker_failed with pass/fail/warning details.

no submission yet no checker run yet diff --git a/docs/decision_0003_project_guides_are_first_class.md b/docs/decision_0003_project_guides_are_first_class.md index 9e82413..655b4af 100644 --- a/docs/decision_0003_project_guides_are_first_class.md +++ b/docs/decision_0003_project_guides_are_first_class.md @@ -40,7 +40,7 @@ Project guide activation requires the guide plus its required policy context bef - revision policy - payment policy -The project-admin-approved submission artifact policy defines what workers must submit. Workstream combines it with non-bypassable Workstream default artifact rules to create the effective submission artifact policy. Workstream then generates the pre-submit checker policy from that effective policy. +The Workstream-derived submission artifact policy defines what workers must submit. Project owners provide plain-language setup material; a Workstream actor with the `admin` or `project_manager` role approves the machine policy. Workstream combines that policy with non-bypassable Workstream default artifact rules to create the effective submission artifact policy. Workstream then generates the pre-submit checker policy from that effective policy. Blocking pre-submit failures prevent submission creation. They do not create durable post-submit checker runs and they do not create human review decisions. 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 a514ac6..41fe7b9 100644 --- a/docs/decision_0011_submission_artifact_policy_drives_pre_submit.md +++ b/docs/decision_0011_submission_artifact_policy_drives_pre_submit.md @@ -16,7 +16,18 @@ Workstream also needs platform-owned default submission safety rules that no pro Every active project guide version must have an approved `SubmissionArtifactPolicy`. -`SubmissionArtifactPolicy` is the project-admin-approved machine-readable contract for worker submissions. It defines: +Project owners provide project setup material in plain language: project purpose, +guide material, task examples, expected outputs, acceptance criteria, rejection +criteria, review rubric, required skills, confidentiality constraints, base +payout or payment policy inputs, and artifact expectations. They do not author +Workstream's machine-readable policy schema directly. + +Workstream derives `ProjectSubmissionArtifactPolicy` from that material, using +internal agent assistance where useful. A Workstream actor with the `admin` or +`project_manager` role must review and approve the derived policy before guide +activation. + +`SubmissionArtifactPolicy` is the Workstream-derived, admin-or-project-manager-approved machine-readable contract for worker submissions. It defines: - required artifacts - required evidence references @@ -31,6 +42,11 @@ Workstream owns a default submission artifact policy. Every project inherits it. Project policy can add stricter requirements, but it cannot remove, weaken, downgrade, or bypass Workstream defaults. +Approval provenance is part of the policy contract. A policy record must make +approval testable with source/provenance state such as derivation source, +approval status, approver actor, approval timestamp, and approved policy +version/hash. + The runtime contract is: ```text @@ -49,7 +65,9 @@ Blocking pre-submit failures prevent submission creation. When blocking pre-subm - no submission version is assigned - no task transition to `submitted` occurs - no submission-created audit event is written -- the response returns worker-safe checker feedback +- the response returns `pre_submission_checker_failed` +- the response includes structured pass/fail/warning details +- the response does not use review decision values: `accept`, `needs_revision`, or `reject` Pre-submit checks are authoritative for submission intake. They are not authoritative proof for human review readiness. Review readiness still requires post-submit internal checker runs against a locked submission. diff --git a/docs/glossary.md b/docs/glossary.md index 1d999de..ebbe297 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -8,6 +8,10 @@ Flow's task evaluation and contribution infrastructure: the system for project g A configured work program with its own human-facing guide, submission artifact policy, checker policies, review policy, revision policy, payment policy, and queue. +## Project Owner + +The external or internal organization that provides project setup material in plain language: project purpose, guide material, examples, expected outputs, acceptance criteria, rejection criteria, review rubric, required skills, confidentiality constraints, base payout or payment policy inputs, and artifact expectations. The project owner does not author Workstream's machine-readable policy schema directly. + ## Source Where a task came from. In v0.1, sources are manual creation, controlled markdown import, or controlled CSV import. @@ -22,7 +26,7 @@ The human-facing operating guide for a project. It contains the project instruct ## Submission Artifact Policy -The project-admin-approved machine-readable contract for what a worker must submit. It defines required artifacts, evidence requirements, artifact hash requirements, allowed storage reference forms, forbidden artifacts, attestation requirements, and project-specific packaging rules. It can add or tighten requirements, but it cannot weaken Workstream's default submission artifact rules. +The Workstream-derived, admin-or-project-manager-approved machine-readable contract for what a worker must submit. It is derived from project owner material, reviewed by a Workstream actor with the `admin` or `project_manager` role, and attached to a project guide version. It defines required artifacts, evidence requirements, artifact hash requirements, allowed storage reference forms, forbidden artifacts, attestation requirements, and project-specific packaging rules. It can add or tighten requirements, but it cannot weaken Workstream's default submission artifact rules. ## Effective Submission Artifact Policy @@ -30,7 +34,11 @@ The deterministic merge of Workstream's default submission artifact policy and t ## Pre-Submit Checker Policy -The server-generated checker matrix produced from the effective submission artifact policy. It runs before Workstream creates a submission row or submission version. Blocking failures return worker-safe fixes and prevent submission creation. +The server-generated checker matrix produced from the effective submission artifact policy. It runs before Workstream creates a submission row or submission version. Blocking failures return `pre_submission_checker_failed` with structured pass/fail/warning details, prevent submission creation, and do not return review decision values: `accept`, `needs_revision`, or `reject`. + +## pre_submission_checker_failed + +The worker-facing pre-submit failure code returned before a submission exists. It includes structured pass/fail/warning details and is not a review decision. It must not be stored as `accept`, `needs_revision`, or `reject`. ## Task diff --git a/docs/operations_project_operating_manual.md b/docs/operations_project_operating_manual.md index 765b070..a016604 100644 --- a/docs/operations_project_operating_manual.md +++ b/docs/operations_project_operating_manual.md @@ -29,7 +29,8 @@ Before releasing tasks: - currency configured - allowed task types listed - required task fields listed -- submission artifact policy approved +- project owner setup material captured +- submission artifact policy derived by Workstream and approved by `admin` or `project_manager` - generated pre-submit checker policy created from the effective submission artifact policy - post-submit checker policy attached - review policy attached @@ -42,7 +43,7 @@ Before releasing tasks: ### Project Activation Gate -A project cannot become active unless guide, submission artifact policy, generated pre-submit checker policy, post-submit checker policy, review policy, revision policy, and payment policy are present. +A project cannot become active unless guide, approved submission artifact policy, generated pre-submit checker policy, post-submit checker policy, review policy, revision policy, and payment policy are present. ### Task Screening Gate @@ -97,7 +98,7 @@ Before accepting a submission packet: - revision replay exists when task was previously `NEEDS_REVISION` - effective submission artifact policy is loaded - generated pre-submit checker policy runs -- blocking pre-submit failures return worker-safe fixes +- blocking pre-submit failures return `pre_submission_checker_failed` with structured pass/fail/warning details - no submission row is created until blocking pre-submit checks pass ## Reviewer Simulation Gate diff --git a/docs/operations_workspace_packet_convention.md b/docs/operations_workspace_packet_convention.md index 2d4d0e3..aeb4403 100644 --- a/docs/operations_workspace_packet_convention.md +++ b/docs/operations_workspace_packet_convention.md @@ -8,7 +8,8 @@ Workstream does not need to own the execution workspace, but it must define what ## Project-Level Convention -Every project defines an approved `SubmissionArtifactPolicy`: +Every project has an approved `SubmissionArtifactPolicy` derived by Workstream +from project owner material: ```text required_artifacts @@ -64,7 +65,7 @@ A packet is not ready unless: Some projects need final work in a paste-ready form. Others need a zip, artifact bundle, markdown packet, or review file. -The project guide explains the canonical form to humans. The approved `SubmissionArtifactPolicy` enforces the artifact, evidence, hash, and packaging rules. +The project guide explains the canonical form to humans. The approved `SubmissionArtifactPolicy` enforces the artifact, evidence, hash, and packaging rules. Project owners do not author this machine policy schema directly. ## Why This Matters diff --git a/docs/product_first_user_flows.md b/docs/product_first_user_flows.md index d787057..1ddc3a7 100644 --- a/docs/product_first_user_flows.md +++ b/docs/product_first_user_flows.md @@ -5,19 +5,21 @@ The first user flows prove that Workstream can run real work from intake to acce ## Flow 1: Admin Creates A Project 1. Admin creates project. -2. Admin adds guide. -3. Admin sets base amount. -4. Admin approves submission artifact policy. -5. Workstream generates pre-submit checker policy. -6. Admin enables post-submit checker policy. -7. Admin enables review policy. -8. Admin enables revision policy. -9. Admin enables payment policy. -10. Project becomes active. +2. Project owner provides guide material, examples, expected outputs, review rubric, artifact expectations, and payment policy inputs. +3. Admin or project_manager adds the guide. +4. Workstream derives project submission artifact policy from the project owner material. +5. Admin or project_manager reviews and approves the submission artifact policy. +6. Workstream generates pre-submit checker policy. +7. Admin or project_manager enables post-submit checker policy. +8. Admin or project_manager enables review policy. +9. Admin or project_manager enables revision policy. +10. Admin or project_manager enables payment policy. +11. Project becomes active. Acceptance: - Project cannot become active without guide, base amount, submission artifact policy, generated pre-submit checker policy, post-submit checker policy, review policy, revision policy, and payment policy. +- Submission artifact policy is Workstream-derived and approved by `admin` or `project_manager`; project owners do not author the machine policy schema directly. - Submission artifact, checker, review, revision, and payment policies are visible on the project page. ## Flow 2: Operator Creates A Task @@ -42,13 +44,14 @@ Acceptance: 3. Worker attaches evidence. 4. Worker writes submission notes. 5. Workstream runs pre-submit checks generated from the effective submission artifact policy. -6. Blocking pre-submit failures return worker-safe fixes and create no submission. +6. Blocking pre-submit failures return `pre_submission_checker_failed` with structured pass/fail/warning details and create no submission. 7. When blocking pre-submit checks pass, Worker submits packet. 8. Task enters `SUBMITTED`. Acceptance: - Submission cannot be created when blocking pre-submit checks fail. +- Blocking pre-submit failures are not review decisions and never return `accept`, `needs_revision`, or `reject`. - Submission cannot be created without required artifacts, evidence references, hashes, and worker attestation defined by the effective submission artifact policy. - Submission packet is immutable after checks start. diff --git a/docs/spec_chunk_5_submission_packet_foundation.md b/docs/spec_chunk_5_submission_packet_foundation.md index 3817be1..ac71a88 100644 --- a/docs/spec_chunk_5_submission_packet_foundation.md +++ b/docs/spec_chunk_5_submission_packet_foundation.md @@ -163,7 +163,7 @@ Chunk 5 writes task audit events with submission identifiers in `event_payload`. - worker-provided guide or policy version fields are rejected by the API schema - worker-provided submission version fields are rejected by the API schema - worker-provided checker names, checker outcomes, evidence ids, and checker run ids are rejected by the API schema -- blocking pre-submit failures return structured worker-safe feedback and create no submission row, no submission version, no task transition to `SUBMITTED`, and no submission-created audit event +- blocking pre-submit failures return `pre_submission_checker_failed` with structured pass/fail/warning details and create no submission row, no submission version, no task transition to `SUBMITTED`, and no submission-created audit event - Workstream stamps locked guide and policy versions from task context - task moves to `SUBMITTED` - submitted packet can be locked before checker execution diff --git a/docs/spec_chunk_6_checker_contract_records.md b/docs/spec_chunk_6_checker_contract_records.md index 3829fc6..0341d1e 100644 --- a/docs/spec_chunk_6_checker_contract_records.md +++ b/docs/spec_chunk_6_checker_contract_records.md @@ -211,9 +211,16 @@ Response fields: Pre-submit feedback binds to `task_id`, the task's locked guide version, the approved submission artifact policy context, draft packet fields, package hash, and artifact manifest shape. It does not require a locked `submission_id` or locked submission version because those do not exist before submission creation. -Blocking pre-submit failures prevent submission creation. They create no submission row, no submission version, no task transition to `submitted`, and no submission-created audit event. - -Pre-submit results are not authoritative for `REVIEW_PENDING` and cannot create `NEEDS_REVISION`. Only post-submit runs against locked submissions can produce routing recommendations for `REVIEW_PENDING` or user-facing `needs_revision`. +Blocking pre-submit failures prevent submission creation. They return +`pre_submission_checker_failed` with structured pass/fail/warning details, +create no submission row, no submission version, no task transition to +`submitted`, and no submission-created audit event. + +Pre-submit results are not authoritative for `REVIEW_PENDING`, cannot create +`NEEDS_REVISION`, and do not return review decision values: `accept`, +`needs_revision`, or `reject`. Only post-submit runs against locked submissions +can produce routing recommendations for `REVIEW_PENDING` or user-facing +`needs_revision`. ## User-Facing Revision Rule diff --git a/docs/spec_chunk_7_checker_runner_registry.md b/docs/spec_chunk_7_checker_runner_registry.md index fba6a6e..c9acca6 100644 --- a/docs/spec_chunk_7_checker_runner_registry.md +++ b/docs/spec_chunk_7_checker_runner_registry.md @@ -138,7 +138,11 @@ For worker-fixable blocking structural failures after submission lock, the run r Chunk 7 records the recommendation only. Chunk 9 applies the lifecycle transition. -Blocking pre-submit failures occur before durable checker runs exist. They prevent submission creation and return worker-safe fixes instead of recording `needs_revision`. +Blocking pre-submit failures occur before durable checker runs exist. They +prevent submission creation and return `pre_submission_checker_failed` with +structured pass/fail/warning details instead of recording `needs_revision`. +They do not return review decision values: `accept`, `needs_revision`, or +`reject`. ## Artifact Manifest Hash @@ -174,7 +178,7 @@ Worker responses must not expose: - checker ORM models are registered in Alembic metadata - partial unique index allows one current run per submission - pre-submit check returns feedback without durable checker rows -- blocking pre-submit failures create no submission row, no submission version, no task transition to `submitted`, and no submission-created audit event +- blocking pre-submit failures return `pre_submission_checker_failed`, include structured pass/fail/warning details, create no submission row, no submission version, no task transition to `submitted`, and no submission-created audit event - durable checker run works through real authenticated API calls - `check_submission_packet` runs against real submission data - duplicate artifact manifests persist worker-visible checker failures diff --git a/docs/spec_chunk_8_submission_artifact_policy_checkers.md b/docs/spec_chunk_8_submission_artifact_policy_checkers.md index a6d10a4..ae41e00 100644 --- a/docs/spec_chunk_8_submission_artifact_policy_checkers.md +++ b/docs/spec_chunk_8_submission_artifact_policy_checkers.md @@ -211,7 +211,11 @@ WorkstreamDefaultSubmissionArtifactPolicy Workstream defaults are non-bypassable. Project policy can add required artifacts, evidence requirements, stricter forbidden patterns, and packaging rules, but it cannot remove hash requirements, allow unsafe storage references, require forbidden files, or downgrade blocking defaults. -Blocking pre-submit failures prevent submission creation. They create no submission row, no submission version, no task transition to `submitted`, and no submission-created audit event. +Blocking pre-submit failures prevent submission creation. They return +`pre_submission_checker_failed` with structured pass/fail/warning details, +create no submission row, no submission version, no task transition to +`submitted`, and no submission-created audit event. They do not return review +decision values: `accept`, `needs_revision`, or `reject`. Durable post-submit checker runs run the canonical default submission-quality checks plus locked checker-policy names: @@ -297,7 +301,7 @@ Safe evidence references mean opaque Workstream evidence ids, sanitized labels, - canonical Chunk 8 checker names are registered - stale Chunk 7 temporary checker names are removed from public docs/templates/tests - pre-submit feedback is generated from the effective submission artifact policy and runs without durable checker records -- blocking pre-submit failures create no submission row, no submission version, no task transition to `submitted`, and no submission-created audit event +- blocking pre-submit failures return `pre_submission_checker_failed`, include structured pass/fail/warning details, create no submission row, no submission version, no task transition to `submitted`, and no submission-created audit event - Workstream default submission artifact rules cannot be weakened by project policy - durable checker runs persist Chunk 8 checker results - missing required evidence blocks review routing diff --git a/docs/spec_week2_checker_framework.md b/docs/spec_week2_checker_framework.md index 12dc602..9147fc3 100644 --- a/docs/spec_week2_checker_framework.md +++ b/docs/spec_week2_checker_framework.md @@ -71,9 +71,14 @@ Pre-submit static checks run before Workstream creates a submission. They are ge - storage reference safety - task assignment and state compatibility -Blocking pre-submit failures prevent submission creation. They create no submission row, no submission version, no task transition to `submitted`, and no submission-created audit event. - -Pre-submit failures do not create review decisions and do not create durable post-submit checker runs. +Blocking pre-submit failures prevent submission creation. They return +`pre_submission_checker_failed` with structured pass/fail/warning details, +create no submission row, no submission version, no task transition to +`submitted`, and no submission-created audit event. + +Pre-submit failures do not create review decisions, do not return `accept`, +`needs_revision`, or `reject`, and do not create durable post-submit checker +runs. Post-submit internal checks run after a submission is created and locked. These checks are the source of truth for review gating. They run from Workstream-owned services, use locked task guide and policy context, and persist durable checker runs/results. diff --git a/docs/template_checker_policy.md b/docs/template_checker_policy.md index 5ac107a..aa3f14e 100644 --- a/docs/template_checker_policy.md +++ b/docs/template_checker_policy.md @@ -55,7 +55,10 @@ EffectiveSubmissionArtifactPolicy = + ProjectSubmissionArtifactPolicy ``` -Blocking pre-submit failures prevent submission creation and do not create durable `CheckerRun` records. +Blocking pre-submit failures prevent submission creation, return +`pre_submission_checker_failed` with structured pass/fail/warning details, do +not create durable `CheckerRun` records, and do not return review decision +values: `accept`, `needs_revision`, or `reject`. ## Checker Registry Fields diff --git a/docs/template_project_guide.md b/docs/template_project_guide.md index 54410b7..59f5dae 100644 --- a/docs/template_project_guide.md +++ b/docs/template_project_guide.md @@ -116,6 +116,11 @@ Every active guide version must have: Artifact requirements shown to workers are derived from the approved `SubmissionArtifactPolicy`. The guide may summarize those requirements, but the policy is the enforcement source. +Project owners provide this guide material and artifact expectations in +plain language. Workstream derives `ProjectSubmissionArtifactPolicy` from that +material, and a Workstream actor with the `admin` or `project_manager` role +approves it before guide activation. + ## Known Checker Blind Spots - ``: diff --git a/docs/template_submission_artifact_policy.md b/docs/template_submission_artifact_policy.md index 0c3c880..7b54442 100644 --- a/docs/template_submission_artifact_policy.md +++ b/docs/template_submission_artifact_policy.md @@ -12,6 +12,38 @@ `v1` +## Source Material + +Project owners provide setup material in plain language. Workstream derives this +policy from that material; project owners do not author the machine-readable +schema directly. + +Required project-owner intake material: + +- project purpose: +- guide material or documentation references: +- task inputs: +- expected outputs: +- examples of good submissions: +- examples of bad submissions: +- acceptance criteria: +- rejection criteria: +- review rubric: +- required skills: +- confidentiality constraints: +- base payout or payment policy inputs: +- artifact expectations: + +## Approval Provenance + +- derivation source: `manual | workstream_agent | import_adapter` +- source material refs: +- approval status: `draft | approved | superseded` +- approved policy hash: +- approved by role: `admin | project_manager` +- approved by actor: +- approved at: + ## Workstream Default Rules Every project inherits Workstream default submission artifact rules. Project policy can add stricter requirements, but it cannot remove, weaken, downgrade, or bypass these defaults. @@ -97,6 +129,10 @@ WorkstreamDefaultSubmissionArtifactPolicy Generated pre-submit checks run before submission creation. Blocking failures create no submission row, no submission version, no task transition to `submitted`, and no submission-created audit event. +Blocking failures return `pre_submission_checker_failed` with structured +pass/fail/warning details. They do not return review decision values: +`accept`, `needs_revision`, or `reject`. + Expected generated checks: - packet shape @@ -112,6 +148,7 @@ Expected generated checks: ## Approval - created by: -- approved by: +- approved by role: `admin | project_manager` +- approved by actor: - effective at: - change summary: diff --git a/docs/template_submission_packet.md b/docs/template_submission_packet.md index ce07fcb..b8a86d4 100644 --- a/docs/template_submission_packet.md +++ b/docs/template_submission_packet.md @@ -28,7 +28,11 @@ List files, links, packages, or deliverables. Workstream derives the locked project guide version, submission artifact policy version, generated pre-submit checker policy hash, post-submit checker policy version, review policy version, revision policy version, and payment policy version from the task and server-side project policy records. The worker does not provide those versions in the submission packet. -Workstream runs generated pre-submit checks before creating the submission. Blocking failures return worker-safe fixes and create no submission row, no submission version, and no submission-created audit event. +Workstream runs generated pre-submit checks before creating the submission. +Blocking failures return `pre_submission_checker_failed` with structured +pass/fail/warning details, create no submission row, no submission version, and +no submission-created audit event, and do not return review decision values: +`accept`, `needs_revision`, or `reject`. ## Artifact Hash Manifest From c40d55440f5c2dba72fc2dbc57a46d346ee3297c Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Mon, 22 Jun 2026 20:20:13 +0100 Subject: [PATCH 07/37] Record submission policy ownership review evidence --- .../WS-POL-001-01-external-review-response.md | 2 ++ .../WS-POL-001-01-internal-review-evidence.md | 17 +++++++++++++---- 2 files changed, 15 insertions(+), 4 deletions(-) diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md index 18d2dc5..f664a66 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md @@ -25,6 +25,8 @@ valid, in scope, and fixed without changing the product contract. | CodeRabbit | `WS-POL-001-03` acceptance criteria repeated "Blocking pre-submit failure creates no..." across consecutive lines. | Low | Fixed | Consolidated the four no-side-effect guarantees into one sentence while preserving every distinct requirement. | | GitHub checks | Agent Gates, Backend, Week 1 API Demo UI, and CodeRabbit status must pass. | High | Passed | All GitHub checks passed after the final push. | | CodeRabbit manual trigger | Manual `@coderabbitai review` was requested after the rate-limit window. | Informational | Complete | CodeRabbit replied "Review finished" and noted incremental review does not re-review already reviewed commits unless automatic reviews are paused. No new actionable findings were posted. | +| Human review | Project owners should not author `SubmissionArtifactPolicy`; Workstream should derive it from project material and require `admin` or `project_manager` approval. | High | Fixed | Updated planning artifacts, ADRs, glossary, architecture docs, specs, templates, operating manual, current data flow, and first user flows. | +| Human review | Pre-submit failures should not use review decisions and should show pass/fail details like the Snorkel-style static checker experience. | High | Fixed | Standardized `pre_submission_checker_failed` with structured pass/fail/warning details and explicit exclusion of `accept`, `needs_revision`, and `reject`. | ## Fix Plan diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md index 9aaa13e..0063cb9 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md @@ -10,13 +10,13 @@ valid findings addressed: yes ## Reviewed Revision -Reviewed code SHA: 709d6915cf5971efcf18f12e7ee55a881370b5e4 +Reviewed code SHA: 0b94c7df1fb1fa2a9df926ddfd5cb81404bb448c -Reviewed at: 2026-06-22T12:36:49Z +Reviewed at: 2026-06-22T19:16:02Z -Reviewer run IDs: 019eee8c-5c09-7603-bae4-2b2bc60f8dd3, 019eee8e-55e6-75b0-92dd-f5c44f80ad7b, 019eee91-1ff6-7552-8ce4-06a48f0ffac9, 019eee94-c99d-72a3-80f5-9b90ddd9c9d3, 019eee9a-b0eb-7020-880f-be0bfa1968f6, 019eeeca-bc88-7ce0-baec-6be4a8ca1f47, 019eeecb-f151-7433-a472-f3bcdaafda8f, 019eef36-6dc2-7e81-9663-8d3a6aec2278, 019eef37-a7cb-7302-84ac-06531bf8b0fb, 019eef3a-3b6c-7a92-a094-15a2f24615ff, 019eef3c-bfbb-7ed1-acb2-112c6d34b455 +Reviewer run IDs: 019eee8c-5c09-7603-bae4-2b2bc60f8dd3, 019eee8e-55e6-75b0-92dd-f5c44f80ad7b, 019eee91-1ff6-7552-8ce4-06a48f0ffac9, 019eee94-c99d-72a3-80f5-9b90ddd9c9d3, 019eee9a-b0eb-7020-880f-be0bfa1968f6, 019eeeca-bc88-7ce0-baec-6be4a8ca1f47, 019eeecb-f151-7433-a472-f3bcdaafda8f, 019eef36-6dc2-7e81-9663-8d3a6aec2278, 019eef37-a7cb-7302-84ac-06531bf8b0fb, 019eef3a-3b6c-7a92-a094-15a2f24615ff, 019eef3c-bfbb-7ed1-acb2-112c6d34b455, 019eeff9-e4de-7ae0-a264-3a1d75fda44e, 019eeffe-4448-7242-9196-da135f61e2f0, 019ef004-ef16-7d21-9910-6c397b8c4b6a, 019ef009-355b-7ae0-9236-e5136266fb8b, 019ef00d-8adf-7c63-8023-0187df5f6283, 019ef018-de9a-71d2-beac-bd74a96496df, 019ef046-eff0-79f1-8243-8e52c40805e3, 019ef04b-722f-7e23-90e3-e6dfd66c77c9, 019ef04f-9b1e-7ad2-bbd4-fc86ded065b4, 019ef098-9469-70f0-8396-2177ffadfeee, 019ef0b5-36e5-7d91-aca5-bc8505eb9f00 -After reviewed SHA `709d6915cf5971efcf18f12e7ee55a881370b5e4`, only review evidence artifacts changed. +After reviewed SHA `0b94c7df1fb1fa2a9df926ddfd5cb81404bb448c`, only review evidence artifacts changed. ## Reviewer Results @@ -32,6 +32,12 @@ After reviewed SHA `709d6915cf5971efcf18f12e7ee55a881370b5e4`, only review evide | qa/test | PASS | None | Re-reviewed consolidated criteria; no-row, no-version, no-transition, and no-durable-checker-run remain testable. | | product/ops | PASS | None | Re-reviewed consolidated criteria; worker-facing semantics remain simple and precise. | | docs | PASS WITH LOW RISKS | None | Re-reviewed consolidated criteria; no adjacent docs required. | +| senior engineering | PASS WITH LOW RISKS | None | Re-reviewed project-owner material, Workstream-derived policy, admin/project_manager approval, activation guard, and pre-submit failure boundary. Low risk captured around keeping chunk 1 scoped to policy provenance/approval, not full derivation workflow. | +| product/ops | PASS WITH LOW RISKS | None | Re-reviewed setup ownership, worker/reviewer boundary, and payment/reputation non-expansion. | +| architecture | PASS WITH LOW RISKS | None | Re-reviewed source-of-truth and chunk-scope boundaries; no blocking boundary violations. | +| qa/test | PASS WITH LOW RISKS | None | Re-reviewed approval provenance, activation guard, and `pre_submission_checker_failed` testability. `approved_by_role` was added to architecture data model after QA noted drift risk. | +| security/auth | PASS WITH LOW RISKS | None | Re-reviewed approval provenance, non-bypassable defaults, role approval boundary, and project-owner material as untrusted input. | +| docs | PASS | None | Re-reviewed canonical docs after stale ownership and pre-submit wording fixes. | ## Valid Findings Addressed @@ -42,6 +48,9 @@ After reviewed SHA `709d6915cf5971efcf18f12e7ee55a881370b5e4`, only review evide - Architecture requested explicit responsibility boundaries. The chunk contract now states routers translate HTTP, services own policy/default validation, repositories persist/query, and schemas define IO contracts. - Docs found `GeneratedPreSubmitCheckerPolicy` could look like a canonical token. The plan now uses canonical `PreSubmitCheckerPolicy` and describes it as generated. - CodeRabbit found repetitive wording in `WS-POL-001-03` acceptance criteria. The repeated lines were consolidated without changing the no-row, no-version, no-transition, and no-durable-checker-run requirements. +- Human review clarified that project owners should not author `SubmissionArtifactPolicy` directly. Docs now state project owners provide plain-language setup material, Workstream derives `ProjectSubmissionArtifactPolicy`, and `admin` or `project_manager` approves it before guide activation. +- QA requested schema-level testability for approval provenance. The chunk contract and architecture data model now name derivation source, source material refs, approval status, approver role, approver actor, approval timestamp, and approved policy version/hash. +- Docs found canonical/spec drift around pre-submit failures. ADRs, glossary, architecture docs, specs, templates, operating manual, and flow docs now use `pre_submission_checker_failed` with structured pass/fail/warning details and explicitly exclude review decision values. ## Commands Run From 6919788c56a30189f28ce1c114c4745c75f6ca45 Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Tue, 23 Jun 2026 10:41:00 +0100 Subject: [PATCH 08/37] Align submission artifact policy planning --- .../CHUNK_MAP.md | 57 ++++++---- .../DECISIONS.md | 46 ++++++-- .../DISCOVERY.md | 20 ++-- .../INTENT.md | 58 ++++++---- .../PLAN.md | 100 +++++++++++------- .../RISKS.md | 3 +- .../STATUS.md | 10 +- ...1-submission-artifact-policy-foundation.md | 55 ++++++---- docs/architecture_checker_framework.md | 21 ++-- docs/architecture_data_model.md | 81 ++++++++++++-- docs/architecture_lifecycle_state_machine.md | 4 +- docs/architecture_lockdown.md | 9 +- docs/current_system_data_flow.html | 5 +- ...ion_0003_project_guides_are_first_class.md | 4 +- ...ssion_artifact_policy_drives_pre_submit.md | 48 ++++++--- docs/glossary.md | 25 ++++- .../operations_workspace_packet_convention.md | 9 +- docs/product_first_user_flows.md | 26 +++-- docs/spec_chunk_3_project_guide_foundation.md | 13 ++- docs/template_project_guide.md | 9 +- docs/template_submission_artifact_policy.md | 52 +++++---- 21 files changed, 446 insertions(+), 209 deletions(-) diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md index 606d6d0..88e8ab9 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md @@ -7,18 +7,20 @@ checker splitting unless explicitly approved. - Every implementation chunk must use Postgres-backed tests. - Worker-facing outcomes remain simple; internal route names stay internal. -- Project owners provide setup material in plain language; Workstream derives - machine-readable submission artifact policy and actors with the `admin` or - `project_manager` role approve it. +- Project guides are open-ended project material. Workstream uses async + `ProjectGuideSufficiencyAgent` and + `SubmissionArtifactPolicyDerivationAgent` outputs to create the locked policy + bundle. ## Chunks -### WS-POL-001-01: Submission Artifact Policy Foundation +### WS-POL-001-01: Guide Policy Bundle Foundation Goal: -Add first-class `SubmissionArtifactPolicy` backend records and schemas, define -Workstream default submission artifact rules in code, and validate that project +Add first-class guide sufficiency, `SubmissionArtifactPolicy`, effective policy, +and persisted `PreSubmitCheckerPolicy` backend records and schemas. Define +Workstream default submission artifact rules in code and validate that project policy cannot weaken defaults. Risk: @@ -49,18 +51,28 @@ backend/app/modules/submissions/** .github/workflows/** frontend or demos payment/reputation/blockchain code +full async agent execution runtime ``` Acceptance criteria: - Dedicated submission artifact policy model/table exists. +- Dedicated guide sufficiency report model/table exists. +- Guide sufficiency report supports `passed`, `blocked`, and + `passed_with_warnings`. - Project policy is scoped to project id + guide version. - Project policy records are Workstream-derived and approved by `admin` or `project_manager`, not direct project owner-authored schema. - Workstream default policy is represented in code. - Effective policy merge rejects attempts to weaken defaults. -- Guide activation requires valid submission artifact policy. -- Existing `evidence_policy` transitional behavior is not silently broken. +- Effective submission artifact policy hash is persisted for the guide version. +- Generated `PreSubmitCheckerPolicy` snapshot/hash is persisted and locked to + the guide version. +- Guide activation requires passing or acknowledged guide sufficiency, approved + submission artifact policy, effective policy hash, and persisted generated + pre-submit checker policy. +- Transitional `evidence_policy`, `required_files`, and `required_evidence` are + replaced, not preserved as compatibility aliases. Required reviewers: @@ -69,16 +81,16 @@ reuse/dedup, test delta. Human review focus: -Policy ownership, project-owner intake checklist, policy field names, default -rule set, migration strategy, and whether `evidence_policy` remains a temporary -compatibility alias. +Guide sufficiency report fields, persisted provenance field names, and keeping +Chunk 1 limited to records/contracts/activation guards. -### WS-POL-001-02: Generated PreSubmitCheckerPolicy +### WS-POL-001-02: Async Guide Analysis And Policy Derivation Goal: -Generate pre-submit checker policy from effective submission artifact policy and -expose it only as server-owned policy context. +Run `ProjectGuideSufficiencyAgent` and +`SubmissionArtifactPolicyDerivationAgent` asynchronously against open-ended +project guide material. Risk: @@ -108,10 +120,16 @@ payment/reputation/blockchain code Acceptance criteria: -- Pre-submit checker policy is generated, not client-supplied. -- Generated policy contains Workstream defaults plus project additions. -- Generated policy names match registered pre-submit checker behavior. -- Workers cannot provide checker names, severities, versions, or outcomes. +- `ProjectGuideSufficiencyAgent` runs async and produces a persisted + sufficiency report for a guide version. +- Blocking guide gaps stop activation and create project-owner clarification + requests. +- Warnings can be acknowledged only by `admin` or `project_manager`. +- `SubmissionArtifactPolicyDerivationAgent` runs async after sufficiency passes + or warnings are acknowledged. +- Derived policy cannot weaken Workstream defaults. +- Workers and project owners cannot provide checker names, severities, + versions, or outcomes. Required reviewers: @@ -120,7 +138,8 @@ reuse/dedup, test delta. Human review focus: -Generated policy persistence/derivation choice and exact naming. +Async job boundaries, sufficiency severity behavior, and clarification request +shape. ### WS-POL-001-03: Submission Creation Uses Effective Policy diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md index 325f7c9..9febbe2 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md @@ -3,15 +3,27 @@ ## Accepted - `ProjectGuide` remains human-facing instruction. +- `ProjectGuide` is open-ended project material. It may be markdown, imported + documentation, URL-backed docs, examples, rubrics, repository docs, or any + project-specific material. - `SubmissionArtifactPolicy` is the machine-readable intake contract. -- Project owners provide project setup material in plain language; - they do not author `SubmissionArtifactPolicy` directly. +- Project owners provide open-ended project material and business terms; + they do not author or approve Workstream internal policy schema directly. +- `ProjectGuideSufficiencyAgent` evaluates whether the guide is sufficient for + submitters, reviewers, and Workstream quality control. +- `GuideSufficiencyReport.status` values are `passed`, `blocked`, and + `passed_with_warnings`. +- Guide sufficiency finding severities are `blocking_gap`, `warning`, and + `info`. +- `SubmissionArtifactPolicyDerivationAgent` derives + `ProjectSubmissionArtifactPolicy` after guide sufficiency passes. - Workstream derives `ProjectSubmissionArtifactPolicy` from project material, with internal agent assistance allowed, then requires approval by `admin` or `project_manager` before guide activation. - Workstream default submission artifact rules are non-bypassable. - `EffectiveSubmissionArtifactPolicy` is default plus project policy. -- `PreSubmitCheckerPolicy` is generated from effective policy. +- `PreSubmitCheckerPolicy` is generated from effective policy, persisted, and + locked to the project guide version. - Pre-submit checks block before submission creation. - Blocking pre-submit feedback is `pre_submission_checker_failed` with structured pass/fail/warning details; it is not `accept`, `needs_revision`, @@ -20,12 +32,26 @@ - Worker-facing task outcomes remain simple; internal routes stay internal. - Stored review decision values remain exactly `accept`, `needs_revision`, and `reject`. Display wording must not create new persisted tokens. +- `evidence_policy`, `required_files`, and `required_evidence` are transitional + fields to replace, not compatibility contracts to preserve. -## Pending Human Decisions +## Accepted Defaults -- Exact default Workstream submission artifact policy fields. -- Exact v0.1 project-owner intake checklist for deriving project policy. -- Whether generated pre-submit policy is persisted or derived on demand. -- Exact names for locked submission artifact policy version/hash fields. -- Compatibility plan for `ProjectGuide.evidence_policy`. -- Compatibility plan for task `required_files` and `required_evidence`. +- Workstream default pre-submit checks include packet shape, artifact manifest + presence, artifact hash validation, storage reference safety, forbidden + artifact blocking, required artifact presence, required evidence presence, + worker attestation validation, and low-quality/generated artifact warnings. +- Workstream default hard rules require production hashes shaped as + `sha256:<64 lowercase hex>`, safe relative artifact paths, no absolute paths, + no traversal paths, no raw signed URLs, no query-string storage refs, no local + filesystem paths, no credential/token-bearing refs, and no default-forbidden + artifacts such as `.env`, `.git`, private keys, secrets, tokens, and + `node_modules`. + +## Remaining Human Review Focus + +- Final review of persisted provenance field names for guide sufficiency + reports, project submission artifact policies, effective policy hashes, and + generated pre-submit checker policy snapshots. +- Final confirmation that Chunk 1 implements records/contracts/activation guard + only, while full async agent execution comes later. diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DISCOVERY.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DISCOVERY.md index 0eeca3c..f0e996d 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DISCOVERY.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DISCOVERY.md @@ -9,8 +9,9 @@ The architecture docs already lock the target model: ```text SubmissionArtifactPolicy +-> GuideSufficiencyReport -> EffectiveSubmissionArtifactPolicy --> generated PreSubmitCheckerPolicy +-> persisted and locked PreSubmitCheckerPolicy -> pre-submit checks before submission creation -> post-submit/internal checks after submission lock ``` @@ -25,11 +26,10 @@ The backend is still transitional: - Post-submit durable checks use registered checker names and locked checker policy. -The product ownership boundary is also not explicit enough yet. Project owners -should provide guide material, task examples, rubrics, payment inputs, and -plain-language artifact expectations. Workstream should derive the -machine-readable project submission artifact policy from that material, then -require approval by `admin` or `project_manager` before guide activation. +The product ownership boundary is now locked. Project owners provide open-ended +project guide material and business terms. Workstream runs asynchronous internal +agents to evaluate guide sufficiency and derive machine-readable policy. The +project owner does not approve Workstream's internal policy controls. ## Relevant Files/Modules @@ -82,11 +82,9 @@ require approval by `admin` or `project_manager` before guide activation. | Question | Why it matters | Needed before chunk? | |---|---|---| -| Exact default artifact rules | Defines non-bypassable Workstream intake behavior. | Yes, before implementation chunk 1 completes. | -| Exact project-owner intake checklist | Defines what a company must provide so Workstream can derive policy. | Yes, before implementation chunk 1 completes. | -| Whether `evidence_policy` stays as backward-compatible alias | Affects API compatibility and migration scope. | Yes, before migration chunk. | -| Exact policy version/hash field names | Prevents future schema drift. | Yes, before schema migration. | -| Whether generated `PreSubmitCheckerPolicy` is persisted or derived on read | Affects data model and audit proof. | Yes, before chunk 2. | +| Exact guide sufficiency report fields | Defines what the sufficiency agent proves before activation. | Yes, before implementation chunk 1 completes. | +| Exact policy provenance field names | Prevents future schema drift. | Yes, before schema migration. | +| Exact async agent execution shape | Affects background job orchestration. | No; chunk 1 can model records/contracts first. | ## Existing Conventions To Preserve diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md index 20163d9..55f3286 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md @@ -2,9 +2,11 @@ ## Problem Being Solved -Workstream currently understands the product direction for submission intake, but -the backend still carries transitional fields such as `evidence_policy`, +Workstream currently understands the product direction for submission intake, +but the backend still carries transitional fields such as `evidence_policy`, `required_files`, `required_evidence`, and broad checker-policy version locking. +Those fields are old v0.1 construction state. They will be replaced, not kept +as compatibility aliases. That is not strong enough for the system we are building. A project guide is human-facing instruction. It can explain expectations, examples, rubric, and @@ -22,6 +24,8 @@ ProjectGuide = human-facing instructions SubmissionArtifactPolicy = machine-readable intake contract Project owner material +-> ProjectGuideSufficiencyAgent +-> SubmissionArtifactPolicyDerivationAgent -> Workstream-derived ProjectSubmissionArtifactPolicy -> approval by admin or project_manager @@ -30,23 +34,30 @@ WorkstreamDefaultSubmissionArtifactPolicy = EffectiveSubmissionArtifactPolicy EffectiveSubmissionArtifactPolicy --> generated PreSubmitCheckerPolicy +-> persisted and locked PreSubmitCheckerPolicy ``` -Project owners provide project material: guide text or documentation links, -task inputs, expected outputs, examples, acceptance criteria, rejection -criteria, review rubric, skill expectations, base payout or payment policy -inputs, confidentiality constraints, and plain-language artifact expectations. -They do not author Workstream's machine-readable submission policy schema -directly. - -Workstream derives the project submission artifact policy from that material, -using internal agent assistance where useful. A Workstream actor with the -`admin` or `project_manager` role reviews and approves the derived policy -before guide activation. Workers submit draft -packet fields. Workstream decides required artifacts, evidence, hashes, storage -reference rules, forbidden artifacts, and blocking pre-submit feedback from the -effective policy. +Project owners provide open-ended project material: markdown, URLs, full +documentation, examples, rubrics, repository docs, task instructions, domain +requirements, business terms, base payout or payment policy inputs, or any +other project-specific source material. Workstream must not force every project +into one fixed intake checklist. A project guide can be a URL to a complete +documentation set if that is the right form for the project. + +Workstream runs asynchronous internal analysis on that material. The +`ProjectGuideSufficiencyAgent` checks whether the guide is sufficient for +submitters, reviewers, and Workstream quality control. Blocking guide gaps stop +activation and create clarification requests back to the project owner. Warnings +remain visible to the Workstream `admin` or `project_manager` and must be +acknowledged before activation. + +After sufficiency passes, the `SubmissionArtifactPolicyDerivationAgent` derives +the machine-readable project submission artifact policy. The project owner does +not approve this internal policy. A Workstream actor with the `admin` or +`project_manager` role approves the derived policy and activates the +guide-policy bundle. Workers submit draft packet fields. Workstream decides +required artifacts, evidence, hashes, storage reference rules, forbidden +artifacts, and blocking pre-submit feedback from the locked effective policy. ## Why Now @@ -71,10 +82,13 @@ After this initiative: - `SubmissionArtifactPolicy` is Workstream-derived from project material and approved by `admin` or `project_manager`, not authored directly by the project owner. +- `GuideSufficiencyReport` is a first-class record tied to a project guide + version. - Workstream default submission artifact rules are defined in code. - Project submission artifact policy cannot weaken Workstream defaults. - Effective submission artifact policy is computed deterministically. -- Generated pre-submit checker policy is derived from effective policy. +- Generated pre-submit checker policy is persisted and locked to the project + guide version. - Submission creation uses the generated pre-submit policy before a submission row is created. - Post-submit/internal checker policy remains separate. @@ -111,10 +125,10 @@ does not create a submission and must not use review decision values. ## Human Judgment Required - Approve the chunk sequence before implementation. -- Approve the exact Workstream default submission artifact rules. -- Approve the required project-owner intake material for v0.1 project setup. -- Approve naming for new persisted fields and policy version/hash fields. -- Approve any migration strategy that changes existing transitional fields. +- Confirm guide sufficiency severity names and report fields. +- Confirm persisted policy provenance field names. +- Confirm Chunk 1 remains records/contracts/activation guard only, not full + agent execution. ## Initial Risk Class diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md index f658f8f..1b3d538 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md @@ -4,10 +4,11 @@ Implement policy-driven submission intake in narrow slices. -First, add the policy foundation without changing the full submission runtime. -Then derive generated pre-submit policy. Then move submission creation to the -effective policy. Then split post-submit checker policy naming and provenance. -Finally, verify revision resubmission and real API flows. +First, add the guide-sufficiency and policy-bundle foundation without changing +the full submission runtime. Then add async guide analysis and derivation +execution. Then move submission creation to the locked pre-submit policy. Then +split post-submit checker policy naming and provenance. Finally, verify +revision resubmission and real API flows. ## Design Chosen @@ -15,36 +16,48 @@ The product model is: ```text ProjectGuide - human-facing instructions + open-ended human-facing project material -ProjectSubmissionArtifactPolicy - Workstream-derived, admin-or-project-manager-approved machine-readable intake rules +GuideSufficiencyReport + Workstream-owned assessment of whether the guide is sufficient WorkstreamDefaultSubmissionArtifactPolicy platform-owned, non-bypassable safety rules +ProjectSubmissionArtifactPolicy + Workstream-derived, admin-or-project-manager-approved machine-readable intake rules + EffectiveSubmissionArtifactPolicy deterministic merge of default + project policy PreSubmitCheckerPolicy - generated checker rules for draft packet intake + persisted and locked checker rules for draft packet intake PostSubmitCheckerPolicy durable checker rules for locked submission review readiness ``` -Project owners provide human-facing setup material. Workstream derives the -machine-readable project submission artifact policy from that material, then a -Workstream actor with the `admin` or `project_manager` role approves it. -Pre-submit checks run before submission -creation and do not create durable checker records. Post-submit/internal checks -run after submission lock and do create durable checker records. - -If no approved project submission artifact policy exists for the active guide, -guide activation fails and tasks using that guide cannot enter the ready worker -pipeline. The system must surface setup failure internally as task/project setup -incomplete rather than letting workers discover missing intake rules at submit -time. +Project owners provide open-ended project material. Workstream does not enforce +a universal checklist. `ProjectGuideSufficiencyAgent` reviews the guide and task +shape asynchronously. Blocking gaps stop activation and create clarification +requests for the project owner. Warnings can be accepted only by a Workstream +actor with the `admin` or `project_manager` role. + +`SubmissionArtifactPolicyDerivationAgent` derives machine-readable +`ProjectSubmissionArtifactPolicy` after guide sufficiency passes. A Workstream +actor with the `admin` or `project_manager` role approves the derived policy. +Workstream then computes the effective policy and persists the generated +`PreSubmitCheckerPolicy` snapshot/hash locked to the guide version. Pre-submit +checks run before submission creation and do not create durable checker records. +Post-submit/internal checks run after submission lock and do create durable +checker records. + +If no passing or acknowledged guide sufficiency report, approved project +submission artifact policy, effective policy hash, and persisted generated +pre-submit checker policy exist for the guide version, guide activation fails +and tasks using that guide cannot enter the ready worker pipeline. The system +must surface setup failure internally as task/project setup incomplete rather +than letting workers discover missing intake rules at submit time. ## Alternatives Considered @@ -72,6 +85,14 @@ Workstream schema. Workstream owns derivation of the machine-readable contract, and actors with the `admin` or `project_manager` role approve it before the project can accept ready tasks. +### Force every project owner through a fixed intake checklist + +Rejected because Workstream must support different project types. A guide may be +markdown, URL-backed docs, repository docs, rubric material, examples, or any +project-specific source material. Guide sufficiency is evaluated by Workstream +agents against the project and task shape instead of by forcing one universal +checklist. + ### Combine pre-submit and post-submit checker policy Rejected because pre-submit answers whether a packet can be submitted at all, @@ -82,9 +103,9 @@ while post-submit answers whether a locked submission can move to human review. - Auth/session: still only verifies external Flow authentication tokens. - Permission/policy: actors with the `admin` or `project_manager` role approve project policy setup; workers do not provide policy versions or checker names. -- Project-owner boundary: project owners provide guide material, - examples, rubrics, payment inputs, and artifact expectations in plain - language; Workstream turns that material into approved policy. +- Project-owner boundary: project owners provide open-ended guide material and + business terms; Workstream evaluates sufficiency, derives policy, and owns + internal controls. - Payment/execution: no payment or contribution records in this initiative. - Persistence/data: schema changes land through Alembic and async SQLAlchemy. - Presentation/API: backend-first; no frontend implementation. @@ -92,21 +113,26 @@ while post-submit answers whether a locked submission can move to human review. ## Rollout/Migration Strategy -1. Add dedicated policy model/API while keeping transitional fields readable. -2. Add the Workstream-owned derivation/approval boundary for project policy. -3. Compute effective policy in service code and validate defaults cannot weaken. -4. Generate pre-submit checker policy from effective policy. -5. Migrate submission creation to effective policy. -6. Split post-submit checker policy naming/provenance. -7. Retire or alias transitional `evidence_policy`, `required_files`, and - `required_evidence` usage after tests prove the new path. +1. Add dedicated guide sufficiency, submission artifact policy, effective + policy, and pre-submit policy records. +2. Replace transitional `evidence_policy`, `required_files`, and + `required_evidence` usage; no v0.1 compatibility alias is required. +3. Add the Workstream-owned derivation/approval boundary for project policy. +4. Compute effective policy in service code and validate defaults cannot weaken. +5. Persist generated pre-submit checker policy snapshot/hash for the guide + version. +6. Add async guide sufficiency and policy derivation execution. +7. Migrate submission creation to the locked generated pre-submit policy. +8. Split post-submit checker policy naming/provenance. ## Verification Strategy - Unit-level policy merge tests for default + project policy. -- Postgres-backed API tests for project policy creation and guide activation. -- Tests proving a guide cannot activate without an approved project submission - artifact policy. +- Postgres-backed API tests for guide sufficiency report, project policy + creation, generated pre-submit policy persistence, and guide activation. +- Tests proving a guide cannot activate without passing or acknowledged guide + sufficiency, approved project submission artifact policy, effective policy + hash, and persisted generated pre-submit checker policy. - Submission API tests proving blocking pre-submit failure creates no submission row, version, task transition, durable checker run, or submission-created audit. - Real API drill proving clean pass and `needs_revision` resubmission. @@ -129,5 +155,7 @@ CI integrity is required only for chunks that touch workflows or test tooling. ## Sequencing -Start with policy foundation. Do not start submission runtime rewiring until the -policy object, defaults, and merge rules are accepted. +Start with guide/policy bundle foundation. Do not start submission runtime +rewiring until the guide sufficiency report, project policy object, defaults, +effective policy hash, persisted generated pre-submit checker policy, and +activation guards are accepted. diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/RISKS.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/RISKS.md index 4525eed..6af01b9 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/RISKS.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/RISKS.md @@ -7,5 +7,6 @@ | Project owner schema burden | High | Project owners provide plain-language material; Workstream derives policy and actors with the `admin` or `project_manager` role approve it. | | Naming drift | High | Human review field names before migrations. | | Worker-facing internal route leakage | Medium | Keep `task_setup_blocked` and `checker_retry` internal; expose `needs_revision` only when worker action is needed. | -| Backward compatibility drift | Medium | Keep transitional fields explicit until replacement is proven. | +| Stale transitional field drift | Medium | Replace `evidence_policy`, `required_files`, and `required_evidence`; do not preserve them as v0.1 compatibility aliases. | +| Agent scope creep | Medium | Chunk 1 models records/contracts/activation guards; full async agent execution is a later chunk. | | Insufficient real API proof | High | Require Postgres-backed API tests and real API drill before closing the initiative. | diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md index c1ee0e6..2939375 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md @@ -2,7 +2,7 @@ ## Current Status -Planning +Planning PR open. ## Active Chunk @@ -12,7 +12,7 @@ Planning | Chunk | Status | Branch | PR | Notes | |---|---|---|---:|---| -| `WS-POL-001-01` | Draft contract | `codex/submission-artifact-policy-loop-plan` | - | Awaiting human approval before implementation. | +| `WS-POL-001-01` | Planning PR open | `codex/submission-artifact-policy-loop-plan` | 26 | Awaiting human approval before implementation. | | `WS-POL-001-02` | Planned | - | - | Starts after policy foundation lands. | | `WS-POL-001-03` | Planned | - | - | Moves submission creation to effective policy. | | `WS-POL-001-04` | Planned | - | - | Splits post-submit checker policy provenance. | @@ -22,13 +22,13 @@ Planning | Blocker | Owner | Next action | |---|---|---| -| Human approval of chunk sequence and first contract | User | Review this planning branch. | -| Exact default submission artifact policy fields | User + Codex | Confirm before implementation completes. | +| Human approval of chunk sequence and first contract | User | Review PR #26. | +| Persisted policy provenance field names | User + Codex | Confirm during PR #26 review. | ## Follow-Ups | Item | Source | Priority | |---|---|---| -| Migrate `evidence_policy` wording to `SubmissionArtifactPolicy` | Discovery | High | +| Replace `evidence_policy`, `required_files`, and `required_evidence` with `SubmissionArtifactPolicy` path | Discovery | High | | Split pre-submit and post-submit policy provenance fields | Discovery | High | | Add revision resubmission pre-submit proof | Discovery | High | diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md index dd5e637..bac6c42 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md @@ -1,4 +1,4 @@ -# Chunk Contract: WS-POL-001-01 - Submission Artifact Policy Foundation +# Chunk Contract: WS-POL-001-01 - Guide Policy Bundle Foundation ## Parent Initiative @@ -6,21 +6,24 @@ WS-POL-001 - Submission Artifact Policy Foundation ## Goal -Add first-class backend support for `SubmissionArtifactPolicy` without rewiring -submission creation or durable checker execution yet. +Add first-class backend support for guide sufficiency reports, +`SubmissionArtifactPolicy`, effective policy hashes, and persisted generated +`PreSubmitCheckerPolicy` snapshots without rewiring submission creation or +durable checker execution yet. ## Why This Chunk Exists The code still uses transitional `evidence_policy`, `required_files`, and -`required_evidence` fields. Before pre-submit checks can be generated from an -effective policy, Workstream needs a real policy object and non-bypassable -default policy validation. +`required_evidence` fields. Those fields are not compatibility contracts. They +must be replaced by the guide-policy bundle path before submission intake can be +deterministic. Project owners must not be asked to author the Workstream policy schema -directly. They provide project setup material in plain language; Workstream -derives project submission artifact policy from that material, and a project -actor with the `admin` or `project_manager` role approves it before guide -activation. +directly. They provide open-ended project guide material. Workstream records +guide sufficiency, derives project submission artifact policy, persists the +effective policy hash, persists the generated pre-submit checker policy +snapshot/hash, and a Workstream actor with the `admin` or `project_manager` role +approves the bundle before guide activation. ## Approved Plan Reference @@ -66,14 +69,22 @@ human review implementation - Routers only translate HTTP requests/responses and map domain errors. - Services own policy merge rules, Workstream default validation, guide - activation checks, Workstream-owned policy derivation boundaries, and - permission-aware orchestration. + sufficiency gating, guide activation checks, Workstream-owned policy + derivation boundaries, and permission-aware orchestration. - Repositories only persist and query policy records. - Schemas only define API input/output contracts and validation shape. +- Full async agent execution is not part of this chunk. This chunk models the + records/contracts and activation guard those agents will use. ## Acceptance Criteria - [ ] Dedicated `SubmissionArtifactPolicy` model/table exists. +- [ ] Dedicated `GuideSufficiencyReport` model/table exists. +- [ ] Guide sufficiency report records `passed`, `blocked`, or + `passed_with_warnings`. +- [ ] Blocking guide sufficiency findings prevent guide activation. +- [ ] Warning guide sufficiency findings require `admin` or `project_manager` + acknowledgement before guide activation. - [ ] Policy rows are scoped by `project_id` and `guide_version`. - [ ] Policy rows have a composite foreign key to `project_guides(project_id, version)`. - [ ] Pydantic input/output schemas exist for project submission artifact policy. @@ -91,8 +102,10 @@ human review implementation - [ ] Workstream default policy rejects raw signed URLs, query strings, local filesystem paths, credential-bearing references, and token-bearing storage references before persistence. - [ ] Workstream default policy blocks default-forbidden secret/token artifacts even when a project policy lists them as required. - [ ] Effective policy merge rejects project policy that weakens defaults. -- [ ] Existing `evidence_policy` transitional behavior is not silently broken. -- [ ] Postgres-backed tests cover create/update/activation/default-weakening cases. +- [ ] Effective submission artifact policy hash is persisted for the guide version. +- [ ] Generated `PreSubmitCheckerPolicy` snapshot/hash is persisted and locked to the guide version. +- [ ] Transitional `evidence_policy`, `required_files`, and `required_evidence` are replaced, not kept as compatibility aliases. +- [ ] Postgres-backed tests cover create/update/activation/default-weakening/guide-sufficiency/pre-submit-policy-locking cases. ## Verification Commands @@ -132,12 +145,10 @@ Conditional: ## Human Review Focus -- Are the policy field names precise enough? -- Is the project-owner intake checklist precise enough for Workstream to derive - policy without making project owners author internal schema? -- Are Workstream default rules complete enough for v0.1? -- Should `evidence_policy` remain a compatibility alias during migration? -- Should generated pre-submit policy be persisted in chunk 2 or derived on read? +- Are the guide sufficiency report fields precise enough? +- Are the persisted provenance field names precise enough? +- Does this chunk stay limited to records/contracts/activation guard, leaving + full async agent execution for the next chunk? ## Stop Conditions @@ -145,8 +156,8 @@ Stop and escalate if: - implementation needs to touch task/submission/checker runtime in this chunk - policy version/hash naming is unclear -- default artifact rules need product decision -- migration requires destructive data changes +- guide sufficiency severity naming is unclear +- migration requires preserving old transitional fields as compatibility aliases - CI/test weakening is required to pass - same blocker remains after 2 repair attempts - secrets or production data are needed diff --git a/docs/architecture_checker_framework.md b/docs/architecture_checker_framework.md index 6eb4b8c..457b23c 100644 --- a/docs/architecture_checker_framework.md +++ b/docs/architecture_checker_framework.md @@ -163,6 +163,7 @@ The deterministic chain is: ```text ProjectGuide +-> GuideSufficiencyReport -> ProjectSubmissionArtifactPolicy -> EffectiveSubmissionArtifactPolicy -> PreSubmitCheckerPolicy @@ -170,10 +171,17 @@ ProjectGuide -> Submission row only when blocking checks pass ``` -`ProjectGuide` is human-facing. `SubmissionArtifactPolicy` is machine-readable, -derived by Workstream from project owner material, and approved by a Workstream -actor with the `admin` or `project_manager` role. Workstream combines that -policy with the non-bypassable Workstream default submission artifact policy. +`ProjectGuide` is open-ended human-facing project material. Workstream first +persists a `GuideSufficiencyReport`. Blocking guide gaps stop activation and +create clarification requests for the project owner. Warnings require +acknowledgement by `admin` or `project_manager`. + +`SubmissionArtifactPolicy` is machine-readable, derived by Workstream from +project guide material after sufficiency passes or warnings are acknowledged, +and approved by a Workstream actor with the `admin` or `project_manager` role. +The project owner does not approve this internal policy. Workstream combines +that policy with the non-bypassable Workstream default submission artifact +policy. Workstream default submission artifact rules require: @@ -188,8 +196,9 @@ Workstream default submission artifact rules require: Project policy adds required artifacts, evidence requirements, stricter forbidden artifacts, stricter packaging rules, and project-specific attestation requirements. -The generated `PreSubmitCheckerPolicy` runs before Workstream creates a -submission. Blocking failures prevent submission creation and return +The generated `PreSubmitCheckerPolicy` is persisted, hashed, and locked to the +project guide version before workers submit packets. It runs before Workstream +creates a submission. Blocking failures prevent submission creation and return `pre_submission_checker_failed` with structured pass/fail/warning details. 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`, diff --git a/docs/architecture_data_model.md b/docs/architecture_data_model.md index 9bfcf67..9aa8070 100644 --- a/docs/architecture_data_model.md +++ b/docs/architecture_data_model.md @@ -13,6 +13,7 @@ Actor Project ProjectGuide + GuideSufficiencyReport SubmissionArtifactPolicy EffectiveSubmissionArtifactPolicy PreSubmitCheckerPolicy @@ -149,13 +150,20 @@ Fields: - `created_at` - `superseded_at` -The guide is versioned and human-facing. It contains project instructions, quality bar, examples, rubric, common rejection reasons, and links or summaries for approved policies. It may be markdown, an imported document, or a URL-backed guide. +The guide is versioned and human-facing. It contains project instructions, +quality bar, examples, rubric, common rejection reasons, and links or summaries +for approved policies. It may be markdown, an imported document, URL-backed +docs, repository docs, examples, rubrics, task instructions, or other +project-specific source material. Runtime enforcement uses machine-readable policies attached to the guide version. Workstream does not parse guide prose at submission time to decide which artifact checks to run. -Project owners provide setup material in plain language. Workstream derives -machine-readable project policy from that material, then a Workstream actor with -the `admin` or `project_manager` role approves it before the guide can activate. +Project owners provide open-ended setup material and business terms. Workstream +does not force every project owner through one universal intake checklist. +Workstream evaluates guide sufficiency, derives machine-readable project policy, +and owns the internal controls. A Workstream actor with the `admin` or +`project_manager` role approves the guide-policy bundle before the guide can +activate. Every task records the guide version active at creation or screening time before the task enters `READY`. Later source adapters must also lock the guide version during normalization before workers see the task. @@ -163,10 +171,47 @@ When a task is claimed or moved to `IN_PROGRESS`, its locked guide and policy co Material changes require a new guide version or policy version. Material changes include acceptance criteria, rejection criteria, reviewer rubric, output requirements, submission artifact policy, pre-submit checker generation rules, post-submit checker policy, review policy, revision policy, and payment policy. -Implementation note: the current v0.1 database has `ProjectGuide.evidence_policy`. That field is a transitional storage location for submission artifact requirements. The architecture source of truth is `SubmissionArtifactPolicy`. +Implementation note: the current v0.1 database has `ProjectGuide.evidence_policy`. +That field is old construction state. The architecture source of truth is +`SubmissionArtifactPolicy`, and the replacement path does not require a +compatibility alias. Implementation note: `ProjectGuide.required_submission_fields` is a legacy display summary. Submission validity is enforced by `EffectiveSubmissionArtifactPolicy`, not by project guide fields. +## GuideSufficiencyReport + +Fields: + +- `id` +- `project_id` +- `guide_version` +- `status` +- `findings` +- `source_material_refs` +- `agent_name` +- `agent_version` +- `created_at` +- `acknowledged_by_role` +- `acknowledged_by` +- `acknowledged_at` + +Status: + +- `passed` +- `blocked` +- `passed_with_warnings` + +Finding severity: + +- `blocking_gap` +- `warning` +- `info` + +`ProjectGuideSufficiencyAgent` creates this report asynchronously for a guide +version. Blocking gaps stop guide activation and create clarification requests +for the project owner. Warnings can be acknowledged only by a Workstream actor +with the `admin` or `project_manager` role before activation. + ## SubmissionArtifactPolicy Fields: @@ -185,7 +230,9 @@ Fields: - `required_attestation_terms` - `packaging_rules` - `created_by` -- `derivation_source` +- `sufficiency_report_id` +- `derivation_agent_name` +- `derivation_agent_version` - `source_material_refs` - `approval_status` - `approved_policy_hash` @@ -214,7 +261,9 @@ Example: "artifact_hash_algorithm": "sha256", "allowed_storage_schemes": ["local", "s3", "r2"], "forbidden_artifacts": ["secrets/**", ".env"], - "derivation_source": "workstream_agent", + "sufficiency_report_id": "guide-sufficiency:v1", + "derivation_agent_name": "SubmissionArtifactPolicyDerivationAgent", + "derivation_agent_version": "v1", "source_material_refs": ["project-guide:v1"], "approval_status": "approved", "approved_by": "flow-project-manager", @@ -225,9 +274,10 @@ Example: } ``` -Workstream derives this policy from project owner material. A Workstream actor -with the `admin` or `project_manager` role approves it. Workers do not supply -it. +Workstream derives this policy from project guide material after guide +sufficiency passes or warnings are acknowledged. A Workstream actor with the +`admin` or `project_manager` role approves it. Project owners and workers do not +supply or approve this internal policy schema. Project policy can add stricter requirements, but it cannot weaken Workstream's default submission artifact policy. @@ -242,9 +292,12 @@ WorkstreamDefaultSubmissionArtifactPolicy Fields: +- `id` - `project_id` - `guide_version` +- `version` - `policy_hash` +- `source_project_policy_hash` - `required_artifacts` - `required_evidence` - `artifact_manifest_required` @@ -253,22 +306,28 @@ Fields: - `allowed_storage_schemes` - `forbidden_artifacts` - `required_attestation_terms` +- `generated_from` - `generated_at` This policy is deterministic. It preserves Workstream defaults first and adds project-approved requirements. Duplicate rules collapse by canonical key. Any project rule that conflicts with Workstream defaults is a project setup defect. ## PreSubmitCheckerPolicy -Generated server-side from `EffectiveSubmissionArtifactPolicy`. +Generated server-side from `EffectiveSubmissionArtifactPolicy`, then persisted +and locked to the project guide version. Fields: +- `id` - `project_id` - `guide_version` +- `version` - `policy_hash` +- `effective_submission_artifact_policy_hash` - `checker_names` - `checker_configs` - `blocking_severities` +- `generated_from_policy_version` - `generated_at` The generated checker order is deterministic: diff --git a/docs/architecture_lifecycle_state_machine.md b/docs/architecture_lifecycle_state_machine.md index 4b7f3b1..c49c407 100644 --- a/docs/architecture_lifecycle_state_machine.md +++ b/docs/architecture_lifecycle_state_machine.md @@ -72,8 +72,10 @@ Required before entering: - task schema valid - project guide active +- GuideSufficiencyReport passed or warnings acknowledged - SubmissionArtifactPolicy approved -- generated PreSubmitCheckerPolicy available +- EffectiveSubmissionArtifactPolicy hash persisted +- generated PreSubmitCheckerPolicy persisted and locked - PostSubmitCheckerPolicy present - review policy present - revision policy present diff --git a/docs/architecture_lockdown.md b/docs/architecture_lockdown.md index c1402ba..ab993d4 100644 --- a/docs/architecture_lockdown.md +++ b/docs/architecture_lockdown.md @@ -77,11 +77,14 @@ Every active guide version must also have approved machine-readable policies: The guide may summarize or link to those policies, but the policies are the enforcement source. -Project owners provide setup material in plain language. Workstream derives +Project owners provide open-ended project material and business terms. +Workstream evaluates guide sufficiency, derives `ProjectSubmissionArtifactPolicy` from that material, and a Workstream actor -with the `admin` or `project_manager` role approves it before guide activation. +with the `admin` or `project_manager` role approves the internal policy bundle +before guide activation. Project owners do not approve Workstream's internal +submission policy schema. -`SubmissionArtifactPolicy` defines what a worker must submit. Workstream combines it with the non-bypassable Workstream default submission artifact policy to create the effective submission artifact policy. Workstream generates `PreSubmitCheckerPolicy` from that effective policy. +`SubmissionArtifactPolicy` defines what a worker must submit. Workstream combines it with the non-bypassable Workstream default submission artifact policy to create the effective submission artifact policy. Workstream generates, persists, hashes, and locks `PreSubmitCheckerPolicy` from that effective policy. Blocking pre-submit failures prevent submission creation. They return `pre_submission_checker_failed` with structured pass/fail/warning details and diff --git a/docs/current_system_data_flow.html b/docs/current_system_data_flow.html index c1bd13c..86aa0d7 100644 --- a/docs/current_system_data_flow.html +++ b/docs/current_system_data_flow.html @@ -471,10 +471,11 @@

Flow token enters API

2

Project guide and policy are prepared

-

The project owner provides guide material and artifact expectations. Workstream derives the submission artifact policy, then an admin or project_manager approves it before tasks can run.

+

The project owner provides open-ended guide material and business terms. Workstream runs guide sufficiency review, derives the submission artifact policy, then an admin or project_manager approves the internal policy bundle before tasks can run.

Project ProjectGuide v1 + GuideSufficiencyReport artifact/checker/review/revision/payment
@@ -482,7 +483,7 @@

Project guide and policy are prepared

3

Guide activation locks contract

-

Activation validates approved submission artifact policy, generated pre-submit policy, registered post-submit checker names, review decisions, revision states, and payment policy.

+

Activation validates a passing or acknowledged sufficiency report, approved submission artifact policy, effective policy hash, persisted generated pre-submit policy, registered post-submit checker names, review decisions, revision states, and payment policy.

status=active one active guide diff --git a/docs/decision_0003_project_guides_are_first_class.md b/docs/decision_0003_project_guides_are_first_class.md index 655b4af..411ad52 100644 --- a/docs/decision_0003_project_guides_are_first_class.md +++ b/docs/decision_0003_project_guides_are_first_class.md @@ -33,14 +33,16 @@ The submission artifact, checker, review, revision, and payment policies are gui Project guide activation requires the guide plus its required policy context before work can lock against it: +- guide sufficiency report - submission artifact policy +- effective submission artifact policy hash - generated pre-submit checker policy - post-submit checker policy - review policy - revision policy - payment policy -The Workstream-derived submission artifact policy defines what workers must submit. Project owners provide plain-language setup material; a Workstream actor with the `admin` or `project_manager` role approves the machine policy. Workstream combines that policy with non-bypassable Workstream default artifact rules to create the effective submission artifact policy. Workstream then generates the pre-submit checker policy from that effective policy. +The Workstream-derived submission artifact policy defines what workers must submit. Project owners provide open-ended project material and business terms. Workstream evaluates guide sufficiency, derives the machine policy, and a Workstream actor with the `admin` or `project_manager` role approves the internal policy bundle. Workstream combines that policy with non-bypassable Workstream default artifact rules to create the effective submission artifact policy. Workstream then generates, persists, hashes, and locks the pre-submit checker policy from that effective policy. Blocking pre-submit failures prevent submission creation. They do not create durable post-submit checker runs and they do not create human review decisions. 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 41fe7b9..d1eb150 100644 --- a/docs/decision_0011_submission_artifact_policy_drives_pre_submit.md +++ b/docs/decision_0011_submission_artifact_policy_drives_pre_submit.md @@ -6,7 +6,10 @@ Accepted ## Context -Project guides are human-facing. They explain the project, task expectations, examples, reviewer rubric, and quality bar. +Project guides are human-facing. They explain the project, task expectations, +examples, reviewer rubric, and quality bar. A guide can be markdown, imported +documentation, URL-backed docs, repository docs, examples, rubrics, task +instructions, or other project-specific source material. Submission intake needs a deterministic machine contract. If artifact requirements live only as guide prose, each project can drift into a different interpretation of what a valid submission packet must contain. @@ -14,18 +17,27 @@ Workstream also needs platform-owned default submission safety rules that no pro ## Decision -Every active project guide version must have an approved `SubmissionArtifactPolicy`. +Every active project guide version must have a complete guide-policy bundle: -Project owners provide project setup material in plain language: project purpose, -guide material, task examples, expected outputs, acceptance criteria, rejection -criteria, review rubric, required skills, confidentiality constraints, base -payout or payment policy inputs, and artifact expectations. They do not author -Workstream's machine-readable policy schema directly. +- passing or acknowledged `GuideSufficiencyReport` +- approved `ProjectSubmissionArtifactPolicy` +- persisted `EffectiveSubmissionArtifactPolicy` hash +- persisted generated `PreSubmitCheckerPolicy` snapshot/hash -Workstream derives `ProjectSubmissionArtifactPolicy` from that material, using -internal agent assistance where useful. A Workstream actor with the `admin` or -`project_manager` role must review and approve the derived policy before guide -activation. +Project owners provide open-ended project material in plain language. Workstream +must not force every project owner through one universal intake checklist. + +`ProjectGuideSufficiencyAgent` evaluates whether the guide is sufficient for +submitters, reviewers, and Workstream quality control. Blocking guide gaps stop +activation and create clarification requests back to the project owner. Warnings +remain visible to Workstream actors with the `admin` or `project_manager` role +and must be acknowledged before activation. + +`SubmissionArtifactPolicyDerivationAgent` derives +`ProjectSubmissionArtifactPolicy` from the guide material after sufficiency +passes or warnings are acknowledged. The project owner does not approve this +internal policy. A Workstream actor with the `admin` or `project_manager` role +reviews and approves the derived policy before guide activation. `SubmissionArtifactPolicy` is the Workstream-derived, admin-or-project-manager-approved machine-readable contract for worker submissions. It defines: @@ -55,9 +67,13 @@ EffectiveSubmissionArtifactPolicy = + ProjectSubmissionArtifactPolicy ``` -Workstream generates `PreSubmitCheckerPolicy` from the effective submission artifact policy. +Workstream generates and persists `PreSubmitCheckerPolicy` from the effective +submission artifact policy. -`PreSubmitCheckerPolicy` is not manually edited by workers and is not supplied by clients. Workers submit only draft packet fields. They do not choose checker names, policy versions, blocking rules, severities, or outcomes. +`PreSubmitCheckerPolicy` is locked to the project guide version. It is not +derived on read, manually edited by workers, or supplied by clients. Workers +submit only draft packet fields. They do not choose checker names, policy +versions, blocking rules, severities, or outcomes. Blocking pre-submit failures prevent submission creation. When blocking pre-submit checks fail: @@ -110,6 +126,8 @@ Positive: Tradeoff: -- project setup must approve one more explicit policy object -- existing `evidence_policy`, `required_files`, and `required_evidence` wording must be migrated toward `SubmissionArtifactPolicy` +- project setup must approve one more explicit Workstream-owned policy bundle +- existing `evidence_policy`, `required_files`, and `required_evidence` wording + must be replaced by `SubmissionArtifactPolicy`; no v0.1 compatibility alias + is required - post-submit checker policy must remain separate from generated pre-submit checker policy diff --git a/docs/glossary.md b/docs/glossary.md index ebbe297..af6c430 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -10,7 +10,11 @@ A configured work program with its own human-facing guide, submission artifact p ## Project Owner -The external or internal organization that provides project setup material in plain language: project purpose, guide material, examples, expected outputs, acceptance criteria, rejection criteria, review rubric, required skills, confidentiality constraints, base payout or payment policy inputs, and artifact expectations. The project owner does not author Workstream's machine-readable policy schema directly. +The external or internal organization that provides open-ended project material +and business terms. That material can be markdown, URL-backed documentation, +repository docs, examples, rubrics, task instructions, base payout or payment +policy inputs, or other project-specific source material. The project owner +does not author or approve Workstream's machine-readable internal policy schema. ## Source @@ -24,9 +28,24 @@ A future external task source that can submit tasks into Workstream through an a The human-facing operating guide for a project. It contains the project instructions, quality bar, task examples, reviewer rubric, common rejection reasons, and links or summaries for the approved policies. A project guide may be markdown, an imported document, or a URL-backed guide, but runtime enforcement uses approved machine-readable policies attached to the guide version. +## Guide Sufficiency Report + +The Workstream-owned record produced by `ProjectGuideSufficiencyAgent` for a +project guide version. It records whether the guide passed, is blocked by gaps, +or passed with warnings that an `admin` or `project_manager` must acknowledge +before activation. + ## Submission Artifact Policy -The Workstream-derived, admin-or-project-manager-approved machine-readable contract for what a worker must submit. It is derived from project owner material, reviewed by a Workstream actor with the `admin` or `project_manager` role, and attached to a project guide version. It defines required artifacts, evidence requirements, artifact hash requirements, allowed storage reference forms, forbidden artifacts, attestation requirements, and project-specific packaging rules. It can add or tighten requirements, but it cannot weaken Workstream's default submission artifact rules. +The Workstream-derived, admin-or-project-manager-approved machine-readable +contract for what a worker must submit. It is derived from open-ended project +guide material after guide sufficiency passes or warnings are acknowledged, +reviewed by a Workstream actor with the `admin` or `project_manager` role, and +attached to a project guide version. It defines required artifacts, evidence +requirements, artifact hash requirements, allowed storage reference forms, +forbidden artifacts, attestation requirements, and project-specific packaging +rules. It can add or tighten requirements, but it cannot weaken Workstream's +default submission artifact rules. ## Effective Submission Artifact Policy @@ -34,7 +53,7 @@ The deterministic merge of Workstream's default submission artifact policy and t ## Pre-Submit Checker Policy -The server-generated checker matrix produced from the effective submission artifact policy. It runs before Workstream creates a submission row or submission version. Blocking failures return `pre_submission_checker_failed` with structured pass/fail/warning details, prevent submission creation, and do not return review decision values: `accept`, `needs_revision`, or `reject`. +The server-generated checker matrix produced from the effective submission artifact policy, persisted with a hash, and locked to the project guide version. It runs before Workstream creates a submission row or submission version. Blocking failures return `pre_submission_checker_failed` with structured pass/fail/warning details, prevent submission creation, and do not return review decision values: `accept`, `needs_revision`, or `reject`. ## pre_submission_checker_failed diff --git a/docs/operations_workspace_packet_convention.md b/docs/operations_workspace_packet_convention.md index aeb4403..3831c73 100644 --- a/docs/operations_workspace_packet_convention.md +++ b/docs/operations_workspace_packet_convention.md @@ -8,10 +8,13 @@ Workstream does not need to own the execution workspace, but it must define what ## Project-Level Convention -Every project has an approved `SubmissionArtifactPolicy` derived by Workstream -from project owner material: +Every project has a guide-version policy bundle derived by Workstream from +open-ended project material: ```text +GuideSufficiencyReport +EffectiveSubmissionArtifactPolicy +PreSubmitCheckerPolicy required_artifacts required_evidence allowed_artifact_types @@ -65,7 +68,7 @@ A packet is not ready unless: Some projects need final work in a paste-ready form. Others need a zip, artifact bundle, markdown packet, or review file. -The project guide explains the canonical form to humans. The approved `SubmissionArtifactPolicy` enforces the artifact, evidence, hash, and packaging rules. Project owners do not author this machine policy schema directly. +The project guide explains the canonical form to humans. The approved `SubmissionArtifactPolicy` and persisted `PreSubmitCheckerPolicy` enforce the artifact, evidence, hash, and packaging rules. Project owners do not author or approve this machine policy schema directly. ## Why This Matters diff --git a/docs/product_first_user_flows.md b/docs/product_first_user_flows.md index 1ddc3a7..a655e38 100644 --- a/docs/product_first_user_flows.md +++ b/docs/product_first_user_flows.md @@ -5,21 +5,25 @@ The first user flows prove that Workstream can run real work from intake to acce ## Flow 1: Admin Creates A Project 1. Admin creates project. -2. Project owner provides guide material, examples, expected outputs, review rubric, artifact expectations, and payment policy inputs. +2. Project owner provides open-ended guide material and business terms. 3. Admin or project_manager adds the guide. -4. Workstream derives project submission artifact policy from the project owner material. -5. Admin or project_manager reviews and approves the submission artifact policy. -6. Workstream generates pre-submit checker policy. -7. Admin or project_manager enables post-submit checker policy. -8. Admin or project_manager enables review policy. -9. Admin or project_manager enables revision policy. -10. Admin or project_manager enables payment policy. -11. Project becomes active. +4. Workstream runs `ProjectGuideSufficiencyAgent` against the guide version. +5. Blocking sufficiency gaps create clarification requests for the project owner. +6. Admin or project_manager acknowledges non-blocking sufficiency warnings. +7. Workstream runs `SubmissionArtifactPolicyDerivationAgent`. +8. Admin or project_manager reviews and approves the derived submission artifact policy. +9. Workstream persists the effective submission artifact policy hash. +10. Workstream persists the generated pre-submit checker policy snapshot/hash. +11. Admin or project_manager enables post-submit checker policy. +12. Admin or project_manager enables review policy. +13. Admin or project_manager enables revision policy. +14. Admin or project_manager enables payment policy. +15. Project becomes active. Acceptance: -- Project cannot become active without guide, base amount, submission artifact policy, generated pre-submit checker policy, post-submit checker policy, review policy, revision policy, and payment policy. -- Submission artifact policy is Workstream-derived and approved by `admin` or `project_manager`; project owners do not author the machine policy schema directly. +- Project cannot become active without guide, base amount, passed or acknowledged guide sufficiency report, submission artifact policy, effective submission artifact policy hash, generated pre-submit checker policy snapshot/hash, post-submit checker policy, review policy, revision policy, and payment policy. +- Submission artifact policy is Workstream-derived and approved by `admin` or `project_manager`; project owners do not author or approve the machine policy schema directly. - Submission artifact, checker, review, revision, and payment policies are visible on the project page. ## Flow 2: Operator Creates A Task diff --git a/docs/spec_chunk_3_project_guide_foundation.md b/docs/spec_chunk_3_project_guide_foundation.md index 64e5785..14f7325 100644 --- a/docs/spec_chunk_3_project_guide_foundation.md +++ b/docs/spec_chunk_3_project_guide_foundation.md @@ -45,21 +45,26 @@ Architecture target: - `projects` - `project_guides` +- `guide_sufficiency_reports` - `submission_artifact_policies` +- `effective_submission_artifact_policies` +- `pre_submit_checker_policies` - `checker_policies` - `review_policies` - `revision_policies` - `payment_policies` -Current v0.1 implementation note: the first project-guide foundation stores submission artifact requirements in `ProjectGuide.evidence_policy`. That is transitional and maps to `SubmissionArtifactPolicy` until the dedicated table/API migration is implemented. +Current v0.1 implementation note: the first project-guide foundation stores submission artifact requirements in `ProjectGuide.evidence_policy`. That is old construction state. The target replacement is `SubmissionArtifactPolicy`; no compatibility alias is required. The guide version is the join key for the guide-specific policies. Project guide activation requires: - guide is still draft +- guide sufficiency report is passed or warnings are acknowledged by `admin` or `project_manager` - submission artifact policy exists for the guide version -- generated pre-submit checker policy exists for the guide version +- effective submission artifact policy hash exists for the guide version +- generated pre-submit checker policy snapshot/hash exists for the guide version - post-submit checker policy exists for the guide version - review policy exists for the guide version - revision policy exists for the guide version @@ -95,9 +100,9 @@ EffectiveSubmissionArtifactPolicy = + ProjectSubmissionArtifactPolicy ``` -Workstream generates pre-submit checker policy from the effective submission artifact policy. Blocking pre-submit failures prevent submission creation. +Workstream generates, persists, hashes, and locks pre-submit checker policy from the effective submission artifact policy. Blocking pre-submit failures prevent submission creation. -Implementation note: the first v0.1 schema stored this as `ProjectGuide.evidence_policy`. That field is transitional and maps to submission artifact requirements until the dedicated policy table/API is implemented. +Implementation note: the first v0.1 schema stored this as `ProjectGuide.evidence_policy`. That field is old construction state and is replaced by the dedicated policy table/API path. ## API Impact diff --git a/docs/template_project_guide.md b/docs/template_project_guide.md index 59f5dae..4c7be74 100644 --- a/docs/template_project_guide.md +++ b/docs/template_project_guide.md @@ -116,10 +116,11 @@ Every active guide version must have: Artifact requirements shown to workers are derived from the approved `SubmissionArtifactPolicy`. The guide may summarize those requirements, but the policy is the enforcement source. -Project owners provide this guide material and artifact expectations in -plain language. Workstream derives `ProjectSubmissionArtifactPolicy` from that -material, and a Workstream actor with the `admin` or `project_manager` role -approves it before guide activation. +Project owners provide open-ended guide material and business terms in plain +language. Workstream evaluates guide sufficiency, derives +`ProjectSubmissionArtifactPolicy` from that material, and a Workstream actor +with the `admin` or `project_manager` role approves the internal policy bundle +before guide activation. ## Known Checker Blind Spots diff --git a/docs/template_submission_artifact_policy.md b/docs/template_submission_artifact_policy.md index 7b54442..442c675 100644 --- a/docs/template_submission_artifact_policy.md +++ b/docs/template_submission_artifact_policy.md @@ -14,29 +14,36 @@ ## Source Material -Project owners provide setup material in plain language. Workstream derives this -policy from that material; project owners do not author the machine-readable -schema directly. - -Required project-owner intake material: - -- project purpose: -- guide material or documentation references: -- task inputs: -- expected outputs: -- examples of good submissions: -- examples of bad submissions: -- acceptance criteria: -- rejection criteria: -- review rubric: -- required skills: -- confidentiality constraints: -- base payout or payment policy inputs: -- artifact expectations: +Project owners provide open-ended project material and business terms. +Workstream derives this policy from that material after guide sufficiency passes +or warnings are acknowledged. Project owners do not author or approve the +machine-readable Workstream policy schema directly. + +Source material refs: + +- project guide version: +- imported document refs: +- URL-backed documentation refs: +- repository documentation refs: +- task example refs: +- rubric refs: +- business term refs: + +## Guide Sufficiency + +- sufficiency report id: +- sufficiency status: `passed | blocked | passed_with_warnings` +- finding severities used: `blocking_gap | warning | info` +- warnings acknowledged by role: `admin | project_manager` +- warnings acknowledged by actor: +- warnings acknowledged at: ## Approval Provenance - derivation source: `manual | workstream_agent | import_adapter` +- derivation agent name: +- derivation agent version: +- sufficiency report id: - source material refs: - approval status: `draft | approved | superseded` - approved policy hash: @@ -129,6 +136,13 @@ WorkstreamDefaultSubmissionArtifactPolicy Generated pre-submit checks run before submission creation. Blocking failures create no submission row, no submission version, no task transition to `submitted`, and no submission-created audit event. +Generated policy lock: + +- generated pre-submit checker policy version: +- generated pre-submit checker policy hash: +- effective submission artifact policy hash: +- locked guide version: + Blocking failures return `pre_submission_checker_failed` with structured pass/fail/warning details. They do not return review decision values: `accept`, `needs_revision`, or `reject`. From 0c73c3254139165d317c480f099d989d64e71b2c Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Tue, 23 Jun 2026 12:15:37 +0100 Subject: [PATCH 09/37] Address policy planning review findings --- .agent-loop/LOOP_STATE.md | 6 +-- .../CHUNK_MAP.md | 46 +++++++++++++++++++ .../INTENT.md | 6 +++ .../PLAN.md | 12 +++++ ...1-submission-artifact-policy-foundation.md | 11 ++++- docs/architecture_checker_framework.md | 4 +- docs/architecture_data_model.md | 2 + docs/architecture_lockdown.md | 4 +- docs/current_system_data_flow.html | 2 +- docs/glossary.md | 5 ++ docs/operations_project_operating_manual.md | 10 +++- docs/spec_chunk_3_project_guide_foundation.md | 2 +- ...ec_chunk_5_submission_packet_foundation.md | 4 +- docs/spec_chunk_6_checker_contract_records.md | 5 +- docs/template_project_guide.md | 2 + docs/template_submission_artifact_policy.md | 6 ++- 16 files changed, 113 insertions(+), 14 deletions(-) diff --git a/.agent-loop/LOOP_STATE.md b/.agent-loop/LOOP_STATE.md index 9681ba0..047648f 100644 --- a/.agent-loop/LOOP_STATE.md +++ b/.agent-loop/LOOP_STATE.md @@ -7,8 +7,8 @@ - Branch: `codex/submission-artifact-policy-loop-plan` - Status: intent, discovery, plan, chunk map, and first chunk contract drafted; implementation has not started - Merge commit: none for this initiative -- Reviewed code SHA: pending -- Current gate: awaiting human review of plan and first chunk contract; backend implementation is not approved +- Reviewed code SHA: pending refresh after latest internal-review fixes +- Current gate: internal review evidence refresh before human review of plan and first chunk contract; backend implementation is not approved - Next chunk: inactive until `WS-POL-001-01` is approved and completed ## Operating Rule @@ -30,4 +30,4 @@ behavior. - PR #23 merged into `main` on 2026-06-20. - PR #24 updated post-merge loop memory on `main`. - PR #25 added Terminal Benchmark example material under `examples/`. -- Current planning branch has no internal review evidence yet. +- Current planning branch has internal review evidence at `.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md`; evidence is being refreshed for the latest reviewed revision. diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md index 88e8ab9..b6e1789 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md @@ -11,6 +11,9 @@ `ProjectGuideSufficiencyAgent` and `SubmissionArtifactPolicyDerivationAgent` outputs to create the locked policy bundle. +- Project owner material is untrusted input. Implementation chunks must reject + unsafe source refs and prevent guide text or imported docs from granting tool + authority or weakening Workstream defaults. ## Chunks @@ -71,9 +74,21 @@ Acceptance criteria: - Guide activation requires passing or acknowledged guide sufficiency, approved submission artifact policy, effective policy hash, and persisted generated pre-submit checker policy. +- Project-owner source refs are sanitized and cannot contain signed URLs, + query-bearing refs, credential-bearing refs, or local filesystem paths. +- Embedded instructions in guide material cannot grant tool authority or weaken + Workstream default policy. - Transitional `evidence_policy`, `required_files`, and `required_evidence` are replaced, not preserved as compatibility aliases. +Verification: + +- Postgres-backed FastAPI/API tests cover policy create/update, guide + sufficiency activation blocking, warning acknowledgement, default weakening + rejection, source-ref sanitization, and pre-submit policy locking. +- Unit/service tests may cover deterministic merge helpers, but API-visible + behavior must be proven through the FastAPI path. + Required reviewers: senior engineering, QA/test, security/auth, product/ops, architecture, docs, @@ -128,9 +143,20 @@ Acceptance criteria: - `SubmissionArtifactPolicyDerivationAgent` runs async after sufficiency passes or warnings are acknowledged. - Derived policy cannot weaken Workstream defaults. +- Malicious guide text, embedded prompt-injection instructions, and unsafe + source refs cannot influence agent authority, fetch behavior, or default + policy strength. - Workers and project owners cannot provide checker names, severities, versions, or outcomes. +Verification: + +- Postgres-backed async tests cover sufficiency report creation, blocking + clarification requests, warning acknowledgement, derivation job output, unsafe + source-ref rejection, and default weakening rejection. +- Background execution tests prove jobs are async and idempotent for a guide + version. + Required reviewers: senior engineering, QA/test, security/auth, product/ops, architecture, docs, @@ -183,6 +209,12 @@ Acceptance criteria: structured pass/fail/warning details, not review decision values. - Passing pre-submit creates a submission stamped with locked policy context. +Verification: + +- Postgres-backed FastAPI/API tests cover clean submission, blocking pre-submit + failure, no-row/no-version/no-transition/no-durable-checker side effects, and + stamped locked policy context. + Required reviewers: senior engineering, QA/test, security/auth, product/ops, architecture, docs, @@ -235,6 +267,12 @@ Acceptance criteria: - Pre-submit feedback does not create durable checker records. - API responses do not expose internal-only routes to workers. +Verification: + +- Postgres-backed checker tests cover pre-submit feedback without durable + `CheckerRun`, post-submit `CheckerRun` creation against locked + `PostSubmitCheckerPolicy`, and worker-facing response filtering. + Required reviewers: senior engineering, QA/test, security/auth, product/ops, architecture, docs, @@ -289,6 +327,14 @@ Acceptance criteria: - Real API drill covers clean pass, blocking pre-submit, post-submit `needs_revision`, and fixed resubmission. +Verification: + +- Real API drill runs against Postgres and covers clean pass, blocking + pre-submit failure, post-submit checker-caused `needs_revision`, fixed + resubmission, immutable older submissions, and locked policy context. +- Postgres-backed tests prove replacement submission versioning and + `outcome_source` separation. + Required reviewers: senior engineering, QA/test, security/auth, product/ops, architecture, docs, diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md index 55f3286..2ddfabc 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md @@ -44,6 +44,12 @@ other project-specific source material. Workstream must not force every project into one fixed intake checklist. A project guide can be a URL to a complete documentation set if that is the right form for the project. +All project-owner material is untrusted input. Guide text, imported docs, URLs, +repository docs, and examples cannot grant tool authority, override Workstream +policy, weaken default checks, or instruct internal agents to ignore their +system rules. Source references must be sanitized before persistence and fetched +only through approved adapters or allowlisted retrieval paths. + Workstream runs asynchronous internal analysis on that material. The `ProjectGuideSufficiencyAgent` checks whether the guide is sufficient for submitters, reviewers, and Workstream quality control. Blocking guide gaps stop diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md index 1b3d538..a70f917 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md @@ -43,6 +43,12 @@ shape asynchronously. Blocking gaps stop activation and create clarification requests for the project owner. Warnings can be accepted only by a Workstream actor with the `admin` or `project_manager` role. +Project owner material is always treated as untrusted data. Internal agents must +not execute embedded instructions from guide text, URLs, repository docs, or +examples. Fetching source material must use approved adapters or allowlisted +retrieval paths, reject signed URLs, query-bearing refs, credential-bearing refs, +and local filesystem paths, and persist only sanitized source refs. + `SubmissionArtifactPolicyDerivationAgent` derives machine-readable `ProjectSubmissionArtifactPolicy` after guide sufficiency passes. A Workstream actor with the `admin` or `project_manager` role approves the derived policy. @@ -106,6 +112,10 @@ while post-submit answers whether a locked submission can move to human review. - Project-owner boundary: project owners provide open-ended guide material and business terms; Workstream evaluates sufficiency, derives policy, and owns internal controls. +- Source-material security: project-owner docs, URLs, examples, and repository + docs are untrusted input; embedded tool instructions, prompt-injection text, + credential-bearing refs, signed URLs, query-bearing refs, and local filesystem + paths cannot become policy authority. - Payment/execution: no payment or contribution records in this initiative. - Persistence/data: schema changes land through Alembic and async SQLAlchemy. - Presentation/API: backend-first; no frontend implementation. @@ -133,6 +143,8 @@ while post-submit answers whether a locked submission can move to human review. - Tests proving a guide cannot activate without passing or acknowledged guide sufficiency, approved project submission artifact policy, effective policy hash, and persisted generated pre-submit checker policy. +- Tests proving malicious or credential-bearing source material cannot weaken + Workstream defaults, grant tool authority, or persist unsafe source refs. - Submission API tests proving blocking pre-submit failure creates no submission row, version, task transition, durable checker run, or submission-created audit. - Real API drill proving clean pass and `needs_revision` resubmission. diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md index bac6c42..7a117e1 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md @@ -25,6 +25,11 @@ effective policy hash, persists the generated pre-submit checker policy snapshot/hash, and a Workstream actor with the `admin` or `project_manager` role approves the bundle before guide activation. +Project owner material is untrusted input. Guide text, URLs, repository docs, +examples, and imported documents cannot grant tool authority, override +Workstream rules, or weaken default checks. Source refs must be sanitized before +persistence. + ## Approved Plan Reference - INTENT: `.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md` @@ -85,6 +90,10 @@ human review implementation - [ ] Blocking guide sufficiency findings prevent guide activation. - [ ] Warning guide sufficiency findings require `admin` or `project_manager` acknowledgement before guide activation. +- [ ] Project-owner source refs are sanitized and reject signed URLs, + query-bearing refs, credential-bearing refs, and local filesystem paths. +- [ ] Embedded instructions in guide material cannot grant tool authority or + weaken Workstream default policy. - [ ] Policy rows are scoped by `project_id` and `guide_version`. - [ ] Policy rows have a composite foreign key to `project_guides(project_id, version)`. - [ ] Pydantic input/output schemas exist for project submission artifact policy. @@ -105,7 +114,7 @@ human review implementation - [ ] Effective submission artifact policy hash is persisted for the guide version. - [ ] Generated `PreSubmitCheckerPolicy` snapshot/hash is persisted and locked to the guide version. - [ ] Transitional `evidence_policy`, `required_files`, and `required_evidence` are replaced, not kept as compatibility aliases. -- [ ] Postgres-backed tests cover create/update/activation/default-weakening/guide-sufficiency/pre-submit-policy-locking cases. +- [ ] Postgres-backed FastAPI/API tests cover create/update/activation/default-weakening/guide-sufficiency/source-ref-sanitization/pre-submit-policy-locking cases. ## Verification Commands diff --git a/docs/architecture_checker_framework.md b/docs/architecture_checker_framework.md index 457b23c..d52153d 100644 --- a/docs/architecture_checker_framework.md +++ b/docs/architecture_checker_framework.md @@ -231,8 +231,8 @@ Examples: ```text Draft packet -> load locked task context --> compute EffectiveSubmissionArtifactPolicy --> generate PreSubmitCheckerPolicy +-> load locked EffectiveSubmissionArtifactPolicy hash +-> load locked PreSubmitCheckerPolicy snapshot/hash -> run pre-submit intake checks -> create Submission only when blocking pre-submit checks pass -> lock submission diff --git a/docs/architecture_data_model.md b/docs/architecture_data_model.md index 9aa8070..6357fad 100644 --- a/docs/architecture_data_model.md +++ b/docs/architecture_data_model.md @@ -266,6 +266,8 @@ Example: "derivation_agent_version": "v1", "source_material_refs": ["project-guide:v1"], "approval_status": "approved", + "approved_policy_hash": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "approved_by_role": "project_manager", "approved_by": "flow-project-manager", "approved_at": "2026-06-22T12:00:00Z", "packaging_rules": { diff --git a/docs/architecture_lockdown.md b/docs/architecture_lockdown.md index ab993d4..2742ae9 100644 --- a/docs/architecture_lockdown.md +++ b/docs/architecture_lockdown.md @@ -68,7 +68,9 @@ Every project guide is human-facing. It must explain: Every active guide version must also have approved machine-readable policies: +- guide sufficiency report - submission artifact policy +- effective submission artifact policy hash - generated pre-submit checker policy - post-submit checker policy - review policy @@ -84,7 +86,7 @@ with the `admin` or `project_manager` role approves the internal policy bundle before guide activation. Project owners do not approve Workstream's internal submission policy schema. -`SubmissionArtifactPolicy` defines what a worker must submit. Workstream combines it with the non-bypassable Workstream default submission artifact policy to create the effective submission artifact policy. Workstream generates, persists, hashes, and locks `PreSubmitCheckerPolicy` from that effective policy. +`SubmissionArtifactPolicy` defines what a worker must submit. Workstream combines it with the non-bypassable Workstream default submission artifact policy to create the effective submission artifact policy. Workstream persists the effective policy hash, then generates, persists, hashes, and locks `PreSubmitCheckerPolicy` from that effective policy. Blocking pre-submit failures prevent submission creation. They return `pre_submission_checker_failed` with structured pass/fail/warning details and diff --git a/docs/current_system_data_flow.html b/docs/current_system_data_flow.html index 86aa0d7..f12bbde 100644 --- a/docs/current_system_data_flow.html +++ b/docs/current_system_data_flow.html @@ -483,7 +483,7 @@

Project guide and policy are prepared

3

Guide activation locks contract

-

Activation validates a passing or acknowledged sufficiency report, approved submission artifact policy, effective policy hash, persisted generated pre-submit policy, registered post-submit checker names, review decisions, revision states, and payment policy.

+

Activation validates a passing or acknowledged sufficiency report, approved submission artifact policy, effective policy hash, persisted generated pre-submit policy, registered post-submit checker names, review policy allowed decisions, revision states, and payment policy.

status=active one active guide diff --git a/docs/glossary.md b/docs/glossary.md index af6c430..0cf38ae 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -47,6 +47,11 @@ forbidden artifacts, attestation requirements, and project-specific packaging rules. It can add or tighten requirements, but it cannot weaken Workstream's default submission artifact rules. +## Project Submission Artifact Policy + +The project-specific `SubmissionArtifactPolicy` attached to one project guide +version before Workstream merges it with default submission artifact policy. + ## Effective Submission Artifact Policy The deterministic merge of Workstream's default submission artifact policy and the project-approved submission artifact policy. Workstream computes this effective policy before pre-submit checks run. diff --git a/docs/operations_project_operating_manual.md b/docs/operations_project_operating_manual.md index a016604..69df2f6 100644 --- a/docs/operations_project_operating_manual.md +++ b/docs/operations_project_operating_manual.md @@ -9,7 +9,9 @@ Every project has: - active guide - queue owner - reviewer owner +- guide sufficiency report - submission artifact policy +- effective submission artifact policy hash - generated pre-submit checker policy - post-submit checker policy - review policy @@ -30,7 +32,9 @@ Before releasing tasks: - allowed task types listed - required task fields listed - project owner setup material captured +- guide sufficiency report passed or warnings acknowledged by `admin` or `project_manager` - submission artifact policy derived by Workstream and approved by `admin` or `project_manager` +- effective submission artifact policy hash persisted - generated pre-submit checker policy created from the effective submission artifact policy - post-submit checker policy attached - review policy attached @@ -43,7 +47,11 @@ Before releasing tasks: ### Project Activation Gate -A project cannot become active unless guide, approved submission artifact policy, generated pre-submit checker policy, post-submit checker policy, review policy, revision policy, and payment policy are present. +A project cannot become active unless guide, passed or acknowledged guide +sufficiency report, approved submission artifact policy, persisted effective +submission artifact policy hash, generated pre-submit checker policy, +post-submit checker policy, review policy, revision policy, and payment policy +are present. ### Task Screening Gate diff --git a/docs/spec_chunk_3_project_guide_foundation.md b/docs/spec_chunk_3_project_guide_foundation.md index 14f7325..73e97e4 100644 --- a/docs/spec_chunk_3_project_guide_foundation.md +++ b/docs/spec_chunk_3_project_guide_foundation.md @@ -62,7 +62,7 @@ Project guide activation requires: - guide is still draft - guide sufficiency report is passed or warnings are acknowledged by `admin` or `project_manager` -- submission artifact policy exists for the guide version +- Workstream-derived submission artifact policy is approved for the guide version with `admin` or `project_manager` approval provenance - effective submission artifact policy hash exists for the guide version - generated pre-submit checker policy snapshot/hash exists for the guide version - post-submit checker policy exists for the guide version diff --git a/docs/spec_chunk_5_submission_packet_foundation.md b/docs/spec_chunk_5_submission_packet_foundation.md index ac71a88..0a1641e 100644 --- a/docs/spec_chunk_5_submission_packet_foundation.md +++ b/docs/spec_chunk_5_submission_packet_foundation.md @@ -122,8 +122,8 @@ Locks a submission packet before checker execution. Locking makes the packet imm - a worker can submit only when assigned to the task - first submission requires task status `IN_PROGRESS` -- Workstream computes the effective submission artifact policy before creating a submission -- Workstream generates pre-submit checker policy from the effective submission artifact policy +- Workstream loads the locked effective submission artifact policy hash before creating a submission +- Workstream loads the locked generated pre-submit checker policy snapshot/hash before creating a submission - blocking pre-submit failures prevent submission creation - when blocking pre-submit fails, no submission row is created, no submission version is assigned, no task transition to `SUBMITTED` occurs, and no submission-created audit event is written - first submission moves the task to `SUBMITTED` diff --git a/docs/spec_chunk_6_checker_contract_records.md b/docs/spec_chunk_6_checker_contract_records.md index 0341d1e..3b14c26 100644 --- a/docs/spec_chunk_6_checker_contract_records.md +++ b/docs/spec_chunk_6_checker_contract_records.md @@ -191,7 +191,10 @@ Normalization rules: Pre-submit checks run before a submission is created. They are authoritative for submission intake and return immediate API feedback without creating an authoritative post-submit checker run. -Workstream generates pre-submit checker policy server-side from the effective submission artifact policy for the task. Workers submit only draft packet fields. They cannot choose checker names, policy versions, blocking rules, severities, results, or outcomes. +Workstream loads the locked generated pre-submit checker policy snapshot/hash +for the task's guide version. Workers submit only draft packet fields. They +cannot choose checker names, policy versions, blocking rules, severities, +results, or outcomes. Response fields: diff --git a/docs/template_project_guide.md b/docs/template_project_guide.md index 4c7be74..85fcb88 100644 --- a/docs/template_project_guide.md +++ b/docs/template_project_guide.md @@ -107,7 +107,9 @@ This section is a human-readable summary. The enforcement source is the approved Every active guide version must have: +- GuideSufficiencyReport: - SubmissionArtifactPolicy: +- EffectiveSubmissionArtifactPolicy hash: - generated PreSubmitCheckerPolicy: - PostSubmitCheckerPolicy: - ReviewPolicy: diff --git a/docs/template_submission_artifact_policy.md b/docs/template_submission_artifact_policy.md index 442c675..2f69a19 100644 --- a/docs/template_submission_artifact_policy.md +++ b/docs/template_submission_artifact_policy.md @@ -40,7 +40,7 @@ Source material refs: ## Approval Provenance -- derivation source: `manual | workstream_agent | import_adapter` +- source material ingestion method: `manual_entry | import_adapter | url_import | repository_import` - derivation agent name: - derivation agent version: - sufficiency report id: @@ -51,6 +51,10 @@ Source material refs: - approved by actor: - approved at: +Source material is untrusted input. Embedded instructions in guide text, URLs, +repository docs, examples, or imported documents cannot grant tool authority, +override Workstream rules, or weaken default checks. + ## Workstream Default Rules Every project inherits Workstream default submission artifact rules. Project policy can add stricter requirements, but it cannot remove, weaken, downgrade, or bypass these defaults. From 5315689499c8c0f9f8dcceb86a089f73c0b333f2 Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Tue, 23 Jun 2026 12:34:20 +0100 Subject: [PATCH 10/37] Tighten policy planning proof obligations --- .../CHUNK_MAP.md | 6 ++++-- .../WS-POL-001-01-submission-artifact-policy-foundation.md | 5 ++++- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md index b6e1789..6184fcf 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md @@ -270,8 +270,10 @@ Acceptance criteria: Verification: - Postgres-backed checker tests cover pre-submit feedback without durable - `CheckerRun`, post-submit `CheckerRun` creation against locked - `PostSubmitCheckerPolicy`, and worker-facing response filtering. + `CheckerRun` and post-submit `CheckerRun` creation against locked + `PostSubmitCheckerPolicy`. +- Postgres-backed FastAPI/API tests cover post-submit policy locking and + worker-facing response filtering. Required reviewers: diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md index 7a117e1..8d3257a 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md @@ -114,7 +114,10 @@ human review implementation - [ ] Effective submission artifact policy hash is persisted for the guide version. - [ ] Generated `PreSubmitCheckerPolicy` snapshot/hash is persisted and locked to the guide version. - [ ] Transitional `evidence_policy`, `required_files`, and `required_evidence` are replaced, not kept as compatibility aliases. -- [ ] Postgres-backed FastAPI/API tests cover create/update/activation/default-weakening/guide-sufficiency/source-ref-sanitization/pre-submit-policy-locking cases. +- [ ] Postgres-backed FastAPI/API tests cover create/update, blocking activation + from guide sufficiency gaps, `admin`/`project_manager` warning + acknowledgement, approval provenance fields, default weakening, + source-ref sanitization, and pre-submit policy locking. ## Verification Commands From 03906f82ba5fcfee21ea1ddcabbb4f706d7b9624 Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Tue, 23 Jun 2026 12:39:46 +0100 Subject: [PATCH 11/37] Refresh policy planning review evidence --- .../WS-POL-001-01-external-review-response.md | 44 +++++---------- .../WS-POL-001-01-internal-review-evidence.md | 56 ++++++++----------- 2 files changed, 36 insertions(+), 64 deletions(-) diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md index f664a66..f8fad97 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md @@ -10,38 +10,26 @@ https://github.com/Flow-Research/workstream/pull/26 ## Source -CodeRabbit and GitHub checks. +CodeRabbit, GitHub checks, and human PR review. ## Summary -External review feedback was handled separately from internal sub-agent evidence. -CodeRabbit reported one readability nitpick in the chunk map. The finding was -valid, in scope, and fixed without changing the product contract. +External review feedback is tracked separately from internal sub-agent evidence. +Internal sub-agent results live in +`WS-POL-001-01-internal-review-evidence.md`. ## External Findings | Source | Finding | Severity | Status | Response | |---|---|---:|---:|---| -| CodeRabbit | `WS-POL-001-03` acceptance criteria repeated "Blocking pre-submit failure creates no..." across consecutive lines. | Low | Fixed | Consolidated the four no-side-effect guarantees into one sentence while preserving every distinct requirement. | -| GitHub checks | Agent Gates, Backend, Week 1 API Demo UI, and CodeRabbit status must pass. | High | Passed | All GitHub checks passed after the final push. | -| CodeRabbit manual trigger | Manual `@coderabbitai review` was requested after the rate-limit window. | Informational | Complete | CodeRabbit replied "Review finished" and noted incremental review does not re-review already reviewed commits unless automatic reviews are paused. No new actionable findings were posted. | -| Human review | Project owners should not author `SubmissionArtifactPolicy`; Workstream should derive it from project material and require `admin` or `project_manager` approval. | High | Fixed | Updated planning artifacts, ADRs, glossary, architecture docs, specs, templates, operating manual, current data flow, and first user flows. | -| Human review | Pre-submit failures should not use review decisions and should show pass/fail details like the Snorkel-style static checker experience. | High | Fixed | Standardized `pre_submission_checker_failed` with structured pass/fail/warning details and explicit exclusion of `accept`, `needs_revision`, and `reject`. | +| CodeRabbit | `WS-POL-001-03` acceptance criteria repeated no-side-effect wording. | Low | Fixed | Consolidated the no-row, no-version, no-transition, and no-durable-checker-run guarantee without weakening it. | +| Human review | Project owners must not author or approve Workstream internal `SubmissionArtifactPolicy`; Workstream derives it from open-ended project material and `admin` or `project_manager` approves the internal bundle. | High | Fixed | Updated planning artifacts, ADRs, glossary, architecture docs, specs, templates, operating manual, data flow, and first user flows. | +| Human review | Project-guide material is open-ended, not a fixed checklist; Workstream must run sufficiency and derivation agents internally. | High | Fixed | Added `ProjectGuideSufficiencyAgent`, `GuideSufficiencyReport`, and `SubmissionArtifactPolicyDerivationAgent` to the plan, ADR, data model, lifecycle, templates, and chunk map. | +| Human review | `PreSubmitCheckerPolicy` must be persisted and locked to the guide version, not derived on read. | High | Fixed | Updated plan, ADRs, data model, lifecycle, checker flow, and chunk contracts to require persisted snapshot/hash and locked effective policy hash. | +| Human review | Pre-submit failures should not use review decisions and should show pass/fail/warning details like the Snorkel-style static checker experience. | High | Fixed | Standardized `pre_submission_checker_failed` with structured pass/fail/warning details and explicit exclusion of `accept`, `needs_revision`, and `reject`. | +| Human review | Current planning PR must be mergeable before implementation starts. | High | Fixed | Updated status, chunk map, chunk contract, proof obligations, and review evidence while keeping backend implementation inactive. | -## Fix Plan - -- Keep the external CodeRabbit response in this `*-external-review-response.md` - artifact. -- Keep internal sub-agent review evidence in - `WS-POL-001-01-internal-review-evidence.md`. -- Apply only the wording consolidation requested by CodeRabbit. -- Re-run affected internal reviewer tracks before pushing. - -## Out-of-Scope Items To Defer - -None. - -## Evidence After Fixes +## Commands To Re-Run After Push ```bash gh pr view 26 --json number,title,state,isDraft,url,reviewDecision,reviews,comments,statusCheckRollup @@ -53,12 +41,6 @@ python3 scripts/check_stale_workstream_wording.py git diff --check ``` -Final GitHub state after push: +## Remaining External Review -```text -agent-gates: pass -backend test: pass -week1 demo UI: pass -CodeRabbit status: pass -CodeRabbit manual trigger: review finished, no new actionable findings posted -``` +Await fresh GitHub checks and CodeRabbit review after this evidence refresh is pushed. diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md index 0063cb9..4380c14 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md @@ -10,47 +10,38 @@ valid findings addressed: yes ## Reviewed Revision -Reviewed code SHA: 0b94c7df1fb1fa2a9df926ddfd5cb81404bb448c +Reviewed code SHA: 5315689499c8c0f9f8dcceb86a089f73c0b333f2 -Reviewed at: 2026-06-22T19:16:02Z +Reviewed at: 2026-06-23T11:35:58Z -Reviewer run IDs: 019eee8c-5c09-7603-bae4-2b2bc60f8dd3, 019eee8e-55e6-75b0-92dd-f5c44f80ad7b, 019eee91-1ff6-7552-8ce4-06a48f0ffac9, 019eee94-c99d-72a3-80f5-9b90ddd9c9d3, 019eee9a-b0eb-7020-880f-be0bfa1968f6, 019eeeca-bc88-7ce0-baec-6be4a8ca1f47, 019eeecb-f151-7433-a472-f3bcdaafda8f, 019eef36-6dc2-7e81-9663-8d3a6aec2278, 019eef37-a7cb-7302-84ac-06531bf8b0fb, 019eef3a-3b6c-7a92-a094-15a2f24615ff, 019eef3c-bfbb-7ed1-acb2-112c6d34b455, 019eeff9-e4de-7ae0-a264-3a1d75fda44e, 019eeffe-4448-7242-9196-da135f61e2f0, 019ef004-ef16-7d21-9910-6c397b8c4b6a, 019ef009-355b-7ae0-9236-e5136266fb8b, 019ef00d-8adf-7c63-8023-0187df5f6283, 019ef018-de9a-71d2-beac-bd74a96496df, 019ef046-eff0-79f1-8243-8e52c40805e3, 019ef04b-722f-7e23-90e3-e6dfd66c77c9, 019ef04f-9b1e-7ad2-bbd4-fc86ded065b4, 019ef098-9469-70f0-8396-2177ffadfeee, 019ef0b5-36e5-7d91-aca5-bc8505eb9f00 +Reviewer run IDs: 019ef3df-a4ae-71f0-b50c-dbd99e65af6c, 019ef3e0-cc78-7583-abd8-826f77b6d435, 019ef3e2-d1fc-7642-b079-561bf61b3d07, 019ef3e5-1e10-78f2-b272-f06200c50334, 019ef3e7-6f3d-7730-a2fd-adc55e496811, 019ef3ea-b44c-7741-9ced-b05bb6a5e5d2, 019ef432-a806-75c1-96ac-11c93eea2f9c -After reviewed SHA `0b94c7df1fb1fa2a9df926ddfd5cb81404bb448c`, only review evidence artifacts changed. +After reviewed SHA `5315689499c8c0f9f8dcceb86a089f73c0b333f2`, only review evidence artifacts changed. ## Reviewer Results | Reviewer | Result | Blocking findings | Notes | |---|---:|---|---| -| senior engineering | PASS WITH LOW RISKS | None remaining | Planning artifacts are coherent, narrow, and do not start backend implementation. Active planning wording was clarified. | -| qa/test | PASS AFTER FIXES | None remaining | Unsafe unqualified pytest command was removed; remaining verification command uses `WORKSTREAM_TEST_DATABASE_URL` with `workstream_test`. | -| security/auth | PASS WITH LOW RISKS | None remaining | Flow auth boundary, storage-reference safety, non-bypassable defaults, and no blockchain/payment expansion are preserved. Default hash/storage/secret rules were added to the chunk contract. | -| product/ops | PASS WITH LOW RISKS | None remaining | Plan matches intent: ProjectGuide is human-facing, SubmissionArtifactPolicy is machine-readable, defaults are non-bypassable, and worker-facing outcomes stay simple. Stored token wording was clarified. | -| architecture | PASS WITH LOW RISKS | None remaining | Chunk sequencing preserves policy foundation, generated pre-submit policy, submission creation rewiring, and post-submit provenance split. Router/service/repository/schema boundaries were added to the contract. | -| docs | PASS WITH LOW RISKS | None remaining | Markdown links, stale wording, and naming passed after normalizing `PreSubmitCheckerPolicy` as the canonical name. | -| senior engineering | PASS | None | Re-reviewed CodeRabbit wording consolidation; meaning was not weakened. | -| qa/test | PASS | None | Re-reviewed consolidated criteria; no-row, no-version, no-transition, and no-durable-checker-run remain testable. | -| product/ops | PASS | None | Re-reviewed consolidated criteria; worker-facing semantics remain simple and precise. | -| docs | PASS WITH LOW RISKS | None | Re-reviewed consolidated criteria; no adjacent docs required. | -| senior engineering | PASS WITH LOW RISKS | None | Re-reviewed project-owner material, Workstream-derived policy, admin/project_manager approval, activation guard, and pre-submit failure boundary. Low risk captured around keeping chunk 1 scoped to policy provenance/approval, not full derivation workflow. | -| product/ops | PASS WITH LOW RISKS | None | Re-reviewed setup ownership, worker/reviewer boundary, and payment/reputation non-expansion. | -| architecture | PASS WITH LOW RISKS | None | Re-reviewed source-of-truth and chunk-scope boundaries; no blocking boundary violations. | -| qa/test | PASS WITH LOW RISKS | None | Re-reviewed approval provenance, activation guard, and `pre_submission_checker_failed` testability. `approved_by_role` was added to architecture data model after QA noted drift risk. | -| security/auth | PASS WITH LOW RISKS | None | Re-reviewed approval provenance, non-bypassable defaults, role approval boundary, and project-owner material as untrusted input. | -| docs | PASS | None | Re-reviewed canonical docs after stale ownership and pre-submit wording fixes. | +| senior engineering | PASS AFTER FIXES | None remaining | Confirmed no backend implementation started. Requested stale evidence refresh, removal of derived-on-read risk, and locked-policy wording in runtime docs. Fixed. | +| QA/test | PASS AFTER FIXES | None remaining | Requested Postgres-backed FastAPI/API proof for Chunk 1 and per-chunk verification expectations. Fixed. | +| security/auth | PASS AFTER FIXES | None remaining | Required project-owner material to be treated as untrusted input, with unsafe refs and embedded tool instructions rejected. Fixed. | +| product/ops | PASS AFTER FIXES | None remaining | Required full activation bundle wording, approved policy provenance, and no manual bypass of derivation agent. Fixed. | +| architecture | PASS AFTER FIXES | None remaining | Required activation docs to include `GuideSufficiencyReport` and effective policy hash, and fixed review-policy wording in the flow diagram. Fixed. | +| docs | PASS AFTER FIXES | None remaining | Required loop state refresh and active guide-policy bundle alignment in docs/templates. Fixed. | +| test-delta | PASS AFTER FIXES | None remaining | Required API-level proof obligations for Chunk 1 warning acknowledgement/provenance and Chunk 4 worker response filtering. Fixed. | ## Valid Findings Addressed -- QA/test found an unsafe plain `pytest tests/test_projects.py` command that could target the non-test local database. The contract now uses only `WORKSTREAM_TEST_DATABASE_URL=.../workstream_test`. -- Security/auth requested explicit default policy acceptance criteria for hash rules, storage reference rejection, and default-forbidden secret/token artifacts. Those criteria were added. -- Senior engineering found `WORK_QUEUE.md` could confuse active planning with approved implementation. Loop wording now says active planning and explicitly blocks backend implementation until user approval. -- Product/ops found display wording could drift from stored review decision values. Intent and decisions now state stored values remain exactly `accept`, `needs_revision`, and `reject`. -- Architecture requested explicit responsibility boundaries. The chunk contract now states routers translate HTTP, services own policy/default validation, repositories persist/query, and schemas define IO contracts. -- Docs found `GeneratedPreSubmitCheckerPolicy` could look like a canonical token. The plan now uses canonical `PreSubmitCheckerPolicy` and describes it as generated. -- CodeRabbit found repetitive wording in `WS-POL-001-03` acceptance criteria. The repeated lines were consolidated without changing the no-row, no-version, no-transition, and no-durable-checker-run requirements. -- Human review clarified that project owners should not author `SubmissionArtifactPolicy` directly. Docs now state project owners provide plain-language setup material, Workstream derives `ProjectSubmissionArtifactPolicy`, and `admin` or `project_manager` approves it before guide activation. -- QA requested schema-level testability for approval provenance. The chunk contract and architecture data model now name derivation source, source material refs, approval status, approver role, approver actor, approval timestamp, and approved policy version/hash. -- Docs found canonical/spec drift around pre-submit failures. ADRs, glossary, architecture docs, specs, templates, operating manual, and flow docs now use `pre_submission_checker_failed` with structured pass/fail/warning details and explicitly exclude review decision values. +- Added explicit untrusted-source-material rules for project owner docs, URLs, repository docs, examples, and imported documents. +- Added source-ref sanitization requirements for signed URLs, query-bearing refs, credential-bearing refs, and local filesystem paths. +- Clarified that guide text and imported material cannot grant tool authority, override Workstream rules, or weaken default policy. +- Tightened Chunk 1 proof to require Postgres-backed FastAPI/API tests for activation blocking, warning acknowledgement by `admin` or `project_manager`, approval provenance, default weakening, source-ref sanitization, and pre-submit policy locking. +- Added per-chunk verification expectations for async guide analysis, submission creation, post-submit policy split, and revision resubmission real API drill. +- Updated activation docs to require passed or acknowledged `GuideSufficiencyReport`, approved `SubmissionArtifactPolicy`, persisted `EffectiveSubmissionArtifactPolicy` hash, generated `PreSubmitCheckerPolicy`, post-submit checker policy, review policy, revision policy, and payment policy. +- Replaced stale runtime wording that implied recomputing/generating pre-submit policy at submission time with loading the locked effective policy hash and locked `PreSubmitCheckerPolicy` snapshot/hash. +- Replaced ambiguous `derivation source: manual | workstream_agent | import_adapter` wording with source-material ingestion method and kept derivation agent fields mandatory. +- Added missing approval provenance fields to the data model example. +- Updated loop state to point at the current internal review evidence instead of saying no evidence exists. ## Commands Run @@ -59,12 +50,11 @@ python3 scripts/check_loop_memory_state.py python3 scripts/check_markdown_links.py python3 scripts/check_stale_workstream_wording.py python3 scripts/workstream_agent_gate.py --base origin/main --head HEAD --format json +python3 scripts/check_internal_review_evidence.py git diff --check -gh pr view 26 --json number,title,state,isDraft,url,reviewDecision,reviews,comments,statusCheckRollup ``` ## Remaining Risks - `WS-POL-001-01` is not approved for backend implementation yet. -- Exact Workstream default submission artifact policy fields remain a human decision before implementation can close. -- Generated `PreSubmitCheckerPolicy` persistence versus derived-on-read remains a human decision for chunk 2. +- Human review should focus on persisted provenance field names and confirming Chunk 1 remains records/contracts/activation guard only. From 9453e9fad97691a638d6e15f239a4e693a61234f Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Tue, 23 Jun 2026 13:02:06 +0100 Subject: [PATCH 12/37] Clarify pre-submit enforcement contract --- .../WS-POL-001-01-external-review-response.md | 1 + ...ssion_artifact_policy_drives_pre_submit.md | 26 +++++++++++++++++++ 2 files changed, 27 insertions(+) diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md index f8fad97..248ab91 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md @@ -28,6 +28,7 @@ Internal sub-agent results live in | Human review | `PreSubmitCheckerPolicy` must be persisted and locked to the guide version, not derived on read. | High | Fixed | Updated plan, ADRs, data model, lifecycle, checker flow, and chunk contracts to require persisted snapshot/hash and locked effective policy hash. | | Human review | Pre-submit failures should not use review decisions and should show pass/fail/warning details like the Snorkel-style static checker experience. | High | Fixed | Standardized `pre_submission_checker_failed` with structured pass/fail/warning details and explicit exclusion of `accept`, `needs_revision`, and `reject`. | | Human review | Current planning PR must be mergeable before implementation starts. | High | Fixed | Updated status, chunk map, chunk contract, proof obligations, and review evidence while keeping backend implementation inactive. | +| CodeRabbit | ADR 0011 described pre-submit/review-decision separation but did not state how implementation must prove enforcement. | Major | Fixed | Added an implementation enforcement contract to ADR 0011. It explicitly says this PR is planning-only and lists the API, UI/demo, persistence, database, and chunk-level proof required before implementation chunks can close. | ## Commands To Re-Run After Push 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 d1eb150..b269389 100644 --- a/docs/decision_0011_submission_artifact_policy_drives_pre_submit.md +++ b/docs/decision_0011_submission_artifact_policy_drives_pre_submit.md @@ -87,6 +87,32 @@ Blocking pre-submit failures prevent submission creation. When blocking pre-subm Pre-submit checks are authoritative for submission intake. They are not authoritative proof for human review readiness. Review readiness still requires post-submit internal checker runs against a locked submission. +## Implementation Enforcement Contract + +This ADR defines the required product contract. This planning PR does not claim +the backend implementation already enforces it. + +The implementation chunks that close this ADR must prove these enforcement +points before they can be marked complete: + +- API response schemas for `pre_submission_checker_failed` must exclude review + decision fields and values such as `accept`, `needs_revision`, and `reject`. +- Worker-facing UI or demo surfaces that render pre-submit results must use + pre-submit pass/fail/warning language, not human review decision terminology. +- Pre-submit intake feedback must not be persisted as human review decisions or + durable post-submit checker results. +- Database schemas or persistence services for pre-submit feedback must not + store review decision columns for pre-submit outcomes; if a shared shape is + unavoidable, review-decision fields must be nullable and enforced empty for + pre-submit records. +- Post-submit checker records and future human review records remain the only + places that can route toward `needs_revision` as a task outcome. + +Chunk `WS-POL-001-03` must prove the API response and no-row/no-version/no-task +transition behavior. Chunk `WS-POL-001-04` must prove post-submit checker +records remain separate from pre-submit feedback and that worker-facing +responses do not expose internal-only routes. + ## Default Workstream Submission Artifact Rules Every submission must include: From 141ad11e42e96bf98d5c24fb77442d681d6698b1 Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Tue, 23 Jun 2026 14:12:43 +0100 Subject: [PATCH 13/37] Assign pre-submit enforcement proof --- .../CHUNK_MAP.md | 10 ++++++++++ ...011_submission_artifact_policy_drives_pre_submit.md | 4 +++- 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md index 6184fcf..6d74b3b 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md @@ -265,6 +265,8 @@ Acceptance criteria: - Pre-submit policy provenance and post-submit policy provenance are distinct. - Durable checker runs use locked post-submit checker policy. - Pre-submit feedback does not create durable checker records. +- Pre-submit feedback persistence cannot store review decision fields, or + enforces review decision fields empty when a shared shape is unavoidable. - API responses do not expose internal-only routes to workers. Verification: @@ -272,6 +274,8 @@ Verification: - Postgres-backed checker tests cover pre-submit feedback without durable `CheckerRun` and post-submit `CheckerRun` creation against locked `PostSubmitCheckerPolicy`. +- Postgres-backed schema/persistence tests prove pre-submit feedback cannot + store review decision values. - Postgres-backed FastAPI/API tests cover post-submit policy locking and worker-facing response filtering. @@ -284,6 +288,12 @@ Human review focus: Field naming and migration safety. +Follow-up: + +- A future frontend/demo chunk must prove any UI or demo surface that renders + pre-submit results uses pass/fail/warning language instead of review decision + terminology before ADR 0011 is marked fully implemented. + ### WS-POL-001-05: Revision Resubmission And Real API Drill Goal: 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 b269389..af42de1 100644 --- a/docs/decision_0011_submission_artifact_policy_drives_pre_submit.md +++ b/docs/decision_0011_submission_artifact_policy_drives_pre_submit.md @@ -111,7 +111,9 @@ points before they can be marked complete: Chunk `WS-POL-001-03` must prove the API response and no-row/no-version/no-task transition behavior. Chunk `WS-POL-001-04` must prove post-submit checker records remain separate from pre-submit feedback and that worker-facing -responses do not expose internal-only routes. +responses do not expose internal-only routes. If any UI or demo surface renders +pre-submit results, a later frontend/demo chunk must prove the same wording +separation before this ADR can be closed as fully implemented. ## Default Workstream Submission Artifact Rules From 4acf31b7eabb2c012c8716d780dc8f68a1800b54 Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Tue, 23 Jun 2026 14:18:11 +0100 Subject: [PATCH 14/37] Refresh enforcement contract review evidence --- .../WS-POL-001-01-internal-review-evidence.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md index 4380c14..76ef090 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md @@ -10,13 +10,13 @@ valid findings addressed: yes ## Reviewed Revision -Reviewed code SHA: 5315689499c8c0f9f8dcceb86a089f73c0b333f2 +Reviewed code SHA: 141ad11e42e96bf98d5c24fb77442d681d6698b1 -Reviewed at: 2026-06-23T11:35:58Z +Reviewed at: 2026-06-23T13:14:19Z -Reviewer run IDs: 019ef3df-a4ae-71f0-b50c-dbd99e65af6c, 019ef3e0-cc78-7583-abd8-826f77b6d435, 019ef3e2-d1fc-7642-b079-561bf61b3d07, 019ef3e5-1e10-78f2-b272-f06200c50334, 019ef3e7-6f3d-7730-a2fd-adc55e496811, 019ef3ea-b44c-7741-9ced-b05bb6a5e5d2, 019ef432-a806-75c1-96ac-11c93eea2f9c +Reviewer run IDs: 019ef3df-a4ae-71f0-b50c-dbd99e65af6c, 019ef3e0-cc78-7583-abd8-826f77b6d435, 019ef3e2-d1fc-7642-b079-561bf61b3d07, 019ef3e5-1e10-78f2-b272-f06200c50334, 019ef3e7-6f3d-7730-a2fd-adc55e496811, 019ef3ea-b44c-7741-9ced-b05bb6a5e5d2, 019ef432-a806-75c1-96ac-11c93eea2f9c, 019ef45d-540a-71e1-9531-19277d5450ed, 019ef45f-a5fa-7721-b9ae-aa39b1f6778e, 019ef462-b086-7923-a03e-78c298316f73, 019ef466-2433-7bf3-9335-069cfa5b5838, 019ef46a-171d-7b42-9795-773132754ff0, 019ef46e-dcea-7423-aa46-47a27b098c85 -After reviewed SHA `5315689499c8c0f9f8dcceb86a089f73c0b333f2`, only review evidence artifacts changed. +After reviewed SHA `141ad11e42e96bf98d5c24fb77442d681d6698b1`, only review evidence artifacts changed. ## Reviewer Results @@ -29,6 +29,12 @@ After reviewed SHA `5315689499c8c0f9f8dcceb86a089f73c0b333f2`, only review evide | architecture | PASS AFTER FIXES | None remaining | Required activation docs to include `GuideSufficiencyReport` and effective policy hash, and fixed review-policy wording in the flow diagram. Fixed. | | docs | PASS AFTER FIXES | None remaining | Required loop state refresh and active guide-policy bundle alignment in docs/templates. Fixed. | | test-delta | PASS AFTER FIXES | None remaining | Required API-level proof obligations for Chunk 1 warning acknowledgement/provenance and Chunk 4 worker response filtering. Fixed. | +| focused senior engineering | PASS | None | Re-reviewed ADR 0011 enforcement contract and confirmed it does not falsely claim backend enforcement. | +| focused QA/test | PASS AFTER FIXES | None remaining | Found missing UI/demo ownership and schema/persistence proof assignment. Fixed in ADR 0011 and Chunk 4 proof obligations. | +| focused security/auth | PASS | None | Re-reviewed ADR 0011 fail-closed API/database contract and planning-only caveat. | +| focused product/ops | PASS | None | Confirmed worker-facing pre-submit language remains separate from review decisions. | +| focused architecture | PASS AFTER FIXES | None remaining | Confirmed boundaries and requested stale evidence refresh. Fixed by this evidence update. | +| focused docs | PASS WITH LOW RISKS | None | Confirmed ADR and external-review wording are clear and do not overclaim implementation. | ## Valid Findings Addressed @@ -42,6 +48,9 @@ After reviewed SHA `5315689499c8c0f9f8dcceb86a089f73c0b333f2`, only review evide - Replaced ambiguous `derivation source: manual | workstream_agent | import_adapter` wording with source-material ingestion method and kept derivation agent fields mandatory. - Added missing approval provenance fields to the data model example. - Updated loop state to point at the current internal review evidence instead of saying no evidence exists. +- Added ADR 0011 implementation enforcement contract without claiming the backend already enforces it. +- Assigned UI/demo wording proof to a later frontend/demo chunk before ADR closure. +- Added Chunk 4 schema/persistence proof that pre-submit feedback cannot store review decision values. ## Commands Run From cfc0c3565f61f8094adcdf6559a50d8026dd609b Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Tue, 23 Jun 2026 14:35:33 +0100 Subject: [PATCH 15/37] Finalize policy planning external review state --- .../reviews/WS-POL-001-01-external-review-response.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md index 248ab91..1a99d89 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md @@ -29,6 +29,7 @@ Internal sub-agent results live in | Human review | Pre-submit failures should not use review decisions and should show pass/fail/warning details like the Snorkel-style static checker experience. | High | Fixed | Standardized `pre_submission_checker_failed` with structured pass/fail/warning details and explicit exclusion of `accept`, `needs_revision`, and `reject`. | | Human review | Current planning PR must be mergeable before implementation starts. | High | Fixed | Updated status, chunk map, chunk contract, proof obligations, and review evidence while keeping backend implementation inactive. | | CodeRabbit | ADR 0011 described pre-submit/review-decision separation but did not state how implementation must prove enforcement. | Major | Fixed | Added an implementation enforcement contract to ADR 0011. It explicitly says this PR is planning-only and lists the API, UI/demo, persistence, database, and chunk-level proof required before implementation chunks can close. | +| CodeRabbit latest review | Latest review reported no actionable comments. | Informational | Complete | CodeRabbit status passed after the final push. | ## Commands To Re-Run After Push @@ -42,6 +43,11 @@ python3 scripts/check_stale_workstream_wording.py git diff --check ``` -## Remaining External Review +## Final External Review State -Await fresh GitHub checks and CodeRabbit review after this evidence refresh is pushed. +```text +agent-gates: pass +backend test: pass +week1 demo UI: pass +CodeRabbit: pass, no actionable comments in latest review +``` From f6d5ef140be4d5366ae0655eaa0f0a9bbb8dc9c9 Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Tue, 23 Jun 2026 16:29:38 +0100 Subject: [PATCH 16/37] Lock deterministic pre-submit checker compilation --- .../CHUNK_MAP.md | 8 +++++ .../DECISIONS.md | 5 ++- .../INTENT.md | 9 ++++++ .../PLAN.md | 10 ++++++ ...1-submission-artifact-policy-foundation.md | 9 ++++++ docs/architecture_checker_framework.md | 22 +++++++++++++ docs/architecture_data_model.md | 10 ++++++ ...ssion_artifact_policy_drives_pre_submit.md | 32 +++++++++++++++++-- 8 files changed, 102 insertions(+), 3 deletions(-) diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md index 6d74b3b..c14c13f 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md @@ -14,6 +14,9 @@ - Project owner material is untrusted input. Implementation chunks must reject unsafe source refs and prevent guide text or imported docs from granting tool authority or weakening Workstream defaults. +- Agents derive constrained policy and checker specifications. Workstream + compiles deterministic checker bundles. Unrestricted generated checker code + is not the default path. ## Chunks @@ -71,6 +74,8 @@ Acceptance criteria: - Effective submission artifact policy hash is persisted for the guide version. - Generated `PreSubmitCheckerPolicy` snapshot/hash is persisted and locked to the guide version. +- Generated `PreSubmitCheckerPolicy` is a compiled deterministic checker bundle + from approved primitives, not unrestricted generated code. - Guide activation requires passing or acknowledged guide sufficiency, approved submission artifact policy, effective policy hash, and persisted generated pre-submit checker policy. @@ -143,6 +148,9 @@ Acceptance criteria: - `SubmissionArtifactPolicyDerivationAgent` runs async after sufficiency passes or warnings are acknowledged. - Derived policy cannot weaken Workstream defaults. +- Derived checker specification uses only approved Workstream primitives. +- Trusted checker compiler produces deterministic `PreSubmitCheckerPolicy` + snapshot/hash from the approved specification. - Malicious guide text, embedded prompt-injection instructions, and unsafe source refs cannot influence agent authority, fetch behavior, or default policy strength. diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md index 9febbe2..0487226 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md @@ -17,12 +17,15 @@ `info`. - `SubmissionArtifactPolicyDerivationAgent` derives `ProjectSubmissionArtifactPolicy` after guide sufficiency passes. +- `SubmissionArtifactPolicyDerivationAgent` produces constrained policy and + checker specifications, not unrestricted executable checker code. - Workstream derives `ProjectSubmissionArtifactPolicy` from project material, with internal agent assistance allowed, then requires approval by `admin` or `project_manager` before guide activation. - Workstream default submission artifact rules are non-bypassable. - `EffectiveSubmissionArtifactPolicy` is default plus project policy. -- `PreSubmitCheckerPolicy` is generated from effective policy, persisted, and +- Workstream's trusted checker compiler turns the constrained checker + specification into deterministic `PreSubmitCheckerPolicy`, persisted and locked to the project guide version. - Pre-submit checks block before submission creation. - Blocking pre-submit feedback is `pre_submission_checker_failed` with diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md index 2ddfabc..2231c6b 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md @@ -34,6 +34,8 @@ WorkstreamDefaultSubmissionArtifactPolicy = EffectiveSubmissionArtifactPolicy EffectiveSubmissionArtifactPolicy +-> constrained pre-submit checker specification +-> trusted Workstream checker compiler -> persisted and locked PreSubmitCheckerPolicy ``` @@ -65,6 +67,11 @@ guide-policy bundle. Workers submit draft packet fields. Workstream decides required artifacts, evidence, hashes, storage reference rules, forbidden artifacts, and blocking pre-submit feedback from the locked effective policy. +The derivation agent produces a constrained artifact-intake contract and checker +specification. Workstream compiles that specification into deterministic checker +logic. Runtime submission evaluation is performed by the locked checker bundle, +not by an agent. + ## Why Now Week 1 and Week 2 established the core backend loop: @@ -95,6 +102,8 @@ After this initiative: - Effective submission artifact policy is computed deterministically. - Generated pre-submit checker policy is persisted and locked to the project guide version. +- Generated pre-submit checker policy is produced by Workstream's trusted + compiler from approved checker primitives, not by unrestricted generated code. - Submission creation uses the generated pre-submit policy before a submission row is created. - Post-submit/internal checker policy remains separate. diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md index a70f917..39fcd58 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md @@ -58,6 +58,13 @@ checks run before submission creation and do not create durable checker records. Post-submit/internal checks run after submission lock and do create durable checker records. +The derivation agent does not generate unrestricted executable checker code. +It produces a constrained checker specification using Workstream-approved +primitives. Workstream's trusted checker compiler turns that specification into +the deterministic `PreSubmitCheckerPolicy` bundle. Runtime checks execute the +locked compiled bundle against staged artifact hashes or future content +identifiers. + If no passing or acknowledged guide sufficiency report, approved project submission artifact policy, effective policy hash, and persisted generated pre-submit checker policy exist for the guide version, guide activation fails @@ -112,6 +119,9 @@ while post-submit answers whether a locked submission can move to human review. - Project-owner boundary: project owners provide open-ended guide material and business terms; Workstream evaluates sufficiency, derives policy, and owns internal controls. +- Checker-code boundary: agents derive constrained checker specifications; + Workstream compiles deterministic checker bundles. Unrestricted generated + checker code is not the default path. - Source-material security: project-owner docs, URLs, examples, and repository docs are untrusted input; embedded tool instructions, prompt-injection text, credential-bearing refs, signed URLs, query-bearing refs, and local filesystem diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md index 8d3257a..1cdbf54 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md @@ -25,6 +25,11 @@ effective policy hash, persists the generated pre-submit checker policy snapshot/hash, and a Workstream actor with the `admin` or `project_manager` role approves the bundle before guide activation. +The generated pre-submit checker policy is deterministic compiled policy, not +unrestricted generated checker code. Agents derive constrained checker +specifications; Workstream's trusted compiler produces the locked checker +bundle. + Project owner material is untrusted input. Guide text, URLs, repository docs, examples, and imported documents cannot grant tool authority, override Workstream rules, or weaken default checks. Source refs must be sanitized before @@ -113,6 +118,10 @@ human review implementation - [ ] Effective policy merge rejects project policy that weakens defaults. - [ ] Effective submission artifact policy hash is persisted for the guide version. - [ ] Generated `PreSubmitCheckerPolicy` snapshot/hash is persisted and locked to the guide version. +- [ ] Generated `PreSubmitCheckerPolicy` stores a constrained checker spec, + compiler version, compiled bundle hash, and immutable compiled bundle. +- [ ] Generated checker bundle uses approved primitives rather than unrestricted + generated code. - [ ] Transitional `evidence_policy`, `required_files`, and `required_evidence` are replaced, not kept as compatibility aliases. - [ ] Postgres-backed FastAPI/API tests cover create/update, blocking activation from guide sufficiency gaps, `admin`/`project_manager` warning diff --git a/docs/architecture_checker_framework.md b/docs/architecture_checker_framework.md index d52153d..6304349 100644 --- a/docs/architecture_checker_framework.md +++ b/docs/architecture_checker_framework.md @@ -166,6 +166,8 @@ ProjectGuide -> GuideSufficiencyReport -> ProjectSubmissionArtifactPolicy -> EffectiveSubmissionArtifactPolicy +-> constrained PreSubmitCheckerSpec +-> trusted Workstream checker compiler -> PreSubmitCheckerPolicy -> pre-submit intake checks -> Submission row only when blocking checks pass @@ -204,6 +206,26 @@ 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`. +The `SubmissionArtifactPolicyDerivationAgent` produces a constrained checker +specification. It does not produce unrestricted checker code. Workstream's +trusted checker compiler turns that specification into deterministic checker +logic using approved primitives such as: + +- `require_file` +- `allow_extension` +- `forbid_extension` +- `require_manifest_field` +- `validate_json_schema` +- `check_directory_structure` +- `require_minimum_evidence` +- `verify_hash` +- `limit_file_size` + +Project-specific executable checker code is a future extension path, not the +default. That extension path must require static validation, generated tests, +sandboxed execution, no network, no shell, no secrets, no database access, +explicit human approval, and a locked code hash. + Pre-submit checks are authoritative for intake. Post-submit checker runs are authoritative for review readiness. The first two gates replace external origin qualification and task ingestion for v0.1. Origin qualification and webhook drop notifications are future adapter concerns. diff --git a/docs/architecture_data_model.md b/docs/architecture_data_model.md index 6357fad..da9ce99 100644 --- a/docs/architecture_data_model.md +++ b/docs/architecture_data_model.md @@ -326,12 +326,22 @@ Fields: - `version` - `policy_hash` - `effective_submission_artifact_policy_hash` +- `checker_spec` +- `compiler_version` +- `compiled_bundle_hash` +- `compiled_bundle` - `checker_names` - `checker_configs` - `blocking_severities` - `generated_from_policy_version` - `generated_at` +`checker_spec` is a constrained machine-readable specification using +Workstream-approved primitives. `compiled_bundle` is the immutable JSON checker +bundle produced by the trusted Workstream checker compiler. It is stored as a +structured snapshot, not arbitrary executable code. `compiled_bundle_hash` +binds the exact compiled logic to `effective_submission_artifact_policy_hash`. + The generated checker order is deterministic: 1. packet shape 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 af42de1..a8213a3 100644 --- a/docs/decision_0011_submission_artifact_policy_drives_pre_submit.md +++ b/docs/decision_0011_submission_artifact_policy_drives_pre_submit.md @@ -39,6 +39,11 @@ passes or warnings are acknowledged. The project owner does not approve this internal policy. A Workstream actor with the `admin` or `project_manager` role reviews and approves the derived policy before guide activation. +The derivation agent does not generate unrestricted executable checker code as +the default path. It produces a machine-readable artifact-intake contract and a +constrained pre-submit checker specification using Workstream-approved +primitives. + `SubmissionArtifactPolicy` is the Workstream-derived, admin-or-project-manager-approved machine-readable contract for worker submissions. It defines: - required artifacts @@ -67,14 +72,37 @@ EffectiveSubmissionArtifactPolicy = + ProjectSubmissionArtifactPolicy ``` -Workstream generates and persists `PreSubmitCheckerPolicy` from the effective -submission artifact policy. +Workstream's trusted checker compiler generates and persists +`PreSubmitCheckerPolicy` from the effective submission artifact policy and the +approved checker specification. `PreSubmitCheckerPolicy` is locked to the project guide version. It is not derived on read, manually edited by workers, or supplied by clients. Workers submit only draft packet fields. They do not choose checker names, policy versions, blocking rules, severities, or outcomes. +The compiled `PreSubmitCheckerPolicy` is deterministic checker logic, not an +agent judgment loop. Runtime checks execute the locked compiled checker bundle +against exact staged artifact hashes or future content identifiers. + +Approved pre-submit checker primitives include: + +- `require_file` +- `allow_extension` +- `forbid_extension` +- `require_manifest_field` +- `validate_json_schema` +- `check_directory_structure` +- `require_minimum_evidence` +- `verify_hash` +- `limit_file_size` + +Project-specific executable checker code is not part of the default path. If a +future project requires logic that cannot fit the constrained checker +specification, the extension path must require static validation, generated +tests, sandboxed execution, no network, no shell, no secrets, no database access, +explicit human approval, and a locked code hash. + Blocking pre-submit failures prevent submission creation. When blocking pre-submit checks fail: - no `Submission` row is created From 0498bbe66468891c8285bb22b1365fee699c2f05 Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Tue, 23 Jun 2026 17:38:24 +0100 Subject: [PATCH 17/37] Tighten deterministic checker compiler proof --- .../CHUNK_MAP.md | 9 +++++++++ ...S-POL-001-01-submission-artifact-policy-foundation.md | 4 ++++ docs/architecture_checker_framework.md | 3 ++- ..._0011_submission_artifact_policy_drives_pre_submit.md | 3 ++- 4 files changed, 17 insertions(+), 2 deletions(-) diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md index c14c13f..30b9587 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md @@ -164,6 +164,11 @@ Verification: source-ref rejection, and default weakening rejection. - Background execution tests prove jobs are async and idempotent for a guide version. +- Compiler tests prove allowed primitive emission, unknown primitive rejection, + byte-stable same-input same-compiler-version bundle hashing, hash binding to + `effective_submission_artifact_policy_hash`, and client/worker inability to + supply checker names, severities, versions, outcomes, compiler version, or + compiled bundles. Required reviewers: @@ -301,6 +306,10 @@ Follow-up: - A future frontend/demo chunk must prove any UI or demo surface that renders pre-submit results uses pass/fail/warning language instead of review decision terminology before ADR 0011 is marked fully implemented. +- A future executable-checker extension chunk, if ever approved, must prove + static validation, generated tests, sandbox policy checks, no network, no + shell, no secrets, no database access, and `admin` or `project_manager` + approval of the exact locked code hash after those checks pass. ### WS-POL-001-05: Revision Resubmission And Real API Drill diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md index 1cdbf54..c91fcf6 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md @@ -127,6 +127,10 @@ human review implementation from guide sufficiency gaps, `admin`/`project_manager` warning acknowledgement, approval provenance fields, default weakening, source-ref sanitization, and pre-submit policy locking. +- [ ] Tests prove primitive allowlisting, unknown primitive rejection, + canonical compiled bundle hashing, hash binding to + `effective_submission_artifact_policy_hash`, immutable compiled bundle + behavior, and absence of executable code fields in the default path. ## Verification Commands diff --git a/docs/architecture_checker_framework.md b/docs/architecture_checker_framework.md index 6304349..1294466 100644 --- a/docs/architecture_checker_framework.md +++ b/docs/architecture_checker_framework.md @@ -224,7 +224,8 @@ logic using approved primitives such as: Project-specific executable checker code is a future extension path, not the default. That extension path must require static validation, generated tests, sandboxed execution, no network, no shell, no secrets, no database access, -explicit human approval, and a locked code hash. +`admin` or `project_manager` approval of the exact code hash after those checks +pass, and a locked code hash. Pre-submit checks are authoritative for intake. Post-submit checker runs are authoritative for review readiness. 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 a8213a3..b790ca1 100644 --- a/docs/decision_0011_submission_artifact_policy_drives_pre_submit.md +++ b/docs/decision_0011_submission_artifact_policy_drives_pre_submit.md @@ -101,7 +101,8 @@ Project-specific executable checker code is not part of the default path. If a future project requires logic that cannot fit the constrained checker specification, the extension path must require static validation, generated tests, sandboxed execution, no network, no shell, no secrets, no database access, -explicit human approval, and a locked code hash. +`admin` or `project_manager` approval of the exact code hash after those checks +pass, and a locked code hash. Blocking pre-submit failures prevent submission creation. When blocking pre-submit checks fail: From 1f4cf3133fc474c3a0400ec2c0a53cc7f365bc8b Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Tue, 23 Jun 2026 17:46:15 +0100 Subject: [PATCH 18/37] Refresh checker compiler review evidence --- .../WS-POL-001-01-internal-review-evidence.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md index 76ef090..2a3d6ba 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md @@ -10,13 +10,13 @@ valid findings addressed: yes ## Reviewed Revision -Reviewed code SHA: 141ad11e42e96bf98d5c24fb77442d681d6698b1 +Reviewed code SHA: 0498bbe66468891c8285bb22b1365fee699c2f05 -Reviewed at: 2026-06-23T13:14:19Z +Reviewed at: 2026-06-23T16:39:43Z -Reviewer run IDs: 019ef3df-a4ae-71f0-b50c-dbd99e65af6c, 019ef3e0-cc78-7583-abd8-826f77b6d435, 019ef3e2-d1fc-7642-b079-561bf61b3d07, 019ef3e5-1e10-78f2-b272-f06200c50334, 019ef3e7-6f3d-7730-a2fd-adc55e496811, 019ef3ea-b44c-7741-9ced-b05bb6a5e5d2, 019ef432-a806-75c1-96ac-11c93eea2f9c, 019ef45d-540a-71e1-9531-19277d5450ed, 019ef45f-a5fa-7721-b9ae-aa39b1f6778e, 019ef462-b086-7923-a03e-78c298316f73, 019ef466-2433-7bf3-9335-069cfa5b5838, 019ef46a-171d-7b42-9795-773132754ff0, 019ef46e-dcea-7423-aa46-47a27b098c85 +Reviewer run IDs: 019ef3df-a4ae-71f0-b50c-dbd99e65af6c, 019ef3e0-cc78-7583-abd8-826f77b6d435, 019ef3e2-d1fc-7642-b079-561bf61b3d07, 019ef3e5-1e10-78f2-b272-f06200c50334, 019ef3e7-6f3d-7730-a2fd-adc55e496811, 019ef3ea-b44c-7741-9ced-b05bb6a5e5d2, 019ef432-a806-75c1-96ac-11c93eea2f9c, 019ef45d-540a-71e1-9531-19277d5450ed, 019ef45f-a5fa-7721-b9ae-aa39b1f6778e, 019ef462-b086-7923-a03e-78c298316f73, 019ef466-2433-7bf3-9335-069cfa5b5838, 019ef46a-171d-7b42-9795-773132754ff0, 019ef46e-dcea-7423-aa46-47a27b098c85, 019ef51b-8491-7192-a868-f2cbc1c56079, 019ef51d-cc5d-7d40-b5e6-0966c546e465, 019ef520-eea1-71c0-919a-63d24728ff32, 019ef523-f173-7e71-8685-902518610fda, 019ef52a-1da8-7df2-9428-c96b1b0cc164 -After reviewed SHA `141ad11e42e96bf98d5c24fb77442d681d6698b1`, only review evidence artifacts changed. +After reviewed SHA `0498bbe66468891c8285bb22b1365fee699c2f05`, only review evidence artifacts changed. ## Reviewer Results @@ -35,6 +35,11 @@ After reviewed SHA `141ad11e42e96bf98d5c24fb77442d681d6698b1`, only review evide | focused product/ops | PASS | None | Confirmed worker-facing pre-submit language remains separate from review decisions. | | focused architecture | PASS AFTER FIXES | None remaining | Confirmed boundaries and requested stale evidence refresh. Fixed by this evidence update. | | focused docs | PASS WITH LOW RISKS | None | Confirmed ADR and external-review wording are clear and do not overclaim implementation. | +| checker compiler architecture | PASS | None | Confirmed agents derive constrained specs and Workstream owns deterministic compiled checker bundles. | +| checker compiler security/auth | PASS WITH LOW RISKS | None | Requested `admin` or `project_manager` approval of exact future extension code hash after validation and sandbox checks. Fixed. | +| checker compiler QA/test | PASS AFTER FIXES | None remaining | Requested proof for primitive allowlisting, unknown primitive rejection, canonical hash binding, immutable bundle behavior, no executable code fields by default, and future extension gate. Fixed. | +| checker compiler product/ops | PASS WITH LOW RISKS | None | Confirmed the workflow preserves setup-agent assistance, deterministic runtime checking, and admin/project_manager approval. | +| checker compiler docs | PASS AFTER FIXES | None remaining | Confirmed wording consistency and requested evidence refresh. Fixed by this evidence update. | ## Valid Findings Addressed @@ -51,6 +56,10 @@ After reviewed SHA `141ad11e42e96bf98d5c24fb77442d681d6698b1`, only review evide - Added ADR 0011 implementation enforcement contract without claiming the backend already enforces it. - Assigned UI/demo wording proof to a later frontend/demo chunk before ADR closure. - Added Chunk 4 schema/persistence proof that pre-submit feedback cannot store review decision values. +- Locked the default pre-submit path to constrained checker specifications and Workstream-compiled deterministic checker bundles, not unrestricted generated checker code. +- Added data model fields for `checker_spec`, `compiler_version`, `compiled_bundle_hash`, and immutable `compiled_bundle`. +- Added proof obligations for primitive allowlisting, unknown primitive rejection, canonical compiled bundle hashing, hash binding to `effective_submission_artifact_policy_hash`, immutable compiled bundle behavior, and absence of executable code fields by default. +- Tightened future executable-checker extension requirements to require static validation, generated tests, sandbox policy checks, no network, no shell, no secrets, no database access, and `admin` or `project_manager` approval of the exact locked code hash after those checks pass. ## Commands Run From 2bbddd6b7a861d1047318d7c2044e5a94c9b5b87 Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Tue, 23 Jun 2026 19:06:07 +0100 Subject: [PATCH 19/37] Address checker response contract review --- .agent-loop/LOOP_STATE.md | 9 +++++---- .../STATUS.md | 10 +++++----- .../reviews/WS-POL-001-01-external-review-response.md | 7 ++++--- docs/architecture_checker_framework.md | 4 +++- 4 files changed, 17 insertions(+), 13 deletions(-) diff --git a/.agent-loop/LOOP_STATE.md b/.agent-loop/LOOP_STATE.md index 047648f..c264a64 100644 --- a/.agent-loop/LOOP_STATE.md +++ b/.agent-loop/LOOP_STATE.md @@ -5,10 +5,10 @@ - Active initiative: `WS-POL-001` - Submission Artifact Policy Foundation - Active planning chunk: `WS-POL-001-01` - Submission Artifact Policy Foundation - Branch: `codex/submission-artifact-policy-loop-plan` -- Status: intent, discovery, plan, chunk map, and first chunk contract drafted; implementation has not started +- Status: planning review requested; implementation has not started - Merge commit: none for this initiative -- Reviewed code SHA: pending refresh after latest internal-review fixes -- Current gate: internal review evidence refresh before human review of plan and first chunk contract; backend implementation is not approved +- Reviewed code SHA: `0498bbe66468891c8285bb22b1365fee699c2f05` +- Current gate: human planning approval pending; backend implementation is not approved - Next chunk: inactive until `WS-POL-001-01` is approved and completed ## Operating Rule @@ -30,4 +30,5 @@ behavior. - PR #23 merged into `main` on 2026-06-20. - PR #24 updated post-merge loop memory on `main`. - PR #25 added Terminal Benchmark example material under `examples/`. -- Current planning branch has internal review evidence at `.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md`; evidence is being refreshed for the latest reviewed revision. +- Current planning branch has internal review evidence at `.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md`. +- External review response is tracked separately at `.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md`. diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md index 2939375..34e0858 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md @@ -2,17 +2,18 @@ ## Current Status -Planning PR open. +Planning review is requested, CI has passed, and latest external review feedback has been addressed. +Implementation has not started. ## Active Chunk -`WS-POL-001-01` is drafted for human review. Implementation has not started. +`WS-POL-001-01` is pending human planning approval. Implementation has not started. ## Chunk Status | Chunk | Status | Branch | PR | Notes | |---|---|---|---:|---| -| `WS-POL-001-01` | Planning PR open | `codex/submission-artifact-policy-loop-plan` | 26 | Awaiting human approval before implementation. | +| `WS-POL-001-01` | Pending human planning approval | `codex/submission-artifact-policy-loop-plan` | 26 | CI passed; external review response is recorded separately from internal review evidence. | | `WS-POL-001-02` | Planned | - | - | Starts after policy foundation lands. | | `WS-POL-001-03` | Planned | - | - | Moves submission creation to effective policy. | | `WS-POL-001-04` | Planned | - | - | Splits post-submit checker policy provenance. | @@ -22,8 +23,7 @@ Planning PR open. | Blocker | Owner | Next action | |---|---|---| -| Human approval of chunk sequence and first contract | User | Review PR #26. | -| Persisted policy provenance field names | User + Codex | Confirm during PR #26 review. | +| Human approval of chunk sequence and first contract | User | Review PR #26 and decide whether to merge. | ## Follow-Ups diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md index 1a99d89..8da9df3 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md @@ -29,7 +29,7 @@ Internal sub-agent results live in | Human review | Pre-submit failures should not use review decisions and should show pass/fail/warning details like the Snorkel-style static checker experience. | High | Fixed | Standardized `pre_submission_checker_failed` with structured pass/fail/warning details and explicit exclusion of `accept`, `needs_revision`, and `reject`. | | Human review | Current planning PR must be mergeable before implementation starts. | High | Fixed | Updated status, chunk map, chunk contract, proof obligations, and review evidence while keeping backend implementation inactive. | | CodeRabbit | ADR 0011 described pre-submit/review-decision separation but did not state how implementation must prove enforcement. | Major | Fixed | Added an implementation enforcement contract to ADR 0011. It explicitly says this PR is planning-only and lists the API, UI/demo, persistence, database, and chunk-level proof required before implementation chunks can close. | -| CodeRabbit latest review | Latest review reported no actionable comments. | Informational | Complete | CodeRabbit status passed after the final push. | +| CodeRabbit | `docs/architecture_checker_framework.md` made `pre_submission_checker_failed` read like the response type instead of the failure code inside `PreSubmitCheckResponse`. | Minor | Fixed | Reworded the checker framework to require `PreSubmitCheckResponse(status="failed", eligible_to_submit=false, failure_code="pre_submission_checker_failed", ...)` for blocking failures. | ## Commands To Re-Run After Push @@ -46,8 +46,9 @@ git diff --check ## Final External Review State ```text -agent-gates: pass +GitHub agent-gates check: pass +local agent gate result: REVIEW_REQUIRED, with internal review evidence supplied backend test: pass week1 demo UI: pass -CodeRabbit: pass, no actionable comments in latest review +CodeRabbit status: success after latest actionable comment was addressed ``` diff --git a/docs/architecture_checker_framework.md b/docs/architecture_checker_framework.md index 1294466..9396e00 100644 --- a/docs/architecture_checker_framework.md +++ b/docs/architecture_checker_framework.md @@ -201,7 +201,9 @@ Project policy adds required artifacts, evidence requirements, stricter forbidde The generated `PreSubmitCheckerPolicy` is persisted, hashed, and locked to the project guide version before workers submit packets. It runs before Workstream creates a submission. Blocking failures prevent submission creation and return -`pre_submission_checker_failed` with structured pass/fail/warning details. +`PreSubmitCheckResponse` with `status="failed"`, +`eligible_to_submit=false`, `failure_code="pre_submission_checker_failed"`, +and structured pass/fail/warning details. 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`. From 3c577ab4215d7f8fce9e2bf2d817f4fc270eb6c8 Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Tue, 23 Jun 2026 19:35:31 +0100 Subject: [PATCH 20/37] Match pre-submit response schema in checker docs --- docs/architecture_checker_framework.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/architecture_checker_framework.md b/docs/architecture_checker_framework.md index 9396e00..2c715ed 100644 --- a/docs/architecture_checker_framework.md +++ b/docs/architecture_checker_framework.md @@ -202,8 +202,9 @@ The generated `PreSubmitCheckerPolicy` is persisted, hashed, and locked to the project guide version before workers submit packets. It runs before Workstream creates a submission. Blocking failures prevent submission creation and return `PreSubmitCheckResponse` with `status="failed"`, -`eligible_to_submit=false`, `failure_code="pre_submission_checker_failed"`, -and structured pass/fail/warning details. +`eligible_to_submit=false`, and structured pass/fail/warning details in +`results`. The user-facing failure condition is +`pre_submission_checker_failed`; it 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`. From 151ba9aeee89a52eec909f8b039aafac321d8a4e Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Tue, 23 Jun 2026 20:15:21 +0100 Subject: [PATCH 21/37] Refresh response contract review evidence --- .agent-loop/LOOP_STATE.md | 2 +- .../STATUS.md | 2 +- .../WS-POL-001-01-external-review-response.md | 11 +++++------ .../WS-POL-001-01-internal-review-evidence.md | 14 ++++++++++---- 4 files changed, 17 insertions(+), 12 deletions(-) diff --git a/.agent-loop/LOOP_STATE.md b/.agent-loop/LOOP_STATE.md index c264a64..7cd124a 100644 --- a/.agent-loop/LOOP_STATE.md +++ b/.agent-loop/LOOP_STATE.md @@ -7,7 +7,7 @@ - Branch: `codex/submission-artifact-policy-loop-plan` - Status: planning review requested; implementation has not started - Merge commit: none for this initiative -- Reviewed code SHA: `0498bbe66468891c8285bb22b1365fee699c2f05` +- Reviewed code SHA: `3c577ab4215d7f8fce9e2bf2d817f4fc270eb6c8` - Current gate: human planning approval pending; backend implementation is not approved - Next chunk: inactive until `WS-POL-001-01` is approved and completed diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md index 34e0858..b5e5c88 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md @@ -2,7 +2,7 @@ ## Current Status -Planning review is requested, CI has passed, and latest external review feedback has been addressed. +Planning review is requested, and latest external review feedback has been addressed. Implementation has not started. ## Active Chunk diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md index 8da9df3..9f9e2cd 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md @@ -29,7 +29,7 @@ Internal sub-agent results live in | Human review | Pre-submit failures should not use review decisions and should show pass/fail/warning details like the Snorkel-style static checker experience. | High | Fixed | Standardized `pre_submission_checker_failed` with structured pass/fail/warning details and explicit exclusion of `accept`, `needs_revision`, and `reject`. | | Human review | Current planning PR must be mergeable before implementation starts. | High | Fixed | Updated status, chunk map, chunk contract, proof obligations, and review evidence while keeping backend implementation inactive. | | CodeRabbit | ADR 0011 described pre-submit/review-decision separation but did not state how implementation must prove enforcement. | Major | Fixed | Added an implementation enforcement contract to ADR 0011. It explicitly says this PR is planning-only and lists the API, UI/demo, persistence, database, and chunk-level proof required before implementation chunks can close. | -| CodeRabbit | `docs/architecture_checker_framework.md` made `pre_submission_checker_failed` read like the response type instead of the failure code inside `PreSubmitCheckResponse`. | Minor | Fixed | Reworded the checker framework to require `PreSubmitCheckResponse(status="failed", eligible_to_submit=false, failure_code="pre_submission_checker_failed", ...)` for blocking failures. | +| CodeRabbit | `docs/architecture_checker_framework.md` made `pre_submission_checker_failed` read like the response type instead of the failure condition represented by a failed pre-submit response. | Minor | Fixed | Reworded the checker framework to require `PreSubmitCheckResponse(status="failed", eligible_to_submit=false, results=[...])` for blocking failures, with `pre_submission_checker_failed` described as the user-facing failure condition rather than a response field. | ## Commands To Re-Run After Push @@ -46,9 +46,8 @@ git diff --check ## Final External Review State ```text -GitHub agent-gates check: pass -local agent gate result: REVIEW_REQUIRED, with internal review evidence supplied -backend test: pass -week1 demo UI: pass -CodeRabbit status: success after latest actionable comment was addressed +latest local agent gate result: REVIEW_REQUIRED, with internal review evidence supplied +latest local evidence gate: pass after evidence refresh +latest local loop memory, Markdown links, stale wording, and diff checks: pass +GitHub checks and CodeRabbit must be re-read after every push before merge ``` diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md index 2a3d6ba..58a9d40 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md @@ -10,13 +10,13 @@ valid findings addressed: yes ## Reviewed Revision -Reviewed code SHA: 0498bbe66468891c8285bb22b1365fee699c2f05 +Reviewed code SHA: 3c577ab4215d7f8fce9e2bf2d817f4fc270eb6c8 -Reviewed at: 2026-06-23T16:39:43Z +Reviewed at: 2026-06-23T19:08:10Z -Reviewer run IDs: 019ef3df-a4ae-71f0-b50c-dbd99e65af6c, 019ef3e0-cc78-7583-abd8-826f77b6d435, 019ef3e2-d1fc-7642-b079-561bf61b3d07, 019ef3e5-1e10-78f2-b272-f06200c50334, 019ef3e7-6f3d-7730-a2fd-adc55e496811, 019ef3ea-b44c-7741-9ced-b05bb6a5e5d2, 019ef432-a806-75c1-96ac-11c93eea2f9c, 019ef45d-540a-71e1-9531-19277d5450ed, 019ef45f-a5fa-7721-b9ae-aa39b1f6778e, 019ef462-b086-7923-a03e-78c298316f73, 019ef466-2433-7bf3-9335-069cfa5b5838, 019ef46a-171d-7b42-9795-773132754ff0, 019ef46e-dcea-7423-aa46-47a27b098c85, 019ef51b-8491-7192-a868-f2cbc1c56079, 019ef51d-cc5d-7d40-b5e6-0966c546e465, 019ef520-eea1-71c0-919a-63d24728ff32, 019ef523-f173-7e71-8685-902518610fda, 019ef52a-1da8-7df2-9428-c96b1b0cc164 +Reviewer run IDs: 019ef3df-a4ae-71f0-b50c-dbd99e65af6c, 019ef3e0-cc78-7583-abd8-826f77b6d435, 019ef3e2-d1fc-7642-b079-561bf61b3d07, 019ef3e5-1e10-78f2-b272-f06200c50334, 019ef3e7-6f3d-7730-a2fd-adc55e496811, 019ef3ea-b44c-7741-9ced-b05bb6a5e5d2, 019ef432-a806-75c1-96ac-11c93eea2f9c, 019ef45d-540a-71e1-9531-19277d5450ed, 019ef45f-a5fa-7721-b9ae-aa39b1f6778e, 019ef462-b086-7923-a03e-78c298316f73, 019ef466-2433-7bf3-9335-069cfa5b5838, 019ef46a-171d-7b42-9795-773132754ff0, 019ef46e-dcea-7423-aa46-47a27b098c85, 019ef51b-8491-7192-a868-f2cbc1c56079, 019ef51d-cc5d-7d40-b5e6-0966c546e465, 019ef520-eea1-71c0-919a-63d24728ff32, 019ef523-f173-7e71-8685-902518610fda, 019ef52a-1da8-7df2-9428-c96b1b0cc164, 019ef5c5-db38-76a1-8617-4572f7ebc7a2, 019ef5c7-2666-7e73-9147-4544265a3818, 019ef5c9-2749-75b2-819d-d7018f2b0e12, 019ef5cb-cc57-7151-b2ec-0f0d49ed0fb1 -After reviewed SHA `0498bbe66468891c8285bb22b1365fee699c2f05`, only review evidence artifacts changed. +After reviewed SHA `3c577ab4215d7f8fce9e2bf2d817f4fc270eb6c8`, only review evidence and loop status artifacts changed. ## Reviewer Results @@ -40,6 +40,10 @@ After reviewed SHA `0498bbe66468891c8285bb22b1365fee699c2f05`, only review evide | checker compiler QA/test | PASS AFTER FIXES | None remaining | Requested proof for primitive allowlisting, unknown primitive rejection, canonical hash binding, immutable bundle behavior, no executable code fields by default, and future extension gate. Fixed. | | checker compiler product/ops | PASS WITH LOW RISKS | None | Confirmed the workflow preserves setup-agent assistance, deterministic runtime checking, and admin/project_manager approval. | | checker compiler docs | PASS AFTER FIXES | None remaining | Confirmed wording consistency and requested evidence refresh. Fixed by this evidence update. | +| response-contract senior engineering | PASS AFTER FIXES | None remaining | Requested external review response wording to match the corrected `PreSubmitCheckResponse` shape. Fixed. | +| response-contract QA/test | PASS AFTER FIXES | None remaining | Verified the architecture doc matches `backend/app/modules/checkers/schemas.py` and requested evidence refresh. Fixed. | +| response-contract security/auth | PASS AFTER FIXES | None remaining | Confirmed pre-submit failure remains separate from review decisions and requested evidence refresh. Fixed. | +| response-contract product/ops | PASS AFTER FIXES | None remaining | Confirmed operator-facing wording is clear and requested external review artifact cleanup plus evidence refresh. Fixed. | ## Valid Findings Addressed @@ -60,6 +64,8 @@ After reviewed SHA `0498bbe66468891c8285bb22b1365fee699c2f05`, only review evide - Added data model fields for `checker_spec`, `compiler_version`, `compiled_bundle_hash`, and immutable `compiled_bundle`. - Added proof obligations for primitive allowlisting, unknown primitive rejection, canonical compiled bundle hashing, hash binding to `effective_submission_artifact_policy_hash`, immutable compiled bundle behavior, and absence of executable code fields by default. - Tightened future executable-checker extension requirements to require static validation, generated tests, sandbox policy checks, no network, no shell, no secrets, no database access, and `admin` or `project_manager` approval of the exact locked code hash after those checks pass. +- Corrected the checker framework response wording to match the current `PreSubmitCheckResponse` schema: `status`, `eligible_to_submit`, and `results`, with `pre_submission_checker_failed` treated as the user-facing failure condition rather than a response field. +- Corrected the external review response artifact so CodeRabbit feedback is tracked separately from internal review evidence and does not claim a nonexistent `failure_code` field in pre-submit responses. ## Commands Run From 9099b60533ba49eb3232fdf505dc17c69c8cbdad Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Wed, 24 Jun 2026 12:38:05 +0100 Subject: [PATCH 22/37] Tighten submission policy planning contract --- .../CHUNK_MAP.md | 93 ++++--- .../DECISIONS.md | 12 +- .../DISCOVERY.md | 4 +- .../INTENT.md | 30 ++- .../PLAN.md | 93 ++++--- ...1-submission-artifact-policy-foundation.md | 74 ++++-- .../WS-POL-001-01-external-review-response.md | 10 +- docs/architecture_checker_framework.md | 17 +- docs/architecture_data_model.md | 251 ++++++++++++++++-- docs/architecture_lifecycle_state_machine.md | 13 +- docs/architecture_lockdown.md | 15 +- docs/current_system_data_flow.html | 4 +- ...ion_0003_project_guides_are_first_class.md | 9 +- ...ssion_artifact_policy_drives_pre_submit.md | 105 +++++++- docs/glossary.md | 8 +- docs/operations_project_operating_manual.md | 23 +- .../operations_workspace_packet_convention.md | 11 +- docs/product_first_user_flows.md | 25 +- docs/roadmap_day_by_day_execution_plan.md | 5 +- docs/roadmap_implementation_backlog.md | 2 +- docs/spec_chunk_3_project_guide_foundation.md | 10 +- ...ec_chunk_5_submission_packet_foundation.md | 12 +- docs/spec_chunk_6_checker_contract_records.md | 18 +- docs/spec_chunk_7_checker_runner_registry.md | 22 +- ...k_8_submission_artifact_policy_checkers.md | 24 +- docs/spec_week2_checker_framework.md | 14 +- docs/template_checker_policy.md | 18 +- docs/template_preflight_evidence.md | 2 +- docs/template_project_guide.md | 10 +- docs/template_submission_artifact_policy.md | 53 +++- docs/template_submission_packet.md | 10 +- 31 files changed, 741 insertions(+), 256 deletions(-) diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md index 30b9587..3abfccd 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md @@ -17,6 +17,9 @@ - Agents derive constrained policy and checker specifications. Workstream compiles deterministic checker bundles. Unrestricted generated checker code is not the default path. +- Reports, derived policies, acknowledgements, effective policies, task + bindings, and checker bundles bind to immutable `GuideSourceSnapshot` + id/hash, not only to `guide_version`. ## Chunks @@ -24,10 +27,11 @@ Goal: -Add first-class guide sufficiency, `SubmissionArtifactPolicy`, effective policy, -and persisted `PreSubmitCheckerPolicy` backend records and schemas. Define -Workstream default submission artifact rules in code and validate that project -policy cannot weaken defaults. +Add first-class guide-source snapshot, guide sufficiency, +`SubmissionArtifactPolicy`, effective project policy, and activation guard +backend records and schemas. Define Workstream default submission artifact rules +and the deterministic project-policy merge contract. Do not move task runtime or +checker compiler behavior yet. Risk: @@ -63,34 +67,43 @@ full async agent execution runtime Acceptance criteria: - Dedicated submission artifact policy model/table exists. +- Dedicated immutable guide source snapshot model/table exists. - Dedicated guide sufficiency report model/table exists. - Guide sufficiency report supports `passed`, `blocked`, and `passed_with_warnings`. - Project policy is scoped to project id + guide version. +- Guide sufficiency report, project policy, and effective project policy bind to + `source_snapshot_id` and `source_snapshot_hash`. - Project policy records are Workstream-derived and approved by `admin` or `project_manager`, not direct project owner-authored schema. - Workstream default policy is represented in code. -- Effective policy merge rejects attempts to weaken defaults. +- Deterministic merge rules are represented in code for union, intersection, + logical OR, minimum limit, platform-locked hash algorithm, and restrictive + packaging merges. +- Effective project policy merge rejects attempts to weaken defaults. +- Required artifacts or evidence that match forbidden rules block project setup. - Effective submission artifact policy hash is persisted for the guide version. -- Generated `PreSubmitCheckerPolicy` snapshot/hash is persisted and locked to - the guide version. -- Generated `PreSubmitCheckerPolicy` is a compiled deterministic checker bundle - from approved primitives, not unrestricted generated code. +- Approved and superseded policy rows are immutable; changes create a new + revision with a supersedes pointer. - Guide activation requires passing or acknowledged guide sufficiency, approved - submission artifact policy, effective policy hash, and persisted generated - pre-submit checker policy. -- Project-owner source refs are sanitized and cannot contain signed URLs, - query-bearing refs, credential-bearing refs, or local filesystem paths. + submission artifact policy, and effective project policy hash bound to the + current guide source snapshot. +- Project-owner source refs persist as sanitized snapshot refs and cannot store + signed URLs, credential-bearing refs, token-bearing refs, or local filesystem + paths. Approved adapters can use ordinary URL query parameters only as + temporary fetch locators. - Embedded instructions in guide material cannot grant tool authority or weaken Workstream default policy. -- Transitional `evidence_policy`, `required_files`, and `required_evidence` are - replaced, not preserved as compatibility aliases. +- Legacy `evidence_policy`, `required_files`, and `required_evidence` are not + treated as compatibility contracts. Runtime removal happens in the task + binding and submission migration chunks. Verification: - Postgres-backed FastAPI/API tests cover policy create/update, guide sufficiency activation blocking, warning acknowledgement, default weakening - rejection, source-ref sanitization, and pre-submit policy locking. + rejection, source snapshot binding, source-ref sanitization, append-only + approved rows, and effective project policy hash persistence. - Unit/service tests may cover deterministic merge helpers, but API-visible behavior must be proven through the FastAPI path. @@ -108,9 +121,9 @@ Chunk 1 limited to records/contracts/activation guards. Goal: -Run `ProjectGuideSufficiencyAgent` and -`SubmissionArtifactPolicyDerivationAgent` asynchronously against open-ended -project guide material. +Run `ProjectGuideSufficiencyAgent`, +`SubmissionArtifactPolicyDerivationAgent`, and the trusted checker compiler +asynchronously against immutable guide-source snapshots. Risk: @@ -141,7 +154,7 @@ payment/reputation/blockchain code Acceptance criteria: - `ProjectGuideSufficiencyAgent` runs async and produces a persisted - sufficiency report for a guide version. + sufficiency report for a guide source snapshot. - Blocking guide gaps stop activation and create project-owner clarification requests. - Warnings can be acknowledged only by `admin` or `project_manager`. @@ -150,7 +163,9 @@ Acceptance criteria: - Derived policy cannot weaken Workstream defaults. - Derived checker specification uses only approved Workstream primitives. - Trusted checker compiler produces deterministic `PreSubmitCheckerPolicy` - snapshot/hash from the approved specification. + project-level contract snapshot/hash from the approved specification. +- Derived report, project policy, effective project policy, and compiler output + are invalidated by a new guide source snapshot. - Malicious guide text, embedded prompt-injection instructions, and unsafe source refs cannot influence agent authority, fetch behavior, or default policy strength. @@ -163,10 +178,10 @@ Verification: clarification requests, warning acknowledgement, derivation job output, unsafe source-ref rejection, and default weakening rejection. - Background execution tests prove jobs are async and idempotent for a guide - version. + source snapshot. - Compiler tests prove allowed primitive emission, unknown primitive rejection, byte-stable same-input same-compiler-version bundle hashing, hash binding to - `effective_submission_artifact_policy_hash`, and client/worker inability to + `effective_project_submission_artifact_policy_hash`, and client/worker inability to supply checker names, severities, versions, outcomes, compiler version, or compiled bundles. @@ -180,12 +195,13 @@ Human review focus: Async job boundaries, sufficiency severity behavior, and clarification request shape. -### WS-POL-001-03: Submission Creation Uses Effective Policy +### WS-POL-001-03: Task Policy Binding And Submission Creation Goal: -Move submission creation pre-submit gate from transitional task fields to the -effective submission artifact policy and generated pre-submit checker policy. +Add approved task artifact bindings, compute effective task submission artifact +policy, generate the task-level pre-submit checker bundle, and move submission +creation from transitional task fields to that locked task policy. Risk: @@ -198,6 +214,7 @@ Depends on: Allowed files: ```text +backend/alembic/versions/** backend/app/modules/tasks/** backend/app/modules/checkers/** backend/tests/test_submissions.py @@ -216,10 +233,24 @@ frontend Acceptance criteria: +- `ApprovedTaskArtifactBinding` exists and selects an approved artifact profile + plus constrained task parameters. +- Task bindings can add or tighten requirements, but cannot weaken platform + defaults or the effective project policy. +- `EffectiveTaskSubmissionArtifactPolicy` is generated from effective project + policy plus task binding and locked before `SCREENING` or `READY`. +- Task-level generated `PreSubmitCheckerPolicy` is persisted with + `compiled_bundle` as canonical JSON source of truth and `compiled_bundle_hash` + as its canonical hash. +- Transitional `required_files` and `required_evidence` are replaced for + submission runtime and are not compatibility aliases. - Blocking pre-submit failure creates no submission row, submission version, submitted transition, or durable checker run. -- Blocking pre-submit failure returns `pre_submission_checker_failed` with - structured pass/fail/warning details, not review decision values. +- `POST /tasks/{id}/submission-precheck` returns `200 PreSubmitCheckResponse` + with `status`, `eligible_to_submit`, and `results`. +- `POST /tasks/{id}/submissions` returns + `422 DomainError(code="pre_submission_checker_failed")` with structured + pass/fail/warning details when blocking pre-submit fails. - Passing pre-submit creates a submission stamped with locked policy context. Verification: @@ -227,6 +258,8 @@ Verification: - Postgres-backed FastAPI/API tests cover clean submission, blocking pre-submit failure, no-row/no-version/no-transition/no-durable-checker side effects, and stamped locked policy context. +- Postgres-backed task tests cover task binding merge, weakening rejection, + task policy hash locking, and removal of transitional task-field authority. Required reviewers: @@ -235,8 +268,8 @@ reuse/dedup, test delta. Human review focus: -No-row/no-version/no-transition guarantee and `pre_submission_checker_failed` -feedback shape. +Task-specific artifact binding, no-row/no-version/no-transition guarantee, and +preflight-versus-submission-create failure shape. ### WS-POL-001-04: PostSubmitCheckerPolicy Split diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md index 0487226..c33bd9a 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md @@ -23,14 +23,16 @@ with internal agent assistance allowed, then requires approval by `admin` or `project_manager` before guide activation. - Workstream default submission artifact rules are non-bypassable. -- `EffectiveSubmissionArtifactPolicy` is default plus project policy. +- `EffectiveProjectSubmissionArtifactPolicy` is default plus project policy. +- `EffectiveTaskSubmissionArtifactPolicy` is effective project policy plus an + approved task artifact binding. - Workstream's trusted checker compiler turns the constrained checker specification into deterministic `PreSubmitCheckerPolicy`, persisted and - locked to the project guide version. + locked to the effective task policy hash. - Pre-submit checks block before submission creation. -- Blocking pre-submit feedback is `pre_submission_checker_failed` with - structured pass/fail/warning details; it is not `accept`, `needs_revision`, - or `reject`. +- Preflight feedback is `PreSubmitCheckResponse`; blocked submission-create + attempts return `pre_submission_checker_failed` with structured + pass/fail/warning details. Neither is `accept`, `needs_revision`, or `reject`. - Post-submit/internal checks remain separate from pre-submit checks. - Worker-facing task outcomes remain simple; internal routes stay internal. - Stored review decision values remain exactly `accept`, `needs_revision`, and diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DISCOVERY.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DISCOVERY.md index f0e996d..6bbc11e 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DISCOVERY.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DISCOVERY.md @@ -10,7 +10,9 @@ The architecture docs already lock the target model: ```text SubmissionArtifactPolicy -> GuideSufficiencyReport --> EffectiveSubmissionArtifactPolicy +-> EffectiveProjectSubmissionArtifactPolicy +-> ApprovedTaskArtifactBinding +-> EffectiveTaskSubmissionArtifactPolicy -> persisted and locked PreSubmitCheckerPolicy -> pre-submit checks before submission creation -> post-submit/internal checks after submission lock diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md index 2231c6b..8ad1db9 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md @@ -31,9 +31,13 @@ Project owner material WorkstreamDefaultSubmissionArtifactPolicy + ProjectSubmissionArtifactPolicy -= EffectiveSubmissionArtifactPolicy += EffectiveProjectSubmissionArtifactPolicy -EffectiveSubmissionArtifactPolicy +EffectiveProjectSubmissionArtifactPolicy ++ ApprovedTaskArtifactBinding += EffectiveTaskSubmissionArtifactPolicy + +EffectiveTaskSubmissionArtifactPolicy -> constrained pre-submit checker specification -> trusted Workstream checker compiler -> persisted and locked PreSubmitCheckerPolicy @@ -95,13 +99,17 @@ After this initiative: - `SubmissionArtifactPolicy` is Workstream-derived from project material and approved by `admin` or `project_manager`, not authored directly by the project owner. -- `GuideSufficiencyReport` is a first-class record tied to a project guide - version. +- `GuideSourceSnapshot` is a first-class immutable record for the exact guide + material Workstream evaluated. +- `GuideSufficiencyReport` is a first-class record tied to a guide source + snapshot. - Workstream default submission artifact rules are defined in code. - Project submission artifact policy cannot weaken Workstream defaults. -- Effective submission artifact policy is computed deterministically. -- Generated pre-submit checker policy is persisted and locked to the project - guide version. +- Effective project submission artifact policy is computed deterministically. +- Approved task artifact bindings produce task-specific effective submission + artifact policy hashes. +- Generated pre-submit checker policy is persisted and locked to the effective + task policy hash. - Generated pre-submit checker policy is produced by Workstream's trusted compiler from approved checker primitives, not by unrestricted generated code. - Submission creation uses the generated pre-submit policy before a submission @@ -133,9 +141,11 @@ simple. Stored review decision values remain exactly `accept`, `needs_revision`, and `reject`; display labels may render those as accepted, needs revision, and rejected where appropriate. -Pre-submit feedback is not review. A blocking pre-submit result is presented as -`pre_submission_checker_failed` with structured pass/fail/warning details. It -does not create a submission and must not use review decision values. +Pre-submit feedback is not review. Preflight failures return +`PreSubmitCheckResponse` with structured pass/fail/warning details. A blocked +submission-create attempt returns `pre_submission_checker_failed` with those +details. It does not create a submission and must not use review decision +values. ## Human Judgment Required diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md index 39fcd58..25381f0 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md @@ -18,6 +18,9 @@ The product model is: ProjectGuide open-ended human-facing project material +GuideSourceSnapshot + immutable capture of the exact guide/source bytes Workstream evaluated + GuideSufficiencyReport Workstream-owned assessment of whether the guide is sufficient @@ -27,9 +30,15 @@ WorkstreamDefaultSubmissionArtifactPolicy ProjectSubmissionArtifactPolicy Workstream-derived, admin-or-project-manager-approved machine-readable intake rules -EffectiveSubmissionArtifactPolicy +EffectiveProjectSubmissionArtifactPolicy deterministic merge of default + project policy +ApprovedTaskArtifactBinding + Workstream-approved task-specific artifact profile and constrained parameters + +EffectiveTaskSubmissionArtifactPolicy + deterministic merge of effective project policy + approved task binding + PreSubmitCheckerPolicy persisted and locked checker rules for draft packet intake @@ -46,15 +55,23 @@ actor with the `admin` or `project_manager` role. Project owner material is always treated as untrusted data. Internal agents must not execute embedded instructions from guide text, URLs, repository docs, or examples. Fetching source material must use approved adapters or allowlisted -retrieval paths, reject signed URLs, query-bearing refs, credential-bearing refs, -and local filesystem paths, and persist only sanitized source refs. +retrieval paths. Temporary fetch locators can include ordinary URL query +parameters when an approved adapter needs them, but signed URLs, +credential-bearing refs, token-bearing refs, and local filesystem paths are +rejected. Workstream persists only immutable `GuideSourceSnapshot` records with +opaque sanitized source refs, content hash, optional future content id, adapter +name, and capture timestamp. It never persists signed URLs, credentials, or +token-bearing locators as durable source identity. `SubmissionArtifactPolicyDerivationAgent` derives machine-readable `ProjectSubmissionArtifactPolicy` after guide sufficiency passes. A Workstream actor with the `admin` or `project_manager` role approves the derived policy. -Workstream then computes the effective policy and persists the generated -`PreSubmitCheckerPolicy` snapshot/hash locked to the guide version. Pre-submit -checks run before submission creation and do not create durable checker records. +Workstream then computes the effective project policy and later combines it +with approved task-specific artifact bindings to produce an +`EffectiveTaskSubmissionArtifactPolicy` locked before a task enters +`SCREENING` or `READY`. The generated `PreSubmitCheckerPolicy` snapshot/hash is +locked to that effective task policy. Pre-submit checks run before submission +creation and do not create durable checker records. Post-submit/internal checks run after submission lock and do create durable checker records. @@ -65,12 +82,20 @@ the deterministic `PreSubmitCheckerPolicy` bundle. Runtime checks execute the locked compiled bundle against staged artifact hashes or future content identifiers. -If no passing or acknowledged guide sufficiency report, approved project -submission artifact policy, effective policy hash, and persisted generated -pre-submit checker policy exist for the guide version, guide activation fails -and tasks using that guide cannot enter the ready worker pipeline. The system -must surface setup failure internally as task/project setup incomplete rather -than letting workers discover missing intake rules at submit time. +If no immutable guide-source snapshot, passing or acknowledged guide sufficiency +report, approved project submission artifact policy, and effective project +policy hash exist for the guide snapshot and guide version, guide activation +fails. If no approved task artifact binding, effective task policy hash, and +task-level pre-submit checker bundle exist, the task cannot enter the ready +worker pipeline. The system must surface setup failure internally as +task/project setup incomplete rather than letting workers discover missing +intake rules at submit time. + +Reports, derived policies, acknowledgements, effective policies, and checker +bundles bind to the exact `GuideSourceSnapshot` id/hash, not only to +`guide_version`. Any guide or source-material change creates a new snapshot and +invalidates prior sufficiency reports, derived project policies, effective +policies, checker bundles, acknowledgements, and approvals for activation. ## Alternatives Considered @@ -79,7 +104,7 @@ than letting workers discover missing intake rules at submit time. Rejected because it leaves too much room for project drift and unfair worker feedback. -### Use project guide `evidence_policy` as the long-term object +### Keep legacy `ProjectGuide.evidence_policy` as the long-term object Rejected because the name is too narrow. The policy governs artifacts, hashes, storage references, packaging, forbidden files, and attestation, not only @@ -124,8 +149,10 @@ while post-submit answers whether a locked submission can move to human review. checker code is not the default path. - Source-material security: project-owner docs, URLs, examples, and repository docs are untrusted input; embedded tool instructions, prompt-injection text, - credential-bearing refs, signed URLs, query-bearing refs, and local filesystem - paths cannot become policy authority. + credential-bearing refs, signed URLs, token-bearing refs, and local filesystem + paths cannot become policy authority. Ordinary URL query parameters are + allowed only as temporary inputs to approved retrieval adapters and are not + persisted as durable source identity. - Payment/execution: no payment or contribution records in this initiative. - Persistence/data: schema changes land through Alembic and async SQLAlchemy. - Presentation/API: backend-first; no frontend implementation. @@ -133,26 +160,31 @@ while post-submit answers whether a locked submission can move to human review. ## Rollout/Migration Strategy -1. Add dedicated guide sufficiency, submission artifact policy, effective - policy, and pre-submit policy records. +1. Add dedicated guide source snapshot, guide sufficiency, submission artifact + policy, and effective project policy records. 2. Replace transitional `evidence_policy`, `required_files`, and `required_evidence` usage; no v0.1 compatibility alias is required. 3. Add the Workstream-owned derivation/approval boundary for project policy. -4. Compute effective policy in service code and validate defaults cannot weaken. -5. Persist generated pre-submit checker policy snapshot/hash for the guide - version. -6. Add async guide sufficiency and policy derivation execution. -7. Migrate submission creation to the locked generated pre-submit policy. +4. Compute effective project policy in service code and validate defaults cannot weaken. +5. Add async guide sufficiency, policy derivation execution, and trusted checker + compiler behavior. +6. Add approved task artifact bindings and effective task policy locking. +7. Migrate submission creation from transitional task fields to the locked task + policy and generated pre-submit checker bundle. 8. Split post-submit checker policy naming/provenance. ## Verification Strategy -- Unit-level policy merge tests for default + project policy. +- Unit-level policy merge tests for default + project policy and effective + project policy + task artifact binding. - Postgres-backed API tests for guide sufficiency report, project policy - creation, generated pre-submit policy persistence, and guide activation. + creation, immutable source snapshots, effective project policy persistence, + and guide activation. - Tests proving a guide cannot activate without passing or acknowledged guide - sufficiency, approved project submission artifact policy, effective policy - hash, and persisted generated pre-submit checker policy. + sufficiency bound to the current source snapshot, approved project submission + artifact policy, and effective project policy hash. +- Tests proving a task cannot enter `READY` without an approved task artifact + binding, effective task policy hash, and generated pre-submit checker bundle. - Tests proving malicious or credential-bearing source material cannot weaken Workstream defaults, grant tool authority, or persist unsafe source refs. - Submission API tests proving blocking pre-submit failure creates no submission @@ -177,7 +209,8 @@ CI integrity is required only for chunks that touch workflows or test tooling. ## Sequencing -Start with guide/policy bundle foundation. Do not start submission runtime -rewiring until the guide sufficiency report, project policy object, defaults, -effective policy hash, persisted generated pre-submit checker policy, and -activation guards are accepted. +Start with guide/source/policy bundle foundation. Do not start submission +runtime rewiring until immutable guide-source snapshots, guide sufficiency +reports, project policy objects, defaults, effective project policy hash, +approved task artifact bindings, effective task policy hash, generated +pre-submit checker bundle, and activation/ready guards are accepted. diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md index c91fcf6..c0a9c7d 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md @@ -6,10 +6,11 @@ WS-POL-001 - Submission Artifact Policy Foundation ## Goal -Add first-class backend support for guide sufficiency reports, -`SubmissionArtifactPolicy`, effective policy hashes, and persisted generated -`PreSubmitCheckerPolicy` snapshots without rewiring submission creation or -durable checker execution yet. +Add first-class backend support for immutable guide-source snapshots, guide +sufficiency reports, `SubmissionArtifactPolicy`, effective project policy +hashes, append-only approval lifecycle, and activation guards without rewiring +submission creation, task runtime, checker compiler behavior, or durable checker +execution yet. ## Why This Chunk Exists @@ -20,20 +21,20 @@ deterministic. Project owners must not be asked to author the Workstream policy schema directly. They provide open-ended project guide material. Workstream records -guide sufficiency, derives project submission artifact policy, persists the -effective policy hash, persists the generated pre-submit checker policy -snapshot/hash, and a Workstream actor with the `admin` or `project_manager` role -approves the bundle before guide activation. +guide-source snapshots, guide sufficiency, project submission artifact policy, +effective project policy hash, and a Workstream actor with the `admin` or +`project_manager` role approves the bundle before guide activation. The generated pre-submit checker policy is deterministic compiled policy, not -unrestricted generated checker code. Agents derive constrained checker -specifications; Workstream's trusted compiler produces the locked checker -bundle. +unrestricted generated checker code. This first chunk defines the record +contract and activation dependency; the async derivation and trusted compiler +behavior land in the next chunk. Project owner material is untrusted input. Guide text, URLs, repository docs, examples, and imported documents cannot grant tool authority, override -Workstream rules, or weaken default checks. Source refs must be sanitized before -persistence. +Workstream rules, or weaken default checks. Approved adapters can use temporary +fetch locators for source ingestion, but durable source identity must be an +immutable `GuideSourceSnapshot` with sanitized source ref and content hash. ## Approved Plan Reference @@ -85,22 +86,31 @@ human review implementation - Schemas only define API input/output contracts and validation shape. - Full async agent execution is not part of this chunk. This chunk models the records/contracts and activation guard those agents will use. +- Trusted checker compiler behavior is not part of this chunk. This chunk + models the persisted fields and invariants later compiler output must satisfy. ## Acceptance Criteria - [ ] Dedicated `SubmissionArtifactPolicy` model/table exists. +- [ ] Dedicated immutable `GuideSourceSnapshot` model/table exists. - [ ] Dedicated `GuideSufficiencyReport` model/table exists. - [ ] Guide sufficiency report records `passed`, `blocked`, or `passed_with_warnings`. +- [ ] Guide sufficiency report binds to `source_snapshot_id` and + `source_snapshot_hash`. - [ ] Blocking guide sufficiency findings prevent guide activation. - [ ] Warning guide sufficiency findings require `admin` or `project_manager` acknowledgement before guide activation. -- [ ] Project-owner source refs are sanitized and reject signed URLs, - query-bearing refs, credential-bearing refs, and local filesystem paths. +- [ ] Durable source snapshot refs are sanitized and reject signed URLs, + credential-bearing refs, token-bearing refs, and local filesystem paths. +- [ ] Approved retrieval adapters can use ordinary URL query parameters only as + temporary fetch locators and never persist them as durable source + authority. - [ ] Embedded instructions in guide material cannot grant tool authority or weaken Workstream default policy. - [ ] Policy rows are scoped by `project_id` and `guide_version`. - [ ] Policy rows have a composite foreign key to `project_guides(project_id, version)`. +- [ ] Policy rows bind to `source_snapshot_id` and `source_snapshot_hash`. - [ ] Pydantic input/output schemas exist for project submission artifact policy. - [ ] Project service can create/update the policy with a draft guide. - [ ] Project policy records include approval provenance showing the approved @@ -113,24 +123,28 @@ human review implementation - [ ] Guide activation requires valid submission artifact policy. - [ ] Workstream default submission artifact policy is represented in code. - [ ] Workstream default policy requires `sha256:<64 lowercase hex>` artifact hashes where production hashes are required. -- [ ] Workstream default policy rejects raw signed URLs, query strings, local filesystem paths, credential-bearing references, and token-bearing storage references before persistence. +- [ ] Persisted artifact/storage refs reject raw signed URLs, query strings, + local filesystem paths, credential-bearing references, and token-bearing + storage references before persistence. - [ ] Workstream default policy blocks default-forbidden secret/token artifacts even when a project policy lists them as required. -- [ ] Effective policy merge rejects project policy that weakens defaults. +- [ ] Effective project policy merge implements deterministic rules for union, + intersection, logical OR, minimum limit, platform-locked hash algorithm, + and restrictive packaging merges. +- [ ] Effective project policy merge rejects project policy that weakens defaults. +- [ ] Required artifact or evidence rules that match forbidden rules block + project setup as conflicts. - [ ] Effective submission artifact policy hash is persisted for the guide version. -- [ ] Generated `PreSubmitCheckerPolicy` snapshot/hash is persisted and locked to the guide version. -- [ ] Generated `PreSubmitCheckerPolicy` stores a constrained checker spec, - compiler version, compiled bundle hash, and immutable compiled bundle. -- [ ] Generated checker bundle uses approved primitives rather than unrestricted - generated code. -- [ ] Transitional `evidence_policy`, `required_files`, and `required_evidence` are replaced, not kept as compatibility aliases. +- [ ] Approved and superseded policy/effective-policy rows are immutable. +- [ ] Changing an approved policy creates a new revision with a supersedes + pointer. +- [ ] Legacy `evidence_policy`, `required_files`, and `required_evidence` are + not treated as compatibility aliases. Runtime replacement of task fields + happens in the task binding and submission migration chunk. - [ ] Postgres-backed FastAPI/API tests cover create/update, blocking activation from guide sufficiency gaps, `admin`/`project_manager` warning acknowledgement, approval provenance fields, default weakening, - source-ref sanitization, and pre-submit policy locking. -- [ ] Tests prove primitive allowlisting, unknown primitive rejection, - canonical compiled bundle hashing, hash binding to - `effective_submission_artifact_policy_hash`, immutable compiled bundle - behavior, and absence of executable code fields in the default path. + source snapshot binding, source-ref sanitization, append-only rows, and + effective project policy hash persistence. ## Verification Commands @@ -171,9 +185,11 @@ Conditional: ## Human Review Focus - Are the guide sufficiency report fields precise enough? +- Are the guide source snapshot fields precise enough? - Are the persisted provenance field names precise enough? - Does this chunk stay limited to records/contracts/activation guard, leaving - full async agent execution for the next chunk? + full async agent execution, trusted compiler behavior, task binding, and + submission runtime migration for later chunks? ## Stop Conditions diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md index 9f9e2cd..ef5ce5e 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md @@ -25,11 +25,19 @@ Internal sub-agent results live in | CodeRabbit | `WS-POL-001-03` acceptance criteria repeated no-side-effect wording. | Low | Fixed | Consolidated the no-row, no-version, no-transition, and no-durable-checker-run guarantee without weakening it. | | Human review | Project owners must not author or approve Workstream internal `SubmissionArtifactPolicy`; Workstream derives it from open-ended project material and `admin` or `project_manager` approves the internal bundle. | High | Fixed | Updated planning artifacts, ADRs, glossary, architecture docs, specs, templates, operating manual, data flow, and first user flows. | | Human review | Project-guide material is open-ended, not a fixed checklist; Workstream must run sufficiency and derivation agents internally. | High | Fixed | Added `ProjectGuideSufficiencyAgent`, `GuideSufficiencyReport`, and `SubmissionArtifactPolicyDerivationAgent` to the plan, ADR, data model, lifecycle, templates, and chunk map. | -| Human review | `PreSubmitCheckerPolicy` must be persisted and locked to the guide version, not derived on read. | High | Fixed | Updated plan, ADRs, data model, lifecycle, checker flow, and chunk contracts to require persisted snapshot/hash and locked effective policy hash. | +| Human review | `PreSubmitCheckerPolicy` must be persisted and locked, not derived on read. | High | Fixed | Updated plan, ADRs, data model, lifecycle, checker flow, and chunk contracts to require persisted snapshot/hash. Later review refined the lock target from guide version to effective task policy hash. | | Human review | Pre-submit failures should not use review decisions and should show pass/fail/warning details like the Snorkel-style static checker experience. | High | Fixed | Standardized `pre_submission_checker_failed` with structured pass/fail/warning details and explicit exclusion of `accept`, `needs_revision`, and `reject`. | | Human review | Current planning PR must be mergeable before implementation starts. | High | Fixed | Updated status, chunk map, chunk contract, proof obligations, and review evidence while keeping backend implementation inactive. | | CodeRabbit | ADR 0011 described pre-submit/review-decision separation but did not state how implementation must prove enforcement. | Major | Fixed | Added an implementation enforcement contract to ADR 0011. It explicitly says this PR is planning-only and lists the API, UI/demo, persistence, database, and chunk-level proof required before implementation chunks can close. | | CodeRabbit | `docs/architecture_checker_framework.md` made `pre_submission_checker_failed` read like the response type instead of the failure condition represented by a failed pre-submit response. | Minor | Fixed | Reworded the checker framework to require `PreSubmitCheckResponse(status="failed", eligible_to_submit=false, results=[...])` for blocking failures, with `pre_submission_checker_failed` described as the user-facing failure condition rather than a response field. | +| Human review | Downstream reports and policies were bound to `guide_version` but not the exact guide/source snapshot. | High | Fixed | Added `GuideSourceSnapshot`, `source_snapshot_id`, and `source_snapshot_hash` to the plan, ADR, data model, chunk map, chunk contract, and templates. Guide/source changes now invalidate reports, policies, acknowledgements, approvals, effective policies, and checker bundles. | +| Human review | Chunk 1 claimed task/checker runtime removals while forbidding task/checker modules. | High | Fixed | Re-scoped Chunk 1 to guide-source snapshots, project policy records, effective project policy merge, append-only lifecycle, and activation guards. Moved compiler behavior to Chunk 2 and task-field/runtime migration to Chunk 3. | +| Human review | Project-level policy alone cannot represent task-specific artifact requirements. | High | Fixed | Added `ApprovedTaskArtifactBinding` and `EffectiveTaskSubmissionArtifactPolicy`, with task-specific binding locked before `SCREENING` or `READY`. | +| Human review | Effective policy merge semantics were not executable enough. | High | Fixed | Added per-field deterministic merge rules for union, intersection, logical OR, minimum limits, platform-locked hash algorithm, restrictive packaging merge, and setup-conflict blocking. | +| Human review | URL ingestion and durable source identity were conflated. | Medium | Fixed | Split temporary approved-adapter fetch locators from durable sanitized source refs. Ordinary URL query parameters can be used for approved retrieval; signed URLs, credentials, token-bearing refs, and local paths cannot be persisted as source identity. | +| Human review | API contract for `pre_submission_checker_failed` was ambiguous. | High | Fixed | Locked separate paths: preflight returns `200 PreSubmitCheckResponse`; blocked submission creation returns `422 DomainError(code="pre_submission_checker_failed")` with structured details. | +| Human review | Approved policies and compiled bundles needed append-only lifecycle rules. | High | Fixed | Added `draft -> approved -> superseded` lifecycle, immutable approved/superseded rows, supersedes pointers, and `compiled_bundle` as canonical JSON source of truth with derived index projections only. | +| Human review | PR body still asked whether `evidence_policy` should remain as a compatibility alias and whether pre-submit policy should derive on read. | Medium | Fixed | Removed stale human-review questions from the PR body. The current plan says no `evidence_policy` compatibility alias and no derive-on-read runtime path. | ## Commands To Re-Run After Push diff --git a/docs/architecture_checker_framework.md b/docs/architecture_checker_framework.md index 2c715ed..ac24ad7 100644 --- a/docs/architecture_checker_framework.md +++ b/docs/architecture_checker_framework.md @@ -101,11 +101,11 @@ Ensures a task has rubric or acceptance criteria. ### check_required_files -Validates required submission artifacts from the effective submission artifact policy. +Validates required submission artifacts from the effective task submission artifact policy. ### check_forbidden_files -Blocks known forbidden artifacts, secrets, private keys, copied internal data, or artifacts forbidden by the effective submission artifact policy. +Blocks known forbidden artifacts, secrets, private keys, copied internal data, or artifacts forbidden by the effective task submission artifact policy. Default forbidden patterns include: @@ -163,9 +163,12 @@ The deterministic chain is: ```text ProjectGuide +-> GuideSourceSnapshot -> GuideSufficiencyReport -> ProjectSubmissionArtifactPolicy --> EffectiveSubmissionArtifactPolicy +-> EffectiveProjectSubmissionArtifactPolicy +-> ApprovedTaskArtifactBinding +-> EffectiveTaskSubmissionArtifactPolicy -> constrained PreSubmitCheckerSpec -> trusted Workstream checker compiler -> PreSubmitCheckerPolicy @@ -199,11 +202,11 @@ Workstream default submission artifact rules require: Project policy adds required artifacts, evidence requirements, stricter forbidden artifacts, stricter packaging rules, and project-specific attestation requirements. The generated `PreSubmitCheckerPolicy` is persisted, hashed, and locked to the -project guide version before workers submit packets. It runs before Workstream -creates a submission. Blocking failures prevent submission creation and return +effective task submission artifact policy before workers submit packets. It +runs before Workstream creates a submission. Preflight failures return `PreSubmitCheckResponse` with `status="failed"`, `eligible_to_submit=false`, and structured pass/fail/warning details in -`results`. The user-facing failure condition is +`results`. Blocked submission-create attempts use the user-facing error code `pre_submission_checker_failed`; it 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`, @@ -257,7 +260,7 @@ Examples: ```text Draft packet -> load locked task context --> load locked EffectiveSubmissionArtifactPolicy hash +-> load locked EffectiveTaskSubmissionArtifactPolicy hash -> load locked PreSubmitCheckerPolicy snapshot/hash -> run pre-submit intake checks -> create Submission only when blocking pre-submit checks pass diff --git a/docs/architecture_data_model.md b/docs/architecture_data_model.md index da9ce99..1fd52ef 100644 --- a/docs/architecture_data_model.md +++ b/docs/architecture_data_model.md @@ -13,9 +13,12 @@ Actor Project ProjectGuide + GuideSourceSnapshot GuideSufficiencyReport SubmissionArtifactPolicy - EffectiveSubmissionArtifactPolicy + EffectiveProjectSubmissionArtifactPolicy + ApprovedTaskArtifactBinding + EffectiveTaskSubmissionArtifactPolicy PreSubmitCheckerPolicy PostSubmitCheckerPolicy ReviewPolicy @@ -176,7 +179,44 @@ That field is old construction state. The architecture source of truth is `SubmissionArtifactPolicy`, and the replacement path does not require a compatibility alias. -Implementation note: `ProjectGuide.required_submission_fields` is a legacy display summary. Submission validity is enforced by `EffectiveSubmissionArtifactPolicy`, not by project guide fields. +Implementation note: `ProjectGuide.required_submission_fields` is a legacy display summary. Submission validity is enforced by `EffectiveTaskSubmissionArtifactPolicy`, not by project guide fields. + +## GuideSourceSnapshot + +Fields: + +- `id` +- `project_id` +- `guide_id` +- `guide_version` +- `source_ref` +- `ingestion_adapter` +- `content_hash` +- `content_cid` (future Flow Node binding) +- `captured_at` +- `created_by` + +`GuideSourceSnapshot` is the immutable source binding for guide material. It +captures the exact guide/source bytes Workstream evaluated. A guide can point at +markdown, imported documents, URL-backed docs, repository docs, examples, or +rubric material, but downstream records do not trust a mutable URL or mutable +draft guide body. They bind to `source_snapshot_id` and +`source_snapshot_hash`. + +URL-backed guide ingestion is split into two identities: + +- temporary fetch locator: used only by an approved retrieval adapter +- durable source record: opaque sanitized source ref plus content hash/CID + +Ordinary URL query parameters can be used by approved adapters when fetching +legitimate documentation. Query strings are temporary fetch inputs only. +Workstream must not persist query strings, signed URLs, credentials, +token-bearing locators, local filesystem paths, or private storage paths as +durable source identity. + +Any guide or source-material change creates a new source snapshot. That +invalidates prior sufficiency reports, derived policies, effective policies, +checker bundles, acknowledgements, and approvals for activation. ## GuideSufficiencyReport @@ -185,6 +225,8 @@ Fields: - `id` - `project_id` - `guide_version` +- `source_snapshot_id` +- `source_snapshot_hash` - `status` - `findings` - `source_material_refs` @@ -219,7 +261,10 @@ Fields: - `id` - `project_id` - `guide_version` +- `source_snapshot_id` +- `source_snapshot_hash` - `version` +- `status` - `required_artifacts` - `required_evidence` - `artifact_manifest_required` @@ -240,6 +285,7 @@ Fields: - `approved_by` - `approved_at` - `created_at` +- `supersedes_policy_id` Example: @@ -283,7 +329,18 @@ supply or approve this internal policy schema. Project policy can add stricter requirements, but it cannot weaken Workstream's default submission artifact policy. -## EffectiveSubmissionArtifactPolicy +Policy rows are append-only after approval: + +```text +draft -> mutable +approved -> immutable +superseded -> immutable +``` + +Changing an approved policy creates a new policy revision with +`supersedes_policy_id`. The old row is never edited in place. + +## EffectiveProjectSubmissionArtifactPolicy Generated server-side from: @@ -297,7 +354,10 @@ Fields: - `id` - `project_id` - `guide_version` +- `source_snapshot_id` +- `source_snapshot_hash` - `version` +- `status` - `policy_hash` - `source_project_policy_hash` - `required_artifacts` @@ -310,37 +370,149 @@ Fields: - `required_attestation_terms` - `generated_from` - `generated_at` +- `supersedes_policy_id` This policy is deterministic. It preserves Workstream defaults first and adds project-approved requirements. Duplicate rules collapse by canonical key. Any project rule that conflicts with Workstream defaults is a project setup defect. +The merge contract is executable per field: + +| Field | Merge rule | +| --- | --- | +| `required_artifacts` | union by canonical artifact key | +| `required_evidence` | union by canonical evidence key | +| `forbidden_artifacts` | union | +| `required_attestation_terms` | union | +| `artifact_manifest_required` | logical OR | +| `artifact_hash_required` | logical OR | +| `allowed_storage_schemes` | intersection | +| `artifact_hash_algorithm` | platform-locked value or intersection of allowed algorithms | +| `maximum_file_size` | minimum non-null limit | +| `maximum_package_size` | minimum non-null limit | +| `packaging_rules` | restrictive merge; conflicts block activation | + +A required artifact or evidence rule matching a forbidden artifact rule blocks +project setup as a policy conflict. It is not deferred to worker submission. + +Approved and superseded effective policies are immutable. Recomputing the +effective policy after guide/source/policy changes creates a new row and hash. + +## ApprovedTaskArtifactBinding + +Fields: + +- `id` +- `task_id` +- `project_id` +- `guide_version` +- `source_snapshot_id` +- `source_snapshot_hash` +- `effective_project_policy_hash` +- `artifact_profile` +- `required_paths` +- `required_evidence` +- `additional_packaging_rules` +- `additional_forbidden_artifacts` +- `approval_status` +- `approved_by_role` +- `approved_by` +- `approved_at` +- `created_at` +- `supersedes_binding_id` + +`ApprovedTaskArtifactBinding` turns a project-level policy into a concrete +task-level intake contract. A project can contain many task types, so Workstream +must not assume every task under one guide submits the same artifacts. The +binding selects an approved artifact profile and supplies constrained +parameters, for example: + +```json +{ + "artifact_profile": "coding_task", + "required_paths": ["src/parser.py", "tests/test_parser.py"] +} +``` + +Task bindings can add or tighten requirements. They cannot weaken Workstream +defaults or the effective project policy. + +## EffectiveTaskSubmissionArtifactPolicy + +Generated server-side from: + +```text +EffectiveProjectSubmissionArtifactPolicy ++ ApprovedTaskArtifactBinding +``` + +Fields: + +- `id` +- `task_id` +- `project_id` +- `guide_version` +- `source_snapshot_id` +- `source_snapshot_hash` +- `version` +- `status` +- `policy_hash` +- `effective_project_policy_hash` +- `approved_task_artifact_binding_id` +- `required_artifacts` +- `required_evidence` +- `artifact_manifest_required` +- `artifact_hash_required` +- `artifact_hash_algorithm` +- `allowed_storage_schemes` +- `forbidden_artifacts` +- `required_attestation_terms` +- `packaging_rules` +- `generated_at` +- `supersedes_policy_id` + +This policy is locked when the task enters `SCREENING` or `READY`. Submission +pre-check and submission creation use this task policy hash, not project guide +prose and not transitional task fields. + ## PreSubmitCheckerPolicy -Generated server-side from `EffectiveSubmissionArtifactPolicy`, then persisted -and locked to the project guide version. +Generated server-side from `EffectiveTaskSubmissionArtifactPolicy`, then +persisted and locked to the task policy hash before the task enters the worker +pipeline. Fields: - `id` +- `task_id` - `project_id` - `guide_version` +- `source_snapshot_id` +- `source_snapshot_hash` - `version` +- `status` - `policy_hash` -- `effective_submission_artifact_policy_hash` +- `effective_task_submission_artifact_policy_hash` - `checker_spec` - `compiler_version` - `compiled_bundle_hash` - `compiled_bundle` -- `checker_names` -- `checker_configs` -- `blocking_severities` +- `checker_names` (derived index projection) +- `checker_configs` (derived index projection) +- `blocking_severities` (derived index projection) - `generated_from_policy_version` - `generated_at` +- `supersedes_policy_id` `checker_spec` is a constrained machine-readable specification using Workstream-approved primitives. `compiled_bundle` is the immutable JSON checker -bundle produced by the trusted Workstream checker compiler. It is stored as a -structured snapshot, not arbitrary executable code. `compiled_bundle_hash` -binds the exact compiled logic to `effective_submission_artifact_policy_hash`. +bundle produced by the trusted Workstream checker compiler and is the canonical +source of truth. It is stored as a structured snapshot, not arbitrary executable +code. `compiled_bundle_hash` binds the exact compiled logic to +`effective_task_submission_artifact_policy_hash`. `checker_names`, +`checker_configs`, and `blocking_severities` are derived index projections only; +they must be regenerated from `compiled_bundle` and must not disagree with it. + +Approved and superseded checker policy rows are immutable. Changing policy or +compiler output creates a new row with `supersedes_policy_id`. The generated checker order is deterministic: @@ -354,11 +526,21 @@ The generated checker order is deterministic: 8. worker attestation validation 9. low-quality artifact warnings -Blocking pre-submit failures prevent submission creation. A failed blocking -pre-submit check returns `pre_submission_checker_failed` with structured -pass/fail/warning details, creates no submission row, no submission version, no -task transition to `submitted`, and no submission-created audit event. It does -not return review decision values. +Pre-submit has two API paths: + +```text +POST /tasks/{id}/submission-precheck +200 PreSubmitCheckResponse(status="failed", eligible_to_submit=false, results=[...]) +``` + +```text +POST /tasks/{id}/submissions +422 DomainError(code="pre_submission_checker_failed", details={status, eligible_to_submit, results}) +``` + +Blocking pre-submit failures prevent submission creation, create no submission +row, no submission version, no task transition to `submitted`, and no +submission-created audit event. They do not return review decision values. ## PostSubmitCheckerPolicy @@ -473,8 +655,12 @@ Fields: - `id` - `project_id` - `locked_guide_version` +- `locked_guide_source_snapshot_id` +- `locked_guide_source_snapshot_hash` - `locked_submission_artifact_policy_version` -- `locked_effective_submission_artifact_policy_hash` +- `locked_effective_project_submission_artifact_policy_hash` +- `locked_task_artifact_binding_id` +- `locked_effective_task_submission_artifact_policy_hash` - `locked_pre_submit_checker_policy_hash` - `locked_post_submit_checker_policy_version` - `locked_review_policy_version` @@ -497,8 +683,8 @@ Fields: - `status` - `acceptance_criteria` - `rejection_criteria` -- `required_files` (derived snapshot) -- `required_evidence` (derived snapshot) +- `required_files` (legacy display snapshot) +- `required_evidence` (legacy display snapshot) - `deadline_at` - `created_by` - `assigned_to` @@ -528,7 +714,13 @@ Source type: External origin adapters are later work. When added, they normalize into this task shape instead of creating a separate task lifecycle. -The task id points to the locked task contract. That contract includes the guide version, submission artifact policy version, effective submission artifact policy hash, generated pre-submit checker policy hash, post-submit checker policy version, review policy version, revision policy version, payment policy version, acceptance criteria, derived required artifacts and evidence references, base payout, and skill tags. Workers submit against the task id; they do not restate policy versions. +The task id points to the locked task contract. That contract includes the guide +version, guide source snapshot hash, project submission artifact policy version, +effective project policy hash, approved task artifact binding, effective task +policy hash, generated pre-submit checker policy hash, post-submit checker +policy version, review policy version, revision policy version, payment policy +version, acceptance criteria, derived display summaries, base payout, and skill +tags. Workers submit against the task id; they do not restate policy versions. Implementation note: current v0.1 code uses `locked_checker_policy_version` for the post-submit checker policy version. The architecture target splits this into `locked_post_submit_checker_policy_version` and explicit submission artifact/pre-submit provenance fields. @@ -560,8 +752,12 @@ Fields: - `artifact_hash_manifest` - `worker_attestation` - `locked_guide_version` +- `locked_guide_source_snapshot_id` +- `locked_guide_source_snapshot_hash` - `locked_submission_artifact_policy_version` -- `locked_effective_submission_artifact_policy_hash` +- `locked_effective_project_submission_artifact_policy_hash` +- `locked_task_artifact_binding_id` +- `locked_effective_task_submission_artifact_policy_hash` - `locked_pre_submit_checker_policy_hash` - `locked_post_submit_checker_policy_version` - `locked_review_policy_version` @@ -571,7 +767,16 @@ Fields: - `locked_at` - `supersedes_submission_id` -The worker submission packet supplies the task id, summary, outputs, artifact hashes, evidence references, and worker attestation. Workstream assigns the submission version, creates evidence ids, and stamps locked guide, submission artifact, pre-submit checker, post-submit checker, review, revision, and payment policy provenance from trusted task/project state. The worker does not provide submission version, evidence ids, checker results, checker run ids, guide versions, submission artifact policy versions, post-submit checker policy versions, review policy versions, revision policy versions, or payment policy versions. +The worker submission packet supplies the task id, summary, outputs, artifact +hashes, evidence references, and worker attestation. Workstream assigns the +submission version, creates evidence ids, and stamps locked guide source, +submission artifact, effective task policy, pre-submit checker, post-submit +checker, review, revision, and payment policy provenance from trusted +task/project state. The worker does not provide submission version, evidence +ids, checker results, checker run ids, guide versions, source snapshots, +submission artifact policy versions, task policy hashes, post-submit checker +policy versions, review policy versions, revision policy versions, or payment +policy versions. Implementation note: current v0.1 code uses `locked_checker_policy_version` on submissions for post-submit checker policy provenance. The architecture target adds explicit submission artifact and pre-submit policy provenance. diff --git a/docs/architecture_lifecycle_state_machine.md b/docs/architecture_lifecycle_state_machine.md index c49c407..35caf82 100644 --- a/docs/architecture_lifecycle_state_machine.md +++ b/docs/architecture_lifecycle_state_machine.md @@ -72,10 +72,13 @@ Required before entering: - task schema valid - project guide active -- GuideSufficiencyReport passed or warnings acknowledged -- SubmissionArtifactPolicy approved -- EffectiveSubmissionArtifactPolicy hash persisted -- generated PreSubmitCheckerPolicy persisted and locked +- current GuideSourceSnapshot id/hash locked +- GuideSufficiencyReport passed or warnings acknowledged for that source snapshot +- ProjectSubmissionArtifactPolicy approved +- EffectiveProjectSubmissionArtifactPolicy hash persisted +- ApprovedTaskArtifactBinding exists +- EffectiveTaskSubmissionArtifactPolicy hash locked +- task-level PreSubmitCheckerPolicy persisted and locked to that task policy hash - PostSubmitCheckerPolicy present - review policy present - revision policy present @@ -101,7 +104,7 @@ Required before entering: - submission summary - package or output reference - evidence items -- effective submission artifact policy loaded +- effective task submission artifact policy loaded - generated pre-submit checker policy executed - no blocking pre-submit failures - immutable submission version diff --git a/docs/architecture_lockdown.md b/docs/architecture_lockdown.md index 2742ae9..014dc4f 100644 --- a/docs/architecture_lockdown.md +++ b/docs/architecture_lockdown.md @@ -70,8 +70,7 @@ Every active guide version must also have approved machine-readable policies: - guide sufficiency report - submission artifact policy -- effective submission artifact policy hash -- generated pre-submit checker policy +- effective project submission artifact policy hash - post-submit checker policy - review policy - revision policy @@ -86,9 +85,11 @@ with the `admin` or `project_manager` role approves the internal policy bundle before guide activation. Project owners do not approve Workstream's internal submission policy schema. -`SubmissionArtifactPolicy` defines what a worker must submit. Workstream combines it with the non-bypassable Workstream default submission artifact policy to create the effective submission artifact policy. Workstream persists the effective policy hash, then generates, persists, hashes, and locks `PreSubmitCheckerPolicy` from that effective policy. +`SubmissionArtifactPolicy` defines project-level intake rules. Workstream combines it with the non-bypassable Workstream default submission artifact policy to create the effective project policy, then combines that with an approved task artifact binding to create the effective task submission artifact policy. Workstream persists the effective task policy hash, then generates, persists, hashes, and locks `PreSubmitCheckerPolicy` from that task policy. -Blocking pre-submit failures prevent submission creation. They return +Blocking pre-submit failures prevent submission creation. Preflight failures +return `PreSubmitCheckResponse(status="failed", eligible_to_submit=false, +results=[...])`. Blocked submission-create attempts return `pre_submission_checker_failed` with structured pass/fail/warning details and create no submission row, no submission version, no task transition to `submitted`, and no submission-created audit event. @@ -106,7 +107,7 @@ Every task must carry enough information to make claiming, checking, reviewing, - task type - required output - acceptance criteria -- required artifacts and evidence references derived from the effective submission artifact policy +- required artifacts and evidence references derived from the effective task submission artifact policy - difficulty - skill tags - estimated time when known @@ -159,7 +160,9 @@ Use these names consistently: - `check_acceptance_criteria_present` - `ContributionRecord` - `SubmissionArtifactPolicy` -- `EffectiveSubmissionArtifactPolicy` +- `EffectiveProjectSubmissionArtifactPolicy` +- `ApprovedTaskArtifactBinding` +- `EffectiveTaskSubmissionArtifactPolicy` - `PreSubmitCheckerPolicy` - `PostSubmitCheckerPolicy` - `pre_submission_checker_failed` diff --git a/docs/current_system_data_flow.html b/docs/current_system_data_flow.html index f12bbde..86e16f8 100644 --- a/docs/current_system_data_flow.html +++ b/docs/current_system_data_flow.html @@ -483,7 +483,7 @@

Project guide and policy are prepared

3

Guide activation locks contract

-

Activation validates a passing or acknowledged sufficiency report, approved submission artifact policy, effective policy hash, persisted generated pre-submit policy, registered post-submit checker names, review policy allowed decisions, revision states, and payment policy.

+

Activation validates a passing or acknowledged sufficiency report, immutable guide source snapshot, approved submission artifact policy, effective project policy hash, registered post-submit checker names, review policy allowed decisions, revision states, and payment policy. Task readiness later validates the approved task artifact binding, effective task policy hash, and task-level pre-submit policy.

status=active one active guide @@ -515,7 +515,7 @@

Worker claims and starts

6

Pre-submit intake checks run

-

Workstream runs generated pre-submit checks from the effective submission artifact policy before creating a submission row. Blocking failures return pre_submission_checker_failed with pass/fail/warning details.

+

Workstream runs generated pre-submit checks from the effective task submission artifact policy before creating a submission row. Preflight failures return PreSubmitCheckResponse details. Blocked submission-create attempts return pre_submission_checker_failed with pass/fail/warning details.

no submission yet no checker run yet diff --git a/docs/decision_0003_project_guides_are_first_class.md b/docs/decision_0003_project_guides_are_first_class.md index 411ad52..d8331a4 100644 --- a/docs/decision_0003_project_guides_are_first_class.md +++ b/docs/decision_0003_project_guides_are_first_class.md @@ -22,7 +22,8 @@ The guide drives: - task requirements - submission artifact policy -- pre-submit checker policy generated from the effective submission artifact policy +- guide source snapshot and effective project submission artifact policy +- task pre-submit checker policy generated from the effective task submission artifact policy - post-submit checker policy - review policy - revision policy @@ -33,16 +34,16 @@ The submission artifact, checker, review, revision, and payment policies are gui Project guide activation requires the guide plus its required policy context before work can lock against it: +- guide source snapshot - guide sufficiency report - submission artifact policy -- effective submission artifact policy hash -- generated pre-submit checker policy +- effective project submission artifact policy hash - post-submit checker policy - review policy - revision policy - payment policy -The Workstream-derived submission artifact policy defines what workers must submit. Project owners provide open-ended project material and business terms. Workstream evaluates guide sufficiency, derives the machine policy, and a Workstream actor with the `admin` or `project_manager` role approves the internal policy bundle. Workstream combines that policy with non-bypassable Workstream default artifact rules to create the effective submission artifact policy. Workstream then generates, persists, hashes, and locks the pre-submit checker policy from that effective policy. +The Workstream-derived submission artifact policy defines project-level intake rules. Project owners provide open-ended project material and business terms. Workstream captures an immutable guide source snapshot, evaluates guide sufficiency, derives the machine policy, and a Workstream actor with the `admin` or `project_manager` role approves the internal policy bundle. Workstream combines that policy with non-bypassable Workstream default artifact rules to create the effective project policy. Task screening later combines that effective project policy with an approved task artifact binding to create the effective task policy and generated pre-submit checker policy. Blocking pre-submit failures prevent submission creation. They do not create durable post-submit checker runs and they do not create human review decisions. 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 b790ca1..3e715f2 100644 --- a/docs/decision_0011_submission_artifact_policy_drives_pre_submit.md +++ b/docs/decision_0011_submission_artifact_policy_drives_pre_submit.md @@ -19,14 +19,34 @@ Workstream also needs platform-owned default submission safety rules that no pro Every active project guide version must have a complete guide-policy bundle: +- immutable `GuideSourceSnapshot` for the exact guide/source bytes evaluated - passing or acknowledged `GuideSufficiencyReport` - approved `ProjectSubmissionArtifactPolicy` -- persisted `EffectiveSubmissionArtifactPolicy` hash +- persisted `EffectiveProjectSubmissionArtifactPolicy` hash + +Before a task can enter the worker pipeline, it must also have: + +- approved `ApprovedTaskArtifactBinding` +- persisted `EffectiveTaskSubmissionArtifactPolicy` hash - persisted generated `PreSubmitCheckerPolicy` snapshot/hash Project owners provide open-ended project material in plain language. Workstream must not force every project owner through one universal intake checklist. +Workstream binds all downstream setup records to the exact guide source +snapshot, not only to `guide_version`. `GuideSourceSnapshot` records include the +guide id, source ref, ingestion adapter, content hash, optional future content +id, and capture timestamp. A guide or source-material change creates a new +snapshot and invalidates prior sufficiency reports, derived policies, effective +policies, checker bundles, acknowledgements, and approvals for activation. + +URL-backed guide ingestion separates the temporary fetch locator from durable +source identity. Approved retrieval adapters can fetch legitimate documentation +that uses ordinary query parameters. Query strings are temporary fetch inputs +only. Workstream must not persist query strings, signed URLs, credentials, +token-bearing refs, or local filesystem paths. The durable source record is an +opaque sanitized source ref plus content hash or future content id. + `ProjectGuideSufficiencyAgent` evaluates whether the guide is sufficient for submitters, reviewers, and Workstream quality control. Blocking guide gaps stop activation and create clarification requests back to the project owner. Warnings @@ -67,16 +87,27 @@ version/hash. The runtime contract is: ```text -EffectiveSubmissionArtifactPolicy = +EffectiveProjectSubmissionArtifactPolicy = WorkstreamDefaultSubmissionArtifactPolicy + ProjectSubmissionArtifactPolicy + +EffectiveTaskSubmissionArtifactPolicy = + EffectiveProjectSubmissionArtifactPolicy + + ApprovedTaskArtifactBinding ``` Workstream's trusted checker compiler generates and persists -`PreSubmitCheckerPolicy` from the effective submission artifact policy and the -approved checker specification. +`PreSubmitCheckerPolicy` from the effective task submission artifact policy and +the approved checker specification. + +Project policies define project-wide artifact intake rules for a guide +snapshot. Tasks can still have different required outputs. `ApprovedTaskArtifactBinding` +selects an approved artifact profile and constrained task parameters. It can +add or tighten requirements, never weaken platform defaults or the effective +project policy. The resulting effective task policy hash is locked when the +task enters `SCREENING` or `READY`. -`PreSubmitCheckerPolicy` is locked to the project guide version. It is not +`PreSubmitCheckerPolicy` is locked to the effective task policy hash. It is not derived on read, manually edited by workers, or supplied by clients. Workers submit only draft packet fields. They do not choose checker names, policy versions, blocking rules, severities, or outcomes. @@ -110,10 +141,36 @@ Blocking pre-submit failures prevent submission creation. When blocking pre-subm - no submission version is assigned - no task transition to `submitted` occurs - no submission-created audit event is written -- the response returns `pre_submission_checker_failed` -- the response includes structured pass/fail/warning details - the response does not use review decision values: `accept`, `needs_revision`, or `reject` +Pre-submit has two API contracts: + +```text +POST /tasks/{id}/submission-precheck +200 PreSubmitCheckResponse +{ + "status": "failed", + "eligible_to_submit": false, + "results": [...] +} +``` + +```text +POST /tasks/{id}/submissions +422 DomainError +{ + "code": "pre_submission_checker_failed", + "details": { + "status": "failed", + "eligible_to_submit": false, + "results": [...] + } +} +``` + +`pre_submission_checker_failed` is the submission-creation error code. It is not +a review decision and is not the response type for the preflight endpoint. + Pre-submit checks are authoritative for submission intake. They are not authoritative proof for human review readiness. Review readiness still requires post-submit internal checker runs against a locked submission. ## Implementation Enforcement Contract @@ -171,6 +228,40 @@ Persisted storage references must be Workstream-issued opaque object references Default forbidden artifacts remain blocked even if a project policy accidentally lists them as required. A required artifact that violates the default forbidden policy is a project setup defect. +The effective policy merge is deterministic: + +| Field | Merge rule | +| --- | --- | +| `required_artifacts` | union by canonical artifact key | +| `required_evidence` | union by canonical evidence key | +| `forbidden_artifacts` | union | +| `required_attestation_terms` | union | +| `artifact_manifest_required` | logical OR | +| `artifact_hash_required` | logical OR | +| `allowed_storage_schemes` | intersection | +| `artifact_hash_algorithm` | platform-locked value or intersection of allowed algorithms | +| `maximum_file_size` | minimum non-null limit | +| `maximum_package_size` | minimum non-null limit | +| `packaging_rules` | restrictive merge; conflicts block activation | + +Conflicts block setup before workers see tasks. A project-required artifact that +matches a forbidden rule is not accepted as a runtime edge case. + +Approved policy and checker records are append-only: + +```text +draft -> mutable +approved -> immutable +superseded -> immutable +``` + +Changing an approved policy, effective policy, task binding, or compiled checker +bundle creates a new row with a `supersedes_*` reference. Approved rows are +never edited in place. For `PreSubmitCheckerPolicy`, `compiled_bundle` is the +canonical JSON source of truth and `compiled_bundle_hash` is the hash of that +canonical JSON. `checker_names`, `checker_configs`, and `blocking_severities` +are derived index projections only. + ## Consequences Positive: diff --git a/docs/glossary.md b/docs/glossary.md index 0cf38ae..3b73165 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -54,15 +54,15 @@ version before Workstream merges it with default submission artifact policy. ## Effective Submission Artifact Policy -The deterministic merge of Workstream's default submission artifact policy and the project-approved submission artifact policy. Workstream computes this effective policy before pre-submit checks run. +The deterministic merge of Workstream's default submission artifact policy and the project-approved submission artifact policy. Workstream computes this effective project policy before task-specific binding. ## Pre-Submit Checker Policy -The server-generated checker matrix produced from the effective submission artifact policy, persisted with a hash, and locked to the project guide version. It runs before Workstream creates a submission row or submission version. Blocking failures return `pre_submission_checker_failed` with structured pass/fail/warning details, prevent submission creation, and do not return review decision values: `accept`, `needs_revision`, or `reject`. +The server-generated checker matrix produced from the effective task submission artifact policy, persisted with a hash, and locked before a task enters the worker pipeline. It runs before Workstream creates a submission row or submission version. The preflight endpoint returns `PreSubmitCheckResponse`; a blocked submission-create attempt returns `pre_submission_checker_failed` with structured pass/fail/warning details. Neither path returns review decision values: `accept`, `needs_revision`, or `reject`. ## pre_submission_checker_failed -The worker-facing pre-submit failure code returned before a submission exists. It includes structured pass/fail/warning details and is not a review decision. It must not be stored as `accept`, `needs_revision`, or `reject`. +The worker-facing domain error code returned when a submission-create attempt is blocked by pre-submit checks. It includes structured pass/fail/warning details in the error details and is not a review decision. It must not be stored as `accept`, `needs_revision`, or `reject`. The preflight endpoint returns `PreSubmitCheckResponse` instead of this error code. ## Task @@ -82,7 +82,7 @@ An automated rule that validates a task or submission before human review. ## Checker Policy -The set of required and warning checks for a project phase. Pre-submit checker policy is generated from the effective submission artifact policy. Post-submit checker policy governs durable internal checker runs after a submission is locked. +The set of required and warning checks for a project phase. Pre-submit checker policy is generated from the effective task submission artifact policy. Post-submit checker policy governs durable internal checker runs after a submission is locked. ## Human Review diff --git a/docs/operations_project_operating_manual.md b/docs/operations_project_operating_manual.md index 69df2f6..40bd991 100644 --- a/docs/operations_project_operating_manual.md +++ b/docs/operations_project_operating_manual.md @@ -9,10 +9,11 @@ Every project has: - active guide - queue owner - reviewer owner +- guide source snapshot - guide sufficiency report - submission artifact policy -- effective submission artifact policy hash -- generated pre-submit checker policy +- effective project submission artifact policy hash +- generated task pre-submit checker policy - post-submit checker policy - review policy - revision policy @@ -26,6 +27,7 @@ Before releasing tasks: - project name and slug exist - project guide imported +- guide source snapshot captured - guide version marked active - base amount configured - currency configured @@ -34,8 +36,9 @@ Before releasing tasks: - project owner setup material captured - guide sufficiency report passed or warnings acknowledged by `admin` or `project_manager` - submission artifact policy derived by Workstream and approved by `admin` or `project_manager` -- effective submission artifact policy hash persisted -- generated pre-submit checker policy created from the effective submission artifact policy +- effective project submission artifact policy hash persisted +- task artifact binding and effective task submission artifact policy are created before each task enters `READY` +- generated pre-submit checker policy is created from the effective task submission artifact policy - post-submit checker policy attached - review policy attached - revision policy attached @@ -49,9 +52,10 @@ Before releasing tasks: A project cannot become active unless guide, passed or acknowledged guide sufficiency report, approved submission artifact policy, persisted effective -submission artifact policy hash, generated pre-submit checker policy, -post-submit checker policy, review policy, revision policy, and payment policy -are present. +project submission artifact policy hash, post-submit checker policy, review +policy, revision policy, and payment policy are present. A task cannot enter +`READY` until it also has an approved task artifact binding, effective task +submission artifact policy hash, and task-level pre-submit checker policy. ### Task Screening Gate @@ -104,9 +108,10 @@ Before accepting a submission packet: - output package or reference exists - evidence exists - revision replay exists when task was previously `NEEDS_REVISION` -- effective submission artifact policy is loaded +- effective task submission artifact policy is loaded - generated pre-submit checker policy runs -- blocking pre-submit failures return `pre_submission_checker_failed` with structured pass/fail/warning details +- preflight failures return `PreSubmitCheckResponse(status="failed", eligible_to_submit=false, results=[...])` +- blocked submission-create attempts return `pre_submission_checker_failed` with structured pass/fail/warning details - no submission row is created until blocking pre-submit checks pass ## Reviewer Simulation Gate diff --git a/docs/operations_workspace_packet_convention.md b/docs/operations_workspace_packet_convention.md index 3831c73..e9a61ce 100644 --- a/docs/operations_workspace_packet_convention.md +++ b/docs/operations_workspace_packet_convention.md @@ -12,8 +12,17 @@ Every project has a guide-version policy bundle derived by Workstream from open-ended project material: ```text +GuideSourceSnapshot GuideSufficiencyReport -EffectiveSubmissionArtifactPolicy +ProjectSubmissionArtifactPolicy +EffectiveProjectSubmissionArtifactPolicy +``` + +Every task then locks a task-specific intake bundle: + +```text +ApprovedTaskArtifactBinding +EffectiveTaskSubmissionArtifactPolicy PreSubmitCheckerPolicy required_artifacts required_evidence diff --git a/docs/product_first_user_flows.md b/docs/product_first_user_flows.md index a655e38..3a6cd8d 100644 --- a/docs/product_first_user_flows.md +++ b/docs/product_first_user_flows.md @@ -12,17 +12,16 @@ The first user flows prove that Workstream can run real work from intake to acce 6. Admin or project_manager acknowledges non-blocking sufficiency warnings. 7. Workstream runs `SubmissionArtifactPolicyDerivationAgent`. 8. Admin or project_manager reviews and approves the derived submission artifact policy. -9. Workstream persists the effective submission artifact policy hash. -10. Workstream persists the generated pre-submit checker policy snapshot/hash. -11. Admin or project_manager enables post-submit checker policy. -12. Admin or project_manager enables review policy. -13. Admin or project_manager enables revision policy. -14. Admin or project_manager enables payment policy. -15. Project becomes active. +9. Workstream persists the effective project submission artifact policy hash. +10. Admin or project_manager enables post-submit checker policy. +11. Admin or project_manager enables review policy. +12. Admin or project_manager enables revision policy. +13. Admin or project_manager enables payment policy. +14. Project becomes active. Acceptance: -- Project cannot become active without guide, base amount, passed or acknowledged guide sufficiency report, submission artifact policy, effective submission artifact policy hash, generated pre-submit checker policy snapshot/hash, post-submit checker policy, review policy, revision policy, and payment policy. +- Project cannot become active without guide, base amount, immutable guide source snapshot, passed or acknowledged guide sufficiency report, submission artifact policy, effective project submission artifact policy hash, post-submit checker policy, review policy, revision policy, and payment policy. - Submission artifact policy is Workstream-derived and approved by `admin` or `project_manager`; project owners do not author or approve the machine policy schema directly. - Submission artifact, checker, review, revision, and payment policies are visible on the project page. @@ -32,14 +31,14 @@ Acceptance: 2. Operator creates task with title, description, expected output, acceptance criteria, base amount, deadline, and difficulty. 3. Workstream validates task against project guide. 4. Task enters `SCREENING`. -5. Screening confirms guide version, task contract, submission artifact requirements, checker policy, review policy, revision policy, payment policy, and reviewability. +5. Screening confirms guide source snapshot, task contract, approved task artifact binding, effective task submission artifact policy hash, generated pre-submit checker policy, post-submit checker policy, review policy, revision policy, payment policy, and reviewability. 6. Task enters `READY`. Acceptance: - Missing required fields block `SCREENING`. - Missing required fields block `READY`. -- Task shows project guide, required artifacts, generated pre-submit checker policy summary, post-submit checker policy, review policy, revision policy, and payment policy. +- Task shows project guide, task-specific required artifacts, generated pre-submit checker policy summary, post-submit checker policy, review policy, revision policy, and payment policy. ## Flow 3: Worker Submits Work @@ -47,8 +46,8 @@ Acceptance: 2. Worker attaches output files or links. 3. Worker attaches evidence. 4. Worker writes submission notes. -5. Workstream runs pre-submit checks generated from the effective submission artifact policy. -6. Blocking pre-submit failures return `pre_submission_checker_failed` with structured pass/fail/warning details and create no submission. +5. Workstream runs pre-submit checks generated from the effective task submission artifact policy. +6. Preflight failures return `PreSubmitCheckResponse`; blocked submission-create attempts return `pre_submission_checker_failed` with structured pass/fail/warning details and create no submission. 7. When blocking pre-submit checks pass, Worker submits packet. 8. Task enters `SUBMITTED`. @@ -56,7 +55,7 @@ Acceptance: - Submission cannot be created when blocking pre-submit checks fail. - Blocking pre-submit failures are not review decisions and never return `accept`, `needs_revision`, or `reject`. -- Submission cannot be created without required artifacts, evidence references, hashes, and worker attestation defined by the effective submission artifact policy. +- Submission cannot be created without required artifacts, evidence references, hashes, and worker attestation defined by the effective task submission artifact policy. - Submission packet is immutable after checks start. ## Flow 4: Automated Checks Run diff --git a/docs/roadmap_day_by_day_execution_plan.md b/docs/roadmap_day_by_day_execution_plan.md index e1691d3..e3c32c5 100644 --- a/docs/roadmap_day_by_day_execution_plan.md +++ b/docs/roadmap_day_by_day_execution_plan.md @@ -67,7 +67,8 @@ Exit criteria: - create a project from a markdown guide - retrieve the active guide version for a task - edit a draft guide without changing historical task guide versions -- block activation of a guide missing submission artifact, generated pre-submit checker, post-submit checker, review, revision, or payment policy +- block activation of a guide missing guide source snapshot, submission artifact policy, effective project policy hash, post-submit checker, review, revision, or payment policy +- block task readiness when approved task artifact binding, effective task policy hash, or task-level pre-submit checker policy is missing - migrations and model tests define the expected invariants ### Day 3: Task Queue @@ -198,7 +199,7 @@ Deliver: - generated `PreSubmitCheckerPolicy` - `PostSubmitCheckerPolicy` -- effective submission artifact policy merge +- effective task submission artifact policy merge - project-required checker list - blocking severity settings - trusted checker retry with reason after internal setup repair diff --git a/docs/roadmap_implementation_backlog.md b/docs/roadmap_implementation_backlog.md index cce1436..5f0c38e 100644 --- a/docs/roadmap_implementation_backlog.md +++ b/docs/roadmap_implementation_backlog.md @@ -85,7 +85,7 @@ - implement `check_confidentiality_attestation` - implement `check_low_quality_generated_artifacts` - implement registered readiness checkers only after their contracts are locked -- implement generated pre-submit intake guards from the effective submission artifact policy +- implement generated pre-submit intake guards from the effective task submission artifact policy ### Review diff --git a/docs/spec_chunk_3_project_guide_foundation.md b/docs/spec_chunk_3_project_guide_foundation.md index 73e97e4..5b9c58b 100644 --- a/docs/spec_chunk_3_project_guide_foundation.md +++ b/docs/spec_chunk_3_project_guide_foundation.md @@ -61,10 +61,10 @@ The guide version is the join key for the guide-specific policies. Project guide activation requires: - guide is still draft +- immutable guide source snapshot exists for the exact source material being activated - guide sufficiency report is passed or warnings are acknowledged by `admin` or `project_manager` - Workstream-derived submission artifact policy is approved for the guide version with `admin` or `project_manager` approval provenance -- effective submission artifact policy hash exists for the guide version -- generated pre-submit checker policy snapshot/hash exists for the guide version +- effective project submission artifact policy hash exists for the guide source snapshot - post-submit checker policy exists for the guide version - review policy exists for the guide version - revision policy exists for the guide version @@ -95,12 +95,12 @@ Submission artifact policy is a first-class guide-version policy. It defines wha The architecture contract is: ```text -EffectiveSubmissionArtifactPolicy = +EffectiveProjectSubmissionArtifactPolicy = WorkstreamDefaultSubmissionArtifactPolicy + ProjectSubmissionArtifactPolicy ``` -Workstream generates, persists, hashes, and locks pre-submit checker policy from the effective submission artifact policy. Blocking pre-submit failures prevent submission creation. +Task screening later combines the effective project policy with an approved task artifact binding to produce `EffectiveTaskSubmissionArtifactPolicy`. Workstream generates, persists, hashes, and locks task pre-submit checker policy from that task policy. Blocking pre-submit failures prevent submission creation. Implementation note: the first v0.1 schema stored this as `ProjectGuide.evidence_policy`. That field is old construction state and is replaced by the dedicated policy table/API path. @@ -144,7 +144,7 @@ The active guide response becomes the future source for task-owned locked guide - guide activation or policy approval is blocked when project submission artifact policy permits unsafe storage references - guide activation or policy approval is blocked when project submission artifact policy requires default-forbidden artifacts - guide activation or policy approval is blocked when project submission artifact policy downgrades Workstream blocking defaults -- generated effective submission artifact policy always contains Workstream defaults +- generated effective project submission artifact policy always contains Workstream defaults - guide activation succeeds with complete guide and policies - active guide can be retrieved for task creation - editing a draft guide works diff --git a/docs/spec_chunk_5_submission_packet_foundation.md b/docs/spec_chunk_5_submission_packet_foundation.md index 0a1641e..dab6cc9 100644 --- a/docs/spec_chunk_5_submission_packet_foundation.md +++ b/docs/spec_chunk_5_submission_packet_foundation.md @@ -45,8 +45,11 @@ Chunk 5 stores package and evidence references. Actual file storage still belong - `artifact_hash_manifest` - `worker_attestation` - `locked_guide_version` +- `locked_guide_source_snapshot_hash` - `locked_submission_artifact_policy_version` -- `locked_effective_submission_artifact_policy_hash` +- `locked_effective_project_submission_artifact_policy_hash` +- `locked_task_artifact_binding_id` +- `locked_effective_task_submission_artifact_policy_hash` - `locked_pre_submit_checker_policy_hash` - `locked_post_submit_checker_policy_version` - `locked_review_policy_version` @@ -122,13 +125,13 @@ Locks a submission packet before checker execution. Locking makes the packet imm - a worker can submit only when assigned to the task - first submission requires task status `IN_PROGRESS` -- Workstream loads the locked effective submission artifact policy hash before creating a submission +- Workstream loads the locked effective task submission artifact policy hash before creating a submission - Workstream loads the locked generated pre-submit checker policy snapshot/hash before creating a submission - blocking pre-submit failures prevent submission creation - when blocking pre-submit fails, no submission row is created, no submission version is assigned, no task transition to `SUBMITTED` occurs, and no submission-created audit event is written - first submission moves the task to `SUBMITTED` - later replacement submissions are allowed while the task is still `SUBMITTED` -- submission packet content must satisfy the effective submission artifact policy +- submission packet content must satisfy the effective task submission artifact policy - every submission creation writes a task audit event - the audit event includes submission id, submission version, worker id, package hash, and artifact hash manifest - locking a submission writes a task audit event @@ -163,7 +166,8 @@ Chunk 5 writes task audit events with submission identifiers in `event_payload`. - worker-provided guide or policy version fields are rejected by the API schema - worker-provided submission version fields are rejected by the API schema - worker-provided checker names, checker outcomes, evidence ids, and checker run ids are rejected by the API schema -- blocking pre-submit failures return `pre_submission_checker_failed` with structured pass/fail/warning details and create no submission row, no submission version, no task transition to `SUBMITTED`, and no submission-created audit event +- preflight failures return `PreSubmitCheckResponse(status="failed", eligible_to_submit=false, results=[...])` +- blocked submission-create attempts return `DomainError(code="pre_submission_checker_failed")` with structured pass/fail/warning details and create no submission row, no submission version, no task transition to `SUBMITTED`, and no submission-created audit event - Workstream stamps locked guide and policy versions from task context - task moves to `SUBMITTED` - submitted packet can be locked before checker execution diff --git a/docs/spec_chunk_6_checker_contract_records.md b/docs/spec_chunk_6_checker_contract_records.md index 3b14c26..5b5681c 100644 --- a/docs/spec_chunk_6_checker_contract_records.md +++ b/docs/spec_chunk_6_checker_contract_records.md @@ -212,12 +212,18 @@ Response fields: - `created_at` - `expires_at` -Pre-submit feedback binds to `task_id`, the task's locked guide version, the approved submission artifact policy context, draft packet fields, package hash, and artifact manifest shape. It does not require a locked `submission_id` or locked submission version because those do not exist before submission creation. - -Blocking pre-submit failures prevent submission creation. They return -`pre_submission_checker_failed` with structured pass/fail/warning details, -create no submission row, no submission version, no task transition to -`submitted`, and no submission-created audit event. +Pre-submit feedback binds to `task_id`, the task's locked guide source snapshot, +approved task artifact binding, effective task submission artifact policy hash, +draft packet fields, package hash, and artifact manifest shape. It does not +require a locked `submission_id` or locked submission version because those do +not exist before submission creation. + +Blocking pre-submit failures prevent submission creation. Preflight failures +return `PreSubmitCheckResponse(status="failed", eligible_to_submit=false, +results=[...])`. Blocked submission-create attempts return +`DomainError(code="pre_submission_checker_failed")` with structured +pass/fail/warning details, create no submission row, no submission version, no +task transition to `submitted`, and no submission-created audit event. Pre-submit results are not authoritative for `REVIEW_PENDING`, cannot create `NEEDS_REVISION`, and do not return review decision values: `accept`, diff --git a/docs/spec_chunk_7_checker_runner_registry.md b/docs/spec_chunk_7_checker_runner_registry.md index c9acca6..354a9c5 100644 --- a/docs/spec_chunk_7_checker_runner_registry.md +++ b/docs/spec_chunk_7_checker_runner_registry.md @@ -26,7 +26,7 @@ Note: Chunk 8 supersedes the temporary Chunk 7 artifact-manifest and evidence-re - checker service - checker API router - checker registry -- pre-submit intake feedback path generated from the effective submission artifact policy +- pre-submit intake feedback path generated from the effective task submission artifact policy - first structural checkers: - `check_submission_packet` - `check_policy_context_present` @@ -61,9 +61,13 @@ Pre-submit feedback is authoritative for submission intake, but it is not author The pre-submit checker set is generated by Workstream from: ```text -EffectiveSubmissionArtifactPolicy = +EffectiveProjectSubmissionArtifactPolicy = WorkstreamDefaultSubmissionArtifactPolicy + ProjectSubmissionArtifactPolicy + +EffectiveTaskSubmissionArtifactPolicy = + EffectiveProjectSubmissionArtifactPolicy + + ApprovedTaskArtifactBinding ``` Workers cannot supply checker names, policy versions, severities, blocking rules, results, or outcomes. @@ -138,11 +142,12 @@ For worker-fixable blocking structural failures after submission lock, the run r Chunk 7 records the recommendation only. Chunk 9 applies the lifecycle transition. -Blocking pre-submit failures occur before durable checker runs exist. They -prevent submission creation and return `pre_submission_checker_failed` with -structured pass/fail/warning details instead of recording `needs_revision`. -They do not return review decision values: `accept`, `needs_revision`, or -`reject`. +Blocking pre-submit failures occur before durable checker runs exist. Preflight +failures return `PreSubmitCheckResponse(status="failed", +eligible_to_submit=false, results=[...])`. Blocked submission-create attempts +return `DomainError(code="pre_submission_checker_failed")` with structured +pass/fail/warning details instead of recording `needs_revision`. They do not +return review decision values: `accept`, `needs_revision`, or `reject`. ## Artifact Manifest Hash @@ -178,7 +183,8 @@ Worker responses must not expose: - checker ORM models are registered in Alembic metadata - partial unique index allows one current run per submission - pre-submit check returns feedback without durable checker rows -- blocking pre-submit failures return `pre_submission_checker_failed`, include structured pass/fail/warning details, create no submission row, no submission version, no task transition to `submitted`, and no submission-created audit event +- preflight failures return `PreSubmitCheckResponse(status="failed", eligible_to_submit=false, results=[...])` +- blocked submission-create attempts return `DomainError(code="pre_submission_checker_failed")`, include structured pass/fail/warning details, create no submission row, no submission version, no task transition to `submitted`, and no submission-created audit event - durable checker run works through real authenticated API calls - `check_submission_packet` runs against real submission data - duplicate artifact manifests persist worker-visible checker failures diff --git a/docs/spec_chunk_8_submission_artifact_policy_checkers.md b/docs/spec_chunk_8_submission_artifact_policy_checkers.md index ae41e00..dadfbf6 100644 --- a/docs/spec_chunk_8_submission_artifact_policy_checkers.md +++ b/docs/spec_chunk_8_submission_artifact_policy_checkers.md @@ -112,7 +112,7 @@ Fails when required artifacts are not represented in the artifact manifest. The checker reads: -- `EffectiveSubmissionArtifactPolicy.required_artifacts`, or a server-locked task snapshot derived from it +- `EffectiveTaskSubmissionArtifactPolicy.required_artifacts` - `submission.artifact_hash_manifest[*].artifact` `task.required_files` is legacy/transitional storage. It is not the policy source of truth once `SubmissionArtifactPolicy` is implemented. @@ -192,7 +192,7 @@ If a future project needs generated-artifact signals to block review, that must ## Pre-Submit Versus Durable Runs -Pre-submit feedback runs checks generated from the effective submission artifact policy. These checks run before Workstream creates a submission row: +Pre-submit feedback runs checks generated from the effective task submission artifact policy. These checks run before Workstream creates a submission row: - `check_submission_packet` - `check_evidence_present` @@ -202,20 +202,23 @@ Pre-submit feedback runs checks generated from the effective submission artifact - `check_confidentiality_attestation` - `check_low_quality_generated_artifacts` -The effective submission artifact policy is: +The effective task submission artifact policy is: ```text WorkstreamDefaultSubmissionArtifactPolicy + ProjectSubmissionArtifactPolicy ++ ApprovedTaskArtifactBinding ``` Workstream defaults are non-bypassable. Project policy can add required artifacts, evidence requirements, stricter forbidden patterns, and packaging rules, but it cannot remove hash requirements, allow unsafe storage references, require forbidden files, or downgrade blocking defaults. -Blocking pre-submit failures prevent submission creation. They return -`pre_submission_checker_failed` with structured pass/fail/warning details, -create no submission row, no submission version, no task transition to -`submitted`, and no submission-created audit event. They do not return review -decision values: `accept`, `needs_revision`, or `reject`. +Blocking pre-submit failures prevent submission creation. Preflight failures +return `PreSubmitCheckResponse(status="failed", eligible_to_submit=false, +results=[...])`. Blocked submission-create attempts return +`DomainError(code="pre_submission_checker_failed")` with structured +pass/fail/warning details, create no submission row, no submission version, no +task transition to `submitted`, and no submission-created audit event. They do +not return review decision values: `accept`, `needs_revision`, or `reject`. Durable post-submit checker runs run the canonical default submission-quality checks plus locked checker-policy names: @@ -300,8 +303,9 @@ Safe evidence references mean opaque Workstream evidence ids, sanitized labels, - canonical Chunk 8 checker names are registered - stale Chunk 7 temporary checker names are removed from public docs/templates/tests -- pre-submit feedback is generated from the effective submission artifact policy and runs without durable checker records -- blocking pre-submit failures return `pre_submission_checker_failed`, include structured pass/fail/warning details, create no submission row, no submission version, no task transition to `submitted`, and no submission-created audit event +- pre-submit feedback is generated from the effective task submission artifact policy and runs without durable checker records +- preflight failures return `PreSubmitCheckResponse(status="failed", eligible_to_submit=false, results=[...])` +- blocked submission-create attempts return `DomainError(code="pre_submission_checker_failed")`, include structured pass/fail/warning details, create no submission row, no submission version, no task transition to `submitted`, and no submission-created audit event - Workstream default submission artifact rules cannot be weakened by project policy - durable checker runs persist Chunk 8 checker results - missing required evidence blocks review routing diff --git a/docs/spec_week2_checker_framework.md b/docs/spec_week2_checker_framework.md index 9147fc3..09f20d6 100644 --- a/docs/spec_week2_checker_framework.md +++ b/docs/spec_week2_checker_framework.md @@ -37,7 +37,7 @@ The checker framework protects reviewer time by proving that the latest locked s ## Core Invariant ```text -Draft packet -> EffectiveSubmissionArtifactPolicy -> Pre-submit checks -> Submit -> Lock -> Internal CheckerRun -> CheckerResults -> routing recommendation +Draft packet -> EffectiveTaskSubmissionArtifactPolicy -> Pre-submit checks -> Submit -> Lock -> Internal CheckerRun -> CheckerResults -> routing recommendation ``` A task cannot reach `REVIEW_PENDING` unless the latest locked submission has a completed checker run for the exact submission version and artifact context. @@ -61,7 +61,7 @@ The checker binding includes: Workstream has two checker moments. -Pre-submit static checks run before Workstream creates a submission. They are generated from the effective submission artifact policy and give immediate feedback on packet shape and policy issues: +Pre-submit static checks run before Workstream creates a submission. They are generated from the effective task submission artifact policy and give immediate feedback on packet shape and policy issues: - required field presence - package hash presence @@ -71,10 +71,12 @@ Pre-submit static checks run before Workstream creates a submission. They are ge - storage reference safety - task assignment and state compatibility -Blocking pre-submit failures prevent submission creation. They return -`pre_submission_checker_failed` with structured pass/fail/warning details, -create no submission row, no submission version, no task transition to -`submitted`, and no submission-created audit event. +Blocking pre-submit failures prevent submission creation. Preflight failures +return `PreSubmitCheckResponse(status="failed", eligible_to_submit=false, +results=[...])`. Blocked submission-create attempts return +`DomainError(code="pre_submission_checker_failed")` with structured +pass/fail/warning details, create no submission row, no submission version, no +task transition to `submitted`, and no submission-created audit event. Pre-submit failures do not create review decisions, do not return `accept`, `needs_revision`, or `reject`, and do not create durable post-submit checker diff --git a/docs/template_checker_policy.md b/docs/template_checker_policy.md index aa3f14e..305e7a2 100644 --- a/docs/template_checker_policy.md +++ b/docs/template_checker_policy.md @@ -12,7 +12,7 @@ This template governs durable internal checker runs after a submission is created, locked, and ready for the pre-review gate. -It does not define pre-submit intake. `PreSubmitCheckerPolicy` is generated from `EffectiveSubmissionArtifactPolicy`. +It does not define pre-submit intake. `PreSubmitCheckerPolicy` is generated from `EffectiveTaskSubmissionArtifactPolicy`. ## Design Boundaries @@ -50,15 +50,21 @@ Task setup checks: Pre-submit checker policy is generated from: ```text -EffectiveSubmissionArtifactPolicy = +EffectiveProjectSubmissionArtifactPolicy = WorkstreamDefaultSubmissionArtifactPolicy + ProjectSubmissionArtifactPolicy + +EffectiveTaskSubmissionArtifactPolicy = + EffectiveProjectSubmissionArtifactPolicy + + ApprovedTaskArtifactBinding ``` -Blocking pre-submit failures prevent submission creation, return -`pre_submission_checker_failed` with structured pass/fail/warning details, do -not create durable `CheckerRun` records, and do not return review decision -values: `accept`, `needs_revision`, or `reject`. +Preflight failures return `PreSubmitCheckResponse(status="failed", +eligible_to_submit=false, results=[...])`. Blocked submission-create attempts +return `DomainError(code="pre_submission_checker_failed")` with structured +pass/fail/warning details. Pre-submit failures do not create durable +`CheckerRun` records and do not return review decision values: `accept`, +`needs_revision`, or `reject`. ## Checker Registry Fields diff --git a/docs/template_preflight_evidence.md b/docs/template_preflight_evidence.md index dba54dc..b602fde 100644 --- a/docs/template_preflight_evidence.md +++ b/docs/template_preflight_evidence.md @@ -2,7 +2,7 @@ This template is for post-submit review readiness evidence after a submission exists and checker runs have produced durable records. -It is not the pre-submit intake contract. Pre-submit intake is generated from `EffectiveSubmissionArtifactPolicy` and blocks submission creation before a submission id, evidence id, or checker run id exists. +It is not the pre-submit intake contract. Pre-submit intake is generated from `EffectiveTaskSubmissionArtifactPolicy` and blocks submission creation before a submission id, evidence id, or checker run id exists. ## Task diff --git a/docs/template_project_guide.md b/docs/template_project_guide.md index 85fcb88..c2e3357 100644 --- a/docs/template_project_guide.md +++ b/docs/template_project_guide.md @@ -107,15 +107,21 @@ This section is a human-readable summary. The enforcement source is the approved Every active guide version must have: +- GuideSourceSnapshot: - GuideSufficiencyReport: - SubmissionArtifactPolicy: -- EffectiveSubmissionArtifactPolicy hash: -- generated PreSubmitCheckerPolicy: +- EffectiveProjectSubmissionArtifactPolicy hash: - PostSubmitCheckerPolicy: - ReviewPolicy: - RevisionPolicy: - PaymentPolicy: +Each task later locks: + +- ApprovedTaskArtifactBinding: +- EffectiveTaskSubmissionArtifactPolicy hash: +- generated PreSubmitCheckerPolicy: + Artifact requirements shown to workers are derived from the approved `SubmissionArtifactPolicy`. The guide may summarize those requirements, but the policy is the enforcement source. Project owners provide open-ended guide material and business terms in plain diff --git a/docs/template_submission_artifact_policy.md b/docs/template_submission_artifact_policy.md index 2f69a19..4ddcebb 100644 --- a/docs/template_submission_artifact_policy.md +++ b/docs/template_submission_artifact_policy.md @@ -19,15 +19,18 @@ Workstream derives this policy from that material after guide sufficiency passes or warnings are acknowledged. Project owners do not author or approve the machine-readable Workstream policy schema directly. -Source material refs: +Source snapshot: -- project guide version: -- imported document refs: -- URL-backed documentation refs: -- repository documentation refs: -- task example refs: -- rubric refs: -- business term refs: +- guide source snapshot id: +- guide source snapshot hash: +- ingestion adapter: +- durable source ref: +- content cid: `` +- captured at: + +Temporary fetch locators are adapter inputs only. Durable source refs must not +store query strings, signed URLs, credentials, token-bearing refs, local +filesystem paths, or private storage paths. ## Guide Sufficiency @@ -44,7 +47,8 @@ Source material refs: - derivation agent name: - derivation agent version: - sufficiency report id: -- source material refs: +- source snapshot id: +- source snapshot hash: - approval status: `draft | approved | superseded` - approved policy hash: - approved by role: `admin | project_manager` @@ -93,6 +97,21 @@ Default forbidden artifacts: A project-required artifact that matches a Workstream default forbidden rule remains blocked. That conflict is a project setup defect. +## Effective Policy Merge Rules + +| Field | Merge Rule | +| --- | --- | +| required artifacts | union by canonical artifact key | +| required evidence | union by canonical evidence key | +| forbidden artifacts | union | +| attestation terms | union | +| manifest required | logical OR | +| hash required | logical OR | +| allowed storage schemes | intersection | +| hash algorithm | platform-locked value or intersection | +| maximum file/package size | minimum non-null limit | +| packaging rules | restrictive merge; conflicts block setup | + ## Project Required Artifacts | Artifact | Required | Hash Required | Notes | @@ -131,11 +150,12 @@ Required attestation topics: ## Generated Pre-Submit Checker Policy -Workstream generates `PreSubmitCheckerPolicy` from: +Workstream generates task-level `PreSubmitCheckerPolicy` from: ```text WorkstreamDefaultSubmissionArtifactPolicy + ProjectSubmissionArtifactPolicy ++ ApprovedTaskArtifactBinding ``` Generated pre-submit checks run before submission creation. Blocking failures create no submission row, no submission version, no task transition to `submitted`, and no submission-created audit event. @@ -144,12 +164,14 @@ Generated policy lock: - generated pre-submit checker policy version: - generated pre-submit checker policy hash: -- effective submission artifact policy hash: +- effective task submission artifact policy hash: - locked guide version: -Blocking failures return `pre_submission_checker_failed` with structured -pass/fail/warning details. They do not return review decision values: -`accept`, `needs_revision`, or `reject`. +Blocked submission-create attempts return `pre_submission_checker_failed` with +structured pass/fail/warning details. +The preflight endpoint returns `PreSubmitCheckResponse` with `status`, +`eligible_to_submit`, and `results`. Neither path returns review decision +values: `accept`, `needs_revision`, or `reject`. Expected generated checks: @@ -170,3 +192,6 @@ Expected generated checks: - approved by actor: - effective at: - change summary: +- supersedes policy id: + +Approved and superseded policies are immutable. Changes create a new revision. diff --git a/docs/template_submission_packet.md b/docs/template_submission_packet.md index b8a86d4..fb45000 100644 --- a/docs/template_submission_packet.md +++ b/docs/template_submission_packet.md @@ -29,10 +29,12 @@ List files, links, packages, or deliverables. Workstream derives the locked project guide version, submission artifact policy version, generated pre-submit checker policy hash, post-submit checker policy version, review policy version, revision policy version, and payment policy version from the task and server-side project policy records. The worker does not provide those versions in the submission packet. Workstream runs generated pre-submit checks before creating the submission. -Blocking failures return `pre_submission_checker_failed` with structured -pass/fail/warning details, create no submission row, no submission version, and -no submission-created audit event, and do not return review decision values: -`accept`, `needs_revision`, or `reject`. +Preflight failures return `PreSubmitCheckResponse` with structured +pass/fail/warning details. Blocked submission-create attempts return +`pre_submission_checker_failed` with the same structured details, create no +submission row, no submission version, and no submission-created audit event, +and do not return review decision values: `accept`, `needs_revision`, or +`reject`. ## Artifact Hash Manifest From 5a7c6b3ad0ff34172eda5fd32f6ecddc28ec7cb9 Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Wed, 24 Jun 2026 12:44:29 +0100 Subject: [PATCH 23/37] Refresh source snapshot review evidence --- .agent-loop/LOOP_STATE.md | 2 +- .../WS-POL-001-01-internal-review-evidence.md | 28 +++++++++++++------ 2 files changed, 20 insertions(+), 10 deletions(-) diff --git a/.agent-loop/LOOP_STATE.md b/.agent-loop/LOOP_STATE.md index 7cd124a..7e5535c 100644 --- a/.agent-loop/LOOP_STATE.md +++ b/.agent-loop/LOOP_STATE.md @@ -7,7 +7,7 @@ - Branch: `codex/submission-artifact-policy-loop-plan` - Status: planning review requested; implementation has not started - Merge commit: none for this initiative -- Reviewed code SHA: `3c577ab4215d7f8fce9e2bf2d817f4fc270eb6c8` +- Reviewed code SHA: `9099b60533ba49eb3232fdf505dc17c69c8cbdad` - Current gate: human planning approval pending; backend implementation is not approved - Next chunk: inactive until `WS-POL-001-01` is approved and completed diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md index 58a9d40..90085aa 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md @@ -10,13 +10,13 @@ valid findings addressed: yes ## Reviewed Revision -Reviewed code SHA: 3c577ab4215d7f8fce9e2bf2d817f4fc270eb6c8 +Reviewed code SHA: 9099b60533ba49eb3232fdf505dc17c69c8cbdad -Reviewed at: 2026-06-23T19:08:10Z +Reviewed at: 2026-06-24T11:38:57Z -Reviewer run IDs: 019ef3df-a4ae-71f0-b50c-dbd99e65af6c, 019ef3e0-cc78-7583-abd8-826f77b6d435, 019ef3e2-d1fc-7642-b079-561bf61b3d07, 019ef3e5-1e10-78f2-b272-f06200c50334, 019ef3e7-6f3d-7730-a2fd-adc55e496811, 019ef3ea-b44c-7741-9ced-b05bb6a5e5d2, 019ef432-a806-75c1-96ac-11c93eea2f9c, 019ef45d-540a-71e1-9531-19277d5450ed, 019ef45f-a5fa-7721-b9ae-aa39b1f6778e, 019ef462-b086-7923-a03e-78c298316f73, 019ef466-2433-7bf3-9335-069cfa5b5838, 019ef46a-171d-7b42-9795-773132754ff0, 019ef46e-dcea-7423-aa46-47a27b098c85, 019ef51b-8491-7192-a868-f2cbc1c56079, 019ef51d-cc5d-7d40-b5e6-0966c546e465, 019ef520-eea1-71c0-919a-63d24728ff32, 019ef523-f173-7e71-8685-902518610fda, 019ef52a-1da8-7df2-9428-c96b1b0cc164, 019ef5c5-db38-76a1-8617-4572f7ebc7a2, 019ef5c7-2666-7e73-9147-4544265a3818, 019ef5c9-2749-75b2-819d-d7018f2b0e12, 019ef5cb-cc57-7151-b2ec-0f0d49ed0fb1 +Reviewer run IDs: 019ef3df-a4ae-71f0-b50c-dbd99e65af6c, 019ef3e0-cc78-7583-abd8-826f77b6d435, 019ef3e2-d1fc-7642-b079-561bf61b3d07, 019ef3e5-1e10-78f2-b272-f06200c50334, 019ef3e7-6f3d-7730-a2fd-adc55e496811, 019ef3ea-b44c-7741-9ced-b05bb6a5e5d2, 019ef432-a806-75c1-96ac-11c93eea2f9c, 019ef45d-540a-71e1-9531-19277d5450ed, 019ef45f-a5fa-7721-b9ae-aa39b1f6778e, 019ef462-b086-7923-a03e-78c298316f73, 019ef466-2433-7bf3-9335-069cfa5b5838, 019ef46a-171d-7b42-9795-773132754ff0, 019ef46e-dcea-7423-aa46-47a27b098c85, 019ef51b-8491-7192-a868-f2cbc1c56079, 019ef51d-cc5d-7d40-b5e6-0966c546e465, 019ef520-eea1-71c0-919a-63d24728ff32, 019ef523-f173-7e71-8685-902518610fda, 019ef52a-1da8-7df2-9428-c96b1b0cc164, 019ef5c5-db38-76a1-8617-4572f7ebc7a2, 019ef5c7-2666-7e73-9147-4544265a3818, 019ef5c9-2749-75b2-819d-d7018f2b0e12, 019ef5cb-cc57-7151-b2ec-0f0d49ed0fb1, 019ef92b-9da7-7140-878a-1b12c6ed5cd9, 019ef92c-c0a4-7922-8a8c-7257ddb20919, 019ef92e-95d3-72d3-8519-c6ef83548bf8, 019ef930-f548-7dc1-beb4-b055c1f10363, 019ef933-f0a4-7ad3-a882-9a45b9e9b638, 019ef937-5144-7190-b4c5-f83af54de620, 019ef95b-77c6-7331-8dab-e3e7e9207f7a -After reviewed SHA `3c577ab4215d7f8fce9e2bf2d817f4fc270eb6c8`, only review evidence and loop status artifacts changed. +After reviewed SHA `9099b60533ba49eb3232fdf505dc17c69c8cbdad`, only review evidence and loop status artifacts changed. ## Reviewer Results @@ -44,16 +44,25 @@ After reviewed SHA `3c577ab4215d7f8fce9e2bf2d817f4fc270eb6c8`, only review evide | response-contract QA/test | PASS AFTER FIXES | None remaining | Verified the architecture doc matches `backend/app/modules/checkers/schemas.py` and requested evidence refresh. Fixed. | | response-contract security/auth | PASS AFTER FIXES | None remaining | Confirmed pre-submit failure remains separate from review decisions and requested evidence refresh. Fixed. | | response-contract product/ops | PASS AFTER FIXES | None remaining | Confirmed operator-facing wording is clear and requested external review artifact cleanup plus evidence refresh. Fixed. | +| source-snapshot senior engineering | PASS AFTER FIXES | None remaining | Requested READY gate and checker-policy template alignment to task-specific policy binding. Fixed. | +| source-snapshot QA/test | PASS AFTER FIXES | None remaining | Requested Chunk 1 proof stay limited to guide snapshot, sufficiency, project policy, effective project policy hash, activation guard, and source/policy invariants. Fixed. | +| source-snapshot security/auth | PASS AFTER FIXES | None remaining | Requested durable source refs never persist query strings and READY require task-level source/policy binding. Fixed. | +| source-snapshot product/ops | PASS AFTER FIXES | None remaining | Requested removal of project-level pre-submit checker wording. Fixed. | +| source-snapshot architecture | PASS AFTER FIXES | None remaining | Requested canonical lineage and removal of old `EffectiveSubmissionArtifactPolicy` source-of-truth naming. Fixed. | +| source-snapshot docs | PASS AFTER FIXES | None remaining | Requested activation/readiness contract alignment and API wording cleanup. Fixed. | +| source-snapshot test delta | PASS AFTER FIXES | None remaining | Confirmed compiler proof moved to Chunk 2 and task runtime migration moved to Chunk 3, then requested migration scope and remaining activation-doc cleanup. Fixed. | ## Valid Findings Addressed - Added explicit untrusted-source-material rules for project owner docs, URLs, repository docs, examples, and imported documents. -- Added source-ref sanitization requirements for signed URLs, query-bearing refs, credential-bearing refs, and local filesystem paths. +- Added immutable `GuideSourceSnapshot` binding with source snapshot id/hash on downstream report, policy, task binding, effective policy, and checker-bundle records. +- Clarified that ordinary URL query parameters may be temporary approved-adapter fetch inputs only; durable source refs cannot persist query strings, signed URLs, credentials, token-bearing refs, local filesystem paths, or private storage paths. - Clarified that guide text and imported material cannot grant tool authority, override Workstream rules, or weaken default policy. -- Tightened Chunk 1 proof to require Postgres-backed FastAPI/API tests for activation blocking, warning acknowledgement by `admin` or `project_manager`, approval provenance, default weakening, source-ref sanitization, and pre-submit policy locking. +- Tightened Chunk 1 proof to require Postgres-backed FastAPI/API tests for guide source snapshots, activation blocking, warning acknowledgement by `admin` or `project_manager`, approval provenance, default weakening, source-ref sanitization, append-only policy rows, and effective project policy hash persistence. - Added per-chunk verification expectations for async guide analysis, submission creation, post-submit policy split, and revision resubmission real API drill. -- Updated activation docs to require passed or acknowledged `GuideSufficiencyReport`, approved `SubmissionArtifactPolicy`, persisted `EffectiveSubmissionArtifactPolicy` hash, generated `PreSubmitCheckerPolicy`, post-submit checker policy, review policy, revision policy, and payment policy. -- Replaced stale runtime wording that implied recomputing/generating pre-submit policy at submission time with loading the locked effective policy hash and locked `PreSubmitCheckerPolicy` snapshot/hash. +- Updated activation docs to require guide source snapshot, passed or acknowledged `GuideSufficiencyReport`, approved `SubmissionArtifactPolicy`, `EffectiveProjectSubmissionArtifactPolicy` hash, post-submit checker policy, review policy, revision policy, and payment policy. +- Updated task readiness docs to require `ApprovedTaskArtifactBinding`, `EffectiveTaskSubmissionArtifactPolicy` hash, and task-level `PreSubmitCheckerPolicy` before workers can claim work. +- Replaced stale runtime wording that implied one project-level pre-submit checker with the canonical lineage: `GuideSourceSnapshot -> ProjectSubmissionArtifactPolicy -> EffectiveProjectSubmissionArtifactPolicy -> ApprovedTaskArtifactBinding -> EffectiveTaskSubmissionArtifactPolicy -> PreSubmitCheckerPolicy`. - Replaced ambiguous `derivation source: manual | workstream_agent | import_adapter` wording with source-material ingestion method and kept derivation agent fields mandatory. - Added missing approval provenance fields to the data model example. - Updated loop state to point at the current internal review evidence instead of saying no evidence exists. @@ -62,7 +71,8 @@ After reviewed SHA `3c577ab4215d7f8fce9e2bf2d817f4fc270eb6c8`, only review evide - Added Chunk 4 schema/persistence proof that pre-submit feedback cannot store review decision values. - Locked the default pre-submit path to constrained checker specifications and Workstream-compiled deterministic checker bundles, not unrestricted generated checker code. - Added data model fields for `checker_spec`, `compiler_version`, `compiled_bundle_hash`, and immutable `compiled_bundle`. -- Added proof obligations for primitive allowlisting, unknown primitive rejection, canonical compiled bundle hashing, hash binding to `effective_submission_artifact_policy_hash`, immutable compiled bundle behavior, and absence of executable code fields by default. +- Moved compiler proof obligations to Chunk 2, where checker modules and checker tests are allowed. +- Moved task binding, `EffectiveTaskSubmissionArtifactPolicy`, task-level `PreSubmitCheckerPolicy`, transitional task-field replacement, and submission runtime migration to Chunk 3, where task/checker modules and migrations are allowed. - Tightened future executable-checker extension requirements to require static validation, generated tests, sandbox policy checks, no network, no shell, no secrets, no database access, and `admin` or `project_manager` approval of the exact locked code hash after those checks pass. - Corrected the checker framework response wording to match the current `PreSubmitCheckResponse` schema: `status`, `eligible_to_submit`, and `results`, with `pre_submission_checker_failed` treated as the user-facing failure condition rather than a response field. - Corrected the external review response artifact so CodeRabbit feedback is tracked separately from internal review evidence and does not claim a nonexistent `failure_code` field in pre-submit responses. From a2c7c0ba48e865a763b05fa7c17000d3b2b60e3d Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Wed, 24 Jun 2026 17:02:03 +0100 Subject: [PATCH 24/37] Finalize submission policy planning consistency --- .../CHUNK_MAP.md | 34 +++-- .../DECISIONS.md | 10 +- .../INTENT.md | 24 ++-- .../PLAN.md | 28 ++-- ...1-submission-artifact-policy-foundation.md | 18 ++- .../WS-POL-001-01-external-review-response.md | 4 + docs/architecture_checker_framework.md | 13 +- docs/architecture_data_model.md | 136 ++++++++++++++---- docs/architecture_lockdown.md | 3 +- docs/current_system_data_flow.html | 4 +- ...ssion_artifact_policy_drives_pre_submit.md | 36 +++-- docs/glossary.md | 16 ++- docs/template_submission_artifact_policy.md | 37 +++-- 13 files changed, 253 insertions(+), 110 deletions(-) diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md index 3abfccd..d35f980 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md @@ -19,7 +19,7 @@ is not the default path. - Reports, derived policies, acknowledgements, effective policies, task bindings, and checker bundles bind to immutable `GuideSourceSnapshot` - id/hash, not only to `guide_version`. + bundle id/hash, not only to `guide_version`. ## Chunks @@ -67,13 +67,15 @@ full async agent execution runtime Acceptance criteria: - Dedicated submission artifact policy model/table exists. -- Dedicated immutable guide source snapshot model/table exists. +- Dedicated immutable guide source snapshot bundle model/table exists. +- Dedicated guide source snapshot item model/table exists, or the snapshot + table stores an equivalent canonical manifest for every source item. - Dedicated guide sufficiency report model/table exists. - Guide sufficiency report supports `passed`, `blocked`, and `passed_with_warnings`. - Project policy is scoped to project id + guide version. - Guide sufficiency report, project policy, and effective project policy bind to - `source_snapshot_id` and `source_snapshot_hash`. + `source_snapshot_id` and server-derived `source_snapshot_hash`. - Project policy records are Workstream-derived and approved by `admin` or `project_manager`, not direct project owner-authored schema. - Workstream default policy is represented in code. @@ -88,7 +90,7 @@ Acceptance criteria: - Guide activation requires passing or acknowledged guide sufficiency, approved submission artifact policy, and effective project policy hash bound to the current guide source snapshot. -- Project-owner source refs persist as sanitized snapshot refs and cannot store +- Project-owner source refs persist as sanitized snapshot item refs and cannot store signed URLs, credential-bearing refs, token-bearing refs, or local filesystem paths. Approved adapters can use ordinary URL query parameters only as temporary fetch locators. @@ -122,8 +124,8 @@ Chunk 1 limited to records/contracts/activation guards. Goal: Run `ProjectGuideSufficiencyAgent`, -`SubmissionArtifactPolicyDerivationAgent`, and the trusted checker compiler -asynchronously against immutable guide-source snapshots. +`SubmissionArtifactPolicyDerivationAgent`, and project checker-spec +canonicalization asynchronously against immutable guide-source snapshots. Risk: @@ -161,10 +163,12 @@ Acceptance criteria: - `SubmissionArtifactPolicyDerivationAgent` runs async after sufficiency passes or warnings are acknowledged. - Derived policy cannot weaken Workstream defaults. -- Derived checker specification uses only approved Workstream primitives. -- Trusted checker compiler produces deterministic `PreSubmitCheckerPolicy` - project-level contract snapshot/hash from the approved specification. -- Derived report, project policy, effective project policy, and compiler output +- `SubmissionArtifactPolicyDerivationAgent` produces + `ProjectPreSubmitCheckerSpec` using only approved Workstream primitives. +- Trusted checker compiler validates and canonicalizes the project checker + specification, producing a stable project checker spec hash. Chunk 2 does not + persist a project-level `PreSubmitCheckerPolicy` row. +- Derived report, project policy, effective project policy, and project checker spec are invalidated by a new guide source snapshot. - Malicious guide text, embedded prompt-injection instructions, and unsafe source refs cannot influence agent authority, fetch behavior, or default @@ -180,10 +184,10 @@ Verification: - Background execution tests prove jobs are async and idempotent for a guide source snapshot. - Compiler tests prove allowed primitive emission, unknown primitive rejection, - byte-stable same-input same-compiler-version bundle hashing, hash binding to - `effective_project_submission_artifact_policy_hash`, and client/worker inability to - supply checker names, severities, versions, outcomes, compiler version, or - compiled bundles. + byte-stable same-input same-compiler-version project spec hashing, hash + binding to `effective_project_submission_artifact_policy_hash`, and + client/worker inability to supply checker names, severities, versions, + outcomes, compiler version, or project checker specs. Required reviewers: @@ -239,6 +243,8 @@ Acceptance criteria: defaults or the effective project policy. - `EffectiveTaskSubmissionArtifactPolicy` is generated from effective project policy plus task binding and locked before `SCREENING` or `READY`. +- Chunk 3 combines the approved task binding, effective task policy, and + approved `ProjectPreSubmitCheckerSpec`. - Task-level generated `PreSubmitCheckerPolicy` is persisted with `compiled_bundle` as canonical JSON source of truth and `compiled_bundle_hash` as its canonical hash. diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md index c33bd9a..85c216e 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md @@ -19,6 +19,8 @@ `ProjectSubmissionArtifactPolicy` after guide sufficiency passes. - `SubmissionArtifactPolicyDerivationAgent` produces constrained policy and checker specifications, not unrestricted executable checker code. +- `SubmissionArtifactPolicyDerivationAgent` produces + `ProjectPreSubmitCheckerSpec` during project setup. - Workstream derives `ProjectSubmissionArtifactPolicy` from project material, with internal agent assistance allowed, then requires approval by `admin` or `project_manager` before guide activation. @@ -27,8 +29,9 @@ - `EffectiveTaskSubmissionArtifactPolicy` is effective project policy plus an approved task artifact binding. - Workstream's trusted checker compiler turns the constrained checker - specification into deterministic `PreSubmitCheckerPolicy`, persisted and - locked to the effective task policy hash. + specification into deterministic task-level `PreSubmitCheckerPolicy` only + after task binding produces the effective task policy hash. There is no + project-level `PreSubmitCheckerPolicy` row. - Pre-submit checks block before submission creation. - Preflight feedback is `PreSubmitCheckResponse`; blocked submission-create attempts return `pre_submission_checker_failed` with structured @@ -47,7 +50,8 @@ artifact blocking, required artifact presence, required evidence presence, worker attestation validation, and low-quality/generated artifact warnings. - Workstream default hard rules require production hashes shaped as - `sha256:<64 lowercase hex>`, safe relative artifact paths, no absolute paths, + `sha256:<64 lowercase hex>` with `sha256` as the platform-locked artifact + hash algorithm, safe relative artifact paths, no absolute paths, no traversal paths, no raw signed URLs, no query-string storage refs, no local filesystem paths, no credential/token-bearing refs, and no default-forbidden artifacts such as `.env`, `.git`, private keys, secrets, tokens, and diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md index 8ad1db9..2dfaf76 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md @@ -27,6 +27,7 @@ Project owner material -> ProjectGuideSufficiencyAgent -> SubmissionArtifactPolicyDerivationAgent -> Workstream-derived ProjectSubmissionArtifactPolicy +-> ProjectPreSubmitCheckerSpec -> approval by admin or project_manager WorkstreamDefaultSubmissionArtifactPolicy @@ -38,7 +39,7 @@ EffectiveProjectSubmissionArtifactPolicy = EffectiveTaskSubmissionArtifactPolicy EffectiveTaskSubmissionArtifactPolicy --> constrained pre-submit checker specification +-> approved ProjectPreSubmitCheckerSpec -> trusted Workstream checker compiler -> persisted and locked PreSubmitCheckerPolicy ``` @@ -64,12 +65,13 @@ remain visible to the Workstream `admin` or `project_manager` and must be acknowledged before activation. After sufficiency passes, the `SubmissionArtifactPolicyDerivationAgent` derives -the machine-readable project submission artifact policy. The project owner does -not approve this internal policy. A Workstream actor with the `admin` or -`project_manager` role approves the derived policy and activates the -guide-policy bundle. Workers submit draft packet fields. Workstream decides -required artifacts, evidence, hashes, storage reference rules, forbidden -artifacts, and blocking pre-submit feedback from the locked effective policy. +the machine-readable project submission artifact policy and +`ProjectPreSubmitCheckerSpec`. The project owner does not approve this internal +policy. A Workstream actor with the `admin` or `project_manager` role approves +the derived policy and activates the guide-policy bundle. Workers submit draft +packet fields. Workstream decides required artifacts, evidence, hashes, storage +reference rules, forbidden artifacts, and blocking pre-submit feedback from the +locked effective policy. The derivation agent produces a constrained artifact-intake contract and checker specification. Workstream compiles that specification into deterministic checker @@ -100,7 +102,7 @@ After this initiative: approved by `admin` or `project_manager`, not authored directly by the project owner. - `GuideSourceSnapshot` is a first-class immutable record for the exact guide - material Workstream evaluated. + material bundle Workstream evaluated. - `GuideSufficiencyReport` is a first-class record tied to a guide source snapshot. - Workstream default submission artifact rules are defined in code. @@ -110,8 +112,10 @@ After this initiative: artifact policy hashes. - Generated pre-submit checker policy is persisted and locked to the effective task policy hash. -- Generated pre-submit checker policy is produced by Workstream's trusted - compiler from approved checker primitives, not by unrestricted generated code. +- `ProjectPreSubmitCheckerSpec` is produced during project setup, then + Workstream's trusted compiler produces the final task-level generated + pre-submit checker policy from approved checker primitives, not by + unrestricted generated code. - Submission creation uses the generated pre-submit policy before a submission row is created. - Post-submit/internal checker policy remains separate. diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md index 25381f0..170d85a 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md @@ -19,7 +19,7 @@ ProjectGuide open-ended human-facing project material GuideSourceSnapshot - immutable capture of the exact guide/source bytes Workstream evaluated + immutable bundle manifest for the exact guide/source material Workstream evaluated GuideSufficiencyReport Workstream-owned assessment of whether the guide is sufficient @@ -40,7 +40,7 @@ EffectiveTaskSubmissionArtifactPolicy deterministic merge of effective project policy + approved task binding PreSubmitCheckerPolicy - persisted and locked checker rules for draft packet intake + persisted and locked task-level checker rules for draft packet intake PostSubmitCheckerPolicy durable checker rules for locked submission review readiness @@ -59,9 +59,10 @@ retrieval paths. Temporary fetch locators can include ordinary URL query parameters when an approved adapter needs them, but signed URLs, credential-bearing refs, token-bearing refs, and local filesystem paths are rejected. Workstream persists only immutable `GuideSourceSnapshot` records with -opaque sanitized source refs, content hash, optional future content id, adapter -name, and capture timestamp. It never persists signed URLs, credentials, or -token-bearing locators as durable source identity. +canonical manifests, bundle hashes, opaque sanitized source refs, per-item +content hashes, optional future content ids, adapter names, and capture +timestamps. It never persists signed URLs, credentials, or token-bearing +locators as durable source identity. `SubmissionArtifactPolicyDerivationAgent` derives machine-readable `ProjectSubmissionArtifactPolicy` after guide sufficiency passes. A Workstream @@ -69,18 +70,20 @@ actor with the `admin` or `project_manager` role approves the derived policy. Workstream then computes the effective project policy and later combines it with approved task-specific artifact bindings to produce an `EffectiveTaskSubmissionArtifactPolicy` locked before a task enters -`SCREENING` or `READY`. The generated `PreSubmitCheckerPolicy` snapshot/hash is -locked to that effective task policy. Pre-submit checks run before submission -creation and do not create durable checker records. +`SCREENING` or `READY`. The generated task-level `PreSubmitCheckerPolicy` +snapshot/hash is locked to that effective task policy. Pre-submit checks run +before submission creation and do not create durable checker records. Post-submit/internal checks run after submission lock and do create durable checker records. The derivation agent does not generate unrestricted executable checker code. It produces a constrained checker specification using Workstream-approved primitives. Workstream's trusted checker compiler turns that specification into -the deterministic `PreSubmitCheckerPolicy` bundle. Runtime checks execute the -locked compiled bundle against staged artifact hashes or future content -identifiers. +a canonical `ProjectPreSubmitCheckerSpec` during project setup. The final +task-level compiler step combines that approved project checker specification +with the approved task binding and effective task policy, then persists the +deterministic `PreSubmitCheckerPolicy` bundle. Runtime checks execute the locked +compiled bundle against staged artifact hashes or future content identifiers. If no immutable guide-source snapshot, passing or acknowledged guide sufficiency report, approved project submission artifact policy, and effective project @@ -96,6 +99,9 @@ bundles bind to the exact `GuideSourceSnapshot` id/hash, not only to `guide_version`. Any guide or source-material change creates a new snapshot and invalidates prior sufficiency reports, derived project policies, effective policies, checker bundles, acknowledgements, and approvals for activation. +A new guide-source snapshot invalidates prior setup records for new activation +and unlocked tasks only. Tasks already locked to an earlier snapshot retain +that policy context unless an explicit audited rebase occurs. ## Alternatives Considered diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md index c0a9c7d..00e5849 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md @@ -34,7 +34,8 @@ Project owner material is untrusted input. Guide text, URLs, repository docs, examples, and imported documents cannot grant tool authority, override Workstream rules, or weaken default checks. Approved adapters can use temporary fetch locators for source ingestion, but durable source identity must be an -immutable `GuideSourceSnapshot` with sanitized source ref and content hash. +immutable `GuideSourceSnapshot` bundle with a canonical manifest, sanitized +source item refs, and per-item content hashes. ## Approved Plan Reference @@ -92,16 +93,18 @@ human review implementation ## Acceptance Criteria - [ ] Dedicated `SubmissionArtifactPolicy` model/table exists. -- [ ] Dedicated immutable `GuideSourceSnapshot` model/table exists. +- [ ] Dedicated immutable `GuideSourceSnapshot` bundle model/table exists. +- [ ] Dedicated `GuideSourceSnapshotItem` model/table exists, or the snapshot + stores an equivalent canonical manifest for every source item. - [ ] Dedicated `GuideSufficiencyReport` model/table exists. - [ ] Guide sufficiency report records `passed`, `blocked`, or `passed_with_warnings`. -- [ ] Guide sufficiency report binds to `source_snapshot_id` and - `source_snapshot_hash`. +- [ ] Guide sufficiency report binds to `source_snapshot_id` and server-derived + `source_snapshot_hash` from `GuideSourceSnapshot.bundle_hash`. - [ ] Blocking guide sufficiency findings prevent guide activation. - [ ] Warning guide sufficiency findings require `admin` or `project_manager` acknowledgement before guide activation. -- [ ] Durable source snapshot refs are sanitized and reject signed URLs, +- [ ] Durable source snapshot item refs are sanitized and reject signed URLs, credential-bearing refs, token-bearing refs, and local filesystem paths. - [ ] Approved retrieval adapters can use ordinary URL query parameters only as temporary fetch locators and never persist them as durable source @@ -110,13 +113,14 @@ human review implementation weaken Workstream default policy. - [ ] Policy rows are scoped by `project_id` and `guide_version`. - [ ] Policy rows have a composite foreign key to `project_guides(project_id, version)`. -- [ ] Policy rows bind to `source_snapshot_id` and `source_snapshot_hash`. +- [ ] Policy rows bind to `source_snapshot_id` and server-derived + `source_snapshot_hash` from `GuideSourceSnapshot.bundle_hash`. - [ ] Pydantic input/output schemas exist for project submission artifact policy. - [ ] Project service can create/update the policy with a draft guide. - [ ] Project policy records include approval provenance showing the approved machine policy was reviewed by `admin` or `project_manager`. - [ ] Approval provenance includes derivation source, source material refs, - approval status, approver role, approver actor, approval timestamp, and + lifecycle status, approver role, approver actor, approval timestamp, and approved policy version or hash. - [ ] Guide activation fails when no approved project submission artifact policy exists for the guide version. diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md index ef5ce5e..eb9db4e 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md @@ -38,6 +38,10 @@ Internal sub-agent results live in | Human review | API contract for `pre_submission_checker_failed` was ambiguous. | High | Fixed | Locked separate paths: preflight returns `200 PreSubmitCheckResponse`; blocked submission creation returns `422 DomainError(code="pre_submission_checker_failed")` with structured details. | | Human review | Approved policies and compiled bundles needed append-only lifecycle rules. | High | Fixed | Added `draft -> approved -> superseded` lifecycle, immutable approved/superseded rows, supersedes pointers, and `compiled_bundle` as canonical JSON source of truth with derived index projections only. | | Human review | PR body still asked whether `evidence_policy` should remain as a compatibility alias and whether pre-submit policy should derive on read. | Medium | Fixed | Removed stale human-review questions from the PR body. The current plan says no `evidence_policy` compatibility alias and no derive-on-read runtime path. | +| Human review | Chunk 2 still implied a project-level `PreSubmitCheckerPolicy`, while Chunk 3 and the data model correctly make `PreSubmitCheckerPolicy` task-level. | High | Fixed | Introduced `ProjectPreSubmitCheckerSpec` for Chunk 2. The trusted compiler validates and canonicalizes the project checker spec in Chunk 2; Chunk 3 combines task binding and persists final task-level `PreSubmitCheckerPolicy`. | +| Human review | `GuideSourceSnapshot` looked like a single source ref instead of a guide material bundle. | High | Fixed | Updated the data model, ADR, plan, chunk map, chunk contract, and template to model `GuideSourceSnapshot` as a canonical manifest bundle with per-item source records and a bundle hash. | +| Human review | Remaining schema details were ambiguous: size fields, hash algorithm, dual status fields, and source snapshot hash consistency. | High | Fixed | Added `maximum_file_size_bytes` and `maximum_package_size_bytes`, locked `artifact_hash_algorithm` to platform `sha256`, normalized policy lifecycle to `lifecycle_status`, and documented `source_snapshot_hash` as server-derived from the snapshot bundle hash. | +| Human review | New guide snapshots needed an explicit fairness boundary for already locked tasks. | High | Fixed | Added the protective rule: a new guide-source snapshot invalidates setup records for new activation and unlocked tasks only; already locked tasks retain their context unless explicitly rebased through audit. | ## Commands To Re-Run After Push diff --git a/docs/architecture_checker_framework.md b/docs/architecture_checker_framework.md index ac24ad7..b87364b 100644 --- a/docs/architecture_checker_framework.md +++ b/docs/architecture_checker_framework.md @@ -167,9 +167,9 @@ ProjectGuide -> GuideSufficiencyReport -> ProjectSubmissionArtifactPolicy -> EffectiveProjectSubmissionArtifactPolicy +-> ProjectPreSubmitCheckerSpec -> ApprovedTaskArtifactBinding -> EffectiveTaskSubmissionArtifactPolicy --> constrained PreSubmitCheckerSpec -> trusted Workstream checker compiler -> PreSubmitCheckerPolicy -> pre-submit intake checks @@ -212,10 +212,13 @@ 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`. -The `SubmissionArtifactPolicyDerivationAgent` produces a constrained checker -specification. It does not produce unrestricted checker code. Workstream's -trusted checker compiler turns that specification into deterministic checker -logic using approved primitives such as: +The `SubmissionArtifactPolicyDerivationAgent` produces +`ProjectPreSubmitCheckerSpec`, a constrained project-level checker +specification. It does not produce unrestricted checker code and does not create +a project-level `PreSubmitCheckerPolicy` row. Workstream's trusted checker +compiler validates and canonicalizes the project spec during setup, then later +combines it with task binding and effective task policy to produce deterministic +task-level checker logic using approved primitives such as: - `require_file` - `allow_extension` diff --git a/docs/architecture_data_model.md b/docs/architecture_data_model.md index 1fd52ef..ec786d5 100644 --- a/docs/architecture_data_model.md +++ b/docs/architecture_data_model.md @@ -14,12 +14,11 @@ Actor Project ProjectGuide GuideSourceSnapshot + GuideSourceSnapshotItem GuideSufficiencyReport SubmissionArtifactPolicy EffectiveProjectSubmissionArtifactPolicy - ApprovedTaskArtifactBinding - EffectiveTaskSubmissionArtifactPolicy - PreSubmitCheckerPolicy + ProjectPreSubmitCheckerSpec PostSubmitCheckerPolicy ReviewPolicy RevisionPolicy @@ -27,6 +26,9 @@ Project ProjectLesson Task + ApprovedTaskArtifactBinding + EffectiveTaskSubmissionArtifactPolicy + PreSubmitCheckerPolicy Assignment Submission EvidenceItem @@ -189,19 +191,42 @@ Fields: - `project_id` - `guide_id` - `guide_version` -- `source_ref` +- `manifest_json` +- `bundle_hash` +- `captured_at` +- `created_by` + +`GuideSourceSnapshot` is the immutable bundle binding for guide material. It +captures the exact guide/source material Workstream evaluated as a canonical +manifest. A guide can point at markdown, imported documents, URL-backed docs, +repository docs, examples, or rubric material, but downstream records do not +trust a mutable URL or mutable draft guide body. They bind to +`source_snapshot_id` and a server-derived `source_snapshot_hash` copied from +`GuideSourceSnapshot.bundle_hash`. + +`bundle_hash` is the canonical hash of the manifest plus every included source +item hash. Changing any included document, example, rubric, repository doc, or +inline guide body creates a new snapshot and bundle hash. + +## GuideSourceSnapshotItem + +Fields: + +- `id` +- `source_snapshot_id` +- `source_kind` +- `durable_ref` - `ingestion_adapter` - `content_hash` - `content_cid` (future Flow Node binding) +- `media_type` - `captured_at` -- `created_by` -`GuideSourceSnapshot` is the immutable source binding for guide material. It -captures the exact guide/source bytes Workstream evaluated. A guide can point at -markdown, imported documents, URL-backed docs, repository docs, examples, or -rubric material, but downstream records do not trust a mutable URL or mutable -draft guide body. They bind to `source_snapshot_id` and -`source_snapshot_hash`. +`GuideSourceSnapshotItem` records each material item included in the guide +bundle. `source_kind` distinguishes inline markdown, URL-backed documentation, +repository docs, examples, rubrics, imported files, and other approved source +types. `durable_ref` is opaque and sanitized; it is not the temporary fetch +locator. URL-backed guide ingestion is split into two identities: @@ -217,6 +242,9 @@ durable source identity. Any guide or source-material change creates a new source snapshot. That invalidates prior sufficiency reports, derived policies, effective policies, checker bundles, acknowledgements, and approvals for activation. +A new guide-source snapshot invalidates prior setup records for new activation +and unlocked tasks only. Tasks already locked to an earlier snapshot retain +that policy context unless an explicit audited rebase occurs. ## GuideSufficiencyReport @@ -254,6 +282,9 @@ version. Blocking gaps stop guide activation and create clarification requests for the project owner. Warnings can be acknowledged only by a Workstream actor with the `admin` or `project_manager` role before activation. +`source_snapshot_hash` is server-derived from the referenced +`GuideSourceSnapshot.bundle_hash`. Clients cannot supply a conflicting hash. + ## SubmissionArtifactPolicy Fields: @@ -264,12 +295,14 @@ Fields: - `source_snapshot_id` - `source_snapshot_hash` - `version` -- `status` +- `lifecycle_status` - `required_artifacts` - `required_evidence` - `artifact_manifest_required` - `artifact_hash_required` - `artifact_hash_algorithm` +- `maximum_file_size_bytes` +- `maximum_package_size_bytes` - `allowed_storage_schemes` - `forbidden_artifacts` - `required_attestation_terms` @@ -279,7 +312,6 @@ Fields: - `derivation_agent_name` - `derivation_agent_version` - `source_material_refs` -- `approval_status` - `approved_policy_hash` - `approved_by_role` - `approved_by` @@ -305,13 +337,15 @@ Example: "artifact_manifest_required": true, "artifact_hash_required": true, "artifact_hash_algorithm": "sha256", + "maximum_file_size_bytes": 52428800, + "maximum_package_size_bytes": 104857600, "allowed_storage_schemes": ["local", "s3", "r2"], "forbidden_artifacts": ["secrets/**", ".env"], "sufficiency_report_id": "guide-sufficiency:v1", "derivation_agent_name": "SubmissionArtifactPolicyDerivationAgent", "derivation_agent_version": "v1", "source_material_refs": ["project-guide:v1"], - "approval_status": "approved", + "lifecycle_status": "approved", "approved_policy_hash": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "approved_by_role": "project_manager", "approved_by": "flow-project-manager", @@ -328,6 +362,10 @@ sufficiency passes or warnings are acknowledged. A Workstream actor with the supply or approve this internal policy schema. Project policy can add stricter requirements, but it cannot weaken Workstream's default submission artifact policy. +`artifact_hash_algorithm` is platform-locked to `sha256` for v0.1. Project and +task policies cannot change it. +`source_snapshot_hash` is server-derived from the referenced snapshot bundle +hash. Policy rows are append-only after approval: @@ -357,7 +395,7 @@ Fields: - `source_snapshot_id` - `source_snapshot_hash` - `version` -- `status` +- `lifecycle_status` - `policy_hash` - `source_project_policy_hash` - `required_artifacts` @@ -365,6 +403,8 @@ Fields: - `artifact_manifest_required` - `artifact_hash_required` - `artifact_hash_algorithm` +- `maximum_file_size_bytes` +- `maximum_package_size_bytes` - `allowed_storage_schemes` - `forbidden_artifacts` - `required_attestation_terms` @@ -385,9 +425,9 @@ The merge contract is executable per field: | `artifact_manifest_required` | logical OR | | `artifact_hash_required` | logical OR | | `allowed_storage_schemes` | intersection | -| `artifact_hash_algorithm` | platform-locked value or intersection of allowed algorithms | -| `maximum_file_size` | minimum non-null limit | -| `maximum_package_size` | minimum non-null limit | +| `artifact_hash_algorithm` | platform-locked `sha256`; project/task policy cannot change it | +| `maximum_file_size_bytes` | minimum non-null limit | +| `maximum_package_size_bytes` | minimum non-null limit | | `packaging_rules` | restrictive merge; conflicts block activation | A required artifact or evidence rule matching a forbidden artifact rule blocks @@ -396,6 +436,36 @@ project setup as a policy conflict. It is not deferred to worker submission. Approved and superseded effective policies are immutable. Recomputing the effective policy after guide/source/policy changes creates a new row and hash. +## ProjectPreSubmitCheckerSpec + +Fields: + +- `id` +- `project_id` +- `guide_version` +- `source_snapshot_id` +- `source_snapshot_hash` +- `effective_project_policy_hash` +- `version` +- `lifecycle_status` +- `canonical_spec` +- `canonical_spec_hash` +- `compiler_version` +- `generated_from_policy_version` +- `generated_at` +- `approved_by_role` +- `approved_by` +- `approved_at` +- `supersedes_spec_id` + +`ProjectPreSubmitCheckerSpec` is the project-level constrained checker +specification produced from the approved project submission artifact policy. It +uses only Workstream-approved primitives. The trusted compiler validates and +canonicalizes this specification during project setup, but it does not persist a +project-level `PreSubmitCheckerPolicy` row. The final executable +`PreSubmitCheckerPolicy` is task-level and is created only after task artifact +binding produces `EffectiveTaskSubmissionArtifactPolicy`. + ## ApprovedTaskArtifactBinding Fields: @@ -412,7 +482,7 @@ Fields: - `required_evidence` - `additional_packaging_rules` - `additional_forbidden_artifacts` -- `approval_status` +- `lifecycle_status` - `approved_by_role` - `approved_by` - `approved_at` @@ -453,7 +523,7 @@ Fields: - `source_snapshot_id` - `source_snapshot_hash` - `version` -- `status` +- `lifecycle_status` - `policy_hash` - `effective_project_policy_hash` - `approved_task_artifact_binding_id` @@ -462,6 +532,8 @@ Fields: - `artifact_manifest_required` - `artifact_hash_required` - `artifact_hash_algorithm` +- `maximum_file_size_bytes` +- `maximum_package_size_bytes` - `allowed_storage_schemes` - `forbidden_artifacts` - `required_attestation_terms` @@ -475,9 +547,9 @@ prose and not transitional task fields. ## PreSubmitCheckerPolicy -Generated server-side from `EffectiveTaskSubmissionArtifactPolicy`, then -persisted and locked to the task policy hash before the task enters the worker -pipeline. +Generated server-side from `EffectiveTaskSubmissionArtifactPolicy` and the +approved `ProjectPreSubmitCheckerSpec`, then persisted and locked to the task +policy hash before the task enters the worker pipeline. Fields: @@ -488,9 +560,11 @@ Fields: - `source_snapshot_id` - `source_snapshot_hash` - `version` -- `status` +- `lifecycle_status` - `policy_hash` - `effective_task_submission_artifact_policy_hash` +- `project_pre_submit_checker_spec_id` +- `project_pre_submit_checker_spec_hash` - `checker_spec` - `compiler_version` - `compiled_bundle_hash` @@ -502,12 +576,14 @@ Fields: - `generated_at` - `supersedes_policy_id` -`checker_spec` is a constrained machine-readable specification using -Workstream-approved primitives. `compiled_bundle` is the immutable JSON checker -bundle produced by the trusted Workstream checker compiler and is the canonical -source of truth. It is stored as a structured snapshot, not arbitrary executable -code. `compiled_bundle_hash` binds the exact compiled logic to -`effective_task_submission_artifact_policy_hash`. `checker_names`, +`checker_spec` is the task-applied constrained machine-readable specification +using Workstream-approved primitives. It is derived from the approved +`ProjectPreSubmitCheckerSpec` and task policy binding. `compiled_bundle` is the +immutable JSON checker bundle produced by the trusted Workstream checker +compiler and is the canonical source of truth. It is stored as a structured +snapshot, not arbitrary executable code. `compiled_bundle_hash` binds the exact +compiled logic to `effective_task_submission_artifact_policy_hash` and +`project_pre_submit_checker_spec_hash`. `checker_names`, `checker_configs`, and `blocking_severities` are derived index projections only; they must be regenerated from `compiled_bundle` and must not disagree with it. diff --git a/docs/architecture_lockdown.md b/docs/architecture_lockdown.md index 014dc4f..b3a2594 100644 --- a/docs/architecture_lockdown.md +++ b/docs/architecture_lockdown.md @@ -85,7 +85,7 @@ with the `admin` or `project_manager` role approves the internal policy bundle before guide activation. Project owners do not approve Workstream's internal submission policy schema. -`SubmissionArtifactPolicy` defines project-level intake rules. Workstream combines it with the non-bypassable Workstream default submission artifact policy to create the effective project policy, then combines that with an approved task artifact binding to create the effective task submission artifact policy. Workstream persists the effective task policy hash, then generates, persists, hashes, and locks `PreSubmitCheckerPolicy` from that task policy. +`SubmissionArtifactPolicy` defines project-level intake rules. Workstream combines it with the non-bypassable Workstream default submission artifact policy to create `EffectiveProjectSubmissionArtifactPolicy`, derives and canonicalizes `ProjectPreSubmitCheckerSpec`, then combines `EffectiveProjectSubmissionArtifactPolicy` with `ApprovedTaskArtifactBinding` to create `EffectiveTaskSubmissionArtifactPolicy`. Workstream persists the effective task policy hash, then generates, persists, hashes, and locks the task-level `PreSubmitCheckerPolicy` from that task policy and approved project checker spec. Blocking pre-submit failures prevent submission creation. Preflight failures return `PreSubmitCheckResponse(status="failed", eligible_to_submit=false, @@ -161,6 +161,7 @@ Use these names consistently: - `ContributionRecord` - `SubmissionArtifactPolicy` - `EffectiveProjectSubmissionArtifactPolicy` +- `ProjectPreSubmitCheckerSpec` - `ApprovedTaskArtifactBinding` - `EffectiveTaskSubmissionArtifactPolicy` - `PreSubmitCheckerPolicy` diff --git a/docs/current_system_data_flow.html b/docs/current_system_data_flow.html index 86e16f8..4e2a8f8 100644 --- a/docs/current_system_data_flow.html +++ b/docs/current_system_data_flow.html @@ -591,11 +591,11 @@

Durable Records Created Along The Way

Project + Guide - Project, ProjectGuide, SubmissionArtifactPolicy, generated pre-submit checker policy, post-submit checker policy, review policy, revision policy, payment policy. + Project, ProjectGuide, GuideSourceSnapshot bundle, SubmissionArtifactPolicy, effective project policy, ProjectPreSubmitCheckerSpec, post-submit checker policy, review policy, revision policy, payment policy.
Task Queue - WorkstreamTask, locked policy versions, TaskAssignment, status transitions. + WorkstreamTask, approved task artifact binding, effective task policy, task-level PreSubmitCheckerPolicy, TaskAssignment, status transitions.
Submission Packet 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 3e715f2..ceab288 100644 --- a/docs/decision_0011_submission_artifact_policy_drives_pre_submit.md +++ b/docs/decision_0011_submission_artifact_policy_drives_pre_submit.md @@ -19,7 +19,7 @@ Workstream also needs platform-owned default submission safety rules that no pro Every active project guide version must have a complete guide-policy bundle: -- immutable `GuideSourceSnapshot` for the exact guide/source bytes evaluated +- immutable `GuideSourceSnapshot` bundle for the exact guide/source material evaluated - passing or acknowledged `GuideSufficiencyReport` - approved `ProjectSubmissionArtifactPolicy` - persisted `EffectiveProjectSubmissionArtifactPolicy` hash @@ -35,10 +35,17 @@ must not force every project owner through one universal intake checklist. Workstream binds all downstream setup records to the exact guide source snapshot, not only to `guide_version`. `GuideSourceSnapshot` records include the -guide id, source ref, ingestion adapter, content hash, optional future content -id, and capture timestamp. A guide or source-material change creates a new -snapshot and invalidates prior sufficiency reports, derived policies, effective -policies, checker bundles, acknowledgements, and approvals for activation. +guide id, canonical manifest JSON, bundle hash, and capture timestamp. Snapshot +items record source kind, sanitized durable ref, ingestion adapter, content +hash, optional future content id, media type, and capture timestamp. The bundle +hash is the canonical hash of the manifest and every included source item. +Changing any included document, example, rubric, repository doc, or inline guide +body creates a new snapshot and invalidates prior sufficiency reports, derived +policies, effective policies, checker specs, checker bundles, +acknowledgements, and approvals for activation. +A new guide-source snapshot invalidates prior setup records for new activation +and unlocked tasks only. Tasks already locked to an earlier snapshot retain +that policy context unless an explicit audited rebase occurs. URL-backed guide ingestion separates the temporary fetch locator from durable source identity. Approved retrieval adapters can fetch legitimate documentation @@ -70,6 +77,7 @@ primitives. - required evidence references - artifact manifest rules - artifact hash rules +- maximum file and package size rules - allowed storage reference forms - forbidden artifacts - worker attestation requirements @@ -81,7 +89,7 @@ Project policy can add stricter requirements, but it cannot remove, weaken, down Approval provenance is part of the policy contract. A policy record must make approval testable with source/provenance state such as derivation source, -approval status, approver actor, approval timestamp, and approved policy +`lifecycle_status`, approver actor, approval timestamp, and approved policy version/hash. The runtime contract is: @@ -96,9 +104,13 @@ EffectiveTaskSubmissionArtifactPolicy = + ApprovedTaskArtifactBinding ``` -Workstream's trusted checker compiler generates and persists -`PreSubmitCheckerPolicy` from the effective task submission artifact policy and -the approved checker specification. +`SubmissionArtifactPolicyDerivationAgent` produces +`ProjectPreSubmitCheckerSpec` at project setup time. Workstream's trusted +checker compiler validates and canonicalizes that project checker specification +but does not persist a project-level `PreSubmitCheckerPolicy` row. After task +binding, the compiler combines the approved task binding, effective task policy, +and approved project checker specification, then persists the final task-level +`PreSubmitCheckerPolicy`. Project policies define project-wide artifact intake rules for a guide snapshot. Tasks can still have different required outputs. `ApprovedTaskArtifactBinding` @@ -239,9 +251,9 @@ The effective policy merge is deterministic: | `artifact_manifest_required` | logical OR | | `artifact_hash_required` | logical OR | | `allowed_storage_schemes` | intersection | -| `artifact_hash_algorithm` | platform-locked value or intersection of allowed algorithms | -| `maximum_file_size` | minimum non-null limit | -| `maximum_package_size` | minimum non-null limit | +| `artifact_hash_algorithm` | platform-locked `sha256`; project/task policy cannot change it | +| `maximum_file_size_bytes` | minimum non-null limit | +| `maximum_package_size_bytes` | minimum non-null limit | | `packaging_rules` | restrictive merge; conflicts block activation | Conflicts block setup before workers see tasks. A project-required artifact that diff --git a/docs/glossary.md b/docs/glossary.md index 3b73165..5cd5deb 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -52,13 +52,25 @@ default submission artifact rules. The project-specific `SubmissionArtifactPolicy` attached to one project guide version before Workstream merges it with default submission artifact policy. -## Effective Submission Artifact Policy +## Effective Project Submission Artifact Policy The deterministic merge of Workstream's default submission artifact policy and the project-approved submission artifact policy. Workstream computes this effective project policy before task-specific binding. +## Project Pre-Submit Checker Spec + +The constrained project-level checker specification derived from the approved +project submission artifact policy. Workstream validates and canonicalizes this +spec during project setup. It is not a `PreSubmitCheckerPolicy` row. + +## Effective Task Submission Artifact Policy + +The deterministic merge of the effective project submission artifact policy and +an approved task artifact binding. Workstream locks this task policy before +generating the task-level pre-submit checker policy. + ## Pre-Submit Checker Policy -The server-generated checker matrix produced from the effective task submission artifact policy, persisted with a hash, and locked before a task enters the worker pipeline. It runs before Workstream creates a submission row or submission version. The preflight endpoint returns `PreSubmitCheckResponse`; a blocked submission-create attempt returns `pre_submission_checker_failed` with structured pass/fail/warning details. Neither path returns review decision values: `accept`, `needs_revision`, or `reject`. +The server-generated task-level checker matrix produced from the effective task submission artifact policy and approved project checker spec, persisted with a hash, and locked before a task enters the worker pipeline. It runs before Workstream creates a submission row or submission version. The preflight endpoint returns `PreSubmitCheckResponse`; a blocked submission-create attempt returns `pre_submission_checker_failed` with structured pass/fail/warning details. Neither path returns review decision values: `accept`, `needs_revision`, or `reject`. ## pre_submission_checker_failed diff --git a/docs/template_submission_artifact_policy.md b/docs/template_submission_artifact_policy.md index 4ddcebb..150d806 100644 --- a/docs/template_submission_artifact_policy.md +++ b/docs/template_submission_artifact_policy.md @@ -22,12 +22,16 @@ machine-readable Workstream policy schema directly. Source snapshot: - guide source snapshot id: -- guide source snapshot hash: -- ingestion adapter: -- durable source ref: -- content cid: `` +- guide source snapshot bundle hash: +- manifest json: - captured at: +Source snapshot items: + +| Source Kind | Durable Ref | Ingestion Adapter | Content Hash | Content CID | Media Type | +| --- | --- | --- | --- | --- | --- | +| `` | `` | `` | `sha256:` | `` | `` | + Temporary fetch locators are adapter inputs only. Durable source refs must not store query strings, signed URLs, credentials, token-bearing refs, local filesystem paths, or private storage paths. @@ -48,8 +52,8 @@ filesystem paths, or private storage paths. - derivation agent version: - sufficiency report id: - source snapshot id: -- source snapshot hash: -- approval status: `draft | approved | superseded` +- source snapshot bundle hash: +- lifecycle status: `draft | approved | superseded` - approved policy hash: - approved by role: `admin | project_manager` - approved by actor: @@ -108,8 +112,9 @@ A project-required artifact that matches a Workstream default forbidden rule rem | manifest required | logical OR | | hash required | logical OR | | allowed storage schemes | intersection | -| hash algorithm | platform-locked value or intersection | -| maximum file/package size | minimum non-null limit | +| hash algorithm | platform-locked `sha256`; project/task policy cannot change it | +| maximum file size bytes | minimum non-null limit | +| maximum package size bytes | minimum non-null limit | | packaging rules | restrictive merge; conflicts block setup | ## Project Required Artifacts @@ -130,8 +135,8 @@ A project-required artifact that matches a Workstream default forbidden rule rem - accepted package format: - required root files: - required directory structure: -- maximum artifact size: -- maximum package size: +- maximum file size bytes: +- maximum package size bytes: ## Project Forbidden Artifacts @@ -148,14 +153,20 @@ Required attestation topics: - credentials and secret exclusion - human accountability for agent-assisted work +## Project Pre-Submit Checker Specification + +Workstream derives and canonicalizes a project-level +`ProjectPreSubmitCheckerSpec` from the approved project policy. This is a +constrained specification using approved primitives, not executable checker +code and not a project-level `PreSubmitCheckerPolicy` row. + ## Generated Pre-Submit Checker Policy Workstream generates task-level `PreSubmitCheckerPolicy` from: ```text -WorkstreamDefaultSubmissionArtifactPolicy -+ ProjectSubmissionArtifactPolicy -+ ApprovedTaskArtifactBinding +EffectiveTaskSubmissionArtifactPolicy ++ ProjectPreSubmitCheckerSpec ``` Generated pre-submit checks run before submission creation. Blocking failures create no submission row, no submission version, no task transition to `submitted`, and no submission-created audit event. From 8a0fd181046e2eab9b668c614c845e62dd81db55 Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Wed, 24 Jun 2026 20:31:04 +0100 Subject: [PATCH 25/37] Correct pre-submit checker ownership model --- .../CHUNK_MAP.md | 62 +++---- .../DECISIONS.md | 11 +- .../DISCOVERY.md | 5 +- .../INTENT.md | 43 ++--- .../PLAN.md | 55 +++--- ...1-submission-artifact-policy-foundation.md | 4 +- .../WS-POL-001-01-external-review-response.md | 6 +- docs/architecture_checker_framework.md | 27 ++- docs/architecture_data_model.md | 170 +++--------------- docs/architecture_lifecycle_state_machine.md | 7 +- docs/architecture_lockdown.md | 7 +- docs/current_system_data_flow.html | 8 +- ...ion_0003_project_guides_are_first_class.md | 4 +- ...ssion_artifact_policy_drives_pre_submit.md | 46 ++--- docs/glossary.md | 18 +- docs/operations_project_operating_manual.md | 10 +- .../operations_workspace_packet_convention.md | 6 +- docs/product_first_user_flows.md | 8 +- docs/roadmap_day_by_day_execution_plan.md | 4 +- docs/roadmap_implementation_backlog.md | 2 +- docs/spec_chunk_3_project_guide_foundation.md | 2 +- ...ec_chunk_5_submission_packet_foundation.md | 4 +- docs/spec_chunk_6_checker_contract_records.md | 2 +- docs/spec_chunk_7_checker_runner_registry.md | 7 +- ...k_8_submission_artifact_policy_checkers.md | 9 +- docs/spec_week2_checker_framework.md | 4 +- docs/template_checker_policy.md | 7 +- docs/template_preflight_evidence.md | 2 +- docs/template_project_guide.md | 6 +- docs/template_submission_artifact_policy.md | 18 +- 30 files changed, 207 insertions(+), 357 deletions(-) diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md index d35f980..974c840 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md @@ -17,8 +17,8 @@ - Agents derive constrained policy and checker specifications. Workstream compiles deterministic checker bundles. Unrestricted generated checker code is not the default path. -- Reports, derived policies, acknowledgements, effective policies, task - bindings, and checker bundles bind to immutable `GuideSourceSnapshot` +- Reports, derived policies, acknowledgements, effective policies, task locked + references, and checker bundles bind to immutable `GuideSourceSnapshot` bundle id/hash, not only to `guide_version`. ## Chunks @@ -124,8 +124,8 @@ Chunk 1 limited to records/contracts/activation guards. Goal: Run `ProjectGuideSufficiencyAgent`, -`SubmissionArtifactPolicyDerivationAgent`, and project checker-spec -canonicalization asynchronously against immutable guide-source snapshots. +`SubmissionArtifactPolicyDerivationAgent`, and project pre-submit +checker compilation asynchronously against immutable guide-source snapshots. Risk: @@ -163,12 +163,12 @@ Acceptance criteria: - `SubmissionArtifactPolicyDerivationAgent` runs async after sufficiency passes or warnings are acknowledged. - Derived policy cannot weaken Workstream defaults. -- `SubmissionArtifactPolicyDerivationAgent` produces - `ProjectPreSubmitCheckerSpec` using only approved Workstream primitives. -- Trusted checker compiler validates and canonicalizes the project checker - specification, producing a stable project checker spec hash. Chunk 2 does not - persist a project-level `PreSubmitCheckerPolicy` row. -- Derived report, project policy, effective project policy, and project checker spec +- `SubmissionArtifactPolicyDerivationAgent` produces a constrained checker + specification using only approved Workstream primitives. +- Trusted checker compiler validates the specification and persists a + deterministic project `PreSubmitCheckerPolicy` bundle and hash. The default + path compiles once per project guide version, not once per task. +- Derived report, project policy, effective project policy, and pre-submit checker bundle are invalidated by a new guide source snapshot. - Malicious guide text, embedded prompt-injection instructions, and unsafe source refs cannot influence agent authority, fetch behavior, or default @@ -184,10 +184,10 @@ Verification: - Background execution tests prove jobs are async and idempotent for a guide source snapshot. - Compiler tests prove allowed primitive emission, unknown primitive rejection, - byte-stable same-input same-compiler-version project spec hashing, hash - binding to `effective_project_submission_artifact_policy_hash`, and - client/worker inability to supply checker names, severities, versions, - outcomes, compiler version, or project checker specs. + byte-stable same-input same-compiler-version bundle hashing, hash binding to + `effective_project_submission_artifact_policy_hash`, and client/worker + inability to supply checker names, severities, versions, outcomes, compiler + version, or compiled bundles. Required reviewers: @@ -199,13 +199,13 @@ Human review focus: Async job boundaries, sufficiency severity behavior, and clarification request shape. -### WS-POL-001-03: Task Policy Binding And Submission Creation +### WS-POL-001-03: Task Locked Context And Submission Creation Goal: -Add approved task artifact bindings, compute effective task submission artifact -policy, generate the task-level pre-submit checker bundle, and move submission -creation from transitional task fields to that locked task policy. +Lock each task to the applicable guide snapshot, effective project policy hash, +and project pre-submit checker bundle. Move submission creation from +transitional task fields to that locked context. Risk: @@ -237,17 +237,13 @@ frontend Acceptance criteria: -- `ApprovedTaskArtifactBinding` exists and selects an approved artifact profile - plus constrained task parameters. -- Task bindings can add or tighten requirements, but cannot weaken platform - defaults or the effective project policy. -- `EffectiveTaskSubmissionArtifactPolicy` is generated from effective project - policy plus task binding and locked before `SCREENING` or `READY`. -- Chunk 3 combines the approved task binding, effective task policy, and - approved `ProjectPreSubmitCheckerSpec`. -- Task-level generated `PreSubmitCheckerPolicy` is persisted with - `compiled_bundle` as canonical JSON source of truth and `compiled_bundle_hash` - as its canonical hash. +- Tasks lock `guide_source_snapshot_id`, `guide_source_snapshot_hash`, + `effective_project_submission_artifact_policy_hash`, + and `pre_submit_checker_policy_hash` before `SCREENING` or `READY`. +- Most tasks in a project share the same `PreSubmitCheckerPolicy`; tasks do not + run policy derivation or checker compilation by default. +- Task-specific values are constrained parameters consumed by the locked + checker bundle, not a newly generated checker policy. - Transitional `required_files` and `required_evidence` are replaced for submission runtime and are not compatibility aliases. - Blocking pre-submit failure creates no submission row, submission version, @@ -264,8 +260,8 @@ Verification: - Postgres-backed FastAPI/API tests cover clean submission, blocking pre-submit failure, no-row/no-version/no-transition/no-durable-checker side effects, and stamped locked policy context. -- Postgres-backed task tests cover task binding merge, weakening rejection, - task policy hash locking, and removal of transitional task-field authority. +- Postgres-backed task tests cover locked context stamping, shared checker reuse + across multiple tasks, and removal of transitional task-field authority. Required reviewers: @@ -274,8 +270,8 @@ reuse/dedup, test delta. Human review focus: -Task-specific artifact binding, no-row/no-version/no-transition guarantee, and -preflight-versus-submission-create failure shape. +Task locked context, shared checker reuse, no-row/no-version/no-transition +guarantee, and preflight-versus-submission-create failure shape. ### WS-POL-001-04: PostSubmitCheckerPolicy Split diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md index 85c216e..76de6b3 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md @@ -19,19 +19,16 @@ `ProjectSubmissionArtifactPolicy` after guide sufficiency passes. - `SubmissionArtifactPolicyDerivationAgent` produces constrained policy and checker specifications, not unrestricted executable checker code. -- `SubmissionArtifactPolicyDerivationAgent` produces - `ProjectPreSubmitCheckerSpec` during project setup. - Workstream derives `ProjectSubmissionArtifactPolicy` from project material, with internal agent assistance allowed, then requires approval by `admin` or `project_manager` before guide activation. - Workstream default submission artifact rules are non-bypassable. - `EffectiveProjectSubmissionArtifactPolicy` is default plus project policy. -- `EffectiveTaskSubmissionArtifactPolicy` is effective project policy plus an - approved task artifact binding. - Workstream's trusted checker compiler turns the constrained checker - specification into deterministic task-level `PreSubmitCheckerPolicy` only - after task binding produces the effective task policy hash. There is no - project-level `PreSubmitCheckerPolicy` row. + specification into deterministic project-scoped `PreSubmitCheckerPolicy`. +- Tasks lock the applicable guide snapshot, effective project policy hash, + and pre-submit checker policy hash. Tasks do not rerun derivation or compile + unique checker bundles by default. - Pre-submit checks block before submission creation. - Preflight feedback is `PreSubmitCheckResponse`; blocked submission-create attempts return `pre_submission_checker_failed` with structured diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DISCOVERY.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DISCOVERY.md index 6bbc11e..d81e540 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DISCOVERY.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DISCOVERY.md @@ -11,9 +11,8 @@ The architecture docs already lock the target model: SubmissionArtifactPolicy -> GuideSufficiencyReport -> EffectiveProjectSubmissionArtifactPolicy --> ApprovedTaskArtifactBinding --> EffectiveTaskSubmissionArtifactPolicy --> persisted and locked PreSubmitCheckerPolicy +-> persisted project PreSubmitCheckerPolicy +-> tasks lock project policy/checker references -> pre-submit checks before submission creation -> post-submit/internal checks after submission lock ``` diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md index 2dfaf76..1e73165 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md @@ -27,7 +27,6 @@ Project owner material -> ProjectGuideSufficiencyAgent -> SubmissionArtifactPolicyDerivationAgent -> Workstream-derived ProjectSubmissionArtifactPolicy --> ProjectPreSubmitCheckerSpec -> approval by admin or project_manager WorkstreamDefaultSubmissionArtifactPolicy @@ -35,13 +34,13 @@ WorkstreamDefaultSubmissionArtifactPolicy = EffectiveProjectSubmissionArtifactPolicy EffectiveProjectSubmissionArtifactPolicy -+ ApprovedTaskArtifactBinding -= EffectiveTaskSubmissionArtifactPolicy - -EffectiveTaskSubmissionArtifactPolicy --> approved ProjectPreSubmitCheckerSpec -> trusted Workstream checker compiler --> persisted and locked PreSubmitCheckerPolicy +-> persisted project PreSubmitCheckerPolicy + +Task +-> locks guide snapshot +-> locks effective project policy hash +-> locks PreSubmitCheckerPolicy hash ``` Project owners provide open-ended project material: markdown, URLs, full @@ -65,19 +64,27 @@ remain visible to the Workstream `admin` or `project_manager` and must be acknowledged before activation. After sufficiency passes, the `SubmissionArtifactPolicyDerivationAgent` derives -the machine-readable project submission artifact policy and -`ProjectPreSubmitCheckerSpec`. The project owner does not approve this internal -policy. A Workstream actor with the `admin` or `project_manager` role approves -the derived policy and activates the guide-policy bundle. Workers submit draft +the machine-readable project submission artifact policy and constrained checker +specification. The project owner does not approve this internal policy. A +Workstream actor with the `admin` or `project_manager` role approves the +derived policy and activates the guide-policy bundle. Workers submit draft packet fields. Workstream decides required artifacts, evidence, hashes, storage reference rules, forbidden artifacts, and blocking pre-submit feedback from the -locked effective policy. +locked effective policy and compiled project checker bundle. The derivation agent produces a constrained artifact-intake contract and checker specification. Workstream compiles that specification into deterministic checker logic. Runtime submission evaluation is performed by the locked checker bundle, not by an agent. +Most tasks in a project reuse the same compiled checker bundle. A task locks the +policy/checker context that governs it; it does not get a freshly derived policy +or freshly compiled checker. If the sufficiency agent finds that the guide does +not cover the project's task set, activation is blocked and the guide is +improved or the work is split into another project/guide. Small task-specific +values are constrained parameters fed into the same locked checker bundle, not +new checker generation. + ## Why Now Week 1 and Week 2 established the core backend loop: @@ -108,14 +115,10 @@ After this initiative: - Workstream default submission artifact rules are defined in code. - Project submission artifact policy cannot weaken Workstream defaults. - Effective project submission artifact policy is computed deterministically. -- Approved task artifact bindings produce task-specific effective submission - artifact policy hashes. -- Generated pre-submit checker policy is persisted and locked to the effective - task policy hash. -- `ProjectPreSubmitCheckerSpec` is produced during project setup, then - Workstream's trusted compiler produces the final task-level generated - pre-submit checker policy from approved checker primitives, not by - unrestricted generated code. +- Generated pre-submit checker policy is persisted at project scope and tasks + lock its hash before entering the worker pipeline. +- Workstream's trusted compiler produces the project pre-submit checker + policy from approved checker primitives, not by unrestricted generated code. - Submission creation uses the generated pre-submit policy before a submission row is created. - Post-submit/internal checker policy remains separate. diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md index 170d85a..f8962a9 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md @@ -33,14 +33,8 @@ ProjectSubmissionArtifactPolicy EffectiveProjectSubmissionArtifactPolicy deterministic merge of default + project policy -ApprovedTaskArtifactBinding - Workstream-approved task-specific artifact profile and constrained parameters - -EffectiveTaskSubmissionArtifactPolicy - deterministic merge of effective project policy + approved task binding - PreSubmitCheckerPolicy - persisted and locked task-level checker rules for draft packet intake + persisted project checker rules for draft packet intake PostSubmitCheckerPolicy durable checker rules for locked submission review readiness @@ -67,32 +61,31 @@ locators as durable source identity. `SubmissionArtifactPolicyDerivationAgent` derives machine-readable `ProjectSubmissionArtifactPolicy` after guide sufficiency passes. A Workstream actor with the `admin` or `project_manager` role approves the derived policy. -Workstream then computes the effective project policy and later combines it -with approved task-specific artifact bindings to produce an -`EffectiveTaskSubmissionArtifactPolicy` locked before a task enters -`SCREENING` or `READY`. The generated task-level `PreSubmitCheckerPolicy` -snapshot/hash is locked to that effective task policy. Pre-submit checks run -before submission creation and do not create durable checker records. +Workstream then computes the effective project policy. The generated +`PreSubmitCheckerPolicy` snapshot/hash is scoped to the project guide version. +Tasks lock references to the exact guide snapshot, effective project policy +hash, and pre-submit checker policy hash before entering `SCREENING` or +`READY`. +Pre-submit checks run before submission creation and do not create durable +checker records. Post-submit/internal checks run after submission lock and do create durable checker records. The derivation agent does not generate unrestricted executable checker code. It produces a constrained checker specification using Workstream-approved primitives. Workstream's trusted checker compiler turns that specification into -a canonical `ProjectPreSubmitCheckerSpec` during project setup. The final -task-level compiler step combines that approved project checker specification -with the approved task binding and effective task policy, then persists the -deterministic `PreSubmitCheckerPolicy` bundle. Runtime checks execute the locked -compiled bundle against staged artifact hashes or future content identifiers. +a deterministic project `PreSubmitCheckerPolicy` bundle during project setup. +Runtime checks execute the locked compiled bundle against staged artifact hashes +or future content identifiers plus the task's constrained parameters. Tasks do +not rerun the derivation agent or compile a new checker bundle for each task. If no immutable guide-source snapshot, passing or acknowledged guide sufficiency report, approved project submission artifact policy, and effective project policy hash exist for the guide snapshot and guide version, guide activation -fails. If no approved task artifact binding, effective task policy hash, and -task-level pre-submit checker bundle exist, the task cannot enter the ready -worker pipeline. The system must surface setup failure internally as -task/project setup incomplete rather than letting workers discover missing -intake rules at submit time. +fails. If the applicable project pre-submit checker bundle is +missing, a task cannot enter the ready worker pipeline. The system must surface +setup failure internally as task/project setup incomplete rather than letting +workers discover missing intake rules at submit time. Reports, derived policies, acknowledgements, effective policies, and checker bundles bind to the exact `GuideSourceSnapshot` id/hash, not only to @@ -174,23 +167,23 @@ while post-submit answers whether a locked submission can move to human review. 4. Compute effective project policy in service code and validate defaults cannot weaken. 5. Add async guide sufficiency, policy derivation execution, and trusted checker compiler behavior. -6. Add approved task artifact bindings and effective task policy locking. +6. Add task locked-context fields for guide snapshot, effective project policy, + and generated pre-submit checker bundle. 7. Migrate submission creation from transitional task fields to the locked task - policy and generated pre-submit checker bundle. + context and generated project pre-submit checker bundle. 8. Split post-submit checker policy naming/provenance. ## Verification Strategy -- Unit-level policy merge tests for default + project policy and effective - project policy + task artifact binding. +- Unit-level policy merge tests for default + project policy. - Postgres-backed API tests for guide sufficiency report, project policy creation, immutable source snapshots, effective project policy persistence, and guide activation. - Tests proving a guide cannot activate without passing or acknowledged guide sufficiency bound to the current source snapshot, approved project submission artifact policy, and effective project policy hash. -- Tests proving a task cannot enter `READY` without an approved task artifact - binding, effective task policy hash, and generated pre-submit checker bundle. +- Tests proving a task cannot enter `READY` without locked guide snapshot, + effective project policy hash, and generated pre-submit checker bundle. - Tests proving malicious or credential-bearing source material cannot weaken Workstream defaults, grant tool authority, or persist unsafe source refs. - Submission API tests proving blocking pre-submit failure creates no submission @@ -218,5 +211,5 @@ CI integrity is required only for chunks that touch workflows or test tooling. Start with guide/source/policy bundle foundation. Do not start submission runtime rewiring until immutable guide-source snapshots, guide sufficiency reports, project policy objects, defaults, effective project policy hash, -approved task artifact bindings, effective task policy hash, generated -pre-submit checker bundle, and activation/ready guards are accepted. +generated pre-submit checker bundle, task locked-context fields, and +activation/ready guards are accepted. diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md index 00e5849..ede8e7b 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md @@ -143,7 +143,7 @@ human review implementation pointer. - [ ] Legacy `evidence_policy`, `required_files`, and `required_evidence` are not treated as compatibility aliases. Runtime replacement of task fields - happens in the task binding and submission migration chunk. + happens in the task locked-context and submission migration chunk. - [ ] Postgres-backed FastAPI/API tests cover create/update, blocking activation from guide sufficiency gaps, `admin`/`project_manager` warning acknowledgement, approval provenance fields, default weakening, @@ -192,7 +192,7 @@ Conditional: - Are the guide source snapshot fields precise enough? - Are the persisted provenance field names precise enough? - Does this chunk stay limited to records/contracts/activation guard, leaving - full async agent execution, trusted compiler behavior, task binding, and + full async agent execution, trusted compiler behavior, task locked context, and submission runtime migration for later chunks? ## Stop Conditions diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md index eb9db4e..bc2b39e 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md @@ -25,20 +25,20 @@ Internal sub-agent results live in | CodeRabbit | `WS-POL-001-03` acceptance criteria repeated no-side-effect wording. | Low | Fixed | Consolidated the no-row, no-version, no-transition, and no-durable-checker-run guarantee without weakening it. | | Human review | Project owners must not author or approve Workstream internal `SubmissionArtifactPolicy`; Workstream derives it from open-ended project material and `admin` or `project_manager` approves the internal bundle. | High | Fixed | Updated planning artifacts, ADRs, glossary, architecture docs, specs, templates, operating manual, data flow, and first user flows. | | Human review | Project-guide material is open-ended, not a fixed checklist; Workstream must run sufficiency and derivation agents internally. | High | Fixed | Added `ProjectGuideSufficiencyAgent`, `GuideSufficiencyReport`, and `SubmissionArtifactPolicyDerivationAgent` to the plan, ADR, data model, lifecycle, templates, and chunk map. | -| Human review | `PreSubmitCheckerPolicy` must be persisted and locked, not derived on read. | High | Fixed | Updated plan, ADRs, data model, lifecycle, checker flow, and chunk contracts to require persisted snapshot/hash. Later review refined the lock target from guide version to effective task policy hash. | +| Human review | `PreSubmitCheckerPolicy` must be persisted and locked, not derived on read. | High | Fixed | Updated plan, ADRs, data model, lifecycle, checker flow, and chunk contracts to require persisted project checker snapshot/hash. Tasks lock the project checker hash; they do not compile their own checker. | | Human review | Pre-submit failures should not use review decisions and should show pass/fail/warning details like the Snorkel-style static checker experience. | High | Fixed | Standardized `pre_submission_checker_failed` with structured pass/fail/warning details and explicit exclusion of `accept`, `needs_revision`, and `reject`. | | Human review | Current planning PR must be mergeable before implementation starts. | High | Fixed | Updated status, chunk map, chunk contract, proof obligations, and review evidence while keeping backend implementation inactive. | | CodeRabbit | ADR 0011 described pre-submit/review-decision separation but did not state how implementation must prove enforcement. | Major | Fixed | Added an implementation enforcement contract to ADR 0011. It explicitly says this PR is planning-only and lists the API, UI/demo, persistence, database, and chunk-level proof required before implementation chunks can close. | | CodeRabbit | `docs/architecture_checker_framework.md` made `pre_submission_checker_failed` read like the response type instead of the failure condition represented by a failed pre-submit response. | Minor | Fixed | Reworded the checker framework to require `PreSubmitCheckResponse(status="failed", eligible_to_submit=false, results=[...])` for blocking failures, with `pre_submission_checker_failed` described as the user-facing failure condition rather than a response field. | | Human review | Downstream reports and policies were bound to `guide_version` but not the exact guide/source snapshot. | High | Fixed | Added `GuideSourceSnapshot`, `source_snapshot_id`, and `source_snapshot_hash` to the plan, ADR, data model, chunk map, chunk contract, and templates. Guide/source changes now invalidate reports, policies, acknowledgements, approvals, effective policies, and checker bundles. | | Human review | Chunk 1 claimed task/checker runtime removals while forbidding task/checker modules. | High | Fixed | Re-scoped Chunk 1 to guide-source snapshots, project policy records, effective project policy merge, append-only lifecycle, and activation guards. Moved compiler behavior to Chunk 2 and task-field/runtime migration to Chunk 3. | -| Human review | Project-level policy alone cannot represent task-specific artifact requirements. | High | Fixed | Added `ApprovedTaskArtifactBinding` and `EffectiveTaskSubmissionArtifactPolicy`, with task-specific binding locked before `SCREENING` or `READY`. | +| Human review | Project-level policy should not become per-task policy generation. | High | Fixed | Corrected the architecture to the realistic model: one project guide/effective policy/project pre-submit checker reused by tasks. `ProjectGuideSufficiencyAgent` must block activation if the guide does not cover the task set. | | Human review | Effective policy merge semantics were not executable enough. | High | Fixed | Added per-field deterministic merge rules for union, intersection, logical OR, minimum limits, platform-locked hash algorithm, restrictive packaging merge, and setup-conflict blocking. | | Human review | URL ingestion and durable source identity were conflated. | Medium | Fixed | Split temporary approved-adapter fetch locators from durable sanitized source refs. Ordinary URL query parameters can be used for approved retrieval; signed URLs, credentials, token-bearing refs, and local paths cannot be persisted as source identity. | | Human review | API contract for `pre_submission_checker_failed` was ambiguous. | High | Fixed | Locked separate paths: preflight returns `200 PreSubmitCheckResponse`; blocked submission creation returns `422 DomainError(code="pre_submission_checker_failed")` with structured details. | | Human review | Approved policies and compiled bundles needed append-only lifecycle rules. | High | Fixed | Added `draft -> approved -> superseded` lifecycle, immutable approved/superseded rows, supersedes pointers, and `compiled_bundle` as canonical JSON source of truth with derived index projections only. | | Human review | PR body still asked whether `evidence_policy` should remain as a compatibility alias and whether pre-submit policy should derive on read. | Medium | Fixed | Removed stale human-review questions from the PR body. The current plan says no `evidence_policy` compatibility alias and no derive-on-read runtime path. | -| Human review | Chunk 2 still implied a project-level `PreSubmitCheckerPolicy`, while Chunk 3 and the data model correctly make `PreSubmitCheckerPolicy` task-level. | High | Fixed | Introduced `ProjectPreSubmitCheckerSpec` for Chunk 2. The trusted compiler validates and canonicalizes the project checker spec in Chunk 2; Chunk 3 combines task binding and persists final task-level `PreSubmitCheckerPolicy`. | +| Human review | Prior edits overcorrected into task-level checker generation. | High | Fixed | Removed per-task policy/checker generation from the plan. Chunk 2 persists the project `PreSubmitCheckerPolicy`; Chunk 3 only locks task references to the project guide, effective policy, and checker hash. | | Human review | `GuideSourceSnapshot` looked like a single source ref instead of a guide material bundle. | High | Fixed | Updated the data model, ADR, plan, chunk map, chunk contract, and template to model `GuideSourceSnapshot` as a canonical manifest bundle with per-item source records and a bundle hash. | | Human review | Remaining schema details were ambiguous: size fields, hash algorithm, dual status fields, and source snapshot hash consistency. | High | Fixed | Added `maximum_file_size_bytes` and `maximum_package_size_bytes`, locked `artifact_hash_algorithm` to platform `sha256`, normalized policy lifecycle to `lifecycle_status`, and documented `source_snapshot_hash` as server-derived from the snapshot bundle hash. | | Human review | New guide snapshots needed an explicit fairness boundary for already locked tasks. | High | Fixed | Added the protective rule: a new guide-source snapshot invalidates setup records for new activation and unlocked tasks only; already locked tasks retain their context unless explicitly rebased through audit. | diff --git a/docs/architecture_checker_framework.md b/docs/architecture_checker_framework.md index b87364b..620a89c 100644 --- a/docs/architecture_checker_framework.md +++ b/docs/architecture_checker_framework.md @@ -101,11 +101,12 @@ Ensures a task has rubric or acceptance criteria. ### check_required_files -Validates required submission artifacts from the effective task submission artifact policy. +Validates required submission artifacts from the locked project pre-submit +checker policy. ### check_forbidden_files -Blocks known forbidden artifacts, secrets, private keys, copied internal data, or artifacts forbidden by the effective task submission artifact policy. +Blocks known forbidden artifacts, secrets, private keys, copied internal data, or artifacts forbidden by the locked project pre-submit checker policy. Default forbidden patterns include: @@ -167,9 +168,6 @@ ProjectGuide -> GuideSufficiencyReport -> ProjectSubmissionArtifactPolicy -> EffectiveProjectSubmissionArtifactPolicy --> ProjectPreSubmitCheckerSpec --> ApprovedTaskArtifactBinding --> EffectiveTaskSubmissionArtifactPolicy -> trusted Workstream checker compiler -> PreSubmitCheckerPolicy -> pre-submit intake checks @@ -201,8 +199,9 @@ Workstream default submission artifact rules require: Project policy adds required artifacts, evidence requirements, stricter forbidden artifacts, stricter packaging rules, and project-specific attestation requirements. -The generated `PreSubmitCheckerPolicy` is persisted, hashed, and locked to the -effective task submission artifact policy before workers submit packets. It +The generated project `PreSubmitCheckerPolicy` is persisted, hashed, and locked +to the effective project submission artifact policy before tasks enter the +worker pipeline. Tasks lock references to that shared project checker hash. It runs before Workstream creates a submission. Preflight failures return `PreSubmitCheckResponse` with `status="failed"`, `eligible_to_submit=false`, and structured pass/fail/warning details in @@ -212,13 +211,11 @@ 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`. -The `SubmissionArtifactPolicyDerivationAgent` produces -`ProjectPreSubmitCheckerSpec`, a constrained project-level checker -specification. It does not produce unrestricted checker code and does not create -a project-level `PreSubmitCheckerPolicy` row. Workstream's trusted checker -compiler validates and canonicalizes the project spec during setup, then later -combines it with task binding and effective task policy to produce deterministic -task-level checker logic using approved primitives such as: +The `SubmissionArtifactPolicyDerivationAgent` produces a constrained checker +specification. It does not produce unrestricted checker code. Workstream's +trusted checker compiler validates that project spec during setup, then +persists deterministic project-level checker logic using approved primitives +such as: - `require_file` - `allow_extension` @@ -263,7 +260,7 @@ Examples: ```text Draft packet -> load locked task context --> load locked EffectiveTaskSubmissionArtifactPolicy hash +-> load locked EffectiveProjectSubmissionArtifactPolicy hash -> load locked PreSubmitCheckerPolicy snapshot/hash -> run pre-submit intake checks -> create Submission only when blocking pre-submit checks pass diff --git a/docs/architecture_data_model.md b/docs/architecture_data_model.md index ec786d5..4a201a8 100644 --- a/docs/architecture_data_model.md +++ b/docs/architecture_data_model.md @@ -18,7 +18,7 @@ Project GuideSufficiencyReport SubmissionArtifactPolicy EffectiveProjectSubmissionArtifactPolicy - ProjectPreSubmitCheckerSpec + PreSubmitCheckerPolicy PostSubmitCheckerPolicy ReviewPolicy RevisionPolicy @@ -26,9 +26,6 @@ Project ProjectLesson Task - ApprovedTaskArtifactBinding - EffectiveTaskSubmissionArtifactPolicy - PreSubmitCheckerPolicy Assignment Submission EvidenceItem @@ -181,7 +178,7 @@ That field is old construction state. The architecture source of truth is `SubmissionArtifactPolicy`, and the replacement path does not require a compatibility alias. -Implementation note: `ProjectGuide.required_submission_fields` is a legacy display summary. Submission validity is enforced by `EffectiveTaskSubmissionArtifactPolicy`, not by project guide fields. +Implementation note: `ProjectGuide.required_submission_fields` is a legacy display summary. Submission validity is enforced by the locked `PreSubmitCheckerPolicy` generated from `EffectiveProjectSubmissionArtifactPolicy`, not by project guide fields. ## GuideSourceSnapshot @@ -436,135 +433,19 @@ project setup as a policy conflict. It is not deferred to worker submission. Approved and superseded effective policies are immutable. Recomputing the effective policy after guide/source/policy changes creates a new row and hash. -## ProjectPreSubmitCheckerSpec - -Fields: - -- `id` -- `project_id` -- `guide_version` -- `source_snapshot_id` -- `source_snapshot_hash` -- `effective_project_policy_hash` -- `version` -- `lifecycle_status` -- `canonical_spec` -- `canonical_spec_hash` -- `compiler_version` -- `generated_from_policy_version` -- `generated_at` -- `approved_by_role` -- `approved_by` -- `approved_at` -- `supersedes_spec_id` - -`ProjectPreSubmitCheckerSpec` is the project-level constrained checker -specification produced from the approved project submission artifact policy. It -uses only Workstream-approved primitives. The trusted compiler validates and -canonicalizes this specification during project setup, but it does not persist a -project-level `PreSubmitCheckerPolicy` row. The final executable -`PreSubmitCheckerPolicy` is task-level and is created only after task artifact -binding produces `EffectiveTaskSubmissionArtifactPolicy`. - -## ApprovedTaskArtifactBinding - -Fields: - -- `id` -- `task_id` -- `project_id` -- `guide_version` -- `source_snapshot_id` -- `source_snapshot_hash` -- `effective_project_policy_hash` -- `artifact_profile` -- `required_paths` -- `required_evidence` -- `additional_packaging_rules` -- `additional_forbidden_artifacts` -- `lifecycle_status` -- `approved_by_role` -- `approved_by` -- `approved_at` -- `created_at` -- `supersedes_binding_id` - -`ApprovedTaskArtifactBinding` turns a project-level policy into a concrete -task-level intake contract. A project can contain many task types, so Workstream -must not assume every task under one guide submits the same artifacts. The -binding selects an approved artifact profile and supplies constrained -parameters, for example: - -```json -{ - "artifact_profile": "coding_task", - "required_paths": ["src/parser.py", "tests/test_parser.py"] -} -``` - -Task bindings can add or tighten requirements. They cannot weaken Workstream -defaults or the effective project policy. - -## EffectiveTaskSubmissionArtifactPolicy - -Generated server-side from: - -```text -EffectiveProjectSubmissionArtifactPolicy -+ ApprovedTaskArtifactBinding -``` - -Fields: - -- `id` -- `task_id` -- `project_id` -- `guide_version` -- `source_snapshot_id` -- `source_snapshot_hash` -- `version` -- `lifecycle_status` -- `policy_hash` -- `effective_project_policy_hash` -- `approved_task_artifact_binding_id` -- `required_artifacts` -- `required_evidence` -- `artifact_manifest_required` -- `artifact_hash_required` -- `artifact_hash_algorithm` -- `maximum_file_size_bytes` -- `maximum_package_size_bytes` -- `allowed_storage_schemes` -- `forbidden_artifacts` -- `required_attestation_terms` -- `packaging_rules` -- `generated_at` -- `supersedes_policy_id` - -This policy is locked when the task enters `SCREENING` or `READY`. Submission -pre-check and submission creation use this task policy hash, not project guide -prose and not transitional task fields. - ## PreSubmitCheckerPolicy -Generated server-side from `EffectiveTaskSubmissionArtifactPolicy` and the -approved `ProjectPreSubmitCheckerSpec`, then persisted and locked to the task -policy hash before the task enters the worker pipeline. - Fields: - `id` -- `task_id` - `project_id` - `guide_version` - `source_snapshot_id` - `source_snapshot_hash` +- `effective_project_policy_hash` - `version` - `lifecycle_status` - `policy_hash` -- `effective_task_submission_artifact_policy_hash` -- `project_pre_submit_checker_spec_id` -- `project_pre_submit_checker_spec_hash` - `checker_spec` - `compiler_version` - `compiled_bundle_hash` @@ -574,19 +455,30 @@ Fields: - `blocking_severities` (derived index projection) - `generated_from_policy_version` - `generated_at` +- `approved_by_role` +- `approved_by` +- `approved_at` - `supersedes_policy_id` -`checker_spec` is the task-applied constrained machine-readable specification -using Workstream-approved primitives. It is derived from the approved -`ProjectPreSubmitCheckerSpec` and task policy binding. `compiled_bundle` is the -immutable JSON checker bundle produced by the trusted Workstream checker -compiler and is the canonical source of truth. It is stored as a structured -snapshot, not arbitrary executable code. `compiled_bundle_hash` binds the exact -compiled logic to `effective_task_submission_artifact_policy_hash` and -`project_pre_submit_checker_spec_hash`. `checker_names`, +Generated server-side from `EffectiveProjectSubmissionArtifactPolicy`, then +persisted and locked for the project guide version before tasks enter the +worker pipeline. Most tasks under the same project guide reuse the same +pre-submit checker bundle. The task stores the locked project checker hash; it +does not own a newly derived policy or newly compiled checker. + +`checker_spec` is the constrained machine-readable specification using +Workstream-approved primitives. `compiled_bundle` is the immutable JSON checker +bundle produced by the trusted Workstream checker compiler and is the canonical +source of truth. It is stored as a structured snapshot, not arbitrary executable +code. `compiled_bundle_hash` binds the exact compiled logic to +`effective_project_policy_hash`. `checker_names`, `checker_configs`, and `blocking_severities` are derived index projections only; they must be regenerated from `compiled_bundle` and must not disagree with it. +Task-specific values, such as expected output path or task id, are constrained +runtime parameters consumed by the locked checker bundle. They are not new +policy derivation and do not create a new checker bundle. + Approved and superseded checker policy rows are immutable. Changing policy or compiler output creates a new row with `supersedes_policy_id`. @@ -735,8 +627,6 @@ Fields: - `locked_guide_source_snapshot_hash` - `locked_submission_artifact_policy_version` - `locked_effective_project_submission_artifact_policy_hash` -- `locked_task_artifact_binding_id` -- `locked_effective_task_submission_artifact_policy_hash` - `locked_pre_submit_checker_policy_hash` - `locked_post_submit_checker_policy_version` - `locked_review_policy_version` @@ -792,11 +682,11 @@ External origin adapters are later work. When added, they normalize into this ta The task id points to the locked task contract. That contract includes the guide version, guide source snapshot hash, project submission artifact policy version, -effective project policy hash, approved task artifact binding, effective task -policy hash, generated pre-submit checker policy hash, post-submit checker -policy version, review policy version, revision policy version, payment policy -version, acceptance criteria, derived display summaries, base payout, and skill -tags. Workers submit against the task id; they do not restate policy versions. +effective project policy hash, generated pre-submit checker policy hash, +post-submit checker policy version, review policy version, revision policy +version, payment policy version, acceptance criteria, derived display summaries, +base payout, and skill tags. Workers submit against the task id; they do not +restate policy versions. Implementation note: current v0.1 code uses `locked_checker_policy_version` for the post-submit checker policy version. The architecture target splits this into `locked_post_submit_checker_policy_version` and explicit submission artifact/pre-submit provenance fields. @@ -832,8 +722,6 @@ Fields: - `locked_guide_source_snapshot_hash` - `locked_submission_artifact_policy_version` - `locked_effective_project_submission_artifact_policy_hash` -- `locked_task_artifact_binding_id` -- `locked_effective_task_submission_artifact_policy_hash` - `locked_pre_submit_checker_policy_hash` - `locked_post_submit_checker_policy_version` - `locked_review_policy_version` @@ -846,11 +734,11 @@ Fields: The worker submission packet supplies the task id, summary, outputs, artifact hashes, evidence references, and worker attestation. Workstream assigns the submission version, creates evidence ids, and stamps locked guide source, -submission artifact, effective task policy, pre-submit checker, post-submit +submission artifact, effective project policy, pre-submit checker, post-submit checker, review, revision, and payment policy provenance from trusted task/project state. The worker does not provide submission version, evidence ids, checker results, checker run ids, guide versions, source snapshots, -submission artifact policy versions, task policy hashes, post-submit checker +submission artifact policy versions, policy hashes, post-submit checker policy versions, review policy versions, revision policy versions, or payment policy versions. diff --git a/docs/architecture_lifecycle_state_machine.md b/docs/architecture_lifecycle_state_machine.md index 35caf82..e43fab0 100644 --- a/docs/architecture_lifecycle_state_machine.md +++ b/docs/architecture_lifecycle_state_machine.md @@ -76,9 +76,8 @@ Required before entering: - GuideSufficiencyReport passed or warnings acknowledged for that source snapshot - ProjectSubmissionArtifactPolicy approved - EffectiveProjectSubmissionArtifactPolicy hash persisted -- ApprovedTaskArtifactBinding exists -- EffectiveTaskSubmissionArtifactPolicy hash locked -- task-level PreSubmitCheckerPolicy persisted and locked to that task policy hash +- project PreSubmitCheckerPolicy persisted and locked to that effective project policy hash +- task locked to GuideSourceSnapshot id/hash, EffectiveProjectSubmissionArtifactPolicy hash, and PreSubmitCheckerPolicy hash - PostSubmitCheckerPolicy present - review policy present - revision policy present @@ -104,7 +103,7 @@ Required before entering: - submission summary - package or output reference - evidence items -- effective task submission artifact policy loaded +- effective project submission artifact policy loaded - generated pre-submit checker policy executed - no blocking pre-submit failures - immutable submission version diff --git a/docs/architecture_lockdown.md b/docs/architecture_lockdown.md index b3a2594..72a7498 100644 --- a/docs/architecture_lockdown.md +++ b/docs/architecture_lockdown.md @@ -85,7 +85,7 @@ with the `admin` or `project_manager` role approves the internal policy bundle before guide activation. Project owners do not approve Workstream's internal submission policy schema. -`SubmissionArtifactPolicy` defines project-level intake rules. Workstream combines it with the non-bypassable Workstream default submission artifact policy to create `EffectiveProjectSubmissionArtifactPolicy`, derives and canonicalizes `ProjectPreSubmitCheckerSpec`, then combines `EffectiveProjectSubmissionArtifactPolicy` with `ApprovedTaskArtifactBinding` to create `EffectiveTaskSubmissionArtifactPolicy`. Workstream persists the effective task policy hash, then generates, persists, hashes, and locks the task-level `PreSubmitCheckerPolicy` from that task policy and approved project checker spec. +`SubmissionArtifactPolicy` defines project-level intake rules. Workstream combines it with the non-bypassable Workstream default submission artifact policy to create `EffectiveProjectSubmissionArtifactPolicy`. Workstream then generates, persists, hashes, and locks project `PreSubmitCheckerPolicy` from that effective project policy. Tasks lock the applicable guide snapshot, effective project policy hash, and pre-submit checker policy hash before entering the worker pipeline. Blocking pre-submit failures prevent submission creation. Preflight failures return `PreSubmitCheckResponse(status="failed", eligible_to_submit=false, @@ -107,7 +107,7 @@ Every task must carry enough information to make claiming, checking, reviewing, - task type - required output - acceptance criteria -- required artifacts and evidence references derived from the effective task submission artifact policy +- required artifacts and evidence references derived from the locked project pre-submit checker policy - difficulty - skill tags - estimated time when known @@ -161,9 +161,6 @@ Use these names consistently: - `ContributionRecord` - `SubmissionArtifactPolicy` - `EffectiveProjectSubmissionArtifactPolicy` -- `ProjectPreSubmitCheckerSpec` -- `ApprovedTaskArtifactBinding` -- `EffectiveTaskSubmissionArtifactPolicy` - `PreSubmitCheckerPolicy` - `PostSubmitCheckerPolicy` - `pre_submission_checker_failed` diff --git a/docs/current_system_data_flow.html b/docs/current_system_data_flow.html index 4e2a8f8..4b793a1 100644 --- a/docs/current_system_data_flow.html +++ b/docs/current_system_data_flow.html @@ -483,7 +483,7 @@

Project guide and policy are prepared

3

Guide activation locks contract

-

Activation validates a passing or acknowledged sufficiency report, immutable guide source snapshot, approved submission artifact policy, effective project policy hash, registered post-submit checker names, review policy allowed decisions, revision states, and payment policy. Task readiness later validates the approved task artifact binding, effective task policy hash, and task-level pre-submit policy.

+

Activation validates a passing or acknowledged sufficiency report, immutable guide source snapshot, approved submission artifact policy, effective project policy hash, project pre-submit checker policy, registered post-submit checker names, review policy allowed decisions, revision states, and payment policy. Task readiness later validates that the task locks the applicable guide snapshot, effective project policy hash, and pre-submit checker policy hash.

status=active one active guide @@ -515,7 +515,7 @@

Worker claims and starts

6

Pre-submit intake checks run

-

Workstream runs generated pre-submit checks from the effective task submission artifact policy before creating a submission row. Preflight failures return PreSubmitCheckResponse details. Blocked submission-create attempts return pre_submission_checker_failed with pass/fail/warning details.

+

Workstream runs generated pre-submit checks from the locked project pre-submit checker policy before creating a submission row. Preflight failures return PreSubmitCheckResponse details. Blocked submission-create attempts return pre_submission_checker_failed with pass/fail/warning details.

no submission yet no checker run yet @@ -591,11 +591,11 @@

Durable Records Created Along The Way

Project + Guide - Project, ProjectGuide, GuideSourceSnapshot bundle, SubmissionArtifactPolicy, effective project policy, ProjectPreSubmitCheckerSpec, post-submit checker policy, review policy, revision policy, payment policy. + Project, ProjectGuide, GuideSourceSnapshot bundle, SubmissionArtifactPolicy, effective project policy, project PreSubmitCheckerPolicy, post-submit checker policy, review policy, revision policy, payment policy.
Task Queue - WorkstreamTask, approved task artifact binding, effective task policy, task-level PreSubmitCheckerPolicy, TaskAssignment, status transitions. + WorkstreamTask, locked guide snapshot, locked effective project policy hash, locked pre-submit checker policy hash, TaskAssignment, status transitions.
Submission Packet diff --git a/docs/decision_0003_project_guides_are_first_class.md b/docs/decision_0003_project_guides_are_first_class.md index d8331a4..f742a45 100644 --- a/docs/decision_0003_project_guides_are_first_class.md +++ b/docs/decision_0003_project_guides_are_first_class.md @@ -23,7 +23,7 @@ The guide drives: - task requirements - submission artifact policy - guide source snapshot and effective project submission artifact policy -- task pre-submit checker policy generated from the effective task submission artifact policy +- project pre-submit checker policy generated from the effective project submission artifact policy - post-submit checker policy - review policy - revision policy @@ -43,7 +43,7 @@ Project guide activation requires the guide plus its required policy context bef - revision policy - payment policy -The Workstream-derived submission artifact policy defines project-level intake rules. Project owners provide open-ended project material and business terms. Workstream captures an immutable guide source snapshot, evaluates guide sufficiency, derives the machine policy, and a Workstream actor with the `admin` or `project_manager` role approves the internal policy bundle. Workstream combines that policy with non-bypassable Workstream default artifact rules to create the effective project policy. Task screening later combines that effective project policy with an approved task artifact binding to create the effective task policy and generated pre-submit checker policy. +The Workstream-derived submission artifact policy defines project-level intake rules. Project owners provide open-ended project material and business terms. Workstream captures an immutable guide source snapshot, evaluates guide sufficiency, derives the machine policy, and a Workstream actor with the `admin` or `project_manager` role approves the internal policy bundle. Workstream combines that policy with non-bypassable Workstream default artifact rules to create the effective project policy, then generates the project pre-submit checker policy from that effective project policy. Tasks lock references to the applicable guide snapshot, effective project policy hash, and pre-submit checker policy hash. Blocking pre-submit failures prevent submission creation. They do not create durable post-submit checker runs and they do not create human review decisions. 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 ceab288..a1aad40 100644 --- a/docs/decision_0011_submission_artifact_policy_drives_pre_submit.md +++ b/docs/decision_0011_submission_artifact_policy_drives_pre_submit.md @@ -26,8 +26,6 @@ Every active project guide version must have a complete guide-policy bundle: Before a task can enter the worker pipeline, it must also have: -- approved `ApprovedTaskArtifactBinding` -- persisted `EffectiveTaskSubmissionArtifactPolicy` hash - persisted generated `PreSubmitCheckerPolicy` snapshot/hash Project owners provide open-ended project material in plain language. Workstream @@ -99,30 +97,32 @@ EffectiveProjectSubmissionArtifactPolicy = WorkstreamDefaultSubmissionArtifactPolicy + ProjectSubmissionArtifactPolicy -EffectiveTaskSubmissionArtifactPolicy = - EffectiveProjectSubmissionArtifactPolicy - + ApprovedTaskArtifactBinding +PreSubmitCheckerPolicy = + trusted compiler output from EffectiveProjectSubmissionArtifactPolicy ``` -`SubmissionArtifactPolicyDerivationAgent` produces -`ProjectPreSubmitCheckerSpec` at project setup time. Workstream's trusted -checker compiler validates and canonicalizes that project checker specification -but does not persist a project-level `PreSubmitCheckerPolicy` row. After task -binding, the compiler combines the approved task binding, effective task policy, -and approved project checker specification, then persists the final task-level +`SubmissionArtifactPolicyDerivationAgent` produces a constrained checker +specification at project setup time. Workstream's trusted checker compiler +validates that specification and persists the project-level `PreSubmitCheckerPolicy`. Project policies define project-wide artifact intake rules for a guide -snapshot. Tasks can still have different required outputs. `ApprovedTaskArtifactBinding` -selects an approved artifact profile and constrained task parameters. It can -add or tighten requirements, never weaken platform defaults or the effective -project policy. The resulting effective task policy hash is locked when the -task enters `SCREENING` or `READY`. - -`PreSubmitCheckerPolicy` is locked to the effective task policy hash. It is not -derived on read, manually edited by workers, or supplied by clients. Workers +snapshot. The dominant operating model is one project guide, one effective +project policy, and one project pre-submit checker bundle reused by every task +under that guide version. `ProjectGuideSufficiencyAgent` is responsible for +checking that the guide and derived policy cover the project's task set. If the +guide does not cover the tasks, activation is blocked and the guide is improved +or the work is split into another project/guide. Workstream does not hide guide +coverage problems by generating new task-specific policies. + +`PreSubmitCheckerPolicy` is locked to the effective project policy hash. It is +not derived on read, manually edited by workers, or supplied by clients. Workers submit only draft packet fields. They do not choose checker names, policy -versions, blocking rules, severities, or outcomes. +versions, blocking rules, severities, or outcomes. Each task stores locked +references to the applicable guide snapshot, effective project policy hash, and +pre-submit checker policy hash before entering the worker pipeline. Task-specific +values are constrained runtime parameters consumed by the shared checker, not +new checker generation. The compiled `PreSubmitCheckerPolicy` is deterministic checker logic, not an agent judgment loop. Runtime checks execute the locked compiled checker bundle @@ -267,9 +267,9 @@ approved -> immutable superseded -> immutable ``` -Changing an approved policy, effective policy, task binding, or compiled checker -bundle creates a new row with a `supersedes_*` reference. Approved rows are -never edited in place. For `PreSubmitCheckerPolicy`, `compiled_bundle` is the +Changing an approved policy, effective policy, or compiled checker bundle +creates a new row with a `supersedes_*` reference. Approved rows are never +edited in place. For `PreSubmitCheckerPolicy`, `compiled_bundle` is the canonical JSON source of truth and `compiled_bundle_hash` is the hash of that canonical JSON. `checker_names`, `checker_configs`, and `blocking_severities` are derived index projections only. diff --git a/docs/glossary.md b/docs/glossary.md index 5cd5deb..bc22d5b 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -54,23 +54,11 @@ version before Workstream merges it with default submission artifact policy. ## Effective Project Submission Artifact Policy -The deterministic merge of Workstream's default submission artifact policy and the project-approved submission artifact policy. Workstream computes this effective project policy before task-specific binding. - -## Project Pre-Submit Checker Spec - -The constrained project-level checker specification derived from the approved -project submission artifact policy. Workstream validates and canonicalizes this -spec during project setup. It is not a `PreSubmitCheckerPolicy` row. - -## Effective Task Submission Artifact Policy - -The deterministic merge of the effective project submission artifact policy and -an approved task artifact binding. Workstream locks this task policy before -generating the task-level pre-submit checker policy. +The deterministic merge of Workstream's default submission artifact policy and the project-approved submission artifact policy. Workstream computes this effective project policy before generating the project pre-submit checker policy. ## Pre-Submit Checker Policy -The server-generated task-level checker matrix produced from the effective task submission artifact policy and approved project checker spec, persisted with a hash, and locked before a task enters the worker pipeline. It runs before Workstream creates a submission row or submission version. The preflight endpoint returns `PreSubmitCheckResponse`; a blocked submission-create attempt returns `pre_submission_checker_failed` with structured pass/fail/warning details. Neither path returns review decision values: `accept`, `needs_revision`, or `reject`. +The server-generated project checker matrix produced from the effective project submission artifact policy, persisted with a hash, and locked by tasks before they enter the worker pipeline. It runs before Workstream creates a submission row or submission version. The preflight endpoint returns `PreSubmitCheckResponse`; a blocked submission-create attempt returns `pre_submission_checker_failed` with structured pass/fail/warning details. Neither path returns review decision values: `accept`, `needs_revision`, or `reject`. ## pre_submission_checker_failed @@ -94,7 +82,7 @@ An automated rule that validates a task or submission before human review. ## Checker Policy -The set of required and warning checks for a project phase. Pre-submit checker policy is generated from the effective task submission artifact policy. Post-submit checker policy governs durable internal checker runs after a submission is locked. +The set of required and warning checks for a project phase. Pre-submit checker policy is generated from the effective project submission artifact policy. Post-submit checker policy governs durable internal checker runs after a submission is locked. ## Human Review diff --git a/docs/operations_project_operating_manual.md b/docs/operations_project_operating_manual.md index 40bd991..659cb0c 100644 --- a/docs/operations_project_operating_manual.md +++ b/docs/operations_project_operating_manual.md @@ -37,8 +37,8 @@ Before releasing tasks: - guide sufficiency report passed or warnings acknowledged by `admin` or `project_manager` - submission artifact policy derived by Workstream and approved by `admin` or `project_manager` - effective project submission artifact policy hash persisted -- task artifact binding and effective task submission artifact policy are created before each task enters `READY` -- generated pre-submit checker policy is created from the effective task submission artifact policy +- generated project pre-submit checker policy is created from the effective project submission artifact policy +- each task locks the guide snapshot, effective project policy hash, and pre-submit checker policy hash before entering `READY` - post-submit checker policy attached - review policy attached - revision policy attached @@ -54,8 +54,8 @@ A project cannot become active unless guide, passed or acknowledged guide sufficiency report, approved submission artifact policy, persisted effective project submission artifact policy hash, post-submit checker policy, review policy, revision policy, and payment policy are present. A task cannot enter -`READY` until it also has an approved task artifact binding, effective task -submission artifact policy hash, and task-level pre-submit checker policy. +`READY` until it also locks the effective project submission artifact policy +hash and project pre-submit checker policy hash. ### Task Screening Gate @@ -108,7 +108,7 @@ Before accepting a submission packet: - output package or reference exists - evidence exists - revision replay exists when task was previously `NEEDS_REVISION` -- effective task submission artifact policy is loaded +- effective project submission artifact policy is loaded - generated pre-submit checker policy runs - preflight failures return `PreSubmitCheckResponse(status="failed", eligible_to_submit=false, results=[...])` - blocked submission-create attempts return `pre_submission_checker_failed` with structured pass/fail/warning details diff --git a/docs/operations_workspace_packet_convention.md b/docs/operations_workspace_packet_convention.md index e9a61ce..fff3986 100644 --- a/docs/operations_workspace_packet_convention.md +++ b/docs/operations_workspace_packet_convention.md @@ -18,11 +18,11 @@ ProjectSubmissionArtifactPolicy EffectiveProjectSubmissionArtifactPolicy ``` -Every task then locks a task-specific intake bundle: +Every task then locks the project intake context: ```text -ApprovedTaskArtifactBinding -EffectiveTaskSubmissionArtifactPolicy +GuideSourceSnapshot +EffectiveProjectSubmissionArtifactPolicy PreSubmitCheckerPolicy required_artifacts required_evidence diff --git a/docs/product_first_user_flows.md b/docs/product_first_user_flows.md index 3a6cd8d..7a5f605 100644 --- a/docs/product_first_user_flows.md +++ b/docs/product_first_user_flows.md @@ -31,14 +31,14 @@ Acceptance: 2. Operator creates task with title, description, expected output, acceptance criteria, base amount, deadline, and difficulty. 3. Workstream validates task against project guide. 4. Task enters `SCREENING`. -5. Screening confirms guide source snapshot, task contract, approved task artifact binding, effective task submission artifact policy hash, generated pre-submit checker policy, post-submit checker policy, review policy, revision policy, payment policy, and reviewability. +5. Screening confirms guide source snapshot, task contract, effective project submission artifact policy hash, generated project pre-submit checker policy, post-submit checker policy, review policy, revision policy, payment policy, and reviewability. 6. Task enters `READY`. Acceptance: - Missing required fields block `SCREENING`. - Missing required fields block `READY`. -- Task shows project guide, task-specific required artifacts, generated pre-submit checker policy summary, post-submit checker policy, review policy, revision policy, and payment policy. +- Task shows project guide, required artifacts, generated pre-submit checker policy summary, post-submit checker policy, review policy, revision policy, and payment policy. ## Flow 3: Worker Submits Work @@ -46,7 +46,7 @@ Acceptance: 2. Worker attaches output files or links. 3. Worker attaches evidence. 4. Worker writes submission notes. -5. Workstream runs pre-submit checks generated from the effective task submission artifact policy. +5. Workstream runs pre-submit checks generated from the effective project submission artifact policy. 6. Preflight failures return `PreSubmitCheckResponse`; blocked submission-create attempts return `pre_submission_checker_failed` with structured pass/fail/warning details and create no submission. 7. When blocking pre-submit checks pass, Worker submits packet. 8. Task enters `SUBMITTED`. @@ -55,7 +55,7 @@ Acceptance: - Submission cannot be created when blocking pre-submit checks fail. - Blocking pre-submit failures are not review decisions and never return `accept`, `needs_revision`, or `reject`. -- Submission cannot be created without required artifacts, evidence references, hashes, and worker attestation defined by the effective task submission artifact policy. +- Submission cannot be created without required artifacts, evidence references, hashes, and worker attestation defined by the locked project pre-submit checker policy. - Submission packet is immutable after checks start. ## Flow 4: Automated Checks Run diff --git a/docs/roadmap_day_by_day_execution_plan.md b/docs/roadmap_day_by_day_execution_plan.md index e3c32c5..a91d9b4 100644 --- a/docs/roadmap_day_by_day_execution_plan.md +++ b/docs/roadmap_day_by_day_execution_plan.md @@ -68,7 +68,7 @@ Exit criteria: - retrieve the active guide version for a task - edit a draft guide without changing historical task guide versions - block activation of a guide missing guide source snapshot, submission artifact policy, effective project policy hash, post-submit checker, review, revision, or payment policy -- block task readiness when approved task artifact binding, effective task policy hash, or task-level pre-submit checker policy is missing +- block task readiness when locked guide snapshot, effective project policy hash, or project pre-submit checker policy hash is missing - migrations and model tests define the expected invariants ### Day 3: Task Queue @@ -199,7 +199,7 @@ Deliver: - generated `PreSubmitCheckerPolicy` - `PostSubmitCheckerPolicy` -- effective task submission artifact policy merge +- project pre-submit checker policy generation - project-required checker list - blocking severity settings - trusted checker retry with reason after internal setup repair diff --git a/docs/roadmap_implementation_backlog.md b/docs/roadmap_implementation_backlog.md index 5f0c38e..5f3e6ee 100644 --- a/docs/roadmap_implementation_backlog.md +++ b/docs/roadmap_implementation_backlog.md @@ -85,7 +85,7 @@ - implement `check_confidentiality_attestation` - implement `check_low_quality_generated_artifacts` - implement registered readiness checkers only after their contracts are locked -- implement generated pre-submit intake guards from the effective task submission artifact policy +- implement generated pre-submit intake guards from the effective project submission artifact policy ### Review diff --git a/docs/spec_chunk_3_project_guide_foundation.md b/docs/spec_chunk_3_project_guide_foundation.md index 5b9c58b..4151689 100644 --- a/docs/spec_chunk_3_project_guide_foundation.md +++ b/docs/spec_chunk_3_project_guide_foundation.md @@ -100,7 +100,7 @@ EffectiveProjectSubmissionArtifactPolicy = + ProjectSubmissionArtifactPolicy ``` -Task screening later combines the effective project policy with an approved task artifact binding to produce `EffectiveTaskSubmissionArtifactPolicy`. Workstream generates, persists, hashes, and locks task pre-submit checker policy from that task policy. Blocking pre-submit failures prevent submission creation. +Workstream generates, persists, hashes, and locks project `PreSubmitCheckerPolicy` from the effective project policy. Tasks later lock the applicable guide snapshot, effective project policy hash, and pre-submit checker policy hash. Blocking pre-submit failures prevent submission creation. Implementation note: the first v0.1 schema stored this as `ProjectGuide.evidence_policy`. That field is old construction state and is replaced by the dedicated policy table/API path. diff --git a/docs/spec_chunk_5_submission_packet_foundation.md b/docs/spec_chunk_5_submission_packet_foundation.md index dab6cc9..e31a253 100644 --- a/docs/spec_chunk_5_submission_packet_foundation.md +++ b/docs/spec_chunk_5_submission_packet_foundation.md @@ -125,13 +125,13 @@ Locks a submission packet before checker execution. Locking makes the packet imm - a worker can submit only when assigned to the task - first submission requires task status `IN_PROGRESS` -- Workstream loads the locked effective task submission artifact policy hash before creating a submission +- Workstream loads the locked effective project submission artifact policy hash before creating a submission - Workstream loads the locked generated pre-submit checker policy snapshot/hash before creating a submission - blocking pre-submit failures prevent submission creation - when blocking pre-submit fails, no submission row is created, no submission version is assigned, no task transition to `SUBMITTED` occurs, and no submission-created audit event is written - first submission moves the task to `SUBMITTED` - later replacement submissions are allowed while the task is still `SUBMITTED` -- submission packet content must satisfy the effective task submission artifact policy +- submission packet content must satisfy the locked project pre-submit checker policy - every submission creation writes a task audit event - the audit event includes submission id, submission version, worker id, package hash, and artifact hash manifest - locking a submission writes a task audit event diff --git a/docs/spec_chunk_6_checker_contract_records.md b/docs/spec_chunk_6_checker_contract_records.md index 5b5681c..08a22a6 100644 --- a/docs/spec_chunk_6_checker_contract_records.md +++ b/docs/spec_chunk_6_checker_contract_records.md @@ -213,7 +213,7 @@ Response fields: - `expires_at` Pre-submit feedback binds to `task_id`, the task's locked guide source snapshot, -approved task artifact binding, effective task submission artifact policy hash, +effective project submission artifact policy hash, pre-submit checker policy hash, draft packet fields, package hash, and artifact manifest shape. It does not require a locked `submission_id` or locked submission version because those do not exist before submission creation. diff --git a/docs/spec_chunk_7_checker_runner_registry.md b/docs/spec_chunk_7_checker_runner_registry.md index 354a9c5..9a4b1eb 100644 --- a/docs/spec_chunk_7_checker_runner_registry.md +++ b/docs/spec_chunk_7_checker_runner_registry.md @@ -26,7 +26,7 @@ Note: Chunk 8 supersedes the temporary Chunk 7 artifact-manifest and evidence-re - checker service - checker API router - checker registry -- pre-submit intake feedback path generated from the effective task submission artifact policy +- pre-submit intake feedback path generated from the effective project submission artifact policy - first structural checkers: - `check_submission_packet` - `check_policy_context_present` @@ -65,9 +65,8 @@ EffectiveProjectSubmissionArtifactPolicy = WorkstreamDefaultSubmissionArtifactPolicy + ProjectSubmissionArtifactPolicy -EffectiveTaskSubmissionArtifactPolicy = - EffectiveProjectSubmissionArtifactPolicy - + ApprovedTaskArtifactBinding +PreSubmitCheckerPolicy = + trusted compiler output from EffectiveProjectSubmissionArtifactPolicy ``` Workers cannot supply checker names, policy versions, severities, blocking rules, results, or outcomes. diff --git a/docs/spec_chunk_8_submission_artifact_policy_checkers.md b/docs/spec_chunk_8_submission_artifact_policy_checkers.md index dadfbf6..ebb3dae 100644 --- a/docs/spec_chunk_8_submission_artifact_policy_checkers.md +++ b/docs/spec_chunk_8_submission_artifact_policy_checkers.md @@ -112,7 +112,7 @@ Fails when required artifacts are not represented in the artifact manifest. The checker reads: -- `EffectiveTaskSubmissionArtifactPolicy.required_artifacts` +- locked project `PreSubmitCheckerPolicy` required artifacts - `submission.artifact_hash_manifest[*].artifact` `task.required_files` is legacy/transitional storage. It is not the policy source of truth once `SubmissionArtifactPolicy` is implemented. @@ -192,7 +192,7 @@ If a future project needs generated-artifact signals to block review, that must ## Pre-Submit Versus Durable Runs -Pre-submit feedback runs checks generated from the effective task submission artifact policy. These checks run before Workstream creates a submission row: +Pre-submit feedback runs checks generated from the effective project submission artifact policy. These checks run before Workstream creates a submission row: - `check_submission_packet` - `check_evidence_present` @@ -202,12 +202,11 @@ Pre-submit feedback runs checks generated from the effective task submission art - `check_confidentiality_attestation` - `check_low_quality_generated_artifacts` -The effective task submission artifact policy is: +The project pre-submit checker policy is generated from: ```text WorkstreamDefaultSubmissionArtifactPolicy + ProjectSubmissionArtifactPolicy -+ ApprovedTaskArtifactBinding ``` Workstream defaults are non-bypassable. Project policy can add required artifacts, evidence requirements, stricter forbidden patterns, and packaging rules, but it cannot remove hash requirements, allow unsafe storage references, require forbidden files, or downgrade blocking defaults. @@ -303,7 +302,7 @@ Safe evidence references mean opaque Workstream evidence ids, sanitized labels, - canonical Chunk 8 checker names are registered - stale Chunk 7 temporary checker names are removed from public docs/templates/tests -- pre-submit feedback is generated from the effective task submission artifact policy and runs without durable checker records +- pre-submit feedback is generated from the effective project submission artifact policy and runs without durable checker records - preflight failures return `PreSubmitCheckResponse(status="failed", eligible_to_submit=false, results=[...])` - blocked submission-create attempts return `DomainError(code="pre_submission_checker_failed")`, include structured pass/fail/warning details, create no submission row, no submission version, no task transition to `submitted`, and no submission-created audit event - Workstream default submission artifact rules cannot be weakened by project policy diff --git a/docs/spec_week2_checker_framework.md b/docs/spec_week2_checker_framework.md index 09f20d6..991810c 100644 --- a/docs/spec_week2_checker_framework.md +++ b/docs/spec_week2_checker_framework.md @@ -37,7 +37,7 @@ The checker framework protects reviewer time by proving that the latest locked s ## Core Invariant ```text -Draft packet -> EffectiveTaskSubmissionArtifactPolicy -> Pre-submit checks -> Submit -> Lock -> Internal CheckerRun -> CheckerResults -> routing recommendation +Draft packet -> project PreSubmitCheckerPolicy -> Pre-submit checks -> Submit -> Lock -> Internal CheckerRun -> CheckerResults -> routing recommendation ``` A task cannot reach `REVIEW_PENDING` unless the latest locked submission has a completed checker run for the exact submission version and artifact context. @@ -61,7 +61,7 @@ The checker binding includes: Workstream has two checker moments. -Pre-submit static checks run before Workstream creates a submission. They are generated from the effective task submission artifact policy and give immediate feedback on packet shape and policy issues: +Pre-submit static checks run before Workstream creates a submission. They are generated from the effective project submission artifact policy and give immediate feedback on packet shape and policy issues: - required field presence - package hash presence diff --git a/docs/template_checker_policy.md b/docs/template_checker_policy.md index 305e7a2..2fcfc9c 100644 --- a/docs/template_checker_policy.md +++ b/docs/template_checker_policy.md @@ -12,7 +12,7 @@ This template governs durable internal checker runs after a submission is created, locked, and ready for the pre-review gate. -It does not define pre-submit intake. `PreSubmitCheckerPolicy` is generated from `EffectiveTaskSubmissionArtifactPolicy`. +It does not define pre-submit intake. `PreSubmitCheckerPolicy` is generated from `EffectiveProjectSubmissionArtifactPolicy`. ## Design Boundaries @@ -54,9 +54,8 @@ EffectiveProjectSubmissionArtifactPolicy = WorkstreamDefaultSubmissionArtifactPolicy + ProjectSubmissionArtifactPolicy -EffectiveTaskSubmissionArtifactPolicy = - EffectiveProjectSubmissionArtifactPolicy - + ApprovedTaskArtifactBinding +PreSubmitCheckerPolicy = + trusted compiler output from EffectiveProjectSubmissionArtifactPolicy ``` Preflight failures return `PreSubmitCheckResponse(status="failed", diff --git a/docs/template_preflight_evidence.md b/docs/template_preflight_evidence.md index b602fde..2e9d701 100644 --- a/docs/template_preflight_evidence.md +++ b/docs/template_preflight_evidence.md @@ -2,7 +2,7 @@ This template is for post-submit review readiness evidence after a submission exists and checker runs have produced durable records. -It is not the pre-submit intake contract. Pre-submit intake is generated from `EffectiveTaskSubmissionArtifactPolicy` and blocks submission creation before a submission id, evidence id, or checker run id exists. +It is not the pre-submit intake contract. Pre-submit intake is generated from the project `PreSubmitCheckerPolicy` and blocks submission creation before a submission id, evidence id, or checker run id exists. ## Task diff --git a/docs/template_project_guide.md b/docs/template_project_guide.md index c2e3357..61d4dfa 100644 --- a/docs/template_project_guide.md +++ b/docs/template_project_guide.md @@ -118,9 +118,9 @@ Every active guide version must have: Each task later locks: -- ApprovedTaskArtifactBinding: -- EffectiveTaskSubmissionArtifactPolicy hash: -- generated PreSubmitCheckerPolicy: +- GuideSourceSnapshot id/hash: +- EffectiveProjectSubmissionArtifactPolicy hash: +- generated PreSubmitCheckerPolicy hash: Artifact requirements shown to workers are derived from the approved `SubmissionArtifactPolicy`. The guide may summarize those requirements, but the policy is the enforcement source. diff --git a/docs/template_submission_artifact_policy.md b/docs/template_submission_artifact_policy.md index 150d806..d587c01 100644 --- a/docs/template_submission_artifact_policy.md +++ b/docs/template_submission_artifact_policy.md @@ -153,20 +153,13 @@ Required attestation topics: - credentials and secret exclusion - human accountability for agent-assisted work -## Project Pre-Submit Checker Specification - -Workstream derives and canonicalizes a project-level -`ProjectPreSubmitCheckerSpec` from the approved project policy. This is a -constrained specification using approved primitives, not executable checker -code and not a project-level `PreSubmitCheckerPolicy` row. - ## Generated Pre-Submit Checker Policy -Workstream generates task-level `PreSubmitCheckerPolicy` from: +Workstream generates project-level `PreSubmitCheckerPolicy` from: ```text -EffectiveTaskSubmissionArtifactPolicy -+ ProjectPreSubmitCheckerSpec +EffectiveProjectSubmissionArtifactPolicy ++ constrained checker specification ``` Generated pre-submit checks run before submission creation. Blocking failures create no submission row, no submission version, no task transition to `submitted`, and no submission-created audit event. @@ -175,9 +168,12 @@ Generated policy lock: - generated pre-submit checker policy version: - generated pre-submit checker policy hash: -- effective task submission artifact policy hash: +- effective project submission artifact policy hash: - locked guide version: +Tasks lock this project checker hash before entering the worker pipeline. Tasks +do not derive or compile their own checker by default. + Blocked submission-create attempts return `pre_submission_checker_failed` with structured pass/fail/warning details. The preflight endpoint returns `PreSubmitCheckResponse` with `status`, From a954f0721db0e26738c495e51ce12f0a14f5c94d Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Wed, 24 Jun 2026 20:38:15 +0100 Subject: [PATCH 26/37] Refresh submission policy review evidence --- .agent-loop/LOOP_STATE.md | 2 +- .../WS-POL-001-01-internal-review-evidence.md | 94 +++++++------------ 2 files changed, 35 insertions(+), 61 deletions(-) diff --git a/.agent-loop/LOOP_STATE.md b/.agent-loop/LOOP_STATE.md index 7e5535c..7726c98 100644 --- a/.agent-loop/LOOP_STATE.md +++ b/.agent-loop/LOOP_STATE.md @@ -7,7 +7,7 @@ - Branch: `codex/submission-artifact-policy-loop-plan` - Status: planning review requested; implementation has not started - Merge commit: none for this initiative -- Reviewed code SHA: `9099b60533ba49eb3232fdf505dc17c69c8cbdad` +- Reviewed code SHA: `8a0fd181046e2eab9b668c614c845e62dd81db55` - Current gate: human planning approval pending; backend implementation is not approved - Next chunk: inactive until `WS-POL-001-01` is approved and completed diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md index 90085aa..4ce63f3 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-internal-review-evidence.md @@ -10,85 +10,59 @@ valid findings addressed: yes ## Reviewed Revision -Reviewed code SHA: 9099b60533ba49eb3232fdf505dc17c69c8cbdad +Reviewed code SHA: 8a0fd181046e2eab9b668c614c845e62dd81db55 -Reviewed at: 2026-06-24T11:38:57Z +Reviewed at: 2026-06-24T19:32:10Z -Reviewer run IDs: 019ef3df-a4ae-71f0-b50c-dbd99e65af6c, 019ef3e0-cc78-7583-abd8-826f77b6d435, 019ef3e2-d1fc-7642-b079-561bf61b3d07, 019ef3e5-1e10-78f2-b272-f06200c50334, 019ef3e7-6f3d-7730-a2fd-adc55e496811, 019ef3ea-b44c-7741-9ced-b05bb6a5e5d2, 019ef432-a806-75c1-96ac-11c93eea2f9c, 019ef45d-540a-71e1-9531-19277d5450ed, 019ef45f-a5fa-7721-b9ae-aa39b1f6778e, 019ef462-b086-7923-a03e-78c298316f73, 019ef466-2433-7bf3-9335-069cfa5b5838, 019ef46a-171d-7b42-9795-773132754ff0, 019ef46e-dcea-7423-aa46-47a27b098c85, 019ef51b-8491-7192-a868-f2cbc1c56079, 019ef51d-cc5d-7d40-b5e6-0966c546e465, 019ef520-eea1-71c0-919a-63d24728ff32, 019ef523-f173-7e71-8685-902518610fda, 019ef52a-1da8-7df2-9428-c96b1b0cc164, 019ef5c5-db38-76a1-8617-4572f7ebc7a2, 019ef5c7-2666-7e73-9147-4544265a3818, 019ef5c9-2749-75b2-819d-d7018f2b0e12, 019ef5cb-cc57-7151-b2ec-0f0d49ed0fb1, 019ef92b-9da7-7140-878a-1b12c6ed5cd9, 019ef92c-c0a4-7922-8a8c-7257ddb20919, 019ef92e-95d3-72d3-8519-c6ef83548bf8, 019ef930-f548-7dc1-beb4-b055c1f10363, 019ef933-f0a4-7ad3-a882-9a45b9e9b638, 019ef937-5144-7190-b4c5-f83af54de620, 019ef95b-77c6-7331-8dab-e3e7e9207f7a +Reviewer run IDs: 019efab5-b602-7b60-984a-49b66f6f3784, 019efab8-11b6-7223-aaf7-5c18653bdb77, 019efabb-4a07-7211-888c-f4af1eacffff, 019efabf-a0ad-7ee0-b48d-de9ce9a0041f, 019efac5-ba48-7a93-ad9e-ef758386182b, 019efacb-e430-7910-98a6-8098321a66f8, 019efb0c-d51d-7210-a25c-99df3efa71df -After reviewed SHA `9099b60533ba49eb3232fdf505dc17c69c8cbdad`, only review evidence and loop status artifacts changed. +After reviewed SHA `8a0fd181046e2eab9b668c614c845e62dd81db55`, only review evidence and loop status artifacts changed. ## Reviewer Results | Reviewer | Result | Blocking findings | Notes | |---|---:|---|---| -| senior engineering | PASS AFTER FIXES | None remaining | Confirmed no backend implementation started. Requested stale evidence refresh, removal of derived-on-read risk, and locked-policy wording in runtime docs. Fixed. | -| QA/test | PASS AFTER FIXES | None remaining | Requested Postgres-backed FastAPI/API proof for Chunk 1 and per-chunk verification expectations. Fixed. | -| security/auth | PASS AFTER FIXES | None remaining | Required project-owner material to be treated as untrusted input, with unsafe refs and embedded tool instructions rejected. Fixed. | -| product/ops | PASS AFTER FIXES | None remaining | Required full activation bundle wording, approved policy provenance, and no manual bypass of derivation agent. Fixed. | -| architecture | PASS AFTER FIXES | None remaining | Required activation docs to include `GuideSufficiencyReport` and effective policy hash, and fixed review-policy wording in the flow diagram. Fixed. | -| docs | PASS AFTER FIXES | None remaining | Required loop state refresh and active guide-policy bundle alignment in docs/templates. Fixed. | -| test-delta | PASS AFTER FIXES | None remaining | Required API-level proof obligations for Chunk 1 warning acknowledgement/provenance and Chunk 4 worker response filtering. Fixed. | -| focused senior engineering | PASS | None | Re-reviewed ADR 0011 enforcement contract and confirmed it does not falsely claim backend enforcement. | -| focused QA/test | PASS AFTER FIXES | None remaining | Found missing UI/demo ownership and schema/persistence proof assignment. Fixed in ADR 0011 and Chunk 4 proof obligations. | -| focused security/auth | PASS | None | Re-reviewed ADR 0011 fail-closed API/database contract and planning-only caveat. | -| focused product/ops | PASS | None | Confirmed worker-facing pre-submit language remains separate from review decisions. | -| focused architecture | PASS AFTER FIXES | None remaining | Confirmed boundaries and requested stale evidence refresh. Fixed by this evidence update. | -| focused docs | PASS WITH LOW RISKS | None | Confirmed ADR and external-review wording are clear and do not overclaim implementation. | -| checker compiler architecture | PASS | None | Confirmed agents derive constrained specs and Workstream owns deterministic compiled checker bundles. | -| checker compiler security/auth | PASS WITH LOW RISKS | None | Requested `admin` or `project_manager` approval of exact future extension code hash after validation and sandbox checks. Fixed. | -| checker compiler QA/test | PASS AFTER FIXES | None remaining | Requested proof for primitive allowlisting, unknown primitive rejection, canonical hash binding, immutable bundle behavior, no executable code fields by default, and future extension gate. Fixed. | -| checker compiler product/ops | PASS WITH LOW RISKS | None | Confirmed the workflow preserves setup-agent assistance, deterministic runtime checking, and admin/project_manager approval. | -| checker compiler docs | PASS AFTER FIXES | None remaining | Confirmed wording consistency and requested evidence refresh. Fixed by this evidence update. | -| response-contract senior engineering | PASS AFTER FIXES | None remaining | Requested external review response wording to match the corrected `PreSubmitCheckResponse` shape. Fixed. | -| response-contract QA/test | PASS AFTER FIXES | None remaining | Verified the architecture doc matches `backend/app/modules/checkers/schemas.py` and requested evidence refresh. Fixed. | -| response-contract security/auth | PASS AFTER FIXES | None remaining | Confirmed pre-submit failure remains separate from review decisions and requested evidence refresh. Fixed. | -| response-contract product/ops | PASS AFTER FIXES | None remaining | Confirmed operator-facing wording is clear and requested external review artifact cleanup plus evidence refresh. Fixed. | -| source-snapshot senior engineering | PASS AFTER FIXES | None remaining | Requested READY gate and checker-policy template alignment to task-specific policy binding. Fixed. | -| source-snapshot QA/test | PASS AFTER FIXES | None remaining | Requested Chunk 1 proof stay limited to guide snapshot, sufficiency, project policy, effective project policy hash, activation guard, and source/policy invariants. Fixed. | -| source-snapshot security/auth | PASS AFTER FIXES | None remaining | Requested durable source refs never persist query strings and READY require task-level source/policy binding. Fixed. | -| source-snapshot product/ops | PASS AFTER FIXES | None remaining | Requested removal of project-level pre-submit checker wording. Fixed. | -| source-snapshot architecture | PASS AFTER FIXES | None remaining | Requested canonical lineage and removal of old `EffectiveSubmissionArtifactPolicy` source-of-truth naming. Fixed. | -| source-snapshot docs | PASS AFTER FIXES | None remaining | Requested activation/readiness contract alignment and API wording cleanup. Fixed. | -| source-snapshot test delta | PASS AFTER FIXES | None remaining | Confirmed compiler proof moved to Chunk 2 and task runtime migration moved to Chunk 3, then requested migration scope and remaining activation-doc cleanup. Fixed. | +| senior engineering | PASS AFTER FIXES | None remaining | Found stale live docs still carrying the rejected task-level policy/checker model. Fixed across guide template, lifecycle, user flows, project manual, checker specs, and packet conventions. | +| QA/test | PASS AFTER FIXES | None remaining | Found stale submission fields for task artifact binding and effective task policy. Fixed. Confirmed Chunk 2 and Chunk 3 are feasible after the correction. | +| security/auth | PASS AFTER FIXES | None remaining | Found stale per-task provenance fields and stale evidence narrative. Fixed. Confirmed untrusted material handling, server-owned checker generation, and non-bypassable defaults. | +| product/ops | PASS AFTER FIXES | None remaining | Found stale per-task provenance fields and stale evidence narrative. Fixed. Confirmed the corrected product flow: project checker reused by tasks. | +| architecture | PASS AFTER FIXES | None remaining | Found stale per-task provenance fields and stale evidence narrative. Fixed. Confirmed the corrected chain: project guide -> sufficiency -> project policy -> effective project policy -> project `PreSubmitCheckerPolicy`; tasks lock references only. | +| docs | PASS AFTER FIXES | None remaining | Found stale live docs describing the rejected task-binding/effective-task-policy model. Fixed. | +| test-delta | PASS WITH LOW RISKS | None | Confirmed no executable tests changed, future proof obligations remain explicit, and live docs match the corrected project-level checker model. | ## Valid Findings Addressed -- Added explicit untrusted-source-material rules for project owner docs, URLs, repository docs, examples, and imported documents. -- Added immutable `GuideSourceSnapshot` binding with source snapshot id/hash on downstream report, policy, task binding, effective policy, and checker-bundle records. -- Clarified that ordinary URL query parameters may be temporary approved-adapter fetch inputs only; durable source refs cannot persist query strings, signed URLs, credentials, token-bearing refs, local filesystem paths, or private storage paths. -- Clarified that guide text and imported material cannot grant tool authority, override Workstream rules, or weaken default policy. -- Tightened Chunk 1 proof to require Postgres-backed FastAPI/API tests for guide source snapshots, activation blocking, warning acknowledgement by `admin` or `project_manager`, approval provenance, default weakening, source-ref sanitization, append-only policy rows, and effective project policy hash persistence. -- Added per-chunk verification expectations for async guide analysis, submission creation, post-submit policy split, and revision resubmission real API drill. -- Updated activation docs to require guide source snapshot, passed or acknowledged `GuideSufficiencyReport`, approved `SubmissionArtifactPolicy`, `EffectiveProjectSubmissionArtifactPolicy` hash, post-submit checker policy, review policy, revision policy, and payment policy. -- Updated task readiness docs to require `ApprovedTaskArtifactBinding`, `EffectiveTaskSubmissionArtifactPolicy` hash, and task-level `PreSubmitCheckerPolicy` before workers can claim work. -- Replaced stale runtime wording that implied one project-level pre-submit checker with the canonical lineage: `GuideSourceSnapshot -> ProjectSubmissionArtifactPolicy -> EffectiveProjectSubmissionArtifactPolicy -> ApprovedTaskArtifactBinding -> EffectiveTaskSubmissionArtifactPolicy -> PreSubmitCheckerPolicy`. -- Replaced ambiguous `derivation source: manual | workstream_agent | import_adapter` wording with source-material ingestion method and kept derivation agent fields mandatory. -- Added missing approval provenance fields to the data model example. -- Updated loop state to point at the current internal review evidence instead of saying no evidence exists. -- Added ADR 0011 implementation enforcement contract without claiming the backend already enforces it. -- Assigned UI/demo wording proof to a later frontend/demo chunk before ADR closure. -- Added Chunk 4 schema/persistence proof that pre-submit feedback cannot store review decision values. -- Locked the default pre-submit path to constrained checker specifications and Workstream-compiled deterministic checker bundles, not unrestricted generated checker code. -- Added data model fields for `checker_spec`, `compiler_version`, `compiled_bundle_hash`, and immutable `compiled_bundle`. -- Moved compiler proof obligations to Chunk 2, where checker modules and checker tests are allowed. -- Moved task binding, `EffectiveTaskSubmissionArtifactPolicy`, task-level `PreSubmitCheckerPolicy`, transitional task-field replacement, and submission runtime migration to Chunk 3, where task/checker modules and migrations are allowed. -- Tightened future executable-checker extension requirements to require static validation, generated tests, sandbox policy checks, no network, no shell, no secrets, no database access, and `admin` or `project_manager` approval of the exact locked code hash after those checks pass. -- Corrected the checker framework response wording to match the current `PreSubmitCheckResponse` schema: `status`, `eligible_to_submit`, and `results`, with `pre_submission_checker_failed` treated as the user-facing failure condition rather than a response field. -- Corrected the external review response artifact so CodeRabbit feedback is tracked separately from internal review evidence and does not claim a nonexistent `failure_code` field in pre-submit responses. +- Removed the per-task policy/checker generation model from active docs. +- Removed `ApprovedTaskArtifactBinding`, `EffectiveTaskSubmissionArtifactPolicy`, + `ProjectPreSubmitCheckerSpec`, task-level `PreSubmitCheckerPolicy`, and + profile-scoped wording from the live architecture path. +- Restored the first-principles model: project guide, source snapshot, + sufficiency report, project submission artifact policy, effective project + policy, project `PreSubmitCheckerPolicy`, then tasks lock references to that + context. +- Documented that `ProjectGuideSufficiencyAgent` checks the project guide + against the project task set. If the guide does not cover the tasks, + activation is blocked and the guide is improved or work is split into another + project/guide. +- Removed stale submission provenance fields for task artifact binding and + effective task policy. +- Updated checker specs, templates, lifecycle docs, product flows, roadmap + docs, and packet conventions to use the project `PreSubmitCheckerPolicy`. +- Confirmed workers and clients cannot choose checker names, severities, + versions, outcomes, compiler version, or compiled bundles. ## Commands Run ```bash -python3 scripts/check_loop_memory_state.py python3 scripts/check_markdown_links.py python3 scripts/check_stale_workstream_wording.py -python3 scripts/workstream_agent_gate.py --base origin/main --head HEAD --format json -python3 scripts/check_internal_review_evidence.py +python3 scripts/check_loop_memory_state.py git diff --check +rg -n "ApprovedTaskArtifactBinding|EffectiveTaskSubmissionArtifactPolicy|ProjectPreSubmitCheckerSpec|task-level PreSubmitCheckerPolicy|task-level pre-submit|project/profile|profile-scoped|task binding|effective task submission artifact policy|effective task policy" docs README.md .agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation --glob '!**/reviews/WS-POL-001-01-internal-review-evidence.md' || true ``` ## Remaining Risks -- `WS-POL-001-01` is not approved for backend implementation yet. -- Human review should focus on persisted provenance field names and confirming Chunk 1 remains records/contracts/activation guard only. +- `WS-POL-001-01` is planning-only and is not backend implementation approval. +- Human review should confirm the corrected project-level checker model before + merge. From 28862e6693a552a8029ac10a9959c47cc989bae3 Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Thu, 25 Jun 2026 14:28:33 +0100 Subject: [PATCH 27/37] Harden submission policy planning contract --- .../CHUNK_MAP.md | 17 ++++++++ .../DECISIONS.md | 2 +- .../PLAN.md | 36 ++++++++++------ ...1-submission-artifact-policy-foundation.md | 9 +++- .../WS-POL-001-01-external-review-response.md | 6 +++ docs/architecture_checker_framework.md | 2 +- docs/architecture_data_model.md | 41 ++++++++++++++----- docs/architecture_lifecycle_state_machine.md | 4 +- docs/architecture_system_architecture.md | 2 +- docs/current_system_data_flow.html | 4 +- ...ion_0003_project_guides_are_first_class.md | 2 +- ...ssion_artifact_policy_drives_pre_submit.md | 34 +++++++++++---- docs/operations_project_operating_manual.md | 17 ++++---- docs/operations_queue_policy.md | 4 +- .../operations_workspace_packet_convention.md | 2 +- docs/principles.md | 2 +- docs/product_first_user_flows.md | 2 +- docs/roadmap_day_by_day_execution_plan.md | 4 +- docs/roadmap_week1_backend_plan.md | 2 +- docs/spec_chunk_3_project_guide_foundation.md | 7 +++- ...ec_chunk_5_submission_packet_foundation.md | 10 ++--- docs/spec_chunk_6_checker_contract_records.md | 4 +- docs/template_project_guide.md | 2 +- docs/template_submission_artifact_policy.md | 26 ++++++++++-- docs/template_submission_packet.md | 4 +- scripts/check_stale_workstream_wording.py | 12 ++++++ scripts/test_agent_gates.py | 22 ++++++++++ 27 files changed, 205 insertions(+), 74 deletions(-) diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md index 974c840..2856248 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md @@ -70,6 +70,10 @@ Acceptance criteria: - Dedicated immutable guide source snapshot bundle model/table exists. - Dedicated guide source snapshot item model/table exists, or the snapshot table stores an equivalent canonical manifest for every source item. +- `GuideSourceSnapshot.bundle_hash` is computed as + `sha256(canonical_json(manifest_json))` with deterministic key ordering, + source-item ordering, UTF-8 encoding, duplicate handling, and volatile-field + exclusions. - Dedicated guide sufficiency report model/table exists. - Guide sufficiency report supports `passed`, `blocked`, and `passed_with_warnings`. @@ -90,6 +94,9 @@ Acceptance criteria: - Guide activation requires passing or acknowledged guide sufficiency, approved submission artifact policy, and effective project policy hash bound to the current guide source snapshot. +- Chunk 1 models the future activation dependency on project + `PreSubmitCheckerPolicy`; Chunk 2 compiles the checker and enforces the + complete activation gate. - Project-owner source refs persist as sanitized snapshot item refs and cannot store signed URLs, credential-bearing refs, token-bearing refs, or local filesystem paths. Approved adapters can use ordinary URL query parameters only as @@ -168,6 +175,14 @@ Acceptance criteria: - Trusted checker compiler validates the specification and persists a deterministic project `PreSubmitCheckerPolicy` bundle and hash. The default path compiles once per project guide version, not once per task. +- Guide activation requires the compiled project `PreSubmitCheckerPolicy` once + Chunk 2 is complete. +- Compiler rejects any checker specification that omits an enforceable + effective project policy rule, weakens severity, skips an evidence rule, or + omits a Workstream default. +- Task runtime parameters come only from trusted task-contract fields and cannot + override required checks, severity, allowed storage, forbidden artifacts, hash + algorithm, or platform defaults. - Derived report, project policy, effective project policy, and pre-submit checker bundle are invalidated by a new guide source snapshot. - Malicious guide text, embedded prompt-injection instructions, and unsafe @@ -244,6 +259,8 @@ Acceptance criteria: run policy derivation or checker compilation by default. - Task-specific values are constrained parameters consumed by the locked checker bundle, not a newly generated checker policy. +- Runtime parameters are sourced only from trusted task-contract fields; no + free-form parameter map is introduced. - Transitional `required_files` and `required_evidence` are replaced for submission runtime and are not compatibility aliases. - Blocking pre-submit failure creates no submission row, submission version, diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md index 76de6b3..7641bd2 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md @@ -58,6 +58,6 @@ - Final review of persisted provenance field names for guide sufficiency reports, project submission artifact policies, effective policy hashes, and - generated pre-submit checker policy snapshots. + generated project pre-submit checker policy snapshots. - Final confirmation that Chunk 1 implements records/contracts/activation guard only, while full async agent execution comes later. diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md index f8962a9..2f444b3 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md @@ -57,12 +57,16 @@ canonical manifests, bundle hashes, opaque sanitized source refs, per-item content hashes, optional future content ids, adapter names, and capture timestamps. It never persists signed URLs, credentials, or token-bearing locators as durable source identity. +The bundle hash is `sha256(canonical_json(manifest_json))` with deterministic +key ordering, source-item ordering, UTF-8 encoding, duplicate handling, and +volatile-field exclusions. `SubmissionArtifactPolicyDerivationAgent` derives machine-readable `ProjectSubmissionArtifactPolicy` after guide sufficiency passes. A Workstream actor with the `admin` or `project_manager` role approves the derived policy. -Workstream then computes the effective project policy. The generated -`PreSubmitCheckerPolicy` snapshot/hash is scoped to the project guide version. +Workstream then computes the effective project policy and compiles the project +`PreSubmitCheckerPolicy`. The generated project `PreSubmitCheckerPolicy` +snapshot/hash is scoped to the project guide version. Tasks lock references to the exact guide snapshot, effective project policy hash, and pre-submit checker policy hash before entering `SCREENING` or `READY`. @@ -78,14 +82,20 @@ a deterministic project `PreSubmitCheckerPolicy` bundle during project setup. Runtime checks execute the locked compiled bundle against staged artifact hashes or future content identifiers plus the task's constrained parameters. Tasks do not rerun the derivation agent or compile a new checker bundle for each task. - -If no immutable guide-source snapshot, passing or acknowledged guide sufficiency -report, approved project submission artifact policy, and effective project -policy hash exist for the guide snapshot and guide version, guide activation -fails. If the applicable project pre-submit checker bundle is -missing, a task cannot enter the ready worker pipeline. The system must surface -setup failure internally as task/project setup incomplete rather than letting -workers discover missing intake rules at submit time. +The compiler must reject any specification that does not cover every enforceable +effective project policy rule. Task runtime parameters come only from trusted +task-contract fields and cannot override required checks, severity, allowed +storage, forbidden artifacts, hash algorithm, or platform defaults. + +In the final architecture, guide activation fails unless the guide snapshot and +guide version have a passing or acknowledged guide sufficiency report, approved +project submission artifact policy, effective project policy hash, and compiled +project `PreSubmitCheckerPolicy` hash. Chunk 1 creates the records and +foundational guards; Chunk 2 adds compiler execution and turns the complete +activation gate on; Chunk 3 makes tasks lock the compiled checker reference +before entering the worker pipeline. The system must surface setup failure +internally as task/project setup incomplete rather than letting workers discover +missing intake rules at submit time. Reports, derived policies, acknowledgements, effective policies, and checker bundles bind to the exact `GuideSourceSnapshot` id/hash, not only to @@ -168,7 +178,7 @@ while post-submit answers whether a locked submission can move to human review. 5. Add async guide sufficiency, policy derivation execution, and trusted checker compiler behavior. 6. Add task locked-context fields for guide snapshot, effective project policy, - and generated pre-submit checker bundle. + and generated project pre-submit checker bundle. 7. Migrate submission creation from transitional task fields to the locked task context and generated project pre-submit checker bundle. 8. Split post-submit checker policy naming/provenance. @@ -183,7 +193,7 @@ while post-submit answers whether a locked submission can move to human review. sufficiency bound to the current source snapshot, approved project submission artifact policy, and effective project policy hash. - Tests proving a task cannot enter `READY` without locked guide snapshot, - effective project policy hash, and generated pre-submit checker bundle. + effective project policy hash, and generated project pre-submit checker bundle. - Tests proving malicious or credential-bearing source material cannot weaken Workstream defaults, grant tool authority, or persist unsafe source refs. - Submission API tests proving blocking pre-submit failure creates no submission @@ -211,5 +221,5 @@ CI integrity is required only for chunks that touch workflows or test tooling. Start with guide/source/policy bundle foundation. Do not start submission runtime rewiring until immutable guide-source snapshots, guide sufficiency reports, project policy objects, defaults, effective project policy hash, -generated pre-submit checker bundle, task locked-context fields, and +generated project pre-submit checker bundle, task locked-context fields, and activation/ready guards are accepted. diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md index ede8e7b..adc7294 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-01-submission-artifact-policy-foundation.md @@ -25,7 +25,7 @@ guide-source snapshots, guide sufficiency, project submission artifact policy, effective project policy hash, and a Workstream actor with the `admin` or `project_manager` role approves the bundle before guide activation. -The generated pre-submit checker policy is deterministic compiled policy, not +The generated project pre-submit checker policy is deterministic compiled policy, not unrestricted generated checker code. This first chunk defines the record contract and activation dependency; the async derivation and trusted compiler behavior land in the next chunk. @@ -96,6 +96,10 @@ human review implementation - [ ] Dedicated immutable `GuideSourceSnapshot` bundle model/table exists. - [ ] Dedicated `GuideSourceSnapshotItem` model/table exists, or the snapshot stores an equivalent canonical manifest for every source item. +- [ ] `GuideSourceSnapshot.bundle_hash` is computed as + `sha256(canonical_json(manifest_json))` using UTF-8, sorted object keys, + no insignificant whitespace, deterministic source-item ordering, + volatile-field exclusions, and duplicate source-item rejection. - [ ] Dedicated `GuideSufficiencyReport` model/table exists. - [ ] Guide sufficiency report records `passed`, `blocked`, or `passed_with_warnings`. @@ -125,6 +129,9 @@ human review implementation - [ ] Guide activation fails when no approved project submission artifact policy exists for the guide version. - [ ] Guide activation requires valid submission artifact policy. +- [ ] The activation contract models project `PreSubmitCheckerPolicy` as a + required final activation dependency; Chunk 2 enforces it after compiler + execution exists. - [ ] Workstream default submission artifact policy is represented in code. - [ ] Workstream default policy requires `sha256:<64 lowercase hex>` artifact hashes where production hashes are required. - [ ] Persisted artifact/storage refs reject raw signed URLs, query strings, diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md index bc2b39e..c22defe 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-01-external-review-response.md @@ -42,6 +42,12 @@ Internal sub-agent results live in | Human review | `GuideSourceSnapshot` looked like a single source ref instead of a guide material bundle. | High | Fixed | Updated the data model, ADR, plan, chunk map, chunk contract, and template to model `GuideSourceSnapshot` as a canonical manifest bundle with per-item source records and a bundle hash. | | Human review | Remaining schema details were ambiguous: size fields, hash algorithm, dual status fields, and source snapshot hash consistency. | High | Fixed | Added `maximum_file_size_bytes` and `maximum_package_size_bytes`, locked `artifact_hash_algorithm` to platform `sha256`, normalized policy lifecycle to `lifecycle_status`, and documented `source_snapshot_hash` as server-derived from the snapshot bundle hash. | | Human review | New guide snapshots needed an explicit fairness boundary for already locked tasks. | High | Fixed | Added the protective rule: a new guide-source snapshot invalidates setup records for new activation and unlocked tasks only; already locked tasks retain their context unless explicitly rebased through audit. | +| Human review | Rejected per-task policy fields still appeared in the Chunk 5 submission spec. | High | Fixed | Removed the stale task-binding and task-effective-policy provenance fields; submissions now keep only project-scoped locked policy/checker provenance. | +| Human review | Chunk wording still allowed project checker generation to be read as task-scoped. | High | Fixed | Normalized active docs to say generated project pre-submit checker policy/bundle and expanded the stale-model scan to include snake-case per-task-policy terms. | +| Human review | Final activation boundary needed to be explicit. | High | Fixed | Locked the final architecture: guide activation requires a compiled project `PreSubmitCheckerPolicy`; Chunk 2 turns that complete activation gate on after compiler execution exists. | +| Human review | Bundle hash canonicalization was under-specified. | High | Fixed | Added `sha256(canonical_json(manifest_json))` with UTF-8, sorted keys, deterministic source-item ordering, volatile-field exclusions, and duplicate source item rejection. | +| Human review | Checker compiler needed a semantic completeness invariant. | High | Fixed | Added the requirement that every enforceable effective project policy rule must produce deterministic checker logic, and the compiler must reject omitted rules, weakened severity, skipped evidence rules, missing platform defaults, or untraceable bundle rules. | +| Human review | Task-specific runtime parameters could become a hidden per-task policy channel. | High | Fixed | Constrained v0.1 runtime parameters to trusted task-contract fields only; no free-form parameter map is allowed and parameters cannot override checks, severity, storage, forbidden artifacts, hash algorithm, or platform defaults. | ## Commands To Re-Run After Push diff --git a/docs/architecture_checker_framework.md b/docs/architecture_checker_framework.md index 620a89c..cb40448 100644 --- a/docs/architecture_checker_framework.md +++ b/docs/architecture_checker_framework.md @@ -71,7 +71,7 @@ Default: - medium-severity `failed` result creates reviewer warning - low-severity `failed` result creates informational note -Approved machine policies can declare stricter blocking behavior. `SubmissionArtifactPolicy` and generated `PreSubmitCheckerPolicy` govern pre-submit artifact rules. `PostSubmitCheckerPolicy` governs durable post-submit checker blocking. +Approved machine policies can declare stricter blocking behavior. `SubmissionArtifactPolicy` and generated project `PreSubmitCheckerPolicy` govern pre-submit artifact rules. `PostSubmitCheckerPolicy` governs durable post-submit checker blocking. Project policy cannot weaken Workstream default submission artifact rules. Workstream defaults are applied before project policy. A project policy that attempts to require a forbidden artifact, remove hash requirements, allow credential-bearing storage references, or downgrade blocking defaults is a project setup defect. diff --git a/docs/architecture_data_model.md b/docs/architecture_data_model.md index 4a201a8..a7b13e3 100644 --- a/docs/architecture_data_model.md +++ b/docs/architecture_data_model.md @@ -201,9 +201,19 @@ trust a mutable URL or mutable draft guide body. They bind to `source_snapshot_id` and a server-derived `source_snapshot_hash` copied from `GuideSourceSnapshot.bundle_hash`. -`bundle_hash` is the canonical hash of the manifest plus every included source -item hash. Changing any included document, example, rubric, repository doc, or -inline guide body creates a new snapshot and bundle hash. +`bundle_hash` is: + +```text +sha256(canonical_json(manifest_json)) +``` + +Canonical JSON uses UTF-8, sorted object keys, no insignificant whitespace, and +source items sorted by `(source_kind, durable_ref, content_hash)`. Volatile +database ids, capture timestamps, and transient fetch locators are excluded from +the canonical manifest. Duplicate source items with the same +`source_kind + durable_ref` are rejected before hashing. Changing any included +document, example, rubric, repository doc, or inline guide body creates a new +snapshot and bundle hash. ## GuideSourceSnapshotItem @@ -359,8 +369,8 @@ sufficiency passes or warnings are acknowledged. A Workstream actor with the supply or approve this internal policy schema. Project policy can add stricter requirements, but it cannot weaken Workstream's default submission artifact policy. -`artifact_hash_algorithm` is platform-locked to `sha256` for v0.1. Project and -task policies cannot change it. +`artifact_hash_algorithm` is platform-locked to `sha256` for v0.1. Project +policy cannot change it, and trusted task runtime parameters cannot override it. `source_snapshot_hash` is server-derived from the referenced snapshot bundle hash. @@ -422,7 +432,7 @@ The merge contract is executable per field: | `artifact_manifest_required` | logical OR | | `artifact_hash_required` | logical OR | | `allowed_storage_schemes` | intersection | -| `artifact_hash_algorithm` | platform-locked `sha256`; project/task policy cannot change it | +| `artifact_hash_algorithm` | platform-locked `sha256`; project policy cannot change it and task runtime parameters cannot override it | | `maximum_file_size_bytes` | minimum non-null limit | | `maximum_package_size_bytes` | minimum non-null limit | | `packaging_rules` | restrictive merge; conflicts block activation | @@ -475,9 +485,18 @@ code. `compiled_bundle_hash` binds the exact compiled logic to `checker_configs`, and `blocking_severities` are derived index projections only; they must be regenerated from `compiled_bundle` and must not disagree with it. -Task-specific values, such as expected output path or task id, are constrained -runtime parameters consumed by the locked checker bundle. They are not new -policy derivation and do not create a new checker bundle. +The compiler must prove semantic coverage: every enforceable +`EffectiveProjectSubmissionArtifactPolicy` rule must produce deterministic +checker logic. It rejects checker specifications that omit a required artifact, +skip an evidence rule, weaken severity, omit a platform default, or produce a +bundle whose rules are not traceable back to the effective project policy. + +For v0.1, task-specific runtime parameters come only from trusted task-contract +fields already owned by Workstream, such as task id, expected output, declared +artifact labels, or acceptance criteria references. There is no free-form +parameter map. Runtime parameters may fill placeholders in the locked checker +bundle, but they cannot change required checks, severity, allowed storage, +forbidden artifacts, hash algorithm, or platform defaults. Approved and superseded checker policy rows are immutable. Changing policy or compiler output creates a new row with `supersedes_policy_id`. @@ -535,7 +554,7 @@ Example: } ``` -Post-submit checker policy governs durable internal checker runs after a submission is locked. It does not replace the generated pre-submit checker policy. +Post-submit checker policy governs durable internal checker runs after a submission is locked. It does not replace the generated project pre-submit checker policy. ## ReviewPolicy @@ -682,7 +701,7 @@ External origin adapters are later work. When added, they normalize into this ta The task id points to the locked task contract. That contract includes the guide version, guide source snapshot hash, project submission artifact policy version, -effective project policy hash, generated pre-submit checker policy hash, +effective project policy hash, generated project pre-submit checker policy hash, post-submit checker policy version, review policy version, revision policy version, payment policy version, acceptance criteria, derived display summaries, base payout, and skill tags. Workers submit against the task id; they do not diff --git a/docs/architecture_lifecycle_state_machine.md b/docs/architecture_lifecycle_state_machine.md index e43fab0..828efbf 100644 --- a/docs/architecture_lifecycle_state_machine.md +++ b/docs/architecture_lifecycle_state_machine.md @@ -48,7 +48,7 @@ Required before leaving: ### SCREENING -The task is structurally prepared but not yet released. This is the pre-release quality gate used to catch weak guides, vague acceptance criteria, missing submission artifact requirements, bad payment policy, missing generated pre-submit checker policy, missing post-submit checker policy, missing review policy, or missing revision policy before workers see the task. +The task is structurally prepared but not yet released. This is the pre-release quality gate used to catch weak guides, vague acceptance criteria, missing submission artifact requirements, bad payment policy, missing generated project pre-submit checker policy, missing post-submit checker policy, missing review policy, or missing revision policy before workers see the task. Required before entering: @@ -104,7 +104,7 @@ Required before entering: - package or output reference - evidence items - effective project submission artifact policy loaded -- generated pre-submit checker policy executed +- generated project pre-submit checker policy executed - no blocking pre-submit failures - immutable submission version - content hash for every uploaded artifact diff --git a/docs/architecture_system_architecture.md b/docs/architecture_system_architecture.md index 3fb13e3..32fa1e4 100644 --- a/docs/architecture_system_architecture.md +++ b/docs/architecture_system_architecture.md @@ -102,7 +102,7 @@ Owns: - guide - base payout - submission artifact policy -- generated pre-submit checker policy +- generated project pre-submit checker policy - post-submit checker policy - review policy - revision policy diff --git a/docs/current_system_data_flow.html b/docs/current_system_data_flow.html index 4b793a1..a17f158 100644 --- a/docs/current_system_data_flow.html +++ b/docs/current_system_data_flow.html @@ -515,7 +515,7 @@

Worker claims and starts

6

Pre-submit intake checks run

-

Workstream runs generated pre-submit checks from the locked project pre-submit checker policy before creating a submission row. Preflight failures return PreSubmitCheckResponse details. Blocked submission-create attempts return pre_submission_checker_failed with pass/fail/warning details.

+

Workstream runs pre-submit checks from the locked project pre-submit checker policy before creating a submission row. Preflight failures return PreSubmitCheckResponse details. Blocked submission-create attempts return pre_submission_checker_failed with pass/fail/warning details.

no submission yet no checker run yet @@ -628,7 +628,7 @@

Durable Records Created Along The Way