WS-POL-003-02: add unified project guide agent adapter

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

@@ -1,8 +1,9 @@
 # Chunk Map: WS-POL-003 - Unified Project Guide Compilation
 
-All chunks are L1, one PR each, proposed, and inactive. Product behavior is
-built hidden before AUTH activation; only a later live-cutover chunk exposes
-it. No chunk starts automatically.
+All chunks are L1 and one PR each. POL-01 is merged, POL-02 is active after its
+explicit human start, and later chunks remain proposed and inactive. Product
+behavior is built hidden before AUTH activation; only a later live-cutover
+chunk exposes it. No chunk starts automatically.
 
 | Chunk | Purpose | Hard dependency |
 |---|---|---|

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

@@ -1,9 +1,10 @@
 # Status: WS-POL-003 - Unified Project Guide Compilation
 
-Status: planning reconciliation active; no implementation chunk is active.
+Status: `WS-POL-003-02` implementation and internal review complete; awaiting
+external review and human merge.
 
-Baseline: `origin/main` `99c0aaf04efd36c7ac4af4aeec2e9d810f012305`
-after merged AUTH-12F3 PR #295.
+Baseline: `origin/main` `fb90237de499ec6d46ad7dfe1eee649f31857fd1`
+after merged `WS-POL-003-01` PR #299.
 
 ## Current delivery truth
 
@@ -26,7 +27,7 @@ after merged AUTH-12F3 PR #295.
 |---|---|---|
 | ART-04B1 complete pre-submit catalogue/effective plan | POL-01 | Merged PR #276 |
 | Canonical CHECKER/POL post-submit registry | POL-01 | Present; remaining POL-002 work must be reframed as executor ownership, not inference |
-| POL-01/02 strict manifest and adapter | POL-03A | Proposed |
+| POL-01/02 strict manifest and adapter | POL-03A | POL-01 merged; POL-02 awaiting external review and human merge |
 | Hidden POL-03A compilation manifest | AUTH-12I compilation request/execute activation | Proposed |
 | AUTH-12I | POL-03B authorized persistence | Not yet implemented |
 | Hidden POL-04A unified setup-service manifest | AUTH-12B2 setup-ledger activation | Not yet implemented |
@@ -37,13 +38,11 @@ after merged AUTH-12F3 PR #295.
 
 ## Chunk state
 
-POL-01 and POL-02 retain their full executable contracts. The newly split
+POL-01 is merged and POL-02 is active. The newly split
 03A-06B and corresponding AUTH gates are reviewed planning skeletons only:
 before any is started, its contract must be expanded on then-current main with
 explicit allowed/not-allowed paths, runnable verification commands, and named
 reviewer tracks. They cannot authorize implementation in their current form.
 
-All WS-POL-003 chunks and corresponding AUTH gates are proposed and inactive.
-The current work is planning-only. The first executable candidate after this
-planning PR merges is `WS-POL-003-01`, subject to a separate explicit start and
-fresh preimplementation review.
+All later WS-POL-003 chunks and corresponding AUTH gates remain proposed and
+inactive. No later chunk starts automatically.

.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/chunks/WS-POL-003-02-unified-agent-adapter.md

@@ -1,6 +1,7 @@
 # Chunk Contract: WS-POL-003-02 - Unified Agent Adapter
 
-Status: Proposed after 01. Risk: L1.
+Status: Implementation and internal review complete; awaiting external review
+and human merge. Risk: L1.
 
 ## Goal
 
@@ -10,24 +11,69 @@ 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.
+- `backend/app/interfaces/project_agents.py`
+- `backend/app/adapters/project_agents/openai_agent_sdk.py`
+- `backend/tests/test_agent_runtime.py`
+- `.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/CHUNK_MAP.md`
+- `.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/STATUS.md`
+- `.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/chunks/WS-POL-003-02-unified-agent-adapter.md`
+- `.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/reviews/WS-POL-003-02-internal-review-evidence.md`
+- `.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/reviews/WS-POL-003-02-pr-trust-bundle.md`
 
 ## Not allowed
 
-Database, authorization, Celery orchestration, policy approval, registry, or checker runtime
-changes; no provider trace persistence or tool/network capability.
+Database models or migrations; authorization; Celery or production service
+orchestration; policy approval/persistence; registry or checker runtime;
+composition-root/runtime selection; dependencies; provider trace persistence;
+tools, network/file capabilities, or live cutover. The three transitional
+runtime methods and their callers remain unchanged until their cutover chunk.
 
 ## Acceptance
 
 - One method consumes the canonical context and returns the strict result.
+- The unified method uses provider-level `strict_json_schema=True`; the helper
+  may remain non-strict only for the transitional legacy policy method.
 - Guide/task contents remain untrusted data and cannot alter instructions.
 - Prompt/input limits, timeout, cancellation, and sanitized error behavior are
   preserved.
+- The complete unified prompt is capped at 16 MiB. Trusted serialization parses
+  the already-canonical guide payload into the prompt envelope instead of
+  double-encoding it as a JSON string, leaving bounded room above the 12 MiB
+  verified ART material limit for canonical catalogue/context overhead;
+  oversized envelopes fail before provider I/O.
 - Agent cannot emit code, commands, URLs, capabilities outside the projection,
   or approval decisions.
+- The adapter applies the merged trusted result validator before returning.
+- Existing runtime methods and production callers remain behaviorally unchanged.
+- Fake-SDK proof records exactly one `Runner.run` call, strict output wrapping
+  for `ProjectGuideCompilationResult`, and absence of tools, handoffs, MCP,
+  file-search, web-search, or equivalent capability configuration.
+- The unified call supplies a per-run SDK configuration with tracing disabled
+  and sensitive trace capture excluded; provider tracing is not a persistence
+  path for guide context or results.
+- Tests prove context-bound trusted validation happens before return and rejects
+  semantically invalid provider output.
 
 ## Verification and review
 
