diff --git a/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/CHUNK_MAP.md b/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/CHUNK_MAP.md new file mode 100644 index 00000000..e30144fb --- /dev/null +++ b/.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. diff --git a/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/DECISIONS.md b/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/DECISIONS.md new file mode 100644 index 00000000..a15a0fbc --- /dev/null +++ b/.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. diff --git a/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/DISCOVERY.md b/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/DISCOVERY.md new file mode 100644 index 00000000..4991d24c --- /dev/null +++ b/.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. diff --git a/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/INTENT.md b/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/INTENT.md new file mode 100644 index 00000000..ea92bf72 --- /dev/null +++ b/.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. diff --git a/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/PLAN.md b/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/PLAN.md new file mode 100644 index 00000000..82585620 --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/PLAN.md @@ -0,0 +1,333 @@ +# Plan: WS-POL-003 - Unified Project Guide Compilation + +## Objective + +Replace the current three complete project-guide inference passes with one +bounded logical `ProjectGuideCompilationAgent` attempt for each exact immutable +guide source, capability-catalogue snapshot, and setup generation. A durable +attempt identity and provider idempotency key enforce that cardinality across +dispatch, timeout, reconciliation, and retry. + +The invocation proposes: + +1. guide sufficiency and findings; +2. a submission-artifact policy draft; +3. an atomic, traceable requirement inventory; +4. supported project-specific pre-submit bindings; +5. supported project-specific post-submit bindings; +6. platform-covered requirements; +7. human-review and lifecycle-policy requirements; and +8. non-executable capability suggestions for unsupported requirements. + +The model is untrusted. Trusted server code validates, canonicalizes, hashes, +persists, compiles, and submits separate canonical policies for approval. + +## Prerequisite sequence + +AUTH-12F, 12G, 12B2, and 12H complete the existing policy mutation, +fixed-service worker, and activation authorization boundaries. WS-POL-003 must +reuse those action-specific boundaries rather than create a broad +`project.guide.compile_everything` permission. + +ART-04B1 supplies the complete typed pre-submit catalogue and effective-plan +compiler: mandatory/non-selectable platform coverage plus its closed selectable +project-rule namespace. ART-04B2/04B3 retain ART scratch/default execution. +WS-POL-003 consumes those typed projections and does not change ART ownership. + +The merged pre-submit projection is consumed exactly as implemented: + +- catalogue ID `workstream.pre_submission_checkers`, version `v0.1`, schema + `pre_submission_checker_catalogue.v1`; +- immutable canonical manifest and `manifest_sha256`; +- stable definition ID/version, owner, phase/order/dependencies, + classification, typed inputs, result schema, failure code, resource budget, + state/disabled behavior, policy trace, and dispatch identity; +- pure `effective_pre_submission_plan.v1` bound to exact project, guide/source, + effective policy, pre-submit policy, catalogue manifest, ordered entries, + rule-instance identities/configuration hashes, and `plan_sha256`. + +WS-POL-003 does not infer missing catalogue fields, mutate availability, or +reconstruct plan identity independently. + +Durable CHECKER/POL ownership supplies post-submit defaults and registered +selectable project rules. WS-POL-003 creates no pre-submit or post-submit +dispatch registry; the unified agent sees read-only projections from both +canonical phase owners. + +Before persistence/runtime cutover, an XINT/AUTH amendment must activate: + +- `project.guide_compilation.request`: Project Manager dispatch/recovery bound + to exact actor/link/grant, project, draft guide, snapshot, setup + run/generation, operation, request digest, and idempotency identity; +- `project.guide_compilation.execute`: fixed `workstream.project.setup` + authority bound to exact canonical input hash, source and phase-owned + capability snapshot hashes, setup run/generation, instruction/agent version, + prior compilation when superseding, session/root transaction, and result. + +Execute authorizes only the model call plus immutable compilation parent +creation/supersession. It does not authorize canonical projections: 12E owns +sufficiency, 12F owns submission/effective/pre-submit policy mutations, and +12G owns post-submit policy mutations. Each projection consumes fresh +action-specific PREP at its protected transaction. + +## Single checker execution surfaces + +There are two lifecycle phases exposed through one internal typed checker +service port, with exactly one complete command per phase: + +```text +ART sealed scratch material +-> checker_service.evaluate_pre_submission(...) exactly once + -> mandatory ART platform plan + exact locked project pre-submit plan +ART verified stored/bound Submission material +-> checker_service.evaluate_post_submission(...) exactly once + -> durable platform defaults + exact locked project post-submit plan +``` + +Artifact-flow orchestration supplies exact ART material facts and invokes the +phase command at the corresponding material boundary. The checker service +facade invokes the canonical phase executor once and returns one typed bounded +result; no caller invokes an individual checker. For pre-submit, ART-04B1-04B3 +remain the sole plan compiler/executor/evidence writer behind the facade. For +post-submit, the durable CHECKER executor/repository is the sole writer. The +facade never reruns members or persists a competing evidence set. + +These commands are internal typed service APIs, not contributor-facing HTTP +checker routes. Callers cannot provide checker names or invoke platform and +project rules separately. Automatic orchestration and any bounded repair use +the same command and deterministic attempt identity. + +Setup proposal, approval, correction-request, and visibility APIs remain +separate because they configure or observe policy rather than execute a +submission. Read-only checker-run visibility also remains bounded and separate. + +This initiative owns the checker service contract and composition. Later +artifact-flow integration consumes it at ART's scratch and verified-storage +boundaries without WS-POL-003 modifying ART code or forcing ART lifecycle changes. + +## Input contract + +`ProjectGuideCompilationContext` is strict (`extra="forbid"`) and contains: + +- exact existing ART-verified `GuideSourceMaterial`; +- optional bounded representative task context; +- non-selectable `platform_coverage` generated from ART-04B1 platform entries + plus CHECKER-owned durable post-submit defaults; +- selectable `project_capabilities` generated from ART-04B1's project-rule + namespace for pre-submit and CHECKER/POL's registered rules for post-submit; +- server-owned classification policy and schema versions; +- optional bounded correction feedback tied to an exact superseded + compilation. + +Representative task context is tenant-local, server-redacted, and limited to +policy shape. It excludes actor/user IDs, emails, submission artifacts, review +decisions, payment/compensation data, credentials, secrets, URLs, and raw task +bodies not already part of approved guide/setup source material. + +The canonical input binds source snapshot ID/hash, catalogue hashes, setup +run/generation, instruction version, configured agent identity, SHA-256, and +byte count. Provider responses, reasoning traces, credentials, scratch paths, +and raw duplicate source text are not persisted. + +## Project capability and stage contract + +Both canonical phase catalogues are closed, typed, versioned, and registered +explicitly at their composition roots. The pre-submit projection uses only the +fields in merged ART-04B1; it does not invent per-entry timeout or safety +metadata absent from `v0.1`. Catalogue mutation requires code, tests, +deployment, and startup parity validation; projects and model output cannot +register it. + +A project capability is eligible for pre-submit only when ART-04B1 registers +it as an enabled `policy_primitive` in `project_policy`, its exact trusted +implementation satisfies the closed primitive contract, and its compiled +configuration matches the definition's policy fields. The later executor owns +the server-side 60-second aggregate project-rule ceiling; the model cannot +change stage, order, resource budget, disabled behavior, or timeout. Sixty +seconds is a ceiling, not permission. Mandatory ART work retains its separate +platform budgets. + +Deterministic work outside that contract is post-submit. Expert judgment is +human review. Claiming, assignment, deadlines, routing, revision, acceptance, +payment, and other transitions are lifecycle policy. Timeout, cancellation, +or infrastructure failure is retryable platform state, never contributor +failure. + +Post-submit is not an escape hatch: a selectable post-submit capability must +also be registered for that stage, closed-schema, deterministic, +side-effect-free, bounded, credential-safe, and implemented by trusted code. +It cannot execute arbitrary project code, shell, network calls, or model +judgment. Its timeout and resource budget are catalogue-owned and enforced. + +Initial project pre-submit capability identities, enabled only when backed by +registered implementations, are: + +- `policy.submission_packet.validate` +- `policy.storage_scheme.enforce` +- `policy.manifest_field.require` (Workstream manifest fields only) +- `policy.hash.verify` +- `policy.file.require` +- `policy.evidence.minimum` +- `policy.artifact.forbid` +- `policy.attestation.require` +- `policy.file_size.limit` +- `policy.package_size.limit` +- `policy.packaging.require` +- `policy.generated_quality.warn` + +`policy.manifest_field.require` does not validate arbitrary domain files. Such +a requirement remains a capability gap until a dedicated typed structured- +document capability exists. + +The initial project-selectable post-submit truth is only +`check_acceptance_criteria_present` unless the running build registers more. +Durable platform defaults are non-selectable and cannot be repeated in project +bindings. Unknown support becomes a capability suggestion; it is never +manufactured to make a guide appear complete. + +## Output contract + +`ProjectGuideCompilationResult` is strict, size/count bounded, and contains: + +- `guide_blocked`, `draft_ready`, or `draft_ready_with_warnings`; +- sufficiency findings; +- nullable submission-artifact policy projection; +- atomic requirements with exactly one disposition; +- pre-submit and post-submit binding proposals; +- bounded capability suggestions; +- bounded safe setup notes; +- server-verified agent/schema identity. + +Allowed dispositions are `platform_covered`, `supported_pre_submit`, +`pre_submit_capability_gap`, `supported_post_submit`, +`post_submit_capability_gap`, `human_review`, +`project_lifecycle_policy`, `guide_blocker`, and `informational`. + +Bindings may select only the exact ID/version/stage exposed through +`project_capabilities`. Suggestions are engineering work items and can contain +no capability ID, source code, command, URL, import, dependency, or executable +expression. + +## Evidence and text safety + +Evidence uses a closed `GuideEvidenceRef` structure minted/validated by trusted +server code from the immutable source-item and extraction lineage. It never +contains raw excerpts, URLs, paths, credentials, signed references, or caller +text. + +Every persisted operator-readable model field passes centralized bounded safe +text validation/redaction. Rejection is atomic: unsafe or structurally invalid +output produces retryable/blocked setup evidence and no policy projection. + +## Trusted validation + +Validation must, in order: + +1. enforce strict shape and count/size limits; +2. lock and revalidate service identity, source lineage, setup run/generation, + and canonical input identity; +3. validate sufficiency/finding consistency; +4. validate artifact policy with existing strict/default-merge rules; +5. validate requirement/binding/suggestion referential integrity; +6. reject platform/default selection or repetition; +7. reject unknown, disabled, stale-version, or wrong-stage capabilities; +8. validate typed configuration, deterministic/side-effect-free constraints, + and phase-owned resource controls exactly as exposed: ART `resource_budget` + plus executor gates and the aggregate pre-submit ceiling, or post-submit + timeout/budget fields only when their canonical source defines them; +9. sanitize every persisted text field; +10. canonicalize and hash the result and each projection; and +11. prepare every required action-specific fixed-service PREP, consume all of + them inside the one root database transaction owning compilation and + projection persistence, then commit mutations and authorization evidence + together; any validation, consumption, or write failure rolls back the + entire unit without borrowing authority between actions. + +The agent cannot order platform execution. Catalogue phases, dependencies, and +the trusted compiler determine order. + +## Persistence and provenance + +Add immutable `ProjectGuideCompilation` provenance with exact project, guide, +source snapshot, catalogue snapshots, setup run/generation, agent/instruction +identity, canonical input/result hashes, component hashes, created service +identity, and append-only supersession. + +Existing `GuideSufficiencyReport`, `SubmissionArtifactPolicy`, +`PreSubmitCheckerPolicy`, and `PostSubmitCheckerPolicy` link to the exact +compilation ID/result/component hashes. They remain canonical business objects. + +Agent-derived projections cannot be edited. Correction creates a new setup +generation and compilation. If separately manual policies remain supported, +they carry manual provenance, invalidate unified downstream proposals, and +cannot claim or reuse agent compilation approval. + +## Lifecycle + +```text +ART verified extraction +-> automatic fixed-service setup continuation +-> canonical platform/capability projections +-> one unified model invocation +-> trusted validation and immutable compilation +-> separate sufficiency/policy proposals +-> Project Manager review/approval +-> trusted effective + pre-submit compilation +-> deterministic post-submit proposal compilation (zero model calls) +-> separate PostSubmitCheckerPolicy approval +-> existing authorized guide activation +``` + +Blocked compilation creates no policy projections. A required capability gap +blocks activation with an exact operator-visible setup status/error. The setup +generation has one durable model-attempt row and provider idempotency key. A +timeout, cancellation, or infrastructure failure before known acceptance may +retry or reconcile only that key; an unknown outcome must be retrieved or +replayed idempotently, never redispatched with a new key. Once an accepted +result is persisted, retry reuses it. Invalid or unsafe output terminally +consumes the attempt and requires a new setup generation for correction. None +of these states is contributor failure or negative contribution evidence. + +## Alternatives rejected + +- Keep three guide-reading inference calls: repeated cost and inconsistent + conclusions. +- Store one combined canonical policy: collapses separate ownership and + approval lifecycles. +- Allow model-created checker code or identifiers: unsafe and non-auditable. +- Build POL-local pre/post primitive maps or duplicate ART platform/project + entries: creates competing dispatch authority instead of consuming the two + canonical phase owners. +- Permit in-place edits to agent projections: destroys result-hash provenance. +- Grant one broad compilation permission: bypasses action-specific AUTH + custody and atomic evidence. +- Keep standalone precheck or caller-selected checker triggers: creates a + parallel execution path that can drift from the locked effective plan. + +## Verification strategy + +- Strict contract and prompt-injection tests. +- Registry/version/stage/configuration/default-isolation tests. +- Fixed-service identity, PREP replay/session/transaction/resource tests. +- Postgres migration, append-only supersession, concurrent idempotency, and + rollback tests. +- Single-logical-attempt lifecycle tests covering concurrent dispatch, + timeout-after-provider-acceptance recovery under the same idempotency key, + accepted-result reuse, terminal invalid/unsafe output, and zero-call + post-submit continuation. +- Stale source/catalogue/setup/policy invalidation tests. +- Task-lock and activation-chain regression tests. +- OpenAPI/import/reachability tests proving standalone precheck is absent, + no caller can select checkers, artifact-facing composition has one command per + phase, and repair converges on the same attempt identity. +- Hosted CI full suite/coverage; changed backend subsystems remain at least 90 + percent and repository floor remains at least 78 percent. + +## Completion boundary + +Completion requires the old three runtime methods/prompts and second +post-submit model invocation to be deleted after all callers cut over. No +compatibility alias, dual inference path, second registry, or independently +invocable legacy precheck survives. The two canonical phase catalogues and one +typed checker service port remain; the port has exactly one complete command +per pre/post phase and no individual-checker product entry. diff --git a/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/RISKS.md b/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/RISKS.md new file mode 100644 index 00000000..1d9c97d7 --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/RISKS.md @@ -0,0 +1,19 @@ +# Risks: WS-POL-003 - Unified Project Guide Compilation + +| Risk | Severity | Mitigation | +|---|---|---| +| Unified model result is trusted as policy | Critical | Strict schemas, canonical registry lookup, trusted validation, separate approvals, and final locked revalidation. | +| Setup service borrows PM/admin authority | Critical | Finish AUTH-12F/12G/12B2/12H; use fresh fixed-service PREP per protected transaction. | +| Pre-submit capability dispatch is duplicated | Critical | Consume ART-04B1's complete platform-plus-project catalogue read-only; add no POL pre-submit registry or primitive map. | +| Manual correction breaks compilation provenance | Critical | Immutable agent projections; new generation or independent manual replacement provenance. | +| Model echoes secrets or injected guide instructions | High | Closed evidence references, safe-text validation/redaction, strict limits, no tools/network, and prompt-injection tests. | +| Early post-submit proposal becomes stale | High | Bind all projections to compilation/result hashes; invalidate on any source/catalogue/policy/generation change. | +| Required unsupported capability silently passes | High | Required gaps block activation and have explicit operator-visible status/code. | +| Platform defaults are repeated or weakened | High | Non-selectable platform projection plus trusted compiler rejection of repetition/reordering/downgrade. | +| One result/record becomes an oversized god object | Medium | Keep canonical policies separate; bounded immutable result and projection hashes only. | +| Setup starts requiring representative tasks | Medium | Task context remains optional and bounded. | +| Migration races concurrent initiatives | High | Allocate the then-current migration only after dependencies merge; prove one Alembic head. | +| ART is forced to own post-submit policy | Critical | ART retains only its current pre-submit catalogue/material custody; durable CHECKER/POL ownership remains post-submit. | +| Individual checker calls bypass the effective plan | Critical | One checker-service port exposes one pre and one post command; artifact-flow orchestration invokes once per material boundary and cannot select checkers. | +| Facade duplicates ART pre-submit execution/evidence | Critical | Pre command delegates once to ART-04B1-04B3 and returns its canonical result/reference; ART remains the sole pre attempt/evidence writer. | +| Compilation parent lacks exact AUTH custody | Critical | Merge narrow XINT/AUTH request+execute activation before chunk 03; projections retain separate 12E/12F/12G PREP. | diff --git a/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/STATUS.md b/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/STATUS.md new file mode 100644 index 00000000..4775ae34 --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/STATUS.md @@ -0,0 +1,27 @@ +# Status: WS-POL-003 - Unified Project Guide Compilation + +Status: planning candidate under review; no implementation is active. + +Baseline: `origin/main` `bb77ff4a0ab61120b94d6d4763934b444c39207d`. + +## Dependency gates + +| Dependency | Required before | Current status at baseline | +|---|---|---| +| AUTH-12F | service submission-policy projection writes | Proposed after merged 12E | +| AUTH-12G | service post-submit projection writes | Proposed after 12F | +| AUTH-12B2 | unified Celery call-graph cutover | Proposed after 12F/12G | +| AUTH-12H | terminal activation integration | Proposed after 12B2 | +| ART PLAN5 / 04A4 | 04A4 superseded; standalone precheck clean cut moved to ART-05B | PLAN5 merged through PR #273 | +| ART-04B1 complete pre-submit catalogue/effective-plan contract | exact immutable platform plus closed project-rule projection consumed read-only | Merged through PR #276 | +| ART-04B2/04B3 | sealed execution and immutable evidence writer used behind the pre facade | Proposed after merged ART-04B1 | +| ART-05B | standalone precheck and legacy Submission path clean cut | Proposed after ART/XINT admission sequence | +| CHECKER/POL post-submit catalogue | durable defaults plus registered selectable project rules | Consumed read-only/hardened by POL work | +| CHECKER typed evaluation port | one pre call in scratch and one post call after verified storage/binding | Owned by WS-POL-003-07 | +| XINT/AUTH compilation activation | exact PM request and fixed-service execute actions for immutable compilation custody | Not yet planned/merged | + +## Chunk state + +All WS-POL-003 chunks are proposed and inactive. Planning does not authorize +implementation. The first implementation chunk requires explicit human start +after this plan and its applicable dependencies are merged. diff --git a/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/chunks/WS-POL-003-01-contract-catalogue-projection.md b/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/chunks/WS-POL-003-01-contract-catalogue-projection.md new file mode 100644 index 00000000..8a69df4b --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/chunks/WS-POL-003-01-contract-catalogue-projection.md @@ -0,0 +1,41 @@ +# Chunk Contract: WS-POL-003-01 - Unified Contract and Catalogue Projection + +Status: Proposed, inactive. Risk: L1. + +## Goal + +Add strict unified input/result/evidence models and read-only projections from +ART-04B1's complete pre-submit catalogue and CHECKER/POL's durable post-submit +capability truth. No model call, persistence, registry, or lifecycle change. + +## Allowed files + +`backend/app/interfaces/project_agents.py`, canonical ART and CHECKER/POL +projection interfaces/composition only, focused tests, and WS-POL-003 docs. + +## Not allowed + +ART/CHECKER catalogue changes, duplicate project registry, database/model/Celery +changes, action activation, or checker execution. + +## Acceptance + +- Strict bounded schemas reject extra/executable/unsafe fields. +- ART platform coverage is non-selectable. Pre-submit project capabilities come + only from ART-04B1; post-submit project capabilities come only from the + canonical durable CHECKER/POL source. +- Pre-submit input preserves the exact full 26-entry ART-04B1 manifest, + including enabled and disabled advisory entries, catalogue ID/version/schema, + `manifest_sha256`, definition identities and states, dispatch kinds, + classifications, phases, policy fields, resource budgets, and disabled + behavior. Selection remains limited to enabled policy primitives. POL invents + no missing timeout/safety fields and cannot mutate catalogue state. +- `GuideEvidenceRef` is closed and raw excerpts/URLs/paths cannot enter it. +- Optional representative task context does not gate compilation. +- Unknown/default/wrong-stage bindings fail closed. + +## Verification and review + +Focused schema/catalogue tests, Ruff, type checks, stale-registry scan. Required +reviewers: architecture, security, QA, product, reuse, test delta, CI integrity. +Human focus: no second registry and no executable model fields. diff --git a/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/chunks/WS-POL-003-02-unified-agent-adapter.md b/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/chunks/WS-POL-003-02-unified-agent-adapter.md new file mode 100644 index 00000000..6ba78131 --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/chunks/WS-POL-003-02-unified-agent-adapter.md @@ -0,0 +1,33 @@ +# Chunk Contract: WS-POL-003-02 - Unified Agent Adapter + +Status: Proposed after 01. Risk: L1. + +## Goal + +Implement one bounded `compile_project_guide` adapter call with untrusted-data +instructions, strict structured output, cancellation, timeout, and sanitized +failures. Do not rewire production Celery orchestration. + +## Allowed files + +`backend/app/adapters/project_agents/**`, project-agent interfaces/configuration, +fake adapter tests, and WS-POL-003 docs. + +## Not allowed + +Database, authorization, Celery orchestration, policy approval, registry, or checker runtime +changes; no provider trace persistence or tool/network capability. + +## Acceptance + +- One method consumes the canonical context and returns the strict result. +- Guide/task contents remain untrusted data and cannot alter instructions. +- Prompt/input limits, timeout, cancellation, and sanitized error behavior are + preserved. +- Agent cannot emit code, commands, URLs, capabilities outside the projection, + or approval decisions. + +## Verification and review + +Fake-runtime, injection, timeout/cancellation, and serialization tests. Required +reviewers: security, architecture, QA, product, test delta, CI integrity. diff --git a/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/chunks/WS-POL-003-03-compilation-persistence-validator.md b/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/chunks/WS-POL-003-03-compilation-persistence-validator.md new file mode 100644 index 00000000..4da1b47d --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/chunks/WS-POL-003-03-compilation-persistence-validator.md @@ -0,0 +1,51 @@ +# Chunk Contract: WS-POL-003-03 - Compilation Persistence and Validator + +Status: Proposed after 02 and required AUTH dependencies. Risk: L1. + +Hard gate: the exact XINT/AUTH registration and activation for +`project.guide_compilation.request` and +`project.guide_compilation.execute` is merged. Generic fixed-service authority +or 12E/12F/12G projection authority cannot substitute for it. + +## Goal + +Add immutable compilation provenance, trusted validation, component hashes, +append-only supersession, and action-specific fixed-service mutation custody. + +## Allowed files + +Project models/schemas/repository/validator/composition, AUTH prepared-resource +composition only where exact existing actions require it, one then-current +Alembic migration, focused tests, and WS-POL-003/AUTH specification docs. + +## Not allowed + +Celery call-graph cutover, approval behavior, checker execution, broad compilation +permission, synthetic human authority, compatibility path, or ART semantics. + +## Acceptance + +- A database `UNIQUE` constraint covers exact `project_id`, `guide_id`, source + snapshot ID, pre- and post-catalogue snapshot hashes, setup run ID, and setup + generation. The setup-run current-compilation pointer advances only by + compare-and-swap against its locked expected generation/current ID. Concurrent + requests therefore converge on one immutable compilation rather than two + current rows. +- Strict validation and sanitization precede atomic persistence. +- Existing policy projections bind exact compilation/component hashes. +- Fresh action-specific fixed-service PREPs are prepared separately, but all + required handles are consumed in the single root database transaction that + owns compilation, projection links, and authorization evidence. Replay, + copied/wrong handle, stale context, or any partial failure rolls back the + whole unit and creates no durable effect. +- Agent-derived projections cannot be updated in place. +- Compilation creation/supersession consumes the exact fixed-service execute + action; PM recovery consumes the exact request action. Projection writes each + consume their separate 12E/12F/12G PREP in that same root transaction and + cannot borrow compilation authority. + +## Verification and review + +Postgres unique-key, compare-and-swap, concurrent-insert, PREP atomicity, and +rollback tests plus AUTH all-pairs denials and 90% changed-subsystem coverage. +Required reviewers: all L1 tracks. diff --git a/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/chunks/WS-POL-003-04-initial-setup-cutover.md b/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/chunks/WS-POL-003-04-initial-setup-cutover.md new file mode 100644 index 00000000..66243dcb --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/chunks/WS-POL-003-04-initial-setup-cutover.md @@ -0,0 +1,41 @@ +# Chunk Contract: WS-POL-003-04 - Initial Setup Pipeline Cutover + +Status: Proposed after 03. Risk: L1. + +## Goal + +Replace the separate sufficiency and submission-policy inference calls with one +unified compilation, while producing the existing canonical report and draft +policy projections. + +## Allowed files + +Project setup worker/service/queue/composition, unified compilation services, +focused project/authorization/ART-boundary tests, and WS-POL-003 docs. + +## Not allowed + +Post-submit continuation cutover, approval semantics, checker execution, +serialized handles/material, or fallback to legacy guide excerpts. + +## Acceptance + +- Automatic and manual recovery converge on one deterministic setup run/task. +- Each generation persists one model-attempt row and provider idempotency key + derived from the exact setup run/generation and compilation input identity. + Dispatch and recovery atomically claim that row; retries use the same key. +- Provider acceptance must be recoverable by idempotent replay/result lookup, + and the accepted result is persisted before downstream continuation. A + timeout-after-acceptance retry reuses that result without another invocation. +- Invalid or unsafe output terminally consumes the generation's attempt; + another evaluation requires a new setup generation. +- Blocked output creates no policy projection. +- Ready output atomically links sufficiency and draft artifact policy to one + compilation. +- Stale/revoked/wrong-service/output failures occur before protected mutation. + +## Verification and review + +Celery concurrent-claim, retry/replay, timeout-after-acceptance, accepted-result +reuse, terminal-invalid-output, stale-generation, provider-failure, and rollback +tests plus hosted full coverage. Required reviewers: all L1 tracks. diff --git a/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/chunks/WS-POL-003-05-approval-pre-submit-integration.md b/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/chunks/WS-POL-003-05-approval-pre-submit-integration.md new file mode 100644 index 00000000..248653ae --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/chunks/WS-POL-003-05-approval-pre-submit-integration.md @@ -0,0 +1,40 @@ +# Chunk Contract: WS-POL-003-05 - Approval and Pre-Submit Integration + +Status: Proposed after 04. Risk: L1. + +## Goal + +Bind Project Manager approval to the exact immutable compilation and compile +approved project pre-submit bindings through ART-04B1's effective-plan +compiler while preserving its platform entries as mandatory and non-selectable. + +## Allowed files + +Project policy approval/service/repository/router/schema surfaces, +ART-04B1 catalogue/compiler integration, +authorization resource composition, focused tests, and specifications. + +## Not allowed + +Second registry/compiler, platform-default selection, checker execution, +post-submit compilation, unrelated approval semantics, task/review/payment +behavior, or in-place agent edits. This chunk does own Project Manager approval +binding to the exact compilation, including hash binding, stale invalidation, +and activation blocking. + +## Acceptance + +- Approval locks exact compilation/result/artifact/pre-submit hashes. +- Platform defaults are composed only by ART and cannot be selected, repeated, + weakened, reordered, or downgraded. +- Required capability gaps block approval/activation with exact operator code. +- Catalogue/source/generation/projection changes stale prior approval. +- Effective and pre-submit outputs commit atomically with authorization evidence. +- The approved project plan and mandatory ART platform entries compose only + through the later single checker-service pre-submit command; this chunk does + not change ART or expose an execution route. + +## Verification and review + +Postgres approval races, stale hashes, default isolation, compiler parity, +AUTH denial, and task-lock regression tests. Required reviewers: all L1 tracks. diff --git a/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/chunks/WS-POL-003-06-post-submit-deterministic-cutover.md b/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/chunks/WS-POL-003-06-post-submit-deterministic-cutover.md new file mode 100644 index 00000000..bc2a229a --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/chunks/WS-POL-003-06-post-submit-deterministic-cutover.md @@ -0,0 +1,42 @@ +# Chunk Contract: WS-POL-003-06 - Deterministic Post-Submit Cutover + +Status: Proposed after 05. Risk: L1. + +## Goal + +Compile the stored unified post-submit proposal after effective/pre-submit +approval without rereading the guide or invoking a second model. + +## Allowed files + +Project post-submit policy/compiler/Celery/repository surfaces, exact AUTH-12G +composition, the canonical durable CHECKER/POL post-submit capability source, +focused tests, and WS-POL-003 docs. + +## Not allowed + +Checker execution, review/revision behavior, new checker registration, default +checker repetition, manual reuse of agent provenance, or ART changes. + +## Acceptance + +- Continuation performs zero model invocations. +- Exact compilation, effective policy, pre-submit plan, catalogue, setup + generation, approval record ID, approval actor identity, and approval hash are + locked and revalidated. +- Any correction, replacement, catalogue change, or change to the stored + approval record/actor/hash invalidates the proposal. +- Platform-default repetition and unknown/wrong-stage checkers fail closed. +- Only registered project entries from the canonical durable CHECKER/POL + post-submit source are selectable; ART pre-submit entries cannot be selected. +- Tests explicitly reject current legacy behavior that repeats any durable + default in either required or warning project bindings. +- Compiled post-submit policy retains separate PM approval; that later approver + may differ, but cannot substitute for or alter the exact approval identity + authorizing selection of the stored proposal. + +## Verification and review + +Zero-call, invalidation, replay, approval-race, default-isolation, and atomic +evidence tests. Runtime dispatch is owned by later consumers of the chunk-07 +port. Required reviewers: all L1 tracks. diff --git a/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/chunks/WS-POL-003-07-single-checker-service-port.md b/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/chunks/WS-POL-003-07-single-checker-service-port.md new file mode 100644 index 00000000..3665cba3 --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/chunks/WS-POL-003-07-single-checker-service-port.md @@ -0,0 +1,68 @@ +# Chunk Contract: WS-POL-003-07 - Single Checker Service Port + +Status: Proposed after 06. Risk: L1. + +## Goal + +Provide one internal typed checker service port with exactly two complete +phase commands: + +- `evaluate_pre_submission(...)`, one logical attempt initiated by artifact-flow + orchestration while exact material is sealed in `ArtifactScratchManager` + custody; +- `evaluate_post_submission(...)`, one logical attempt initiated by + artifact-flow orchestration after exact verified content is durably stored, + bound, and attached to the Submission lineage. + +Each command invokes the complete canonical phase executor and returns one +typed result. The pre command is a facade over ART-04B1-04B3's existing +effective-plan execution; it does not reimplement or rerun ART entries. The +post command invokes the durable CHECKER executor. Artifact-flow callers never +select or call individual platform/project checkers. + +## Allowed files + +Checker interfaces/service/composition, project policy plan adapters, typed ART +material/result interfaces only, focused checker/project tests, and WS-POL-003 +docs. + +## Not allowed + +ART scratch/storage/provider/binding/lifecycle changes, public contributor +checker routes, caller-selected checker names, per-checker endpoints, dynamic +plugins, arbitrary code/network execution, or prepared handles in payloads. + +## Acceptance + +- The service exposes exactly one pre and one post command and no generic + `run_checker(name, ...)` product boundary. +- Pre composes mandatory ART platform entries with exact task-locked project + pre-submit entries through ART-04B1-04B3 and evaluates them once against one + sealed scratch generation. +- Post composes durable defaults with exact task-locked project post-submit + entries and evaluates them against one verified stored/bound content lineage. +- Both commands bind exact project/task/assignment, guide/policy, artifact, + manifest, generation, attempt, action, service identity, and transaction + facts; stale/replay/cross-phase/cross-resource calls fail closed. +- The port requires a deterministic attempt identity. Bounded retry/repair may + call the command again for that same logical attempt, but replay returns the + existing canonical result without rerunning completed members. A genuinely + new evaluation requires a new attempt identity; this chunk does not alter or + claim the external call sites. +- ART's pre-submit attempt/result/evidence repository is the only pre writer; + CHECKER's durable repository is the only post writer. The facade returns the + canonical result/reference and cannot persist partial or duplicate member + results. Each phase-owner repository transaction atomically claims its + attempt and commits the canonical member set, phase result, and authorization + evidence; concurrent callers observe or resume that same row. +- One bounded phase result contains every platform/project member with exact + definition/version/policy trace; infrastructure failure is never contributor + blame or a review decision. + +## Verification and review + +All-pairs phase/identity/resource denial, exact-once composition, no-individual- +dispatch reachability, timeout/cancellation, deterministic attempt replay, +scratch and stored-content contract parity, and 90% changed-subsystem coverage. +Required reviewers: all L1 tracks. Human focus: the port permits one complete +call per phase and cannot select individual checkers. diff --git a/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/chunks/WS-POL-003-08-visibility-correction-cleanup.md b/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/chunks/WS-POL-003-08-visibility-correction-cleanup.md new file mode 100644 index 00000000..a1af6bd0 --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/chunks/WS-POL-003-08-visibility-correction-cleanup.md @@ -0,0 +1,48 @@ +# Chunk Contract: WS-POL-003-08 - Visibility, Correction, and Cleanup + +Status: Proposed after 07 and AUTH-12H. Risk: L1. + +## Goal + +Expose a bounded Project Manager review package, implement generation-safe +correction, prove activation compatibility, and delete retired multi-inference +paths and parallel project-checker maps. + +## Allowed files + +Project setup visibility/correction/API/service/worker surfaces, agent +interfaces/adapters cleanup, checker project-catalogue and ordinary trigger +route cleanup, task/activation regression tests, docs, and WS-POL-003 memory. + +## Not allowed + +ART code, raw guide/model output exposure, in-place agent projection edits, +contributor compilation routes, public checker selection APIs, or compatibility +aliases. + +## Acceptance + +- Project Manager sees bounded sufficiency, policy proposals, requirements, + bindings, gaps, and safe notes without raw material. +- Correction creates a new setup generation and compilation; immutable history + remains linked and superseded. +- Existing authorized activation consumes only the complete current approved + chain. +- Three retired runtime methods/prompts and the second post-submit model call + are deleted; the canonical ART-04B1 pre-submit catalogue, canonical + CHECKER/POL post-submit catalogue, and one checker service port remain. +- OpenAPI/import/reachability tests prove ART-05B has removed the standalone + `/submission-precheck` route and remove the ordinary + caller-triggered `POST /submissions/{id}/checker-runs` execution path. A + bounded repair command may remain only by Submission/run identity and must + use the same deterministic attempt contract. +- Static/import tests find no per-checker product entry, caller-selected + checker names, dual project registry, stale terminology, or compatibility + inference path. +- Failures/gaps create no contribution, payment, or reputation evidence. + +## Verification and review + +API privacy, correction, activation, task-lock, stale wording/link, +registry/reachability, full hosted CI, and 90% changed-subsystem coverage. +Required reviewers: all L1 tracks. diff --git a/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/reviews/WS-POL-003-PLAN-internal-review-evidence.md b/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/reviews/WS-POL-003-PLAN-internal-review-evidence.md new file mode 100644 index 00000000..d03dd68f --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/reviews/WS-POL-003-PLAN-internal-review-evidence.md @@ -0,0 +1,51 @@ +# WS-POL-003 Planning Internal Review Evidence + +Reviewed baseline was reconciled after ART-04B1 merged to `origin/main` +`bb77ff4a0ab61120b94d6d4763934b444c39207d`. + +## Scope reviewed + +- Intent, discovery, plan, decisions, risks, status, chunk map, and all eight + proposed chunk contracts. +- Current project-agent, project setup, checker compiler/catalogue/effective + plan/runner/router, AUTH prepared-capability, ART PLAN5/04B1-04B3, and POL-002 + boundaries. + +## Reviewer results + +| Track | Final result | Resolution | +|---|---|---| +| Architecture | PASS WITH LOW RISKS | Clarified ART-04B1 as the unchanged complete pre-submit catalogue; collapsed duplicate status wording; preserved external call-site ownership. | +| Security | PASS WITH LOW RISKS | Added exact XINT/AUTH request+execute gate, immutable projection rules, bounded safe model input/output, and separate phase-owned evidence writers. | +| Product/operations | PASS WITH LOW RISKS | Replaced ambiguous ART-dispatch wording with artifact-flow integration at ART material boundaries; kept setup APIs distinct from execution. | +| QA/test | PASS WITH LOW RISKS | Made pre command a facade over ART-04B1-04B3, named sole pre/post evidence writers, added default-repetition tests, and strengthened chunk-07 dependency. | + +After PR #276 merged, the plan was reconciled again against the implemented +`PreSubmissionCheckerCatalogue`, exact v0.1 manifest, pure effective-plan +compiler, and PLAN5 route-removal sequence before the PR head was refreshed. +The final architecture review passed. Final QA and security reviews identified +the same non-blocking precision issue: preserve disabled advisory entries in +the full manifest and consume phase-owned resource controls without inventing +a pre-submit per-entry timeout. Both corrections are incorporated. + +CodeRabbit then identified eight concurrency, idempotency, approval-binding, +and transaction-boundary gaps. The plan now defines database uniqueness and +compare-and-swap, one durable provider attempt/key per setup generation, +timeout-after-acceptance recovery, exact approval identity, phase-owned checker +attempt claims, and one root transaction consuming all separate PREPs. Fresh +architecture, security, QA, and product/operations rereviews all passed with no +remaining findings. + +No blocking finding remains. All reviewer sessions completed. + +## Checks + +- `python3 scripts/check_markdown_links.py` — passed. +- `python3 scripts/check_stale_workstream_wording.py` — passed. +- Targeted `scripts/check_stale_authorization_docs.py` scan of all 17 planning + files — passed. +- `git diff --check` — passed. +- Temporary root draft `latest_new_addtion_plan.md` — deleted. + +No application code, migration, workflow, coverage threshold, or runtime +behavior changed in this planning-only chunk. diff --git a/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/reviews/WS-POL-003-PLAN-pr-trust-bundle.md b/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/reviews/WS-POL-003-PLAN-pr-trust-bundle.md new file mode 100644 index 00000000..20fc7b73 --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/reviews/WS-POL-003-PLAN-pr-trust-bundle.md @@ -0,0 +1,80 @@ +# WS-POL-003 Planning PR Trust Bundle + +## Chunk + +`WS-POL-003-PLAN` — Unified Project Guide Compilation planning. + +## Goal and human-approved intent + +Replace three complete Project Guide inference passes with one bounded unified +compilation per immutable setup generation, while retaining separate canonical +policy objects, approvals, authorization boundaries, and checker ownership. + +Provide one internal typed checker-service facade with one complete pre-submit +command at sealed-scratch custody and one complete post-submit command after +verified storage/binding. No caller selects or invokes individual checkers. + +## What changed and why + +- Added the complete WS-POL-003 intent, discovery, plan, decisions, risks, + status, and eight bounded implementation contracts. +- Consumed merged ART-04B1's exact catalogue/effective-plan contract and + preserved future ART-04B2/04B3 as the sole pre-submit executor/evidence + writer, with durable CHECKER/POL as the post-submit owner. +- Added exact future XINT/AUTH compilation request/execute custody before + persistence can start. +- Made unified agent projections immutable, safe-text bounded, capability + closed-world, and generation/hash bound. +- Deleted the temporary root planning draft after incorporating its valid intent. + +The original draft had the right product direction but stale baseline, +ambiguous correction provenance, under-specified fixed-service authority, and +unclear phase execution/evidence ownership. + +## Design and scope control + +- One model invocation; no model policy authority. +- ART's complete pre-submit catalogue is consumed unchanged. +- No new checker registry, dynamic plugin, generated code, or compatibility path. +- Pre facade delegates once to ART and persists no duplicate evidence. +- Post facade uses CHECKER's sole durable writer. +- No application code, API, database, migration, workflow, or CI change. + +Rejected alternatives include three repeated inference calls, one combined +canonical policy object, in-place edits to agent projections, broad compilation +authority, POL-local pre-submit maps, and per-checker product APIs. + +## Acceptance evidence and test delta + +This is documentation/planning only. Markdown links, stale wording, and diff +integrity pass. There is no runtime test delta and no CI or coverage weakening. + +## Reviewer results and external review + +Architecture, security, product/operations, and QA all pass with low residual +dependency-discipline risks after repairs. CodeRabbit and hosted CI are pending +on the PR head. + +## Remaining risks and follow-up + +- Implementation must honor every dependency gate; planning does not activate + any action or chunk. +- Exact XINT/AUTH compilation request/execute activation must merge before + WS-POL-003-03. +- ART-04B2/04B3 must merge and be callable behind merged ART-04B1 before the + checker facade chunk. +- Each implementation chunk requires separate human start, evidence, review, + PR, and human merge. + +## Human review focus + +- Does one unified inference preserve separate policy and approval truth? +- Is ART pre-submit ownership unchanged and free of duplicate evidence? +- Is post-submit authority confined to durable CHECKER/POL ownership? +- Are capability gaps, correction, replay, and stale generation fail-closed? +- Are the eight chunks genuinely bounded and correctly dependency-gated? + +## Human merge ownership + +This PR must be merged only after explicit human approval. Merge authorizes the +plan record only; it does not start an implementation chunk.