# Story System Phase 5 Legacy Downgrade Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 把旧中枢正式降级为兼容/投影层，让写前默认输入统一到 Story Contracts，让写后默认事实统一到 accepted `CHAPTER_COMMIT`，并让 preflight / dashboard / skills / agents 都显式反映这条主链。

**Architecture:** 新增统一 runtime 来源解析层，集中回答“本章现在应该信什么”。`context_manager`、`memory_contract_adapter`、`extract_chapter_context`、skills 与 dashboard 都只认 `MASTER / VOLUME / CHAPTER / REVIEW + latest accepted CHAPTER_COMMIT`；`state.json / index.db / summaries / memory_scratchpad` 保留，但只作为 commit 投影和查询 read-model。旧 `genre-profiles.md`、旧散写命令、旧 state-first 心智模型继续存在时，必须只以 fallback / compatibility 明示暴露，不能再伪装成主链。

**Tech Stack:** Python 3.13, pytest, Pydantic, SQLite (`index.db`), FastAPI dashboard, React frontend, Story System JSON artifacts under `.story-system/`

**Spec:** `docs/superpowers/specs/2026-04-12-story-system-evolution-spec.md`

**Companion Plans:** `docs/superpowers/plans/2026-04-12-story-system-phase2-contract-first-runtime.md`, `docs/superpowers/plans/2026-04-12-story-system-phase3-chapter-commit-chain.md`, `docs/superpowers/plans/2026-04-12-story-system-phase4-event-log-and-override-ledger.md`

---

## Scope Split

本计划只覆盖 Phase 5：

1. 合同成为默认主输入
2. accepted `CHAPTER_COMMIT` 成为默认写后事实入口
3. `state / index / summary / memory` 显式降级为投影/read-model
4. `genre-profiles.md` 与旧 reference 判断链显式退化为 fallback
5. preflight / dashboard / query / write / review / context-agent / data-agent 全部切到新主链认知

明确不做：

- 不重写 `StateManager / IndexManager / ScratchpadManager` 的底层存储
- 不删除 `.webnovel/state.json`、`.webnovel/index.db`、`.webnovel/memory_scratchpad.json`
- 不重建历史全量 commit / event 数据
- 不新增第二套 commit / projection 体系
- 不做与 Phase 5 无关的 UI 大改版

退出标准：

1. `context_manager`、`memory_contract_adapter`、`extract_chapter_context` 默认读取合同与 latest accepted commit，而不是先读旧状态再拼判断
2. `ChapterCommitService` 写出的 commit 元数据足以声明其为唯一写后事实来源，并能稳定定位 `MASTER / VOLUME / CHAPTER / REVIEW`
3. `webnovel-write` / `webnovel-query` / `webnovel-review` / `webnovel-plan` 与 `context-agent` / `data-agent` 的默认指令已切到 contract-first + commit-first
4. preflight 与 dashboard 能直接暴露“主链是否就绪、是否仍落入 legacy fallback、是否存在 rejected / projection backlog”
5. `genre-profiles.md` 被明示为 fallback-only；合同存在时不再参与全局系统判断
6. 文档、命令说明、运维手册都能准确描述 `.story-system` 主链和 `.webnovel/*` 投影链的关系

---

## File Structure

### 要创建的文件

- `webnovel-writer/scripts/data_modules/story_runtime_sources.py`
- `webnovel-writer/scripts/data_modules/story_runtime_health.py`
- `webnovel-writer/scripts/data_modules/tests/test_story_runtime_sources.py`
- `webnovel-writer/scripts/data_modules/tests/test_story_runtime_health.py`
- `docs/architecture/story-system-phase5.md`

### 要修改的文件

- `webnovel-writer/scripts/data_modules/chapter_commit_service.py`
- `webnovel-writer/scripts/data_modules/context_manager.py`
- `webnovel-writer/scripts/data_modules/memory_contract_adapter.py`
- `webnovel-writer/scripts/extract_chapter_context.py`
- `webnovel-writer/scripts/data_modules/tests/test_chapter_commit_service.py`
- `webnovel-writer/scripts/data_modules/tests/test_context_manager.py`
- `webnovel-writer/scripts/data_modules/tests/test_memory_contract_adapter.py`
- `webnovel-writer/scripts/data_modules/tests/test_extract_chapter_context.py`
- `webnovel-writer/scripts/data_modules/webnovel.py`
- `webnovel-writer/scripts/data_modules/tests/test_webnovel_unified_cli.py`
- `webnovel-writer/dashboard/app.py`
- `webnovel-writer/dashboard/frontend/src/App.jsx`
- `webnovel-writer/dashboard/frontend/src/api.js`
- `webnovel-writer/skills/webnovel-write/SKILL.md`
- `webnovel-writer/skills/webnovel-review/SKILL.md`
- `webnovel-writer/skills/webnovel-query/SKILL.md`
- `webnovel-writer/skills/webnovel-plan/SKILL.md`
- `webnovel-writer/skills/webnovel-dashboard/SKILL.md`
- `webnovel-writer/agents/context-agent.md`
- `webnovel-writer/agents/data-agent.md`
- `webnovel-writer/scripts/data_modules/tests/test_prompt_integrity.py`
- `webnovel-writer/references/genre-profiles.md`
- `README.md`
- `docs/architecture/overview.md`
- `docs/guides/commands.md`
- `docs/operations/operations.md`
- `docs/superpowers/README.md`