-Fake-runtime, injection, timeout/cancellation, and serialization tests. Required
-reviewers: security, architecture, QA, product, test delta, CI integrity.
+Commands:
+
+```bash
+cd backend
+uv run ruff check app/interfaces/project_agents.py app/adapters/project_agents/openai_agent_sdk.py tests/test_agent_runtime.py
+uv run pytest -q tests/test_agent_runtime.py tests/test_project_guide_compilation_contracts.py
+uv run docstr-coverage --config .docstr.yaml
+git diff --name-only origin/main
+git diff --check
+```
+
+Hosted GitHub Backend lanes own the full Postgres-backed suite and repository
+coverage proof; no local full suite is required.
+
+Required reviewers: security, architecture, QA, product/operations, test delta,
+CI integrity, and senior engineering.
+
+Human review focus: confirm one provider call with strict structured output,
+no tool/network surface, untrusted material isolation, context-bound trusted
+validation, cancellation propagation, sanitized failures, and no production
+orchestration/caller rewiring.

.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/reviews/WS-POL-003-02-internal-review-evidence.md

@@ -0,0 +1,39 @@
+# WS-POL-003-02 Internal Review Evidence
+
+Date: 2026-08-08. Risk: L1.
+
+## Deterministic evidence
+
+- Scoped Ruff: passed.
+- Focused compilation, adapter, and adjacent legacy regressions: 79 passed.
+- Changed adapter coverage: 91.89 percent, above the 90 percent requirement.
+- Real installed OpenAI Agents SDK accepted the strict result schema and the
+  tracing-disabled `RunConfig` fields.
+- Repository docstring coverage: 80.5 percent, above the 80 percent gate.
+- Stale wording, Markdown links, diff integrity, lane ownership, and strict
+  allowed-file scope checks: passed.
+- No workflow, dependency, lockfile, package script, coverage threshold, skip,
+  xfail, database, authorization, Celery, registry, checker, or production
+  caller change exists.
+
+## Review results
+
+- Architecture: pass; one existing port/adapter method, contract-owned
+  canonical serialization, no production rewiring or competing abstraction.
+- Security: pass after strict provider schema, explicit tool-free construction,
+  provider tracing disablement, sensitive trace exclusion, and fail-closed
+  context-bound validation were proved.
+- QA: pass after adding a dedicated unified envelope cap and preventing
+  double-encoding of large escapable canonical guide material.
+- Product/operations: pass; the result remains an untrusted proposal and makes
+  no approval, activation, review, payment, contribution, or reputation
+  decision.
+- Senior engineering: pass after canonical prompt serialization aligned every
+  accepted sub-12-MiB guide with the bounded unified envelope.
+- Test delta: pass; tests are additive with no removed, skipped, or weakened
+  assertions.
+- CI integrity: pass; commands and lane ownership are correct and no gate was
+  weakened.
+
+All High findings were corrected and re-reviewed. No reviewer session remains
+open.

.agent-loop/initiatives/WS-POL-003-unified-project-guide-compilation/reviews/WS-POL-003-02-pr-trust-bundle.md

@@ -0,0 +1,53 @@
+# WS-POL-003-02 PR Trust Bundle
+
+## Goal and design
+
+Add one hidden `compile_project_guide` runtime method that sends the merged
+strict context through exactly one provider call and validates the complete
+untrusted result before returning. The existing adapter/helper is reused; no
+second runtime, registry, compiler, or production path is introduced.
+
+The unified call uses provider-level strict JSON schema, no tools/handoffs/MCP
+or search capability, a tracing-disabled sensitive-data-excluding per-run
+configuration, a 16 MiB complete-envelope cap, deterministic canonical prompt
+serialization without double-encoding guide JSON, timeout/cancellation, and
+sanitized failures.
+
+## Scope
+
+Changed runtime files are limited to the project-agent protocol, OpenAI adapter,
+and focused fake-runtime tests. Initiative status, contract, and review evidence
+are updated with them. No database, migration, AUTH, Celery, API, service
+orchestration, policy persistence/approval, catalogue, checker runtime,
+dependency, composition root, production caller, or live-cutover change exists.
+
+## Acceptance proof
+
+- Exactly one `Runner.run` call and one strict `ProjectGuideCompilationResult`
+  schema wrapper are asserted.
+- Canonical prompt input remains untrusted and is separated from instructions.
+- No tool/network/file/handoff/MCP/search configuration is supplied.
+- Provider tracing and sensitive trace data are explicitly disabled.
+- Trusted semantic validation rejects shaped but invalid results before return.
+- A valid near-bound quote-heavy guide that previously expanded above 16 MiB
+  now serializes once below the bound; oversized envelopes deny before SDK I/O.
+- Timeout is sanitized and caller cancellation propagates.
+- Legacy runtime behavior and production call sites remain unchanged.
+
+## Evidence and reviews
+
+- Ruff passed.
+- 79 focused/adjacent tests passed.
+- Changed adapter coverage: 91.89 percent.
+- Docstring coverage: 80.5 percent.
+- Architecture, security, QA, product/operations, senior engineering, test
+  delta, and CI integrity reviews passed after fixes.
+- Stale wording, Markdown links, scope, lane ownership, and diff checks passed.
+
+## Remaining risk and human focus
+
+This method is deliberately hidden and unused. Later persistence/orchestration
+chunks must preserve one logical attempt and must not enable provider tracing,
+tools, or a second inference path. Human review should focus on canonical prompt
+fidelity, the no-trace/no-tools boundary, result validation, cancellation/error
+semantics, and absence of production rewiring.