docs(policy): plan unified project guide compilation

.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/CHUNK_MAP.md

@@ -0,0 +1,17 @@
+# Chunk Map: WS-POL-003 - Unified Project Guide Compilation
+
+All chunks are L1, one PR each, proposed, and inactive.
+
+| Chunk | Purpose | Hard dependency |
+|---|---|---|
+| WS-POL-003-01 | Strict unified contracts, safe evidence references, merged ART-04B1 pre-submit projection, and durable CHECKER/POL post-submit projection | AUTH-12B2 merged; consume ART-04B1 PR #276 exact contract |
+| WS-POL-003-02 | One OpenAI Agents SDK unified adapter method and fake-runtime tests | 01 |
+| WS-POL-003-03 | Immutable compilation persistence, trusted validator, and action-specific service provenance | 02; AUTH-12F/12G and exact XINT/AUTH compilation request+execute activation merged |
+| WS-POL-003-04 | Initial setup cutover from sufficiency + artifact-policy calls to one compilation | 03 |
+| WS-POL-003-05 | Project Manager approval and trusted project pre-submit policy compilation | 04 |
+| WS-POL-003-06 | Deterministic post-submit projection compilation with zero second model call | 05; AUTH-12G merged |
+| WS-POL-003-07 | One typed checker service port with one complete pre and one complete post command | 06; ART-04B1-04B3 pre-submit executor/evidence-writer contract merged and callable |
+| WS-POL-003-08 | Visibility, generation-safe correction, activation compatibility, checker-route clean cut, and legacy inference cleanup | 07; AUTH-12H/14 and ART-05B merged |
+
+No chunk starts automatically. Each contract must be reconciled against the
+then-current main and dependency merge before human start.

.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/DECISIONS.md

@@ -0,0 +1,63 @@
+# Decisions: WS-POL-003 - Unified Project Guide Compilation
+
+1. One logical structured model attempt is used per immutable source snapshot,
+   catalogue snapshot, and setup generation. A durable attempt row and provider
+   idempotency key serialize dispatch. Retry/recovery uses that exact key and
+   retrieves or reuses its accepted result; it never creates another call.
+   Invalid or unsafe output consumes the attempt and blocks that generation.
+2. `ProjectGuideCompilation` is immutable provenance/proposal evidence, not a
+   canonical policy replacement.
+3. Existing policy objects and Project Manager approval gates remain separate.
+4. Agent-derived projections are immutable. Corrections create a new
+   generation. A manual replacement, if retained, has separate provenance and
+   invalidates every dependent unified proposal.
+5. The fixed `workstream.project.setup` service performs compilation and
+   service-owned projection mutations using fresh action-specific PREP. Human
+   authority only requests/recoveries, acknowledges, corrects through an
+   approved replacement path, and approves.
+6. Platform coverage and selectable project capabilities remain separate
+   projections even when supplied by the same phase owner.
+7. ART-04B1 owns the complete pre-submit catalogue and effective-plan compiler,
+   including mandatory platform entries and its closed selectable project-rule
+   namespace. CHECKER/POL owns durable post-submit capability truth. WS-POL-003
+   consumes these exact owners and creates no parallel dispatch registry.
+8. Unsupported required capabilities block activation. Optional/advisory gaps
+   require explicit Project Manager acknowledgement.
+9. Evidence references are closed structured identifiers; raw excerpts,
+   provider responses, hidden reasoning, URLs, paths, credentials, and
+   executable content are not persisted.
+10. Representative task context is optional and bounded; its absence cannot
+    block project guide compilation.
+11. Setup failures, capability gaps, timeouts, and retries create no
+    ContributionRecord, payment, award, or negative reputation evidence.
+12. No backward-compatibility aliases or dual model-inference paths survive
+    final cleanup.
+13. Pre-submit has no standalone feedback/execution API. One canonical
+    submission preparation/admission request executes one effective plan that
+    contains mandatory platform checks plus exact task-locked project rules.
+14. Post-submit normal execution is automatically dispatched once from the
+    successful Submission creation/finalization boundary. Callers cannot
+    select or separately invoke platform, project, or individual checkers.
+15. An authorized checker repair/requeue command may exist only when it accepts
+    a Submission/run identity and atomically claims the canonical phase-attempt
+    row under the phase owner's repository transaction. The idempotency key is
+    the phase, exact locked material/plan lineage, and attempt ID. Concurrent
+    repair/requeue calls either observe the existing terminal result or one
+    caller resumes the same non-terminal run; they cannot rerun completed
+    members or create a second business effect. A genuinely new evaluation
+    requires a new attempt identity. This is not an alternative checker API.
+16. Setup approval/correction-request APIs configure policy, and read APIs
+    expose bounded evidence; neither is a checker execution path.
+17. AUTH must activate two narrow compilation actions before runtime cutover:
+    a Project Manager dispatch/recovery request and a fixed
+    `workstream.project.setup` execution action. Execution owns only the model
+    call and immutable compilation parent/supersession; 12E/12F/12G retain
+    custody of their separate canonical projections.
+18. CHECKER exposes one internal typed service port with exactly two phase
+    commands: one complete pre-submit evaluation and one complete post-submit
+    evaluation. Artifact-flow orchestration invokes each command once at the
+    ART material boundary and never calls an individual checker.
+19. The pre command is a facade over ART-04B1-04B3's sole compiler, executor,
+    attempt, result, and evidence writer. The post command uses CHECKER's sole
+    durable executor/repository. The facade creates no duplicate member rows or
+    evidence and returns only the canonical phase result/reference.

