writer: spoken WORDS size the audio, not the number of lines

The length table counts spoken lines, and a line runs from six words to twenty.
Six words is 2.4 s of a 10 s hop. chain_00059 was written one six-word line per
10 s hop -- inside the word band, one line short of the row -- and rendered
17.8%, 10.9% and 6.6% voiced across its three hops, longest continuous voiced
run 0.5 s. Fragments, not speech. The line lint alone would have called it one
line short and left the author no idea how far short that actually was.

`count_beat` returns the spoken words too, and validate does the arithmetic out
loud: "6 spoken words is about 2.4s of speech in a 10s hop. A character written
as talking throughout needs roughly 25." The number the author needs is not the
number of lines.

The floor is half the hop, deliberately lenient: a beat is allowed to be action
as well as talk, and the point is to catch a hop that cannot possibly be filled
rather than to demand wall-to-wall dialogue. A hop with no speech at all says
nothing here -- that is what the line lint is for.

build_user_turn states the same arithmetic on the pinned path, so the draft
starts closer instead of being corrected afterwards.

PROMPTING.md now says outright that a written plan is a strong draft rather
than a finished one, and names the two things to read every time: the `desc` on
each ref, and the spoken words in each beat.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014VB4Dw6F79643vySkf19KV

PROMPTING.md

@@ -630,3 +630,24 @@ a `shot_plan` and `ref_plan` this node accepts:
 
 The node still validates everything, so a model that gets it wrong is caught
 rather than obeyed.
+
+**Treat a written plan as a strong draft, not a finished one.** It will get the
+structure right -- tags, retention tiers, schedules, directives, a beat per hop
+that reads as one continuous take -- and that is the part that is tedious to
+write by hand and easy to get subtly wrong. What it will not reliably get right
+is judgement about your particular pictures and your particular scene. Two
+things to read every time before you queue:
+
+- **The `desc` on each ref.** It is written from the photograph and it goes into
+  the prompt verbatim as what to carry over, so a wrong one is actively
+  harmful -- a wardrobe plate described as "a dark top" when the garment is
+  white will fight the picture it came from. Vision quality varies a lot
+  between models here.
+- **The spoken words in each beat.** Speech runs about 2.5 words a second, so a
+  10 s hop of someone talking needs roughly 25 words inside the quotes. Models
+  write one short line and stop. The panel now warns with the arithmetic, and
+  the fix is to write the extra sentences yourself.
+
+Everything the panel flags is a warning rather than a rejection, because all of
+it is legitimate to want on purpose. Read the warnings, fix what you meant
+differently, and queue.

planner.py

@@ -80,12 +80,30 @@ def beat_table():
     return out
 
 
+# Words per second of ordinary speech. ~150 wpm is the conversational figure
+# and it matches what this model renders: chain_00059 hop 1 carried six spoken
+# words and measured 1.8 s of voiced audio.
+SPEECH_WPS = 2.5
+
+# How much of a hop a speaking character should actually be speaking for. Below
+# this there are seconds of someone visibly mid-sentence with nothing assigned,
+# and the model fills them itself -- as fragments (chain_00059: 17.8% voiced,
+# longest run 0.5 s) or as invented dialogue (chain_00048). Half is deliberately
+# lenient: a beat is allowed to be action as well as talk, and the point is to
+# catch a hop that cannot possibly be filled, not to demand wall-to-wall speech.
+SPEECH_MIN_SHARE = 0.5
+
+
 def count_beat(beat):
-    """(words, spoken_lines) for one beat.
+    """(words, spoken_lines, spoken_words) for one beat.
 
     A spoken line is a single-quoted span. The delimiter test is a quote that is
     NOT between two word characters, because the beats are full of apostrophes
     that are: "Today's class was absolutely exhausting" is one line, not two.
+
+    `spoken_words` is what is inside those spans. Lines are the wrong unit on
+    their own -- a line runs from six words to twenty, and six words is 2.4 s
+    of a 10 s hop.
     """
     text = str(beat or "")
     words = len(text.split())
@@ -93,7 +111,10 @@ def count_beat(beat):
     delims = [i for i in marks
               if not (i > 0 and text[i - 1].isalnum()
                       and i + 1 < len(text) and text[i + 1].isalnum())]
-    return words, len(delims) // 2
+    spoken = 0
+    for a, b in zip(delims[0::2], delims[1::2]):
+        spoken += len(text[a + 1:b].split())
+    return words, len(delims) // 2, spoken
 
 
 def schema():
@@ -184,7 +205,7 @@ def validate(shot_text, ref_text, *, hops=None, known_files=None, pinned=None,
     to the person but never retried, because a model asked to fix a lint it
     disagrees with tends to rewrite the parts that were fine.
     """
-    from .h3_ref_chain import DURATION_FRAMES
+    from .h3_ref_chain import DURATION_FRAMES, FPS
 
     errors, warnings = [], []
 