### 文件职责

- `story_runtime_sources.py`：统一解析本章 contracts、latest commit、fallback 状态，避免各入口各自判断
- `story_runtime_health.py`：把主链状态、legacy fallback、rejected/backlog 汇总为 preflight / dashboard 共用健康报告
- `chapter_commit_service.py`：补齐 write-fact provenance，确保 commit 能明确引用 volume 合同与写后真理角色
- `context_manager.py`：把 runtime pack 切成“合同主链 + commit 摘要 + legacy fallback hints”
- `memory_contract_adapter.py`：让 `load_context` 和 `commit_chapter` 都服从 contract/commit 主链
- `extract_chapter_context.py`：把导出文本从“旧状态摘要”升级为“主链状态 + fallback 显示”
- `webnovel.py`：preflight 暴露 story runtime health，统一 CLI 对外语义
- `dashboard/app.py` + `frontend/src/*`：提供可视化 runtime health / commit 状态 / legacy fallback 观测
- `skills/*` + `agents/*`：把人机提示词中的默认工作流从旧散写链切到 commit 主链

---

## Task 1: 建立统一 runtime 来源解析与 commit provenance

**Files:**
- Create: `webnovel-writer/scripts/data_modules/story_runtime_sources.py`
- Create: `webnovel-writer/scripts/data_modules/tests/test_story_runtime_sources.py`
- Modify: `webnovel-writer/scripts/data_modules/chapter_commit_service.py`
- Modify: `webnovel-writer/scripts/data_modules/tests/test_chapter_commit_service.py`

- [ ] **Step 1: 先写 runtime 来源与 commit provenance 的失败测试**

```python
# webnovel-writer/scripts/data_modules/tests/test_story_runtime_sources.py
#!/usr/bin/env python3
# -*- coding: utf-8 -*-

import json

from data_modules.story_runtime_sources import load_runtime_sources


def test_load_runtime_sources_prefers_latest_accepted_commit(tmp_path):
    story_root = tmp_path / ".story-system"
    (story_root / "chapters").mkdir(parents=True, exist_ok=True)
    (story_root / "volumes").mkdir(parents=True, exist_ok=True)
    (story_root / "reviews").mkdir(parents=True, exist_ok=True)
    (story_root / "commits").mkdir(parents=True, exist_ok=True)

    (story_root / "MASTER_SETTING.json").write_text(
        json.dumps({"meta": {"contract_type": "MASTER_SETTING"}, "route": {"primary_genre": "玄幻"}}),
        encoding="utf-8",
    )
    (story_root / "chapters" / "chapter_003.json").write_text(
        json.dumps({"meta": {"contract_type": "CHAPTER_BRIEF", "chapter": 3}}),
        encoding="utf-8",
    )
    (story_root / "volumes" / "volume_001.json").write_text(
        json.dumps({"meta": {"contract_type": "VOLUME_BRIEF", "volume": 1}}),
        encoding="utf-8",
    )
    (story_root / "reviews" / "chapter_003.review.json").write_text(
        json.dumps({"meta": {"contract_type": "REVIEW_CONTRACT", "chapter": 3}}),
        encoding="utf-8",
    )
    (story_root / "commits" / "chapter_003.commit.json").write_text(
        json.dumps(
            {
                "meta": {"schema_version": "story-system/v1", "chapter": 3, "status": "accepted"},
                "provenance": {"write_fact_role": "chapter_commit"},
                "projection_status": {"state": "done", "index": "done", "summary": "done", "memory": "done"},
            }
        ),
        encoding="utf-8",
    )

    snapshot = load_runtime_sources(tmp_path, chapter=3)

    assert snapshot.latest_accepted_commit["meta"]["status"] == "accepted"
    assert snapshot.primary_write_source == "chapter_commit"
    assert snapshot.fallback_sources == []
```

```python
# webnovel-writer/scripts/data_modules/tests/test_chapter_commit_service.py
def test_commit_service_includes_volume_ref_and_write_fact_provenance(tmp_path):
    service = ChapterCommitService(tmp_path)
    payload = service.build_commit(
        chapter=3,
        review_result={"blocking_count": 0},
        fulfillment_result={"planned_nodes": ["发现陷阱"], "covered_nodes": ["发现陷阱"], "missed_nodes": [], "extra_nodes": []},
        disambiguation_result={"pending": []},
        extraction_result={"state_deltas": [], "entity_deltas": [], "accepted_events": []},
    )

    assert payload["contract_refs"]["volume"] == "volume_001.json"
    assert payload["provenance"]["write_fact_role"] == "chapter_commit"
    assert payload["provenance"]["projection_role"] == "derived_read_models"
```

- [ ] **Step 2: 跑红灯，确认新测试确实失败**

Run: `python -m pytest webnovel-writer/scripts/data_modules/tests/test_story_runtime_sources.py webnovel-writer/scripts/data_modules/tests/test_chapter_commit_service.py -q --no-cov`

Expected:
- `ModuleNotFoundError: No module named 'data_modules.story_runtime_sources'`
- 或 `KeyError: 'volume' / 'provenance'`

- [ ] **Step 3: 实现统一 runtime 来源解析器**

