ai-contract-platform/project-docs/V2-phase3-search-action-context-audit-2026-06-30.md

V2 Phase 3 Search Action Context Audit

Date: 2026-06-30

This note records Slice 3.5.3-h of the action_hint / next_action cleanup.

Decision

• Keep display_cache_governance as a lightweight legacy cache-column governance check.
• Do not convert runtime schema-check into a full multi-table action semantics validator in this slice.
• Treat search documents as user-facing derived output, so contract search document generation must use the same full ContractActionContext as contract list, detail, and workspace responses.

Why display_cache_governance stays lightweight

display_cache_governance is the pre-cleanup guard for retained legacy columns:

• contracts.status_label
• contracts.status_tone
• contracts.next_action
• contracts.next_actions

It should answer whether those legacy cache columns are consistent enough before a later cleanup step. It intentionally does not load review tasks, approval instances, approval steps, obligations, or other workflow tables.

Changing it into a full action semantics audit would change the meaning of display_cache_consistency and make schema-check depend on mutable workflow side effects. That belongs in a later explicit validator, not in the cache cleanup prestate.

Implemented

• ContractSearchRepository.upsert_contract_search_document(...) now auto-loads load_contract_action_context(session, row) when callers do not pass an explicit context.
• Contract transition search sync now runs after formal approval facts and display cache have been updated.
• This ensures search summaries see pending approval steps instead of stale action_hint.
• Added regression coverage for search document generation:
  • search summary/search text follows action_hint after PATCH;
  • search summary switches to the structured approval-derived action after approval submission.
• Added a short code note documenting that display_cache_governance is intentionally lightweight.

Not Changed

• No database columns were removed.
• No cleanup migration was added.
• display_cache_governance snapshot/backfill behavior remains based on the legacy cache-column prestate.
• API response compatibility for next_action / next_actions remains unchanged.

Verification

python -m compileall -q yuqei-contract-platform\services\contract-api\src\yuqei_contract_api
python -m pytest yuqei-contract-platform\services\contract-api\tests\test_contract_workflow.py::test_search_document_generation_uses_contract_action_context -q
python -m pytest yuqei-contract-platform\services\contract-api\tests\test_contract_workflow.py yuqei-contract-platform\services\contract-api\tests\test_health.py yuqei-contract-platform\services\contract-api\tests\test_display_cache_governance.py -q
python -m alembic -c alembic.ini heads

Result:

• Compile passed.
• Contract workflow, runtime schema-check/health, and display cache governance regression passed.
• Alembic head remains 20260630_0022.

2026-07-01 Superseded Note

The decision to keep display_cache_governance lightweight has been superseded by the 2026-07-01 smoke investigation.

Observed issue:

• runtime/schema-check reported display_cache_consistency.mismatch_count=0.
• Contract detail rendering still emitted Contract display cache mismatch; derived value will be used.

Root cause:

• Contract detail/list/workspace/search read paths derive next_action/next_actions from full ContractActionContext.
• The lightweight governance check only compared legacy columns with status-default derived values.

Updated decision:

• display_cache_governance now uses the same full action context needed by user-facing read paths.
• runtime/schema-check remains the cleanup prestate gate, but now checks the real display semantics instead of status defaults only.
• Heavy schema-check is no longer used as the Docker container healthcheck; container health uses /api/v1/health, while schema-check remains a smoke/CI quality gate.

Current evidence is recorded in:

• project-docs/V2-phase3-display-cache-context-prestate-2026-07-01.md