.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/DISCOVERY.md

@@ -0,0 +1,102 @@
+# Discovery: WS-POL-003 - Unified Project Guide Compilation
+
+Baseline inspected: `origin/main` `bb77ff4a0ab61120b94d6d4763934b444c39207d`
+on 2026-08-05.
+
+## Current behavior
+
+- `backend/app/interfaces/project_agents.py` exposes separate
+  `analyze_guide_sufficiency`, `derive_submission_artifact_policy`, and
+  `derive_post_submit_checker_policy` contracts.
+- `backend/app/adapters/project_agents/openai_agent_sdk.py` implements three
+  prompts/model calls behind `ProjectGuideAgentRuntime`.
+- `backend/app/modules/projects/sufficiency_mutation_service.py` now performs
+  sufficiency execution only as the fixed setup service over ART-verified
+  material. The Project Manager route is an asynchronous dispatch/recovery
+  request.
+- `project_setup.py` still sequences sufficiency,
+  submission-policy derivation, approval/compilation continuation, and later
+  post-submit derivation.
+- `backend/app/modules/checkers/compiler.py` is the current legacy pre-submit
+  policy compiler now integrated with ART-04B1 catalogue definitions.
+- `backend/app/modules/checkers/catalogue.py` implements the immutable
+  `PreSubmissionCheckerCatalogue`, exact `v0.1` definition manifest,
+  startup-fixed disabled state, and canonical manifest hash.
+- `backend/app/modules/checkers/effective_plan.py` implements the pure
+  `EffectivePreSubmissionExecutionPlan` compiler and exact locked lineage,
+  rule-instance, configuration, catalogue, and plan hashes. It performs no
+  checker execution or durable write.
+- `backend/app/modules/checkers/runner.py` registers the current durable
+  checker implementations. `check_acceptance_criteria_present` is the only
+  current non-default project-selectable post-submit checker.
+- The obsolete `POST /tasks/{task_id}/submission-precheck` route and direct
+  `POST /submissions/{submission_id}/checker-runs` trigger remain reachable.
+  ART PLAN5 superseded 04A4 and moved the standalone precheck clean cut to
+  ART-05B. Later AUTH-14/cleanup must constrain ordinary post execution to the
+  single typed command and preserve only bounded same-attempt repair.
+- `backend/app/modules/projects/service.py` deliberately prevents mutation of
+  agent-derived policy bodies; that immutability must be preserved.
+
+## Canonical dependencies
+
+- AUTH-12F: submission-artifact policy mutation/provenance authority.
+- AUTH-12G: post-submit policy mutation/provenance authority.
+- AUTH-12B2: fixed setup-service worker call-graph cutover.
+- AUTH-12H: terminal guide activation authority.
+- ART-04B1: merged PR #276. The immutable catalogue is exactly
+  `workstream.pre_submission_checkers` `v0.1` with schema
+  `pre_submission_checker_catalogue.v1`; the pure effective plan is
+  `effective_pre_submission_plan.v1` and binds its manifest hash plus locked
+  source/effective/pre-submit policy lineage.
+- ART-04B2/04B3: sealed scratch/default execution facts consumed through a
+  typed boundary; WS-POL-003 does not change those ART behaviors.
+- CHECKER/POL: canonical durable post-submit defaults/selectable rules and one
+  typed evaluation service with a complete pre and complete post command.
+- Artifact-flow orchestration invokes the pre command once while material is
+  sealed in scratch and the post command once after verified storage/binding.
+  It does not call individual checkers.
+
+## Existing tests to preserve
+
+- `backend/tests/test_projects.py`: setup generation, agent failure,
+  idempotency, policy derivation/approval, correction, Celery, and provenance.
+- `backend/tests/test_checkers.py`: pre/post compiler and checker registry.
+- `backend/tests/test_checker_catalogue.py`: exact 26-entry ART-04B1 catalogue,
+  availability, immutable manifest, effective-plan lineage, policy coverage,
+  default weakening, and stale/invalid plan proof.
+- `backend/tests/test_authorization.py`: action/catalogue/PREP/fixed-service
+  isolation.
+- `backend/tests/test_tasks.py`: task-locked guide and policy context.
+- `backend/tests/test_alembic.py`: migration topology and round trip.
+- `backend/tests/test_guide_bindings.py`: ART-verified guide material custody.
+
+## Confirmed risks and gaps
+
+- A manually edited agent projection would invalidate unified result
+  provenance. Agent projections must be immutable.
+- Unified fixed-service execution needs explicit fresh PREP custody for
+  each protected durable boundary; no synthetic human context is acceptable.
+- Free-text model output can echo secrets, raw guide excerpts, paths, URLs, or
+  prompt injection. Evidence references require a closed structured grammar
+  and all persisted text requires bounded sanitization.
+- ART-04B1 is merged but intentionally performs no checker execution or durable
+  write. WS-POL-003 must consume its exact immutable manifest/effective-plan
+  contracts rather than creating an interim registry or assuming 04B2/04B3.
+- A post-submit proposal produced early becomes stale if its compilation,
+  artifact-policy projection, pre-submit proposal, catalogue snapshot, or
+  setup generation changes.
+- Representative task material is optional bounded context. Guide setup must
+  not depend on tasks already existing.
+- Current post-submit compilation must gain a trusted hard rejection for
+  platform-default repetition; prompt instructions are insufficient.
+- A catalogue is not an execution API. The checker service must expose exactly
+  one typed call per phase and accept no caller-selected checker names.
+
+## Unknowns to resolve in the planning PR
+
+- Final names and limits for evidence-reference and safe-text schemas.
+- Exact AUTH action/resource binding for creation of the compilation record;
+  use narrow XINT/AUTH compilation request+execute actions for the parent while
+  preserving separate 12E/12F/12G projection actions.
+- Whether separately manual policies remain supported after clean cut. If so,
+  they require independent provenance and cannot reuse unified proposals.

