---
phase: 100-l3-l4-iteration-journal-and-thin-contracts
plan: 01
type: execute
wave: 1
depends_on:
  - 91-runtime-path-contracts
  - 92-registry-and-current-topic-path-normalization
files_modified:
  - docs/design-principles.md
  - docs/HUMAN_IDEA_AI_EXECUTION_STEERING_PROTOCOL_VNEXT.md
  - research/knowledge-hub/runtime/TOPIC_TRUTH_ROOT_CONTRACT.md
  - research/knowledge-hub/runtime/DECLARATIVE_RUNTIME_CONTRACTS.md
  - research/knowledge-hub/knowledge_hub/topic_truth_root_support.py
  - research/knowledge-hub/knowledge_hub/aitp_service.py
  - research/knowledge-hub/knowledge_hub/runtime_bundle_support.py
  - research/knowledge-hub/knowledge_hub/topic_replay.py
  - research/knowledge-hub/tests/test_runtime_path_hygiene_contracts.py
  - research/knowledge-hub/tests/test_aitp_service.py
  - research/knowledge-hub/tests/test_runtime_profiles_and_projections.py
autonomous: true
requirements:
  - REQ-ITER-01
  - REQ-ITER-02
  - REQ-ITER-03
must_haves:
  truths:
    - one run may include multiple L3-L4-L3 iterations without losing human-readable continuity
    - Markdown remains the primary review surface for iteration narrative
    - JSON companions stay thin and machine-facing rather than duplicating prose
    - existing execution, review, returned-result, and staging artifacts remain authoritative in their own roles
---

<objective>
Add a Markdown-first `L3` iteration journal layer that lets one run carry
multiple `L3 -> L4 -> L3` cycles while preserving thin machine contracts and
compatibility with existing runtime artifacts.
</objective>

<context>
@.planning/phases/100-l3-l4-iteration-journal-and-thin-contracts/100-CONTEXT.md
@docs/superpowers/specs/2026-04-16-l3-l4-iteration-journal-design.md
@docs/design-principles.md
@docs/HUMAN_IDEA_AI_EXECUTION_STEERING_PROTOCOL_VNEXT.md
@research/knowledge-hub/runtime/TOPIC_TRUTH_ROOT_CONTRACT.md
@research/knowledge-hub/runtime/DECLARATIVE_RUNTIME_CONTRACTS.md
@research/knowledge-hub/runtime/README.md
@research/knowledge-hub/knowledge_hub/aitp_service.py
@research/knowledge-hub/knowledge_hub/topic_truth_root_support.py
@research/knowledge-hub/knowledge_hub/runtime_bundle_support.py
@research/knowledge-hub/knowledge_hub/_bundle/runtime/scripts/closed_loop_v1.py
</context>

<tasks>

<task type="auto">
  <name>Task 1: Freeze contract and principle language</name>
  <files>docs/design-principles.md, docs/HUMAN_IDEA_AI_EXECUTION_STEERING_PROTOCOL_VNEXT.md, research/knowledge-hub/runtime/TOPIC_TRUTH_ROOT_CONTRACT.md, research/knowledge-hub/runtime/DECLARATIVE_RUNTIME_CONTRACTS.md</files>
  <read_first>docs/superpowers/specs/2026-04-16-l3-l4-iteration-journal-design.md</read_first>
  <action>Add the Markdown-first / thin-machine-contract rule plus the run-local `L3-L4` iteration journal contract so later runtime changes have one authoritative documentation boundary.</action>
  <verify>python -m pytest research/knowledge-hub/tests/test_runtime_path_hygiene_contracts.py -q</verify>
  <acceptance_criteria>
    - principle docs explicitly say Markdown owns the review narrative
    - declarative runtime contracts define run-local iteration journal paths
    - truth-root contract names thin JSON companions as the machine role
  </acceptance_criteria>
  <done>The repo has an explicit contract for iteration journals before code changes begin.</done>
</task>

<task type="auto">
  <name>Task 2: Add failing tests for run-local iteration journal materialization</name>
  <files>research/knowledge-hub/tests/test_aitp_service.py, research/knowledge-hub/tests/test_runtime_profiles_and_projections.py, research/knowledge-hub/tests/test_runtime_path_hygiene_contracts.py</files>
  <read_first>research/knowledge-hub/tests/test_aitp_service.py, research/knowledge-hub/tests/test_runtime_profiles_and_projections.py</read_first>
  <action>Add failing tests that require `iteration_journal.md|json`, per-iteration `plan/l4_return/l3_synthesis` paths, and thin JSON behavior for run-local iteration state.</action>
  <verify>python -m pytest research/knowledge-hub/tests/test_aitp_service.py research/knowledge-hub/tests/test_runtime_profiles_and_projections.py research/knowledge-hub/tests/test_runtime_path_hygiene_contracts.py -q</verify>
  <acceptance_criteria>
    - tests fail before implementation
    - failures prove the journal layer does not yet exist in production code
  </acceptance_criteria>
  <done>The runtime gap is expressed as real failing contracts.</done>