```python
# webnovel-writer/scripts/data_modules/story_runtime_sources.py
from __future__ import annotations

from dataclasses import dataclass, field
from pathlib import Path
from typing import Any

from .story_contracts import StoryContractPaths, read_json_if_exists


@dataclass
class RuntimeSourceSnapshot:
    chapter: int
    contracts: dict[str, dict[str, Any]]
    latest_commit: dict[str, Any] | None
    latest_accepted_commit: dict[str, Any] | None
    fallback_sources: list[str] = field(default_factory=list)
    primary_write_source: str = "chapter_commit"

    def to_dict(self) -> dict[str, Any]:
        return {
            "chapter": self.chapter,
            "contracts": self.contracts,
            "latest_commit": self.latest_commit,
            "latest_accepted_commit": self.latest_accepted_commit,
            "fallback_sources": self.fallback_sources,
            "primary_write_source": self.primary_write_source,
        }


def load_runtime_sources(project_root: Path, chapter: int) -> RuntimeSourceSnapshot:
    paths = StoryContractPaths.from_project_root(project_root)
    contracts = {
        "master": read_json_if_exists(paths.master_json) or {},
        "chapter": read_json_if_exists(paths.chapter_json(chapter)) or {},
        "volume": read_json_if_exists(paths.volume_json(1)) or {},
        "review": read_json_if_exists(paths.review_json(chapter)) or {},
    }

    latest_commit = read_json_if_exists(paths.commit_json(chapter))
    latest_accepted_commit = latest_commit if (latest_commit or {}).get("meta", {}).get("status") == "accepted" else None

    fallback_sources: list[str] = []
    for key, payload in contracts.items():
        if not payload:
            fallback_sources.append(f"missing_{key}_contract")
    if latest_accepted_commit is None:
        fallback_sources.append("missing_accepted_commit")

    return RuntimeSourceSnapshot(
        chapter=chapter,
        contracts=contracts,
        latest_commit=latest_commit,
        latest_accepted_commit=latest_accepted_commit,
        fallback_sources=fallback_sources,
    )
```

- [ ] **Step 4: 在 commit service 中补齐 provenance 字段和 volume 引用**

```python
# webnovel-writer/scripts/data_modules/chapter_commit_service.py
from chapter_outline_loader import volume_num_for_chapter_from_state


def build_commit(
    self,
    chapter: int,
    review_result: Dict[str, Any],
    fulfillment_result: Dict[str, Any],
    disambiguation_result: Dict[str, Any],
    extraction_result: Dict[str, Any],
) -> Dict[str, Any]:
    volume = volume_num_for_chapter_from_state(self.project_root, chapter) or 1
    return {
        "meta": {
            "schema_version": "story-system/v1",
            "chapter": chapter,
            "status": status,
        },
        "contract_refs": {
            "master": "MASTER_SETTING.json",
            "volume": f"volume_{volume:03d}.json",
            "chapter": f"chapter_{chapter:03d}.json",
            "review": f"chapter_{chapter:03d}.review.json",
        },
        "provenance": {
            "write_fact_role": "chapter_commit",
            "projection_role": "derived_read_models",
            "legacy_state_role": "projection_only",
        },
        "outline_snapshot": {
            "planned_nodes": fulfillment_result.get("planned_nodes", []),
            "covered_nodes": fulfillment_result.get("covered_nodes", []),
            "missed_nodes": fulfillment_result.get("missed_nodes", []),
            "extra_nodes": fulfillment_result.get("extra_nodes", []),
        },
        "review_result": review_result,
        "fulfillment_result": fulfillment_result,
        "disambiguation_result": disambiguation_result,
        "accepted_events": extraction_result.get("accepted_events", []),
        "state_deltas": extraction_result.get("state_deltas", []),
        "entity_deltas": extraction_result.get("entity_deltas", []),
        "summary_text": extraction_result.get("summary_text", ""),
        "projection_status": {"state": "pending", "index": "pending", "summary": "pending", "memory": "pending"},
    }
```

- [ ] **Step 5: 重新跑聚焦测试**

Run: `python -m pytest webnovel-writer/scripts/data_modules/tests/test_story_runtime_sources.py webnovel-writer/scripts/data_modules/tests/test_chapter_commit_service.py -q --no-cov`

Expected: `2 passed`

- [ ] **Step 6: 提交本任务**

```bash
git add webnovel-writer/scripts/data_modules/story_runtime_sources.py \
        webnovel-writer/scripts/data_modules/chapter_commit_service.py \
        webnovel-writer/scripts/data_modules/tests/test_story_runtime_sources.py \
        webnovel-writer/scripts/data_modules/tests/test_chapter_commit_service.py
git commit -m "feat: add story runtime source resolver"
```

---

## Task 2: 把上下文入口切到 contract-first + commit-first

**Files:**
- Modify: `webnovel-writer/scripts/data_modules/context_manager.py`
- Modify: `webnovel-writer/scripts/data_modules/memory_contract_adapter.py`
- Modify: `webnovel-writer/scripts/extract_chapter_context.py`
- Modify: `webnovel-writer/scripts/data_modules/tests/test_context_manager.py`
- Modify: `webnovel-writer/scripts/data_modules/tests/test_memory_contract_adapter.py`
- Modify: `webnovel-writer/scripts/data_modules/tests/test_extract_chapter_context.py`

- [ ] **Step 1: 先补三组失败测试，锁定新主链语义**

