Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

fix: both routes look at every element once, and the reader is never the builder (#84)

rponeawa3e855607c721
diff --git a/.agents/skills/hypit/SKILL.md b/.agents/skills/hypit/SKILL.md
index 8eab0a57..d1ac6543 100644
--- a/.agents/skills/hypit/SKILL.md
+++ b/.agents/skills/hypit/SKILL.md
@@ -10,12 +10,14 @@ author for, and everything else is yours to decide:
- **Spending their money.** A Build generates, and generating is billed. Say what it will cost and
get a yes before submitting one.
-- **Which observer reads the reference, and the credentials it needs.** Vertex or the calling agent
- is a decision about the author's account, and `references/credentials.md` says what each one wants.
- Ask once, at the start.
+- **Which observer reads a reference video, and the credentials it needs.** Vertex or the calling
+ agent is a decision about the author's account, and `references/credentials.md` says what each one
+ wants. Ask once, at the start. This question belongs to the reconstruction route alone: a program
+ authored from a description has no reference, and its pictures are local renders nobody is billed
+ to read.
Everything else — the working directory, the project location, which packages to use, which generator
-draws a picture, how to name a Segment, what to do about a difference the comparison reported — is a
+draws a picture, how to name a Segment, what to do about something a review reported — is a
choice between things that all work, and asking costs the author an interruption to answer a question
the references already answer. Decide it and keep going. A run that stops half way with a question is
a run the author has to restart.
diff --git a/.agents/skills/hypit/references/element-review.md b/.agents/skills/hypit/references/element-review.md
new file mode 100644
index 00000000..73ac368d
--- /dev/null
+++ b/.agents/skills/hypit/references/element-review.md
@@ -0,0 +1,258 @@
+# Looking at what was built, before a Build runs
+
+Structural checks prove that a source is legal. They prove nothing about whether it looks like what
+was wanted. A newly written package can resolve, activate, decode and pass every check while drawing
+something nobody asked for. Close that gap deliberately.
+
+Both routes close it here, and both close it the same way: render one element as the Source
+configures it, have somebody who did not build it read the picture, repair what they named, and stop
+at a fixed ceiling. What differs is only the question put to the reader. A reconstruction has a
+reference, so it asks what differs — `reconstruction/comparison-round.md`. A program authored from
+a description has none, so it asks whether the picture is what it was asked to be —
+`original-authoring/conformance-round.md`. Read this file first and that one after.
+
+Whether an element is *wired at all* is a different gate with a different rule: `preview.md`'s
+`preview_check` must pass before this round is reached, and its failures are repaired without any
+attempt ceiling. A graph that does not trace is not a difference to weigh; it is work that is not
+done.
+
+Note what that gate covers: it proves the graph is wired, not that every track draws. Nothing is
+handed to a Producer until the Build runs, so a Producer that refuses the media it receives surfaces
+there rather than here.
+
+The difference between the two gates is what each reports. `preview_check` names the graph failure —
+the target that does not trace, the chain that is missing — so its repairs are not guessing. This round
+names what is visibly wrong with the picture, in words, and a repair aims at something the round
+named. Neither gate expects you to guess; each one tells you what is wrong, and you repair that.
+
+## The round covers one element at a time, across every stretch it is drawn over
+
+Loop over one authored element at a time — the new component, one caption system, one inserted card.
+
+### Render what the Source configures, not what the catalogue shows
+
+The thing read is the element **as this video places it**: the Recipe values the Source actually
+passes, the Script text the Source actually feeds it, and the windows the Source actually binds. A
+package's catalogue preview is a different picture drawn from different values — the package's own
+sample copy and sample Recipe, chosen to show a reader the Surface's range — and a Source can fill
+every one of those parameters with values that collide while the preview stays perfect. Reading the
+preview answers a question nobody asked. `preview.md` keeps the two apart, says which command draws
+which, and holds `render_element`'s own flags.
+
+`render_element` reads the Canvas, the Recipe values and the Script text out of the Source, mocks
+every layer a Build has not made, and drives the package's Producer. Nothing is transcribed by hand,
+so nothing is transcribed one line at a time — which is what made a caption system look correct while
+its lines collided.
+
+**It draws the whole stretch, not the element alone.** `--element` names which element the round is
+about; the picture is everything the Source places over those words, so two elements over one Segment
+produce the same picture. Scope it with `--question` — that is what tells the reader which part of it
+to read.
+
+The window is named in words. `--segment` and `--selection` take a Script name, never a timestamp:
+name the Segment or the Selection the element is drawn over, and give the same name to the round, so
+every picture covers the same words. `script-time.md` says why a name travels where a number cannot.
+
+### Mock the layers a Build has not made
+
+The element rarely draws the whole frame. Below it is a base take that does not exist yet, and inside
+it may be media slots the Source declares as generations. Render them as mocks rather than leaving
+them out: a missing base is not a neutral background, it is black, and text that is legible on black
+can be illegible on the picture that will replace it.
+
+`render_element` does this itself. It finds every generation the Source declares — the takes, the
+stills, the slot contents — calls `make-placeholder` for each at the Canvas's own size, and declares
+them in a derived Run under the project's `.hypit/`. Never `hypit image`, which pays for a generation
+the video will not reuse, and never a placeholder drawn by a script written for the occasion.
+
+The sizes come from the Source's `space:Canvas`, because the mock is composed inside the render and
+the render's geometry is the Canvas.
+
+Then tell the reader that those regions are placeholders standing in for declared-but-unbuilt
+generations, and to read only what the element itself draws. Said plainly it costs one clause and
+saves the mock coming back as a finding in the one round there is.
+
+A mock lives only in this render. It is never written into the Source, and no gate reads it: the
+`playback` check reads the Source's Recipes, so a mock cannot be mistaken for coverage.
+
+### The derived Run holds one Segment, not the whole Source
+
+The mocks are substituted into a Source that has already been cut to the window. `render_element`
+keeps the Segment the window names, drops the rest of the Script, and then drops every element that
+named a Segment, Selection or Moment that went with it — and every element naming one of those, to a
+fixed point, plus any container the cut left with no children. So an element bound to a Selection in
+another Segment is not in this render, and its absence says nothing about the Source.
+
+One name survives the cut rather than taking its element with it: a Moment in `until=` that is marked
+*after* the kept Segment. An element given the span it occupies and a Moment to close it is on screen
+for the whole of a stretch that ends before that word, so the cut removes the close and keeps the
+element. That is what makes an element bounded by a late Moment renderable over the earlier Segments
+it is drawn over, which is every stretch this round asks for it in.
+
+The cut Source is on disk at `<project>/.hypit/compare/sliced.svml`, byte-for-byte from the original
+except for what was removed, and the derived Run sits beside it. Open it whenever something you
+expected to see is not in the picture: an element that is not in the fragment was cut by the window,
+and one that is in the fragment and still not on screen is the package failing to draw it. Those two
+repair in opposite directions, and the fragment is what tells them apart.
+`packages/reference-video-tools/src/slice.ts` records the same thing as `SliceResult.dropped` — each
+dropped id and the name it could no longer reach — and explains what decides survival.
+
+### A caption Style is read once, where it first appears
+
+Captions are the one element where the stretches are not different questions. A caption system is one
+Style applied to whatever words fall under it, so two stretches drawn in the same Style differ only in
+which words they hold — the typeface, size, weight, box, padding and placement are the same
+declaration in both, and reading the second one returns the answer the first already gave.
+
+So read **one stretch per distinct Style**, at the first occurrence of that Style. A program with
+one default Style and a `caption:Use` override for one Selection is two looks, wherever those
+two first appear, not one per Segment. This is the same reading `script-time.md` applies to every
+other system that spans cuts: the system is authored once, so it is read once.
+
+What is not covered by that is anything a Style does not decide. A Cue that overflows the frame is a
+Segment nobody broke with `||` rather than a Style at the wrong width — `playbooks/craft/captions.md`
+says so — and it belongs to the stretch whose words are long, not to the Style.
+
+### Render every stretch first, then send them all at once
+
+No look's question depends on another's answer, so nothing is gained by waiting: rendering one and
+reading it before rendering the next makes the round as long as the sum of its parts. Render the
+whole set, then issue the round together.
+
+**Send all of an element's pictures before repairing anything.** A repair changes what the next
+picture would have shown, so a round interleaved with repairs is not one round — and what this round
+is for is the set of findings across every stretch, which only exists once they have all come back.
+
+## The reader is not the builder
+
+This is the rule the whole round rests on, and it is not a preference. Somebody who knows what was
+built, and what they hoped it would look like, confirms it. That is how a wrong typeface survives a
+look: it resembles what the builder remembers choosing.
+
+**Where the harness has subagents, one subagent per picture is required, and they run together.**
+Claude Code and Codex have them. Give each its own, hand it the `instruction`, the `prompt` verbatim,
+the `image_refs`, and — on a task that carries them — `transcript_ref` and `transcript_words`. Hand it
+nothing else. Not what you built, not which component drew it, not what you expect it to find, not
+another look's answer. Take the returned text and record it yourself, so one writer owns the log.
+
+**Do not open the pictures yourself.** Whatever visual ability the model running this round has, using
+it makes the reader and the builder the same reader, and the round stops being evidence of anything.
+This is the same prohibition the `gemini` observer gets for free by sending its pictures to a separate
+request; one subagent per task is what makes the other paths equal to it rather than merely faster.
+
+Answering inline is the fallback for a harness with no subagents, and only that. Read them one after
+another rather than merging them into a single look — what the round is for is the set of findings
+across stretches, and one answered in the light of the previous answer stops being independent
+evidence of anything. There the discipline has to be explicit, because the reader is the builder and
+nothing structural prevents it:
+
+- **Write down what you see before naming a cause.** List what is visibly there, in the words you
+ would use if you had never seen the Source. Deciding what went wrong first, then looking, finds what
+ you expected.
+- **Something you did not write down is not an attempt.** The two-attempt ceilings below count repairs
+ aimed at what the round named.
+- **Measure rather than iterate.** A stroke that is too thick, a shape that is too tall, a margin that
+ is too wide — read the number off the frame against the frame's own width and height, and change the
+ value once.
+
+## Repair in dependency order
+
+When the finding is structural rather than cosmetic, repair in the order given by
+`local-author-package.md`: package and workspace resolution, activation contribution, Manifest,
+Producer, Type and Validator agreement, Surface vocabulary and decoding, implementation behaviour,
+then source usage. Fixing source usage over a broken implementation hides the defect one layer down.
+
+## One round
+
+**There is one round.** What it returns is the whole set this program gets. Repair against that set
+and stop; do not look again.
+
+Two things follow, and they are the whole discipline:
+
+- **Every repair aims at something the round named.** Changing something it did not mention is
+ thrashing, and it does not earn one of the attempts below.
+- **A finding caused by an input that does not exist yet is not a repair target.** The mocks above
+ stand in for a base take and for media slots a Build has not filled, and a reader told where they
+ are should bypass them. One that reports a mock anyway is describing an absence, not a defect.
+
+Something nobody can close is not a failure to record as one. A typeface the generator cannot
+reproduce, a texture it will not hold, a grain that is not available — write it into the report and
+leave it.
+
+### Two ceilings, and they never share attempts
+
+The first is over the *package*: something the package cannot express is a package defect, and fixing
+it means changing the package's structure. The second is over the *values*: once the package can
+express everything, tune the Recipe, the font, the placement and the motion.
+
+**Write-and-remake the package: two attempts.** The first fixes what is obvious, the second fixes what
+the first revealed. If it is still something the package cannot express — a typeface mix it has no
+port for, a motion it cannot draw — the package is wrong rather than the values, and tuning values
+is thrashing. Widen the package instead, which starts a fresh write-and-remake for the widened shape.
+
+**Fill the parameters: two attempts.** The wrong weight, the wrong size, the wrong colour, the wrong
+position. Beyond the ceiling, guesses overshoot — correcting past the target rather than towards it.
+Time beats fidelity here by explicit choice.
+
+**Each ceiling is two attempts for the element, across all its stretches.** Looking at an element in
+five stretches does not buy ten attempts; it buys a fuller picture of what one attempt has to fix. One
+repair aimed at something several stretches agree on is one attempt however many reported it.
+
+## Measure what can be measured; iterate only on what cannot
+
+Two attempts per element is not enough to converge by guessing, and it is not meant to be. Something
+stated as a quantity — a stroke that is too thick, a shape that is too tall, type that is too large,
+a margin that is too wide — is not a guessing problem. Ask for the number, over whichever stretch
+renders the quantity most legibly. This is one reading of one number, not the coverage round, and
+reading it off one where the thing is small buys a worse number for the same price.
+
+Do that instead of spending an attempt. An attempt is for what has no number — a typeface's
+character, a texture, a rhythm — where the only route is change it and look again.
+
+Measure against the frame, not against the screen it is viewed on. A quantity read off a rendered
+still means what it means relative to that still's own width and height — a stroke that is "one
+percent of the frame height", a shape "a third of the frame width" — which is the same basis the
+Recipe's fractions use. Saying "a little too tall" and changing it on feel spends the attempt the
+measurement exists to save.
+
+Stopping is the end, and the end carries no final look. When the attempts are spent the work on that element stops as
+it is: the second repair is the last thing the reader saw, and there is no third round to name what
+remains. Do not spend one to find out — a look that changes nothing and exists only to report the gap
+is a step for a report nobody asked for. The element is what it is; move on to the next one.
+
+Hypit Studio is a browser preview for a person to look at. It is not a source of the picture this
+round needs: that picture is the local render in `preview.md`, which draws one element as the Source
+configures it, without a Provider.
+
+Repairing one element never re-runs the others. Do not rebuild the whole video to inspect one piece,
+and do not defer every look to a final delivery Build.
+
+## Say what this round did not settle
+
+Every element was looked at and every repair stopped. That is what "complete" means here, and it does
+not mean the video was watched: this round runs before the Build, so the pictures it read were renders
+with stand-ins under them. Report the difference rather than letting the word carry it.
+
+State plainly, in the completion report, that the following are unsettled:
+
+- **every generated picture and take** — the images and the shots a Provider has still to make;
+- **the timing of every Track** — this round reads each one against a stand-in SemanticTake, so how a
+ Caption, Media or Typography Track sits against the speech that is finally delivered is settled once
+ that speech exists;
+- **whether the picture is continuous** — the frames nobody authored that
+ `playbooks/craft/frame-coverage.md` is about. One inherited edge is settled here: the gate reads each
+ Recipe's `playback` and refuses an insert configured to stop when its material runs out. The rest —
+ a window that starts late, a blend whose frames are half-covered, a schedule inside a component that
+ stops between activations — appear in the delivery;
+- **whether the delivery says the Script's words** — a take generated from a prompt that lost its
+ dialogue passes every check made here.
+ `playbooks/craft/seedance-directing.md` says how to trace a take's prompt back to the Segment's
+ `dialogue` while the Source is being written, which is where this one is prevented.
+
+The gate is the mechanical half of this: it names the elements nobody looked at and the timed pictures
+configured to empty their windows, and refuses to pass while either remains. It cannot name what a
+Build has not produced yet, which is why this list is stated rather than computed.
+
+If a project-local package was built along the way, decide whether it should outlive this video and
+put that to the author: `package-promotion.md` says how to judge it and what promoting it actually
+costs.
diff --git a/.agents/skills/hypit/references/local-author-package.md b/.agents/skills/hypit/references/local-author-package.md
index 34408ca4..34da02e7 100644
--- a/.agents/skills/hypit/references/local-author-package.md
+++ b/.agents/skills/hypit/references/local-author-package.md
@@ -4,20 +4,27 @@ Use this workflow only after proving that no legal composition of installed pack
required behavior. A similar-looking tag is insufficient when its declared Types, timing or output
behavior differs. Never write an unknown tag before its package exists.
-## Read the observation before deciding the package's shape
+## Know what the element has to look like before deciding the package's shape
-The observation is the contract, and it is read before the first line of the package — not assumed,
-not remembered, not rediscovered halfway. In the reconstruction route the evidence for the element
-this package owns lives in the shot observations (`type:` and `visual:` for its text and picture,
-`persistent_systems` for its whole-reference life) and the word-level transcript. Read them.
+Whatever settles that is the contract, and it is read before the first line of the package — not
+assumed, not remembered, not rediscovered halfway. Which document settles it depends on where the
+package came from:
-Then write out, one line each, every appearance property the observation states — the typeface
+- **From a reference video**, the evidence for the element this package owns lives in the shot
+ observations (`type:` and `visual:` for its text and picture, `persistent_systems` for its
+ whole-reference life) and the word-level transcript. Read them.
+- **From a description**, nothing external settles it, so it is settled by decision: the answers the
+ author froze and the appearance values written down before the sources were. `original-authoring/route.md`
+ requires both. A value nobody wrote down is one this package will be asked for later and will not
+ have.
+
+Then write out, one line each, every appearance property that contract states — the typeface
character, the weights, the mix of faces, the colours, the stroke, the shadow, the motion, the
timing. A package whose declared vocabulary cannot express one of those lines is wrong before it is
written: widen the package until it carries every one of them. There is no acceptable shortfall —
-a property the observation states is either expressed by the package or the package is not done. A
-stated property silently dropped is how a reference whose title runs two typefaces ends up as a
-package that draws one font, and the loop cannot repair what the package cannot express.
+a stated property is either expressed by the package or the package is not done. A
+stated property silently dropped is how a title that runs two typefaces ends up as a
+package that draws one font, and the round cannot repair what the package cannot express.
## Write `package.json` and the activation first
@@ -241,7 +248,7 @@ hypit check path/to/build.svrun
A package that cannot be *wired* is not done. `hypit check` proves the Source is legal, and nothing
more; it will not tell you that the track a package produces cannot be traced to a Film at all. Run
the preview check and repair until it passes — a graph failure is not a difference to weigh, it is
-work that is not finished, and it is not bounded by the loop's attempt ceiling:
+work that is not finished, and it is not bounded by the round's attempt ceiling:
```bash
hypit-reference-video-tools preview_check path/to/build.svrun
diff --git a/.agents/skills/hypit/references/original-authoring/conformance-round.md b/.agents/skills/hypit/references/original-authoring/conformance-round.md
new file mode 100644
index 00000000..cbb1ffca
--- /dev/null
+++ b/.agents/skills/hypit/references/original-authoring/conformance-round.md
@@ -0,0 +1,98 @@
+# Reading each element against what it was asked to be
+
+**Read `../element-review.md` first.** It owns the round this file sits inside, and everything below
+is what having no reference changes.
+
+What it changes is the question. A reconstruction has a second picture and asks what differs. Here
+there is one picture, and the question is whether it is what was asked for. Nothing external can
+answer that, so the answer has to be written down before it is asked.
+
+## What the element is judged against
+
+Two things, both of which already exist by the time this round starts:
+
+- **The answers frozen at step 3** — the subject, the length, the aspect ratio, the language, who is
+ in it, what it says. `route.md` requires them frozen before any prompt is written precisely so that
+ something here can be measured against them.
+- **The appearance values written down at step 7** — every value that changes what the viewer sees.
+ A reconstruction measures those off the reference; here they are chosen, and a value nobody wrote
+ down cannot be wrong, which is the failure this round exists to catch.
+
+Write the element's own share of both into a file and pass it as `--intent-file`. It is required, and
+required for a reason: a conformance question with nothing to conform to asks whether the picture
+looks acceptable, which it always does to whoever drew it.
+
+## The round
+
+```
+hypit-reference-video-tools review_element --run projects/<name>/build.svrun \
+ --element <id> --segment <id>|--selection <id> \
+ --video <rendered>.mp4 --intent-file <what this element was asked to be>
+```
+
+`--batch <reviews.json>` sends a whole round as one call, an array of
+`{element, segment|selection, video_path, intent_file}` inheriting the Run. Render every stretch
+first, then send them together.
+
+The command does not render — `render_element` in `../preview.md` did that. It prepares the picture,
+writes an entry to `<project>/.hypit/reviews.jsonl`, and hands back the task: the instruction, the
+prompt and one picture. A clip becomes a grid of its own frames; a render that never changes becomes
+one still.
+
+There is **no observer question on this route**. The picture is a local render, nobody is billed to
+look at it, and the reader is a subagent. If you came here from the skill entry expecting to ask the author
+which observer reads the reference, that question belongs to the other route.
+
+## What the reader is asked
+
+`review_element` writes the whole prompt, so there is nothing to compose. It asks two things:
+
+- **Whether the picture matches the description** — which parts it satisfies, which it does not, what
+ the description asks for that is not there, and what is present that the description never
+ mentioned.
+- **What is visibly wrong** — anything cut off by the frame edge or reaching past it, anything
+ overlapping something meant to be read, any position or alignment against the frame's edges that
+ looks unintended, and anything too low in contrast to read. Over a clip it also asks what appears,
+ moves or leaves in a way the description does not account for.
+
+The placeholder clause is in the prompt already: the reader is told that flat-filled regions stand in
+for generations that have not run and to read only what is drawn over them. Do not add it by hand, and
+do not add anything that says what you built or what you expect to be found.
+
+`--question` is available and means what it means on the other route: which region to read, never what
+to conclude.
+
+## Recording the findings
+
+```
+hypit-reference-video-tools record_review --run projects/<name>/build.svrun \
+ --review-id <id> --text-file <the findings>
+```
+
+Until that lands, the picture has been drawn and handed over with nobody having said what it shows,
+and `authoring_check` lists it under `awaiting_answer` and credits the element nothing. Record every
+finding, including the ones that read as satisfied, in the words the reader used.
+
+## Measuring, on this route
+
+A quantity is read rather than guessed at, and here the instrument is a second subagent: give it the
+same picture and ask for one number against the frame's own width and height. It costs a subagent and
+no money, which is why it is always cheaper than spending one of the two attempts.
+
+## Closing the round
+
+```
+hypit-reference-video-tools authoring_check projects/<name>/build.svrun
+```
+
+It names each element nobody has looked at and the command that looks at it, and reports
+`"passed": false` until none are left. Like its counterpart it asks for participation rather than
+convergence: an element reviewed once and stopped at its ceiling passes, and an element nobody looked
+at does not.
+
+It also applies every check the Source alone decides — a stretch of the Script nothing draws a
+full-frame picture over, a Frame reaching past the Canvas, and a timed picture whose `playback` is
+left at its default and so draws its material once and then nothing for the rest of its window.
+`../playbooks/craft/generated-dependencies.md` says what to set.
+
+**Done when:** `"passed": true`. Then, and only then, the Build.
diff --git a/.agents/skills/hypit/references/original-authoring/route.md b/.agents/skills/hypit/references/original-authoring/route.md
index 25d20ea3..5b08c4da 100644
--- a/.agents/skills/hypit/references/original-authoring/route.md
+++ b/.agents/skills/hypit/references/original-authoring/route.md
@@ -11,7 +11,7 @@ between the two — what a picture is, what one generation owes another, which p
— is the same work and is written once, in the files these steps link. This page owns the order.
**This route spends.** One Build generates the pictures, the takes, the speech and the render, and
-step 10 is where the author says yes to it. There is no reference to check against, so the two things
+step 13 is where the author says yes to it. There is no reference to check against, so the two things
a reconstruction gets for free have to be decided deliberately: what the program is *for*, and what
every appearance value *is*. Neither has an evidence file to consult. Write them down rather than
discovering them at render time.
@@ -58,8 +58,8 @@ claims before any prompt is written. Everything downstream is measured against t
### 5. Choose the packages
**Read now:** `../vocabulary.md` — which installed packages own the systems this program contains,
-and whether any is genuinely missing. A system you never inspected is a system you are about to
-invent, and inventing one here is easy: there is no reference to contradict you.
+and whether any is genuinely missing. That file states why a system nobody inspected is one you are
+about to invent, and this route is where that is easiest: there is no reference to contradict you.
For a proven gap, read `../local-author-package.md` completely and build the package.
@@ -67,8 +67,10 @@ For a proven gap, read `../local-author-package.md` completely and build the pac
The Script comes first and the shots come out of it: a Segment is what one `whisperx:SemanticTake`
aligns one Take to, so how the Script is cut decides how many generations there are and where the
-seams fall. `../playbooks/craft/generated-dependencies.md` says why over-splitting manufactures seams
-nobody asked for.
+seams fall.
+
+**Read now:** `../script-time.md` — where a Segment ends, where a forced seam goes, and why each
+take's duration comes from `estimate:Speech` rather than from the duration the author asked for.
Give every planned shot one job — hook, context, evidence, mechanism, reaction, payoff, transition,
or CTA. Delete shots with no distinct job.
@@ -87,12 +89,37 @@ reused in the Run Source. `../runtime.md` — how to author a Profile.
tracing. `../preview.md` proves the Run traces before a Provider is reached. Neither is bounded by any
attempt ceiling: a graph that does not trace is work that is not done.
-### 9. See it before paying for it
+### 9. Render every stretch of every element
+
+**Read now:** `../element-review.md` — the round unit, what a render has to include, and how many
+stretches to draw. `../preview.md` holds `render_element` itself.
+
+Render the whole set before reading any of it. Studio is also free and is for the author to look at;
+it is not the picture this round reads.
+
+### 10. Read each element against what you asked for
+
+**Read now:** `conformance-round.md` — what the element is judged against, the
+`--intent-file` it is judged with, and what the reader is asked.
+
+One subagent per picture where the harness has them, dispatched together, and never opened by you.
+
+### 11. Repair against what the round returned
+
+Inside the two ceilings `../element-review.md` sets, in the dependency order it gives. A repair aimed
+at something the round did not name is thrashing and earns no attempt.
+
+### 12. Close the pre-Build work on the check
+
+```bash
+hypit-reference-video-tools authoring_check projects/<name>/build.svrun
+```
-`../preview.md` again: one element rendered to a still locally, or the whole Run opened in Studio for
-the author. Both are free.
+**Done when:** `"passed": true`. It refuses while any drawing element has never been looked at, while
+any stretch of the Script has nothing drawing a full frame over it, and while any timed picture is
+configured to empty its window.
-### 10. The Build
+### 13. The Build
Confirm credentials, the Runtime Profile, the installed packages, model limits, resolution and
Endpoint prerequisites. Run `doctor`, `check` and `plan`.
@@ -103,7 +130,7 @@ submitting it.** This is the one point on this route where their money is spent.
**Read now:** `../runtime.md` — submitting the Build, `status`, `inspect`, and `get` for the finished
Artifact.
-### 11. Ask whether the package outlives the video
+### 14. Ask whether the package outlives the video
If this job produced a project-local package, `../package-promotion.md` says how to judge whether it
should leave the project and what promoting it costs.
diff --git a/.agents/skills/hypit/references/playbooks/craft/frame-coverage.md b/.agents/skills/hypit/references/playbooks/craft/frame-coverage.md
index d7c7ede2..1e6e7bc4 100644
--- a/.agents/skills/hypit/references/playbooks/craft/frame-coverage.md
+++ b/.agents/skills/hypit/references/playbooks/craft/frame-coverage.md
@@ -58,7 +58,7 @@ looks finished while the same edges are still wrong. Nothing downstream catches
has no timeline, so it takes no `playback` and the pre-Build check does not apply to it, and Gate 4
measures black, which a still removes.
-The placeholders the comparison loop renders under an element never reach the Source. They exist in
+The placeholders the comparison round renders under an element never reach the Source. They exist in
that render and nowhere else — the Source never names them, and the checks that decide
coverage read the Source's Recipes and bindings rather than any picture. A mock cannot quiet a hole
it is structurally unable to reach.
diff --git a/.agents/skills/hypit/references/playbooks/craft/sfx.md b/.agents/skills/hypit/references/playbooks/craft/sfx.md
index 7eebaf68..b3d5b627 100644
--- a/.agents/skills/hypit/references/playbooks/craft/sfx.md
+++ b/.agents/skills/hypit/references/playbooks/craft/sfx.md
@@ -33,8 +33,8 @@ Declare the source, normalize it to audio-only `SynchronizedMedia`, and place it
- Use `during={story.selection.NAME}` for a range, a Script Moment plus `for` for a point event, or
explicit `start`/`end` timing in the SemanticTrack frame domain — the last only for a program
with no speech to anchor to, the same gate `overlays.md` and `screen-demo.md` put on absolute
- placement. Copying the reference's own seconds into an `start=`/`end=` is the same defect
- `continuity.md` names for covering content.
+ placement. Copying a video's own seconds into a `start=`/`end=` is the same defect
+ `../../script-time.md` names for covering content.
- Use `playback="once"` for a discrete effect, loop only for a genuinely repeating texture, and
bounded pitch-preserving stretch only when the occupancy must fill an authored range.
- Use explicit trim, gain, fade-in, and fade-out. The Audio Track preserves source level and does not
diff --git a/.agents/skills/hypit/references/preview.md b/.agents/skills/hypit/references/preview.md
index 7a91929f..7aa1f918 100644
--- a/.agents/skills/hypit/references/preview.md
+++ b/.agents/skills/hypit/references/preview.md
@@ -58,15 +58,39 @@ What this proves is that the graph is **wired**, not that every track **draws**.
refuses the media kind it is handed is not caught here, because nothing is handed to it until the
Build runs.
-## Render one element to a still, locally
+## Render one element, locally
-One element — a new component, one caption system, one inserted card — can be rendered to an image
-without a paid Provider. A new package's visual Surface needs a preview image anyway. The repository's
-own visual test `packages/hyperframes/test/browser-visual.test.ts` shows the path end to end: build
-the Track, compile the HyperFrames document, and render it through the local HyperFrames Runtime.
+One element — a new component, one caption system, one inserted card — is drawn without a paid
+Provider by `render_element`. This is the picture to reach for whenever one element has to be looked
+at rather than the whole program, and rendering the delivery to inspect a single piece is the waste it
+exists to prevent. `element-review.md` says how many of these to draw and what to do with them; this
+section owns the command.
-This is the image to reach for whenever one element has to be looked at rather than the whole
-program. Rendering the delivery to inspect a single piece is the waste it exists to prevent.
+```bash
+hypit-reference-video-tools render_element /path/to/project/build.svrun \
+ --element <id> --segment <id>|--selection <id> --out <path>.mp4
+```
+
+It reads the Canvas, the frame rate, the Recipe values, the Script text and the bindings out of the
+Source, mocks every layer a Build has not made, and drives the package's Producer. Nothing about it is
+written per package.
+
+`--element` takes the element's bare id — `captions`, the `id=` the Source wrote on the element. The
+command appends the output suffix itself when it looks for the track, so `--element captions.track`
+matches nothing: it refuses with `the Source places no element named captions.track` and lists the
+bare ids that are placed.
+
+`--segment` and `--selection` take a Script name, never a timestamp. Without either, the whole program
+is drawn. An `--out` ending `.mp4`, `.mov` or `.webm` writes the stretch as a clip; any other extension
+writes one still from the middle of it.
+
+A whole round is one call: `--batch <renders.json>`, an array of `{element, segment|selection, out}`
+inheriting the Run. They run together, paced by the machine.
+
+Each Segment's length comes from the Source's own `estimate:Speech`, which is the only clock a program
+has before its speech is synthesized. The result's `timing` says what sized each Segment, and the same
+object is written to `<out>.stand-in.json`. A reconstruction can borrow the reference's clock instead
+with `--reference-id`; `reconstruction/comparison-round.md` says when that matters.
## Open the whole Run for a person
diff --git a/.agents/skills/hypit/references/reconstruction/comparison-round.md b/.agents/skills/hypit/references/reconstruction/comparison-round.md
new file mode 100644
index 00000000..b24a9653
--- /dev/null
+++ b/.agents/skills/hypit/references/reconstruction/comparison-round.md
@@ -0,0 +1,165 @@
+# Comparing what was built against the reference
+
+**Read `../element-review.md` first.** It owns the round this file sits inside: one element at a time,
+render what the Source configures, mock what a Build has not made, one round, two attempt ceilings,
+measure rather than guess, and the rule that the reader is not the builder. Everything below is what a
+reference adds to that.
+
+What it adds is a second picture. The round asks what differs between the reference and the render
+rather than whether the render is what it was asked to be, and `compare_reconstruction` is how that
+question is put.
+
+## The reference side is finished
+
+The reference video does not change, and its observations are cached. Re-observing at a fixed
+temperature of `1.0` buys paraphrase drift and another bill, so never re-run a completed observation
+to "check" it. `--reobserve` exists for a shot whose media was rebuilt, not for doubt.
+
+Cached does not mean correct. The authority on the reference side is the picture, not the prose
+written about it. `evidence.md` says when an observation is worth doubting and how to settle it: a
+narrow `observe_reference --question` over the shot, put to the reference's own observer. That is
+cheaper than re-observing the whole shot, and on the `gemini` observer it is how the picture gets
+looked at, since opening it yourself is what the blindness rule below forbids.
+
+Everything else happens on the reconstruction side, which changes every time a package, Recipe or
+source edge is edited.
+
+## The render runs on the reference's clock
+
+`render_element` takes `--reference-id`, and it times the stand-in from that reference's own
+transcript, so each Segment runs for as long as the reference spends on its words. Pass it every time:
+the comparison cuts both sides to the same words and refuses a pair whose two halves are different
+lengths, and only this clock puts the render on the reference's. It is also what lets anything whose
+appearance is a function of elapsed time — a progressive reveal, a typewriter, staggered rows — be
+compared at the speed it will be seen at.
+
+A `--batch <renders.json>` round inherits the reference along with the Run.
+
+The window is still named in words on both sides. A word range and a shot are different divisions of
+the same video — one Segment routinely runs across five shots — and what a render and the reference
+have in common is the words, which is why the name travels between them rather than a number.
+
+One geometry has to agree before any of it means anything. The reference's own pixel dimensions are
+stored under `video` in its `state.json`, and they size nothing here — but their **aspect** has to
+match the Canvas's. When it does not, every comparison puts two differently-shaped pictures side by
+side and the observer reports proportion differences that belong to the Canvas rather than to the
+element. Fix the Canvas before comparing.
+
+## Compare the whole stretch, against every stretch the element is drawn over
+
+Compare clips, not chosen frames:
+
+```
+hypit-reference-video-tools compare_reconstruction --reference-id <id> \
+ --run projects/<name>/build.svrun --segment <id>|--selection <id> \
+ --video <rendered>.mp4 --element <id>
+```
+
+The word range is the one the render was drawn over, and the reference is cut from its own analysis
+video at the seconds it speaks those words, so the two sides hold the same words for the same length
+of time. Each end moves onto a shot boundary when one lies inside its own end word, and the rendered
+clip is trimmed by the same seconds, so the pair opens and closes where the picture changes while
+still covering exactly the words asked for. An end with no boundary inside its word leaves the pair
+part-way through a shot, and the prompt then says how many seconds of it to read as an incomplete
+shot and to report no differences from. `--shot-id <id>` compares one cut of the picture as the whole
+shot it already is, and refuses a render whose length is not that shot's.
+
+An element that animates in, leaves, and is replaced by another within one static board does not
+produce a cut, so a stretch can hold several states and no single frame represents it. Choosing one is
+the failure this replaces: a caption system compared against the stretch with the shortest line looks
+correct, because one line has nothing to collide with.
+
+Compare it against **every stretch the element is drawn over**, not the clearest one. There is one
+round and it comes before any repair, so a stretch left out of it is a stretch nothing will ever say
+anything about. A caption Style is the one exception, and `../element-review.md` states it: one
+stretch per distinct Style, at its first occurrence.
+
+Where the reference shows a caption behaving differently somewhere, that is a stretch worth its own
+comparison; where it shows the same design drawn over different words, it is not.
+
+On the `gemini` observer the whole round is one call. Write the comparisons to a JSON file — the same
+objects the flags produce, minus `reference_id` — and hand the file over:
+
+```json
+[
+ {"run": "projects/<name>/build.svrun", "segment": "pro",
+ "video_path": "projects/<name>/renders/board-pro.mp4", "element": "board"},
+ {"run": "projects/<name>/build.svrun", "selection": "wait",
+ "video_path": "projects/<name>/renders/marks-wait.mp4", "element": "marks"}
+]
+```
+
+```
+hypit-reference-video-tools compare_reconstruction --reference-id <id> --batch comparisons.json
+```
+
+It paces the requests itself, keeps each comparison's derived cuts apart, and returns them under
+`comparisons`. One that fails arrives under `failures` beside the input that produced it and takes
+only itself down. Do not write a shell script to fan these out: the pacing, the per-comparison result
+and the isolation are what the batch is for, and a hand-rolled loop has none of them.
+
+`--image` is available for one case only: the reference's own `visual:` observation states in words
+that the element is completely still. The judgement comes from the reference's observation, never
+from looking at your own render and concluding it does not move — deciding that from the
+reconstruction is how the wrong frame got chosen in the first place. Where the observation does not
+say still, compare the clip.
+
+Pass `--element <id>` every time so the gate credits the comparison to that element.
+
+## One observer reads the reference, and it is the one the reference was prepared with
+
+`compare_reconstruction` is how the reference frame is looked at, and `observers.md` says who looks.
+The reference has one observer for its whole life, and the comparison goes through the same one that
+wrote its observations.
+
+**On the `gemini` observer, that observer is not you.** The command sends the reference clip and the
+rendered clip as an unlabelled pair and returns the differences in words. Do not open the reference
+yourself and look at it, whatever visual ability the model running this round has, and do not look at
+the rendered reconstruction either. A second observer is a second opinion paid for with the very bias
+it claims to correct: it sees the reconstruction, knows what was built, and confirms what it expects.
+This is why a font that is wrong is caught — the comparison names it, and the package is repaired,
+rather than a font being chosen because it resembles what you remember.
+
+**On the `agent` observer the command returns two pictures and the question instead of an answer.**
+That observer reads pictures rather than video, so a clip comparison arrives as two frame tiles, both
+built against the compared stretch's own duration, so the two grids sample at the same rate and the
+same layout. What is compared is the same stretch either way, and `../element-review.md` says who
+reads them: one subagent per comparison, dispatched together, and never you.
+
+## Comparison is blind
+
+- Never tell the observer which picture is the reconstruction, what was built, which component drew
+ it, or what you expect to be wrong. An observer told what to confirm will confirm it.
+- `--question` carries what to look at, never what to conclude. Three things qualify: which region to
+ read, which regions to skip because they hold a placeholder standing in for a declared-but-unbuilt
+ generation, and one visible quantity to measure. None of them says which picture is the
+ reconstruction, what was built, or what you expect to be wrong — and a question that hints at the
+ answer, rather than naming what to look at, has stopped being scope.
+
+The pair is always sent in one order: **one is the reference, two is the render.** The observer is not
+told that and must not be; you need it, because a difference reported "in one" is a difference in the
+reference and one "in two" is something to repair.
+
+## Measuring, on this route
+
+`../element-review.md` says to ask for a number rather than spend an attempt. Here that question is
+`compare_reconstruction --question "how tall is the oval relative to the frame?"`, which returns a
+measurement in one step, from whichever observer the reference holds.
+
+## The reference has nothing further to say after the round
+
+It already showed every stretch, and a second look re-reads the same frames to check your own work.
+That spends the expensive half of the route — the renders and the observer — on verifying a repair
+rather than on learning anything about the reference.
+
+So **a repair is not verified here**, and the honest place to say so is the report. Passing
+`pnpm check` and `hypit check` is the precondition for the round, not a result of it. The one thing
+that is not bounded by the round is settling disagreeing evidence: a narrow
+`observe_reference --question` does that at any point, which is what `evidence.md` is for.
+
+`../element-review.md` lists what a pre-Build round leaves unsettled, and that list is what the
+completion report carries.
+
+If the author wants the result to differ from the reference — their presenter, their product, their
+brand — read the sources you wrote and change them to what they asked for. `route.md` says why that
+happens here rather than earlier.
diff --git a/.agents/skills/hypit/references/reconstruction/continuity.md b/.agents/skills/hypit/references/reconstruction/continuity.md
index e0bd2b8c..d8757594 100644
--- a/.agents/skills/hypit/references/reconstruction/continuity.md
+++ b/.agents/skills/hypit/references/reconstruction/continuity.md
@@ -36,35 +36,19 @@ the Source as `start="3.25s" end="7.42s"` is the shortest path from the evidence
produces a reconstruction that is wrong the moment it is built.
Those seconds describe the reference's own clock, and nothing in the reconstruction runs on that
-clock. Every take is generated, comes back at whatever length the model returned, and the
-SemanticTrack is built from the words WhisperX finds inside it. An Item bound to 3.25 seconds points
-at whichever word happens to land there, which is not the word the number was copied from. One take
-returning half a second long moves every window after it.
-
-Bind covering content to a Script Selection over the words it covers — mark the range in the Script,
-pass `semantic={speech.semantic}` to the Track, and use `during={story.selection.NAME}` — and let the
-projection resolve the frames. The reference's seconds then decide *which words* a Selection spans,
-which is what they can honestly tell you, rather than which frame an Item starts on.
-
-Explicit `start`/`end` is for a program with no speech to anchor to. `../playbooks/craft/b-roll.md`
-states the same rule from the authoring side, and reads it as a deliberate choice rather than a
-transcription.
+clock. `../script-time.md` says what to bind to instead, and why an Item bound to 3.25 seconds points
+at whichever word happens to land there. The reference's seconds then decide *which words* a Selection
+spans, which is what they can honestly tell you, rather than which frame an Item starts on.
## A system that spans shots is authored once
-- A visual system that persists across cuts — captions, a running list that keeps its state, a
- progress indicator, a persistent badge or logo, a recurring lower third — is one system: one
- Program, one Track and one shared Style over its full observed lifetime, even when the visible
- words, items or values change.
-- Do not recreate the system per shot, and do not create a second Style because a new shot begins. A
- new shot is never itself evidence of a change in appearance.
-- Author an observed local difference as a scoped variation inside the one system, on exactly the
- words, items or interval where it was observed.
-- Whether the system is one Program with per-item timing or separate instances is decided by the
- declared vocabulary of the chosen package, never by shot count.
-- The `persistent_systems` observation from `prepare_reference` reports these systems for the whole
- reference, including whether each one's appearance ever changes and where. Use it instead of
- inferring lifetimes from per-shot prose.
+`../script-time.md` states the rule: one Program, one Track, one shared Style over the system's full
+lifetime, and a scoped variation rather than a second Style. A new shot is never itself evidence of a
+change in appearance.
+
+The reference supplies the lifetimes. The `persistent_systems` observation from `prepare_reference`
+reports these systems for the whole reference, including whether each one's appearance ever changes
+and where. Use it instead of inferring lifetimes from per-shot prose.
## Base pictures and designed fields
diff --git a/.agents/skills/hypit/references/reconstruction/evidence.md b/.agents/skills/hypit/references/reconstruction/evidence.md
index 6e7263cc..d174bc13 100644
--- a/.agents/skills/hypit/references/reconstruction/evidence.md
+++ b/.agents/skills/hypit/references/reconstruction/evidence.md
@@ -15,7 +15,7 @@ hypit-reference-video-tools compare_reconstruction --reference-id <reference-id>
`record_observation` is how the `agent` observer returns an answer; on the `gemini` observer the tool
writes its own and the command is unused. A long answer arrives whole with `--text-file <path>`;
`--text <text>` suits a short one. `make-placeholder` writes the mocks a comparison render needs;
-`reconstruction-loop.md` says when. `list_svml_packages` and `inspect_svml_vocabulary` read installed
+`comparison-round.md` says when. `list_svml_packages` and `inspect_svml_vocabulary` read installed
vocabulary and have nothing to do with a reference video — `../vocabulary.md` documents them.
A reference is found from the Distribution rather than from where you are standing, so these commands
@@ -43,7 +43,7 @@ and on the `agent` observer it is the only exact record of the sound. Read it wh
depends on when a word is said — placing an on-screen text reveal against the line that triggers it,
timing a caption, checking that a voice observation matches what was spoken, or judging a Segment's
natural boundary. It does not set a take's duration: the take is generated and its length comes from
-`estimate:Speech`, as `final-sources.md` requires. Do not run WhisperX by hand and do not ask a model
+`estimate:Speech`, as `../script-time.md` requires. Do not run WhisperX by hand and do not ask a model
to transcribe.
`transcript` reports `status`, `transcript_ref` and `word_count`. Read the words from
@@ -117,21 +117,23 @@ The frames are on disk at `.hypit/reference-video-tools/<reference-id>/shots/NNN
and the shot clips beside them. When evidence disagrees — one shot against the next, a shot against a
whole-reference pass, or an observation against what the video plainly is — settle it with a narrow
question over that shot, which puts the question to the reference's own observer. On the `gemini`
-observer that means you do not open the frame yourself; `reconstruction-loop.md` says which rule
+observer that means you do not open the frame yourself; `comparison-round.md` says which rule
binds on which path.
Be most suspicious of anything an observation asserts about change over time — something appearing,
vanishing, being removed, being drawn in a single frame. A describer working from one pass infers
those rather than seeing them, and infers them wrongly. A narrow question over the stretch is how
such a claim is checked. A `compare_reconstruction` against a quick rendered probe works too, and is
-a probe rather than the element comparison `reconstruction-loop.md` runs — that one is rendered from
+a probe rather than the element comparison `comparison-round.md` runs — that one is rendered from
the Source's own values and is credited with `--element`.
## Narrow questions
-`--question` is a separate path. It requires one to three `--shot-id` values, answers only that
-question from those shots' clips and frames in a single request, and neither reads nor writes the
-observation cache:
+`--question` is a separate path. It requires one to three `--shot-id` values and answers only that
+question from those shots' clips and frames. Its answer is cached like any other, under a key naming
+the shots it was asked over and the question itself, so asking the same question again returns what
+was already answered and reports `reused`. `--reobserve` is what asks again. A different question
+over the same shots gets its own key:
```bash
hypit-reference-video-tools observe_reference --reference-id <id> --shot-id shot-007 \
diff --git a/.agents/skills/hypit/references/reconstruction/final-sources.md b/.agents/skills/hypit/references/reconstruction/final-sources.md
index 3712b948..78fb151c 100644
--- a/.agents/skills/hypit/references/reconstruction/final-sources.md
+++ b/.agents/skills/hypit/references/reconstruction/final-sources.md
@@ -20,40 +20,25 @@ to author one.
Do not author one source fragment per shot. Do not let check success substitute for unresolved
semantic evidence; return to a narrow `observe_reference` question when necessary.
-## A Segment is a stretch the reference actually plays as one
+## Where the Segments fall, and how long each take runs
-Cut the Script into Segments the way the reference is *spoken*, not the way its shots are numbered:
-consecutive Segments carrying one unbroken voiceover are one Segment with Selections inside it.
-`../playbooks/craft/generated-dependencies.md` says why — a Segment is a generation boundary, and
-splitting a stretch the reference delivers unbroken invents a seam it does not have.
+`../script-time.md` decides both, and it decides them the same way for any program: a Segment is a
+stretch that is spoken as one, the seam goes at a sentence end, and each take's duration comes from
+`estimate:Speech` rather than from any clock.
-One thing does force a seam. The take that speaks a Segment generates that speech, so a Segment can
-be no longer than one generation. Where an unbroken passage runs past what the model will produce in
-one take, it becomes two Segments — and then the seam is yours to place rather than the ceiling's.
-Put it where the speaker would draw breath: at a sentence end, never mid-clause.
+The reference adds one thing to that, and it is a warning rather than a rule. The generated speech
+plays at its own pace, not the reference's: its measured word timings describe how the original
+speaker delivered the line, the reconstruction re-speaks it, and the generated take will not match
+that recording second for second. Reading the reference's span onto the take fixes a length that has
+nothing to do with how the generator speaks.
-## A take's duration is estimated, not read off the reference
-
-Every take is generated, and the generated speech plays at its own pace, not the reference's. So
-each take's duration comes from `estimate:Speech` — the prediction of how long the generated line
-will be. Write that estimate on the take.
-
-The reference's measured word timings describe how the original speaker delivered the line; the
-reconstruction re-speaks it, and the generated take will not match that recording second for
-second. Reading the reference's span onto the take fixes a length that has nothing to do with how
-the generator speaks.
-
-Nothing depends on the estimate being exact. Script Selections bind every placed element to the
-words, and the SemanticTrack places the words where the generated audio actually has them, so a
-take that comes back a little long or short moves the words, not the bindings. This is also what
-lets a reconstruction survive the author changing the lines: the estimate recomputes from the new
-words, where a literal read off the old reference would not. `estimate:Speech` takes
-`story.segment.NAME.speech`, so the duration follows the script it is asked to predict.
+The estimate is also what lets a reconstruction survive the author changing the lines at the end of the route,
+where a literal read off the old reference would not.
Then check and wire, in that order. `../authoring.md` holds the check set — all four commands, not
only the Author Source — and `../preview.md` holds the graph check that comes after it. A Source that
passes every check can still declare a Run that does not trace, and neither gate is bounded by the
-loop's two-attempt ceiling: a graph that does not trace is not a difference to weigh, it is work that
+round's two-attempt ceiling: a graph that does not trace is not a difference to weigh, it is work that
is not done.
One thing to expect here rather than to debug: a route that declares its generation instead of
@@ -65,7 +50,7 @@ Fix package resolution and package implementation before repairing source use. C
three files are accepted. Do not create `check_svml_project` or another wrapper.
Accepted checks end the structural work, not the reconstruction. Every element you authored still has
-to be rendered and compared against the reference under `reconstruction-loop.md`, and that work ends
+to be rendered and compared against the reference under `comparison-round.md`, and that work ends
on `reconstruction_check` (`route.md` holds the command), which refuses to pass while any drawing
element has never been compared. It needs a prepared reference; when several are prepared it takes
`--reference-id <id>`.
diff --git a/.agents/skills/hypit/references/reconstruction/observers.md b/.agents/skills/hypit/references/reconstruction/observers.md
index 5bbce490..787c2b0a 100644
--- a/.agents/skills/hypit/references/reconstruction/observers.md
+++ b/.agents/skills/hypit/references/reconstruction/observers.md
@@ -112,7 +112,7 @@ and do not put the gap to the author.
- **The transcript says when.** WhisperX measures every word locally on both paths, so the words and
their timings are exact whichever observer reads the pictures. That settles whether anyone is
speaking at a given moment, and where a word sits. It does not set a take's duration: the take is
- generated and its length comes from `estimate:Speech`, as `final-sources.md` requires.
+ generated and its length comes from `estimate:Speech`, as `../script-time.md` requires.
- **The pictures say who.** Attribute speech to the person the frames show speaking during the words
the transcript places there. A task that needs sound says so in its own prompt and asks for exactly
this reading.
@@ -124,15 +124,21 @@ and do not put the gap to the author.
`voices` and the sound half of each `boundary` are the observations this shapes. They are attributions
read off pictures and word timings, and that is what a later reader should take them for.
-## Answer each task in its own subagent when you can
+## Each task is answered in its own subagent
-Every task is self-contained, and no task refers to another task's answer. So if the harness you are
-running in can spawn subagents — Claude Code and Codex can, and some cannot — give each task in a pass
-to its own, and run the pass together.
+Every task is self-contained, and no task refers to another task's answer. **Where the harness can
+spawn subagents — Claude Code and Codex can, and some cannot — one subagent per task is required, and
+a pass runs them together.** `../element-review.md` states the rule and why it is not a preference;
+this is what it means for a reference observation.
-Hand the subagent the `instruction`, the `prompt` verbatim and the `image_refs`, and nothing else.
-Not what you built, not which component drew anything, not what you expect it to find, and not another
-observation's answer. Take the returned text and record it yourself, so one writer owns the cache.
+Hand the subagent the `instruction`, the `prompt` verbatim, the `image_refs`, and `transcript_ref` and
+`transcript_words` when the task carries them — and nothing else. Not what you built, not which
+component drew anything, not what you expect it to find, and not another observation's answer. Take
+the returned text and record it yourself, so one writer owns the cache.
+
+**Do not open the pictures yourself.** That is the whole point: the observer that uploads is a
+separate request and cannot be you, and one task per subagent is what makes this path equal to it
+rather than merely faster.
Two things follow from one task per subagent, and both of them are properties the `gemini` observer
has for free:
@@ -144,11 +150,12 @@ has for free:
does not know which is the reference, what was built or what you hoped to see. That is the same
unlabelled pair the other observer gets.
-Answer the tasks in order yourself when the harness has no subagents. It is slower, and it is the
-fallback rather than the shape to aim for.
+Answer the tasks in order yourself only where the harness has no subagents. It is slower, it is the
+fallback rather than the shape to aim for, and the discipline below stands in for the blindness it
+cannot have.
-The comparison loop arrives here in batches. One element is compared against every stretch it is drawn
-over before any repair, and `reconstruction-loop.md` has the renders all made before the first
+The comparison round arrives here in batches. One element is compared against every stretch it is drawn
+over before any repair, and `comparison-round.md` has the renders all made before the first
comparison is sent, so they arrive together. Each is self-contained in the same way an observation
task is: no comparison's question depends on another's answer.
@@ -161,9 +168,8 @@ A clip comparison reaches this observer as two frame tiles — the reference's o
from the render against the same duration, both drawn at the same cell width. Read them as a pair of
grids sampling the same stretch at the same rate.
-The pair is always sent in one order: **one is the reference, two is the render.** The observer is not
-told that and must not be; you need it, because a difference reported "in one" is a difference in the
-reference and one "in two" is something to repair. Read the answer with that in hand.
+`comparison-round.md` states the order the pair is sent in and why the observer is not told it. Read
+the answer with that in hand.
### Record the differences against the comparison that asked for them
@@ -181,17 +187,7 @@ as equivalent, in the words the observer used.
## Comparing without subagents
-Answering the comparison yourself makes the report yours, and you know what you built, so the
-discipline that keeps it useful has to be explicit:
-
-- **Write the differences down before naming a cause.** List what is visibly different, in the words
- you would use if you had never seen the source. Deciding what went wrong first, then looking, finds
- what you expected.
-- **A difference you did not write down is not an attempt.** `reconstruction-loop.md`'s two-attempt
- ceilings apply unchanged, and they count repairs aimed at differences the comparison named.
-- **Measure rather than iterate.** A stroke that is too thick, a shape that is too tall, a margin that
- is too wide — read the number off the frame against the frame's own width and height, and change the
- value once. `reconstruction-loop.md` says why an attempt is for differences that have no number.
-
-The same three hold when a subagent compares, and they cost nothing there; what a subagent adds is
+Answering the comparison yourself makes the report yours, and you know what you built.
+`../element-review.md` states the three rules that stand in for the blindness a harness without
+subagents cannot give you, and they apply here unchanged. What a subagent adds, and they cannot, is
that the comparer is not the builder.
diff --git a/.agents/skills/hypit/references/reconstruction/reconstruction-loop.md b/.agents/skills/hypit/references/reconstruction/reconstruction-loop.md
deleted file mode 100644
index 8cccb384..00000000
--- a/.agents/skills/hypit/references/reconstruction/reconstruction-loop.md
+++ /dev/null
@@ -1,386 +0,0 @@
-# Closing the loop on what was built
-
-Structural checks prove that a source is legal. They prove nothing about whether it looks like the
-reference. A newly written package can resolve, activate, decode and pass every check while drawing
-something the reference never contained. Close that gap deliberately.
-
-This loop is about how an element *looks* against the reference, and it is bounded. Whether an
-element is *wired at all* is a different gate with a different rule: `preview_check` (in
-`../preview.md`) must pass before this loop is even reached, and its failures are repaired
-without any attempt ceiling. A graph that does not trace is not a difference to weigh; it is work
-that is not done.
-
-Note what that gate covers: `preview_check` proves the graph is wired, not that every track draws.
-Nothing is handed to a Producer until the Build runs, so a Producer that refuses the media it
-receives surfaces there rather than here.
-
-The difference between the two gates is what each reports. `preview_check` names the graph failure —
-the target that does not trace, the chain that is missing — so its repairs are not guessing. This
-loop names the appearance difference: `compare_reconstruction` sends the rendered element and the
-matching stretch of the reference to an observer and returns what differs in words, and a repair aims
-at a difference the comparison named. Neither gate expects the agent to guess; each one tells you what
-is wrong, and you repair that.
-
-## The reference side is finished
-
-The reference video does not change, and its observations are cached. Re-observing at a fixed
-temperature of `1.0` buys paraphrase drift and another bill, so never re-run a completed observation
-to "check" it. `--reobserve` exists for a shot whose media was rebuilt, not for doubt.
-
-Cached does not mean correct. The authority on the reference side is the picture, not the prose
-written about it. `evidence.md` says when an observation is worth doubting and how to settle it: a
-narrow `observe_reference --question` over the shot, put to the reference's own observer. That is
-cheaper than re-observing the whole shot, and on the `gemini` observer it is how the picture gets
-looked at, since opening it yourself is what the blindness rule below forbids.
-
-Everything in this file happens on the reconstruction side, which changes every time a package,
-Recipe or source edge is edited.
-
-## The loop unit is one element, across every stretch it is drawn over
-
-Loop over one reconstructed element at a time — the new component, one caption system, one inserted
-card.
-
-### Render what the Source configures, not what the catalogue shows
-
-The thing compared is the element **as this video places it**: the Recipe values the Source actually
-passes, the Script text the Source actually feeds it, and the windows the Source actually binds. A
-package's catalogue preview is a different picture drawn from different values — the package's own
-sample copy and sample Recipe, chosen to show a reader the Surface's range — and a Source can fill
-every one of those parameters with values that collide while the preview stays perfect. Comparing the
-preview answers a question nobody asked. `../preview.md` keeps the two apart and says which command
-draws which.
-
-One command produces it, and it is not written per package:
-
-```
-hypit-reference-video-tools render_element projects/<name>/build.svrun \
- --element <id> --segment <id>|--selection <id> --reference-id <id> --out <path>.mp4
-```
-
-A whole round is one call: `--batch <renders.json>`, an array of `{element, segment|selection, out}`
-inheriting the Run and the reference. They run together.
-
-`--element` takes the element's bare id — `captions`, the `id=` the Source wrote on the element. The
-command appends the output suffix itself when it looks for the track, so `--element captions.track`
-matches nothing: it refuses with `the Source places no element named captions.track` and lists the
-bare ids that are placed.
-
-It reads the Canvas, the Recipe values and the Script text out of the Source, mocks every layer a
-Build has not made, and drives the package's Producer. Nothing is transcribed by hand, so nothing is
-transcribed one line at a time — which is what made a caption system look correct while its lines
-collided.
-
-**It draws the whole stretch, not the element alone.** `--element` names which element the comparison
-is about; the picture is everything the Source places over those words, so two elements over one
-Segment produce the same picture. Scope the comparison with `--question` — that is what tells the
-observer which part of it to read.
-
-`--reference-id` names the reference, and it times the stand-in from that reference's own transcript,
-so each Segment runs for as long as the reference spends on its words. Pass it every time: the
-comparison cuts both sides to the same words and refuses a pair whose two halves are different
-lengths, and only this clock puts the render on the reference's. It is also what lets anything whose
-appearance is a function of elapsed time — a progressive reveal, a typewriter, staggered rows — be
-compared at the speed it will be seen at.
-
-The window is named in words. `--segment` and `--selection` take a Script name, never a timestamp:
-name the Segment or the Selection the element is drawn over, and give the same name to the
-comparison, so both sides cover the same words. A word range and a shot are different divisions of
-the same video — one Segment routinely runs across five shots — and what a render and the reference
-have in common is the words, which is why the name travels between them rather than a number.
-
-### Mock the layers a Build has not made
-
-The element rarely draws the whole frame. Below it is a base take that does not exist yet, and inside
-it may be media slots the Source declares as generations. Render them as mocks rather than leaving
-them out: a missing base is not a neutral background, it is black, and text that is legible on black
-can be illegible on the picture that will replace it.
-
-`render_element` does this itself. It finds every generation the Source declares — the takes, the
-stills, the slot contents — calls `make-placeholder` for each at the Canvas's own size, and declares
-them in a derived Run under the project's `.hypit/`. Never `hypit image`, which pays for a generation
-the video will not reuse, and never a placeholder drawn by a script written for the occasion.
-
-The sizes come from the Source's `space:Canvas`, not from the reference video, because the mock is
-composed inside the render and the render's geometry is the Canvas. The reference's own pixel
-dimensions are a different and usually smaller number, stored under `video` in its `state.json`. They
-do not size anything here, but their **aspect** has to match the Canvas's: when it does not, every
-comparison puts two differently-shaped pictures side by side and the observer reports proportion
-differences that belong to the Canvas rather than to the element. Fix the Canvas before comparing.
-
-Then tell the observer, through `--question`, that those regions are placeholders standing in for
-declared-but-unbuilt generations, and to compare only what the element itself draws. Said plainly it
-costs one clause and saves the mock coming back as a difference in the one round there is.
-
-A mock lives only in this render. It is never written into the Source, and no gate reads it: the
-`playback` check in `reconstruction_check` reads the Source's Recipes, so a mock cannot be mistaken
-for coverage.
-
-### The derived Run holds one Segment, not the whole Source
-
-The mocks are substituted into a Source that has already been cut to the window. `render_element`
-keeps the Segment the window names, drops the rest of the Script, and then drops every element that
-named a Segment, Selection or Moment that went with it — and every element naming one of those, to a
-fixed point, plus any container the cut left with no children. So an element bound to a Selection in
-another Segment is not in this render, and its absence says nothing about the Source.
-
-One name survives the cut rather than taking its element with it: a Moment in `until=` that is marked
-*after* the kept Segment. An element given the span it occupies and a Moment to close it is on screen
-for the whole of a stretch that ends before that word, so the cut removes the close and keeps the
-element. That is what makes an element bounded by a late Moment renderable over the earlier Segments
-it is drawn over, which is every stretch this loop asks for it in.
-
-The cut Source is on disk at `<project>/.hypit/compare/sliced.svml`, byte-for-byte from the original
-except for what was removed, and the derived Run sits beside it. Open it whenever something you
-expected to see is not in the picture: an element that is not in the fragment was cut by the window,
-and one that is in the fragment and still not on screen is the package failing to draw it. Those two
-repair in opposite directions, and the fragment is what tells them apart.
-`packages/reference-video-tools/src/slice.ts` records the same thing as `SliceResult.dropped` — each
-dropped id and the name it could no longer reach — and explains what decides survival.
-
-### Compare the whole stretch, against every stretch the element is drawn over
-
-Compare clips, not chosen frames:
-
-```
-hypit-reference-video-tools compare_reconstruction --reference-id <id> \
- --run projects/<name>/build.svrun --segment <id>|--selection <id> \
- --video <rendered>.mp4 --element <id>
-```
-
-The word range is the one the render was drawn over, and the reference is cut from its own analysis
-video at the seconds it speaks those words, so the two sides hold the same words for the same length
-of time. Each end moves onto a shot boundary when one lies inside its own end word, and the rendered
-clip is trimmed by the same seconds, so the pair opens and closes where the picture changes while
-still covering exactly the words asked for. An end with no boundary inside its word leaves the pair
-part-way through a shot, and the prompt then says how many seconds of it to read as an incomplete
-shot and to report no differences from. `--shot-id <id>` compares one cut of the picture as the whole
-shot it already is.
-
-An element that animates in, leaves, and is replaced by another within one static board does not
-produce a cut, so a stretch can hold several states and no single frame represents it. Choosing one is
-the failure this replaces: a caption system compared against the stretch with the shortest line looks
-correct, because one line has nothing to collide with.
-
-Compare it against **every stretch the element is drawn over**, not the clearest one. There is one
-round and it comes before any repair, so a stretch left out of it is a stretch nothing will ever say
-anything about.
-
-### A caption Style is compared once, where it first appears
-
-Captions are the one element where the stretches are not different questions. A caption system is one
-Style applied to whatever words fall under it, so two stretches drawn in the same Style differ only in
-which words they hold — the typeface, size, weight, box, padding and placement are the same
-declaration in both, and reading the second one returns the answer the first already gave.
-
-So compare **one stretch per distinct Style**, at the first occurrence of that Style. A program with
-one default Style and a `caption:Use` override for one Selection is two comparisons, wherever those
-two first appear, not one per Segment. This is the same reading `continuity.md` applies to every other
-system that spans cuts: the system is authored once, so it is read once.
-
-What is not covered by that is anything a Style does not decide. A Cue that overflows the frame is a
-Segment nobody broke with `||` rather than a Style at the wrong width — `../playbooks/craft/captions.md`
-says so — and it belongs to the stretch whose words are long, not to the Style. Where the reference
-shows a caption behaving differently somewhere, that is a stretch worth its own comparison; where it
-shows the same design drawn over different words, it is not.
-
-**Render every stretch first, then send them all at once.** No comparison's question depends on
-another's answer, so nothing is gained by waiting: rendering one and comparing it before rendering the
-next makes the round as long as the sum of its parts. Render the whole set, then issue the
-comparisons together — concurrent requests on the `gemini` observer, one subagent each on the `agent`
-observer, and one after another only where the harness has no subagents.
-
-On the `gemini` observer the whole round is one call. Write the comparisons to a JSON file — the same
-objects the flags produce, minus `reference_id` — and hand the file over:
-
-```json
-[
- {"run": "projects/<name>/build.svrun", "segment": "pro",
- "video_path": "projects/<name>/renders/board-pro.mp4", "element": "board"},
- {"run": "projects/<name>/build.svrun", "selection": "wait",
- "video_path": "projects/<name>/renders/marks-wait.mp4", "element": "marks"}
-]
-```
-
-```
-hypit-reference-video-tools compare_reconstruction --reference-id <id> --batch comparisons.json
-```
-
-It paces the requests itself, keeps each comparison's derived cuts apart, and returns them under
-`comparisons`. One that fails arrives under `failures` beside the input that produced it and takes
-only itself down. Do not write a shell script to fan these out: the pacing, the per-comparison result
-and the isolation are what the batch is for, and a hand-rolled loop has none of them.
-
-This is the round. Everything the reference has to say about this reconstruction comes back from it,
-and the ceilings below count repairs made against what it returned.
-
-`--image` is available for one case only: the reference's own `visual:` observation states in words
-that the element is completely still. The judgement comes from the reference's observation, never
-from looking at your own render and concluding it does not move — deciding that from the
-reconstruction is how the wrong frame got chosen in the first place. Where the observation does not
-say still, compare the clip.
-
-Pass `--element <id>` every time so the gate credits the comparison to that element.
-
-### One observer reads the reference, and it is the one the reference was prepared with
-
-`compare_reconstruction` is how the reference frame is looked at, and `observers.md` says who looks.
-The reference has one observer for its whole life, and the comparison goes through the same one that
-wrote its observations.
-
-**On the `gemini` observer, that observer is not you.** The command sends the reference clip and the
-rendered clip as an unlabelled pair and returns the differences in words. Do not open the reference
-yourself and look at it, whatever visual ability the model running this loop has, and do not look at
-the rendered reconstruction either. A second observer is a second opinion paid for with the very bias
-it claims to correct: it sees the reconstruction, knows what was built, and confirms what it expects.
-This is why a font that is wrong is caught — the comparison names it, and the package is repaired,
-rather than a font being chosen because it resembles what you remember.
-
-**On the `agent` observer the command returns two pictures and the question instead of an answer, and
-who looks at them is up to the harness.** That observer reads pictures rather than video, so a clip
-comparison arrives as two frame tiles, both built against the compared stretch's own duration, so the
-two grids sample at the same rate and the same layout.
-What is compared is the same stretch either way.
-
-Give the pair to a subagent when you can: one handed two unlabelled pictures and the question knows
-neither which is the reference nor what was built, which is the same blindness this section rests on.
-The round means one element produces several comparisons at once, so dispatch one subagent
-per comparison and let them run together. Where the harness has no subagents, run them one after
-another rather than merging them into a single look, and answer them yourself under the discipline
-`observers.md` states in place of blindness — write the differences down before naming a cause, count
-only repairs aimed at a difference you wrote down, and read a quantity off the picture rather than
-spending an attempt guessing at it.
-
-Hypit Studio is a browser preview for a person to look at. It is not a source of the picture this
-loop needs: that picture is the local render in `../preview.md`, which draws one element as the
-Source configures it, without a Provider.
-
-Repairing one element never re-runs the others. Do not rebuild the whole video to inspect one piece,
-and do not defer every comparison to a final delivery Build.
-
-## Comparison is blind
-
-- Never tell the observer which picture is the reconstruction, what was built, which component drew
- it, or what you expect to be wrong. An observer told what to confirm will confirm it.
-- `--question` carries what to look at, never what to conclude. Three things qualify: which region to
- read, which regions to skip because they hold a placeholder standing in for a declared-but-unbuilt
- generation, and one visible quantity to measure. None of them says which picture is the
- reconstruction, what was built, or what you expect to be wrong — and a question that hints at the
- answer, rather than naming what to look at, has stopped being scope.
-
-## Repair in dependency order
-
-When the difference is structural rather than cosmetic, repair in the order given by
-`../local-author-package.md`: package and workspace resolution, activation contribution, Manifest,
-Producer, Type and Validator agreement, Surface vocabulary and decoding, implementation behaviour,
-then source usage. Fixing source usage over a broken implementation hides the defect one layer down.
-
-## One comparison round
-
-**There is one comparison round.** What it returns is the whole difference set this reconstruction
-gets. Repair against that set and stop; do not compare again. This bounds the comparing, and nothing
-else: a narrow `observe_reference --question` settles disagreeing evidence at any point, which is
-what `evidence.md` is for.
-
-The reference has nothing further to say after it: it already showed every stretch, and a second look
-re-reads the same frames to check your own work. That spends the expensive half of the route — the
-renders and the observer — on verifying a repair rather than on learning anything about the
-reference.
-
-So **a repair is not verified here**, and the honest place to say so is the report: the section at
-the end of this file says what this route left unchecked. Passing `pnpm check` and `hypit check` is
-the precondition for the round, not a result of it.
-
-Two things follow, and they are the whole discipline:
-
-- **Every repair aims at a difference the comparison named.** Changing something it did not mention
- is thrashing, and it does not earn one of the attempts below.
-- **A difference caused by an input that does not exist yet is not a repair target.** The mocks above
- stand in for a base take and for media slots a Build has not filled, and an observer told where they
- are should bypass them. One that reports a mock anyway is describing an absence, not a defect.
-
-A difference nobody can close is not a failure to record as one. A typeface the generator cannot
-reproduce, a texture it will not hold, a grain that is not available — write it into the report and
-leave it.
-
-### Two ceilings, and they never share attempts
-
-The first is over the *package*: a difference the package cannot express is a package defect, and
-fixing it means changing the package's structure. The second is over the *values*: once the package
-can express everything the observation states, tune the Recipe, the font, the placement and the
-motion.
-
-**Write-and-remake the package: two attempts.** The first fixes what is obvious, the second fixes what
-the first revealed. If the difference is still one the package cannot express — a typeface mix it has
-no port for, a motion it cannot draw — the package is wrong rather than the values, and tuning values
-is thrashing. Widen the package instead, which starts a fresh write-and-remake for the widened shape.
-
-**Fill the parameters: two attempts.** The wrong weight, the wrong size, the wrong colour, the wrong
-position. Beyond the ceiling, guesses overshoot — correcting past the reference rather than towards
-it. Time beats fidelity here by explicit choice.
-
-**Each ceiling is two attempts for the element, across all its stretches.** Comparing an element in
-five stretches does not buy ten attempts; it buys a fuller picture of what one attempt has to fix. One
-repair aimed at a difference several stretches agree on is one attempt however many reported it.
-
-## Measure what can be measured; iterate only on what cannot
-
-Two attempts per loop is not enough to converge by guessing, and it is not meant to be. A difference
-stated as a quantity — a stroke that is too thick, a shape that is too tall, type that is too large,
-a margin that is too wide — is not a guessing problem. Ask for the number: a
-`compare_reconstruction --question "how tall is the oval relative to the frame?"` returns a
-measurement in one step, from whichever observer the reference holds. Ask it over whichever stretch
-renders the quantity most legibly — this is one reading of one number, not the coverage round, and
-reading it off one where the thing is small buys a worse number for the same price.
-
-Do that instead of spending an attempt. An attempt is for differences that have no number — a
-typeface's character, a texture, a rhythm — where the only route is change it and look again.
-
-Measure against the frame, not against the screen it is viewed on. A quantity read off a rendered
-still means what it means relative to that still's own width and height — a stroke that is "one
-percent of the frame height", a shape "a third of the frame width" — which is the same basis the
-Recipe's fractions use. Saying "a little too tall" and changing it on feel spends the attempt the
-measurement exists to save.
-
-Stopping is the end, and the end carries no final comparison. When the attempts are spent the loop
-stops as it is: the second repair is the last thing the observer saw, and there is no third
-comparison to name what remains. Do not spend one to find out — a comparison that changes nothing
-and exists only to report the gap is a paid step for a report nobody asked for. The element is what
-it is; move on to the next one.
-
-When there is no next element the reconstruction is complete, and three things follow it.
-
-## Say what this route did not verify
-
-"Complete" here means every element was compared and every loop stopped. It does not mean the video
-was watched, because on this route no video exists: the Build has not run. Report the difference
-rather than letting the word carry it.
-
-State plainly, in the completion report, that the following are unverified:
-
-- **every generated picture and take** — the images and the shots a Provider has still to make;
-- **the timing of every Track** — this route compares each one against a stand-in SemanticTake, so
- how a Caption, Media or Typography Track sits against the speech that is finally delivered is
- settled once that speech exists;
-- **whether the picture is continuous** — the frames nobody authored that `frame-coverage.md` is
- about. One inherited edge is settled here: `reconstruction_check` reads each Recipe's `playback`
- and refuses an insert configured to stop when its material runs out. The rest
- of them — a window that starts late, a blend whose frames are half-covered, a schedule inside a
- component that stops between activations — appear in the delivery;
-- **whether the delivery says the Script's words** — a take generated from a prompt that lost its
- dialogue passes every check this route runs.
- `../playbooks/craft/seedance-directing.md` says how to trace a take's prompt back to the Segment's
- `dialogue` while the Source is being written, which is where this one is prevented.
-
-`reconstruction_check` is the mechanical half of this: it names the elements that were never compared
-and the timed pictures configured to empty their windows, and refuses to pass while either remains.
-It cannot name what a Build has not produced yet, which is why
-this list is stated rather than computed.
-
-If the author wants the result to differ from the reference — their presenter, their product, their
-brand — read the sources you wrote and change them to what they asked for. `route.md` says why that
-happens here rather than earlier.
-
-If a project-local package was built along the way, decide whether it should outlive this video and
-put that to the author: `../package-promotion.md` says how to judge it and what promoting it
-actually costs.
diff --git a/.agents/skills/hypit/references/reconstruction/route.md b/.agents/skills/hypit/references/reconstruction/route.md
index 4ec4239d..91f0a66d 100644
--- a/.agents/skills/hypit/references/reconstruction/route.md
+++ b/.agents/skills/hypit/references/reconstruction/route.md
@@ -39,7 +39,7 @@ Reference observation is part of the work and is expected to cost what it costs.
The author gives one thing: the path to a video. The working directory, the project name, which
packages to use and where the result goes are yours to decide. Ask the author about the video and
nothing else — what it is for, who is in it, what it should say. Those answers describe the result
-they want; record them and apply them at step 24. Never interrupt to ask which generator, which
+they want; record them and apply them at step 23. Never interrupt to ask which generator, which
package, which directory, or whether to proceed.
The author often wants the result to differ from the reference: their presenter, their product,
@@ -96,26 +96,14 @@ exception: it selects an observer rather than blocking one, and step 5 owns it.
observer, the credential decision table, the disclosure the author is owed, and the rule that one
reference has one observer for its whole life.
-### 5. Probe for Vertex credentials
+### 5. Probe for Vertex credentials, then ask which observer reads
-```bash
-node .agents/skills/hypit/scripts/check-credentials.mjs GOOGLE_CLOUD_PROJECT GOOGLE_APPLICATION_CREDENTIALS_JSON
-```
-
-Report what this machine holds rather than asking the author to recall it. Both `set` means `gemini`
-is available and the author chooses. Either one `missing` means `agent` is the path that can run
-today.
-
-### 6. Ask which observer reads the reference
-
-Ask once. Name what each costs, and say that `agent` reads the reference a little less closely — a
-shot arrives as sampled frames rather than continuous video, so continuity across it is read rather
-than watched, and there is no sound, so a voice is attributed rather than heard. Say it once, take
-the answer, and run.
+`observers.md`'s "Choosing" section holds the command, what each answer means, and the disclosure the
+author is owed. Run it, put the question once, take the answer, and run.
**This is the only question this route asks about how it runs.**
-### 7. Say which observer is reading
+### 6. Say which observer is reading
One line, before any evidence starts.
@@ -123,7 +111,7 @@ One line, before any evidence starts.
## Phase 1 — Evidence, with reading alongside
-### 8. List installed vocabulary
+### 7. List installed vocabulary
```bash
hypit-reference-video-tools list_svml_packages
@@ -133,7 +121,7 @@ It reads `node_modules/@hypit` relative to the working directory and refuses whe
it from the repository root. Name the project with `--package-root` when the command is not run from
inside it. This is instant and may run before or during the sweep.
-### 9. Prepare the reference
+### 8. Prepare the reference
```bash
hypit-reference-video-tools prepare_reference --video-path <path> --observer gemini|agent
@@ -151,13 +139,13 @@ they come back as `pending_observations` for you to answer with `record_observat
four first, because `observe_reference` quotes them into every shot's question and refuses to run
until they exist.
-### 10. Run the full sweep, in the background
+### 9. Run the full sweep, in the background
```bash
hypit-reference-video-tools observe_reference --reference-id <reference-id>
```
-**Start this before step 11 and read while it runs.** Its prompts are fixed and nothing in step 11
+**Start this before step 10 and read while it runs.** Its prompts are fixed and nothing in step 10
changes what they ask. Reading first and observing afterwards makes the same run several minutes
longer for nothing.
@@ -165,23 +153,19 @@ On the `agent` observer, give each task its own subagent where the harness has t
together; that is what makes the sweep parallel. Answering everything one call listed is not the end
of it — the sweep ends when `pending_observations` and `unresolved` are both empty.
-### 11. Read the route's craft, while the sweep runs
+### 10. Read the route's craft, while the sweep runs
Read completely, in this order — a reconstruction needs to know what a picture *is* before what one
generation owes another:
1. `continuity.md` — shot, overlay, B-roll, speaker, product and persistent-system rules.
-2. `../playbooks/craft/graphic-compositions.md` — what may be a base picture, when a full screen is
- one authored composition, and where a missing picture comes from.
-3. `../playbooks/craft/generated-dependencies.md` — what one generation owes another: the location,
- the split picture, the voice, the first frame, and the stretch too short to be a take.
-4. `../playbooks/craft/frame-coverage.md` — what is on screen at every instant, and the edges nobody
- chose.
-5. `../playbooks/craft/visual-continuity.md` — recurring anchors as explicit artifacts, one location
- generated once, and the reverse-view geometry that must hold across takes.
-6. `../vocabulary.md` — how a package is chosen: enumerate every system before naming one, reuse
+2. Every craft file named in the first item of `../playbooks/index.md`'s required load order, in the
+ order it gives them. That page owns the list; restating it here is how a required file once became
+ reachable from one route and invisible to the other.
+3. `../script-time.md` — what a Segment is bound to, and why never a number of seconds.
+4. `../vocabulary.md` — how a package is chosen: enumerate every system before naming one, reuse
before compose before declaring a gap, and what a real gap obliges.
-7. `vocabulary.md` — what the reference evidence adds to that: enumerating from the observations, and
+5. `vocabulary.md` — what the reference evidence adds to that: enumerating from the observations, and
measuring an appearance value rather than choosing it.
Do not skip one because the task looks like a familiar video format.
@@ -190,26 +174,21 @@ Do not skip one because the task looks like a familiar video format.
## Phase 2 — Interpret the evidence
-### 12. Collect the sweep and inspect what failed
+### 11. Collect the sweep and inspect what failed
`unresolved` lists observations that failed outright. A complete observation that says "unclear" is
still complete. Be most suspicious of anything an observation asserts about change over time.
`evidence.md` says why and what to do.
-### 13. Settle conflicts with narrow questions
+### 12. Settle conflicts with narrow questions
-```bash
-hypit-reference-video-tools observe_reference --reference-id <id> --shot-id shot-007 \
- --question "How thick is the outline on the caption words, relative to the stroke width of the letters?"
-```
-
-One to three shots per question; `--batch <questions.json>` sends several. Ask about visible
-attributes. Never ask which component to use. Do not re-observe a full shot to correct one.
+`evidence.md`'s "Narrow questions" section holds the command, what a question may ask, and why
+re-observing a whole shot to correct one is the wrong repair.
**Done when:** every appearance value that changes what the viewer sees is measured rather than
defaulted, and every conflict between observations is settled.
-### 14. Inspect candidate packages
+### 13. Inspect candidate packages
```bash
hypit-reference-video-tools inspect_svml_vocabulary --package @hypit/<name> [--package …]
@@ -218,7 +197,7 @@ hypit-reference-video-tools inspect_svml_vocabulary --package @hypit/<name> [--p
Enumerate the systems from the observations, then inspect a candidate for each. A system you never
inspected is a system you are about to invent.
-### 15. Develop a project-local package, only for a proven gap
+### 14. Develop a project-local package, only for a proven gap
**Read now:** `../local-author-package.md`, completely.
@@ -229,7 +208,7 @@ that loads is not yet a component that looks like the reference.
## Phase 3 — Author, check, wire
-### 16. Write the four files
+### 15. Write the four files
`main.svml`, `recipes.svs`, `build.svrun`, `hypit.runtime.json`. The Runtime Profile is part of the
deliverable even though this route runs nothing: without it the first thing the author meets is
@@ -243,81 +222,62 @@ deliverable even though this route runs nothing: without it the first thing the
- `../playbooks/craft/captions.md` — Cue breaks, the Recipe keys, and what recomputes when speech
changes.
- `../playbooks/craft/persona-and-audio.md` — one voice sample per person, and the identity anchors
- that make step 24 cheap.
+ that make step 23 cheap.
- `../playbooks/index.md` and the craft files it names for the systems this reference actually
contains. Those conditions can only be evaluated now, with the evidence in.
Do not author one source fragment per shot.
-### 17. Check all three sources
+### 16. Check every source
-```bash
-hypit check path/to/main.svml
-hypit check path/to/recipes.svs
-hypit check path/to/build.svrun
-```
+`../authoring.md` holds the check set — every command, not only the Author Source — and why no wrapper
+is written for it.
-Check all of them. Do not create a check wrapper.
-
-### 18. Prove the graph traces
+### 17. Prove the graph traces
```bash
hypit-reference-video-tools preview_check /path/to/project/build.svrun
```
-**Read now:** `../preview.md`.
-
-`preview_check` reporting only `unresolved capabilities` and staying sound **is the pass**, and is
-the state every reconstruction is in when its sources are first written. Neither this gate nor step
-17 is bounded by the loop's attempt ceilings: a graph that does not trace is work that is not done.
+**Read now:** `../preview.md`, which says which refusal is the pass. A Source that declares its
+generations rather than performing them is the state every reconstruction is in when its sources are
+first written. Neither this gate nor step 16 is bounded by the round's attempt ceilings.
---
-## Phase 4 — The comparison loop
+## Phase 4 — The comparison round
-### 19. Read the loop
+### 18. Read the round
-**Read now:** `reconstruction-loop.md`, as soon as the sources place an element — that is the first
-moment the loop has something to render.
+**Read now:** `../element-review.md`, then `comparison-round.md`, as soon as the sources place an
+element — that is the first moment the round has something to render.
-### 20. Render every stretch of every authored element
+### 19. Render every stretch of every authored element
-```bash
-hypit-reference-video-tools render_element projects/<name>/build.svrun \
- --element <id> --segment <id>|--selection <id> --reference-id <id> --out <path>.mp4
-```
+`../preview.md` holds `render_element`; `comparison-round.md` says to pass `--reference-id` every time
+so the stand-in runs on the reference's clock. Render the whole set before comparing any of it.
-A whole round is one call: `--batch <renders.json>`. `render_element` calls `make-placeholder` itself
-for the layers a Build has not made.
+### 20. Send every comparison for the element at once
-### 21. Send every comparison for the element at once
+`comparison-round.md` holds `compare_reconstruction` and its batch form. **Pass `--element <id>` every
+time**, or step 22 credits the comparison to nothing.
-```bash
-hypit-reference-video-tools compare_reconstruction --reference-id <id> --shot-id <id> \
- --video <path>|--image <path> [--question <scope>] [--element <id>]
-```
-
-**Pass `--element <id>` every time**, or step 23 credits the comparison to nothing. Send all of an
-element's comparisons before repairing anything.
+### 21. Repair against the differences that round returned
-### 22. Repair against the differences that round returned
+Within the two ceilings `../element-review.md` sets. Then return to step 19 for the next element.
-Within the two ceilings `reconstruction-loop.md` sets. Then return to step 20 for the next element.
-
-### 23. Close the route on the check
+### 22. Close the route on the check
```bash
hypit-reference-video-tools reconstruction_check projects/<name>/build.svrun
```
It names each element that has never been compared and the command that compares it, and reports
-`"passed": false` until none are left. It asks for participation rather than convergence — the loop
+`"passed": false` until none are left. It asks for participation rather than convergence — the round
is deliberately bounded and may stop with visible differences remaining — so an element compared once
-and stopped at its ceiling passes, and an element nobody looked at does not.
-
-It also reads each timed picture's appearance Recipe and refuses a `playback` left at its default,
-which draws generated material once and then draws nothing for the rest of the window.
-`../playbooks/craft/generated-dependencies.md` says what to set.
+and stopped at its ceiling passes, and an element nobody looked at does not. It also refuses a
+`playback` left at its default — `../playbooks/craft/generated-dependencies.md` says what to set — and
+an uncovered stretch of the Script, and reports every Frame reaching past the Canvas.
How it picks a reference: exactly one prepared → it uses that one; several → it demands
`--reference-id <id>` and refuses without it; none → it refuses and tells you to run
@@ -333,8 +293,8 @@ drawing element passes with nothing to require.
---
-### 24. Apply the author's requested change
+### 23. Apply the author's requested change
-Read what you wrote and change it to what they asked for at step 6. The identity of each recurring
+Read what you wrote and change it to what they asked for at the start. The identity of each recurring
person and product is already a single anchor, because `../playbooks/craft/persona-and-audio.md` and
`../playbooks/craft/visual-continuity.md` required that while you were writing.
diff --git a/.agents/skills/hypit/references/reconstruction/vocabulary.md b/.agents/skills/hypit/references/reconstruction/vocabulary.md
index 600dd658..73840d9d 100644
--- a/.agents/skills/hypit/references/reconstruction/vocabulary.md
+++ b/.agents/skills/hypit/references/reconstruction/vocabulary.md
@@ -31,7 +31,7 @@ measured rather than chosen:
## After the gap is filled
Installing the package is not the end of the gap route. Read `final-sources.md` and write the three
-sources, then continue into `reconstruction-loop.md`: a component that loads is not yet a component
+sources, then continue into `comparison-round.md`: a component that loads is not yet a component
that looks like the reference.
The reference-video CLI remains limited to observation, vocabulary inspection and blind image
diff --git a/.agents/skills/hypit/references/script-time.md b/.agents/skills/hypit/references/script-time.md
new file mode 100644
index 00000000..2f798953
--- /dev/null
+++ b/.agents/skills/hypit/references/script-time.md
@@ -0,0 +1,59 @@
+# The program runs on the script's words, not on a clock
+
+Every take is generated. It comes back at whatever length the model returned, and the SemanticTrack is
+built from the words WhisperX finds inside it. So a number of seconds is never what a program is
+authored against: the words are, and everything placed is bound to them.
+
+Both routes reach this file. What differs is only where the temptation to use a clock comes from — a
+reference video hands you a table of seconds, and a brief hands you a duration — and the answer is the
+same either way.
+
+## A Segment is a stretch that is spoken as one
+
+Cut the Script into Segments the way the program is *spoken*, not the way its pictures are numbered:
+consecutive Segments carrying one unbroken voiceover are one Segment with Selections inside it.
+`playbooks/craft/generated-dependencies.md` says why — a Segment is a generation boundary, and
+splitting a stretch that is delivered unbroken invents a seam it does not have.
+
+One thing does force a seam. The take that speaks a Segment generates that speech, so a Segment can
+be no longer than one generation. Where an unbroken passage runs past what the model will produce in
+one take, it becomes two Segments — and then the seam is yours to place rather than the ceiling's.
+Put it where the speaker would draw breath: at a sentence end, never mid-clause.
+
+## A take's duration is estimated
+
+Every take is generated, and the generated speech plays at its own pace. So each take's duration comes
+from `estimate:Speech` — the prediction of how long the generated line will be. Write that estimate on
+the take.
+
+Nothing depends on the estimate being exact. Script Selections bind every placed element to the
+words, and the SemanticTrack places the words where the generated audio actually has them, so a
+take that comes back a little long or short moves the words, not the bindings. This is also what
+lets a program survive the author changing the lines: the estimate recomputes from the new
+words. `estimate:Speech` takes `story.segment.NAME.speech`, so the duration follows the script it is
+asked to predict.
+
+## Bind covering content to the words, not to a frame
+
+Bind covering content to a Script Selection over the words it covers — mark the range in the Script,
+pass `semantic={speech.semantic}` to the Track, and use `during={story.selection.NAME}` — and let the
+projection resolve the frames.
+
+An Item bound to 3.25 seconds points at whichever word happens to land there, which is not the word
+the number was copied from. One take returning half a second long moves every window after it.
+
+Explicit `start`/`end` is for a program with no speech to anchor to.
+`playbooks/craft/b-roll.md` reads that as a deliberate choice rather than a transcription.
+
+## A system that spans pictures is authored once
+
+- A visual system that persists across cuts — captions, a running list that keeps its state, a
+ progress indicator, a persistent badge or logo, a recurring lower third — is one system: one
+ Program, one Track and one shared Style over its full lifetime, even when the visible
+ words, items or values change.
+- Do not recreate the system per picture, and do not create a second Style because a new picture
+ begins. A new picture is never itself evidence of a change in appearance.
+- Author a local difference as a scoped variation inside the one system, on exactly the
+ words, items or interval where it belongs.
+- Whether the system is one Program with per-item timing or separate instances is decided by the
+ declared vocabulary of the chosen package, never by how many pictures there are.
diff --git a/packages/reference-video-tools/src/authoring.ts b/packages/reference-video-tools/src/authoring.ts
index 5e199437..3c2b50f4 100644
--- a/packages/reference-video-tools/src/authoring.ts
+++ b/packages/reference-video-tools/src/authoring.ts
@@ -806,7 +806,7 @@ function timingReport(reference: string | undefined, segments: readonly StandInT
* Render one element of a Source the way that Source configures it, without a Build and without a
* Provider.
*
- * `reconstruction-loop.md` compares a reconstructed element against the reference. What it must
+ * `comparison-round.md` compares a reconstructed element against the reference. What it must
* compare is the element as this video places it — the Recipe values the Source passes, the Script
* text it feeds, the windows it binds — because a Source can fill those with values that collide
* while a package's catalogue preview, drawn from sample values, stays perfect. Producing that
@@ -919,9 +919,14 @@ export async function renderElement(input: RenderElementInput): Promise<Record<s
if (focusedSegment !== undefined) {
sliced = sliceSource(svml, focusedSegment);
sourcePath = join(compareRoot, "sliced.svml");
- // The fragment sits three directories below the Source it came from, so its own relative imports
+ // The fragment sits three directories below the Source it came from, so its own relative paths
// have to reach back the same distance the derived Run's carried files do.
- const repointed = sliced.text.replace(/(\s(?:source|from)=")\.\//gu, "$1../../../");
+ //
+ // `src` belongs in this list beside the import attributes. It is how the author's own supplied
+ // material is named — a presenter still, a voice sample — and left alone it resolved against the
+ // fragment's directory, where there is no `assets/`. Every Source carrying a `media:Image` with a
+ // relative path failed to render at all, on either route, the moment a window was named.
+ const repointed = sliced.text.replace(/(\s(?:source|from|src)=")\.\//gu, "$1../../../");
await writeFile(sourcePath, repointed, "utf8");
// Everything downstream reads the Source: which Takes to stand in for, which media to mock, which
// outputs to satisfy. Left on the original it would declare mocks for elements the cut removed,
diff --git a/packages/reference-video-tools/src/checks.ts b/packages/reference-video-tools/src/checks.ts
index 49efb061..ae0d5c3e 100644
--- a/packages/reference-video-tools/src/checks.ts
+++ b/packages/reference-video-tools/src/checks.ts
@@ -128,6 +128,37 @@ export type ReconstructionCheckInput = {
readonly reference_id?: string;
};
+/**
+ * Which route wrote the Source, and therefore what "this element was looked at" means.
+ *
+ * `reconstruction` credits a comparison against the reference video, logged under that reference.
+ * `description` credits a review of the element against what the author asked for, logged under the
+ * project — there is no reference to compare to, so the question is conformance rather than
+ * difference. Everything else the check does is the same on both: which elements draw, which words
+ * nothing covers, which Frames reach past the Canvas, and which timed pictures empty their windows
+ * are all read from the Source and know nothing about where the Source came from.
+ */
+export type AuthoringCheckMode = "reconstruction" | "description";
+
+export type AuthoringCheckInput = ReconstructionCheckInput & {
+ readonly mode?: AuthoringCheckMode;
+};
+
+/**
+ * Where a description-authored project's reviews are logged.
+ *
+ * Beside the per-render directories rather than inside them: `render_element` empties its own
+ * `.hypit/compare/<key>` on the way in, and a log kept under there would be deleted by the next
+ * render of the element it is the evidence for.
+ *
+ * Under the project rather than under a reference, because a review is about one project. That is
+ * also what spares this log the cross-project filter the comparison log needs: a reference is shared
+ * between every reconstruction of one video, and a project's `.hypit` is not shared with anyone.
+ */
+export function reviewLogPath(runPath: string): string {
+ return join(dirname(runPath), ".hypit", "reviews.jsonl");
+}
+
/**
* Which clock timed the stand-ins an element's comparisons were made over.
*
@@ -423,18 +454,22 @@ function framesPastTheCanvas(svml: string): readonly OutOfBoundsFrame[] {
}
/**
- * Report what the route can still settle after the Source is written and before a Build runs: which
- * reconstructed elements have never been compared against the reference, which words of the Script
- * nothing draws a full-frame picture over, and which timed pictures are configured to stop before
- * their window ends.
+ * Report what a route can still settle after the Source is written and before a Build runs: which
+ * drawing elements nobody has looked at, which words of the Script nothing draws a full-frame
+ * picture over, and which timed pictures are configured to stop before their window ends.
+ *
+ * Both routes end here, and `mode` is the only thing that differs. A reconstruction is looked at by
+ * comparing each element against the reference; a description-authored program has no reference, so
+ * each element is reviewed against what the author asked for. What counts as evidence and where it
+ * is logged follow from that; everything else below is read from the Source and does not care.
*
- * `preview_check` proves the graph is wired. It proves nothing about whether what the graph draws
- * resembles the reference video, and a Source can pass every structural check while a component
- * draws something the reference never contained. Closing that gap is
- * `references/reconstruction/reconstruction-loop.md`, which is prose, and prose is what a route
- * skips silently. This is the same requirement as a command that answers whether it was met.
+ * `preview_check` proves the graph is wired. It proves nothing about whether what the graph draws is
+ * what was wanted, and a Source can pass every structural check while a component draws something
+ * nobody asked for. Closing that gap is `references/element-review.md` and the route file beside it,
+ * which is prose, and prose is what a route skips silently. This is the same requirement as a command
+ * that answers whether it was met.
*
- * What it checks is **participation, not convergence**. The loop is deliberately bounded and may
+ * What it checks is **participation, not convergence**. The round is deliberately bounded and may
* stop with visible differences remaining, so requiring convergence here would contradict it. An
* element that was compared once and stopped at its ceiling passes; an element nobody ever looked
* at does not.
@@ -444,11 +479,10 @@ function framesPastTheCanvas(svml: string): readonly OutOfBoundsFrame[] {
* colour and placement are as unverified as a new package's — and `render_element` stands in for the
* speech, so it renders before a Build like any other.
*
- * A comparison counts whether its answer came back in-band (`complete`, the gemini observer) or was
- * handed out to be answered by looking (`pending`, the agent observer); only `failed` is not a
- * comparison. The gate cannot judge whether the shot an element was compared against actually showed
- * it, so the shots are reported for a reader, and a lone comparison is called out rather than assumed
- * meaningful.
+ * A look counts once it has been answered: in band (`complete`, the gemini observer) or handed out
+ * and closed by whoever answered it (`pending` until then). Only `failed` is not a look. The gate
+ * cannot judge whether the stretch an element was looked at over actually showed it, so the stretches
+ * are reported for a reader, and a lone look is called out rather than assumed meaningful.
*
* Each element also carries what timed the stand-ins it was compared over, read from the sidecar
* `render_element` writes beside its output and carried into the log by `compare_reconstruction`.
@@ -467,10 +501,17 @@ function framesPastTheCanvas(svml: string): readonly OutOfBoundsFrame[] {
*
* A project that places no drawing element passes with nothing to require.
*/
-export async function reconstructionCheck(
- input: ReconstructionCheckInput,
+export async function authoringCheck(
+ input: AuthoringCheckInput,
roots: { readonly packageRoot: string },
): Promise<Record<string, unknown>> {
+ const mode: AuthoringCheckMode = input.mode ?? "reconstruction";
+ // What looking at an element is called on this route. A reconstruction compares it against the
+ // reference; a description-authored program has nothing to compare to and is read against what the
+ // author asked for. The arithmetic is the same either way, so only the word differs — and the keys
+ // do not, so one shape describes both reports.
+ const looked = mode === "reconstruction" ? "compared" : "reviewed";
+ const looking = mode === "reconstruction" ? "comparison" : "review";
const cwd = invokedFrom();
const runPath = resolve(cwd, input.run);
// Where the Source's imports resolve from. A project's own packages are installed against the
@@ -784,16 +825,24 @@ export async function reconstructionCheck(
// The Source does not name the reference it reconstructs, so a single prepared reference is used
// when there is exactly one and named explicitly when there is more than one.
+ //
+ // Only on the route that has a reference. A description-authored project has none, and resolving
+ // one here is what used to stop this command before it reached the checks that have nothing to do
+ // with a reference — the `playback` refusal, frame coverage and the Canvas overhang are read from
+ // the Source alone, and were unreachable to that route for no reason but this block.
const preparedRoot = referenceRoot();
- const prepared = (await readdir(preparedRoot, { withFileTypes: true }).catch(() => []))
- .filter((entry) => entry.isDirectory()).map((entry) => entry.name);
- let reference = input.reference_id;
- if (reference === undefined) {
- assert(prepared.length > 0, `no prepared reference under ${preparedRoot}; run prepare_reference first`);
- assert(prepared.length === 1, `${prepared.length} prepared references; pass --reference-id (${prepared.join(", ")})`);
- reference = prepared[0]!;
+ let reference: string | undefined;
+ if (mode === "reconstruction") {
+ const prepared = (await readdir(preparedRoot, { withFileTypes: true }).catch(() => []))
+ .filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+ reference = input.reference_id;
+ if (reference === undefined) {
+ assert(prepared.length > 0, `no prepared reference under ${preparedRoot}; run prepare_reference first`);
+ assert(prepared.length === 1, `${prepared.length} prepared references; pass --reference-id (${prepared.join(", ")})`);
+ reference = prepared[0]!;
+ }
+ assert(prepared.includes(reference), `reference ${reference} is not prepared under ${preparedRoot}`);
}
- assert(prepared.includes(reference), `reference ${reference} is not prepared under ${preparedRoot}`);
type LoggedComparison = {
readonly element?: string;
@@ -811,7 +860,9 @@ export async function reconstructionCheck(
?? (entry.range?.segment === undefined ? undefined : `segment ${entry.range.segment}`)
?? (entry.range?.selection === undefined ? undefined : `selection ${entry.range.selection}`)
?? "an unnamed stretch";
- const logPath = join(preparedRoot, reference, "comparisons.jsonl");
+ const logPath = mode === "reconstruction"
+ ? join(preparedRoot, reference!, "comparisons.jsonl")
+ : reviewLogPath(runPath);
// A reference is keyed by the video, and rightly: its observations are about that video and cost
// real money, so two reconstructions of one file share them. Its comparisons are not about the
// video — they are about one reconstruction — and they were being kept in the same place, so a
@@ -821,7 +872,11 @@ export async function reconstructionCheck(
// What separates them is already on every row: the render it compared. A render belongs to the
// project that produced it, so a row whose picture is not under this project is not this project's
// evidence. Nothing has to move and no earlier log has to be migrated.
+ //
+ // A review log needs none of this: it is already the project's own, so every row in it is this
+ // project's evidence and there is nothing to separate.
const inThisProject = (entry: LoggedComparison): boolean => {
+ if (mode === "description") return true;
if (entry.image_path === undefined) return false;
const at = resolve(entry.image_path);
return at === packageRoot || at.startsWith(`${packageRoot}${sep}`);
@@ -876,8 +931,8 @@ export async function reconstructionCheck(
const elements: ElementReport[] = drawn.map((element) => {
const stretches = rounds.get(element.id) ?? [];
const state = stretches.length === 0
- ? "never compared"
- : `${stretches.length} comparison${stretches.length === 1 ? "" : "s"} against ${[...new Set(stretches)].join(", ")}`;
+ ? `never ${looked}`
+ : `${stretches.length} ${looking}${stretches.length === 1 ? "" : "s"} against ${[...new Set(stretches)].join(", ")}`;
return {
element: `${element.alias}:${element.tag}`,
id: element.id,
@@ -888,7 +943,7 @@ export async function reconstructionCheck(
timing_basis: timingBasis(element.id),
// The gate cannot judge whether the stretch chosen actually showed the element, so a lone
// comparison is called out for a reader to confirm rather than silently accepted.
- ...(stretches.length === 1 ? { note: "single comparison — confirm this stretch shows the element, not a look-alike" } : {}),
+ ...(stretches.length === 1 ? { note: `single ${looking} — confirm this stretch shows the element, not a look-alike` } : {}),
};
});
@@ -898,9 +953,9 @@ export async function reconstructionCheck(
const summary: string[] = [];
if (never.length === 0 && running.length === 0) {
- summary.push(`every drawing element has been compared (${elements.length}), and every timed picture fills its window.`);
+ summary.push(`every drawing element has been ${looked} (${elements.length}), and every timed picture fills its window.`);
}
- if (never.length > 0) summary.push(`${never.length} of ${elements.length} elements have never been compared.`);
+ if (never.length > 0) summary.push(`${never.length} of ${elements.length} elements have never been ${looked}.`);
if (running.length > 0) {
summary.push(`${running.length} window${running.length === 1 ? "" : "s"} will empty before ${running.length === 1 ? "it ends" : "they end"}.`);
}
@@ -912,11 +967,19 @@ export async function reconstructionCheck(
+ `${overhang.length === 1 ? "reaches" : "reach"} past the Canvas; read each one against the reference.`);
}
const compared = elements.filter((element) => element.comparisons > 0).length;
- if (compared > 0) {
+ if (compared > 0 && mode === "reconstruction") {
summary.push(untimed.length === 0
? `every compared element was looked at over a reference-timed stand-in (${compared}).`
: `${untimed.length} of ${compared} compared elements have comparisons over a stand-in that was not reference-timed.`);
}
+ // On the description route every stand-in is estimate-timed, because `estimate:Speech` is the only
+ // clock there is until the Build synthesizes the speech. Reporting that as a shortfall would name
+ // every element every time and ask for a re-render against a reference that does not exist, so it
+ // is stated once as what it is.
+ if (compared > 0 && mode === "description") {
+ summary.push(`every ${looking} was made over a stand-in timed by estimate:Speech (${compared}); how each element `
+ + "sits against the speech the Build synthesizes is settled once that speech exists.");
+ }
if (unresolved.length > 0) {
summary.push(`${unresolved.length} imported package${unresolved.length === 1 ? "" : "s"} could not be resolved, `
+ "so nothing is known about what they draw.");
@@ -926,41 +989,59 @@ export async function reconstructionCheck(
+ "outside this project and are not counted here.");
}
if (awaiting.length > 0) {
- summary.push(`${awaiting.length} comparison${awaiting.length === 1 ? " is" : "s are"} still waiting for `
- + "the differences to be recorded.");
+ summary.push(`${awaiting.length} ${looking}${awaiting.length === 1 ? " is" : "s are"} still waiting for `
+ + `${mode === "reconstruction" ? "the differences" : "the findings"} to be recorded.`);
}
return {
run: runPath,
- reference_id: reference,
+ ...(reference === undefined ? {} : { reference_id: reference }),
// Where this command actually read and resolved from. Said here, no document has to describe it
// from the outside and go stale when it moves.
- roots: { reference: preparedRoot, packages: packageRoot },
+ roots: mode === "reconstruction"
+ ? { reference: preparedRoot, packages: packageRoot }
+ : { reviews: logPath, packages: packageRoot },
passed: never.length === 0 && running.length === 0 && coverage.gaps.length === 0 && unresolved.length === 0,
summary,
elements,
...(never.length === 0 ? {} : {
never_compared: {
ids: never.map((element) => element.id),
- next: "Read .agents/skills/hypit/references/reconstruction/reconstruction-loop.md, then for each: "
- + "render the element as the Source configures it, mock the layers a Build has not made, "
- + "and compare the whole stretch blind — one comparison per Segment or Selection it is drawn over.",
- commands: never.map((element) =>
- `hypit-reference-video-tools compare_reconstruction --reference-id ${reference} --run ${runPath} `
- + `--segment <each Segment ${element.id} is drawn over> `
- + `--video <rendered clip>.mp4 --element ${element.id}`),
+ next: mode === "reconstruction"
+ ? "Read .agents/skills/hypit/references/element-review.md and "
+ + ".agents/skills/hypit/references/reconstruction/comparison-round.md, then for each: "
+ + "render the element as the Source configures it, mock the layers a Build has not made, "
+ + "and compare the whole stretch blind — one comparison per Segment or Selection it is drawn over."
+ : "Read .agents/skills/hypit/references/element-review.md and "
+ + ".agents/skills/hypit/references/original-authoring/conformance-round.md, then for each: "
+ + "render the element as the Source configures it, mock the layers a Build has not made, "
+ + "and have it read against what this element was asked to be — one review per Segment or "
+ + "Selection it is drawn over.",
+ commands: never.map((element) => mode === "reconstruction"
+ ? `hypit-reference-video-tools compare_reconstruction --reference-id ${reference} --run ${runPath} `
+ + `--segment <each Segment ${element.id} is drawn over> `
+ + `--video <rendered clip>.mp4 --element ${element.id}`
+ : `hypit-reference-video-tools review_element --run ${runPath} `
+ + `--segment <each Segment ${element.id} is drawn over> `
+ + `--video <rendered clip>.mp4 --element ${element.id} --intent-file <what ${element.id} was asked to be>`),
},
}),
...(awaiting.length === 0 ? {} : {
awaiting_answer: {
ids: awaiting.map((entry) => entry.id).filter((id) => id !== undefined),
elements: [...new Set(awaiting.map((entry) => entry.element).filter((id) => id !== undefined))],
- note: `${awaiting.length} comparison${awaiting.length === 1 ? " was" : "s were"} performed and handed to an `
- + "observer that answers out of band, and the differences have not come back. Until they do, the pair has "
- + "been drawn and cut but nobody has said what it shows, so it credits nothing here.\n\n"
- + "Close each one with its id:\n"
- + " hypit-reference-video-tools record_observation --reference-id "
- + `${reference} --key comparison:<id> --text-file <the differences>`,
+ note: mode === "reconstruction"
+ ? `${awaiting.length} comparison${awaiting.length === 1 ? " was" : "s were"} performed and handed to an `
+ + "observer that answers out of band, and the differences have not come back. Until they do, the pair has "
+ + "been drawn and cut but nobody has said what it shows, so it credits nothing here.\n\n"
+ + "Close each one with its id:\n"
+ + " hypit-reference-video-tools record_observation --reference-id "
+ + `${reference} --key comparison:<id> --text-file <the differences>`
+ : `${awaiting.length} review${awaiting.length === 1 ? " was" : "s were"} handed out and the findings have `
+ + "not come back. Until they do, the picture has been drawn but nobody has said what it shows, so it "
+ + "credits nothing here.\n\n"
+ + "Close each one with its id:\n"
+ + ` hypit-reference-video-tools record_review --run ${runPath} --review-id <id> --text-file <the findings>`,
},
}),
...(unresolved.length === 0 ? {} : {
@@ -990,7 +1071,10 @@ export async function reconstructionCheck(
note: `${unlabelled} comparison${unlabelled === 1 ? " was" : "s were"} recorded without --element and cannot be credited to one.`,
},
}),
- ...(untimed.length === 0 ? {} : {
+ // Only where a reference-timed stand-in is reachable. On the description route every stand-in is
+ // estimate-timed by definition, so this would list every element and point at a `--reference-id`
+ // that does not exist; the summary states that fact once instead.
+ ...(untimed.length === 0 || mode === "description" ? {} : {
timing_next: {
ids: untimed.map((element) => element.id),
note: "A stand-in sized by estimate:Speech puts every element where the Source puts it and gives it "
diff --git a/packages/reference-video-tools/src/cli.ts b/packages/reference-video-tools/src/cli.ts
index 892dba8e..68b65c6b 100644
--- a/packages/reference-video-tools/src/cli.ts
+++ b/packages/reference-video-tools/src/cli.ts
@@ -2,7 +2,7 @@
import { readFile } from "node:fs/promises";
import { createReferenceVideoTools } from "./tools.js";
-import type { CompareReconstructionInput, ObserveReferenceInput, RenderElementInput } from "./tools.js";
+import type { CompareReconstructionInput, ObserveReferenceInput, RenderElementInput, ReviewElementInput } from "./tools.js";
type Flags = ReadonlyMap<string, string | readonly string[] | boolean>;
@@ -21,12 +21,16 @@ function usage(): string {
" hypit-reference-video-tools compare_reconstruction --reference-id <id> --run <build.svrun> --segment <id>|--selection <id> --video <path>|--image <path> [--question <scope>] [--element <id>]",
" hypit-reference-video-tools compare_reconstruction --reference-id <id> --shot-id <id> --video <path>|--image <path> [--question <scope>] [--element <id>]",
" hypit-reference-video-tools compare_reconstruction --reference-id <id> --batch <comparisons.json>",
+ " hypit-reference-video-tools review_element --run <build.svrun> --element <id> --segment <id>|--selection <id> --video <path>|--image <path> --intent-file <path> [--question <scope>]",
+ " hypit-reference-video-tools review_element --run <build.svrun> --batch <reviews.json>",
+ " hypit-reference-video-tools record_review --run <build.svrun> --review-id <id> --text <text>|--text-file <path>",
" hypit-reference-video-tools make-placeholder --out <path> --width <w> --height <h> [--color light|mid|dark|white|black|#RRGGBB] [--video] [--seconds <s>]",
" hypit-reference-video-tools render_element <build.svrun> --element <id> --out <path.png|path.mp4> [--segment <id>] [--selection <id>] [--reference-id <id>]",
" hypit-reference-video-tools render_element <build.svrun> --batch <renders.json> [--reference-id <id>]",
" hypit-reference-video-tools render_previews <package-dir> [...]",
" hypit-reference-video-tools preview_check <build.svrun> [<hypit.runtime.json>]",
" hypit-reference-video-tools reconstruction_check <build.svrun> [--reference-id <id>]",
+ " hypit-reference-video-tools authoring_check <build.svrun>",
"",
"preview_check opens the Run the way Studio does and reports whether the graph traces. `sound` is",
"true when every Track resolved, and also when the only thing missing is capabilities a Provider has",
@@ -105,7 +109,7 @@ function usage(): string {
"placeholder and is therefore still whatever the reference does.",
"",
"make-placeholder writes a correctly-sized placeholder for a media slot the Source declares as a",
- "generation and a Build has not filled. It is deterministic and Provider-free: the comparison loop",
+ "generation and a Build has not filled. It is deterministic and Provider-free: the comparison round",
"uses its output to mock an empty slot, and the observer is told the slot is a placeholder so it is",
"bypassed rather than reported as a difference. `--color` picks the fill from the named presets (the",
"default `light` shows on a dark base; `dark` shows on a light one) or a six-digit hex, and the",
@@ -115,16 +119,31 @@ function usage(): string {
"script written by hand.",
"",
"record_observation takes the keys the agent observer is handed: the four whole-reference keys, a",
- "shot key such as visual:003 or boundary:004, a narrow question keyed by the shots it was asked over",
- "(question:003+004), and a comparison keyed by the `comparison_id` compare_reconstruction returned",
- "(comparison:<id>). A comparison's answer is written back onto its own line of the log, which is",
+ "shot key such as visual:shot-003 or boundary:shot-004, a narrow question keyed by the shots it was",
+ "asked over and by the question itself (question:shot-003+shot-004:<digest>), and a comparison keyed",
+ "by the `comparison_id` compare_reconstruction returned (comparison:<id>). Pass the key back exactly",
+ "as it was handed out. A comparison's answer is written back onto its own line of the log, which is",
"what makes it count toward coverage; until then reconstruction_check lists it under",
"`awaiting_answer`.",
"",
+ "review_element is the counterpart on the route with no reference: it reads one rendered element",
+ "against what that element was asked to be, rather than against a video to copy. --intent-file",
+ "carries the author's own words and is required; --element is required too, so a review credits an",
+ "element by construction. A clip becomes a grid of its own frames, and the task comes back to be",
+ "answered — nobody is billed to look at a local render — with record_review closing it. Reviews are",
+ "logged under the project, at <project>/.hypit/reviews.jsonl, and authoring_check reads them.",
+ "",
+ "authoring_check is reconstruction_check for a program authored from a description. It resolves no",
+ "reference and credits an element from the review log, and it applies every check the Source alone",
+ "decides — an uncovered stretch, a Frame reaching past the Canvas, a `playback` left at its default.",
+ "Pick the command that matches the route; neither infers which one you meant.",
+ "",
"--observer picks who reads the reference, once per reference. `gemini` uploads video to Vertex and",
"needs GOOGLE_CLOUD_PROJECT and GOOGLE_APPLICATION_CREDENTIALS_JSON. `agent` needs no credentials: it",
"returns each observation as a task carrying its prompt and one tiled picture per shot, which the",
- "calling agent answers with record_observation.",
+ "calling agent answers with record_observation. A task whose question needs sound also carries the",
+ "words WhisperX measured — `transcript_words` for its own stretch, `transcript_ref` for the whole",
+ "file — since that observer reads pictures and the words are the only record of when speech happens.",
"",
"inspect_visual_contract answers what a Producer that draws may return: the element kinds, the style",
"names admitted on them, which take an enum, and how few keyframes an animation carries. Every line is",
@@ -149,7 +168,7 @@ function usage(): string {
// `preview_check` and `reconstruction_check`, one or more package directories for `render_previews` —
// so a token that is not a flag is collected rather than refused. Every other command still refuses
// one, which is why the check is made per command rather than dropped here.
-const COMMANDS_WITH_OPERANDS = new Set(["render_element", "render_previews", "preview_check", "reconstruction_check"]);
+const COMMANDS_WITH_OPERANDS = new Set(["render_element", "render_previews", "preview_check", "reconstruction_check", "authoring_check"]);
function parse(argv: readonly string[]): { readonly command: string; readonly operands: readonly string[]; readonly flags: Flags } {
const command = argv[0];
@@ -268,6 +287,37 @@ async function main(): Promise<void> {
text: textFile === undefined ? required(flags, "text") : await readFile(textFile, "utf8"),
};
result = await tools.record_observation(input as { reference_id: string; key: string; text: string });
+ } else if (command === "review_element") {
+ const reviewFile = one(flags, "batch");
+ if (reviewFile !== undefined) {
+ const parsed: unknown = JSON.parse(await readFile(reviewFile, "utf8"));
+ const list = Array.isArray(parsed) ? parsed : (parsed as { reviews?: unknown }).reviews;
+ if (!Array.isArray(list)) throw new Error(`${reviewFile} must hold a JSON array of reviews, or an object with a "reviews" array`);
+ result = await tools.review_element({ run: required(flags, "run"), reviews: list } as ReviewElementInput);
+ report(`${JSON.stringify(result, null, 2)}\n`);
+ return;
+ }
+ const input = supplied ?? {
+ run: required(flags, "run"),
+ element: required(flags, "element"),
+ ...(one(flags, "segment") === undefined ? {} : { segment: one(flags, "segment") }),
+ ...(one(flags, "selection") === undefined ? {} : { selection: one(flags, "selection") }),
+ ...(one(flags, "image") === undefined ? {} : { image_path: one(flags, "image") }),
+ ...(one(flags, "video") === undefined ? {} : { video_path: one(flags, "video") }),
+ ...(one(flags, "intent-file") === undefined ? {} : { intent_file: one(flags, "intent-file") }),
+ ...(one(flags, "intent") === undefined ? {} : { intent: one(flags, "intent") }),
+ ...(one(flags, "question") === undefined ? {} : { question: one(flags, "question") }),
+ };
+ result = await tools.review_element(input as ReviewElementInput);
+ } else if (command === "record_review") {
+ // Findings are paragraphs of prose, so they arrive the way an observation's do.
+ const textFile = one(flags, "text-file");
+ const input = supplied ?? {
+ run: required(flags, "run"),
+ review_id: required(flags, "review-id"),
+ text: textFile === undefined ? required(flags, "text") : await readFile(textFile, "utf8"),
+ };
+ result = await tools.record_review(input as { run: string; review_id: string; text: string });
} else if (command === "compare_reconstruction") {
// A round is a list of comparisons, and a list is too long for flags. --batch names a JSON file
// holding it, which is also how it survives being written by one step and read by another.
@@ -373,6 +423,10 @@ async function main(): Promise<void> {
...(one(flags, "reference-id") === undefined ? {} : { reference_id: one(flags, "reference-id") }),
};
result = await tools.reconstruction_check(input as { run: string; reference_id?: string });
+ } else if (command === "authoring_check") {
+ const run = operands[0];
+ if (supplied === undefined && run === undefined) throw new Error(`a <build.svrun> is required\n\n${usage()}`);
+ result = await tools.authoring_check((supplied ?? { run }) as { run: string });
} else {
throw new Error(`unknown command ${command}\n\n${usage()}`);
}
diff --git a/packages/reference-video-tools/src/placeholder.ts b/packages/reference-video-tools/src/placeholder.ts
index cc0b24e9..946d00bd 100644
--- a/packages/reference-video-tools/src/placeholder.ts
+++ b/packages/reference-video-tools/src/placeholder.ts
@@ -72,7 +72,7 @@ function resolvePlaceholderColor(value: string | undefined): PlaceholderPalette
/**
* A correctly-sized placeholder image for a media slot the Source declares as a generation and a
- * Build has not filled. The comparison loop needs a still; the slot must be mocked, and the mock is
+ * Build has not filled. The comparison round needs a still; the slot must be mocked, and the mock is
* this tool's output — deterministic, Provider-free, never a real generation and never a hand-rolled
* script. A field with an inset frame reads as a slot waiting for content rather than a broken
* image, so the observer can bypass the region instead of reporting it every round.
diff --git a/packages/reference-video-tools/src/slice.ts b/packages/reference-video-tools/src/slice.ts
index 22dc5315..68d50e92 100644
--- a/packages/reference-video-tools/src/slice.ts
+++ b/packages/reference-video-tools/src/slice.ts
@@ -157,7 +157,7 @@ export function sliceSource(source: string, segment: string): SliceResult {
// A name outside the cut is not always a name the element can do without. An element given the span
// it occupies and a Moment to cut it — `during="program" until={story.moment.done}` — is on screen
// for the whole of any stretch that ends before that word. Dropping it made the one element a
- // reference is about unrenderable over every Segment but the last, while the loop asks for it to be
+ // reference is about unrenderable over every Segment but the last, while the round asks for it to be
// compared over each of them. Marked before the cut it really is gone, and marked inside it survives
// already, so this is the one case: a close that has not arrived yet, which the fragment reaches by
// no longer closing.
diff --git a/packages/reference-video-tools/src/tools.ts b/packages/reference-video-tools/src/tools.ts
index 0d83c11e..43601b73 100644
--- a/packages/reference-video-tools/src/tools.ts
+++ b/packages/reference-video-tools/src/tools.ts
@@ -22,8 +22,8 @@ import { videoCliDistribution } from "@hypit/video-cli";
import { authorSource, invokedFrom, referenceRoot, referenceWords, renderElement, renderPreviews, spokenRange, standInSidecarPath } from "./authoring.js";
import type { RenderElementInput, RenderPreviewsInput, SpokenRange, StandInFocus, StandInSidecar } from "./authoring.js";
import { writePlaceholder } from "./placeholder.js";
-import { previewCheck, reconstructionCheck } from "./checks.js";
-import type { PreviewCheckInput, ReconstructionCheckInput } from "./checks.js";
+import { authoringCheck, previewCheck, reviewLogPath } from "./checks.js";
+import type { AuthoringCheckInput, PreviewCheckInput, ReconstructionCheckInput } from "./checks.js";
import {
assert,
completelyStill,
@@ -107,6 +107,51 @@ export type CompareReconstructionInput = {
readonly comparisons?: readonly Omit<CompareReconstructionInput, "reference_id" | "comparisons">[];
};
+/**
+ * One element of a description-authored program, read against what it was asked to be.
+ *
+ * The counterpart of `compare_reconstruction` on the route with no reference. There is nothing to
+ * differ from, so the question is conformance: does the picture match the description, and what is
+ * visibly wrong with it. That makes it one-sided, which is the only structural difference — the
+ * render is prepared the same way, the log has the same shape, and the same gate reads it.
+ *
+ * There is no observer choice here. The picture is a local render and nobody is billed to look at it,
+ * so the task always comes back to be answered rather than being sent anywhere.
+ */
+export type ReviewElementInput = {
+ /** The Run whose Author SVML the words are read from, and the project the log belongs to. */
+ readonly run: string;
+ /**
+ * Which element the findings are credited to. Required on a single review and asserted there — a
+ * review credited to nothing is a picture nobody can say was looked at. Optional in the type only
+ * because a `--batch` call carries it per entry rather than at the top.
+ */
+ readonly element?: string;
+ /** The window the render covers, named in words. Exactly one is given. */
+ readonly segment?: string;
+ readonly selection?: string;
+ /** The render. Exactly one of `image_path` and `video_path` is given. */
+ readonly image_path?: string;
+ readonly video_path?: string;
+ /**
+ * What this element was asked to be, in the author's own words: the answers frozen when the brief
+ * was taken and the appearance values written down before the Source was. Required, because a
+ * conformance question with nothing to conform to is an invitation to invent a standard.
+ */
+ readonly intent?: string;
+ readonly intent_file?: string;
+ /** Which region to read, when the picture holds more than the element. Never what to conclude. */
+ readonly question?: string;
+ /** A whole round, run together. Each entry inherits `run` from the outer input. */
+ readonly reviews?: readonly Omit<ReviewElementInput, "run" | "reviews">[];
+};
+
+export type RecordReviewInput = {
+ readonly run: string;
+ readonly review_id: string;
+ readonly text: string;
+};
+
export type MakePlaceholderInput = {
readonly out: string;
readonly width: number;
@@ -130,11 +175,20 @@ export type ReferenceVideoTools = {
paths(): Promise<Record<string, unknown>>;
compare_reconstruction(input: CompareReconstructionInput): Promise<Record<string, unknown>>;
record_observation(input: RecordObservationInput): Promise<Record<string, unknown>>;
+ review_element(input: ReviewElementInput): Promise<Record<string, unknown>>;
+ record_review(input: RecordReviewInput): Promise<Record<string, unknown>>;
make_placeholder(input: MakePlaceholderInput): Promise<Record<string, unknown>>;
render_element(input: RenderElementInput): Promise<Record<string, unknown>>;
render_previews(input: RenderPreviewsInput): Promise<Record<string, unknown>>;
preview_check(input: PreviewCheckInput): Promise<Record<string, unknown>>;
reconstruction_check(input: ReconstructionCheckInput): Promise<Record<string, unknown>>;
+ /**
+ * The same gate for a program authored from a description. It resolves no reference, credits an
+ * element from the project's own review log, and refuses on everything the Source alone decides —
+ * an uncovered stretch, a Frame past the Canvas, a `playback` left at its default — all of which
+ * were unreachable to this route while the check began by demanding a reference.
+ */
+ authoring_check(input: Omit<AuthoringCheckInput, "mode" | "reference_id">): Promise<Record<string, unknown>>;
};
type ToolOptions = {
@@ -189,7 +243,7 @@ export type ComparedRange = {
readonly tail_snapped: boolean;
};
-/** One line per comparison performed, appended so a stopped loop still leaves its trail. */
+/** One line per comparison performed, appended so a stopped round still leaves its trail. */
export type ComparisonRecord = {
readonly at: string;
/**
@@ -221,6 +275,37 @@ export type ComparisonRecord = {
readonly differences?: string;
};
+/**
+ * One line per element review on the route that has no reference to compare against.
+ *
+ * The fields it shares with `ComparisonRecord` are spelled the same, so the gate reads one shape from
+ * either log without an adapter. What differs is the question: a comparison reports how two pictures
+ * differ, and a review reports whether one picture is what it was asked to be — so it carries the
+ * intent it was judged against, and its answer is `findings`.
+ */
+export type ReviewRecord = {
+ readonly at: string;
+ readonly id: string;
+ /** Always present. `review_element` requires `--element`, so a review credits one by construction. */
+ readonly element: string;
+ /**
+ * The window, named the way it was asked for. Only the name: `ComparedRange` also carries where the
+ * reference speaks those words and how the cut was snapped to its shot boundaries, and none of that
+ * exists here. The gate reads the name and nothing else from either log.
+ */
+ readonly range?: { readonly segment?: string; readonly selection?: string };
+ readonly image_path: string;
+ readonly image_digest: string;
+ readonly status: Observation["status"];
+ readonly scope?: string;
+ readonly clip?: boolean;
+ readonly stand_in?: StandInSidecar;
+ /** What this element was asked to be, in the author's own words. */
+ readonly intent: string;
+ /** What the reader found, once it has come back. */
+ readonly findings?: string;
+};
+
async function fileDigest(path: string): Promise<string> {
return `sha256:${createHash("sha256").update(await readFile(path)).digest("hex")}`;
}
@@ -238,9 +323,28 @@ async function standInBeside(renderedPath: string): Promise<StandInSidecar | und
try { return JSON.parse(text) as StandInSidecar; } catch { return undefined; }
}
-async function appendComparison(root: string, record: ComparisonRecord): Promise<void> {
- await serially(root, async () => {
- await appendFile(join(root, "comparisons.jsonl"), `${JSON.stringify(record)}\n`, "utf8");
+/**
+ * One line per look performed, appended so a stopped round still leaves its trail.
+ *
+ * Two logs have this shape and the same three operations over it. A comparison of a reconstruction
+ * against its reference is kept under the reference, and its answer is the differences; a review of a
+ * description-authored element against what it was asked to be is kept under the project, and its
+ * answer is the findings. Nothing else about appending, closing or recognising an answered entry
+ * differs, so the file and the name of the answer are arguments rather than a second copy.
+ */
+type LookLog = {
+ readonly root: string;
+ readonly file: string;
+ /** Which field carries the answer, and therefore what tells an open entry from a closed one. */
+ readonly answer: "differences" | "findings";
+};
+
+const comparisonLog = (root: string): LookLog => ({ root, file: "comparisons.jsonl", answer: "differences" });
+const reviewLog = (root: string): LookLog => ({ root, file: "reviews.jsonl", answer: "findings" });
+
+async function appendLooked(log: LookLog, record: ComparisonRecord | ReviewRecord): Promise<void> {
+ await serially(log.root, async () => {
+ await appendFile(join(log.root, log.file), `${JSON.stringify(record)}\n`, "utf8");
});
}
@@ -257,19 +361,19 @@ async function appendComparison(root: string, record: ComparisonRecord): Promise
* is the case this must not swallow.
*/
async function answeredAlready(
- root: string,
+ log: LookLog,
key: {
readonly digest: string; readonly stretch: string; readonly clip: boolean;
/** Which element the answer was credited to, and what the observer was asked to limit itself to. */
readonly element: string; readonly scope: string;
},
-): Promise<ComparisonRecord | undefined> {
- const lines = (await readFile(join(root, "comparisons.jsonl"), "utf8").catch(() => "")).split("\n");
+): Promise<(ComparisonRecord & ReviewRecord) | undefined> {
+ const lines = (await readFile(join(log.root, log.file), "utf8").catch(() => "")).split("\n");
for (const line of lines.reverse()) {
if (line.trim().length === 0) continue;
- let record: ComparisonRecord;
- try { record = JSON.parse(line) as ComparisonRecord; } catch { continue; }
- if (record.status !== "complete" || record.differences === undefined) continue;
+ let record: ComparisonRecord & ReviewRecord;
+ try { record = JSON.parse(line) as ComparisonRecord & ReviewRecord; } catch { continue; }
+ if (record.status !== "complete" || record[log.answer] === undefined) continue;
if (record.image_digest !== key.digest) continue;
if (comparedStretch(record) !== key.stretch) continue;
if ((record.clip ?? false) !== key.clip) continue;
@@ -285,8 +389,11 @@ async function answeredAlready(
return undefined;
}
-/** What a comparison was put beside, named the way it was asked for. */
-function comparedStretch(record: Pick<ComparisonRecord, "shot_id" | "range">): string {
+/** What a look was made over, named the way it was asked for. */
+function comparedStretch(record: {
+ readonly shot_id?: string;
+ readonly range?: { readonly segment?: string; readonly selection?: string };
+}): string {
return record.shot_id
?? (record.range?.segment === undefined ? undefined : `segment:${record.range.segment}`)
?? (record.range?.selection === undefined ? undefined : `selection:${record.range.selection}`)
@@ -297,13 +404,13 @@ function comparedStretch(record: Pick<ComparisonRecord, "shot_id" | "range">): s
* Record the differences against the comparison that asked for them, and mark it answered.
*
* The log is append-only while a round runs, so closing an entry rewrites the file. That is a
- * read-modify-write over the same bytes `appendComparison` appends to, so both go through the same
+ * read-modify-write over the same bytes `appendLooked` appends to, so both go through the same
* queue — a round fired at once would otherwise drop whichever line landed between the read and the
* write. Returns false when no entry carries the id, which is what a mistyped one looks like.
*/
-async function closeComparison(root: string, id: string, differences: string): Promise<boolean> {
- return await serially(root, async () => {
- const path = join(root, "comparisons.jsonl");
+async function closeLooked(log: LookLog, id: string, text: string): Promise<boolean> {
+ return await serially(log.root, async () => {
+ const path = join(log.root, log.file);
const lines = (await readFile(path, "utf8").catch(() => "")).split("\n").filter((line) => line.trim().length > 0);
let found = false;
const rewritten = lines.map((line) => {
@@ -311,7 +418,7 @@ async function closeComparison(root: string, id: string, differences: string): P
try { record = JSON.parse(line) as ComparisonRecord; } catch { return line; }
if (record.id !== id) return line;
found = true;
- return JSON.stringify({ ...record, status: "complete", differences });
+ return JSON.stringify({ ...record, status: "complete", [log.answer]: text });
});
if (found) await writeFile(path, `${rewritten.join("\n")}\n`, "utf8");
return found;
@@ -479,11 +586,15 @@ const TILE_PREAMBLE = "Each supplied picture that shows a grid of frames is one
// There is no second source of sound to fall back to, so this says how to answer from what there is
// rather than leaving the observation short. The transcript settles when speech happens; the picture
// settles who is on screen while it does. Read together they carry the question far enough to answer.
+// The two fields are named rather than described: an instruction to use the transcript, given to a
+// reader with no way to find it, is answered without one.
const NO_SOUND = "You are reading pictures and cannot hear this reference. Answer from the pictures and"
+ " the measured transcript together: the transcript says exactly when words are spoken, and the"
- + " pictures say who is on screen and whose mouth is moving while they are. Attribute speech to the"
- + " person the pictures show speaking during the words the transcript places there, and answer the"
- + " question in full rather than deferring the parts that would be easier with sound.";
+ + " pictures say who is on screen and whose mouth is moving while they are. The words this task's own"
+ + " stretch contains are supplied as `transcript_words`, and the whole measured transcript is the file"
+ + " at `transcript_ref`. Attribute speech to the person the pictures show speaking during the words the"
+ + " transcript places there, and answer the question in full rather than deferring the parts that would"
+ + " be easier with sound.";
/** Declares one observation: what it asks, and the evidence it asks over. The observer decides how. */
type Request = {
@@ -492,6 +603,14 @@ type Request = {
readonly instruction: string;
/** True when answering needs sound. The `agent` observer has none and is told to say so. */
readonly sound?: boolean;
+ /**
+ * The shots this question is asked over, when it is asked over shots rather than the whole video.
+ *
+ * Only a sound question reads it, and only on the observer that cannot hear: it is what narrows the
+ * measured transcript to the words this task's own stretch contains. A question over the whole
+ * reference leaves it unset and is given the whole transcript instead.
+ */
+ readonly shots?: readonly Shot[];
};
type Asker = (key: string, request: Request) => Promise<Observation>;
@@ -765,6 +884,19 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
return state;
};
+ /**
+ * What paces a round of work.
+ *
+ * The launch gap and the concurrency cap are a vendor's quota, so they belong to the observer that
+ * sends requests and to nothing else. The observer that answers out of band reaches no Provider:
+ * building a list of tasks is local and unbounded, and cutting a comparison's frames is local but
+ * costs a decode, so it is paced by the machine rather than by a gap invented for someone's API.
+ */
+ const rateFor = (observer: Observer, work: "listing" | "ffmpeg", items: number) =>
+ observer !== "agent" ? { concurrency, gapMs }
+ : work === "ffmpeg" ? { concurrency: Math.max(1, Math.min(cpus().length - 1, items)), gapMs: 0 }
+ : { concurrency: Number.MAX_SAFE_INTEGER, gapMs: 0 };
+
// One reference is read by one observer throughout. Mixing them inside a single reference would
// leave observations of two different kinds of evidence under the same keys, with nothing on the
// record saying which is which, so the choice is made once at prepare and carried in the state.
@@ -774,18 +906,35 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
): Promise<{ readonly ask: Asker; readonly pending: readonly ObservationTaskRequest[]; readonly paced?: boolean }> => {
if (observer === "agent") {
const pending: ObservationTaskRequest[] = [];
+ // The transcript's path is fixed by the reference, so it can be named before the file exists.
+ // It has to be: `prepare_reference` builds its four tasks while WhisperX is still measuring
+ // beside them, and one of those four is a sound question. By the time the observer opens it,
+ // that call has returned and the file is written.
+ const transcriptRef = join(stateRoot(state.reference_id), "transcript.json");
+ // Read once for the whole pass rather than per task. Absent during prepare, and absent for good
+ // on a silent reference: a task then carries the pictures alone, which is what it had before.
+ const words = await referenceWords(state.reference_id).catch(() => []);
return {
pending,
// Pacing is for a quota. This asker does no I/O — it appends to an array — so holding each
// task to the launch gap spent minutes producing a list.
paced: false,
- ask: async (key, { media, prompt, instruction, sound }) => {
+ ask: async (key, { media, prompt, instruction, sound, shots }) => {
// An observation reads grids of one shot each, which is what the preamble describes. A
// comparison holds one grid of a render and one of a stretch that may cut several times, so
// it says how to read its own pair and the preamble would contradict it.
const parts = key.startsWith("comparison:")
? [] : sound === true ? [TILE_PREAMBLE, NO_SOUND] : [TILE_PREAMBLE];
- pending.push({ key, instruction, prompt: [...parts, prompt].join("\n\n"), image_refs: asPictures(media, state) });
+ // A word counts as inside the stretch when it overlaps it at all, so one straddling either
+ // end is carried rather than dropped: it is spoken over the pictures this task holds.
+ const spoken = sound !== true || shots === undefined || shots.length === 0 ? "" : words
+ .filter((word) => shots.some((shot) => word.endSeconds > shot.start_seconds && word.startSeconds < shot.end_seconds))
+ .map((word) => word.text).join(" ");
+ pending.push({
+ key, instruction, prompt: [...parts, prompt].join("\n\n"), image_refs: asPictures(media, state),
+ ...(sound === true && words.length > 0 ? { transcript_ref: transcriptRef } : {}),
+ ...(spoken.length === 0 ? {} : { transcript_words: spoken }),
+ });
return observation("pending", "awaiting the agent observer");
},
};
@@ -983,7 +1132,8 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
if (input.questions !== undefined) {
const round = input.questions;
assert(round.length > 0, "questions is empty");
- const answers = await pacedMap(round, concurrency, gapMs, async (asked) => {
+ const batchRate = rateFor((await loadState(input.reference_id)).observer ?? "gemini", "listing", round.length);
+ const answers = await pacedMap(round, batchRate.concurrency, batchRate.gapMs, async (asked) => {
try {
return { ok: true as const, value: await tools.observe_reference({
reference_id: input.reference_id, shot_ids: asked.shot_ids, question: asked.question,
@@ -1015,18 +1165,32 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
if (question.length > 0) {
assert(input.shot_ids !== undefined && input.shot_ids.length > 0, "question requires at least one shot id, so that it is answered from the shots it is about");
assert(selected.length <= 3, "question accepts at most three shots");
- // Keyed by the shots it is asked over, so the observer that answers out of band has a key it
- // can record against. Asked under a bare `question` the task was handed out and the answer had
- // nowhere to go, which left the documented way of repairing bad evidence unusable on that path.
- const key = `question:${selected.map((shot) => shot.shot_id).join("+")}`;
- const answer = await ask(key, {
- media: selected.flatMap((shot) => [shot.clip_ref, shot.representative_frame_ref]),
- // A narrow question is as likely to be about who is speaking as about what is on screen, and
- // this is the one prompt where the observer reading pictures was not told it cannot hear.
- sound: true,
- prompt: question,
- instruction: "Answer only the narrow reference-video question in natural language. Do not write code, markup, SVML, or component names.",
- });
+ // Keyed by the shots it is asked over and by the question itself, so the observer that answers
+ // out of band has a key it can record against and a second, different question over the same
+ // shots gets its own. Keyed on the shots alone, the two would share an entry and the later one
+ // would be answered with the earlier one's text.
+ const key = `question:${selected.map((shot) => shot.shot_id).join("+")}:${createHash("sha256").update(question).digest("hex").slice(0, 8)}`;
+ const path = join(state.root, "observations.json");
+ const held = (await readJson<Record<string, Observation>>(path))?.[key];
+ const reused = held?.status === "complete" && input.reobserve !== true;
+ // Through the same cache the sweep uses, rather than straight to the asker. Asked directly, an
+ // answer recorded against this key was written to a file nothing read: the observer that
+ // answers out of band could never retrieve one, and the observer that bills was asked again.
+ const answers = await runObservationTasks(
+ state.root,
+ [{ key, request: {
+ media: selected.flatMap((shot) => [shot.clip_ref, shot.representative_frame_ref]),
+ // A narrow question is as likely to be about who is speaking as about what is on screen, and
+ // this is the one prompt where the observer reading pictures was not told it cannot hear.
+ sound: true,
+ shots: selected,
+ prompt: question,
+ instruction: "Answer only the narrow reference-video question in natural language. Do not write code, markup, SVML, or component names.",
+ } }],
+ input.reobserve === true ? new Set([key]) : new Set<string>(),
+ rate.concurrency, rate.gapMs, ask,
+ );
+ const answer = answers.get(key)!;
return {
reference_id: state.reference_id,
observer,
@@ -1034,6 +1198,9 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
question,
observation_key: key,
answer,
+ // Says the answer came back without asking anyone, so a reader knows they were not billed
+ // for it and that `--reobserve` is what asks again.
+ ...(reused ? { reused: true } : {}),
unresolved: answer.status === "complete" ? [] : [key],
pending_observations: pending,
};
@@ -1084,6 +1251,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
return { key: `audio:${shot.shot_id}`, request: {
media: [shot.clip_ref, ...(previous?.audio_tail_ref == null ? [] : [previous.audio_tail_ref])],
sound: true,
+ shots: [shot],
prompt: `${globalContext}\n\nListen to shot ${shot.index}. Decide who is speaking, whether sound continues from the previous shot, whether visible people actually produce the sound, and whether a silent B-roll person only appears to speak. Handle off-screen, alternating, overlapping, and no-person-visible speech. Return natural language evidence only.`,
instruction: "Observe sound only. Do not write markup, SVML, JSON plans, or component names.",
} };
@@ -1095,6 +1263,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
return { key: `boundary:${right.shot_id}`, request: {
media: [left.clip_ref, right.clip_ref, left.tail_frame_ref],
sound: true,
+ shots: [left, right],
prompt: `Compare shots ${left.index} and ${right.index}, which meet at one cut. Answer two questions separately, each under its own heading.\n\nContinuous camera shot: are these one continuous camera shot, or two? Explain the visual and sound continuity evidence.\n\nOverlay continuity: does the same visible overlay or inserted picture continue across the boundary, change, or end? Explain the evidence.\n\nReturn natural language evidence only.`,
instruction: "Analyze what happens at one cut. Do not name SVML components or write code.",
} };
@@ -1138,6 +1307,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
// with sound. This asks the same question over three shots, so an observer reading pictures
// is told the same thing about what it is missing.
sound: true,
+ shots: items,
prompt: `Compare shots ${items[0].index}, ${items[1].index}, and ${items[2].index}. Decide whether the three clips are one continuous camera shot and whether one visual overlay or insert persists through both boundaries. Explain the evidence in natural language only.`,
instruction: "Analyze a three-shot continuity window only. Do not write markup, SVML, JSON plans, or component names.",
},
@@ -1294,7 +1464,10 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
if (input.comparisons !== undefined) {
const batch = input.comparisons;
assert(batch.length > 0, "comparisons is empty");
- const results = await pacedMap(batch, concurrency, gapMs, async (one) => {
+ // Each entry cuts and tiles its own two sides, so on the observer that answers out of band
+ // this round is ffmpeg work rather than a queue of requests.
+ const batchRate = rateFor((await loadState(input.reference_id)).observer ?? "gemini", "ffmpeg", batch.length);
+ const results = await pacedMap(batch, batchRate.concurrency, batchRate.gapMs, async (one) => {
const merged = { reference_id: input.reference_id, ...one };
// One comparison that throws — an unreadable render, a Selection the Script does not mark —
// takes only itself down. The rest of the list is what the caller came for.
@@ -1386,6 +1559,19 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
}
const asClip = clip && !bothStill;
+ // A shot is compared at its own length on either observer. `--shot-id` takes the reference's cut
+ // whole rather than cutting it to a word range, so nothing else lines the two sides up: a render
+ // of a different length puts more or less of the video beside it, and whatever the pair shows,
+ // it is not one stretch seen twice. The word-range path is held to the same tolerance inside
+ // `cutWordRange`; this is the path that had no check at all.
+ if (asClip && shot !== undefined) {
+ const drawn = await probe(renderedPath);
+ const slack = drawn.frameRate > 0 ? 3 / drawn.frameRate : 0.1;
+ assert(Math.abs(drawn.duration - shot.duration_seconds) <= slack,
+ `shot ${shot.shot_id} runs ${round(shot.duration_seconds)}s and the render ${round(drawn.duration)}s, `
+ + `which is more than ${round(slack)}s apart; the two sides would cover different amounts of the video`);
+ }
+
// A clip comparison reads the whole stretch on both sides. The observer that reads video is
// given the two clips; the observer that reads pictures is given two frame tiles, which is the
// same degradation `prepare_reference` already applies to a shot. Tiling both against the same
@@ -1401,16 +1587,6 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
if (shot !== undefined) {
assert(shot.frames_tile_ref !== null,
`shot ${shot.shot_id} has no frame tile; re-prepare the reference with --redo all --observer agent`);
- // The reference's grid was drawn across the shot's own duration, so a render of a different
- // length sampled against that duration is a grid of different moments: a longer render loses
- // its tail entirely and a shorter one leaves black cells the observer reads as a difference.
- // The word-range path is held to the same tolerance by `cutWordRange`.
- const drawn = await probe(renderedPath);
- const slack = drawn.frameRate > 0 ? 3 / drawn.frameRate : 0.1;
- assert(Math.abs(drawn.duration - shot.duration_seconds) <= slack,
- `shot ${shot.shot_id} runs ${round(shot.duration_seconds)}s and the render ${round(drawn.duration)}s, `
- + `which is more than ${round(slack)}s apart; both grids are sampled across the shot's duration, `
- + "so they would show different moments");
referenceMedia = shot.frames_tile_ref;
const tileTarget = join(root, "comparisons", `shot-${shot.shot_id}`, slot, "reconstruction.jpg");
await ensureDir(dirname(tileTarget));
@@ -1441,7 +1617,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
.digest("hex").slice(0, 6)}`;
// Nothing changed since this pair was last answered, so nothing new can be said about it.
const digest = await fileDigest(renderedPath);
- const already = await answeredAlready(root, {
+ const already = await answeredAlready(comparisonLog(root), {
digest,
stretch: comparedStretch({ ...(shot === undefined ? {} : { shot_id: shot.shot_id }), ...(cut === undefined ? {} : { range: cut.record }) }),
clip: asClip,
@@ -1476,7 +1652,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
// What was compared, and what was seen. The record is what a gate reads to tell an element that
// was looked at from one that never was, and what an identical pair is answered from without
// asking again.
- await appendComparison(root, {
+ await appendLooked(comparisonLog(root), {
at: startedAt,
id: comparisonId,
...(shot === undefined ? {} : { shot_id: shot.shot_id }),
@@ -1540,14 +1716,17 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
// observation cache: the log is what a gate reads to tell an element that was looked at from one
// that never was, and until this existed an agent-observer comparison could never leave `pending`.
if (key.startsWith("comparison:")) {
- const closed = await closeComparison(root, key.slice("comparison:".length), text);
+ const closed = await closeLooked(comparisonLog(root), key.slice("comparison:".length), text);
assert(closed, `${key} names no open comparison of reference ${input.reference_id}`);
return { reference_id: state.reference_id, key, stored_in: "comparisons" };
}
const shotKeys = new Set(state.shots.flatMap((shot) => [`visual:${shot.shot_id}`, `type:${shot.shot_id}`, `audio:${shot.shot_id}`, `boundary:${shot.shot_id}`, `window:${shot.shot_id}`]));
- // A narrow question is asked over one to three shots and keyed by them, so its key is built the
- // same way `observe_reference` built it rather than enumerated here.
- const questionKey = /^question:([0-9a-z]+(?:\+[0-9a-z]+)*)$/u.exec(key);
+ // A narrow question is asked over one to three shots and keyed by them and by a digest of the
+ // question, so its key is matched the same way `observe_reference` builds it rather than
+ // enumerated here. A shot id is `shot-001`: the hyphen belongs in the class, and leaving it out
+ // rejected every key this tool actually produces, so an answer to a narrow question had nowhere
+ // to go on the one observer that has to record its answers by hand.
+ const questionKey = /^question:([0-9a-z-]+(?:\+[0-9a-z-]+)*):[0-9a-f]{8}$/u.exec(key);
const knownShots = new Set(state.shots.map((shot) => shot.shot_id));
const askedOver = questionKey?.[1]!.split("+") ?? [];
const isQuestion = questionKey !== null && askedOver.length <= 3 && askedOver.every((id) => knownShots.has(id));
@@ -1563,8 +1742,153 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
return { reference_id: state.reference_id, key, stored_in: "observations" };
},
+ async review_element(input): Promise<Record<string, unknown>> {
+ const runPath = resolve(invokedFrom(), input.run);
+ const root = dirname(reviewLogPath(runPath));
+ await ensureDir(root);
+
+ if (input.reviews !== undefined) {
+ const batch = input.reviews;
+ assert(batch.length > 0, "reviews is empty");
+ // Local work throughout — a decode per entry and no request anywhere — so it is paced by the
+ // machine, the way `render_element` is.
+ const atOnce = Math.max(1, Math.min(cpus().length - 1, batch.length));
+ const results = await pacedMap(batch, atOnce, 0, async (one) => {
+ const merged = { ...one, run: input.run };
+ try { return { ok: true as const, value: await tools.review_element(merged) }; }
+ catch (error) { return { ok: false as const, error: error instanceof Error ? error.message : String(error), input: merged }; }
+ });
+ const done = results.filter((item) => item.ok).map((item) => item.value!);
+ const failed = results.filter((item) => !item.ok);
+ return {
+ run: runPath,
+ reviewed: done.length,
+ failed: failed.length,
+ reviews: done,
+ ...(failed.length === 0 ? {} : { failures: failed.map((item) => ({ error: item.error, input: item.input })) }),
+ };
+ }
+
+ const element = input.element?.trim() ?? "";
+ assert(element.length > 0, "--element is required; a review with no element is credited to nothing");
+ const named = [input.segment, input.selection].filter((value) => value !== undefined);
+ assert(named.length === 1, "name exactly one of --segment or --selection: the window the render covers");
+ const supplied = [input.image_path, input.video_path].filter((value) => value !== undefined);
+ assert(supplied.length === 1, "supply exactly one of --image or --video");
+
+ const intent = (input.intent ?? (input.intent_file === undefined
+ ? undefined
+ : await readFile(resolve(invokedFrom(), input.intent_file), "utf8")))?.trim() ?? "";
+ assert(intent.length > 0,
+ "--intent-file is required: what this element was asked to be, in the words the brief was taken in. "
+ + "Without it the question is whether the picture looks acceptable, which it always does to whoever drew it.");
+
+ const renderedPath = resolve(invokedFrom(), input.video_path ?? input.image_path!);
+ await stat(renderedPath).catch(() => { throw new Error(`cannot read ${renderedPath}`); });
+ const slot = `${basename(renderedPath).replace(/\.[^.]+$/u, "")}-${createHash("sha256").update(renderedPath).digest("hex").slice(0, 8)}`;
+ const standIn = await standInBeside(renderedPath);
+ const scope = input.question?.trim() ?? "";
+ const startedAt = new Date().toISOString();
+
+ // The reader looks at pictures, so a clip becomes a grid of its own frames. With no reference
+ // beside it there is no second side to match, so the render's own duration and width decide the
+ // sampling — and its own stillness decides whether there is anything to sample at all.
+ let picture = renderedPath;
+ let asClip = false;
+ if (input.video_path !== undefined) {
+ const drawn = await probe(renderedPath);
+ asClip = !(await completelyStill(renderedPath));
+ const target = join(root, "reviews", slot, asClip ? "element.jpg" : "element-still.jpg");
+ await ensureDir(dirname(target));
+ picture = asClip
+ ? await shotTile(renderedPath, drawn.duration, target, Math.min(480, drawn.width))
+ : await cutFrame(renderedPath, drawn.duration / 2, target);
+ }
+
+ const digest = await fileDigest(renderedPath);
+ const stretch = comparedStretch({ range: { ...(input.segment === undefined ? {} : { segment: input.segment }), ...(input.selection === undefined ? {} : { selection: input.selection }) } });
+ // Nothing about the picture or the question changed since this was last answered, so nothing new
+ // can be said about it. Here this is what bounds the looking: a review costs no vendor money, so
+ // without it a round could re-ask the same picture until it liked the answer.
+ const already = await answeredAlready(reviewLog(root), { digest, stretch, clip: asClip, element, scope });
+ if (already !== undefined) {
+ return {
+ run: runPath, element, ...(input.segment === undefined ? {} : { segment: input.segment }),
+ ...(input.selection === undefined ? {} : { selection: input.selection }),
+ reviewed: asClip ? "clip" : "still",
+ reused: { answered_at: already.at, review_id: already.id, findings: already.findings },
+ };
+ }
+
+ const reviewId = `${slot}-${createHash("sha256").update(`${slot}|${stretch}|${startedAt}`).digest("hex").slice(0, 6)}`;
+ const unit = asClip ? "grid of frames sampled evenly across the stretch, laid out in reading order: left to right, then top to bottom" : "still picture";
+ const record: ReviewRecord = {
+ at: startedAt, id: reviewId, element,
+ range: { ...(input.segment === undefined ? {} : { segment: input.segment }), ...(input.selection === undefined ? {} : { selection: input.selection }) },
+ image_path: renderedPath, image_digest: digest, status: "pending",
+ ...(scope.length === 0 ? {} : { scope }), clip: asClip,
+ ...(standIn === undefined ? {} : { stand_in: standIn }),
+ intent,
+ };
+ await appendLooked(reviewLog(root), record);
+
+ return {
+ run: runPath, element,
+ ...(input.segment === undefined ? {} : { segment: input.segment }),
+ ...(input.selection === undefined ? {} : { selection: input.selection }),
+ review_id: reviewId,
+ reviewed: asClip ? "clip" : "still",
+ ...(standIn === undefined ? {} : { stand_in: standIn }),
+ pending_reviews: [{
+ key: `review:${reviewId}`,
+ instruction: "You are given one picture of a rendered video element and a written description of what it"
+ + " was asked to be. Report whether the picture matches the description, and every visible defect."
+ + " You are not told how it was produced. Do not write code, markup, SVML, component names, or"
+ + " production advice.",
+ prompt: `The picture is one ${unit}.\n\n`
+ + `What this element was asked to be:\n\n${intent}\n\n`
+ + (scope.length === 0 ? "" : `Read only this part of the picture: ${scope}\n\n`)
+ // Said by the tool rather than left to be retyped each round: on this route nobody is
+ // billed to look and the mocks are not the author's business, so there is no reason to
+ // make it something a caller can forget.
+ + "Flat-filled regions stand in for pictures that have not been generated yet. Ignore what they"
+ + " contain and read only what is drawn over them.\n\n"
+ + "Answer two things, each under its own heading.\n\n"
+ + "Matches the description: state which parts of the description the picture satisfies and which"
+ + " it does not. Name anything the description asks for that is not there, and anything present"
+ + " that the description does not mention.\n\n"
+ + "Visible defects: report each of these you can see, and say it is absent when you cannot."
+ + " Anything cut off by the edge of the frame or reaching past it. Anything overlapping or"
+ + " covering something else that is meant to be read. Anything whose position or alignment"
+ + " against the edges of the frame looks unintended. Text or marks too low in contrast against"
+ + " what is behind them to read."
+ + (asClip ? " Anything that appears, moves or leaves in a way the description does not account for." : "")
+ + "\n\nMeasure what you can against the frame's own width and height rather than in pixels."
+ + " Return natural language only.",
+ image_refs: [picture],
+ }],
+ record_with: `record_review --run ${runPath} --review-id ${reviewId} --text-file <the findings>`,
+ unresolved: [`review:${reviewId}`],
+ };
+ },
+
+ // The findings come back out of band, the way an observation's do: whoever looked at the picture
+ // did it somewhere else and returns text. This is where that text lands, and until it does the
+ // review has been drawn and handed over with nobody having said what it shows.
+ async record_review(input): Promise<Record<string, unknown>> {
+ const runPath = resolve(invokedFrom(), input.run);
+ const root = dirname(reviewLogPath(runPath));
+ const id = input.review_id.trim().replace(/^review:/u, "");
+ assert(id.length > 0, "review_id is required");
+ const text = input.text.trim();
+ assert(text.length > 0, "text is required; a review that found nothing wrong says so in words");
+ const closed = await closeLooked(reviewLog(root), id, text);
+ assert(closed, `${id} names no open review of ${runPath}`);
+ return { run: runPath, review_id: id, stored_in: reviewLogPath(runPath) };
+ },
+
// A media slot that is declared as a generation is not fillable by this route, which never
- // Builds. The comparison loop still needs a still to compare, so the slot is mocked with a
+ // Builds. The comparison round still needs a still to compare, so the slot is mocked with a
// fixed, correctly-sized placeholder — the same tool on every run, never a real generation and
// never a script the agent writes by hand.
async make_placeholder(input): Promise<Record<string, unknown>> {
@@ -1610,7 +1934,11 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
},
async reconstruction_check(input): Promise<Record<string, unknown>> {
- return await reconstructionCheck(input, { packageRoot });
+ return await authoringCheck({ ...input, mode: "reconstruction" }, { packageRoot });
+ },
+
+ async authoring_check(input): Promise<Record<string, unknown>> {
+ return await authoringCheck({ ...input, mode: "description" }, { packageRoot });
},
};
return tools;
diff --git a/packages/reference-video-tools/src/types.ts b/packages/reference-video-tools/src/types.ts
index c17d8f0f..a636a39a 100644
--- a/packages/reference-video-tools/src/types.ts
+++ b/packages/reference-video-tools/src/types.ts
@@ -65,6 +65,17 @@ export type ObservationTaskRequest = {
readonly instruction: string;
readonly prompt: string;
readonly image_refs: readonly string[];
+ /**
+ * The measured words, for a task whose question needs sound.
+ *
+ * WhisperX runs locally on both paths, so the words and their times are the one piece of evidence
+ * this observer has that its pictures do not carry, and the prompt for such a task tells it to
+ * answer from the two together. Naming the file here is what makes that instruction followable:
+ * `transcript_words` is what the transcript places inside this task's own stretch, and
+ * `transcript_ref` is the whole file for a question asked over the whole reference.
+ */
+ readonly transcript_ref?: string;
+ readonly transcript_words?: string;
};
export type ReferenceState = {
diff --git a/packages/reference-video-tools/test/tools.test.ts b/packages/reference-video-tools/test/tools.test.ts
index fdca408e..30fadc10 100644
--- a/packages/reference-video-tools/test/tools.test.ts
+++ b/packages/reference-video-tools/test/tools.test.ts
@@ -155,18 +155,26 @@ test("a second observation reuses the cache and only an explicit reobserve runs
assert.equal(forced.length, 4, "reobserve reruns the selected shot's picture, type and sound plus its one boundary, and nothing else");
});
-test("a narrow question costs one call, answers from the named shots and never re-runs observations", async () => {
- const { stateRoot } = await workspace(4);
+test("a narrow question costs one call, answers from the named shots and is answered once", async () => {
+ await workspace(4);
const calls: Call[] = [];
- const result = await tools(calls, "the caption sits above the lower edge")
- .observe_reference({ reference_id: REFERENCE, shot_ids: ["shot-003"], question: "How thick is the caption outline?" });
+ const api = tools(calls, "the caption sits above the lower edge");
+ const result = await api.observe_reference({ reference_id: REFERENCE, shot_ids: ["shot-003"], question: "How thick is the caption outline?" });
assert.equal(calls.length, 1);
assert.deepEqual(calls[0]!.mimeTypes, ["video/mp4", "image/jpeg"]);
assert.equal(calls[0]!.text, "How thick is the caption outline?");
assert.deepEqual(result["shot_ids"], ["shot-003"]);
assert.deepEqual(result["answer"], { status: "complete", text: "the caption sits above the lower edge" });
- assert.equal(await readFile(join(stateRoot, "observations.json"), "utf8"), "{}\n");
+
+ // The key carries the question as well as the shots, so a second question over the same shot is a
+ // separate entry rather than the first one's answer handed back under a shared key.
+ const repeated = await api.observe_reference({ reference_id: REFERENCE, shot_ids: ["shot-003"], question: "How thick is the caption outline?" });
+ assert.equal(calls.length, 1, "asking the same question again reads the answer rather than paying for a paraphrase");
+ assert.equal(repeated["reused"], true);
+ const different = await api.observe_reference({ reference_id: REFERENCE, shot_ids: ["shot-003"], question: "What colour is the background?" });
+ assert.equal(calls.length, 2, "a different question over the same shot is a different question");
+ assert.notEqual(different["observation_key"], repeated["observation_key"]);
await assert.rejects(
tools([]).observe_reference({ reference_id: REFERENCE, question: "which shot?" }),
@@ -176,6 +184,24 @@ test("a narrow question costs one call, answers from the named shots and never r
/at most three shots/u);
});
+test("the key a narrow question is handed out under is one record_observation accepts", async () => {
+ // A shot id is `shot-003`, and the key that names it was being matched by a pattern with no hyphen
+ // in its class — so every real narrow-question key was refused, and the observer that has to record
+ // its own answers had nowhere to put one.
+ await workspace(4);
+ const api = createReferenceVideoTools({ concurrency: 4, launchGapMs: 0, retryDelayMs: 0, generate: async () => "" });
+ const state = JSON.parse(await readFile(join(process.env["HYPIT_REPOSITORY"]!, ".hypit", "reference-video-tools", REFERENCE, "state.json"), "utf8")) as ReferenceState;
+ await writeFile(join(state.root, "state.json"), `${JSON.stringify({ ...state, observer: "agent" }, null, 2)}\n`, "utf8");
+
+ const asked = await api.observe_reference({ reference_id: REFERENCE, shot_ids: ["shot-003"], question: "How thick is the caption outline?" });
+ const key = (asked["pending_observations"] as readonly { readonly key: string }[])[0]!.key;
+ const stored = await api.record_observation({ reference_id: REFERENCE, key, text: "two pixels" });
+ assert.equal(stored["stored_in"], "observations");
+
+ const again = await api.observe_reference({ reference_id: REFERENCE, shot_ids: ["shot-003"], question: "How thick is the caption outline?" });
+ assert.deepEqual(again["answer"], { status: "complete", text: "two pixels" });
+});
+
test("reconstruction comparison sends an unlabelled pair and accepts rendered PNG frames", async () => {
const { root } = await workspace(1);
const rendered = join(root, "rendered.png");
diff --git a/test/hypit-skill-reachability.mjs b/test/hypit-skill-reachability.mjs
new file mode 100644
index 00000000..00bf4ad8
--- /dev/null
+++ b/test/hypit-skill-reachability.mjs
@@ -0,0 +1,329 @@
+/**
+ * What a reader of the hypit skill can still reach, as a set of sentences.
+ *
+ * Editing the skill means moving prose between files: a passage two routes both need is written
+ * once and linked from both, and a passage filed under one route is moved to a shared file. Every
+ * one of those edits is supposed to be invisible to a reader — they follow a link instead of
+ * reading on, and arrive at the same words. Checking that the links resolve does not check that.
+ * A link resolves perfectly to a file that lost a clause on the way in.
+ *
+ * So the unit here is the sentence, not the file and not the link. Two runs of `--route` are
+ * comparable with `comm`, and a sentence that was reachable before and is not reachable now is a
+ * loss wherever it used to live. Which file a sentence sits in is deliberately not part of the
+ * key: a move is meant to score as a no-op.
+ *
+ * One detail decides whether any of this works. The skill's prose is hard-wrapped at about 100
+ * columns, so a sentence is routinely split across two lines and any line-based comparison sees
+ * two halves rather than one sentence. `grep -rn "never inspected is a system"` finds three files;
+ * there are four. That is the failure this tool exists to make impossible, and it is why
+ * normalization collapses a paragraph's newlines before it splits on sentence ends.
+ *
+ * node test/hypit-skill-reachability.mjs --route reconstruction
+ * node test/hypit-skill-reachability.mjs --at HEAD --route description
+ * node test/hypit-skill-reachability.mjs --links
+ * node test/hypit-skill-reachability.mjs --orphans
+ * node test/hypit-skill-reachability.mjs --restatements [--threshold 0.45]
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync, readdirSync } from "node:fs";
+import { dirname, join, posix, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repositoryRoot = fileURLToPath(new URL("../", import.meta.url));
+const skillRoot = ".agents/skills/hypit";
+
+/** A path in one of these is written from the repository root; anything else is relative to its file. */
+const rootRelativePrefixes = ["docs/", "examples/", "packages/", "services/", "test/"];
+
+/**
+ * Where each route starts reading, and where it stops.
+ *
+ * Both begin at `SKILL.md`, because that is what routes the task. But `SKILL.md` names both route
+ * files, so a traversal that followed every link from it would reach the whole skill twice and the
+ * two routes would come back identical — which is exactly the question this tool is asked. Each
+ * route therefore refuses to enter the other's directory, and that refusal is the property under
+ * test: a passage filed under `reconstruction/` is a passage the description route cannot read,
+ * which is the defect the moves in this change are for.
+ */
+const routes = {
+ reconstruction: {
+ roots: [`${skillRoot}/SKILL.md`, `${skillRoot}/references/reconstruction/route.md`],
+ closed: `${skillRoot}/references/original-authoring/`,
+ },
+ description: {
+ roots: [`${skillRoot}/SKILL.md`, `${skillRoot}/references/original-authoring/route.md`],
+ closed: `${skillRoot}/references/reconstruction/`,
+ },
+};
+
+/**
+ * Reads a file as of a commit, or from the working tree when `at` is undefined.
+ *
+ * Reading the baseline through `git show` rather than from a copy on disk is what keeps the
+ * baseline from drifting: there is no second tree to forget to refresh, and the comparison is
+ * always against a named commit rather than against whatever was captured at some earlier moment.
+ */
+function read(path, at) {
+ try {
+ if (at === undefined) return readFileSync(join(repositoryRoot, path), "utf8");
+ // A path that does not exist at that commit is an answer, not an error: `--links` asks exactly
+ // that question. `git show` says so on stderr, which would otherwise interleave with the report.
+ return execFileSync("git", ["show", `${at}:${path}`], { cwd: repositoryRoot, encoding: "utf8", maxBuffer: 64 * 1024 * 1024, stdio: ["ignore", "pipe", "ignore"] });
+ } catch {
+ return null;
+ }
+}
+
+/** Every `.md` under the skill, as repository-relative paths. */
+function everySkillFile(at) {
+ if (at === undefined) {
+ const found = [];
+ const visit = (directory) => {
+ for (const entry of readdirSync(join(repositoryRoot, directory), { withFileTypes: true })) {
+ const child = posix.join(directory, entry.name);
+ if (entry.isDirectory()) visit(child);
+ else if (entry.name.endsWith(".md")) found.push(child);
+ }
+ };
+ visit(skillRoot);
+ return found.sort();
+ }
+ const listed = execFileSync("git", ["ls-tree", "-r", "--name-only", at, "--", skillRoot], { cwd: repositoryRoot, encoding: "utf8" });
+ return listed.split("\n").filter((line) => line.endsWith(".md")).sort();
+}
+
+/**
+ * Where a backticked path in `from` points.
+ *
+ * Two conventions are in use and telling them apart is not cosmetic. A path under `docs/`,
+ * `packages/`, `services/`, `examples/` or `test/` names a place in the repository; everything else
+ * names a file beside the one doing the linking. Resolving both the same way produces a dozen
+ * reports of which most are the scanner misreading the convention, and the two real breaks are
+ * lost among them.
+ */
+function resolveLink(from, target) {
+ if (rootRelativePrefixes.some((prefix) => target.startsWith(prefix))) return target;
+ return posix.normalize(posix.join(posix.dirname(from), target));
+}
+
+const linkPattern = /`([^`\n]+\.md)`/g;
+
+/** `packages/<name>/README.md` names the shape of a path, not a path. Angle brackets mark the difference. */
+const isTemplate = (target) => target.includes("<");
+
+function linksIn(text, from) {
+ const found = new Set();
+ for (const match of text.matchAll(linkPattern)) {
+ if (isTemplate(match[1])) continue;
+ found.add(resolveLink(from, match[1]));
+ }
+ return [...found];
+}
+
+/**
+ * The files one route can reach.
+ *
+ * `playbooks/` is added wholesale rather than followed link by link. `playbooks/index.md` routes to
+ * a format by name and a route reads whichever one fits, so which craft files a given run reaches
+ * depends on the video rather than on the route. Treating them all as reachable from both routes
+ * keeps that choice from showing up as a difference between two runs of this tool.
+ */
+function reachable(route, at) {
+ const { roots, closed } = routes[route];
+ const seen = new Set();
+ const queue = [...roots];
+ while (queue.length > 0) {
+ const path = queue.shift();
+ if (seen.has(path) || path.startsWith(closed)) continue;
+ const text = read(path, at);
+ if (text === null) continue;
+ seen.add(path);
+ for (const link of linksIn(text, path)) if (!seen.has(link)) queue.push(link);
+ }
+ for (const path of everySkillFile(at)) if (path.startsWith(`${skillRoot}/references/playbooks/`)) seen.add(path);
+ return [...seen].sort();
+}
+
+const fence = /^```/;
+
+/**
+ * A fenced block as one comparable unit.
+ *
+ * The content is kept whole rather than split into sentences — a command is not prose, and a flag
+ * that changed is a different command. Only whitespace is collapsed, so a block reflowed across
+ * different lines still matches: where the line breaks fall in a shell invocation is layout, and
+ * reporting that as a loss would bury the changes that are not.
+ */
+function flattenBlock(lines) {
+ return `code:${lines.join(" ").replace(/\s+/gu, " ").trim()}`;
+}
+
+/**
+ * A file's comparable units: its fenced blocks whole, and its prose as sentences.
+ *
+ * A fenced block is compared byte for byte because a command is not prose — a flag that changed is
+ * a different command, and splitting one into sentences would compare it on the wrong axis. The
+ * prose either side of it is unwrapped first, so a sentence the file broke across two lines is one
+ * unit again.
+ *
+ * Short units are dropped. Below about forty characters the population is headings, table cells and
+ * fragments like "One line is enough", which collide across files that have nothing to do with each
+ * other and would report a loss every time an unrelated heading was reworded.
+ */
+function unitsIn(text) {
+ const units = [];
+ const lines = text.split("\n");
+ const prose = [];
+ let block = null;
+
+ for (const line of lines) {
+ if (fence.test(line)) {
+ if (block === null) block = [];
+ else { units.push(flattenBlock(block)); block = null; }
+ continue;
+ }
+ if (block !== null) block.push(line);
+ else prose.push(line);
+ }
+ if (block !== null) units.push(flattenBlock(block));
+
+ for (const paragraph of prose.join("\n").split(/\n\s*\n/)) {
+ const flat = paragraph
+ // A list marker is layout, not content, and it has to come off every line rather than only the
+ // first: a bullet list is one paragraph, so after the unwrap the second bullet onward would keep
+ // its dash inline and stop matching the same sentence written as prose. Moving a rule out of a
+ // list and into a paragraph is exactly the edit this file exists to prove safe.
+ .replace(/^[\s>]*(?:[-*+]|#+)\s+/gmu, "")
+ .replace(/\s+/gu, " ") // the unwrap: a hard-wrapped sentence becomes one string
+ .replace(/[`*_]/gu, "")
+ .trim();
+ if (flat.length === 0) continue;
+ for (const sentence of flat.split(/(?<=[.!?])\s+/u)) {
+ const unit = sentence.trim().toLowerCase();
+ if (unit.length >= 40) units.push(unit);
+ }
+ }
+ return units;
+}
+
+function unitsForRoute(route, at) {
+ const lines = [];
+ for (const path of reachable(route, at)) {
+ const text = read(path, at);
+ if (text === null) continue;
+ // Tab-separated so `cut -f1` isolates the unit. A pipe would not: the prose uses it in tables.
+ for (const unit of unitsIn(text)) lines.push(`${unit}\t${path}`);
+ }
+ return lines;
+}
+
+/** Word trigrams, for asking whether two units say the same thing in different words. */
+function trigrams(unit) {
+ const words = unit.split(/\s+/u).filter((word) => word.length > 0);
+ const grams = new Set();
+ for (let index = 0; index + 2 < words.length; index += 1) grams.add(words.slice(index, index + 3).join(" "));
+ return grams;
+}
+
+function jaccard(left, right) {
+ let shared = 0;
+ for (const gram of left) if (right.has(gram)) shared += 1;
+ const union = left.size + right.size - shared;
+ return union === 0 ? 0 : shared / union;
+}
+
+/**
+ * Where the same thing is said in more than one place.
+ *
+ * Identical units are grouped rather than paired. One sentence repeated across nine format files is
+ * one thing to look at, not the thirty-six pairs the cross product produces — and at that volume the
+ * rewordings, which are the ones worth finding, are buried under the exact repeats.
+ *
+ * This is a review list and never a gate. Some repetition is deliberate: each format file closes
+ * with the same footer pointing back at the always-read craft, and that is the footer doing its job.
+ * The output says where to look; whether a given entry should survive is a judgement.
+ */
+function restatements(at, threshold) {
+ const entries = [];
+ for (const path of everySkillFile(at)) {
+ const text = read(path, at);
+ if (text === null) continue;
+ for (const unit of unitsIn(text)) {
+ if (unit.startsWith("code:")) continue;
+ const grams = trigrams(unit);
+ if (grams.size >= 4) entries.push({ path, unit, grams });
+ }
+ }
+
+ const identical = new Map();
+ for (const entry of entries) {
+ const holders = identical.get(entry.unit) ?? new Set();
+ holders.add(entry.path);
+ identical.set(entry.unit, holders);
+ }
+ const repeats = [...identical].filter(([, holders]) => holders.size > 1)
+ .map(([unit, holders]) => ({ unit, files: [...holders].sort() }))
+ .sort((one, other) => other.files.length - one.files.length);
+
+ // One representative per distinct unit, so a sentence in nine files does not pair with itself.
+ const distinct = [...identical.keys()].map((unit) => entries.find((entry) => entry.unit === unit));
+ const pairs = [];
+ for (let i = 0; i < distinct.length; i += 1) {
+ for (let j = i + 1; j < distinct.length; j += 1) {
+ const score = jaccard(distinct[i].grams, distinct[j].grams);
+ if (score >= threshold) pairs.push({ score, a: distinct[i], b: distinct[j] });
+ }
+ }
+ return { repeats, pairs: pairs.sort((one, other) => other.score - one.score) };
+}
+
+function flagValue(argv, name) {
+ const index = argv.indexOf(name);
+ return index === -1 ? undefined : argv[index + 1];
+}
+
+const argv = process.argv.slice(2);
+const at = flagValue(argv, "--at");
+const route = flagValue(argv, "--route");
+
+if (route !== undefined) {
+ if (routes[route] === undefined) throw new Error(`--route must be one of ${Object.keys(routes).join(", ")}`);
+ process.stdout.write(`${unitsForRoute(route, at).join("\n")}\n`);
+} else if (argv.includes("--links")) {
+ // Only a path that resolves to nothing is reported. A path this scanner reads the wrong way round
+ // would be reported too, which is what the root-relative rule above is for.
+ let broken = 0;
+ for (const path of everySkillFile(at)) {
+ const text = read(path, at);
+ if (text === null) continue;
+ for (const match of text.matchAll(linkPattern)) {
+ if (isTemplate(match[1])) continue;
+ const target = resolveLink(path, match[1]);
+ if (read(target, at) === null) { process.stdout.write(`${path}: \`${match[1]}\` -> ${target} does not exist\n`); broken += 1; }
+ }
+ }
+ process.stdout.write(`${broken} broken\n`);
+} else if (argv.includes("--orphans")) {
+ // A file no route reaches is a file nobody reads. It is the failure a sentence-level diff cannot
+ // see: create a new shared file, link it from one route, and the other route silently loses it.
+ const reached = new Set([...reachable("reconstruction", at), ...reachable("description", at)]);
+ let orphans = 0;
+ for (const path of everySkillFile(at)) if (!reached.has(path)) { process.stdout.write(`${path}\n`); orphans += 1; }
+ process.stdout.write(`${orphans} orphaned\n`);
+} else if (argv.includes("--restatements")) {
+ const threshold = Number(flagValue(argv, "--threshold") ?? 0.45);
+ const { repeats, pairs } = restatements(at, threshold);
+ process.stdout.write("== said identically in more than one file ==\n");
+ for (const repeat of repeats) {
+ process.stdout.write(`${repeat.files.length} files: ${repeat.unit}\n`);
+ for (const file of repeat.files) process.stdout.write(` ${file}\n`);
+ }
+ process.stdout.write(`\n== said differently in more than one file (>= ${threshold}) ==\n`);
+ for (const pair of pairs) {
+ process.stdout.write(`${pair.score.toFixed(2)}\n ${pair.a.path}: ${pair.a.unit}\n ${pair.b.path}: ${pair.b.unit}\n`);
+ }
+ process.stdout.write(`\n${repeats.length} repeated, ${pairs.length} reworded\n`);
+} else {
+ process.stdout.write("usage: --route <reconstruction|description> | --links | --orphans | --restatements [--threshold N] [--at <commit>]\n");
+ process.exit(1);
+}