---
phase: 145-structured-transition-and-demotion-trace
plan: 01
type: execute
wave: 1
depends_on:
  - v1.70-closure
files_modified:
  - research/knowledge-hub/knowledge_hub/runtime_projection_handler.py
  - research/knowledge-hub/knowledge_hub/runtime_bundle_support.py
  - research/knowledge-hub/knowledge_hub/topic_replay.py
  - research/knowledge-hub/knowledge_hub/promotion_gate_support.py
  - research/knowledge-hub/runtime/scripts/run_transition_history_acceptance.py
  - research/knowledge-hub/tests/test_transition_history_contracts.py
  - research/knowledge-hub/tests/test_runtime_scripts.py
  - research/knowledge-hub/README.md
  - research/knowledge-hub/runtime/README.md
  - research/knowledge-hub/runtime/AITP_TEST_RUNBOOK.md
autonomous: true
requirements:
  - REQ-TRANSITION-01
  - REQ-TRANSITION-02
  - REQ-DEMOTION-01
  - REQ-DEMOTION-02
  - REQ-VERIFY-01
must_haves:
  truths:
    - extend the existing runtime replay/promotion surfaces instead of inventing a disconnected history subsystem
    - backward moves must keep explicit demotion reasons and evidence refs
    - the first slice stays bounded to visibility and replay, not full hypothesis management
---

<objective>
Add one structured runtime transition and demotion history surface so AITP can
answer how a topic moved across layers, including what got sent backward and
why, without requiring reconstruction from scattered notes.
</objective>

<tasks>

<task type="auto">
  <name>Task 1: Add the structured runtime transition/demotion surface</name>
  <files>research/knowledge-hub/knowledge_hub/runtime_projection_handler.py, research/knowledge-hub/knowledge_hub/runtime_bundle_support.py, research/knowledge-hub/knowledge_hub/topic_replay.py, research/knowledge-hub/knowledge_hub/promotion_gate_support.py</files>
  <read_first>research/knowledge-hub/knowledge_hub/runtime_projection_handler.py</read_first>
  <action>Materialize one structured transition history plus one demotion-aware replay/read path that records `from`, `to`, `reason`, timestamp, and evidence refs for bounded layer moves.</action>
  <verify>python -m pytest research/knowledge-hub/tests/test_transition_history_contracts.py -q</verify>
  <acceptance_criteria>
    - runtime records explicit forward/backward transition rows
    - demotion reasons remain visible on replay/read paths
    - the work extends current runtime/promotion surfaces rather than creating a parallel history subsystem
  </acceptance_criteria>
  <done>The runtime history slice is durable and operator-visible.</done>
</task>

<task type="auto">
  <name>Task 2: Add isolated acceptance and docs</name>
  <files>research/knowledge-hub/runtime/scripts/run_transition_history_acceptance.py, research/knowledge-hub/tests/test_runtime_scripts.py, research/knowledge-hub/README.md, research/knowledge-hub/runtime/README.md, research/knowledge-hub/runtime/AITP_TEST_RUNBOOK.md</files>
  <read_first>research/knowledge-hub/tests/test_topic_replay.py</read_first>
  <action>Add one isolated acceptance lane and update operator docs so the new transition/demotion history surface is testable and discoverable.</action>
  <verify>python research/knowledge-hub/runtime/scripts/run_transition_history_acceptance.py --json</verify>
  <acceptance_criteria>
    - docs and runbook reference the transition/demotion acceptance lane
    - isolated acceptance proves replayable forward/backward layer history on a temp kernel root
  </acceptance_criteria>
  <done>Phase `145` is ready to execute and verify.</done>
</task>

</tasks>