```python
# webnovel-writer/scripts/data_modules/tests/test_context_manager.py
def test_context_manager_prefers_contract_route_over_legacy_genre_profile(temp_project):
    refs_dir = temp_project.project_root / ".claude" / "references"
    refs_dir.mkdir(parents=True, exist_ok=True)
    (refs_dir / "genre-profiles.md").write_text("## 都市\n- 旧画像提示", encoding="utf-8")
    (refs_dir / "reading-power-taxonomy.md").write_text("## 都市\n- 旧分类", encoding="utf-8")

    state = {
        "project": {"genre": "都市"},
        "protagonist_state": {"name": "林默"},
        "chapter_meta": {},
        "disambiguation_warnings": [],
        "disambiguation_pending": [],
    }
    temp_project.state_file.write_text(json.dumps(state, ensure_ascii=False), encoding="utf-8")

    story_root = temp_project.story_system_dir
    story_root.mkdir(parents=True, exist_ok=True)
    (story_root / "MASTER_SETTING.json").write_text(
        json.dumps(
            {
                "meta": {"schema_version": "story-system/v1", "contract_type": "MASTER_SETTING"},
                "route": {"primary_genre": "都市异能"},
                "master_constraints": {"core_tone": "先压后爆"},
            },
            ensure_ascii=False,
        ),
        encoding="utf-8",
    )

    manager = ContextManager(temp_project)
    payload = manager.build_context(3, use_snapshot=False, save_snapshot=False)

    assert payload["sections"]["story_contract"]["content"]["master"]["route"]["primary_genre"] == "都市异能"
    assert payload["sections"]["runtime_status"]["content"]["fallback_sources"] == ["missing_volume_contract", "missing_chapter_contract", "missing_review_contract", "missing_accepted_commit"]
```

```python
# webnovel-writer/scripts/data_modules/tests/test_memory_contract_adapter.py
def test_commit_chapter_delegates_to_chapter_commit_mainline(tmp_path):
    cfg = _make_project(tmp_path)
    adapter = MemoryContractAdapter(cfg)

    result = adapter.commit_chapter(
        3,
        {
            "review_result": {"blocking_count": 0},
            "fulfillment_result": {"planned_nodes": ["发现陷阱"], "covered_nodes": ["发现陷阱"], "missed_nodes": [], "extra_nodes": []},
            "disambiguation_result": {"pending": []},
            "extraction_result": {"state_deltas": [], "entity_deltas": [], "accepted_events": [], "summary_text": "本章摘要"},
        },
    )

    assert (tmp_path / ".story-system" / "commits" / "chapter_003.commit.json").is_file()
    assert result.chapter == 3
    assert "commit_status=accepted" in result.warnings
```

```python
# webnovel-writer/scripts/data_modules/tests/test_extract_chapter_context.py
def test_render_text_contains_runtime_status_section(tmp_path):
    from extract_chapter_context import _render_text

    text = _render_text(
        {
            "chapter": 3,
            "outline": "测试大纲",
            "previous_summaries": [],
            "state_summary": "旧状态摘要",
            "context_contract_version": "v2",
            "reader_signal": {},
            "genre_profile": {},
            "writing_guidance": {},
            "runtime_status": {
                "primary_write_source": "chapter_commit",
                "fallback_sources": ["missing_accepted_commit"],
            },
            "latest_commit": {"meta": {"chapter": 3, "status": "rejected"}},
        }
    )

    assert "## Runtime Status" in text
    assert "- 写后事实入口: chapter_commit" in text
    assert "- Legacy Fallback: missing_accepted_commit" in text
```

- [ ] **Step 2: 跑红灯，确认当前入口仍然偏旧链路**

Run: `python -m pytest webnovel-writer/scripts/data_modules/tests/test_context_manager.py webnovel-writer/scripts/data_modules/tests/test_memory_contract_adapter.py webnovel-writer/scripts/data_modules/tests/test_extract_chapter_context.py -q --no-cov`

Expected:
- `KeyError: 'runtime_status'`
- `AssertionError`（`commit_chapter` 仍未生成 `.story-system/commits/chapter_003.commit.json`）
- `_render_text` 中不存在 runtime status 段

- [ ] **Step 3: 重写 ContextManager 的 pack 组装顺序**

```python
# webnovel-writer/scripts/data_modules/context_manager.py
from .story_runtime_sources import load_runtime_sources


def _build_pack(self, chapter: int) -> Dict[str, Any]:
    runtime_sources = load_runtime_sources(self.config.project_root, chapter)
    state = self._load_state()

    story_contract = {
        "master": runtime_sources.contracts.get("master") or {},
        "volume": runtime_sources.contracts.get("volume") or {},
        "chapter": runtime_sources.contracts.get("chapter") or {},
        "review_contract": runtime_sources.contracts.get("review") or {},
    }

    genre_profile = {}
    if runtime_sources.fallback_sources:
        genre_profile = self._load_genre_profile(state)
        genre_profile["mode"] = "fallback_only"

    reader_signal = self._load_reader_signal(chapter)
    return {
        "story_contract": story_contract,
        "runtime_status": runtime_sources.to_dict(),
        "latest_commit": runtime_sources.latest_accepted_commit or runtime_sources.latest_commit or {},
        "genre_profile": genre_profile,
        "reader_signal": reader_signal,
        "preferences": self._load_json_optional(self.config.webnovel_dir / "preferences.json"),
        "writing_guidance": self._build_writing_guidance(chapter, reader_signal, genre_profile),
    }
```

