Updated the prompts for quality control

Author: Robert Weber

novelforge/agents/chapter/pipeline.py

@@ -111,16 +111,31 @@ def run_per_chapter_compression_check(chapter_num: int, chapter_summary: str, pr
         return ""
 
 
-def run_character_state_updater(chapter_text: str, chapter_summary: str, characters_text: str, chapter_num: int, title: str,
-                                 degraded_passes: list[dict] | None = None) -> str:
-    """Run the character state updater, returning state changes or empty string on failure."""
+def run_character_state_updater(
+    chapter_text: str, chapter_summary: str, characters_text: str,
+    chapter_num: int, title: str,
+    degraded_passes: list[dict] | None = None,
+) -> tuple[str, list[dict]]:
+    """Run the character state updater, returning ``(state_log, ledger_updates)``.
+
+    ``state_log`` is the bullet-point character state text (empty string on
+    failure). ``ledger_updates`` is a list of object-ledger delta records
+    (empty list on failure or when no plot-critical object moved). The
+    caller merges ledger_updates into a cumulative object ledger keyed by
+    ``object_name``.
+
+    If the LLM returns plain text instead of JSON (for example because the
+    prompt change landed mid-run), the text is treated as the state log and
+    the ledger updates are an empty list.
+    """
     try:
-        return call_llm(
+        raw = call_llm(
             build_character_state_updater_prompt(
                 chapter_text=chapter_text, chapter_summary=chapter_summary,
                 characters_text=characters_text, chapter_num=chapter_num, title=title,
             ),
-            action=f"Running Character State Updater for Chapter {chapter_num}"
+            action=f"Running Character State Updater for Chapter {chapter_num}",
+            json_mode=True,
         )
     except Exception as exc:
         failure_summary = _log_pass_failure(
@@ -133,7 +148,33 @@ def run_character_state_updater(chapter_text: str, chapter_summary: str, charact
                 "chapter_num": chapter_num,
                 "failure_summary": failure_summary,
             })
-        return ""
+        return "", []
+
+    # Tolerant parse: JSON preferred, plain text accepted as legacy fallback.
+    try:
+        data = parse_llm_json(raw)
+    except Exception:
+        data = None
+    if isinstance(data, dict):
+        state_log = str(data.get("character_state_log", "") or "").strip()
+        ledger_updates_raw = data.get("object_ledger_updates", [])
+        ledger_updates: list[dict] = []
+        if isinstance(ledger_updates_raw, list):
+            for item in ledger_updates_raw:
+                if not isinstance(item, dict):
+                    continue
+                object_name = str(item.get("object_name", "")).strip()
+                if not object_name:
+                    continue
+                ledger_updates.append({
+                    "object_name": object_name,
+                    "current_holder": str(item.get("current_holder", "")).strip(),
+                    "last_transfer_method": str(item.get("last_transfer_method", "")).strip(),
+                    "plot_critical": bool(item.get("plot_critical", True)),
+                })
+        return state_log, ledger_updates
+    # Legacy / non-JSON response: keep the text and emit no ledger updates.
+    return str(raw or "").strip(), []
 
 
 def _apply_name_substitution(text: str, old_name: str, replacement: str) -> str:
@@ -361,6 +402,9 @@ def run_continuity_gatekeeper(
     chapter_num: int, chapter_title: str, chapter_summary: str, previous_summaries: str,
     chapter_timeline_context: str = "", chapter_fate_context: str = "",
     chapter_arc_context: str = "", character_state_log: str = "",
+    chapter_technology_context: str = "",
+    chapter_rhythm_shape: str = "",
+    object_ledger_context: str = "",
     degraded_passes: list[dict] | None = None,
 ) -> str:
     """Run the pre-chapter continuity gatekeeper, returning a brief or empty string on failure."""
@@ -373,6 +417,9 @@ def run_continuity_gatekeeper(
                 chapter_fate_context=chapter_fate_context,
                 chapter_arc_context=chapter_arc_context,
                 character_state_log=character_state_log,
+                chapter_technology_context=chapter_technology_context,
+                chapter_rhythm_shape=chapter_rhythm_shape,
+                object_ledger_context=object_ledger_context,
             ),
             action=f"Running Continuity Gatekeeper for Chapter {chapter_num}",
         )

novelforge/agents/chapter/prompts.py

@@ -116,8 +116,15 @@ def build_chapter_draft_prompt(
     voice_prompt: str = "", perspective_prompt: str = "",
     procedural_exemplars: str = "", chapter_openings_log: str = "",
     consequence_log: str = "", total_chapters: int = 0,
+    object_ledger_context: str = "",
 ) -> list[dict[str, str]]:
-    """Build the initial chapter draft prompt with all planning context."""
+    """Build the initial chapter draft prompt with all planning context.
+
+    ``object_ledger_context`` carries the cumulative chain-of-custody for
+    plot-critical items. When non-empty, the draft prompt surfaces each
+    item's current holder so the LLM does not invent new custody (giving a
+    character an object they don't canonically hold).
+    """
     return render_prompt(
         "chapter_draft",
         title=title, genre=genre, premise=premise,
@@ -146,6 +153,7 @@ def build_chapter_draft_prompt(
         soft_limited_words=", ".join(get_soft_limited_words(genre)),
         voice_prompt=voice_prompt or "",
         perspective_prompt=perspective_prompt or "",
+        object_ledger_context=object_ledger_context or "",
     )
 
 
@@ -380,8 +388,28 @@ def build_continuity_gatekeeper_prompt(
     chapter_num: int, chapter_title: str, chapter_summary: str, previous_summaries: str,
     chapter_timeline_context: str = "", chapter_fate_context: str = "",
     chapter_arc_context: str = "", character_state_log: str = "",
+    chapter_technology_context: str = "",
+    chapter_rhythm_shape: str = "",
+    object_ledger_context: str = "",
 ) -> list[dict[str, str]]:
-    """Build the pre-chapter continuity validation prompt."""
+    """Build the pre-chapter continuity validation prompt.
+
+    ``chapter_technology_context`` carries the world-rule specification
+    (``rules`` array plus supplementary detail) for this chapter. When
+    present, the gatekeeper is expected to flag scenes that violate any
+    rule's forbidden clause or alter its cost.
+
+    ``chapter_rhythm_shape`` carries the assigned rhythm. When it is
+    ``"climax-focal"`` or ``"aftermath"`` (the two reserved climax-gate
+    rhythms) the gatekeeper enforces the extra rules in the template —
+    blocking deferred climactic choices, externally-resolved climaxes, and
+    post-climax re-staging.
+
+    ``object_ledger_context`` carries the cumulative chain-of-custody for
+    plot-critical items. When non-empty, the gatekeeper flags any
+    chapter-plan scene that would have a character interact with an object
+    they do not canonically hold, without an explicit transfer scene.
+    """
     return render_prompt(
         "continuity_gatekeeper",
         chapter_num=chapter_num, chapter_title=chapter_title,
@@ -391,6 +419,9 @@ def build_continuity_gatekeeper_prompt(
         chapter_fate_context=chapter_fate_context or "",
         chapter_arc_context=chapter_arc_context or "",
         character_state_log=character_state_log or "",
+        chapter_technology_context=chapter_technology_context or "",
+        chapter_rhythm_shape=chapter_rhythm_shape or "",
+        object_ledger_context=object_ledger_context or "",
     )
 
 

novelforge/agents/planning/character_arc.py

@@ -80,6 +80,35 @@ def _build_fallback_impl(character_list: list[dict], chapter_list: list[dict]) -
                 {"chapter": vuln_ch_2, "scene": f"{name} shows vulnerability through action — admits fault, asks for help, or breaks composure."},
             ]
 
+            # Plant 2-3 foreshadow beats per major pivot in earlier chapters
+            # so each arc turn (midpoint, crisis, final) feels earned.
+            # Foreshadow chapters are clamped to land BEFORE the pivot they
+            # telegraph, and at least chapter 2 to leave room for setup.
+            def _foreshadow_chapters(pivot_ch: int) -> list[int]:
+                slots = [
+                    max(2, pivot_ch - max(1, pivot_ch // 3)),
+                    max(2, pivot_ch - max(1, pivot_ch // 2)),
+                ]
+                return sorted({c for c in slots if c < pivot_ch})
+
+            foreshadow_beats: list[dict] = []
+            for pivot_label, pivot_ch in (
+                ("midpoint", midpoint_chapter),
+                ("crisis", crisis_chapter),
+                ("final", final_chapter),
+            ):
+                for fch in _foreshadow_chapters(pivot_ch):
+                    foreshadow_beats.append({
+                        "chapter": fch,
+                        "foreshadows": pivot_label,
+                        "beat": (
+                            f"Plant a small, dramatized moment for {name} that "
+                            f"telegraphs the upcoming {pivot_label} — a line of "
+                            f"dialogue, a decision, or a visible reaction that "
+                            f"the reader will recognize in retrospect."
+                        ),
+                    })
+
             arcs.append(
                 {
                     "character": name,
@@ -110,6 +139,7 @@ def _build_fallback_impl(character_list: list[dict], chapter_list: list[dict]) -
                         },
                     ],
                     "vulnerability_scenes": vulnerability_scenes,
+                    "foreshadow_beats": foreshadow_beats,
                     "consistency_rules": [
                         "Arc must move forward each appearance.",
                         "No regression to start state after midpoint without explicit cause.",
@@ -187,6 +217,31 @@ def normalise(self, data: dict, **ctx) -> dict:
                     "scene": str(vs.get("scene", "")).strip(),
                 })
 
+            # Foreshadow beats — scheduled plants for upcoming pivots. Each
+            # beat binds a chapter to a specific pivot it telegraphs; the
+            # per-chapter Character agent verifies the beat is on-page when
+            # the scheduled chapter is written. Records missing a non-empty
+            # ``beat`` field are dropped (they cannot be verified).
+            foreshadow_beats = item.get("foreshadow_beats", [])
+            if not isinstance(foreshadow_beats, list):
+                foreshadow_beats = []
+            normalised_foreshadow: list[dict] = []
+            allowed_pivots = {"midpoint", "crisis", "final"}
+            for fb in foreshadow_beats:
+                if not isinstance(fb, dict):
+                    continue
+                beat_text = str(fb.get("beat", "")).strip()
+                if not beat_text:
+                    continue
+                foreshadows = str(fb.get("foreshadows", "")).strip().lower()
+                if foreshadows not in allowed_pivots:
+                    foreshadows = "midpoint"
+                normalised_foreshadow.append({
+                    "chapter": _coerce_positive_int(fb.get("chapter"), 1),
+                    "foreshadows": foreshadows,
+                    "beat": beat_text,
+                })
+
             normalised_arcs.append(
                 {
                     "character": name,
@@ -200,6 +255,7 @@ def normalise(self, data: dict, **ctx) -> dict:
                     "arc_theme": str(item.get("arc_theme", "")).strip(),
                     "chapter_beats": normalised_beats,
                     "vulnerability_scenes": normalised_vuln,
+                    "foreshadow_beats": normalised_foreshadow,
                     "consistency_rules": [str(x) for x in consistency_rules if str(x).strip()],
                 }
             )
@@ -263,7 +319,15 @@ def get_chapter_context(self, plan: dict, chapter_num: int) -> str:
                 if isinstance(vs, dict) and _coerce_positive_int(vs.get("chapter"), 0) == chapter_num
             ]
 
-            if matching_beats or matching_vuln:
+            foreshadow_beats = arc.get("foreshadow_beats", [])
+            if not isinstance(foreshadow_beats, list):
+                foreshadow_beats = []
+            matching_foreshadow = [
+                fb for fb in foreshadow_beats
+                if isinstance(fb, dict) and _coerce_positive_int(fb.get("chapter"), 0) == chapter_num
+            ]
+
+            if matching_beats or matching_vuln or matching_foreshadow:
                 lines.append(
                     f"- {char_name}: start={arc.get('start_state', '')}; midpoint={arc.get('midpoint_transformation', '')}; "
                     f"crisis={arc.get('crisis_point', '')}; final_choice={arc.get('final_moral_choice', '')}"
@@ -281,6 +345,13 @@ def get_chapter_context(self, plan: dict, chapter_num: int) -> str:
                         f"  - *** VULNERABILITY SCENE (this chapter): {vs.get('scene', '')} — "
                         f"Show this through ACTION and DIALOGUE, not narration. ***"
                     )
+                for fb in matching_foreshadow:
+                    pivot = str(fb.get("foreshadows", "")).strip() or "upcoming pivot"
+                    lines.append(
+                        f"  - *** FORESHADOW BEAT (this chapter, telegraphs {pivot}): "
+                        f"{fb.get('beat', '')} — Must appear on-page through a "
+                        f"dramatized moment (dialogue, decision, or visible reaction). ***"
+                    )
                 rules = arc.get("consistency_rules", [])
                 if isinstance(rules, list) and rules:
                     lines.append("  - Arc rules: " + "; ".join(str(x) for x in rules[:4]))

novelforge/agents/planning/technology_rules.py

@@ -37,6 +37,17 @@ def _build_fallback_impl(chapter_list: list[dict]) -> dict:
         """Create a deterministic fallback with a single surveillance system and chapter constraints."""
         safe_chapter_list = _safe_chapter_list(chapter_list)
         total_chapters = max(1, len(safe_chapter_list))
+        # Minimal default rules — intentionally sparse. The fallback exists
+        # only when the LLM call fails entirely; a real novel's LLM output
+        # will supply 4-10 concrete, genre-appropriate rules.
+        rules = [
+            {
+                "capability": "Primary detection apparatus",
+                "cost": "Finite compute budget; cannot run every check simultaneously.",
+                "forbidden": "Instant omniscient tracking of all targets; retroactive perfect reconstruction of past events.",
+                "exception": "none",
+            }
+        ]
         systems = [
             {
                 "name": "Primary Surveillance Grid",
@@ -60,6 +71,7 @@ def _build_fallback_impl(chapter_list: list[dict]) -> dict:
                 "must_not_allow": ["Do not grant instant detection or infinite processing without explicit setup."],
             })
         return {
+            "rules": rules,
             "systems": systems,
             "global_constraints": [
                 "Every tech action has delay, uncertainty, or resource cost.",
@@ -76,6 +88,29 @@ def normalise(self, data: dict, **ctx) -> dict:
         if not isinstance(data, dict):
             return fallback
 
+        # Normalise the authoritative `rules` array. Each rule must have a
+        # non-empty `capability`; other fields default to empty string or
+        # "none" so the gatekeeper can always render them.
+        raw_rules = data.get("rules", [])
+        if not isinstance(raw_rules, list):
+            raw_rules = []
+        normalised_rules: list[dict] = []
+        seen_capabilities: set[str] = set()
+        for item in raw_rules:
+            if not isinstance(item, dict):
+                continue
+            capability = str(item.get("capability", "")).strip()
+            if not capability or capability.lower() in seen_capabilities:
+                continue
+            seen_capabilities.add(capability.lower())
+            exception = str(item.get("exception", "")).strip() or "none"
+            normalised_rules.append({
+                "capability": capability,
+                "cost": str(item.get("cost", "")).strip(),
+                "forbidden": str(item.get("forbidden", "")).strip(),
+                "exception": exception,
+            })
+
         raw_systems = data.get("systems", [])
         if not isinstance(raw_systems, list):
             raw_systems = []
@@ -126,21 +161,47 @@ def normalise(self, data: dict, **ctx) -> dict:
             continuity_risks = []
 
         return {
+            "rules": normalised_rules or fallback["rules"],
             "systems": normalised_systems or fallback["systems"],
             "global_constraints": [str(x) for x in global_constraints if str(x).strip()] or fallback["global_constraints"],
             "chapter_constraints": normalised_constraints or fallback["chapter_constraints"],
             "continuity_risks": [str(x) for x in continuity_risks if str(x).strip()],
         }
 
     def get_chapter_context(self, plan: dict, chapter_num: int) -> str:
-        """Format technology systems and constraints as a prompt snippet for a chapter."""
+        """Format world rules, systems, and constraints as a prompt snippet for a chapter.
+
+        Rules are surfaced at the top as the primary, enforceable constraints
+        the Continuity Gatekeeper should match chapter plans against. Other
+        fields (systems, global/chapter constraints, continuity risks) are
+        supplementary detail.
+        """
         if not isinstance(plan, dict):
             return ""
 
+        lines = ["Technology Rules Designer output for this chapter:"]
+
+        # Primary: enforceable rules (capability / cost / forbidden / exception).
+        rules = plan.get("rules", [])
+        if isinstance(rules, list) and rules:
+            lines.append("- ENFORCEABLE RULES:")
+            for rule in rules[:10]:
+                if not isinstance(rule, dict):
+                    continue
+                capability = str(rule.get("capability", "?")).strip() or "?"
+                cost = str(rule.get("cost", "")).strip()
+                forbidden = str(rule.get("forbidden", "")).strip()
+                exception = str(rule.get("exception", "")).strip() or "none"
+                lines.append(f"  - Rule '{capability}':")
+                if cost:
+                    lines.append(f"    · cost: {cost}")
+                if forbidden:
+                    lines.append(f"    · forbidden: {forbidden}")
+                lines.append(f"    · exception: {exception}")
+
         systems = plan.get("systems", [])
         if not isinstance(systems, list):
             systems = []
-        lines = ["Technology Rules Designer output for this chapter:"]
         for system in systems[:6]:
             if not isinstance(system, dict):
                 continue