spine-rigc 0.3.0 → 0.5.0

package/README.md

@@ -138,6 +138,21 @@ per animation and per frame:
   land in the box `frames.json` records is measured there, exactly, and the rest
   share one fitted framing. `--framing shared` measures every set in the shared one
   — the whole-root behaviour before issue #100, and worth 15–25 MAE on a character.
+  A **fitted** framing then gets one last pass that searches whole-pixel offsets
+  (±2 px) for the lowest MAE and takes the best one, because a fit registers extent
+  and the best fit of two extents is not the best alignment of two pictures — a
+  constant pixel is worth up to 30 % of a set's figure (issue #146). The line says
+  what it moved and what that was worth, and it says so when the identity won as
+  well. A box that is **not** an estimate — `frames.json`'s own, or one you pinned —
+  is never moved: there the same search is reported as a finding, because a constant
+  pixel inside the right box is the candidate's own figure sitting off, not framing.
+- **The whole shot, against the contact sheet** — a set that ships a couple of
+  stills and folds every sampled frame into one `contact.png` (rung 2's do,
+  spineboy's `@30fps` sets do) used to be compared on the stills alone, honestly
+  reported and empty behind: nothing at all was measured about the frames in
+  between. `check` now samples the candidate at the set's own rate and compares it
+  against the sheet's own tiles, whose grid it measures off the sheet (issue #36).
+  MAE only, and a sheet that is not a grid of those frames is refused by name.
 - **Per-frame change** — how many pixels each side moved since **its own** previous
   frame, compared against each other. It is the only measure here that looks at the
   relation between two frames rather than at one, and it is what catches a held pose
@@ -146,7 +161,8 @@ per animation and per frame:
 - **Per-slot drift** — where each of the candidate's own slots landed against the
   reference frame, in pixels. MAE says *how wrong*; a slot's drift says *which
   part, which way, how far*. Where the reference merged two parts into one blob —
-  the trap [AUTHORING §8](docs/AUTHORING.md) opens with — the slot is
+  the trap [AUTHORING §8](docs/AUTHORING.md) opens with, and it counts as merged
+  even when one part is most of the blob (issue #37) — the slot is
   template-matched against its own rendered pixels instead, with a confidence; and
   where nothing inside the distance that slot could plausibly have moved matches
   it, the answer is **no match** rather than a number about some other part.
@@ -175,14 +191,33 @@ same pixels whatever coordinates they were authored in, an invisible transparent
 margin cannot move the result, and no single quad corner in a single frame can set
 the scale for a run.
 
-There is no pass mark, for the same reason `diff` has none.
+There is no pass mark **in the tool**, for the same reason `diff` has none. The
+ladder's pass definition and its thresholds are a document read by a person over
+the whole table — [docs/LADDER.md](docs/LADDER.md)'s *Operating rules* — and not an
+exit code either command could produce.
 
 ### Benchmark ladder — the rungs, and where they stand
 
+🎓 **The ladder is complete, 2026-08-28.** All eight numbered rungs and the
+spineboy graduation exam are cleared under gate v2.1, every clause PASS or SKIP:
+worst attributable slot drift **5.55 px** against a 6.0 px bar, and **0 of 124**
+frame-change disagreements. Recompiling the same spec in a different session
+reproduced every field of the measurement record **to the digit**. The rungs stay
+in place as regression gates.
+
+⚠️ **What that certifies, stated exactly.** That **the tool, the guide and the
+protocol reach the bar across a bounded series of honest attempts, each residual
+diagnosed and fixed** — spineboy took five, and the last inherited its
+predecessor's specs under the run protocol's inheritance clause. It is **not**
+that an agent authors a spineboy-scale rig from the brief alone in one run: the
+ladder has not demonstrated that, and each row records which of the two it is.
+
 **[docs/LADDER.md](docs/LADDER.md) is the live ledger**: the rung order
 (blockers → rung 3 first → 1 · 2 · 4 · 5 → 6 → 8 → 7 → spineboy), what each
 rung gates on, how a rung is scored, the honesty rule that keeps the reference
-export away from the authoring agent, and a status table. Run one with:
+export away from the authoring agent, the operating rules — what a pass is, and
+the numbered thresholds of the current gate (**gate v2.1**) that decide one — and a status table. Run
+one with:
 
 ```bash
 bun cli.ts bench 3 --candidate path/to/candidate/spine
@@ -567,6 +602,9 @@ for a result, and there is no flag that changes that.
 - [docs/LADDER.md](docs/LADDER.md) is the benchmark: the same job, from a brief
   and rendered frames, scored. [docs/PILOT.md](docs/PILOT.md) is how to run an
   agent through it and score what comes back.
+- 🤖 **Handing the authoring to an AI agent?**
+  [docs/PROMPTING.md](docs/PROMPTING.md) is the operator's page — the six prompt
+  clauses a measured pilot run paid for, and what you can leave unsaid.
 
 ## Usage
 

package/cli.ts

@@ -523,9 +523,18 @@ function cmdBench(flags: Record<string, string>, positional: string[]): void {
         : framing.source === 'declared'
           ? `frames.json's own box, the candidate measured into it`
           : `fitted to the candidate's pixels, ${framing.passes} pass(es)${framing.settled ? '' : framing.cycled ? ', cycling' : ', unsettled'}`;
+      // The MAE-refined offset belongs on this line rather than only in `check`'s
+      // own table: it moved the box every figure below was measured in, so a row
+      // that quoted the figures without it would not say what they were measured
+      // against — issue #146's own version of the #34 lesson above.
+      const r = framing.refinement;
+      const refined =
+        r === null || !r.applied
+          ? ''
+          : `  MAE-refined ${signed(r.dx)}, ${signed(r.dy)}px (${r.before.toFixed(2)} → ${r.after.toFixed(2)} ref)`;
       console.log(
         `  framing    fit x${framing.fit.scale.toFixed(6)}  rms ${framing.fit.rms.toFixed(2)}px  union residual ` +
-          `${signed(framing.fit.residualWidth)} x ${signed(framing.fit.residualHeight)}px  (${how})`,
+          `${signed(framing.fit.residualWidth)} x ${signed(framing.fit.residualHeight)}px  (${how})${refined}`,
       );
     }
     for (const anim of check.animations) {
@@ -551,9 +560,17 @@ function cmdBench(flags: Record<string, string>, positional: string[]): void {
       // carried here and not only in `check`'s own table because this is the line a
       // loop reads between builds, and `mean=` has a denominator the candidate can
       // grow — see `FrameCheck.maeReference`.
+      // ...and the contact sheet, when the set ships one: a row reading "over 2
+      // frame(s)" for a 311-frame shot is the hole issue #36 closed, and the whole
+      // -shot figure is the one that says the frames between the stills were seen.
+      const sheet =
+        anim.sheet === null
+          ? ''
+          : `, sheet ${anim.sheet.compared} tile(s) mean=${anim.sheet.meanMae.toFixed(2)} ` +
+            `worst=${anim.sheet.worstMae.toFixed(2)}`;
       console.log(
         `  ${anim.dir.padEnd(10)} MAE mean=${anim.meanMae.toFixed(2)} worst=${anim.worstMae.toFixed(2)} ` +
-          `ref=${anim.meanMaeReference.toFixed(2)}  over ${anim.compared} frame(s)  ${drift}${change}${chain}`,
+          `ref=${anim.meanMaeReference.toFixed(2)}  over ${anim.compared} frame(s)  ${drift}${change}${chain}${sheet}`,
       );
     }
   } else {