diff --git a/.agent-loop/LOOP_STATE.md b/.agent-loop/LOOP_STATE.md index 12d1a6a..945b33c 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: planning review ready; implementation has not started +- Merge commit: none for this initiative +- Reviewed code SHA: `8b51a84b1bede193bbafe0b1eeb7b7981a271a0e` +- Current gate: awaiting human planning approval and PR merge decision; backend implementation is not approved +- Next chunk: inactive until `WS-POL-001-01` is approved and completed ## Operating Rule @@ -19,14 +19,16 @@ 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 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/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..48c957a --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md @@ -0,0 +1,437 @@ +# 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. +- Project guides are open-ended project material. Workstream uses async + `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. +- 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 locked + references, and checker bundles bind to immutable `GuideSourceSnapshot` + bundle id/hash, not only to `guide_version`. + +## Chunks + +### WS-POL-001-01: Guide Policy Bundle Foundation + +Goal: + +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: + +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 +full async agent execution runtime +``` + +Acceptance criteria: + +- Dedicated submission artifact policy 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. +- `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`. +- Project policy is scoped to project id + guide version. +- Guide sufficiency report, project policy, and effective project policy bind to + `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. +- 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 project submission artifact policy hash is persisted for the guide version. +- 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, and effective project submission artifact 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 + temporary fetch locators. +- Embedded instructions in guide material cannot grant tool authority or weaken + Workstream default policy. +- Legacy `evidence_policy`, `required_files`, and `required_evidence` are not + treated as compatibility contracts. Runtime removal happens in the task + locked-context and submission migration chunk. + +Verification: + +- Postgres-backed FastAPI/API tests cover policy create/update, guide + sufficiency activation blocking, warning acknowledgement, default weakening + rejection, source snapshot binding, source-ref sanitization, append-only + approved rows, and effective project submission artifact policy hash persistence. +- 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, +reuse/dedup, test delta. + +Human review focus: + +Guide sufficiency report fields, persisted provenance field names, and keeping +Chunk 1 limited to records/contracts/activation guards. + +### WS-POL-001-02: Async Guide Analysis And Policy Derivation + +Goal: + +Run `ProjectGuideSufficiencyAgent`, +`SubmissionArtifactPolicyDerivationAgent`, and project pre-submit +checker compilation asynchronously against immutable guide-source snapshots. + +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: + +- `ProjectGuideSufficiencyAgent` runs async and produces a persisted + 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`. +- `SubmissionArtifactPolicyDerivationAgent` runs async after sufficiency passes + or warnings are acknowledged. +- Derived policy cannot weaken Workstream defaults. +- `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. +- 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 + 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 + 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. +- Compiler semantic rejection tests prove omitted required artifact coverage, + skipped evidence coverage, weakened severity, omitted Workstream defaults, and + untraceable compiled bundle rules are rejected. + +Required reviewers: + +senior engineering, QA/test, security/auth, product/ops, architecture, docs, +reuse/dedup, test delta. + +Human review focus: + +Async job boundaries, sufficiency severity behavior, and clarification request +shape. + +### WS-POL-001-03: Task Locked Context And Submission Creation + +Goal: + +Lock each task to the applicable guide snapshot, effective project submission artifact policy hash, +and project pre-submit checker bundle. Move submission creation from +transitional task fields to that locked context. + +Risk: + +L1 + +Depends on: + +`WS-POL-001-02` + +Allowed files: + +```text +backend/alembic/versions/** +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: + +- Tasks lock `locked_guide_source_snapshot_id`, + `locked_guide_source_snapshot_hash`, + `locked_effective_project_submission_artifact_policy_hash`, + and `locked_pre_submit_checker_bundle_hash` during screening before `READY`. +- Every task under the same active project guide version shares that guide + version's project `PreSubmitCheckerPolicy`; tasks do not run policy + derivation or checker compilation. +- If a guide version does not cover the task set, activation is blocked and the + guide is improved or the work is split into another project/guide. +- 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, + submitted transition, or durable checker run. +- `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: + +- 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 locked context stamping, shared checker reuse + for every task under the same active project guide version, blocked activation + for uncovered task sets, and removal of transitional task-field authority. +- API/schema negative tests reject client-supplied free-form task runtime + parameter maps and attempted runtime overrides of required checks, severity, + allowed storage, forbidden artifacts, hash algorithm, or platform defaults. + +Required reviewers: + +senior engineering, QA/test, security/auth, product/ops, architecture, docs, +reuse/dedup, test delta. + +Human review focus: + +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 + +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. +- 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: + +- 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. + +Required reviewers: + +senior engineering, QA/test, security/auth, product/ops, architecture, docs, +reuse/dedup, test delta. + +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. +- 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 + +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. + +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, +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..be26844 --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DECISIONS.md @@ -0,0 +1,63 @@ +# Decisions: WS-POL-001 - Submission Artifact Policy Foundation + +## 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 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. +- `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. +- `EffectiveProjectSubmissionArtifactPolicy` is default plus project policy. +- Workstream's trusted checker compiler turns the constrained checker + specification into deterministic project-scoped `PreSubmitCheckerPolicy`. +- Tasks lock the applicable guide snapshot, effective project submission artifact policy hash, + and pre-submit checker bundle 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 + 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 + `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. + +## Accepted Defaults + +- 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>` 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 + `node_modules`. + +## Remaining Human Review Focus + +- Final review of persisted provenance field names for guide sufficiency + reports, project submission artifact policies, effective project submission artifact policy hashes, and + generated project pre-submit checker compiled bundle hashes. +- 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 new file mode 100644 index 0000000..d81e540 --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/DISCOVERY.md @@ -0,0 +1,98 @@ +# 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 +-> GuideSufficiencyReport +-> EffectiveProjectSubmissionArtifactPolicy +-> persisted project PreSubmitCheckerPolicy +-> tasks lock project policy/checker references +-> 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. + +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 + +| 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. | +| 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. | +| 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 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 + +- 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..c61a75d --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md @@ -0,0 +1,168 @@ +# 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. +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 +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 + +Project owner material +-> ProjectGuideSufficiencyAgent +-> SubmissionArtifactPolicyDerivationAgent +-> Workstream-derived ProjectSubmissionArtifactPolicy +-> approval by admin or project_manager + +WorkstreamDefaultSubmissionArtifactPolicy ++ ProjectSubmissionArtifactPolicy += EffectiveProjectSubmissionArtifactPolicy + +EffectiveProjectSubmissionArtifactPolicy +-> trusted Workstream checker compiler +-> persisted project PreSubmitCheckerPolicy + +Task +-> locks guide snapshot +-> locks effective project submission artifact policy hash +-> locks PreSubmitCheckerPolicy compiled bundle hash +``` + +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. + +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 +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 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 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. + +Every task under the same active project guide version reuses that guide +version's compiled project 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: + +- 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. +- `SubmissionArtifactPolicy` is Workstream-derived from project material and + 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 bundle 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 project submission artifact policy is computed deterministically. +- Generated pre-submit checker policy is persisted at project scope and tasks + lock its compiled bundle hash during screening before entering `READY`. +- 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. +- 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. + +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 + +- Approve the chunk sequence before implementation. +- 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 + +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..ee5fbc9 --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md @@ -0,0 +1,225 @@ +# Plan: WS-POL-001 - Submission Artifact Policy Foundation + +## Proposed Approach + +Implement policy-driven submission intake in narrow slices. + +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 + +The product model is: + +```text +ProjectGuide + open-ended human-facing project material + +GuideSourceSnapshot + immutable bundle manifest for the exact guide/source material Workstream evaluated + +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 + +EffectiveProjectSubmissionArtifactPolicy + deterministic merge of default + project policy + +PreSubmitCheckerPolicy + persisted project checker rules for draft packet intake + +PostSubmitCheckerPolicy + durable checker rules for locked submission review readiness +``` + +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. + +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. 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 +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 submission artifact policy and compiles the project +`PreSubmitCheckerPolicy`. The generated project `PreSubmitCheckerPolicy` +compiled bundle hash is scoped to the project guide version. +Tasks lock references to the exact guide snapshot, effective project submission +artifact policy hash, and pre-submit checker bundle hash during screening before +entering `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 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. +The compiler must reject any specification that does not cover every enforceable +effective project submission artifact 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 submission artifact policy hash, and project +`PreSubmitCheckerPolicy` compiled bundle 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 +`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 + +### Keep using guide prose and task fields + +Rejected because it leaves too much room for project drift and unfair worker +feedback. + +### 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 +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. + +### 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. + +### 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, +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: 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 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, 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. +- CI/deployment: no workflow weakening. + +## Rollout/Migration Strategy + +1. Add dedicated guide source snapshot, guide sufficiency, submission artifact + policy, and effective project submission artifact 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 project submission artifact policy in service code and validate defaults cannot weaken. +5. Add async guide sufficiency, policy derivation execution, and trusted checker + compiler behavior. +6. Add task locked-context fields for guide snapshot, effective project submission artifact policy, + 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. + +## Verification Strategy + +- 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 submission artifact 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 submission artifact policy hash. +- Tests proving a task cannot enter `READY` without locked guide snapshot, + effective project submission artifact 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 + 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 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 submission artifact policy hash, +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/RISKS.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/RISKS.md new file mode 100644 index 0000000..6af01b9 --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/RISKS.md @@ -0,0 +1,12 @@ +# 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. | +| 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. | +| 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 new file mode 100644 index 0000000..94bb4de --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md @@ -0,0 +1,35 @@ +# Status: WS-POL-001 - Submission Artifact Policy Foundation + +## Current Status + +Planning review is ready, and latest internal and external review feedback has +been addressed. +Implementation has not started. + +## Active Chunk + +`WS-POL-001-01` is pending human planning approval. Implementation has not started. + +## Chunk Status + +| Chunk | Status | Branch | PR | Notes | +|---|---|---|---:|---| +| `WS-POL-001-01` | Awaiting human planning approval | `codex/submission-artifact-policy-loop-plan` | 26 | Internal review complete; 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. | +| `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 PR #26 and decide whether to merge. | + +## Follow-Ups + +| Item | Source | Priority | +|---|---|---| +| 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 new file mode 100644 index 0000000..1401469 --- /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,242 @@ +# Chunk Contract: WS-POL-001-01 - Guide Policy Bundle Foundation + +## Parent Initiative + +WS-POL-001 - Submission Artifact Policy Foundation + +## Goal + +Add first-class backend support for immutable guide-source snapshots, guide +sufficiency reports, `SubmissionArtifactPolicy`, effective project submission +artifact 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 + +The code still uses transitional `evidence_policy`, `required_files`, and +`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 open-ended project guide material. Workstream records +guide-source snapshots, guide sufficiency, project submission artifact policy, +effective project submission artifact policy hash, and a Workstream actor with +the `admin` or `project_manager` role approves the bundle before guide +activation. + +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. + +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` bundle with a canonical manifest, sanitized +source item refs, and per-item content hashes. + +## 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` + +## Current Planning PR Scope + +PR #26 is the planning approval PR for this initiative. It may update the +initiative plan, chunk map, architecture docs, operating docs, templates, and +engineering-loop gates needed to make the implementation contract unambiguous. + +The implementation scope below applies after this planning PR is approved. It +does not authorize runtime product behavior in the planning PR, and it does not +require the planning PR to be limited to backend implementation files. + +Planning PR scope exceptions: + +- `.agent-loop/**` +- `docs/**` +- `scripts/check_stale_workstream_wording.py` +- `scripts/test_agent_gates.py` + +Planning PR non-scope: + +- product runtime behavior +- database schema changes +- API behavior changes +- frontend/demo changes +- workflow/dependency changes +- payment, reputation, settlement, or blockchain code + +## Risk Class + +L1 + +## SLA + +P1 + +## Implementation 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/** +``` + +## Implementation 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 + 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. +- 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` 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`. +- [ ] 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 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 + 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 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, + 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. +- [ ] 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, + 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 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 project submission artifact policy hash is persisted for the guide version. +- [ ] 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 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, + source snapshot binding, source-ref sanitization, append-only rows, and + effective project submission artifact policy hash persistence. + +## 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 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, trusted compiler behavior, task locked context, and + submission runtime migration for later chunks? + +## Stop Conditions + +Stop and escalate if: + +- implementation needs to touch task/submission/checker runtime in this chunk +- policy version/hash naming is unclear +- 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/.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..7803100 --- /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,83 @@ +# External Review Response: WS-POL-001-01 + +## PR + +https://github.com/Flow-Research/workstream/pull/26 + +## Chunk + +`WS-POL-001-01` + +## Source + +CodeRabbit, GitHub checks, and human PR review. + +## Summary + +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 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 project checker compiled bundle provenance. Tasks lock the project checker bundle 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 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 | 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 bundle 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. | +| 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. | +| CodeRabbit | Some docs still referenced guide version, shortened policy hash names, or generic policy names where immutable guide-source snapshot and effective project submission artifact policy were required. | Minor | Fixed | Updated first-user flow, chunk map, chunk contract, lifecycle, and roadmap wording to use immutable guide-source snapshot, `SubmissionArtifactPolicy`, and effective project submission artifact policy hash consistently. | +| CodeRabbit | Source snapshot item Markdown table used raw pipe characters inside the source-kind placeholder. | Minor | Fixed | Replaced pipe separators with slash separators so the table remains valid Markdown. | +| CodeRabbit | Rejected-model stale-wording patterns for PascalCase symbols were case-sensitive. | Minor | Fixed | Made the relevant stale-wording regexes case-insensitive while preserving the existing regression test coverage. | +| Human review | `SCREENING -> READY` operations docs omitted guide source snapshot id/hash, effective project submission artifact policy hash, and pre-submit checker bundle hash. | High | Fixed | Updated queue policy and task locked-context docs so `READY` requires those locked references before workers see tasks. | +| Human review | The planning PR scope was easy to confuse with the later backend implementation chunk scope. | High | Fixed | Added explicit planning PR scope exceptions and renamed future backend scope headings to implementation allowed/not-allowed files. | +| Human review | "Most tasks" wording left a loophole for task-specific checker generation. | High | Fixed | Changed the contract to every task under the same active project guide version reusing that guide version's project `PreSubmitCheckerPolicy`; uncovered task sets block activation or split into another project/guide. | +| Human review | Submission packet provenance omitted locked guide-source snapshot id/hash and effective project submission artifact policy hash. | Medium | Fixed | Updated the submission packet template and submission spec provenance to include server-derived guide-source snapshot id/hash, effective project submission artifact policy hash, and checker bundle hash. | +| Human review | Checker docs still described `check_evidence_present` reading `task.required_evidence`. | Medium | Fixed | Updated the checker spec so evidence requirements come from the locked project `PreSubmitCheckerPolicy` and effective project submission artifact policy. | +| Human review | Activation summaries omitted immutable guide-source snapshot in local lists. | Medium | Fixed | Updated architecture lockdown, operating manual, data flow, and queue docs to include immutable guide-source snapshot in activation and readiness gates. | +| Human review | Project setup checklist marked guide active before the full activation bundle. | Low | Fixed | Reordered the checklist so guide activation follows sufficiency, approved policy, effective project submission artifact policy hash, generated checker, checker bundle hash, post-submit checker, review, revision, payment, and reviewer setup. | +| Internal review | Final reviewer pass recorded low residual risks but no blockers. | Low | Documented | Internal evidence records exact reviewed SHA, reviewer run IDs, local proof commands, and residual risks separately from external review response. | + +## Commands To Re-Run After Push + +```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 +python3 scripts/test_agent_gates.py +git diff --check +``` + +## Final External Review State + +```text +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, agent gate tests, 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 new file mode 100644 index 0000000..addf951 --- /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,92 @@ +# 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: 8b51a84b1bede193bbafe0b1eeb7b7981a271a0e + +Reviewed at: 2026-06-26T21:22:31Z + +Reviewer run IDs: 019f05c6-67db-7650-9f9e-d7313cfa3969, 019f05c6-6e02-7ca2-8d2f-1881c51ffd71, 019f05c6-71c2-7cc0-b86b-cab012596f23, 019f05c6-755b-7892-b9d3-cbd5a5bffdd6, 019f05c6-7d33-7af0-bbdf-340ff8ad6634, 019f05c6-848e-7b22-9405-1ee70f67ae55, 019f05c9-2556-7730-bed9-6d21ebf9fb20, 019f05cc-a82a-7d90-8277-2e13d0417252, 019f05cc-aa78-7ee0-922c-be066be11538 + +After reviewed SHA `8b51a84b1bede193bbafe0b1eeb7b7981a271a0e`, only review evidence, initiative status, and loop state changed. + +## Reviewer Results + +| Reviewer | Result | Blocking findings | Notes | +|---|---:|---|---| +| senior engineering | PASS WITH LOW RISKS | None | Confirmed planning-vs-implementation separation, project-scoped `PreSubmitCheckerPolicy`, no per-task checker generation, `locked_pre_submit_checker_bundle_hash` as compiled bundle hash, and activation/READY boundaries. Low risk: some summary docs omit the word compiled while canonical docs are explicit. | +| QA/test | PASS WITH LOW RISKS | None | Confirmed project-guide-version checker reuse, blocked/split uncovered task sets, activation/READY locks, submission provenance, and strengthened stale-wording tests. Low risk: archived internal review docs intentionally preserve old target wording. | +| security/auth | PASS WITH LOW RISKS | None | Confirmed immutable guide-source bundle, server-derived source snapshot hash, append-only approved rows, non-weakening defaults, locked compiled bundle hash, constrained runtime parameters, and narrow stale-wording skip. Low risk: one plan sentence uses shortened sufficiency wording while chunk/data contracts include warning acknowledgement. | +| product/ops | PASS WITH LOW RISKS | None | Confirmed project-owner boundary, setup checklist, activation/READY gates, pre-submit failure separation from review decisions, and no per-task checker generation. Low risk: setup checklist ordering is acceptable but could be polished later. | +| architecture | PASS WITH LOW RISKS | None | Confirmed no boundary violation, project/guide-version-scoped checker bundle, immutable `GuideSourceSnapshot`, chunk separation, and no hidden per-task policy channel. Low risk: runtime enforcement is future work by design. | +| ci integrity | PASS WITH LOW RISKS | None | Confirmed no workflow/package weakening, exact reviewer result parsing, reviewed-SHA binding, narrow stale-wording skip, and fail-closed agent gate behavior when `--fail-on-high` is used. Low risk: the default PR workflow keeps the static agent gate advisory, unchanged from main. | +| docs | PASS WITH LOW RISKS | None | Confirmed docs/templates cover guide-source snapshot id/hash, `locked_pre_submit_checker_bundle_hash`, pre-submit failure API contract, and product/engineering loop separation. Medium human-review risk remains only PR breadth. | +| reuse/dedup | PASS WITH LOW RISKS | None | Confirmed no duplicate task-owned policy/checker path, internal/external review separation, and one implementation table path for `SubmissionArtifactPolicy`. Low risk: `SubmissionArtifactPolicy` and `ProjectSubmissionArtifactPolicy` wording must stay explicit during implementation. | +| test delta | PASS | None | Confirmed tests were strengthened, no assertions were weakened, stale-wording coverage is additive, exact reviewer-result tests remain active, and reviewed-SHA binding remains covered. | + +## Valid Findings Addressed + +- Removed rejected per-task policy/checker generation from active contracts. +- Locked the project-guide-version model: every task under the same active guide + version reuses that guide version's project `PreSubmitCheckerPolicy`; uncovered + task sets block activation or are split into another project/guide. +- Clarified that `locked_pre_submit_checker_bundle_hash` means + `PreSubmitCheckerPolicy.compiled_bundle_hash`, not a generic policy hash. +- Added immutable `GuideSourceSnapshot` bundle semantics with canonical + manifest hash, source item refs, server-derived source hash, and activation + invalidation rules. +- Added project activation and task `READY` gates requiring guide-source + snapshot id/hash, effective project submission artifact policy hash, and + project pre-submit checker bundle hash. +- Updated submission packet provenance to include locked guide-source snapshot + id/hash, effective project submission artifact policy hash, and checker bundle + hash from server-owned task context. +- Replaced stale target wording that read from `task.required_evidence` with the + locked project `PreSubmitCheckerPolicy` and effective project submission + artifact policy path. +- Documented that this PR is planning approval only. Runtime product behavior, + schema/API changes, and frontend changes remain out of scope until the + implementation chunk is approved. +- Expanded stale-wording guard coverage for rejected per-task policy/checker + names and narrowed the historical-review skip to `docs/internal_reviews/`. +- Preserved separation between internal sub-agent evidence and external + CodeRabbit/GitHub/human review response artifacts. + +## Commands Run + +```bash +python3 scripts/check_markdown_links.py +python3 scripts/check_stale_workstream_wording.py +python3 scripts/test_agent_gates.py +python3 scripts/check_loop_memory_state.py +python3 scripts/workstream_agent_gate.py --base origin/main --head HEAD --format json +git diff --check +``` + +## Results + +```text +Markdown link check passed for 41 changed Markdown files. +Stale wording check passed. +25 agent gate tests passed. +Loop memory state check passed. +git diff --check passed. +Agent gate result: REVIEW_REQUIRED because this planning PR is large and touches risk-sensitive policy/spec/test-gate files. +``` + +## Remaining Risks + +- `WS-POL-001-01` is planning-only and is not backend implementation approval. +- Runtime enforcement remains for later chunks, especially compiler execution, + task locked-context persistence, and submission runtime migration. +- Human review must accept the large planning PR breadth before merge. +- Historical review archives under `docs/internal_reviews/` intentionally + preserve old wording and are skipped by the stale-wording scan. diff --git a/docs/architecture_checker_framework.md b/docs/architecture_checker_framework.md index 49d62bd..fa9f0e4 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. @@ -101,11 +101,12 @@ 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 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 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: @@ -163,14 +164,27 @@ The deterministic chain is: ```text ProjectGuide +-> GuideSourceSnapshot +-> GuideSufficiencyReport -> ProjectSubmissionArtifactPolicy --> EffectiveSubmissionArtifactPolicy +-> EffectiveProjectSubmissionArtifactPolicy +-> trusted Workstream checker compiler -> PreSubmitCheckerPolicy -> pre-submit intake checks -> 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 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: @@ -185,7 +199,39 @@ 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 project `PreSubmitCheckerPolicy` is persisted with a compiled +bundle hash and locked to the effective project submission artifact policy before tasks enter the +worker pipeline. Tasks lock references to the shared project's compiled checker +bundle 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 +`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`, +`needs_revision`, or `reject`. + +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` +- `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, +`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. @@ -214,8 +260,8 @@ Examples: ```text Draft packet -> load locked task context --> compute EffectiveSubmissionArtifactPolicy --> generate PreSubmitCheckerPolicy +-> load locked EffectiveProjectSubmissionArtifactPolicy hash +-> load locked PreSubmitCheckerPolicy compiled bundle 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 02f7ac6..ddc96ac 100644 --- a/docs/architecture_data_model.md +++ b/docs/architecture_data_model.md @@ -13,8 +13,11 @@ Actor Project ProjectGuide + GuideSourceSnapshot + GuideSourceSnapshotItem + GuideSufficiencyReport SubmissionArtifactPolicy - EffectiveSubmissionArtifactPolicy + EffectiveProjectSubmissionArtifactPolicy PreSubmitCheckerPolicy PostSubmitCheckerPolicy ReviewPolicy @@ -149,19 +152,145 @@ 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 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. 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. 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 the locked `PreSubmitCheckerPolicy` generated from `EffectiveProjectSubmissionArtifactPolicy`, not by project guide fields. + +## GuideSourceSnapshot + +Fields: + +- `id` +- `project_id` +- `guide_id` +- `guide_version` +- `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: + +```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 + +Fields: + +- `id` +- `source_snapshot_id` +- `source_kind` +- `durable_ref` +- `ingestion_adapter` +- `content_hash` +- `content_cid` (future Flow Node binding) +- `media_type` +- `captured_at` + +`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: + +- 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. +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 + +Fields: + +- `id` +- `project_id` +- `guide_version` +- `source_snapshot_id` +- `source_snapshot_hash` +- `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: -Implementation note: `ProjectGuide.required_submission_fields` is a legacy display summary. Submission validity is enforced by `EffectiveSubmissionArtifactPolicy`, not by project guide fields. +- `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. + +`source_snapshot_hash` is server-derived from the referenced +`GuideSourceSnapshot.bundle_hash`. Clients cannot supply a conflicting hash. ## SubmissionArtifactPolicy @@ -170,19 +299,32 @@ Fields: - `id` - `project_id` - `guide_version` +- `source_snapshot_id` +- `source_snapshot_hash` - `version` +- `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` - `packaging_rules` - `created_by` +- `sufficiency_report_id` +- `derivation_agent_name` +- `derivation_agent_version` +- `source_material_refs` +- `approved_policy_hash` +- `approved_by_role` - `approved_by` +- `approved_at` - `created_at` +- `supersedes_policy_id` Example: @@ -202,19 +344,48 @@ 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"], + "lifecycle_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": { "archive_required": true } } ``` -Project admins approve this policy. 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. +`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. -## 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: @@ -225,34 +396,117 @@ WorkstreamDefaultSubmissionArtifactPolicy Fields: +- `id` - `project_id` - `guide_version` +- `source_snapshot_id` +- `source_snapshot_hash` +- `version` +- `lifecycle_status` - `policy_hash` +- `source_project_policy_hash` - `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` +- `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. -## PreSubmitCheckerPolicy +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 `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 | -Generated server-side from `EffectiveSubmissionArtifactPolicy`. +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. + +## PreSubmitCheckerPolicy Fields: +- `id` - `project_id` - `guide_version` +- `source_snapshot_id` +- `source_snapshot_hash` +- `effective_project_submission_artifact_policy_hash` +- `version` +- `lifecycle_status` - `policy_hash` -- `checker_names` -- `checker_configs` -- `blocking_severities` +- `checker_spec` +- `compiler_version` +- `compiled_bundle_hash` +- `compiled_bundle` +- `checker_names` (derived index projection) +- `checker_configs` (derived index projection) +- `blocking_severities` (derived index projection) +- `generated_from_policy_version` - `generated_at` +- `approved_by_role` +- `approved_by` +- `approved_at` +- `supersedes_policy_id` + +Generated server-side from `EffectiveProjectSubmissionArtifactPolicy`, then +persisted and locked for the project guide version before tasks enter the +worker pipeline. Every task under the same active project guide version reuses +that guide version's project pre-submit checker bundle. If the guide version +does not cover the task set, activation is blocked and the guide is improved or +the work is split into another project/guide. The task stores +`locked_pre_submit_checker_bundle_hash`, which equals +`PreSubmitCheckerPolicy.compiled_bundle_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_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. +`policy_hash` identifies the approved checker policy/spec record, while +`compiled_bundle_hash` is the runtime provenance value locked by tasks, +submissions, and revision context. + +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`. The generated checker order is deterministic: @@ -266,7 +520,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 creates no submission row, no submission version, no task transition to `submitted`, and no submission-created audit event. +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 @@ -293,7 +561,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 @@ -381,9 +649,11 @@ 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_pre_submit_checker_policy_hash` +- `locked_effective_project_submission_artifact_policy_hash` +- `locked_pre_submit_checker_bundle_hash` - `locked_post_submit_checker_policy_version` - `locked_review_policy_version` - `locked_revision_policy_version` @@ -405,8 +675,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` @@ -436,7 +706,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 id/hash, project submission artifact policy version, +effective project submission artifact policy hash, generated project pre-submit checker bundle 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. @@ -468,9 +744,11 @@ 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_pre_submit_checker_policy_hash` +- `locked_effective_project_submission_artifact_policy_hash` +- `locked_pre_submit_checker_bundle_hash` - `locked_post_submit_checker_policy_version` - `locked_review_policy_version` - `locked_revision_policy_version` @@ -479,7 +757,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 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, 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. @@ -741,8 +1028,8 @@ Fields: - `next_locked_guide_version` - `prior_locked_submission_artifact_policy_version` - `next_locked_submission_artifact_policy_version` -- `prior_locked_pre_submit_checker_policy_hash` -- `next_locked_pre_submit_checker_policy_hash` +- `prior_locked_pre_submit_checker_bundle_hash` +- `next_locked_pre_submit_checker_bundle_hash` - `prior_locked_post_submit_checker_policy_version` - `next_locked_post_submit_checker_policy_version` - `prior_locked_review_policy_version` diff --git a/docs/architecture_lifecycle_state_machine.md b/docs/architecture_lifecycle_state_machine.md index 4b7f3b1..9fa80aa 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: @@ -72,8 +72,12 @@ Required before entering: - task schema valid - project guide active +- current GuideSourceSnapshot id/hash locked +- GuideSufficiencyReport passed or warnings acknowledged for that source snapshot - SubmissionArtifactPolicy approved -- generated PreSubmitCheckerPolicy available +- EffectiveProjectSubmissionArtifactPolicy hash persisted +- project PreSubmitCheckerPolicy persisted with a compiled bundle hash and locked to that effective project submission artifact policy hash +- task locked to GuideSourceSnapshot id/hash, EffectiveProjectSubmissionArtifactPolicy hash, and PreSubmitCheckerPolicy compiled bundle hash - PostSubmitCheckerPolicy present - review policy present - revision policy present @@ -99,8 +103,8 @@ Required before entering: - submission summary - package or output reference - evidence items -- effective submission artifact policy loaded -- generated pre-submit checker policy executed +- effective project submission artifact policy loaded +- 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_lockdown.md b/docs/architecture_lockdown.md index 18d9622..babda0a 100644 --- a/docs/architecture_lockdown.md +++ b/docs/architecture_lockdown.md @@ -68,8 +68,11 @@ Every project guide is human-facing. It must explain: Every active guide version must also have approved machine-readable policies: +- immutable guide-source snapshot +- guide sufficiency report - submission artifact policy -- generated pre-submit checker policy +- effective project submission artifact policy hash +- project pre-submit checker bundle hash - post-submit checker policy - review policy - revision policy @@ -77,9 +80,21 @@ 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. -`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. +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 the internal policy bundle +before guide activation. Project owners do not approve Workstream's internal +submission policy schema. -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. +`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, and locks project `PreSubmitCheckerPolicy` with a compiled bundle hash from that effective project submission artifact policy. Tasks lock the applicable guide snapshot, effective project submission artifact policy hash, and pre-submit checker bundle hash before entering the worker pipeline. + +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. Tasks lock to the active guide version at creation or screening time before entering `READY`. Material guide changes require a new guide version. @@ -94,7 +109,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 locked project pre-submit checker policy - difficulty - skill tags - estimated time when known @@ -147,9 +162,10 @@ Use these names consistently: - `check_acceptance_criteria_present` - `ContributionRecord` - `SubmissionArtifactPolicy` -- `EffectiveSubmissionArtifactPolicy` +- `EffectiveProjectSubmissionArtifactPolicy` - `PreSubmitCheckerPolicy` - `PostSubmitCheckerPolicy` +- `pre_submission_checker_failed` - `Project activation gate` - `Task screening gate` - `Submission quality gate` 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 8ef365f..c5e1670 100644 --- a/docs/current_system_data_flow.html +++ b/docs/current_system_data_flow.html @@ -470,11 +470,12 @@

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 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 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 a passing or acknowledged sufficiency report, immutable guide source snapshot, approved submission artifact policy, effective project submission artifact policy hash, project pre-submit checker compiled bundle hash, 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 submission artifact policy hash, and pre-submit checker bundle hash.

status=active one active guide @@ -514,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.

+

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 @@ -590,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, project PreSubmitCheckerPolicy, post-submit checker policy, review policy, revision policy, payment policy.
Task Queue - WorkstreamTask, locked policy versions, TaskAssignment, status transitions. + WorkstreamTask, locked guide snapshot, locked effective project submission artifact policy hash, locked pre-submit checker bundle hash, TaskAssignment, status transitions.
Submission Packet @@ -627,7 +628,7 @@

Durable Records Created Along The Way