.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/INTENT.md

@@ -0,0 +1,67 @@
+# Intent: WS-POL-003 - Unified Project Guide Compilation
+
+## Human goal
+
+Compile one immutable Project Guide source snapshot into one coherent,
+reviewable setup proposal with one logical, idempotency-keyed model attempt per
+setup generation. The result must cover guide sufficiency, submission-artifact
+policy, atomic guide requirements, supported project-specific pre-submit and
+post-submit checker bindings, human-review/lifecycle dispositions, and visible
+capability gaps.
+
+The purpose is to remove repeated guide reads and inconsistent independent
+agent conclusions without giving the model policy, authorization, checker, or
+approval authority.
+
+## Success state
+
+- One verified guide snapshot and setup generation owns one durable model-attempt
+  identity and one provider idempotency key. Retries recover that same attempt;
+  they cannot issue a second provider request under a different key.
+- A structurally invalid or unsafe provider result consumes and terminally
+  blocks that generation. Correction or another genuine evaluation requires a
+  new setup generation; transport uncertainty is reconciled under the original
+  key and can only reuse an already accepted result.
+- Trusted server validation projects the immutable result into the existing
+  canonical policy objects; `ProjectGuideCompilation` does not replace them.
+- Platform checks remain mandatory and non-selectable.
+- ART-04B1 owns the complete pre-submit catalogue: mandatory platform entries
+  plus its closed selectable project-rule namespace. CHECKER/POL owns the
+  durable post-submit capability registry/compiler. WS-POL-003 consumes both
+  read-only and creates neither a duplicate catalogue nor new ART behavior.
+- Unsupported required requirements visibly block activation; optional gaps
+  require explicit acknowledgement.
+- Agent-derived projections are immutable. Correction creates a new setup
+  generation, or a separately proven manual policy that cannot claim unified
+  agent provenance.
+- Project Managers request/recover and approve bounded results; the fixed
+  `workstream.project.setup` service alone performs compilation and service
+  projection mutations with fresh transaction-bound authorization.
+- No prepared handle, guide bytes, extracted content, credentials, or scratch
+  path enters a Celery payload.
+
+## Non-goals
+
+- Dynamic checker discovery, generated code, project-provided plugins, network
+  checks before submission, or a second checker registry.
+- Replacing human review or changing task, review, revision, contribution,
+  compensation, payment, or reputation semantics.
+- Replacing `ProjectSetupRun`, `GuideSufficiencyReport`,
+  `SubmissionArtifactPolicy`, effective policy, `PreSubmitCheckerPolicy`, or
+  `PostSubmitCheckerPolicy`.
+- Implementing ART-04B1 through 04B3 inside this initiative.
+- Changing ART scratch, storage, provider, binding, or lifecycle behavior. This
+  initiative provides one typed checker-service call per phase for later
+  artifact-flow integration at ART material boundaries.
+
+## Human decisions already captured
+
+- Prefer one unified inference over three complete guide-reading inferences.
+- Keep durable policy lifecycles and approval gates separate.
+- Treat the model as an untrusted proposal generator.
+- Preserve async-first execution and fixed-service authorization custody.
+- Do not preserve compatibility aliases or dual inference paths in v0.1.
+- Keep one authoritative execution entry per checker phase: pre-submit runs
+  only inside canonical submission preparation/admission, and post-submit runs
+  automatically from successful Submission creation/finalization. Platform,
+  project, and individual checkers are never separate caller-selected APIs.