</task>

<task type="auto">
  <name>Task 3: Implement run and iteration path helpers plus Markdown renderers</name>
  <files>research/knowledge-hub/knowledge_hub/topic_truth_root_support.py, research/knowledge-hub/knowledge_hub/aitp_service.py</files>
  <read_first>research/knowledge-hub/knowledge_hub/topic_truth_root_support.py, research/knowledge-hub/knowledge_hub/aitp_service.py</read_first>
  <action>Add helpers for `iteration_journal.*` and `iterations/<iteration_id>/*` under `topics/<topic_slug>/L3/runs/<run_id>/`, including Markdown renderers that keep the human narrative in Markdown and machine pointers in JSON.</action>
  <verify>python -m pytest research/knowledge-hub/tests/test_aitp_service.py -q -k "iteration_journal or topic_truth_root"</verify>
  <acceptance_criteria>
    - service can derive run-local iteration journal paths under the topic truth root
    - journal Markdown renders a readable run index
    - JSON payloads remain thin and path/status oriented
  </acceptance_criteria>
  <done>The topic root knows how to host one multi-iteration run journal.</done>
</task>

<task type="auto">
  <name>Task 4: Wire iteration journal updates into existing execution and return flow</name>
  <files>research/knowledge-hub/knowledge_hub/aitp_service.py, research/knowledge-hub/knowledge_hub/runtime_bundle_support.py, research/knowledge-hub/knowledge_hub/topic_replay.py</files>
  <read_first>research/knowledge-hub/knowledge_hub/_bundle/runtime/scripts/closed_loop_v1.py, research/knowledge-hub/knowledge_hub/runtime_bundle_support.py, research/knowledge-hub/knowledge_hub/topic_replay.py</read_first>
  <action>When a run plans work, materializes an execution task, receives an `L4` return, or records an `L3` synthesis/staging decision, update the corresponding journal and per-iteration surfaces instead of leaving those steps scattered only across existing machine artifacts.</action>
  <verify>python -m pytest research/knowledge-hub/tests/test_aitp_service.py research/knowledge-hub/tests/test_runtime_profiles_and_projections.py -q</verify>
  <acceptance_criteria>
    - one run can accumulate multiple iteration records
    - `l4_return` points at execution-task, review-bundle, and returned-result artifacts
    - `l3_synthesis` can record continue/defer/stage decisions honestly
  </acceptance_criteria>
  <done>The journal layer is updated by real runtime transitions rather than by manual note editing only.</done>
</task>

<task type="auto">
  <name>Task 5: Surface iteration journal pointers through runtime read paths</name>
  <files>research/knowledge-hub/knowledge_hub/runtime_bundle_support.py, research/knowledge-hub/knowledge_hub/topic_replay.py, research/knowledge-hub/knowledge_hub/aitp_service.py</files>
  <read_first>research/knowledge-hub/knowledge_hub/runtime_bundle_support.py, research/knowledge-hub/knowledge_hub/topic_replay.py</read_first>
  <action>Expose the run-local iteration journal as a must-read or supporting surface in runtime bundle, status, and replay outputs so human review can find the journal without reconstructing the run from scattered files.</action>
  <verify>python -m pytest research/knowledge-hub/tests/test_runtime_profiles_and_projections.py research/knowledge-hub/tests/test_aitp_service.py -q</verify>
  <acceptance_criteria>
    - runtime bundle and replay can point at the journal surfaces
    - the journal does not replace execution or review artifacts in their existing roles
  </acceptance_criteria>
  <done>The journal becomes visible through normal runtime entrypoints.</done>
</task>

<task type="auto">
  <name>Task 6: Re-run the focused slice</name>
  <files>research/knowledge-hub/tests/test_runtime_path_hygiene_contracts.py, research/knowledge-hub/tests/test_aitp_service.py, research/knowledge-hub/tests/test_runtime_profiles_and_projections.py</files>
  <read_first>.planning/phases/100-l3-l4-iteration-journal-and-thin-contracts/100-CONTEXT.md</read_first>
  <action>Re-run the focused contract and runtime slices to prove the new journal layer lands cleanly without regressing truth-root and review-surface behavior.</action>
  <verify>python -m pytest research/knowledge-hub/tests/test_runtime_path_hygiene_contracts.py research/knowledge-hub/tests/test_aitp_service.py research/knowledge-hub/tests/test_runtime_profiles_and_projections.py -q</verify>
  <acceptance_criteria>
    - focused tests exit 0
    - no regression in Markdown-authority or truth-root contracts
  </acceptance_criteria>
  <done>The phase lands on a stable, test-backed baseline.</done>
</task>

</tasks>
