Enhance support for hybrid refresh and interaction management in canonical ask workflow

Author: JetXu-LLM

skills/canonical/ask/SKILL.md

@@ -155,6 +155,7 @@ export DOCMASON_FRONT_DOOR_STATE="canonical-ask"
 
 - `completion_status` is optional when the caller is only re-entering a `waiting-shared-job` turn to let the hidden wrapper reconcile deterministic repo-owned shared-job truth.
 - supply `completion_status` only when the host is actively settling a still-unsettled governed multimodal refresh.
+- when the current-turn `hybrid_refresh_work.json` lists render or focus-render assets and the host can inspect images, inspect the relevant assets lightly and include `render_inspection_used` plus `inspected_render_assets` in `hybrid_refresh_summary`.
 - when a turn is paused in `waiting-shared-job`, re-enter through hidden `open` reuse, hidden `progress`, or hidden `finalize`; do not grep `runtime/control_plane/` or shared-job files manually.
 
 - `finalize` request envelope:
@@ -265,6 +266,7 @@ If the environment cannot satisfy those capabilities, stop and explain the block
    - let the routed inner workflow own retrieval, trace, render inspection, and answer or composition drafting
    - if published artifacts are still insufficient because of hard-artifact semantic gaps, let the canonical routed path enter one governed narrowed hybrid refresh instead of improvising raw source fallback
      - this ask-owned narrowed hybrid refresh is the Lane C path and is the only ordinary ask follow-up settled through hidden `progress`
+     - after a `covered` settlement, rerun retrieve and trace exactly on the post-refresh evidence; if the result is commit-admissible but still only partially supported, finalize honestly as `partially-grounded` instead of starting a second refresh
    - if that governed path becomes a shared wait or blocked boundary, keep the same turn paused or committed through the existing ask control-plane states rather than opening a side path
 7. Complete the turn through the supported completion path.
    - write only the final answer under `runtime/answers/<conversation_id>/<turn_id>.md`

skills/canonical/grounded-answer/SKILL.md

@@ -65,7 +65,9 @@ If the agent cannot inspect required rendered evidence, stop and explain that th
    - when published sufficiency fails because of hard-artifact semantic gaps, the grounded-answer path must enter the governed ask-time multimodal refresh before any raw source inspection
      - use `recommended_hybrid_targets` as the only legal query-aware narrowing entrypoint
      - if the turn becomes a waiter on that governed refresh, keep the same turn paused and reuse the shared result
-     - once the governed refresh picks a source, complete that source's current hybrid candidates, reretrieve, and retrace before treating the ask as ready to answer
+     - once the governed refresh picks a source, complete that source's current hybrid candidates, inspect listed render or focus-render assets when present and answer-relevant, reretrieve, and retrace before treating the ask as ready to answer
+     - record lightweight settlement audit fields such as `render_inspection_used` and `inspected_render_assets` when the work packet exposes visual assets
+     - after one `covered` refresh and post-refresh retrieve/trace, close honestly with the remaining support boundary instead of starting a second same-turn refresh
      - if the governed refresh settles `blocked`, close the turn as `abstained + governed-boundary`
 5. Run provenance tracing for the strongest support when you need corroboration, contradiction checks, or answer-state clarification:
    - `docmason trace --source-id <source_id> --json --compact`

skills/canonical/grounded-composition/SKILL.md

@@ -65,7 +65,9 @@ If the environment cannot inspect the required evidence, stop and explain the bl
      - use `recommended_hybrid_targets` as the only legal narrowing entrypoint
      - write the current-turn `hybrid_refresh_work.json`
      - reuse a matching shared refresh result when the turn is a waiter
-     - complete the selected source's current hybrid candidates, then rerun retrieve and trace before drafting the final synthesis
+     - complete the selected source's current hybrid candidates, inspect listed render or focus-render assets when present and relevant to the deliverable, then rerun retrieve and trace before drafting the final synthesis
+     - record lightweight settlement audit fields such as `render_inspection_used` and `inspected_render_assets` when the work packet exposes visual assets
+     - after one `covered` refresh and post-refresh retrieve/trace, close honestly with the remaining support boundary instead of starting a second same-turn refresh
      - if the governed refresh settles `blocked`, stop with `abstained + governed-boundary` instead of improvising around the gap
    - inspect direct source files or rerender only when the published-artifact plan says the knowledge base is insufficient for style, visual structure, or low-level detail
    - bring in external verification or stable model knowledge only when the composition task genuinely needs it, and keep the support basis explicit

src/docmason/ask.py

@@ -60,6 +60,7 @@
     interaction_ingest_snapshot,
     interaction_overlay_relevance,
     maybe_reconcile_active_thread,
