modwright 0.1.0

package/knowledge/cyberpunk2077/anims.authoring.yaml

@@ -0,0 +1,579 @@
+game: cyberpunk2077
+topic: anims.authoring
+title: authoring custom FPP melee grips, regrips, sway, lunge, heavies and finishers
+facts:
+  - id: cp2077.anims.authoring.hand-position-report-was-improvement-not-regression
+    claim: "A user report that \"hand positions have moved\" (comparing the current build to the prior
+      baseline) was diagnosed via an A/B launch comparison as NOT a regression: the prior 08-20
+      baseline was materially worse everywhere the grip mattered, and the true remaining defect was
+      that the idle's own hand-posed right-hand grip was itself bad — because it fed every hold and
+      the whole crouch family through GRIP_SRC, the defect propagated everywhere except the block,
+      which kept its own independent hand-posed grip."
+    status: verified
+    source: ModWright field verification
+    tags:
+      - grip
+      - regression-diagnosis
+      - grip-src
+      - ab-comparison
+      - hand-position
+    detail: 'Concrete symptom that ruled out "the new hands are fine": fingers were visibly intersecting
+      the blade wherever the grip came from GRIP_SRC (idle, holds, crouch), exactly where the block
+      did not show the defect.'
+  - id: cp2077.anims.authoring.grip-transfer-must-use-palm-line-not-donor-wrist
+    claim: A naive grip-transfer (repointing weapon_rel/hand_rel from one hand-posed source pose to
+      another) silently assumes the source and the donor hold the wrist alike; replaying a donor's
+      untouched wrist under a source pose whose wrist was turned 86 degrees by hand-posing swung the
+      blade 0.426 m off the palm line (versus 0.115 m for the working approach). The working
+      transfer instead derives the roll term and palm midpoint FROM the source pose itself
+      (GRIP["roll_rel"], GRIP["palm_mid_local"]), turns BOTH wrists onto the re-fitted blade, and
+      iterates three rounds because turning a wrist moves the palm point the fit uses.
+    status: inferred
+    source: ModWright research
+    tags:
+      - grip-transfer
+      - palm-line
+      - weapon-rel
+      - hand-rel
+      - wrist-independence
+    detail: "Generalizes to: a grip is a relationship between the weapon and BOTH hands together;
+      anchoring the transfer to one hand only works while that hand is a fixed reference point,
+      which hand-posing specifically breaks. Offline result of the working transfer: 0.057/0.048 m
+      wrap-to-palm on all 12 transferred holds against the idle's own 0.063/0.049 m, and grip within
+      0.1 degree of the idle on all 12. Status is inferred, not verified — the evidence is an
+      offline measurement; the transferred holds were separately seen in game 2026-08-21 but no note
+      records an in-game confirmation of the palm-line rule itself. Concrete source numbers:
+      GRIP[\"roll_rel\"] came out 152.3 degrees against the ROLL=180 constant it replaced."
+  - id: cp2077.anims.authoring.rotate-weapon-in-grip-not-grip-with-weapon
+    claim: "When a pose needs the weapon reoriented, pivoting the weapon ALONE about its own grip axis
+      (the line through the two wrap centroids) leaves the hands byte-identical to the pre-roll
+      pose; a rigid rotation of hands and weapon together as one piece instead forces the whole
+      angle through the wrists and can slide the wraps up to about 6 cm out of the palms. Measured
+      at a 75-degree weapon-only roll: wrists 108.5/39.5 degrees, identical before and after."
+    status: inferred
+    source: ModWright research
+    tags:
+      - rotate-weapon-in-grip
+      - grip-axis
+      - wrist-load
+      - deformation-free
+    detail: "Three tried rigid-rotation variants for the crouch pose (rigid roll on the wrist line,
+      elbow-solved roll, weapon-only roll) scored 125.5/80.9 degrees, 108.4/56.8, and 108.5/39.5
+      wrist load respectively — the weapon-only pivot exactly reproduced the idle's own wrist load,
+      and the wrist-line pivot was the one that \"tore the arms in game\". Also measured at roll 75:
+      wrap-to-palm unchanged at 0.0631/0.0492, blade tip elevation -57.3 -> +8.8 degrees, hang 0.901
+      -> 0.083 m. Status is inferred, not verified: these are offline measurements. The chosen ANGLE
+      was picked in game (cp2077.anims.authoring.crouch-roll-value-chosen-in-game); no note records
+      the user separately confirming in game that the weapon-only pivot left the hands unmoved."
+  - id: cp2077.anims.authoring.crouch-roll-value-chosen-in-game
+    claim: CROUCH_ROLL = 75 degrees (a rotation of the weapon alone about the line through both palms)
+      was chosen live in game by cycling candidate values with a CET console tool rather than by
+      offline preview alone; 75 was picked over the geometrically "flattest" option (60, dead level)
+      because it carries the blade tips slightly up, matching that a crouched player's enemies are
+      above them.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - crouch-roll
+      - live-tuning
+      - cet-console
+      - user-decision
+    detail: The measured sweep (offline, no build needed) showed roll 60 as dead level (blade hangs 0.04
+      m below grip) and roll 0 as hanging 0.91 m below; 75 sits between the crouch's own 60-degree
+      "level" candidate and a fully raised guard.
+  - id: cp2077.anims.authoring.engine-limit-fpp-additive-ignores-spine-and-shoulders
+    claim: The FPP additive sway layer only honours LeftArm/RightArm and below plus the gun-space chain;
+      Spine3 and both shoulders are IGNORED by the engine at runtime. A build that authored the
+      entire ambient sway correction onto Spine3 (a geometrically elegant choice, since both
+      shoulders and the whole gun-space chain hang off Spine3 while the FPP camera does not)
+      measured a perfect zero-slip result offline (Blender reproduced the vanilla weapon path to
+      0.09 mm) but rendered completely MOTIONLESS in game — idle, walk, crouch and block all dead
+      still.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - engine-limit
+      - spine3
+      - fpp-additive
+      - sway
+      - launch-cost
+    detail: "Confirmed structurally by `_addbones.py`: in every vanilla additive, the first moving bone
+      in each arm chain is the upper arm, and Spine3/LeftShoulder/RightShoulder are exactly zero in
+      every one — the vanilla animators never used the spine because the additive layer cannot reach
+      it. The build was updated to gate every touched sway clip on
+      Spine3/Spine2/Spine1/Spine/Hips/LeftShoulder/RightShoulder staying at identity."
+  - id: cp2077.anims.authoring.no-base-independent-fix-for-full-ambient-sway
+    claim: Because the ambient-sway additive layer only reaches the arms (which form two separate
+      kinematic chains once the shoulders above them are unreachable), no single additive that keeps
+      the two arms perfectly moving together as one unit can serve every base pose without the
+      correction being conjugated by each base's own arm transform — meaning full pre-encoder-fix
+      sway amplitude and full base-independence are mutually exclusive, not a tuning failure to be
+      solved with more iteration.
+    status: inferred
+    source: ModWright research
+    tags:
+      - sway
+      - base-independence
+      - arm-chain
+      - structural-limit
+    detail: This structural conclusion predates and is independent of the later encoder root-cause
+      discovery (SWAY_GUNROT_CONST); it concerns the authored-signal side of the sway problem, not
+      the encoder-noise side.
+  - id: cp2077.anims.authoring.sway-damp-gain-tuning-superseded
+    claim: Before the encoder root cause was found, the sway defect was mitigated by tuning SWAY_DAMP
+      (uniformly scaling the vanilla arm-local sway; slip scales exactly with it, a pure trade) to
+      0.85 and SWAY_GAIN (a left-arm-only rotation correction solved on the idle base, exact only on
+      that one base) to 0.25, calibrated so the idle's measured slip matched the level the user
+      already called correct on the block (0.0320 m) rather than reaching zero.
+    status: contradicted
+    source: ModWright research
+    tags:
+      - sway-damp
+      - sway-gain
+      - tuning
+      - dead-approach
+    detail: "Explicitly retired once the real root cause (encoder rotation noise on gun-space/IK bones)
+      was found and fixed: \"do NOT re-tune gain/damp, that trade is dead\" (a project's own notes).
+      See cp2077.anims.encoder.sway-gunrot-const-fix-verified-in-game for the superseding fix."
+  - id: cp2077.anims.authoring.crouch-still-softness-open
+    claim: After the sway root-cause fix, the crouch-still pose (which settles into melee_safepose, not
+      melee_crouchpose) still measures about 15.8 mm of slip versus 4 mm or less everywhere else,
+      because the sway's left-arm rotation correction is solved against ADDITIVE_BASE =
+      melee_idlepose and over-corrects on other bases; the prescribed fix, if the eye catches it, is
+      to re-pin the sway solve against melee_safepose (a new SWAY_BASE constant) and re-measure,
+      explicitly NOT to re-tune gain/damp.
+    status: unverified
+    source: ModWright research
+    tags:
+      - crouch-still
+      - melee_safepose
+      - sway-base
+      - open-item
+    detail: Left as an open item pending whether the user's eye ever catches it in normal play; not yet
+      re-pinned or re-measured as of the source's writing.
+  - id: cp2077.anims.authoring.wrist-budget-values-and-metric
+    claim: The calibrated per-side wrist load budget (bend plus twist) used to gate every authored grip
+      and pose is right hand <= 108.5 degrees, left hand <= 50.7 degrees, calibrated on static poses
+      already confirmed good in game. Palm-to-palm angle PARITY is explicitly NOT a valid grip
+      similarity metric — two confirmed-good shipped grips sit at 124 degrees apart from each other
+      — judge a grip only by palm-to-marker distance and wrist load.
+    status: inferred
+    source: ModWright research
+    tags:
+      - wrist-budget
+      - palm-parity
+      - grip-metric
+      - check-wrists
+    detail: Repeated across multiple authoring documents as a standing rule ("NEVER palm parity") after
+      being independently re-derived more than once.
+  - id: cp2077.anims.authoring.wrist-budget-untested-for-transient-loads
+    claim: The 108.5/50.7 degree wrist load budget was calibrated on four STATIC poses; its validity for
+      fast, transient mid-swing loads (as opposed to held poses) has never been confirmed in game,
+      and was deliberately left as a warning rather than a hard build failure on transient frames,
+      pending a launch verdict.
+    status: unverified
+    source: ModWright research
+    tags:
+      - wrist-budget
+      - transient-load
+      - static-vs-dynamic
+      - open-item
+    detail: "The stated policy: gate the plateaus (held poses) hard on this budget, warn-only on fast
+      transients, and let the launch judge whether the budget is too conservative for motion."
+  - id: cp2077.anims.authoring.grip-carry-wrist-configuration-closed-form
+    claim: "The transferable arm content of a grip that must move a hand while preserving its wrist feel
+      is the WRIST CONFIGURATION W = ForeArm^-1 @ Hand, reproduced per frame with two
+      hand-preserving, CLOSED-FORM degrees of freedom: forearm axial roll (about the elbow-to-wrist
+      line) and elbow swing (about the shoulder-to-hand line) — neither requires a per-frame search,
+      avoiding the jitter a discrete load-minimizing search produces (one documented search-based
+      approach moved the elbow 4.9 to 19.0 to 15.4 cm on three consecutive frames, jumping between
+      near-equal-error minima)."
+    status: inferred
+    source: ModWright research
+    tags:
+      - grip-carry
+      - wrist-configuration
+      - closed-form
+      - forearm-roll
+      - elbow-swing
+    detail: "Validation (offline): an offline grip-carry check recovers the Phase 1 katana relax EXACTLY
+      from its raw capture — residual 0.0000 degrees, elbow match 0.0000 m — with both a known-good
+      and a known-bad case exercised. This resolved what had been framed as a false dichotomy
+      between \"carry the donor's arm values\" (re-derives a documented failure: an earlier
+      GRIP_DELTA experiment that carried forearm values pushed hold grips to 0.566-0.640 m span
+      against an approved 0.509 m) and \"re-run a load-minimizing search per frame\" (inherits
+      jitter)."
+  - id: cp2077.anims.authoring.fingers-derived-never-carried
+    claim: Finger/hand-subtree bones must always be DERIVED fresh from the FINAL placed hand transform
+      on every frame, never carried through an intermediate rotation step; a routine that reorients
+      the hand after its children were already positioned orphans the fingers from the palm — the
+      general fix pattern is to rebuild the hand's children rigidly from the final hand transform
+      every time, which regrip_frame() already did and which fixed an adjacent defect in
+      solve_two_bone()'s hand-reorientation step.
+    status: inferred
+    source: ModWright research
+    tags:
+      - finger-derivation
+      - hand-subtree
+      - rebuild-from-final-hand
+      - builder-rule
+    detail: The specific defect found (relax_wrist rotating the hand's own subtree instead of excluding
+      it) was confirmed to be DEAD code in the shipping configuration at the time it was found, and
+      to never have perturbed actual weapon placement — only measurement diagnostics and finger
+      cosmetics were affected.
+  - id: cp2077.anims.authoring.sway-slip-proportional-to-turn-times-span
+    claim: The geometric law behind the ambient sway defect is slip is approximately proportional to
+      weapon_turn times grip_span; because the custom weapon's hands sit roughly 0.51 m apart versus
+      the donor katana's 0.093 m, the identical ambient sway rotation drags roughly 5-6 times more
+      haft length through the off hand than it does on the weapon the sway was originally authored
+      for.
+    status: inferred
+    source: ModWright research
+    tags:
+      - sway
+      - weapon-turn
+      - grip-span
+      - geometric-law
+    detail: "Measured comparison table (span in meters, slip per meter of span): katana base+add
+      0.093/0.193, hammer base+add 0.473/0.012, the custom weapon 0.513/0.120 — the katana's own
+      sway is proportionally far worse but invisible only because its span is tiny."
+  - id: cp2077.anims.authoring.right-arm-repose-is-the-turn-amplifier
+    claim: Rebuilding a custom weapon's base pose from the donor one bone group at a time isolated the
+      weapon-turn increase under the shared ambient additive (3.66 to 5.22 degrees) entirely to the
+      RIGHT arm re-pose, not to the wrist changes or the left arm re-pose.
+    status: inferred
+    source: ModWright research
+    tags:
+      - right-arm
+      - weapon-turn
+      - isolation
+      - sway-source
+    detail: "Isolation table: donor arms + our wrists (turn 3.66), + our left arm (turn 3.66,
+      unchanged), + our right arm (turn 5.22 — the whole jump)."
+  - id: cp2077.anims.authoring.no-vanilla-clip-carries-lunge-travel
+    claim: Across a sweep of 1166 player-FPP-melee clips, root_excursion_m measures 0.0000 on every
+      single one — 58 clips do move some torso or leg bone by more than 1 mm, but none of that
+      displaces the body; the best-looking forward-hand-travel candidates were either camera-frame
+      artifacts (measured hand travel of +0.81 to +0.95 m collapses to +0.15/+0.17 m once measured
+      in the live per-frame camera basis instead of a frame-0-fixed basis, because the camera itself
+      travels 0.836 m during those clips) or monotonic pose-transition drift rather than a genuine
+      thrust-and-return; a custom finisher's forward lunge travel therefore has to be supplied by
+      the engine (record/script side), with the clip supplying only the arm and blade extension.
+    status: inferred
+    source: ModWright research
+    tags:
+      - lunge
+      - root-motion
+      - camera-frame-artifact
+      - no-clip-travel
+    detail: Exactly one attack-family clip in the whole census showed a genuine forward-out-and-back
+      drive above 0.25 m (default_melee_weapon/final_attack_03, +0.288 m at frame 9 of 46, returning
+      to net 0.000), and even that is an arm extension, not a lunge.
+  - id: cp2077.anims.authoring.entry-transition-and-terminal-pose-both-constrain-authoring
+    claim: "Because the Attack state's entry transition is a hard, zero-duration cut and the whole state
+      machine terminates attack clips exactly on melee_idlepose frame 0, every custom-authored swing
+      has a symmetric requirement: frame 0 must equal the CURRENT (re-posed) idle's grip exactly,
+      and the final frame must equal melee_idlepose frame 0 exactly, with a near-static, cut-safe
+      plateau covering the whole mapped cut window in between."
+    status: inferred
+    source: ModWright research
+    tags:
+      - entry-transition
+      - terminal-pose
+      - cut-safe-plateau
+      - authoring-constraint
+    detail: "Both live defects this constraint was written to fix were measured concretely before the
+      fix: a 0.42 m instantaneous hand snap on attack entry, and a 403.5 mm / 98.0 degree gap
+      between the re-posed idle and the vanilla idle every attack clip terminates onto."
+  - id: cp2077.anims.authoring.blade-rides-right-hand-not-palm-line-for-attacks
+    claim: "For authored ATTACK clips (as opposed to static holds), deriving the blade transform from a
+      fitted palm line between both hands is the wrong model: the fit becomes numerically
+      ill-conditioned at a stacked/katana-style grip (a 0.108 m span measured about 4.3x
+      ill-conditioned) and is UNDEFINED whenever the left hand is off the haft mid-regrip, which
+      every authored swing does at some point. The adopted model instead rigs the blade rigidly to
+      the RIGHT hand (X(t) = H_R(t) @ rel_R, with rel_R captured once from the END-grip reference),
+      then solves the LEFT hand onto the blade per a per-swing grip timeline."
+    status: inferred
+    source: ModWright research
+    tags:
+      - blade-placement
+      - right-hand-rigid
+      - palm-line
+      - ill-conditioned
+      - grip-timeline
+    detail: This is the design underlying build_attack2r.py; it removes a conditioning problem entirely
+      rather than mitigating it, and it matches how the engine itself composes a held weapon
+      (WeaponRight is a child bone of RightHand).
+  - id: cp2077.anims.authoring.regrip-windows-must-be-authored-in-state-time
+    claim: Because the record's three-segment retimer stretches each authored Phase segment
+      independently and by different factors per swing (e.g. one swing's startup plays at 2.67x,
+      another swing's recover at 2.63x), a release/regrip window or contact frame authored as a
+      fixed FRACTION of clip time can play up to about 3x faster or slower on screen than in the
+      Blender preview; regrip windows and contact frames must instead be expressed in state time
+      (seconds actually on screen) and mapped through each swing's own record durations into clip
+      frames at build time.
+    status: inferred
+    source: ModWright research
+    tags:
+      - regrip-window
+      - state-time
+      - clip-fraction
+      - retimer
+      - authoring-rule
+    detail: "Corollary: the authored contact frame goes at 0.899 of the startup segment when the retimer
+      engages (per cp2077.anims.graph.gameplay-hit-lands-near-active-phase-event), also expressed
+      through this same time mapping."
+  - id: cp2077.anims.authoring.boundary-grip-design-end-everywhere
+    claim: The project's boundary-grip design question — whether each chain-linked swing should open and
+      close on a shared END grip with its own out-and-back regrip inside the clip, versus carrying a
+      grip across chain links for a prettier but more fragile join — was resolved by the user in
+      favor of END-EVERYWHERE, on the grounds that opening and closing every swing at the same
+      END-grip pose is robust to every cut timing and entry path; chain-carried grips were offered
+      and declined.
+    status: contradicted
+    source: ModWright research
+    tags:
+      - boundary-grip
+      - end-grip
+      - chain-carried-grip
+      - user-decision
+      - dead-belief
+    detail: "Kept as the decision of 2026-08-23. REVERSED the same evening by the launch verdict on
+      build a4214cda: \"Vanilla chains ALTERNATE stroke direction (R->L, L->R, R->L...) and do NOT
+      return to baseline between chained swings. REVERSES the END-boundary decision.\" Superseded by
+      cp2077.anims.authoring.chain-links-open-on-predecessor-park. Its original consequence — each
+      swing's regrip authored entirely inside its own clip (END-CENTRE-END, END-KATANA-END) — no
+      longer holds past swing 0."
+  - id: cp2077.anims.authoring.chain-links-open-on-predecessor-park
+    claim: "Vanilla melee chains ALTERNATE stroke direction (right-to-left, then left-to-right, then
+      right-to-left) and do NOT return to a baseline pose between chained swings: each clip opens on
+      its predecessor's PARK pose, strokes through the screen-centre hit dot, parks on the far side
+      (which becomes the successor's cut-in window), and only its RECOVERY tail — played when the
+      chain stops — returns grip and pose to the idle. Entry to the first swing from the idle stays
+      a hard cut."
+    status: inferred
+    supersedes: cp2077.anims.authoring.boundary-grip-design-end-everywhere
+    source: ModWright research
+    tags:
+      - chain-join
+      - park-pose
+      - stroke-alternation
+      - cut-window
+      - authoring-rule
+    detail: 'Two companion rules were adopted from the same verdict: every melee swing must land on the
+      screen-centre hit dot (strokes are authored in CAMERA space), and ONE CLIP = ONE STROKE — a
+      windup-plus-strike-plus-return packed into a single clip fought the record retimer and read as
+      unreadable noise (user on the rejected build: swings 1 and 2 were "so fast I can perceive no
+      details"). Vanilla clips read fine at the same retime because their content is a single
+      stroke. The measured screen-space consequence of the park convention is
+      cp2077.anims.authoring.vanilla-swing-parks-off-screen-between-chain-links.'
+  - id: cp2077.anims.authoring.swing0-composite-donor-approved-in-game
+    claim: Swing 0 (combo_attack_01, the light-chain opener) shipped as a from-scratch AUTHORED forward
+      thrust rather than adopting a single donor whole, because no single vanilla clip on disk is a
+      genuine forward thrust; the closest composite reference blended pwa_knife combo_attack_03's
+      forward drive (the largest single-frame forward displacement measured in the whole shortlist)
+      with pwa_katana safe_attack's extension and held finish. Both hands stay on the END grips
+      throughout. The user approved this swing's pose and extension in game.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - swing0
+      - donor-composite
+      - forward-thrust
+      - approved-in-game
+    detail: pwa_katana combo_attack_01 (rank 1 by record data) was explicitly rejected on inspection —
+      its arc is a descending diagonal chop, not a thrust in any component, and its shape was
+      reassigned to swing 2's spec instead.
+  - id: cp2077.anims.authoring.vanilla-swing-parks-off-screen-between-chain-links
+    claim: A screen-space trace of the vanilla katana clip occupying the swing-1 slot (combo_attack_02)
+      showed the clip parks the blade AND both hands fully OFF-SCREEN to the right (in-frame
+      fraction 0.00 through the whole cut window) after a roughly three-frame full-viewport
+      crossing, entering from off-screen left in its own windup; the chain's next link
+      (combo_attack_03) opens at that same off-right position and sweeps back to park off-screen
+      left, i.e. vanilla combos alternate off-screen parks rather than ending each swing framed in
+      view.
+    status: inferred
+    source: ModWright research
+    tags:
+      - screen-space-trace
+      - off-screen-park
+      - chain-alternation
+      - vanilla-reference
+    detail: This directly overturned five earlier rejected parametric builds of the corresponding custom
+      swing, all of which had ended the sweep framed fully in view — exactly what a real swing never
+      does, and what the user's rejections ("half way", "back in front") were describing.
+  - id: cp2077.anims.authoring.rigid-transform-of-prior-park-cannot-reach-off-screen-park
+    claim: "An exhaustive offline sweep of about 2.5 million candidate placements (5 degrees of freedom
+      across 6 tested grip widths) for a chained swing's parked pose, modeled as a rigid transform
+      of the PREDECESSOR swing's own park (yaw about the eye, forward push, lateral drift, pitch,
+      roll), found ZERO placements satisfying the measured vanilla park's screen geometry at any
+      tested grip width. The structural cause: the custom weapon's two hands sit roughly 0.5 m apart
+      on the haft (half-sword) versus the katana's roughly 0.15 m, so where vanilla parks its two
+      hands about 4 cm apart in depth, the equivalent half-sword grip would need about 31 cm of hand
+      depth separation, which no rigid transform of a single prior pose can produce."
+    status: inferred
+    source: ModWright research
+    tags:
+      - park-pose
+      - rigid-transform
+      - exhaustive-sweep
+      - half-sword-grip
+      - structural-limit
+    detail: "Confirmed the fallback predicted in advance by the project's own standing rule (\"if the
+      user rejects the v6 parametric attempt, do not tune parameters again — hand it to the user\"):
+      the park needed a free, hand-posed placement rather than a parametric one."
+  - id: cp2077.anims.authoring.one-hand-posed-frame-beat-five-parametric-iterations
+    claim: Across this authoring effort, a single hand-posed correction (the swing-0 "EXTEND" grip,
+      posed once by the user) landed correctly on the first attempt, and the correction it produced
+      turned out to be rotation-dominant (33 mm plus 40.8 degrees on the right hand, 73 mm plus 38.8
+      degrees on the left) — a shape no translation-focused parameter search would have found —
+      while five successive parametric iterations of a different swing's spec all failed against the
+      same user's rejections.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - hand-posed
+      - parametric-tuning
+      - extend-grip
+      - authoring-strategy
+    detail: "The standing rule this produced: after one parametric attempt against a corrected, measured
+      specification, if the user still rejects it, switch to a user-hand-posed reference pose rather
+      than continuing to tune parameters."
+  - id: cp2077.anims.authoring.heavy-attack-phase-proportions
+    claim: "A heavy attack's phase proportions, measured from the vanilla katana heavy_attack_01 (42
+      frames) and used as a SHAPE reference (not a timing reference, since the vanilla clip's own
+      record retimes it) for a custom heavy swing: roughly 1 part chamber (a slow wind-up), 0.5 part
+      strike (a very fast few-frame swing), 2 parts dwell (a long, nearly frozen follow-through). An
+      early rejected draft had the dwell but built the chamber and the strike out of two
+      interpolated poses, and read as \"a slide rather than a swing\" specifically because it lacked
+      this proportion."
+    status: inferred
+    source: ModWright research
+    tags:
+      - heavy-attack
+      - phase-proportion
+      - chamber-strike-dwell
+      - katana-reference
+    detail: The interpolated draft was rejected by the user on its preview GIF ("really not working"),
+      not in game, which is why this is inferred. Vanilla's own katana heavy does not strike at the
+      record's stock attackEffectDelay frame (about frame 9 in a naive 1:1 mapping) — it strikes
+      around frame 13 of its own clip, because the katana's strong record carries nonzero
+      startup/active/recover durations that retime the whole clip; a heavy authored to play 1:1 (no
+      retimer) needs its own record durations reconsidered if the vanilla clip's shape is reused
+      as-is.
+  - id: cp2077.anims.authoring.heavy-attacks-hand-authored-by-user-on-ik-handle-rig
+    claim: After a pose-interpolation approach for a heavy attack was rejected on the preview GIF, the
+      heavy attacks were switched to direct user hand-authoring on a rig exposing 7 keyframeable IK
+      handles (HAND_L/R, ELBOW_L/R, SHOULDER_L/R, and a blade-carrying weapon-adjust handle that
+      also drags both hand handles along with it), overlaid with two animated reference skeletons
+      (vanilla katana and machete heavies) for shape comparison; the tooling samples the resulting
+      pose EVERY frame regardless of how sparsely the user keys, and the user later confirmed all
+      heavy attacks were done.
+    status: inferred
+    source: ModWright research
+    tags:
+      - heavy-attack
+      - hand-authoring
+      - ik-handle-rig
+      - reference-skeleton
+      - user-authored
+    detail: Because the user is the sole ground truth for a hand-authored path, the screen-geometry
+      gates run report-only (non-blocking) on this content rather than failing the build. The user
+      reported the work complete ("heavy attacks are all done", 2026-08-26); that is a statement
+      about authoring progress, not an in-game engine observation, so this fact is inferred rather
+      than verified.
+  - id: cp2077.anims.authoring.blade-rotation-cheap-translation-expensive-for-heavy-authoring
+    claim: On the heavy-attack hand-authoring rig, a 90-degree blade ROTATION about the grip axis left
+      both palms within about 2 cm of their reference markers (nearly free), while a 0.30 m blade
+      TRANSLATION put the far hand 0.83 m from its shoulder, saturating the arm's IK and pulling the
+      palm 16-22 cm off the grip; a heavy swing's visible travel should therefore come from rotating
+      the blade about the grip rather than translating it through space, matching how the vanilla
+      katana heavy's own 0.87 m stroke is mostly the weapon swinging about the hands rather than the
+      hands themselves travelling.
+    status: inferred
+    source: ModWright research
+    tags:
+      - blade-rotation
+      - blade-translation
+      - reach-limit
+      - heavy-authoring
+    detail: 'Stated as a rule of thumb for the user during hand-authoring: "if the arms straighten and
+      the hands visibly leave the haft, you are past the reach limit — pull the blade back in and
+      get the travel from rotation instead."'
+  - id: cp2077.anims.authoring.clip-coverage-audit-donor-grip-vs-authored-grip
+    claim: A full-set audit measuring hand span and each hand's distance from the WeaponRight bone axis
+      across all 97 clips in the shipped set found 47 of 72 non-additive clips fully re-authored
+      onto the custom weapon's own wide (0.18-0.58 m) half-sword grip, and 25 clips still holding
+      the donor katana's narrow (0.092-0.114 m) two-hands-together grip; of those 25, 16 are
+      reachable in normal gameplay (crouch/jump/equip attacks, weapon slide, block-deflect, being
+      parried) and are real outstanding work items, while 9 are structurally unreachable at the
+      shipped AttacksNumber setting and require no work unless that setting is later raised.
+    status: inferred
+    source: ModWright research
+    tags:
+      - clip-coverage-audit
+      - donor-grip
+      - reachable-clips
+      - unreachable-clips
+    detail: "Open contradiction the audit itself flags: the user reported the crouch attack looks GOOD
+      in play despite crouch_attack still measuring a donor-grip span, so either the melee state
+      machine leaves the crouch state before an attack actually plays that clip, or the defect
+      simply has not yet been seen — this needs settling before authoring effort is spent there."
+  - id: cp2077.anims.authoring.donor-pick-falling-slash-swing
+    claim: For a chain design's falling-slash swing, pwa_one_handed_blunt combo_attack_01 was picked
+      over other candidates as the only genuine top-right-to-bottom-left diagonal cut among the
+      shortlisted donors (40 degrees below horizontal), with the tighter, cleaner HOLD pose (0.014
+      to 0.062 m of wobble in the weapon frame) borrowed from pwa_katana heavy_attack_01 or
+      combo_attack_03 instead. pwa_katana heavy_attack_01 was explicitly rejected as a donor for the
+      ARC despite having the cleanest hold, because 10 of its 12 sampled first-person tiles show no
+      blade on screen at all.
+    status: inferred
+    source: ModWright research
+    tags:
+      - donor-pick
+      - falling-slash
+      - first-person-visibility
+      - contact-sheet
+    detail: "Picked by the user on 2026-08-23 from a 12-donor contact-sheet index — an offline preview
+      choice, not an in-game observation, hence inferred. General lesson recorded alongside this
+      pick: a donor's record name does not describe its actual arc (Phase 0's own warning,
+      reconfirmed here), and first-person BLADE VISIBILITY, not arc quality alone, is a hard filter
+      on donor viability."
+  - id: cp2077.anims.authoring.vanilla-light-chain-shared-swing-grammar
+    claim: "A comparative per-frame speed and rotation measurement of the katana, machete and hammer
+      vanilla light-attack chains found a shared grammar for a satisfying swing: a short
+      rotation-or-translation-led ANTICIPATION before the stroke that scales with weapon weight
+      (measured: 3 frames / 357 mm for a katana combo versus 10 frames / 651 mm for a hammer combo),
+      a 1-3 frame WHIP that peaks in speed exactly AT the contact frame (never decelerating into
+      contact), a multi-frame POST-IMPACT DWELL (longest on the finisher, 9 frames measured), and a
+      RECOVERY that always tapers toward near-zero speed over its last 3-5 frames rather than
+      arriving at the idle pose at speed."
+    status: inferred
+    source: ModWright research
+    tags:
+      - swing-grammar
+      - anticipation
+      - whip
+      - dwell
+      - recovery
+      - vanilla-reference
+    detail: The project's own earlier swing-2/swing-3 builds used a single decelerating smoothstep with
+      no rotation-led coil and no proportionate dwell, and were redesigned specifically to match
+      this measured grammar after the user asked for a pass studying "anticipation and pauses."
+  - id: cp2077.anims.authoring.mounted-vehicle-path-unaffected-by-lunge-record-change
+    claim: "The finisher's move-to-target lunge fix (enabling enableAdjustingPlayerPositionToTarget on
+      the finisher's attack record) does not affect bike or vehicle melee combat: the
+      mounted-vehicle path runs a distinct event class (MeleeMountedFinalAttackEvents) whose four
+      MountedStrongAttackAbstract records all explicitly set that field to false, and the mod's own
+      anim-steering script already early-returns for that mounted event class — though nothing
+      enforces this relationship if the finisher record is ever reparented away from its current
+      base."
+    status: inferred
+    source: ModWright research
+    tags:
+      - mounted-vehicle
+      - meleemountedfinalattackevents
+      - lunge
+      - risk
+    detail: Flagged specifically as a fragile-but-currently-safe invariant, not a structurally
+      guaranteed one, in case the finisher record's inheritance chain changes in a future edit.