- [ ] **Step 4: 让 MemoryContractAdapter 同时切换读链与写链**

```python
# webnovel-writer/scripts/data_modules/memory_contract_adapter.py
from .chapter_commit_service import ChapterCommitService
from .story_runtime_sources import load_runtime_sources


def load_context(self, chapter: int, budget_tokens: int = 4000) -> ContextPack:
    runtime_sources = load_runtime_sources(self.config.project_root, chapter)
    sections = {
        "story_contracts": runtime_sources.contracts,
        "runtime_status": runtime_sources.to_dict(),
        "latest_commit": runtime_sources.latest_accepted_commit or runtime_sources.latest_commit or {},
    }
    return ContextPack(chapter=chapter, sections=sections, budget_used_tokens=0)


def commit_chapter(self, chapter: int, result: dict) -> CommitResult:
    service = ChapterCommitService(self.config.project_root)
    payload = service.build_commit(
        chapter=chapter,
        review_result=result.get("review_result", {}),
        fulfillment_result=result.get("fulfillment_result", {}),
        disambiguation_result=result.get("disambiguation_result", {}),
        extraction_result=result.get("extraction_result", {}),
    )
    service.persist_commit(payload)
    payload = service.apply_projections(payload) if payload["meta"]["status"] == "accepted" else payload
    summary_path = str(self.config.webnovel_dir / "summaries" / f"ch{chapter:04d}.md")
    return CommitResult(
        chapter=chapter,
        entities_added=len((payload.get("entity_deltas") or [])),
        entities_updated=0,
        state_changes_recorded=len((payload.get("state_deltas") or [])),
        relationships_added=0,
        memory_items_added=0,
        summary_path=summary_path if Path(summary_path).exists() else "",
        warnings=[f"commit_status={payload['meta']['status']}"],
    )
```

- [ ] **Step 5: 更新 `extract_chapter_context.py` 的文本输出，让 legacy fallback 显式可见**

```python
# webnovel-writer/scripts/extract_chapter_context.py
def _render_text(payload: Dict[str, Any]) -> str:
    lines = [f"# 第{payload.get('chapter', 0)}章上下文"]
    runtime_status = payload.get("runtime_status") or {}
    latest_commit = payload.get("latest_commit") or {}
    lines.extend(
        [
            "## Runtime Status",
            f"- 写后事实入口: {runtime_status.get('primary_write_source', 'unknown')}",
            f"- Legacy Fallback: {', '.join(runtime_status.get('fallback_sources') or ['none'])}",
            f"- Latest Commit: {(latest_commit.get('meta') or {}).get('status', 'missing')}",
        ]
    )
    return "\n".join(lines)
```

- [ ] **Step 6: 重跑聚焦测试**

Run: `python -m pytest webnovel-writer/scripts/data_modules/tests/test_context_manager.py webnovel-writer/scripts/data_modules/tests/test_memory_contract_adapter.py webnovel-writer/scripts/data_modules/tests/test_extract_chapter_context.py -q --no-cov`

Expected: `3 passed` 或对应文件内全部通过

- [ ] **Step 7: 提交本任务**

```bash
git add webnovel-writer/scripts/data_modules/context_manager.py \
        webnovel-writer/scripts/data_modules/memory_contract_adapter.py \
        webnovel-writer/scripts/extract_chapter_context.py \
        webnovel-writer/scripts/data_modules/tests/test_context_manager.py \
        webnovel-writer/scripts/data_modules/tests/test_memory_contract_adapter.py \
        webnovel-writer/scripts/data_modules/tests/test_extract_chapter_context.py
git commit -m "feat: switch context loading to contract and commit chain"
```

---

## Task 3: 把 skills / agents 的默认工作流切到 commit 主链

**Files:**
- Modify: `webnovel-writer/skills/webnovel-write/SKILL.md`
- Modify: `webnovel-writer/skills/webnovel-review/SKILL.md`
- Modify: `webnovel-writer/skills/webnovel-query/SKILL.md`
- Modify: `webnovel-writer/skills/webnovel-plan/SKILL.md`
- Modify: `webnovel-writer/skills/webnovel-dashboard/SKILL.md`
- Modify: `webnovel-writer/agents/context-agent.md`
- Modify: `webnovel-writer/agents/data-agent.md`
- Modify: `webnovel-writer/scripts/data_modules/tests/test_prompt_integrity.py`

- [ ] **Step 1: 先写 prompt integrity 失败测试，锁住新主链叙述**

```python
# webnovel-writer/scripts/data_modules/tests/test_prompt_integrity.py
def test_webnovel_write_skill_uses_chapter_commit_as_step5_mainline():
    text = (SKILLS_DIR / "webnovel-write" / "SKILL.md").read_text(encoding="utf-8")
    assert "chapter-commit" in text
    assert "accepted `CHAPTER_COMMIT`" in text
    assert "state process-chapter" not in text


def test_data_agent_is_described_as_extraction_only_not_direct_write_mainline():
    text = (AGENTS_DIR / "data-agent.md").read_text(encoding="utf-8")
    assert "chapter-commit" in text
    assert "直接写入 index.db 和 state.json" not in text


def test_webnovel_query_skill_prefers_story_system_and_memory_contract():
    text = (SKILLS_DIR / "webnovel-query" / "SKILL.md").read_text(encoding="utf-8")
    assert "memory-contract load-context" in text
    assert ".story-system/" in text
    assert 'cat "$PROJECT_ROOT/.webnovel/state.json"' not in text
```

