---
phase: 01-topic-start-hardening
plan: 02
type: execute
wave: 1
depends_on: []
files_modified:
  - research/knowledge-hub/runtime/scripts/sync_topic_state.py
  - research/knowledge-hub/runtime/scripts/orchestrate_topic.py
  - research/knowledge-hub/runtime/README.md
  - research/knowledge-hub/tests/test_runtime_scripts.py
autonomous: true
requirements:
  - STAT-01
  - STAT-02
  - STAT-03
user_setup: []
must_haves:
  truths:
    - Runtime state exposes a machine-readable explanation of why the topic is where it is.
    - Human-facing runtime surfaces render current route choice, last evidence return, active human need, and blocker summary from durable state.
    - A later session can answer status questions from current runtime artifacts without reconstructing old chat.
  artifacts:
    - path: research/knowledge-hub/runtime/scripts/sync_topic_state.py
      provides: Machine-readable status_explainability synthesis
      min_lines: 250
      contains: "derive_status_explainability"
    - path: research/knowledge-hub/runtime/scripts/orchestrate_topic.py
      provides: Operator-console rendering for explainability fields
      contains: "## Topic explainability"
    - path: research/knowledge-hub/tests/test_runtime_scripts.py
      provides: Regression coverage for explainability rendering
      contains: "status_explainability"
  key_links:
    - from: research/knowledge-hub/runtime/scripts/sync_topic_state.py
      to: research/knowledge-hub/runtime/scripts/orchestrate_topic.py
      via: `status_explainability` payload rendered into operator-facing markdown
      pattern: "status_explainability"
    - from: research/knowledge-hub/runtime/scripts/sync_topic_state.py
      to: research/knowledge-hub/tests/test_runtime_scripts.py
      via: runtime-script regression tests
      pattern: "derive_status_explainability|status_explainability"
---

<objective>
Expose truthful status explainability across the machine-readable runtime state
and human-facing runtime views.

Purpose: Make later resume/status questions answerable from durable artifacts
instead of chat reconstruction.
Output: Updated runtime explainability synthesis, markdown rendering, runtime
docs, and regression coverage.
</objective>

<execution_context>
@D:/BaiduSyncdisk/Theoretical-Physics/.codex-home/get-shit-done/workflows/execute-plan.md
@D:/BaiduSyncdisk/Theoretical-Physics/.codex-home/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/01-topic-start-hardening/01-CONTEXT.md
@research/knowledge-hub/runtime/scripts/sync_topic_state.py
@research/knowledge-hub/runtime/scripts/orchestrate_topic.py
@research/knowledge-hub/runtime/README.md
@research/knowledge-hub/tests/test_runtime_scripts.py
</context>

<tasks>

<task type="auto">
  <name>Task 1: Build machine-readable status explainability</name>
  <files>research/knowledge-hub/runtime/scripts/sync_topic_state.py</files>
  <read_first>research/knowledge-hub/runtime/scripts/sync_topic_state.py, .planning/phases/01-topic-start-hardening/01-CONTEXT.md, research/knowledge-hub/runtime/README.md</read_first>
  <action>Add or refine a single `status_explainability` synthesis path in `sync_topic_state.py` that collects `why_this_topic_is_here`, `current_route_choice`, `last_evidence_return`, `active_human_need`, `blocker_summary`, and `next_bounded_action` from the current runtime artifacts. Keep the values truthful: missing durable artifacts should produce explicit limitation-heavy summaries rather than fabricated certainty.</action>
  <verify>python -m pytest research/knowledge-hub/tests/test_runtime_scripts.py -q</verify>
  <acceptance_criteria>
    - research/knowledge-hub/runtime/scripts/sync_topic_state.py contains `derive_status_explainability`
    - research/knowledge-hub/runtime/scripts/sync_topic_state.py contains `why_this_topic_is_here`
    - research/knowledge-hub/runtime/scripts/sync_topic_state.py contains `last_evidence_return`
  </acceptance_criteria>
  <done>The runtime state carries a stable machine-readable answer surface for topic status questions.</done>
</task>

<task type="auto">
  <name>Task 2: Render explainability into operator-facing runtime surfaces</name>
  <files>research/knowledge-hub/runtime/scripts/orchestrate_topic.py, research/knowledge-hub/runtime/README.md, research/knowledge-hub/tests/test_runtime_scripts.py</files>
  <read_first>research/knowledge-hub/runtime/scripts/orchestrate_topic.py, research/knowledge-hub/runtime/README.md, research/knowledge-hub/tests/test_runtime_scripts.py, research/knowledge-hub/runtime/scripts/sync_topic_state.py</read_first>
  <action>Render the synthesized explainability fields into operator-facing markdown in `orchestrate_topic.py` and the runtime resume surface, then align `runtime/README.md` with the machine-readable contract. Extend `test_runtime_scripts.py` so the explainability sections and key strings are asserted directly instead of relying on manual inspection.</action>
  <verify>python -m pytest research/knowledge-hub/tests/test_runtime_scripts.py -q</verify>
  <acceptance_criteria>
    - research/knowledge-hub/runtime/scripts/orchestrate_topic.py contains `## Topic explainability`
    - research/knowledge-hub/runtime/README.md contains `status_explainability`
    - `python -m pytest research/knowledge-hub/tests/test_runtime_scripts.py -q` exits 0
  </acceptance_criteria>
  <done>Human-facing runtime views and docs expose the same explainability contract as the machine-readable state.</done>
</task>

</tasks>

<verification>
Before declaring plan complete:
- [ ] `python -m pytest research/knowledge-hub/tests/test_runtime_scripts.py -q`
- [ ] `status_explainability` fields render into both resume and operator-console surfaces.
- [ ] Missing evidence or human checkpoints remain explicit rather than silently omitted.
</verification>

<success_criteria>

- All tasks completed
- All verification checks pass
- No errors or warnings introduced
- Runtime artifacts can answer status questions from durable state alone

  </success_criteria>

<output>
After completion, create `.planning/phases/01-topic-start-hardening/01-02-SUMMARY.md`
</output>