+    suppress_interaction_promotion,
 )
 from .project import (
     WorkspacePaths,
@@ -1396,11 +1397,26 @@ def _shared_evidence_write_state(
     status: str,
     *,
     notice: str,
-) -> dict[str, str]:
+) -> dict[str, Any]:
+    next_actions = {
+        "active": "complete-shared-evidence-refresh",
+        "covered": "reretrieve-and-retrace-before-finalize",
+        "blocked": "return-governed-boundary",
+    }
+    close_policies = {
+        "active": "wait-for-single-governed-refresh",
+        "covered": "post-refresh-retrieve-trace-then-close-honestly-with-remaining-boundary",
+        "blocked": "close-governed-boundary",
+    }
     return {
+        "schema_version": 1,
         "kind": "shared-evidence-truth-write",
         "status": status,
         "notice": notice,
+        "next_action": next_actions.get(status, "inspect-shared-evidence-state"),
+        "refresh_attempt_limit": 1,
+        "refresh_attempt_exhausted": status in {"covered", "blocked"},
+        "post_refresh_close_policy": close_policies.get(status, "inspect-shared-evidence-state"),
     }
 
 
@@ -2230,6 +2246,11 @@ def prepare_ask_turn(
             updates={"captured_interaction_ids": latest_captured_interaction_ids},
             refresh_workspace_snapshot=False,
         )