@@ -246,7 +267,7 @@ def validate(shot_text, ref_text, *, hops=None, known_files=None, pinned=None,
         if not row:
             continue
         w0, w1, l0, l1 = row
-        words, spoken = count_beat((sh or {}).get("beat"))
+        words, spoken, spoken_words = count_beat((sh or {}).get("beat"))
         label = str((sh or {}).get("duration") or duration).strip()
         if words < w0 or words > w1:
             warnings.append(
@@ -262,6 +283,20 @@ def validate(shot_text, ref_text, *, hops=None, known_files=None, pinned=None,
                 f"{l0}" + (f"-{l1}" if l1 > l0 else "") + ". The line count is "
                 "a floor as well as a ceiling -- speaking seconds with nothing "
                 "assigned come back as invented dialogue.")
+        # Lines are the wrong unit on their own: one runs from six words to
+        # twenty. This is the arithmetic, and it is worth stating outright
+        # because the number the author needs is not the number of lines.
+        secs = DURATION_FRAMES.get(label, 0) / float(FPS or 24)
+        if spoken_words and secs:
+            speech = spoken_words / SPEECH_WPS
+            if speech < secs * SPEECH_MIN_SHARE:
+                warnings.append(
+                    f"shot {i + 1}: {spoken_words} spoken words is about "
+                    f"{speech:.1f}s of speech in a {secs:.0f}s hop. A character "
+                    f"written as talking throughout needs roughly "
+                    f"{int(secs * SPEECH_WPS)}. The seconds left over are a "
+                    f"person visibly mid-sentence with nothing assigned, and "
+                    f"the model fills them itself.")
 
     # A person with pictures but no continuity text still *renders*, which is
     # why `refs.check` only warns. The writer is the one place that can fill
@@ -548,6 +583,22 @@ def build_user_turn(brief, hops, files, pinned=None, duration=None):
             + (f"{l0}-{l1} spoken lines" if l1 > l0 else
                f"{l0} spoken line" + ("" if l0 == 1 else "s"))
             + ". Count both in every beat before you answer.")
+        # Lines alone do not size the audio: one runs from six words to twenty,
+        # and six words is 2.4 s of a 10 s hop. Live, a 3x10 s vlog written
+        # with one six-word line per hop rendered 17.8% voiced, in fragments.
+        try:
+            from .h3_ref_chain import DURATION_FRAMES, FPS  # noqa: PLC0415
+            secs = DURATION_FRAMES.get(str(duration).strip(), 0) / float(FPS or 24)
+        except Exception:
+            secs = 0
+        if secs:
+            lines.append(
+                f"Speech runs about {SPEECH_WPS:g} words a second, so a "
+                f"character who talks for most of a {secs:.0f}s hop needs "
+                f"roughly {int(secs * SPEECH_WPS)} words INSIDE the quotes -- "
+                f"several sentences, not one. Count the spoken words too. "
+                f"A hop where nobody speaks is fine, but say so: name the "
+                f"sound the room makes instead.")
     pinned = [p for p in (pinned or []) if isinstance(p, dict)]
     if pinned:
         lines += ["",

tools/check_planner.py

@@ -396,6 +396,31 @@ def main():
     ck("and overruled when the rail has one",
        overruled["refs"][0].get("mp") == 0.54)
 
+    # Spoken WORDS, not lines. A line runs from six words to twenty, and six
+    # words is 2.4 s of a 10 s hop: chain_00059 was written one six-word line
+    # per 10 s hop and rendered 17.8% voiced, longest run 0.5 s.
+    ck("apostrophes are not quote delimiters",
+       PL.count_beat("She says, 'Today's class was long.' She waits.") == (8, 1, 4),
+       repr(PL.count_beat("She says, 'Today's class was long.' She waits.")))
+    ck("two spans are counted as two lines",
+       PL.count_beat("'I am happy!' and 'I never want to leave.'")[1:] == (2, 8),
+       repr(PL.count_beat("'I am happy!' and 'I never want to leave.'")))
+
+    def _talk(spoken):
+        return json.dumps({"shots": [
+            {"id": "s1", "beat": "@ref_1 walks and says, '" + spoken
+                                 + "' She keeps going as the clip ends.",
+             "directives": {"tail": "hold"}}]})
+
+    thin = " ".join(["word"] * 6)          # 2.4 s of a 10 s hop
+    full = " ".join(["word"] * 25)         # about what 10 s holds
+    for label, spoken, want in (("a six-word line in a 10 s hop is flagged", thin, True),
+                                ("twenty-five words is not", full, False)):
+        _, ws = PL.validate(_talk(spoken), json.dumps(GOOD_REFS), hops=1,
+                            known_files=kf, duration="10 s")
+        ck(label, any("spoken words is about" in w for w in ws) == want,
+           "; ".join(w for w in ws if "spoken words" in w)[:110])
+
     # A wardrobe plate on a continuation hop brings its own room. chain_00034
     # was this on hop 2; the 3x10 s portrait chain on 2026-09-02 was this on
     # hop 3 -- podcast_host.jpg is her sitting in a studio, it rode all three