Checks and balances

Every gate a script passes: the linter, the damage test, the ledger, the bar, the read-aloud pass and the readers.

The gate runner, check.js

node .claude/skills/video-script-production/scripts/check.js --dir research/<slug>/script --version vN [--prev vM] [--fix] [--no-selftest] [--facts FACTS.md]

It runs, in order: tool and file integrity, the chain JSON, the timecodes, lint, the damage test, the ledger check, the bar, the comparison with the previous version, and the manual gates read from HANDOFF-vN.md. It writes STATUS-vN.md and lint/. --fix rewrites stale heading timecodes first. --no-selftest skips the damage test while drafting; run it before you stop.

"Hard" gates decide the exit code. "Bar" gates decide whether BAR MET is printed.

B1: the v6 bar numbers

These are tighter than the linter so that a script that merely passes is not mistaken for a finished one.

The linter, lint.js (70 rules)

node scripts/lint.js --script SCRIPT-vN.md --chain chain-vN.json --label vN --out lint/

Without a chain it runs in text-only mode. Output: lint-<label>.json and .md; exit 1 on a FAIL. Thresholds are in scripts/rules.json; reasons in references/principles.md. The rule list as emitted on Moser Baer v7:

Key thresholds from rules.json: speaking pace 150 wpm; hook cap 110 seconds with at most 1 quantity; ladder rung 1 by 60% of runtime, rung 2 between 50% and 90%, rung 3 after 80%; at most 4 quantities in 30 seconds and 5 a minute; at most 7 hero numbers; beats 90 to 260 words; at most 3 live major loops; spine closes after 70%; pulls warm for 60 seconds, minimum 4 pulls and 3 kinds; rhythm windows of 30 seconds, a hard window is 2 or more quantities, a landing is at most 45 words; humans: protagonist named by word 160; person gap warn at 60 and fail at 100 seconds; dense beat is 7 quantities or 4 new names; headline at most 20 words, tease at most 30, takeaway at most 14.

How to treat a rule that fires

• FAIL: fix the script, never rules.json. references/lint-fixes.md lists what each rule usually means and the fix that worked.
• WARN: read it and decide. Heuristic rules (A4 naked numbers, C3 shared noun, F1 negation pivots) can be false alarms. Reword; do not raise the budget.
• Known false positives: "I couldn't find what it earned. It was still..." looks like a negation pivot; "moving on" matches the additive list even when it means leaving; "L&T" normalises to "lt", which sits inside "built" (rule A7); the sentence splitter ends sentences at "V.G."; D2 reads only digit figures, so number-words hide a first figure; comparison markers are a list and one phrase can count twice.

The damage test, selftest.js (56 checks on v7)

node scripts/selftest.js --script SCRIPT-vN.md --chain chain-vN.json