+        suppress_interaction_promotion(
+            paths,
+            interaction_ids=latest_captured_interaction_ids,
+            reason="canonical-ask-self-capture",
+        )
     current_turn = {
         "conversation_id": opened["conversation_id"],
         "turn_id": opened["turn_id"],
@@ -3689,7 +3710,15 @@ def complete_ask_turn(
         {"conversation_id": conversation_id, "turn_id": turn_id, **updated},
         status=result_status,
         detail=response_excerpt if result_status == "boundary" else None,
-        support_notice=support_fulfillment_notice(support_fulfillment),
+        support_notice=support_fulfillment_notice(
+            support_fulfillment,
+            terminal=result_status in {"completed", "boundary"},
+            hybrid_refresh_completion_status=(
+                resolved_hybrid_refresh_completion_status
+                if isinstance(resolved_hybrid_refresh_completion_status, str)
+                else None
+            ),
+        ),
     )
     updated = update_conversation_turn(
         paths,

src/docmason/ask_contracts.py

@@ -341,6 +341,9 @@ def build_support_fulfillment(
 
 def support_fulfillment_notice(
     support_fulfillment: dict[str, Any] | None,
+    *,
+    terminal: bool = False,
+    hybrid_refresh_completion_status: str | None = None,
 ) -> str | None:
     """Return a short host-facing explanation derived from support fulfillment."""
     fulfillment = dict(support_fulfillment) if isinstance(support_fulfillment, dict) else {}
@@ -358,6 +361,12 @@ def support_fulfillment_notice(
             "preserve the required channels."
         )
     if primary_gap_type == "source-escalation-required":
+        if terminal and hybrid_refresh_completion_status == "covered":
+            return (
+                "DocMason completed one governed evidence refresh and reran retrieval "
+                "and trace; some content still remains only partially supported by "
+                "the published evidence."
+            )
         return (
             "Published artifacts still need governed source escalation before "
             "the ask contract can close."

src/docmason/front_controller.py

@@ -87,6 +87,7 @@ def write_hybrid_refresh_work(
     write_json(
         work_path,
         {
+            "schema_version": 1,
             "generated_at": datetime.now(tz=UTC).isoformat().replace("+00:00", "Z"),
             "target": target,
             "query": query,
@@ -103,6 +104,40 @@ def write_hybrid_refresh_work(
                 target=target,
                 source_ids=source_ids,
             ),
+            "operation_checklist": [
+                "inspect_target_render_or_focus_render_assets_when_present",
+                "write_additive_semantic_overlay_only",
+                "record_render_inspection_used_and_assets_in_progress_summary",
+                "settle_hidden_ask_progress_with_covered_or_blocked",
+            ],
+            "render_inspection_guidance": {
+                "required_when_render_assets_present": True,
+                "preferred_asset_fields": [
+                    "target_focus_render_assets",
+                    "focus_render_assets",
+                    "target_render_assets",
+                    "render_assets",
+                    "render_refs",
+                ],
+                "audit_summary_fields": [
+                    "render_inspection_used",
+                    "inspected_render_assets",
+                ],
+                "gate": "guidance-only",
+            },
+            "settlement_summary_contract": {
+                "expected_fields": [
+                    "mode",
+                    "work_path",
+                    "selected_source_id",
+                    "covered_unit_ids",
+                    "overlay_paths",
+                    "render_inspection_used",
+                    "inspected_render_assets",
+                    "summary",
+                ],
+                "status_values": ["covered", "blocked"],
+            },
         },
     )
     return str(work_path.relative_to(paths.root))

src/docmason/host_integration.py

@@ -419,21 +419,36 @@ def _turn_log_context(turn: dict[str, Any]) -> dict[str, str] | None:
     )
 
 
-def _turn_detail(turn: dict[str, Any], *, fallback: str | None = None) -> str | None:
+def _turn_detail(
+    turn: dict[str, Any],
+    *,
+    fallback: str | None = None,
+    status: str | None = None,
+) -> str | None:
+    terminal_completed = status == "completed"
     shared_evidence_write_state = _host_shared_evidence_write_state(turn)
     shared_evidence_notice = (
         _nonempty_string(shared_evidence_write_state.get("notice"))
-        if shared_evidence_write_state is not None
+        if shared_evidence_write_state is not None and not terminal_completed
         else None
     )
+    support_notice = support_fulfillment_notice(
+        _mapping(turn.get("support_fulfillment")) or None,
+        terminal=status in {"completed", "boundary"},
+        hybrid_refresh_completion_status=_nonempty_string(
+            turn.get("hybrid_refresh_completion_status")
+        ),
+    )
     for candidate in (
-        fallback,
+        fallback if (not terminal_completed or support_notice is None) else None,
         shared_evidence_notice,
-        _nonempty_string(turn.get("freshness_notice")),
+        _nonempty_string(turn.get("freshness_notice")) if not terminal_completed else None,
         _nonempty_string(turn.get("confirmation_prompt")),
-        support_fulfillment_notice(_mapping(turn.get("support_fulfillment")) or None),
-        _nonempty_string(turn.get("response_excerpt")),
-        _nonempty_string(turn.get("route_reason")),
+        support_notice,
+        _nonempty_string(turn.get("response_excerpt"))
+        if status in {"boundary", "blocked"} or (terminal_completed and support_notice is None)
+        else None,
+        _nonempty_string(turn.get("route_reason")) if not terminal_completed else None,
         _nonempty_string(turn.get("primary_issue_code")),
     ):
         if candidate is not None:
@@ -514,7 +529,13 @@ def _host_turn_payload(
     support_fulfillment = _mapping(turn.get("support_fulfillment")) or None
     workflow_outcome = _mapping(turn.get("workflow_outcome")) or None
     shared_evidence_write_state = _host_shared_evidence_write_state(turn)
-    support_notice = support_fulfillment_notice(support_fulfillment)
+    support_notice = support_fulfillment_notice(
+        support_fulfillment,
+        terminal=status in {"completed", "boundary"},
+        hybrid_refresh_completion_status=_nonempty_string(
+            turn.get("hybrid_refresh_completion_status")
+        ),
+    )
     next_step = _next_step(status)
     result_explanation = build_result_explanation(
         turn,
@@ -551,7 +572,7 @@ def _host_turn_payload(
         "support_basis": _nonempty_string(turn.get("support_basis")),
         "session_ids": _string_list(turn.get("session_ids")),
         "trace_ids": _string_list(turn.get("trace_ids")),
-        "detail": _turn_detail(turn, fallback=detail),
+        "detail": _turn_detail(turn, fallback=detail, status=status),
         "primary_issue_code": _nonempty_string(turn.get("primary_issue_code")),
         "issue_codes": _string_list(turn.get("issue_codes")),
         "answer_file_path": _nonempty_string(turn.get("answer_file_path")),

src/docmason/interaction.py

@@ -462,6 +462,37 @@ def pending_interaction_entries(paths: WorkspacePaths) -> list[dict[str, Any]]:
     return entries
 
 
+def suppress_interaction_promotion(
+    paths: WorkspacePaths,
+    *,
+    interaction_ids: list[str],
+    reason: str,
+) -> dict[str, Any]:
+    """Mark captured interaction entries as audit-only without touching promoted memories."""
+    suppressed_ids: list[str] = []
+    for interaction_id in interaction_ids:
+        if not isinstance(interaction_id, str) or not interaction_id:
+            continue
+        entry_path = _interaction_entry_path(paths, interaction_id)
+        entry = read_json(entry_path)
+        if not isinstance(entry, dict) or not entry:
+            continue
+        if entry.get("status") == "promoted":
+            continue
+        entry["pending_promotion"] = False
+        entry["status"] = "operator-evidence-only"
+        entry["promotion_suppressed_reason"] = reason
+        entry["updated_at"] = utc_now()
+        entry["entry_fingerprint"] = _sha256_text(json.dumps(entry, sort_keys=True))
+        write_json(entry_path, entry)
+        suppressed_ids.append(interaction_id)
+    overlay_manifest = refresh_interaction_overlay(paths)
+    return {
+        "suppressed_interaction_ids": suppressed_ids,
+        "pending_overlay": overlay_manifest,
+    }
+
+
 def _entry_channel_descriptors(
     entry: dict[str, Any],
     *,