- [ ] **Step 2: 跑红灯**

Run: `python -m pytest webnovel-writer/scripts/data_modules/tests/test_prompt_integrity.py -q --no-cov`

Expected: 至少 1 个断言失败，说明提示词仍在使用旧散写心智模型

- [ ] **Step 3: 改写 `webnovel-write`，让 Step 5 以 commit 为成功判定**

````md
<!-- webnovel-writer/skills/webnovel-write/SKILL.md -->
### Step 5：构建 extraction artifacts 并提交 `CHAPTER_COMMIT`

必须产出中间文件：
- `${PROJECT_ROOT}/.webnovel/tmp/review_results.json`
- `${PROJECT_ROOT}/.webnovel/tmp/fulfillment_result.json`
- `${PROJECT_ROOT}/.webnovel/tmp/disambiguation_result.json`
- `${PROJECT_ROOT}/.webnovel/tmp/extraction_result.json`

主命令：

```bash
python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" chapter-commit \
  --chapter {chapter_num} \
  --review-result "${PROJECT_ROOT}/.webnovel/tmp/review_results.json" \
  --fulfillment-result "${PROJECT_ROOT}/.webnovel/tmp/fulfillment_result.json" \
  --disambiguation-result "${PROJECT_ROOT}/.webnovel/tmp/disambiguation_result.json" \
  --extraction-result "${PROJECT_ROOT}/.webnovel/tmp/extraction_result.json"
```

成功标准：
- `.story-system/commits/chapter_{chapter_num}.commit.json` 已存在
- `meta.status == accepted`
- `projection_status` 中 `state/index/summary/memory` 均为 `done` 或明确 `skipped`
````

- [ ] **Step 4: 改写 query / review / plan / context-agent / data-agent 的默认读取与写入叙述**

```md
<!-- webnovel-writer/agents/data-agent.md -->
你负责生成 `extraction_result.json`，并为 `chapter-commit` 提供：
- `accepted_events`
- `state_deltas`
- `entity_deltas`
- `summary_text`

你不是写后真理源。
`state.json / index.db / summaries / memory_scratchpad` 的最终写入由 accepted `CHAPTER_COMMIT` 的 projection writers 完成。
```