It breaks one property at a time (adds a greeting or a route term to the hook, stacks six figures in one breath, types a junction AND_THEN, moves a care line after its figure, strips a pull's touches, stacks negation pivots, and so on) and checks the matching rule fires. It tests the linter, not the script, and is the safety net when a rule or lint.js changes. A mutation counts only if the named rule fires, not a neighbour. A "MISS" means: find which text the test cut, and fix the text, not the rule. Mutations touch only **VO:** lines, because a quote can also occur in the notes sections. A chain that does not declare a section gets those mutations skipped (v6: 46 behave, 10 skipped).

The reason it exists: the damage test found loopholes in the project's own new rules. A role phrase ("its founder") counted as naming the protagonist; a name from three paragraphs earlier satisfied the dangling-pronoun test; the parable test looked only at the first and last line; two regex word boundaries had been written as backspace characters by the shell. Write the damage test for a new rule before trusting it, and try to pass the rule with a bad script.

The ledger check, ledger-check.js

Checks that every spoken digit figure is in the ledger as spoken (so "14 cents" requires the ledger to hold the words "14 cents", not only $0.14), that the four hand-off sections exist, and that [CHECK] rows reach the open items. It reads digit figures only; spelled numbers are not read. On its first run it found real gaps in v5 and v6: "14 cents" and "₹110 crore" were spoken while the ledger held $0.14 and ₹109.8 crore, and two refuted rival figures lived only in the do-not-use table.

The other deterministic tools

retime.js

Writes heading time ranges from word counts at 150 wpm (--write, --check).

extract-vo.js

Extracts the spoken text, numbered. Modes: timed (for the read-aloud pass), blind (for readers), plain (for copying into a TTS tool).

compare.js

Side-by-side text-level measures and beat openers across versions.

calibrate.js

Measures voice, rhythm, comparisons, admissions, "you" and name rates on a folder of winner transcripts, to set thresholds on data.

session-log.js

Writes every search, fetch and subagent of a Claude Code session as Markdown (the research record).

scaffold.js

Blank script, chain, FACTS and hand-off; --from vP copies the previous version.

The reference profile (Moser Baer v6)

The bar was set from the approved v6. Winners column: 8 English "why X died" transcripts (auto-captions of scripted voice-overs). Reproduce with calibrate.js --dir <winners> --script SCRIPT-vN.md.

v7: 70 of 70 rules, 56 of 56 damage checks, 20.2 minutes, 3,029 words, hook 107 s, 2.0 quantities a minute, 5 comparison markers, headlines on beats 3, 7, 9, 10 and 12. The v6 profile is kept because v6 is the script the user approved.

The contraction median differs by sample: 12 mixed English winners had about 1.5 per 100 words, the 8 captioned "why X died" winners 0.75, so the F5 floor of 1.0 and the bar of 1.5 are design choices.

The judgement bar

These cannot be checked by a machine. The author answers them in the read-aloud pass and readers answer them if authorised. A script that passes the mechanical bar and fails any of these is not finished.

1. The whole story is told: origin, rise with its mechanism, the first sign, the response, the fall, the people who paid, the blame question answered by the record, the lesson. Rule J1 forces a beat for each; it cannot judge whether the beat is rich.
2. The thesis is verified, not only the numbers. Every "X caused Y" has a source for the link; if not, the script says so aloud and states the weaker thesis.
3. A reader who has never seen the chain can say the argument back and knows who the main person is, what they wanted, and why a decision of theirs is a puzzle.
4. The first two minutes are not a menu.
5. The persona is likeable, not smug, is fair to both sides, and is never aloof about the people who paid.
6. Every figure of speech earns its place.
7. Every "I" is true of whoever will say it.
8. The title and the evidence agree, or the disagreement is stated to the user with alternates.
9. Nothing about a living person goes beyond the record; allegations are allegations.
10. Nobody is a stranger. (K)
11. Nothing needs decoding. (K)
12. The prize is felt before the fall, the turn is heard, the cost is said, and each beat is a small arc of doubt, edge and proof. (L)
13. A dense stretch opens with a headline, and the hook ends as a trailer. (M)

The read-aloud checklist (S9)

Print the spoken text (extract-vo.js --mode timed), read it in order as if saying it to one person, and answer each item. Each exists because a real defect of that kind passed a green linter. Record Read-aloud pass: done (<date>; what you found). A pass that found nothing is suspicious; look again at items 1 to 3.

What the reader cannot follow

1. Every pronoun and "the same thing" has its person or thing in the previous sentence. (v5's hook ended on "the city he left" with "he" last named three paragraphs earlier; v6 beat 3 had "the same thing" pointing at nothing.)
2. Every name, term and acronym is explained the first time it is spoken, in words a stranger would use.
3. No stretch is a pile-up of new names, figures and concepts, even if the figure count is within budget.

Claims

4. Nothing is asserted about what someone thought, felt or intended unless a source says it. Hedge or cut ("I think each step looked sensible").
5. No link is built on an adjacency the script itself says it cannot support.
6. A comparison shows scale, not innocence or guilt.
7. Hedges are true: every "I couldn't find" describes a check that was made, by whoever will say it.
8. Allegations and findings are kept apart; nobody is called a villain, crook or fraudster without a conviction.

Promises and flow

9. A tease is paid at the size it was sold.
10. Nothing is said twice (a recap after the thesis read as a third ending).
11. The join into every beat feels like "therefore" or "but". If "and then" fits, the flow is broken.
12. The hook promises experiences, not the route, and the learning it promises is paid in the close.

Voice

13. Say each sentence aloud in one breath. A sentence you would not say to a friend is written English.
14. The persona is fair and warm where it counts: aloof about verdicts, never about the workers; no sarcasm at a person; no claim to effort that was not made.
15. Each figure of speech helps: it explains, comes back, and its limit is honest.
16. The close is quiet and human and returns to the opening image.

Facts one more time

17. Units and magnitudes: crore against million, rupee against dollar, "doubled" against the arithmetic (1,620 to 3,500 is 2.2 times). Check the 7 hero numbers against the ledger by eye.
18. Dates: day, month and year of every dated event in the hook and pulls (the 21 June 2012 clock must be right).
19. Names: spelling, and whether a private person is named on the strength of one source.

Cast, turns and dense stretches (round 7)

20. The opening list is what the audience actually did, including the slightly guilty association.
21. The decode test: say each sentence to someone who has not read the research; rewrite any line they would have to work out.
22. The hook's last line is a person's act and a puzzle, not a place or a mechanism, with no manner (calm, cold) that no source gives.
23. Each beat is a small arc: the doubt, the person's edge, the proof. The edge must be one a source supports.
24. Restate the height before the fall point.
25. A cliffhanger lands in the viewer ("you'd do a double take"), not in an unnamed crowd.
26. A dense beat's headline is a trailer line, not a spoiler or a summary of the numbers; if it and the last line say the same thing, one goes.

After the pass, fix, run check.js again (edits can break a declared quote), and write the result in the hand-off. The round-7 pass found five defects, two of them created by the changes themselves (a "This pattern" with no antecedent once a line moved; a pair of "too").

The reader pass (S10; needs the user's permission)

Two Sonnet subagents get only the blind file. The viewer reads as a first-time viewer: per paragraph, the question in their head and their urge to keep watching 0 to 10; a confusion log; which figures they remember; for each topic shift, whether it felt like therefore, but or and-then; what they expect after 60 seconds; the argument back from memory; who the narrator is in three adjectives and whether they would trust them. The editor reads as a skeptical editor: the thesis as the script supports it, each causal claim rated supported-in-the-script, asserted-only or leaps; the swap and and-then tests on every boundary; load; every promise in the first 150 words and where it is paid; padding; claims about people. Readers must return their report as text. Run once on Moser Baer v4; v5, v6, v7 and Cafe Coffee Day v1 have had none.

What the v4 readers found that a 100/100 linter had not

• Two paragraphs too dense in names and terms (the linter counted figures, not people or jargon). K3, K4 and M1 were later built from this.
• A tease that was oversold ("something so strange you can't unsee" was paid by an ordinary pair of results).
• A link built on an adjacency the script could not support ("alongside all this, the company owed a bond").
• A comparison that showed scale and not innocence.
• A recap after the thesis that read as a third ending.
• Unglossed Philips, gigawatt, tribunal, Alchemist.
• That the title's "Killed" outran the evidence.

What each layer can and cannot prove

Written 2026-10-27 from the repository files and the project memory notes. If a page and a file disagree, the file is right: fix the page.