diff --git a/.clinerules/h3-plan-gate.md b/.clinerules/h3-plan-gate.md index 97ea6e6..a1879a4 100644 --- a/.clinerules/h3-plan-gate.md +++ b/.clinerules/h3-plan-gate.md @@ -21,5 +21,10 @@ rules hold on every task regardless: `.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py --check ` (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 (` 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. diff --git a/README.md b/README.md index 79c7050..499e972 100755 --- a/README.md +++ b/README.md @@ -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 `` + 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 diff --git a/h3-plan-gate/SKILL.md b/h3-plan-gate/SKILL.md index 8b51927..9093b9c 100755 --- a/h3-plan-gate/SKILL.md +++ b/h3-plan-gate/SKILL.md @@ -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 ` (its output is under 1 KB) and fix one file at a time. @@ -110,7 +110,9 @@ subject_definitions, and the body references only ``). If the story's carries a `characters:` block with refmod entries — `sam:&identity: ; voice: &` — 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 +` 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. ` binds to : ...` (reference image — faithful to the image), or ` 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 `` 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 diff --git a/h3-plan-gate/build_plan.py b/h3-plan-gate/build_plan.py index 9a36a19..07937b9 100755 --- a/h3-plan-gate/build_plan.py +++ b/h3-plan-gate/build_plan.py @@ -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: diff --git a/h3-plan-gate/verify_plan_rules.py b/h3-plan-gate/verify_plan_rules.py index 238bb1c..197d0a8 100755 --- a/h3-plan-gate/verify_plan_rules.py +++ b/h3-plan-gate/verify_plan_rules.py @@ -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 ' - ...' 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+\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: ; voice: ' 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: ; voice: ') 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 ' 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" — 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[""]["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, + " 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")