Refmod verbatim is now machine-checked: outline_refmods() extracts the story's identity/voice block from the outline's subjects strings and diffs every scene's subject_definitions line against it (fragment --outline + the merge); rewrites, form swaps and invented refmods fail with actionable errors; embedded suite gains the gate fixtures and stays under Cline's 8k output cap (7,712 B)

This commit is contained in:
Z User 2026-10-31 01:19:46 +00:00
parent dc8d9fab81
commit f6be7ffcc5
5 changed files with 206 additions and 17 deletions

View File

@ -21,5 +21,10 @@ rules hold on every task regardless:
`.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py --check <file>`
(output under 1 KB). Use `python` if there is no `.venv`, `py -3` if `python` is not
on PATH.
- A user refmod is verbatim or it is wrong: when the outline's `subjects` string carries
`identity: ...; voice: ...`, every scene's `subject_definitions` line for that subject
is a character-for-character copy of the outline text (`<Subject N> identity: ...;
voice: ...`) — never reworded, reordered or summarized. Validate fragments with
`--outline outline.json`; the validator diffs the text and a rewrite fails the scene.
- The two big prompt files under `h3-plan-gate/` are read in the bounded line ranges
cited in SKILL.md Steps 1 and 3 — never whole when context is tight.

View File

@ -29,7 +29,7 @@ re-merged without touching the rest.
| `h3_plan_assembler_system_prompt.md` | Stage 4 LLM merge prompt — only when you cannot run scripts |
| `h3_plan_json_system_prompt.md` | Single-pass variant (whole plan in one turn) — fastest for 2–4 scene stories |
| `build_plan.py` | Deterministic Stage 4 merger — verifies the continuity across the chain and puts all the scenes together at the end: strips `_handoff`, injects `"prompt_prefix": [""]` + defaults, validates everything before writing `plan.json` |
| `verify_plan_rules.py` | Node-replica validator (final plans *and* per-turn fragments): six-section Ref2VA prompt contract, the three subject-definition forms, refmod isolation, structure, handoff truth, continuity, thin-scene floor — no word band — with an embedded test suite |
| `verify_plan_rules.py` | Node-replica validator (final plans *and* per-turn fragments): six-section Ref2VA prompt contract, the three subject-definition forms, refmod isolation, refmod wording diffed verbatim against the outline (`--outline` / the merge), structure, handoff truth, continuity, thin-scene floor — no word band — with an embedded test suite |
| `count_prompt_tokens.py` | o200k token counter for the prompt fences (needs `pip install tiktoken`) |
| `h3_agent_workflow_examples/` | Worked 3-scene candy-store run in the six-section Ref2VA setup (refmod-pinned `<Subject 1>` + no-image shopkeeper): `outline.json` → `scene_01..03.json` → `plan.json` |
@ -67,9 +67,13 @@ six-section Ref2VA prompt (`subject_definitions:` → `summary: [reference gener
object for the next turn. Optional gate after each turn:
```sh
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_02.json --index 2 --prev scene_01.json
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_02.json --index 2 --prev scene_01.json --outline outline.json
```
(`--outline` also checks the scene's id, duration and dialogue against the guide's row,
and diffs the user-refmod identity/voice text against the guide verbatim — a rewritten
subject_definition fails the scene instead of surfacing at delivery.)
(All command blocks below use the Windows venv form; on macOS/Linux replace
`.venv\Scripts\python.exe` with `python3`.)
@ -176,9 +180,9 @@ given over to making that one scene a complete composition, validating it before
moving to the next:
```sh
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_01.json --index 1 --total 3
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_02.json --index 2 --total 3 --prev scene_01.json
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_03.json --index 3 --total 3 --prev scene_02.json
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_01.json --index 1 --total 3 --outline outline.json
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_02.json --index 2 --total 3 --prev scene_01.json --outline outline.json
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_03.json --index 3 --total 3 --prev scene_02.json --outline outline.json
```
Each fragment carries the six-section Ref2VA prompt and a truthful `_handoff`. Note the

View File

@ -55,7 +55,7 @@ never compose a scene from a guide the user has not approved.
`@@CONTINUE@@` and REPLACE the remaining content (repeat the marker for very large
plans). The finished file must not contain the marker.
- Cline also cuts command output at 8,000 characters. The full embedded suite prints
~7.6 KB when it passes — right at the edge — and a failing run prints more. If suite
~7.7 KB when it passes — under the cap — and a failing run prints more. If suite
output arrives truncated (`[... output truncated ...]`) or the suite fails, ignore the
cut output and work per file: run `--check <file>` (its output is under 1 KB) and fix
one file at a time.
@ -110,7 +110,9 @@ subject_definitions, and the body references only `<Subject N>`). If the story's
carries a `characters:` block with refmod entries — `sam:&identity: <identity text>;
voice: <voice text>&` — copy the identity and voice text verbatim into that subject's
inventory string (the & marks are delimiters, never content); the scene turns must carry
them into subject_definitions untouched.
them into subject_definitions untouched. That inventory string is the machine-checked
source: the validator diffs every scene's refmod line against it, so a paraphrase there
cannot be repaired later.
### Subject pinning (three forms — decide here, use in every scene)
@ -155,12 +157,23 @@ and concrete — the validator has no word band, only a thin-scene floor, so nev
and never summarize. If Cline rejects a scene write with 'Editor input too large',
split it with the marker pattern from the rules above.
**Refmod copy rule (the one writers keep breaking):** if the outline's `subjects` string
for a subject carries `identity: ...; voice: ...` (user refmod), that scene's
`subject_definitions` line is a character-for-character COPY of the outline text, in the
`<Subject N> identity: ...; voice: ...` form. Select the text in `outline.json`, copy,
paste — never retype it from memory, never reword, reorder, trim or summarize it. The
commands below pass `--outline`, so the validator diffs the line against the guide and a
rewrite fails the scene on the spot.
```sh
py -3 "%USERPROFILE%\.agent\skills\h3-plan-gate\verify_plan_rules.py" fragment scene_01.json --index 1 --total 5
py -3 "%USERPROFILE%\.agent\skills\h3-plan-gate\verify_plan_rules.py" fragment scene_02.json --index 2 --total 5 --prev scene_01.json
py -3 "%USERPROFILE%\.agent\skills\h3-plan-gate\verify_plan_rules.py" fragment scene_01.json --index 1 --total 5 --outline outline.json
py -3 "%USERPROFILE%\.agent\skills\h3-plan-gate\verify_plan_rules.py" fragment scene_02.json --index 2 --total 5 --prev scene_01.json --outline outline.json
```
(`--total` is the scene count from the outline; `--prev` chains the previous file.)
(`--total` is the scene count from the outline; `--prev` chains the previous file;
`--outline` also checks the scene's id, duration and dialogue against the guide's row —
and diffs the user-refmod identity/voice text against it verbatim, so a rewritten
subject_definition fails here instead of at delivery.)
Each fragment is exactly this shape (the six-section Ref2VA prompt; the subject lines
use the pinning form chosen in the guide):
@ -291,7 +304,9 @@ and sampler latent or the video can come out square.
`<Subject N> binds to <Image N> : ...` (reference image — faithful to the image), or
`<Subject N> identity: ...; voice: ...` (user refmod — the story's tested wording
verbatim, the `&...&` wrapper stripped; exempt from the no-image bans). No form carries
a length cap.
a length cap. With `--outline` (and at the merge) the refmod identity/voice text is
diffed against the outline's inventory string — a rewritten definition fails the
validation, so carry the text through untouched.
- **Refmod isolation:** a refmod subject is referenced by the bare `<Subject N>` token
everywhere outside `subject_definitions` — the body never re-states the subject's name
and never re-describes the look or voice the refmod already pins (the workflow injects

View File

@ -21,7 +21,10 @@ Usage:
The outline file (from the scene agent's PROMPT A) is optional; it is auto-detected by
its "scenes" key. When present, fragment ids, durations, and dialogue are checked
against it in order. Fenced markdown JSON (```json ... ```) also parses.
against it in order, and every user-refmod subject's identity/voice text must arrive
in the fragments' subject_definitions verbatim (whitespace aside) - a scene that
rewrites the story's tested character block fails the merge. Fenced markdown JSON
(```json ... ```) also parses.
"""
import argparse
import json
@ -112,6 +115,16 @@ def main():
defaults = {"duration_seconds": d.get("duration_seconds", args.duration),
"steps": int(d.get("steps", args.steps))}
refmods = None
if outline:
cast = outline.get("style_and_cast")
refmods = vpr.outline_refmods(
cast.get("subjects") if isinstance(cast, dict) else None,
where="outline")
if refmods:
print("outline user refmods (verbatim-checked): "
+ ", ".join(refmods))
prev = None
final_shots = []
for i, (path, shot) in enumerate(shots_in, 1):
@ -123,7 +136,8 @@ def main():
"dialogue": row.get("dialogue") or []}
print(f"\nfragment {i}/{n} from {path}:")
prev = vpr.validate_fragment(shot, index=i, total=n,
prev_handoff=prev, expect=expect)
prev_handoff=prev, expect=expect,
refmods=refmods)
merged = {k: shot[k] for k in ("id", "prompt", "duration_seconds") if k in shot}
for extra in ("steps", "seed"):
if extra in shot:

View File

@ -11,6 +11,9 @@ a CLI:
python verify_plan_rules.py plan FILE # validate a final plan JSON
python verify_plan_rules.py fragment FILE # validate one scene fragment
[--index N] [--total N] [--prev PREV_FILE] # --prev chains the handoff
[--outline OUTLINE_JSON] # id/duration/dialogue + the
# user-refmod wording are
# checked against the guide
The prompt setup validated here (user-tested; authoritative over older docs):
@ -104,6 +107,12 @@ RETENTION_MARKERS = VISUAL_RETENTION_MARKERS | AUDIO_RETENTION_MARKERS
# full look woven into every scene body.)
REF2VA_REFMOD_RE = re.compile(r"^identity\s*:", re.I)
REF2VA_VOICE_SPLIT_RE = re.compile(r";\s*voice\s*:", re.I)
# An outline inventory string pins a user refmod when it carries the story's
# 'identity: ...; voice: ...' block (PROMPT A copies it verbatim from the
# story's characters: section). Unanchored on purpose - the inventory string
# has a '<Subject N> - ...' prefix before the block; REF2VA_REFMOD_RE is
# anchored to the line head and cannot find it.
OUTLINE_REFMOD_RE = re.compile(r"\bidentity\s*:", re.I)
REF2VA_BINDS_RE = re.compile(r"^binds\s+to\s+<Image\s+\d+>\s*:\s*\S", re.I)
REF2VA_WRAPPER_RE = re.compile(r"&")
REF2VA_DEF_SKINSTATE_RE = re.compile(
@ -367,6 +376,84 @@ def check_refmod_isolation(defined, rest_text, where):
f"re-describe the pinned look or voice (found: {', '.join(hits)})")
def outline_refmods(subjects, where="outline"):
"""User-refmod texts pinned by the outline's style_and_cast.subjects.
PROMPT A copies the story's tested 'identity: ...; voice: ...' block
verbatim into the subject's inventory string. Returns
{label: {"identity": str, "voice": str}} for every inventory string that
carries one. These are the source texts a scene's subject_definitions line
must reproduce verbatim (whitespace aside) - never rewritten.
"""
refmods = {}
if not isinstance(subjects, list):
return refmods
for entry in subjects:
if not isinstance(entry, str):
continue
m = re.match(r"\s*(<(?:Subject|Picture|Video|Audio)\s+\d+>)\s*(.*)$",
entry, re.S)
if not m:
continue
label, rest = m.group(1), m.group(2)
hit = OUTLINE_REFMOD_RE.search(rest)
if not hit:
continue
parts = REF2VA_VOICE_SPLIT_RE.split(rest[hit.end():], maxsplit=1)
if len(parts) != 2 or not parts[0].strip() or not parts[1].strip():
raise ValueError(
f"{where}: {label} pins a user refmod but its inventory string "
f"does not carry the story's complete "
f"'identity: <user text>; voice: <user text>' block - copy it "
f"from the story's characters: section verbatim")
clean = lambda s: " ".join(s.replace("&", " ").split())
refmods[label] = {"identity": clean(parts[0]), "voice": clean(parts[1])}
return refmods
def check_refmod_verbatim(defs, refmods, where):
"""The outline's user-refmod wording must arrive in subject_definitions
verbatim: the scene may not rewrite, reword, trim or re-summarize the
user's tested character block. refmods is None when no outline is in play
(nothing to diff); an empty dict means an outline with no refmod subject.
"""
if refmods is None:
return
for label, info in defs.items():
if info["form"] == "refmod" and label not in refmods:
raise ValueError(
f"{where}: {label} uses the user-refmod form 'identity: ...; "
f"voice: ...' but the outline does not pin it as a refmod. If "
f"the story carries a characters: refmod block for this "
f"subject, copy it verbatim into the outline's subjects string "
f"first ('identity: <user text>; voice: <user text>') and "
f"re-validate; otherwise use the no-image or binds form (the "
f"form is decided in the guide, then kept)")
for label, want in refmods.items():
info = defs.get(label)
if info is None:
raise ValueError(
f"{where}: the outline pins {label} as a user refmod "
f"(identity/voice) but subject_definitions has no {label} line")
if info["form"] != "refmod":
raise ValueError(
f"{where}: the outline pins {label} as a user refmod, so its "
f"subject_definitions line must be '<Subject N> identity: ...; "
f"voice: ...' carrying the outline's text verbatim - found the "
f"{info['form']} form instead ({info['line'].strip()[:60]!r})")
parts = REF2VA_VOICE_SPLIT_RE.split(info["text"], maxsplit=1)
got_id = " ".join(parts[0].split())
got_voice = " ".join(parts[1].split())
if got_id != want["identity"] or got_voice != want["voice"]:
raise ValueError(
f"{where}: {label} rewrites the user refmod - subject_definitions "
f"must carry the outline's tested wording verbatim (copy it from "
f"the outline's subjects entry; whitespace aside, every word "
f"must match). Expected identity: {want['identity'][:90]!r}; "
f"voice: {want['voice'][:90]!r}. Found identity: {got_id[:90]!r}; "
f"voice: {got_voice[:90]!r}")
def check_ref2va_prompt(text, where, duration=None):
"""Validate one compiled six-section Ref2VA prompt (the joined prompt lines
of one shot). Raises ValueError on the first broken rule.
@ -543,13 +630,17 @@ def check_ref2va_sections(plan):
# Scene-agent fragment validation (agent workflow)
# ---------------------------------------------------------------------------
def validate_fragment(obj, index=1, total=None, prev_handoff=None, expect=None):
def validate_fragment(obj, index=1, total=None, prev_handoff=None, expect=None,
refmods=None):
"""Validate one scene-agent fragment (the future shot of a plan).
obj -- parsed fragment: {id, prompt, duration_seconds, _handoff}
index/total -- position in the story (1-based) for messages
prev_handoff -- previous fragment's _handoff dict, or None for scene 1
expect -- optional outline row {id, duration_seconds, dialogue}
refmods -- {label: {identity, voice}} pinned by the outline (None =
no outline in play); the fragment's user-refmod wording is
diffed verbatim against it
Returns the fragment's _handoff so callers can chain turns.
"""
@ -591,6 +682,7 @@ def validate_fragment(obj, index=1, total=None, prev_handoff=None, expect=None):
f"non-empty strings")
info = check_ref2va_prompt(text, where, duration=dur)
check_refmod_verbatim(info["defined"], refmods, where)
body, ssc = info["body"], info["soundscape"]
wc = len(body.split())
@ -925,7 +1017,7 @@ def run_defs_suite():
validate_fragment(frag, index=1, total=1)
print(f" {label} UNEXPECTEDLY PASSED <-- BUG")
except (ValueError, AssertionError) as exc:
print(f" {label} rejected: {exc}")
print(f" {label} rejected: {str(exc)[:110]}")
def run_ref2va_fail_suite():
@ -1141,6 +1233,42 @@ edge_bad = [
]
def run_refmod_gate_suite():
"""The outline verbatim gate: a scene may not rewrite the user's refmod."""
print("\nOutline refmod verbatim gate:")
sam_block = ("identity: Sam is a 9 year old boy with his blonde hair in "
"pigtails that dresses like a baby girl; voice: Sam is a 9 "
"year old boy with his blonde hair in pigtails that dresses "
"like a baby girl")
subjects = [f"<Subject 1> — Sam (user refmod, carry verbatim into "
f"subject_definitions): {sam_block}"]
refmods = outline_refmods(subjects)
validate_fragment(dict(CANDY_BROWSE), index=1, total=2, refmods=refmods)
print(" verbatim copy: ok")
paraphrase = json.loads(json.dumps(refmods))
paraphrase["<Subject 1>"]["identity"] = (
"Sam is a 9 year old boy with golden pigtails that dresses like a "
"baby girl")
rewritten = dict(CANDY_BROWSE)
cases = [
("rewritten refmod text", rewritten, {"refmods": paraphrase}),
("refmod pinned, scene uses the no-image form",
dict(CANDY_BROWSE, prompt=[p.replace(SAM_REFMOD,
"<Subject 1> is a 9 year old boy with blonde hair in pigtails")
if p == SAM_REFMOD else p for p in CANDY_BROWSE["prompt"]]),
{"refmods": refmods}),
("invented refmod (outline pins none)", dict(CANDY_BROWSE),
{"refmods": {}}),
]
for label, obj, kwargs in cases:
try:
validate_fragment(obj, index=1, total=2, **kwargs)
print(f" {label} UNEXPECTEDLY PASSED <-- BUG")
except (ValueError, AssertionError) as exc:
print(f" {label} rejected: {str(exc)[:110]}")
def run_embedded_suite():
plan = {"prompt_prefix": [""],
"defaults": {"duration_seconds": 10, "steps": 5},
@ -1171,10 +1299,11 @@ def run_embedded_suite():
run_defs_suite()
run_ref2va_fail_suite()
run_chain_fail_suite()
run_refmod_gate_suite()
# delivered-duration math check used in the TIMING section
print("\nTiming table (raw frames from duration):")
for s in (0.2, 1, 2, 5, 10, 15, 30, 149.666, 149.667):
for s in (1, 2, 5, 10, 15, 149.666, 149.667):
try:
print(f" {s}s -> {_h3_frame_length(s)} raw frames")
except ValueError as exc:
@ -1196,6 +1325,9 @@ def main():
p_frag.add_argument("--total", type=int, default=None)
p_frag.add_argument("--prev", default=None,
help="previous fragment file; chains the soundscape handoff")
p_frag.add_argument("--outline", default=None,
help="outline JSON: also checks id, duration, dialogue and "
"the user-refmod wording against the guide")
args = parser.parse_args()
if args.cmd is None:
@ -1214,7 +1346,26 @@ def main():
if isinstance(pf, dict) and isinstance(pf.get("shots"), list) and pf["shots"]:
pf = pf["shots"][-1]
prev = pf.get("_handoff") if isinstance(pf, dict) else None
validate_fragment(raw, index=args.index, total=args.total, prev_handoff=prev)
expect = None
refmods = None
if args.outline:
try:
with open(args.outline, encoding="utf-8-sig") as fh:
ol = load_json_text(fh.read(), args.outline)
except OSError as exc:
raise SystemExit(f"{args.outline}: cannot read ({exc})")
cast = ol.get("style_and_cast") if isinstance(ol, dict) else None
refmods = outline_refmods(
cast.get("subjects") if isinstance(cast, dict) else None,
where=f"outline {args.outline}")
rows = ol.get("scenes") if isinstance(ol, dict) else None
if isinstance(rows, list) and 1 <= args.index <= len(rows):
row = rows[args.index - 1]
expect = {"id": row.get("id"),
"duration_seconds": row.get("duration_seconds"),
"dialogue": row.get("dialogue") or []}
validate_fragment(raw, index=args.index, total=args.total,
prev_handoff=prev, expect=expect, refmods=refmods)
print("OK")