```md
<!-- webnovel-writer/skills/webnovel-query/SKILL.md -->
查询顺序固定为：
1. `.story-system/MASTER_SETTING.json`
2. `.story-system/volumes/*.json`
3. `.story-system/chapters/*.json`
4. latest accepted `.story-system/commits/chapter_XXX.commit.json`
5. `memory-contract load-context`
6. `.webnovel/state.json` / `index.db`（仅 fallback/read-model）
```

- [ ] **Step 5: 重新跑 prompt integrity**

Run: `python -m pytest webnovel-writer/scripts/data_modules/tests/test_prompt_integrity.py -q --no-cov`

Expected: `passed`

- [ ] **Step 6: 提交本任务**

```bash
git add webnovel-writer/skills/webnovel-write/SKILL.md \
        webnovel-writer/skills/webnovel-review/SKILL.md \
        webnovel-writer/skills/webnovel-query/SKILL.md \
        webnovel-writer/skills/webnovel-plan/SKILL.md \
        webnovel-writer/skills/webnovel-dashboard/SKILL.md \
        webnovel-writer/agents/context-agent.md \
        webnovel-writer/agents/data-agent.md \
        webnovel-writer/scripts/data_modules/tests/test_prompt_integrity.py
git commit -m "docs: cut skills over to chapter commit mainline"
```

---

## Task 4: 暴露 story runtime health，消灭“看起来切了，实际上没切”

**Files:**
- Create: `webnovel-writer/scripts/data_modules/story_runtime_health.py`
- Create: `webnovel-writer/scripts/data_modules/tests/test_story_runtime_health.py`
- Modify: `webnovel-writer/scripts/data_modules/webnovel.py`
- Modify: `webnovel-writer/scripts/data_modules/tests/test_webnovel_unified_cli.py`
- Modify: `webnovel-writer/dashboard/app.py`
- Modify: `webnovel-writer/dashboard/frontend/src/api.js`
- Modify: `webnovel-writer/dashboard/frontend/src/App.jsx`

- [ ] **Step 1: 先写 health helper 与 preflight 的失败测试**

```python
# webnovel-writer/scripts/data_modules/tests/test_story_runtime_health.py
from data_modules.story_runtime_health import build_story_runtime_health


def test_story_runtime_health_reports_missing_commit_as_not_ready(tmp_path):
    report = build_story_runtime_health(tmp_path, chapter=3)
    assert report["mainline_ready"] is False
    assert "missing_accepted_commit" in report["fallback_sources"]
```

```python
# webnovel-writer/scripts/data_modules/tests/test_webnovel_unified_cli.py
def test_preflight_includes_story_runtime_health(monkeypatch, tmp_path, capsys):
    module = _load_webnovel_module()

    project_root = tmp_path / "book"
    (project_root / ".webnovel").mkdir(parents=True, exist_ok=True)
    (project_root / ".webnovel" / "state.json").write_text("{}", encoding="utf-8")

    monkeypatch.setattr(sys, "argv", ["webnovel", "--project-root", str(project_root), "preflight", "--format", "json"])

    with pytest.raises(SystemExit):
        module.main()

    captured = capsys.readouterr()
    assert '"story_runtime"' in captured.out
    assert '"mainline_ready"' in captured.out
```

- [ ] **Step 2: 跑红灯**

Run: `python -m pytest webnovel-writer/scripts/data_modules/tests/test_story_runtime_health.py webnovel-writer/scripts/data_modules/tests/test_webnovel_unified_cli.py -q --no-cov`

Expected:
- `ModuleNotFoundError: No module named 'data_modules.story_runtime_health'`
- preflight JSON 中不存在 `story_runtime`

- [ ] **Step 3: 实现 health helper，并接到 preflight**

```python
# webnovel-writer/scripts/data_modules/story_runtime_health.py
from __future__ import annotations

from pathlib import Path
from typing import Any

from .story_runtime_sources import load_runtime_sources


def build_story_runtime_health(project_root: Path, chapter: int | None = None) -> dict[str, Any]:
    current_chapter = int(chapter or 0)
    snapshot = load_runtime_sources(project_root, current_chapter) if current_chapter else None
    fallback_sources = list((snapshot.fallback_sources if snapshot else ["chapter_unspecified"]))
    latest_commit = (snapshot.latest_commit if snapshot else None) or {}
    return {
        "chapter": current_chapter,
        "mainline_ready": bool(snapshot and not snapshot.fallback_sources),
        "fallback_sources": fallback_sources,
        "latest_commit_status": (latest_commit.get("meta") or {}).get("status", "missing"),
        "primary_write_source": (snapshot.primary_write_source if snapshot else "chapter_commit"),
    }
```

```python
# webnovel-writer/scripts/data_modules/webnovel.py
from data_modules.story_runtime_health import build_story_runtime_health


def _build_preflight_report(explicit_project_root: Optional[str]) -> dict:
    scripts_dir = _scripts_dir().resolve()
    plugin_root = scripts_dir.parent
    skill_root = plugin_root / "skills" / "webnovel-write"
    entry_script = scripts_dir / "webnovel.py"
    extract_script = scripts_dir / "extract_chapter_context.py"

    checks = [
        {"name": "scripts_dir", "ok": scripts_dir.is_dir(), "path": str(scripts_dir)},
        {"name": "entry_script", "ok": entry_script.is_file(), "path": str(entry_script)},
        {"name": "extract_context_script", "ok": extract_script.is_file(), "path": str(extract_script)},
        {"name": "skill_root", "ok": skill_root.is_dir(), "path": str(skill_root)},
    ]

    project_root = ""
    project_root_error = ""
    try:
        resolved_root = _resolve_root(explicit_project_root)
        project_root = str(resolved_root)
        checks.append({"name": "project_root", "ok": True, "path": project_root})
    except Exception as exc:
        project_root_error = str(exc)
        checks.append({"name": "project_root", "ok": False, "path": explicit_project_root or "", "error": project_root_error})

    story_runtime = build_story_runtime_health(Path(project_root)) if project_root else {}
    return {
        "ok": all(bool(item["ok"]) for item in checks),
        "project_root": project_root,
        "scripts_dir": str(scripts_dir),
        "skill_root": str(skill_root),
        "checks": checks,
        "project_root_error": project_root_error,
        "story_runtime": story_runtime,
    }
```

- [ ] **Step 4: 在 dashboard 暴露 story runtime health 与 latest commit 状态**

```python
# webnovel-writer/dashboard/app.py
from data_modules.story_runtime_health import build_story_runtime_health


@app.get("/api/story-runtime/health")
def story_runtime_health():
    project_root = _get_project_root()
    state_path = project_root / ".webnovel" / "state.json"
    chapter = 0
    if state_path.is_file():
        state = json.loads(state_path.read_text(encoding="utf-8"))
        chapter = int(((state.get("progress") or {}).get("current_chapter") or 0))
    return build_story_runtime_health(project_root, chapter=chapter)
```

```jsx
// webnovel-writer/dashboard/frontend/src/App.jsx
const [runtimeHealth, setRuntimeHealth] = useState(null)

useEffect(() => {
  fetchJSON('/api/story-runtime/health').then(setRuntimeHealth).catch(() => setRuntimeHealth(null))
}, [refreshKey])

{runtimeHealth ? (
  <div className="card stat-card">
    <span className="stat-label">Story Runtime</span>
    <span className="stat-value plain">{runtimeHealth.mainline_ready ? 'Mainline' : 'Fallback'}</span>
    <span className="stat-sub">
      {runtimeHealth.latest_commit_status} · {(runtimeHealth.fallback_sources || []).join(', ') || 'no fallback'}
    </span>
  </div>
) : null}
```

- [ ] **Step 5: 跑后端测试和前端构建**

Run: `python -m pytest webnovel-writer/scripts/data_modules/tests/test_story_runtime_health.py webnovel-writer/scripts/data_modules/tests/test_webnovel_unified_cli.py -q --no-cov`

Expected: `passed`

Run: `npm --prefix webnovel-writer/dashboard/frontend run build`

Expected: Vite build success，无新增 lint/blocking error

- [ ] **Step 6: 提交本任务**

```bash
git add webnovel-writer/scripts/data_modules/story_runtime_health.py \
        webnovel-writer/scripts/data_modules/webnovel.py \
        webnovel-writer/scripts/data_modules/tests/test_story_runtime_health.py \
        webnovel-writer/scripts/data_modules/tests/test_webnovel_unified_cli.py \
        webnovel-writer/dashboard/app.py \
        webnovel-writer/dashboard/frontend/src/api.js \
        webnovel-writer/dashboard/frontend/src/App.jsx
git commit -m "feat: surface story runtime health in preflight and dashboard"
```

---

## Task 5: 封板 legacy fallback 文档与运行说明

**Files:**
- Create: `docs/architecture/story-system-phase5.md`
- Modify: `webnovel-writer/references/genre-profiles.md`
- Modify: `README.md`
- Modify: `docs/architecture/overview.md`
- Modify: `docs/guides/commands.md`
- Modify: `docs/operations/operations.md`
- Modify: `docs/superpowers/README.md`

- [ ] **Step 1: 先补 architecture 文档骨架，明确主链已切换**

````md
<!-- docs/architecture/story-system-phase5.md -->
# Story System Phase 5

## 核心结论

- 写前真源：`MASTER / VOLUME / CHAPTER / REVIEW`
- 写后真源：accepted `CHAPTER_COMMIT`
- `state / index / summary / memory`：投影/read-model
- `genre-profiles.md`：fallback-only

## 默认链路

```text
story-system --persist/--emit-runtime-contracts
    -> context / query / write / review 读取合同
chapter-commit --chapter N
    -> accepted commit
    -> projection writers
    -> state / index / summaries / memory
```
````

- [ ] **Step 2: 在 `genre-profiles.md` 文件头显式打上 fallback-only 标记**

```md
<!-- webnovel-writer/references/genre-profiles.md -->
# genre-profiles

> **状态：Fallback Only**
> 高频题材的主判定、主调性、主禁忌已迁移到 Story Contract / CSV route seed。
> 本文件只在合同缺失、项目未升级或显式 fallback 时提供补充提示。
```

- [ ] **Step 3: 更新 README / commands / operations，把主链写成可执行手册**

```md
<!-- docs/guides/commands.md -->
## Story System 主链

1. 生成合同：
   `python -X utf8 "webnovel-writer/scripts/webnovel.py" --project-root "{WORKSPACE_ROOT}" story-system "{goal}" --chapter {N} --persist --emit-runtime-contracts --format both`
2. 提交章节：
   `python -X utf8 "webnovel-writer/scripts/webnovel.py" --project-root "{PROJECT_ROOT}" chapter-commit --chapter {N} --review-result ".webnovel/tmp/review_results.json" --fulfillment-result ".webnovel/tmp/fulfillment_result.json" --disambiguation-result ".webnovel/tmp/disambiguation_result.json" --extraction-result ".webnovel/tmp/extraction_result.json"`
3. 检查健康：
   `python -X utf8 "webnovel-writer/scripts/webnovel.py" --project-root "{PROJECT_ROOT}" preflight --format json`
```

- [ ] **Step 4: 做一次最终回归**

Run: `python -m pytest webnovel-writer/scripts/data_modules/tests/test_prompt_integrity.py webnovel-writer/scripts/data_modules/tests/test_webnovel_unified_cli.py webnovel-writer/scripts/data_modules/tests/test_context_manager.py webnovel-writer/scripts/data_modules/tests/test_memory_contract_adapter.py -q --no-cov`

Expected: 全部通过

- [ ] **Step 5: 提交本任务**

```bash
git add docs/architecture/story-system-phase5.md \
        webnovel-writer/references/genre-profiles.md \
        README.md \
        docs/architecture/overview.md \
        docs/guides/commands.md \
        docs/operations/operations.md \
        docs/superpowers/README.md
git commit -m "docs: finalize phase5 legacy downgrade"
```

---

## Self-Review

### Spec Coverage

- `13.6 Phase 5：旧链路降级`
  - Task 1 负责统一 runtime 来源与 commit provenance
  - Task 2 负责默认主输入与默认写后事实切换
  - Task 3 负责 skills / agents 提示词切链
  - Task 4 负责 preflight / dashboard / health 观测
  - Task 5 负责 fallback-only 文档封板与命令手册

- `7.2 运行时优先级`
  - Task 2 显式把 `story_contracts -> latest accepted commit -> legacy fallback` 固化到入口层

- `7.3 写后真理源`
  - Task 1 与 Task 2 让 `CHAPTER_COMMIT` 成为唯一写后事实入口

- `17.1 文档更新要求`
  - Task 5 覆盖架构文档、命令文档、运维手册与总览文档

### Placeholder Scan

- 全文没有延后实现的占位表述
- 每个任务都给了具体文件、测试、命令和提交信息
- 没有用跨任务引用代替实际步骤

### Type Consistency

本计划统一使用以下命名，不在后续任务中换名：

- `RuntimeSourceSnapshot`
- `load_runtime_sources(project_root, chapter)`
- `build_story_runtime_health(project_root, chapter=None)`
- `latest_accepted_commit`
- `fallback_sources`
- `write_fact_role = "chapter_commit"`

---

## Execution Handoff

Plan complete and saved to `docs/superpowers/plans/2026-04-13-story-system-phase5-legacy-downgrade.md`. Two execution options:

**1. Subagent-Driven (recommended)** - I dispatch a fresh subagent per task, review between tasks, fast iteration

**2. Inline Execution** - Execute tasks in this session using executing-plans, batch execution with checkpoints

Which approach?