{"id":"69c4fcd7-dd2e-4c8f-924d-70ea5689c318","entityType":"agent","slug":"clawhub-yannxinn-piano-score-fingering","name":"Piano Score Fingering Arrangement","canonicalUrl":"https://www.xpersona.co/agent/clawhub-yannxinn-piano-score-fingering","canonicalPath":"/agent/clawhub-yannxinn-piano-score-fingering","generatedAt":"2026-10-10T11:54:55.752Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-10T09:30:11.553Z","emptyReason":null},"description":"Verify score facts, then generate and review two-hand fingering Skill: Piano Score Fingering Arrangement Owner: yannxinn Summary: Verify score facts, then generate and review two-hand fingering Tags: latest:0.1.0 Version history: v0.1.0 | 2026-08-16T08:22:14.885Z | auto Piano Score Fingering v0.1.0 - Initial release with support for piano score recognition from images, PDFs, MusicXML, MXL, or MuseScore files. - Preserves exact page coordinates of every notehead and delivers coord","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.5K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s175vkyg557rprrs31zwem4qt187twvc:piano-score-fingering","sourceUrl":"https://clawhub.ai/yannxinn/piano-score-fingering","homepage":"https://clawhub.ai/yannxinn/skills/piano-score-fingering","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/yannxinn/piano-score-fingering","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/yannxinn/skills/piano-score-fingering","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":64,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Verify score facts, then generate and review two-hand fingering Skill: Piano Score Fingering Arrangement Owner: yannxinn Summary: Verify score facts, then gener"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T09:30:11.553Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T09:30:11.553Z","emptyReason":null},"stars":null,"forks":null,"downloads":1524,"packageName":null,"latestVersion":"0.1.0","tractionLabel":"1.5K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T09:30:11.553Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T09:30:11.553Z","lastCrawledAt":"2026-10-10T09:30:11.553Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T09:30:11.553Z","lastVerifiedAt":null,"highlights":[{"version":"0.1.0","createdAt":"2026-08-16T08:22:14.885Z","changelog":"Piano Score Fingering v0.1.0 - Initial release with support for piano score recognition from images, PDFs, MusicXML, MXL, or MuseScore files. - Preserves exact page coordinates of every notehead and delivers coordinate-accurate overlays. - Provides an integrated fingering workflow, including dynamic two-hand fingering search and annotated PDF or fingered MusicXML output. - Ensures verified score facts and blocks incomplete or ambiguous recognition before fingering. - Offers detailed inspection, review, and error auditing; outputs comprehensive reports and manage recognition plan lifecycle. - No additional software, libraries, or online OMR services required.","fileCount":105,"zipByteSize":486036}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s175vkyg557rprrs31zwem4qt187twvc:piano-score-fingering","setupComplexity":"low","setupSteps":["Setup complexity is LOW. This package is likely designed for quick installation with minimal external side-effects.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yannxinn-piano-score-fingering/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yannxinn-piano-score-fingering/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yannxinn-piano-score-fingering/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-yannxinn-piano-score-fingering/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-yannxinn-piano-score-fingering/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-yannxinn-piano-score-fingering/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T11:54:55.751Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yannxinn-piano-score-fingering/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yannxinn-piano-score-fingering/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yannxinn-piano-score-fingering/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yannxinn-piano-score-fingering/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-10T09:30:11.553Z","emptyReason":null},"readme":"Skill: Piano Score Fingering Arrangement\n\nOwner: yannxinn\n\nSummary: Verify score facts, then generate and review two-hand fingering\n\nTags: latest:0.1.0\n\nVersion history:\n\nv0.1.0 | 2026-08-16T08:22:14.885Z | auto\n\nPiano Score Fingering v0.1.0\n\n- Initial release with support for piano score recognition from images, PDFs, MusicXML, MXL, or MuseScore files.\n- Preserves exact page coordinates of every notehead and delivers coordinate-accurate overlays.\n- Provides an integrated fingering workflow, including dynamic two-hand fingering search and annotated PDF or fingered MusicXML output.\n- Ensures verified score facts and blocks incomplete or ambiguous recognition before fingering.\n- Offers detailed inspection, review, and error auditing; outputs comprehensive reports and manage recognition plan lifecycle.\n- No additional software, libraries, or online OMR services required.\n\nArchive index:\n\nArchive v0.1.0: 105 files, 486036 bytes\n\nFiles: agents (0b), agents/openai.yaml (392b), assets (0b), assets/icon.svg (1210b), assets/tests (0b), assets/tests/test_chords.xml (77537b), assets/tests/test_multivoice.xml (933b), assets/tests/test_octaves.xml (72972b), assets/tests/test_scales_all_keys.xml (86621b), assets/tests/test_scales.xml (103293b), assets/tests/test_ties.xml (1103b), NOTICE.txt (8302b), references (0b), references/common-fingering-errors.md (6030b), references/fingering-plan-schema.md (10509b), references/professional-fingering-rules.md (9799b), scripts (0b), scripts/apply_fingerings.py (6153b), scripts/audit_overlay_anchors.py (4401b), scripts/build_measure_review_manifest.py (7644b), scripts/create_delivery_report.py (4300b), scripts/create_plan_from_musicxml.py (10246b), scripts/fingering_core (0b), scripts/fingering_core/__init__.py (193b), scripts/fingering_core/hand.py (28162b), scripts/fingering_core/models.py (2258b), scripts/generate_fingering_plan.py (31041b), scripts/manage_recognition.py (13725b), scripts/plan_io.py (3282b), scripts/recognition_state.py (5197b), scripts/render_fingering_pdf.py (13371b), scripts/render_jianpu_svg.py (4820b), scripts/render_score_overlay.py (182b), scripts/run_self_test.py (24408b), scripts/validate_fingering_plan.py (14851b), scripts/validate_recognition.py (28130b), scripts/vendor (0b), scripts/vendor/pypdf (0b), scripts/vendor/pypdf/__init__.py (1283b), scripts/vendor/pypdf/_cmap.py (12572b), scripts/vendor/pypdf/_codecs (0b), scripts/vendor/pypdf/_codecs/__init__.py (1373b), scripts/vendor/pypdf/_codecs/_codecs.py (10555b), scripts/vendor/pypdf/_codecs/adobe_glyphs.py (447213b), scripts/vendor/pypdf/_codecs/core_font_metrics.py (114968b), scripts/vendor/pypdf/_codecs/pdfdoc.py (4269b), scripts/vendor/pypdf/_codecs/std.py (2630b), scripts/vendor/pypdf/_codecs/symbol.py (3734b), scripts/vendor/pypdf/_codecs/zapfding.py (3742b), scripts/vendor/pypdf/_crypt_providers (0b), scripts/vendor/pypdf/_crypt_providers/__init__.py (3054b), scripts/vendor/pypdf/_crypt_providers/_base.py (1711b), scripts/vendor/pypdf/_crypt_providers/_cryptography.py (4460b), scripts/vendor/pypdf/_crypt_providers/_fallback.py (3334b), scripts/vendor/pypdf/_crypt_providers/_pycryptodome.py (3280b), scripts/vendor/pypdf/_doc_common.py (54398b), scripts/vendor/pypdf/_encryption.py (49546b), scripts/vendor/pypdf/_font.py (14256b), scripts/vendor/pypdf/_page_labels.py (8626b), scripts/vendor/pypdf/_page.py (90193b), scripts/vendor/pypdf/_protocols.py (2123b), scripts/vendor/pypdf/_reader.py (57708b), scripts/vendor/pypdf/_text_extraction (0b), scripts/vendor/pypdf/_text_extraction/__init__.py (8515b), scripts/vendor/pypdf/_text_extraction/_layout_mode (0b), scripts/vendor/pypdf/_text_extraction/_layout_mode/__init__.py (340b), scripts/vendor/pypdf/_text_extraction/_layout_mode/_fixed_width_page.py (15370b), scripts/vendor/pypdf/_text_extraction/_layout_mode/_text_state_manager.py (8221b), scripts/vendor/pypdf/_text_extraction/_layout_mode/_text_state_params.py (5481b), scripts/vendor/pypdf/_text_extraction/_text_extractor.py (14388b), scripts/vendor/pypdf/_utils.py (20814b), scripts/vendor/pypdf/_version.py (23b), scripts/vendor/pypdf/_writer.py (131834b), scripts/vendor/pypdf/annotations (0b), scripts/vendor/pypdf/annotations/__init__.py (990b), scripts/vendor/pypdf/annotations/_base.py (961b), scripts/vendor/pypdf/annotations/_markup_annotations.py (11862b), scripts/vendor/pypdf/annotations/_non_markup_annotations.py (3649b), scripts/vendor/pypdf/constants.py (23634b), scripts/vendor/pypdf/errors.py (1947b)\n\nFile v0.1.0:SKILL.md\n\n---\nname: piano-score-fingering\ndescription: Read piano scores from images, PDFs, MusicXML, MXL, or MuseScore files; preserve the page coordinates of every notehead; generate playable two-hand fingering with the bundled dynamic hand-position search; and deliver an annotated PDF or fingered MusicXML. Use for piano-score recognition, automatic fingering, coordinate-accurate score annotation, fingering review, and practice guidance without requiring PianoPlayer, MuseScore, ReportLab, or online OMR services.\n---\n\n# Piano Score Fingering\n\nComplete the workflow when the host can read files, inspect score pages, run Python, and write output files. Use only the bundled scripts and capabilities already present in the host. Do not require the user to install software, Python packages, browser extensions, or online recognition services.\n\n## Accuracy gates and delivery levels\n\nNever generate fingering from unverified score facts merely to produce an output. Always create inspectable artifacts. Deliver one of these outcomes:\n\n1. **Complete**: process the full requested range and deliver PDF/MusicXML plus a report.\n2. **Review required**: all performance semantics are verified, but non-semantic layout or musical-preference warnings remain; deliver the fingering result and report.\n3. **Partial**: only when the full range cannot be recognized reliably. Complete at least one whole measure or full system and label every output as a partial experiment.\n\nBlock fingering whenever pitch, clef, accidental, rhythm, hand, chord membership, tie, voice, or notehead identity is unresolved. On failure, still deliver the recognition plan, anchor audit, and error report. Historical outputs may reveal prior error types, but must never become recognition truth or a fingering target for a new task.\n\nLoad references only when needed: use [references/professional-fingering-rules.md](references/professional-fingering-rules.md) for musical review, [references/fingering-plan-schema.md](references/fingering-plan-schema.md) when creating or repairing a visual recognition plan, and [references/common-fingering-errors.md](references/common-fingering-errors.md) when a validator or user identifies a matching error. Keep [NOTICE.txt](NOTICE.txt) with every redistributed copy.\n\n## Choose the input path\n\n### PDF or image\n\n1. Make one complete recognition draft. Declare `measure_scope`, then create one `measure_region` for every page + measure + hand, including rest-only measures.\n2. Classify symbols before reading pitch and rhythm. Put noteheads in `notes` and rests in `rests`; never treat stems, beams, barlines, dots, text, or rectangular rest marks as notes.\n3. Record the true center of every visible notehead with `origin=direct_visual_notehead`. Locate every member of a touching chord separately and set `chord_member_verified=true`. Never infer a missing member from spacing or a repeated accompaniment pattern.\n4. Use `pdf_point` coordinates with a bottom-left origin for PDFs and `pixel_top_left` with a top-left origin for images. Write standard MusicXML as the semantic source and a unified `fingering-plan.json` for identities and coordinates.\n5. Perform an independent measure-level structure pass from source crops. Count visible noteheads and rests before comparing with the draft. Recheck only anomalous measures.\n\nThe second pass verifies measure/hand note counts, accidentals, same-position neighbors, ties, rests, and chord members; it does not regenerate the whole draft. Build a review manifest:\n\n```bash\npython3 scripts/build_measure_review_manifest.py build fingering-plan.json -o measure-review.json\npython3 scripts/build_measure_review_manifest.py apply fingering-plan.json measure-review.json -o review-plan.json\n```\n\nInspect each `evidence_crop` before filling `expected_noteheads`, `expected_rests`, and `duration_verified`. Do not derive expected counts from current plan entries. Verified notes require `recognition_passes=2`, `symbol_class=notehead`, and `notehead_shape_verified=true`. Record rests separately with their type, duration, and `rest_shape_verified=true`.\n\n### Recognition fact lifecycle\n\nMaintain one traceable source of truth:\n\n`draft -> review -> verified -> locked`\n\nCreate a compact exception queue, review at most two local rounds, and leave unresolved items open rather than looping over the full score:\n\n```bash\npython3 scripts/manage_recognition.py queue fingering-plan.json -o review-queue.json --plan-output review-plan.json\npython3 scripts/manage_recognition.py freeze review-plan.json -o locked-plan.json\npython3 scripts/manage_recognition.py status locked-plan.json\n```\n\nThe lock stores a SHA-256 digest of score facts. Fingering, color, type size, and label position may change after locking; pitch, rhythm, voice, chords, ties, staff geometry, and notehead coordinates may not. Every generator run recomputes the digest and blocks silent changes.\n\nWhen a later recognition error is found, patch only the affected page, measure, and hand:\n\n```bash\npython3 scripts/manage_recognition.py patch locked-plan.json correction.json -o review-plan.json\npython3 scripts/manage_recognition.py confirm review-plan.json --gates pitch_geometry rhythm chords anchors -o verified-plan.json\npython3 scripts/manage_recognition.py freeze verified-plan.json -o locked-plan-v2.json\n```\n\nNever edit a locked plan and simply recalculate its digest.\n\n### Execution budget and stop conditions\n\n- Allow one full recognition draft, one independent structure pass, and at most two local review rounds.\n- Run full-score fingering search once. After locking, patch and recompute only affected measures; do not rerun the whole score with `--ignore-existing`.\n- Perform one final full-page visual inspection. Earlier checks use anomalous measure crops. Layout changes rerender only affected pages.\n- Stop after two failed automatic correction rounds and deliver the audit plus a review-required result. During work longer than 60 seconds, report stage, hand, measure, and percentage.\n- Let scripts perform deterministic checks; show the model only the compact review queue, not repeated full plans and page images.\n\n### Hard recognition gate\n\nFor every system, record five `staff_line_y` values, its clef, and stable `system_id`. Bind every note through `staff_geometry_id`. Every scoped measure/hand needs exactly one `measure_symbol_check`, including rest-only measures with zero noteheads. Verify scope, staff geometry, pitch geometry, accidentals, rhythm, ties, chord membership, and anchors before setting the corresponding gate to `true`.\n\nRun before any fingering calculation:\n\n```bash\npython3 scripts/validate_recognition.py fingering-plan.json\n```\n\nThe validator derives the natural pitch from clef and staff geometry, then checks spelling, MIDI, ties, geometry, review state, and the fact lock. `--allow-review` is diagnostic only and never authorizes generation. An anchor is valid only when its center crosses a real oval notehead, not a rest block, stem, or beam.\n\nDo not redraw a supplied PDF/image or replace it with image generation. Overlay vector finger numbers on the original page.\n\n### MusicXML, MXL, and MuseScore\n\n```bash\npython3 scripts/create_plan_from_musicxml.py input.musicxml -o fingering-plan.json\n```\n\nMXL is supported directly. If MusicXML has no layout coordinates, always deliver fingered MusicXML and add PDF only when the host can render a verifiable score page. Do not claim that this Skill contains a full MusicXML engraving engine or require MuseScore. Read `.mscx` as XML and convert its semantics; read `.mscz` only when the host can unpack it, otherwise ask for MusicXML export.\n\n## Unified identity and coordinates\n\nUse a single plan throughout. Every note must have a stable `note_id` and separate:\n\n- `keyboard_x_cm`: physical key-center position used by the fingering algorithm;\n- `page_x/page_y`: original notehead center used by the overlay;\n- MusicXML identity: `part + measure_index + staff + voice + onset + pitch_midi + chord_row`.\n\nFor PDF/image delivery run:\n\n```bash\npython3 scripts/validate_fingering_plan.py fingering-plan.json --require-coordinates\npython3 scripts/validate_fingering_plan.py fingered-plan.json --require-verified-anchors\n```\n\nDerive `keyboard_x_cm` only from `pitch_midi` with the bundled `keypos_midi`; never estimate it from page position or note-name text. Physical key positions must increase strictly with MIDI pitch, and enharmonic spellings must map to the same key.\n\n## Generate fingering\n\n```bash\npython3 scripts/generate_fingering_plan.py fingering-plan.json -o fingered-plan.json\n```\n\nFor a local correction:\n\n```bash\npython3 scripts/generate_fingering_plan.py locked-plan.json -o fingered-plan-v2.json --measure-range 49-52 --context-measures 1\npython3 scripts/generate_fingering_plan.py patched-fingered-plan.json -o fingered-plan-v2.json --changed-only --context-measures 1\n```\n\nContext measures are read-only; preserve all fingerings and manual corrections outside the target. Use hand size `XXS`, `XS`, `S`, `M`, `L`, `XL`, or `XXL`; default to `M`. With `lookahead=0`, select 3–8 events automatically. Use `--max-auto-depth 9` only for a deliberately slow final search. Use `--ignore-existing` only when the user explicitly requests it, and at most once per task.\n\nThe adapted PianoPlayer core scores key distance, duration, finger strength, black-key tendencies, span, chord ordering, lookahead, and existing fingering anchors. It also penalizes skipped adjacent fingers in scalar motion, excessive `2->1` crossings, and premature use of finger 5 while a melody continues in the same direction. The output is an executable draft, not final musical truth.\n\n## Musical review\n\nApply [references/professional-fingering-rules.md](references/professional-fingering-rules.md) in priority order. Remove hard violations first, then review full phrases and cross-measure transitions:\n\n- favor relaxed movement, continuity, stable positions, and preparation for what follows;\n- avoid the same finger on successive different pitches in legato;\n- do not trap a scale on finger 5 without preparation;\n- require a contextual reason for thumb crossings, substitutions, skips, and shifts;\n- give chords non-conflicting fingers ordered by pitch;\n- preserve the same mapping for structurally identical double notes or chords when the whole hand can shift;\n- review left-hand bass–chord–next-bass as one motion; an outer bass below the following dyad normally uses finger 5;\n- keep the same finger across tied identical notes unless an explicit silent substitution is marked and verified;\n- keep repeated accompaniment pitches and structural slots consistent unless an explained `repeated_note` or `substitution` exception exists;\n- preserve `locked=true` fingerings and review handoffs, simultaneities, and collisions.\n\nFor manual corrections set `source=reviewed`, write `transition_type` and `exception_reason`, add the applicable `rule_id`, and set `exception_verified=true` only after note-by-note review. Recognition or structural errors must be fixed; musical preference warnings may remain as review items.\n\n## Write back and render\n\n```bash\npython3 scripts/apply_fingerings.py input.musicxml fingered-plan.json -o fingered.musicxml\npython3 scripts/render_fingering_pdf.py fingered-plan.json --source input.pdf -o fingered-score.pdf\n```\n\nPlace right-hand labels above noteheads in dark blue and left-hand labels below their own staff in dark red; never let left-hand labels enter the next system. Keep labels visibly clear of notes and notation. Use `label_x`, `label_offset`, and `font_size` only where ownership remains unambiguous.\n\nFor chords use `chord_label_layout=\"stacked\"`, one shared `chord_label_x`, and vertical order matching `chord_row`. Never scatter one chord's finger numbers diagonally, which can imply sequential attacks. Also deliver a PNG preview for image/PDF input.\n\nFor anchor inspection, render source pages to images, store them in `pages[].image`, then run:\n\n```bash\npython3 scripts/audit_overlay_anchors.py fingered-plan.json -o anchor-audit\n```\n\n## Final verification\n\n```bash\npython3 scripts/verify_output.py fingered-plan.json fingered-score.pdf\n```\n\nRender the final PDF to images and compare every page with the source. Confirm correct note/chord ownership, no missing or duplicate labels, no crop or page-order change, no collision with noteheads/accidentals/stems/beams/ties, natural cross-measure fingering, and a reopenable PDF with the correct page count.\n\nRequire evidence for all five states: `recognition_verified`, `pitch_geometry_verified`, `ties_verified`, `fingering_rules_verified`, and `placement_verified`. Fix only dirty measures/pages, run local checks, then perform one final whole-score pass. Limit automatic collision repair to two rounds and never create free alternating vertical offsets within one continuous group.\n\nCreate the report:\n\n```bash\npython3 scripts/create_delivery_report.py fingered-plan.json -o result-report.md --pdf fingered-score.pdf --preview fingered-score.png\n```\n\nReport delivery level, scope, recognized and fingered note counts, coverage, low-confidence notes, collisions, and remaining review measures. A complete result requires 100% scoped coverage and zero collisions. Deliver available files even when the result is review-required or partial, and add short practice guidance for crossings, shifts, and leaps.\n\nFile v0.1.0:_meta.json\n\n{\n  \"ownerId\": \"kn775p024j3fvm7wzg9ge615a187t6nv\",\n  \"slug\": \"piano-score-fingering\",\n  \"version\": \"0.1.0\",\n  \"publishedAt\": 1786868534885\n}\n\nFile v0.1.0:references/common-fingering-errors.md\n\n# Common Fingering Errors\n\nUse this as a counterexample checklist after the first fingering pass and again before rendering. For evidence, priorities, exceptions, and implementation limits, see [professional-fingering-rules.md](professional-fingering-rules.md).\n\n## 0. Correct-looking fingering on the wrong pitch\n\n- **Error:** notehead geometry shows a second, but the plan records a third and assigns the left-hand dyad `3-1`.\n- **Fix:** run `validate_recognition.py` and derive pitch from staff geometry and clef. Block every pitch/geometry contradiction before fingering.\n- Never bypass recognition gates with confidence scores, coverage, or a successfully generated PDF.\n\n## 1. Missing a tightly spaced chord member\n\n- **Error:** two adjacent noteheads around one stem become one event, so a three-note chord receives only `1-5`.\n- **Fix:** inspect seconds at high zoom, bind every visible notehead, and assign the complete chord, such as `1-2-5`.\n- Finger-label count must equal visible notehead count.\n\n## 2. Meaningless changes in an isomorphic transposed pattern\n\n- **Error:** structurally identical dyads use `1-5, 1-5, 1-4`.\n- **Fix:** keep `1-5, 1-5, 1-5` and move the hand as a unit. Change only for a documented continuation, articulation, key-shape, or span reason.\n\n## 3. Reassigning an unchanged moving dyad\n\n- **Error:** a comfortable dyad that can shift laterally uses `1-3, 1-4, 1-5`.\n- **Fix:** preserve one shape, for example `1-5, 1-5, 1-5`, and review the whole sequence rather than isolated chords.\n\n## 4. Skipping an available adjacent finger in scalar motion\n\n- **Error:** a descending step uses `5-3` even though finger 4 is free and natural.\n- **Fix:** prefer `5-4`. Skip only to prepare what follows or avoid an ergonomic problem, and record the reason.\n\n## 5. Reusing one finger on successive different pitches\n\n- **Error:** a connected melody repeatedly uses the same finger without a planned crossing or shift.\n- **Fix:** use adjacent fingers, a prepared crossing, or an explicit lateral shift. Staccato, repeated notes, or intentionally detached leaps may be exceptions.\n\n## 6. Finger distance does not match the dyad interval\n\n- **Error:** every dyad receives `1-5` or left-hand `5-1`, unnecessarily stretching a third.\n- **Fix:** begin with adjacent fingers for seconds, `1-3` (left hand low-to-high `3-1`) for thirds, `1-4` for fourths, and `1-5` for fifths or wider. Context may justify `2-4` or `3-5`, but the hand must stay relaxed and the reason must be recorded.\n\n## 7. A single note competes with the next chord for the same finger\n\n- **Error:** left-hand bass 3 leads directly to a third with `3-1`, producing `3 -> 3-1`.\n- **Fix:** inspect the full transition. A bass below the chord normally uses 5, producing `5 -> 3-1`. Check single-to-chord and chord-to-single transitions finger by finger.\n\n## 8. Copying a bad template through a repeated pattern\n\n- **Error:** `5-4-1` is copied across every wide descending three-note group without validating the first group.\n- **Fix:** verify interval geometry and hand shape first; a wide descending group often favors outer–middle–thumb, such as right-hand `5-3-1`. Consistency may amplify only a valid template.\n\n## 9. Unexplained finger changes on repeated accompaniment pitches\n\n- **Error:** the same pitch in the same structural slot changes finger without a repetition technique or preparation need.\n- **Fix:** preserve the finger by default, such as left-hand repeated bass on 5. Exceptions require `repeated_note` or `substitution` plus a reason.\n\n## 10. Changing finger across a tied identical pitch\n\n- **Error:** one tie group uses `2-3` without a silent-substitution reason.\n- **Fix:** place both notes in the same `tie_group` and force the same finger. A real substitution requires `transition_type=substitution`, `rule_id=A4`, `exception_reason`, and `exception_verified=true` after note-level review.\n\n## 11. Treating left-hand bass and dyads in isolation\n\n- **Error:** individually legal dyads create an unstable `4 -> 3-1 -> 3-1` accompaniment motion.\n- **Fix:** review outer bass–dyad–dyad as one unit. Start with bass 5, second `2-1`, or third `3-1`, then adapt to what follows. Any deviation from a stable outer finger or chord shape needs a verified exception.\n\n## 12. Fingering a notehead that does not exist\n\n- **Error:** a stem, beam, or barline creates a sixth event where the score has five noteheads, leaving a floating label.\n- **Fix:** record `event_count_checks` for dense or previously faulty measures and count each page/measure/hand independently. A matching global total does not prove local correctness.\n\n## 13. Mistaking a rest for a note\n\n- **Error:** a whole or half rest is read as a filled notehead and affects the next hand-position search.\n- **Fix:** require an open or filled oval contour for noteheads. Classify rectangular rests, zig-zag rests, stems, beams, barlines, and dots as non-note symbols. In sparse measures, zoom every candidate and record `sparse_symbol_verified=true`. After deleting a false event, recompute at least that measure and the next.\n\n## 14. Inventing a touching chord member from an accompaniment pattern\n\n- **Error:** only one notehead is visible, but a second coordinate is generated from repeated structure or fixed spacing, turning a third into a second and producing `2-1` instead of `3-1` across the page.\n- **Fix:** locate both real oval centers and set `origin=direct_visual_notehead` plus `chord_member_verified=true` for each. Never create members with `page_y +/- 5`, `page_y +/- 10`, or a transposed prior chord. Keep the item unresolved if the image cannot separate it.\n\n## 15. Physical key coordinates run opposite to pitch\n\n- **Error:** equally spacing all semitones makes a higher D receive a smaller `keyboard_x_cm` than a lower B-flat, reversing the search direction.\n- **Fix:** map `pitch_midi` to real white/black key centers and require strict increase across MIDI pitch, including octave boundaries. Block every mismatch before dynamic search.\n\nFile v0.1.0:references/fingering-plan-schema.md\n\n# Unified Fingering Plan Schema\n\nAll scripts read and write one JSON fingering plan. MusicXML supplies score semantics; `notes` also store physical key positions for search and page coordinates for overlay.\n\n## Top-level structure\n\n```json\n{\n  \"schema_version\": \"1.0\",\n  \"source\": {\"type\": \"pdf\", \"path\": \"source.pdf\", \"coordinate_unit\": \"pdf_point\"},\n  \"settings\": {\"hand_size\": \"M\", \"lookahead\": 0},\n  \"pages\": [{\"page\": 1, \"width\": 595.28, \"height\": 841.89}],\n  \"recognition\": {\n    \"status\": \"locked\",\n    \"scope\": \"pages 1-2\",\n    \"expected_note_count\": 128,\n    \"unresolved_note_count\": 0,\n    \"review_confidence_threshold\": 0.8,\n    \"confidence_policy\": {\n      \"require_independent_passes\": 2,\n      \"require_measure_region_coverage\": true,\n      \"require_measure_symbol_checks\": true,\n      \"require_rest_inventory\": true,\n      \"require_direct_notehead_anchors\": true,\n      \"require_dense_event_checks\": true,\n      \"dense_notehead_threshold\": 8,\n      \"require_notehead_shape_evidence\": true,\n      \"require_sparse_rest_checks\": true,\n      \"sparse_event_threshold\": 1,\n      \"require_same_position_evidence\": true,\n      \"require_tie_evidence\": true\n    },\n    \"event_count_checks\": [\n      {\"page\": 1, \"measure\": 12, \"hand\": \"RH\", \"expected_noteheads\": 9,\n       \"source\": \"independent_visual_count\", \"verified\": true}\n    ],\n    \"measure_scope\": [\n      {\"page\": 1, \"measure_start\": 1, \"measure_end\": 23, \"hands\": [\"RH\", \"LH\"]}\n    ],\n    \"measure_regions\": [\n      {\"region_id\": \"p1-m12-rh\", \"page\": 1, \"measure\": 12, \"hand\": \"RH\",\n       \"bbox\": [80, 210, 270, 310], \"evidence_crop\": \"crops/p1-m12-rh.png\"}\n    ],\n    \"measure_symbol_checks\": [\n      {\"region_id\": \"p1-m12-rh\", \"page\": 1, \"measure\": 12, \"hand\": \"RH\",\n       \"expected_noteheads\": 9, \"expected_rests\": 0, \"duration_verified\": true,\n       \"source\": \"independent_visual_review\", \"evidence_crop\": \"crops/p1-m12-rh.png\",\n       \"verified\": true}\n    ],\n    \"delivery_level\": \"complete\",\n    \"review_queue\": [],\n    \"fact_lock\": {\n      \"algorithm\": \"sha256-score-facts-v2\",\n      \"digest\": \"generated by manage_recognition.py freeze\",\n      \"note_count\": 128\n    },\n    \"verification\": {\n      \"scope_complete\": true,\n      \"staff_geometry\": true,\n      \"pitch_geometry\": true,\n      \"accidentals\": true,\n      \"rhythm\": true,\n      \"ties\": true,\n      \"chords\": true,\n      \"anchors\": true\n    },\n    \"systems\": [\n      {\"system_id\": \"p1-system1-rh\", \"page\": 1, \"staff\": 1, \"clef\": \"treble\",\n       \"staff_line_y\": [246, 256, 266, 276, 286]}\n    ]\n  },\n  \"notes\": [],\n  \"rests\": []\n}\n```\n\n`source.type` is `pdf`, `image`, or `musicxml`. With `lookahead=0`, the generator selects 3–8 events automatically; use `--max-auto-depth 9` for a slow final search or set `lookahead=3–9` explicitly.\n\n`recognition.delivery_level` is `complete`, `review`, or `partial`. Before image/PDF fingering generation, all eight verification gates must be true and `unresolved_note_count` must be zero. Record `systems[].staff_line_y` from visually top to bottom; coordinate direction depends on the source coordinate system. Use `treble` or `bass`, or provide `top_line_step` and `top_line_octave` for other/transposing clefs.\n\n`recognition.status` progresses through `draft`, `review`, `verified`, and `locked`; generation accepts only `locked`. `manage_recognition.py freeze` creates `fact_lock` over semantics, staff geometry, note/rest coordinates, crop evidence, and independent counts, deliberately excluding fingering and label layout. Any later fact change invalidates the digest.\n\n`review_queue` contains local visual-review exceptions. Each entry has a stable `review_id`, `status` (`open` or `resolved`), `page`, `measure`, `hand`, `note_ids`, and `reason`. A plan with open items cannot be locked. Merge the queue by page + measure + hand rather than creating hundreds of repeated note-level messages.\n\nIndependent-pass policy means rerunning the same detector is not new evidence. Each note must meet `recognition_passes`; dense regions need a verified count, and same-position neighbors or visual ties need explicit evidence.\n\nUse scoped patches for local corrections. At least one of page, measure, or hand must be limited, and operations outside the scope are rejected:\n\n```json\n{\n  \"reason\": \"Measure 52 RH has five visible noteheads; remove the false event\",\n  \"scope\": {\"pages\": [3], \"measures\": [52], \"hands\": [\"RH\"]},\n  \"operations\": [\n    {\"op\": \"delete\", \"note_id\": \"p3-m52-rh-06\"},\n    {\"op\": \"replace\", \"note_id\": \"p3-m52-rh-05\",\n     \"changes\": {\"pitch_midi\": 86, \"pitch_step\": \"D\", \"pitch_octave\": 6}}\n  ],\n  \"recognition_changes\": {\"expected_note_count\": 888, \"unresolved_note_count\": 0}\n}\n```\n\nAllowed operations are `replace`, `delete`, and `add`. `replace` must preserve the stable `note_id`. Structural, pitch, rhythm, tie, chord, or coordinate changes automatically revoke affected gates, which must be explicitly reconfirmed against the source.\n\n`event_count_checks` are extra independent local counts for dense or previously faulty regions. `measure_scope`, `measure_regions`, and `measure_symbol_checks` form the complete visual-recognition gate: every scoped page + measure + hand requires one unique region and one independent check, including rest-only measures with zero expected noteheads. Inspect `evidence_crop` before entering expected counts; never copy observed plan totals. `build_measure_review_manifest.py build` intentionally leaves expected fields blank.\n\nMusicXML semantic input does not require page geometry, but it must verify `pitch_spelling`, `rhythm`, `ties`, and `chords`; `create_plan_from_musicxml.py` supplies these automatically.\n\n## Note fields\n\nEach note contains:\n\n```json\n{\n  \"note_id\": \"P1-M12-S1-V1-T8-N64-C0\",\n  \"part\": \"P1\", \"measure\": \"12\", \"measure_index\": 12,\n  \"staff\": 1, \"voice\": \"1\", \"onset\": 8.0, \"duration\": 2.0,\n  \"pitch_midi\": 64, \"pitch_step\": \"E\", \"pitch_alter\": 0, \"pitch_octave\": 4,\n  \"event_index\": 27,\n  \"chord_id\": \"P1-M12-T8-S1\", \"chord_row\": 0, \"chord_size\": 1,\n  \"hand\": \"RH\", \"keyboard_x_cm\": 86.42,\n  \"page\": 2, \"page_x\": 620.5, \"page_y\": 418.2,\n  \"staff_geometry_id\": \"p1-system1-rh\",\n  \"anchor_verified\": true, \"anchor_method\": \"visual_notehead\",\n  \"pitch_geometry_verified\": true,\n  \"symbol_class\": \"notehead\", \"notehead_shape_verified\": true,\n  \"origin\": \"direct_visual_notehead\", \"chord_member_verified\": true,\n  \"recognition_passes\": 2, \"same_position_verified\": true,\n  \"tie_evidence\": \"visual_tie\", \"tie_group\": null,\n  \"tie_start\": false, \"tie_stop\": false,\n  \"finger\": 3, \"placement\": \"above\", \"locked\": false, \"source\": \"generated\"\n}\n```\n\nAdd `confidence` (0–1) and `review_reason` when visual recognition is uncertain. Any uncertainty affecting pitch, clef, accidental, hand, chord membership, voice, or tie remains in recognition and blocks generation. Only non-semantic layout uncertainty may proceed as review-required.\n\n`recognition_passes` counts independent recognition/review passes. Adjacent same-`page_y` notes require `same_position_verified=true` to distinguish repetition/tie from accidental-driven pitch differences. Use `tie_evidence=visual_tie` or `visual_slur` for visible connections and `source_semantic` for structured sources.\n\nEvery real image/PDF note uses `symbol_class=notehead` and `notehead_shape_verified=true`, proving that the candidate center crosses an open or filled oval, not a rest, stem, beam, barline, or dot. In measures at or below `sparse_event_threshold`, verify every candidate with `sparse_symbol_verified=true`.\n\n`origin=direct_visual_notehead` forbids pattern-inferred notes. When `chord_size>1`, each member needs its own coordinates and `chord_member_verified=true`; declared size must equal the evidence-backed member count.\n\n## Rest fields\n\nRests never enter `notes`; store them in top-level `rests`:\n\n```json\n{\n  \"rest_id\": \"p2-m35-rh-rest-0\", \"page\": 2, \"measure_index\": 35,\n  \"hand\": \"RH\", \"page_x\": 816.0, \"page_y\": 241.0,\n  \"rest_type\": \"whole\", \"duration\": 6.0,\n  \"symbol_class\": \"rest\", \"rest_shape_verified\": true\n}\n```\n\nUse explicit `rest_type` values such as `whole`, `half`, `quarter`, or `eighth`; `duration` follows the plan's beat units. A rest-only measure needs a verifiable rest record and must not be represented merely by missing notes.\n\nFor vertically stacked chord labels, give members the same `chord_label_x`, `chord_label_offset`, and `chord_label_layout: \"stacked\"`. The renderer orders labels from low to high by `chord_row`. Both label offsets use source-page coordinate units and scale with the output page.\n\n## Coordinate rules\n\n- `keyboard_x_cm` is the physical key-center position used only by the fingering algorithm.\n- `page_x/page_y` is the notehead center used only by original-page overlay.\n- `pdf_point` uses a bottom-left origin; `pixel_top_left` uses a top-left origin and is converted by the renderer.\n- MusicXML has no page coordinates. Preserving a source layout requires a corresponding PDF/image plus completed coordinates.\n- PDF/image delivery requires `page`, `page_x`, and `page_y`; estimated staff positions cannot replace notehead centers.\n- Set `anchor_verified=true` only after a zoomed crosshair intersects a real notehead. `anchor_method` may be `visual_notehead`, `detected_notehead`, or `layout_source`.\n- Set `pitch_geometry_verified=true` only when `page_y`, staff geometry, clef, and pitch agree.\n- Equal measure subdivision, proportional estimates, or copied-system coordinates may seed a search but can never be marked verified.\n- Compute `keyboard_x_cm` from `pitch_midi` with `keypos_midi`. Adjacent MIDI keys must increase strictly, including B-flat–B–C octave boundaries.\n\n## Stable note identity\n\nPrefer a source MusicXML element `id`. Otherwise derive `note_id` from `part + measure_index + staff + voice + onset + pitch_midi + chord_row`. Never rely only on a measure-local index because polyphony, chords, and grace notes make it unstable.\n\n## Fingering sources and exceptions\n\n- `existing`: supplied by the score; default `locked=true`.\n- `generated`: created by the algorithm.\n- `reviewed`: manually corrected after musical review; include `exception_reason`.\n\nFor unconventional crossings, skips, same-note substitutions, or deviations from a stable accompaniment shape, also set the relevant `rule_id` and set `exception_verified=true` only after note-level review. A generator-written explanation is not self-verifying. Never overwrite `locked=true` unless the user explicitly asks to ignore existing fingering.\n\nFile v0.1.0:references/professional-fingering-rules.md\n\n# Professional Piano Fingering Rules\n\nUse this document as the musical rule hierarchy for draft generation, human review, and exception explanations. `common-fingering-errors.md` contains only counterexamples.\n\n## Evidence scope\n\nOnly full primary papers, author manuscripts, and upstream source code were used. The rules below are original summaries; no paper text or tables are redistributed.\n\n### Sources\n\n- **[P97]** Parncutt, Sloboda, Clarke, Raekallio, and Desain. *An Ergonomic Model of Keyboard Fingering for Melodic Fragments*. Music Perception 14(4), 1997, 341–382. [Author manuscript](https://static.uni-graz.at/fileadmin/_Persoenliche_Webseite/parncutt_richard/Pdfs/PaSlClRaDe97_FingeringModel.pdf). Supports playable/comfortable spans, stretch and compression, position changes, weak fingers, black/white keys, crossings, rhythm, tempo, articulation, register, repetition, and phrase boundaries. The model focuses mainly on monophonic legato fragments and its provisional average-hand weights are not universal.\n- **[AK07]** Al Kasimi, Nichols, and Raphael. *A Simple Algorithm for Automatic Generation of Polyphonic Piano Fingerings*. ISMIR 2007, 355–356. [Full paper](https://archives.ismir.net/ismir2007/paper/000355.pdf). Supports hard constraints for polyphony/chords and joint vertical chord comfort plus horizontal chord-to-chord motion, adjustable by hand size. It does not model substitutions, black/white-key differences, or automatic hand assignment.\n- **[N14]** Nakamura, Ono, and Sagayama. *Merged-output HMM for Piano Fingering of Both Hands*. ISMIR 2014. [Author manuscript](https://eita-nakamura.github.io/articles/Nakamura_etal_MergedOutputHMMForPianoFingering_ISMIR2014.pdf). Supports preserving within-hand voice continuity instead of assigning hands from an instantaneous pitch split. It is a statistical architecture, not a teaching rulebook.\n- **[N19]** Nakamura, Saito, and Yoshii. *Statistical Learning and Estimation of Piano Fingering*. Information Sciences 517, 2020; [open preprint](https://arxiv.org/pdf/1904.10237). Supports multi-event context, systematic performer variation, simultaneous/sustained-note constraints, and multiple acceptable answers. Statistical fit alone does not equal musical quality.\n- **[PP]** Marco Musy. [PianoPlayer](https://github.com/marcomusy/pianoplayer). Engineering basis for hand geometry, motion/duration cost, lookahead, and anchors. It is not a pedagogical authority and has limitations in ornamentation, hand interaction, and crossing cases.\n\nExclude paywalled books, abstract-only papers, previews, blogs, and secondary summaries from the formal evidence base.\n\n## Priority hierarchy\n\nResolve conflicts in this order:\n\n1. user-locked fingering, explicit composer instructions, and established musical intent;\n2. playability and safety hard constraints;\n3. articulation, voice, sustain, and phrase continuity;\n4. relaxed hand shape, motion economy, and preparation;\n5. consistency of repeated structures;\n6. general preferences about weak fingers, black keys, and conventional shapes.\n\nA lower rule never overrules a higher one. Optimize stable, repeatable realization of the whole phrase, not local ease on one note. [P97][N19]\n\n## A. Hard constraints and explainable connections\n\n### A1. One finger per simultaneous key\n\nOne finger cannot depress two different keys at once. Simultaneous notes in one hand require distinct fingers. **Enforced by generator and validator.** [AK07][N19]\n\n### A2. No finger crossing inside a chord\n\nWhen chord pitches rise, right-hand finger numbers normally rise and left-hand numbers normally fall. Right-hand C–E may be `1-3`; left-hand C–E may be `3-1`. **Enforced by generator and validator.** [AK07][N19]\n\n### A3. Fit every interval inside the selected hand's playable span\n\nDiscard candidates outside `MinPrac/MaxPrac`, then compare comfort. Adjust thresholds for hand size and skill; never impose an average adult hand as universal. **Enforced with XXS–XXL hand presets.** [P97][AK07]\n\n### A4. Preserve finger occupancy during sustain\n\nA finger holding a note cannot play another key simultaneously. Keep the same finger by default. Allow same-note substitution only when notation, legato, or explicit review requires it; mark `transition_type=substitution`. Recognized `tie_group` membership is enforced; other cross-event sustain still requires review. [AK07][N19]\n\n### A5. Do not repeat one finger on adjacent different legato pitches without reason\n\nUse an adjacent finger, crossing, or planned shift. Staccato, pedal connection, phrase breaks, or a deliberate color may justify an exception. **Validator warning plus musical review.** [P97]\n\n## B. High-priority scoring rules\n\n### B1. Match finger distance to musical interval\n\nCompare interval distance with finger distance in melody and simultaneity. Begin with adjacent fingers for seconds, right-hand `1-3` / left-hand low-to-high `3-1` for thirds, `1-4` for fourths, and `1-5` / `5-1` for fifths or wider. Override only for black/white-key shape, voice, or continuation and record why. [P97][AK07]\n\n### B2. Penalize both excessive stretch and compression\n\nReachable is not automatically comfortable in repetition. Add cost outside the comfort zone, especially for pairs without the thumb. The algorithm partly scores this; pair-specific comfort and compression still need review. [P97][AK07]\n\n### B3. Minimize the number and size of position changes\n\nPrefer stable positions. When movement is necessary, compare frequency, distance, landing comfort, and preparation for later notes. Never create a large next-beat leap for one locally convenient note. [P97][PP]\n\n### B4. Use at least three events of context\n\nDo not decide from one pair alone. Runs, arpeggios, and shifts must see beyond the next turning point. Use 3–9 events of lookahead. [N19][PP]\n\n### B5. Prefer adjacent fingers in ordinary scalar motion\n\nAvoid unexplained skipped fingers, unless adjacent fingering would create a dead end, trap the hand on finger 5, or damage crossing preparation. [P97]\n\n### B6. Evaluate crossings with direction and key height\n\nThumb crossings are not categorically wrong. White-to-white, black-to-black, thumb-on-black, and directional compression have different costs. Relax only for articulation, pedal, or tempo with an explanation. [P97][AK07]\n\n### B7. Make weak-finger preference subordinate to music and tempo\n\nPenalize unnecessary 4/5 dependence or awkward `3-4-5` coordination, but never ban weak fingers mechanically. Accent, voice projection, stable position, and tempo may require them. [P97]\n\n### B8. Keep the mapping of repeated, sequential, and isomorphic patterns\n\nWhen interval structure, key shape, and continuation match, repeat the same finger sequence to build a stable motor program. Change as a whole group only when tonal shape, phrase target, or landing changes. Current section-level pattern detection requires model review. [P97]\n\n### B9. Place shifts at phrase, rest, articulation, or pedal opportunities\n\nPrefer phrase boundaries, rests, staccato, pedal cover, or structural accents. A legato-optimal fingering need not be staccato-optimal. [P97][N19]\n\n### B10. Evaluate chords vertically and horizontally\n\nCheck internal interval/finger comfort and the complete connection from the previous chord to the next. Do not choose isolated beautiful shapes that connect poorly. The algorithm enforces stable outer-note-to-dyad behavior; larger chords and complex sustains need review. [AK07][N19]\n\n### B11. Review hand assignment through voice continuity\n\nDo not split hands mechanically at middle C or an instantaneous pitch boundary. Preserve each hand's voice, rhythm, and motion and inspect handoff conflicts. [N14][N19]\n\n### B12. Preserve multiple valid answers and individual variation\n\nProfessional performers may choose different acceptable fingerings. Respect anchors, hand size, level, tempo, and user preference. Present alternatives or review flags instead of claiming one universal answer. [P97][AK07][N19][PP]\n\n## Generation and review procedure\n\n1. Lock user/source fingering, voices, articulation, sustains, and coordinate identity.\n2. Remove impossible candidates with A1–A4; make A5 create an explainable warning.\n3. Accumulate local and lookahead costs for B1–B7 and B10.\n4. Review B8, B9, and B11 over a phrase or at least one complete pattern.\n5. For tied or near-tied solutions, apply B12: preserve anchors and choose the most stable; report meaningful alternatives.\n6. Record `exception_reason` whenever retaining a general-rule violation, identifying articulation, voice, tempo, hand size, or preparation.\n\n## Exit checklist\n\n- [ ] Simultaneous notes use distinct, non-crossing fingers.\n- [ ] Every span fits the selected hand; small intervals do not mechanically use `1-5/5-1`.\n- [ ] Sustains, substitutions, and same-finger different notes match articulation.\n- [ ] Every crossing, skip, and shift is explained by at least three surrounding events.\n- [ ] Repeated or sequential patterns do not change fingering meaninglessly.\n- [ ] Shifts occur at musically or physically suitable opportunities.\n- [ ] Chords are comfortable alone and connect naturally.\n- [ ] Hand assignment preserves voices rather than using a crude pitch split.\n- [ ] Fast passages penalize unnecessary motion and awkward shape more heavily.\n- [ ] Locked fingering is preserved and individual variation is treated as a parameter.\n\n## Capability boundary\n\nThe Skill generates and validates an ergonomic draft, but phrase detection, metric accent, pedal, articulation, section-level similarity, and cross-hand redistribution are not all encoded in one optimizer. The host model must review them from the full score, and the report must distinguish algorithmic enforcement from musical review.\n\nFile v0.1.0:skill-card.md\n\n## Description:\n\nReads piano scores from images, PDFs, MusicXML, MXL, or MuseScore files, verifies score facts, generates playable two-hand fingering, and delivers annotated PDF or fingered MusicXML outputs.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[yannxinn](https://clawhub.ai/user/yannxinn)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers, musicians, educators, and score-preparation users can use this skill to verify piano score facts, generate and review two-hand fingering, and produce practice-ready annotated outputs. It is intended for local score-processing workflows that need traceable recognition, fingering review, and delivery reports.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill processes local score files and writes output files, so untrusted MXL, PDF, or image inputs can carry normal local file-processing risk.\n\nMitigation: Run it in a constrained workspace, provide only the score files needed for the task, and avoid using untrusted inputs outside that environment.\n\nRisk: Predictable output paths in shared directories can be vulnerable to local symlink or file-precreation issues.\n\nMitigation: Write outputs to a private task directory and avoid shared directories where other users or processes can create files.\n\nRisk: Incorrect or incomplete score recognition can lead to misleading fingering or misplaced annotations.\n\nMitigation: Use the skill's recognition gates, locked plan workflow, anchor audits, validation scripts, and final visual inspection before relying on generated fingerings.\n\n## Reference(s):\n\n- [Server-resolved source repository](https://github.com/Yannxinn/piano-score-fingering)\n- [ClawHub skill page](https://clawhub.ai/yannxinn/skills/piano-score-fingering)\n- [Professional fingering rules](references/professional-fingering-rules.md)\n- [Fingering plan schema](references/fingering-plan-schema.md)\n- [Common fingering errors](references/common-fingering-errors.md)\n- [PianoPlayer upstream project](https://github.com/marcomusy/pianoplayer)\n- [pypdf upstream project](https://github.com/py-pdf/pypdf)\n- [Parncutt et al. fingering model](https://static.uni-graz.at/fileadmin/_Persoenliche_Webseite/parncutt_richard/Pdfs/PaSlClRaDe97_FingeringModel.pdf)\n- [Al Kasimi et al. piano fingering research](https://archives.ismir.net/ismir2007/paper/000355.pdf)\n- [Nakamura et al. merged-output HMM paper](https://eita-nakamura.github.io/articles/Nakamura_etal_MergedOutputHMMForPianoFingering_ISMIR2014.pdf)\n- [Piano fingering research on arXiv](https://arxiv.org/pdf/1904.10237)\n\n## Skill Output:\n\n**Output Type(s):** [Guidance, Shell commands, JSON, Markdown, MusicXML, PDF, PNG]\n\n**Output Format:** [Markdown workflow guidance with shell commands, JSON plans, fingered MusicXML, annotated PDFs, PNG previews, and delivery reports]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Local file-processing workflow; outputs depend on verified score facts, locked plans, anchor audits, and final visual checks.]\n\n## Skill Version(s):\n\n0.1.0 (source: server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v0.1.0:agents/openai.yaml\n\ninterface:\n  display_name: \"Piano Score Fingering\"\n  short_description: \"Verify score facts, then generate and review two-hand fingering\"\n  default_prompt: \"Use $piano-score-fingering to recognize this piano score measure by measure, lock verified notehead and rest facts, generate fingering, and deliver an annotated PDF.\"\n  icon_small: \"./assets/icon.svg\"\n  icon_large: \"./assets/icon.svg\"\n\nFile v0.1.0:NOTICE.txt\n\nPIANO SCORE FINGERING SKILL - AUTHORSHIP AND THIRD-PARTY NOTICES\n================================================================\n\n1. Original work\n----------------\n\nTitle: Piano Score Fingering Skill\nAuthor and creator: Yanxin Liu\nCopyright (c) 2026 Yanxin Liu. All rights reserved.\n\nThe original design and implementation by Yanxin Liu include the Skill workflow,\nSkill instructions, unified note-identity and dual-coordinate data model,\nscore-image/PDF anchoring process, fingering-plan validation and musical review\nrules, MusicXML integration, original-score PDF overlay workflow, output\nverification, and related adaptations that are not third-party code identified\nbelow.\n\nThis notice identifies authorship and copyright ownership. It does not grant a\npublic license to the original portions of this Skill. A separate license may be\nadded by the author if broader reuse, modification, or redistribution rights are\nintended in the future.\n\n2. Third-party components\n-------------------------\n\nThis distribution contains or adapts the following open-source components.\nTheir original copyright notices and license terms apply only to the relevant\nthird-party portions. They do not transfer ownership of Yanxin Liu's original\nwork and do not imply endorsement by the upstream authors.\n\n2.1 PianoPlayer\n\nProject: https://github.com/marcomusy/pianoplayer\nUpstream branch used: master\nUse in this Skill: adapted hand geometry, candidate fingering search, dynamic\nlook-ahead, keyboard movement cost, hand-size presets, chord constraints, and\nexisting-fingering anchors. PianoPlayer does not provide the image/PDF score\nrecognition or page-coordinate workflow in this Skill.\nLicense: MIT License\n\nMIT License\n\nCopyright (c) 2017 Marco Musy\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\n2.2 pypdf 6.10.0\n\nProject: https://github.com/py-pdf/pypdf\nUse in this Skill: bundled PDF reading and page merging.\nLicense: BSD 3-Clause License\n\nCopyright (c) 2006-2008, Mathieu Fenniak\nSome contributions copyright (c) 2007, Ashish Kulkarni <kulkarni.ashish@gmail.com>\nSome contributions copyright (c) 2014, Steve Witham <switham_github@mac-guyver.com>\n\nAll rights reserved.\n\nRedistribution and use in source and binary forms, with or without\nmodification, are permitted provided that the following conditions are met:\n\n* Redistributions of source code must retain the above copyright notice,\n  this list of conditions and the following disclaimer.\n* Redistributions in binary form must reproduce the above copyright notice,\n  this list of conditions and the following disclaimer in the documentation\n  and/or other materials provided with the distribution.\n* The name of the author may not be used to endorse or promote products\n  derived from this software without specific prior written permission.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\"\nAND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE\nIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE\nARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE\nLIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR\nCONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF\nSUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS\nINTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN\nCONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)\nARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE\nPOSSIBILITY OF SUCH DAMAGE.\n\n2.3 typing_extensions 4.15.0\n\nProject: https://github.com/python/typing_extensions\nUse in this Skill: bundled compatibility module used by pypdf on older Python\nversions.\nLicense: Python Software Foundation License Version 2\n\nPYTHON SOFTWARE FOUNDATION LICENSE VERSION 2\n\n1. This LICENSE AGREEMENT is between the Python Software Foundation (\"PSF\"),\nand the Individual or Organization (\"Licensee\") accessing and otherwise using\nthis software in source or binary form and its associated documentation.\n\n2. Subject to the terms and conditions of this License Agreement, PSF hereby\ngrants Licensee a nonexclusive, royalty-free, world-wide license to reproduce,\nanalyze, test, perform and/or display publicly, prepare derivative works,\ndistribute, and otherwise use the software alone or in any derivative version,\nprovided, however, that PSF's License Agreement and PSF's notice of copyright,\ni.e. \"Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,\n2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021,\n2022, 2023 Python Software Foundation; All Rights Reserved\"\nare retained in the software alone or in any derivative version prepared by\nLicensee.\n\n3. In the event Licensee prepares a derivative work that is based on or\nincorporates the software or any part thereof, and wants to make the derivative\nwork available to others as provided herein, Licensee hereby agrees to include\nin any such work a brief summary of the changes made.\n\n4. PSF is making the software available to Licensee on an \"AS IS\" basis. PSF\nMAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE,\nBUT NOT LIMITATION, PSF MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY\nOF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF\nTHE SOFTWARE WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.\n\n5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF THE SOFTWARE FOR\nANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF\nMODIFYING, DISTRIBUTING, OR OTHERWISE USING THE SOFTWARE, OR ANY DERIVATIVE\nTHEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.\n\n6. This License Agreement will automatically terminate upon a material breach\nof its terms and conditions.\n\n7. Nothing in this License Agreement shall be deemed to create any relationship\nof agency, partnership, or joint venture between PSF and Licensee. This License\nAgreement does not grant permission to use PSF trademarks or trade name in a\ntrademark sense to endorse or promote products or services of Licensee or any\nthird party.\n\n8. By copying, installing or otherwise using the software, Licensee agrees to\nbe bound by the terms and conditions of this License Agreement.\n\nThe complete license history distributed with the installed typing_extensions\npackage is represented by the applicable PSF License Version 2 above. Source\nfiles retain any additional upstream notices required by their licenses.\n\n3. Distribution note\n--------------------\n\nThe research sources used to formulate the professional fingering guidance are\nlisted in references/professional-fingering-rules.md. Those principles are\noriginal Chinese summaries and synthesis by Yanxin Liu's Skill; the papers\nthemselves are not copied into or redistributed with this Skill. Bibliographic\nmention does not imply endorsement by the authors or change the copyright and\nlicense status of the cited publications.\n\nOnly sources whose complete text was accessible during preparation are treated\nas formal evidence in that reference file. Paywalled books, abstracts, previews,\nand secondary summaries are excluded from the formal rule basis.\n\nKeep this NOTICE.txt file with all copies or substantial portions of this Skill.\nDo not remove copyright or license headers from third-party source files.","readmeExcerpt":"Skill: Piano Score Fingering Arrangement Owner: yannxinn Summary: Verify score facts, then generate and review two-hand fingering Tags: latest:0.1.0 Version history: v0.1.0 | 2026-08-16T08:22:14.885Z | auto Piano Score Fingering v0.1.0 - Initial release with support for piano score recognition from images, PDFs, MusicXML, MXL, or MuseScore files. - Preserves exact page coordinates of every notehead and delivers coord","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"python3 scripts/build_measure_review_manifest.py build fingering-plan.json -o measure-review.json\npython3 scripts/build_measure_review_manifest.py apply fingering-plan.json measure-review.json -o review-plan.json"},{"language":"bash","snippet":"python3 scripts/manage_recognition.py queue fingering-plan.json -o review-queue.json --plan-output review-plan.json\npython3 scripts/manage_recognition.py freeze review-plan.json -o locked-plan.json\npython3 scripts/manage_recognition.py status locked-plan.json"},{"language":"bash","snippet":"python3 scripts/manage_recognition.py patch locked-plan.json correction.json -o review-plan.json\npython3 scripts/manage_recognition.py confirm review-plan.json --gates pitch_geometry rhythm chords anchors -o verified-plan.json\npython3 scripts/manage_recognition.py freeze verified-plan.json -o locked-plan-v2.json"},{"language":"bash","snippet":"python3 scripts/validate_recognition.py fingering-plan.json"},{"language":"bash","snippet":"python3 scripts/create_plan_from_musicxml.py input.musicxml -o fingering-plan.json"},{"language":"bash","snippet":"python3 scripts/validate_fingering_plan.py fingering-plan.json --require-coordinates\npython3 scripts/validate_fingering_plan.py fingered-plan.json --require-verified-anchors"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: piano-score-fingering\ndescription: Read piano scores from images, PDFs, MusicXML, MXL, or MuseScore files; preserve the page coordinates of every notehead; generate playable two-hand fingering with the bundled dynamic hand-position search; and deliver an annotated PDF or fingered MusicXML. Use for piano-score recognition, automatic fingering, coordinate-accurate score annotation, fingering review, and practice guidance without requiring PianoPlayer, MuseScore, ReportLab, or online OMR services.\n---\n\n# Piano Score Fingering\n\nComplete the workflow when the host can read files, inspect score pages, run Python, and write output files. Use only the bundled scripts and capabilities already present in the host. Do not require the user to install software, Python packages, browser extensions, or online recognition services.\n\n## Accuracy gates and delivery levels\n\nNever generate fingering from unverified score facts merely to produce an output. Always create inspectable artifacts. Deliver one of these outcomes:\n\n1. **Complete**: process the full requested range and deliver PDF/MusicXML plus a report.\n2. **Review required**: all performance semantics are verified, but non-semantic layout or musical-preference warnings remain; deliver the fingering result and report.\n3. **Partial**: only when the full range cannot be recognized reliably. Complete at least one whole measure or full system and label every output as a partial experiment.\n\nBlock fingering whenever pitch, clef, accidental, rhythm, hand, chord membership, tie, voice, or notehead identity is unresolved. On failure, still deliver the recognition plan, anchor audit, and error report. Historical outputs may reveal prior error types, but must never become recognition truth or a fingering target for a new task.\n\nLoad references only when needed: use [references/professional-fingering-rules.md](references/professional-fingering-rules.md) for musical review, [references/fingering-plan-schema.md](references/fingering-plan-schema.md) when creating or repairing a visual recognition plan, and [references/common-fingering-errors.md](references/common-fingering-errors.md) when a validator or user identifies a matching error. Keep [NOTICE.txt](NOTICE.txt) with every redistributed copy.\n\n## Choose the input path\n\n### PDF or image\n\n1. Make one complete recognition draft. Declare `measure_scope`, then create one `measure_region` for every page + measure + hand, including rest-only measures.\n2. Classify symbols before reading pitch and rhythm. Put noteheads in `notes` and rests in `rests`; never treat stems, beams, barlines, dots, text, or rectangular rest marks as notes.\n3. Record the true center of every visible notehead with `origin=direct_visual_notehead`. Locate every member of a touching chord separately and set `chord_member_verified=true`. Never infer a missing member from spacing or a repeated accompaniment pattern.\n4. Use `pdf_point` coordinates with a bottom-left origin for PDFs and `pixel_top_"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn775p024j3fvm7wzg9ge615a187t6nv\",\n  \"slug\": \"piano-score-fingering\",\n  \"version\": \"0.1.0\",\n  \"publishedAt\": 1786868534885\n}"},{"path":"references/common-fingering-errors.md","content":"# Common Fingering Errors\n\nUse this as a counterexample checklist after the first fingering pass and again before rendering. For evidence, priorities, exceptions, and implementation limits, see [professional-fingering-rules.md](professional-fingering-rules.md).\n\n## 0. Correct-looking fingering on the wrong pitch\n\n- **Error:** notehead geometry shows a second, but the plan records a third and assigns the left-hand dyad `3-1`.\n- **Fix:** run `validate_recognition.py` and derive pitch from staff geometry and clef. Block every pitch/geometry contradiction before fingering.\n- Never bypass recognition gates with confidence scores, coverage, or a successfully generated PDF.\n\n## 1. Missing a tightly spaced chord member\n\n- **Error:** two adjacent noteheads around one stem become one event, so a three-note chord receives only `1-5`.\n- **Fix:** inspect seconds at high zoom, bind every visible notehead, and assign the complete chord, such as `1-2-5`.\n- Finger-label count must equal visible notehead count.\n\n## 2. Meaningless changes in an isomorphic transposed pattern\n\n- **Error:** structurally identical dyads use `1-5, 1-5, 1-4`.\n- **Fix:** keep `1-5, 1-5, 1-5` and move the hand as a unit. Change only for a documented continuation, articulation, key-shape, or span reason.\n\n## 3. Reassigning an unchanged moving dyad\n\n- **Error:** a comfortable dyad that can shift laterally uses `1-3, 1-4, 1-5`.\n- **Fix:** preserve one shape, for example `1-5, 1-5, 1-5`, and review the whole sequence rather than isolated chords.\n\n## 4. Skipping an available adjacent finger in scalar motion\n\n- **Error:** a descending step uses `5-3` even though finger 4 is free and natural.\n- **Fix:** prefer `5-4`. Skip only to prepare what follows or avoid an ergonomic problem, and record the reason.\n\n## 5. Reusing one finger on successive different pitches\n\n- **Error:** a connected melody repeatedly uses the same finger without a planned crossing or shift.\n- **Fix:** use adjacent fingers, a prepared crossing, or an explicit lateral shift. Staccato, repeated notes, or intentionally detached leaps may be exceptions.\n\n## 6. Finger distance does not match the dyad interval\n\n- **Error:** every dyad receives `1-5` or left-hand `5-1`, unnecessarily stretching a third.\n- **Fix:** begin with adjacent fingers for seconds, `1-3` (left hand low-to-high `3-1`) for thirds, `1-4` for fourths, and `1-5` for fifths or wider. Context may justify `2-4` or `3-5`, but the hand must stay relaxed and the reason must be recorded.\n\n## 7. A single note competes with the next chord for the same finger\n\n- **Error:** left-hand bass 3 leads directly to a third with `3-1`, producing `3 -> 3-1`.\n- **Fix:** inspect the full transition. A bass below the chord normally uses 5, producing `5 -> 3-1`. Check single-to-chord and chord-to-single transitions finger by finger.\n\n## 8. Copying a bad template through a repeated pattern\n\n- **Error:** `5-4-1` is copied across every wide descending three-note group without validating the fi"},{"path":"references/fingering-plan-schema.md","content":"# Unified Fingering Plan Schema\n\nAll scripts read and write one JSON fingering plan. MusicXML supplies score semantics; `notes` also store physical key positions for search and page coordinates for overlay.\n\n## Top-level structure\n\n```json\n{\n  \"schema_version\": \"1.0\",\n  \"source\": {\"type\": \"pdf\", \"path\": \"source.pdf\", \"coordinate_unit\": \"pdf_point\"},\n  \"settings\": {\"hand_size\": \"M\", \"lookahead\": 0},\n  \"pages\": [{\"page\": 1, \"width\": 595.28, \"height\": 841.89}],\n  \"recognition\": {\n    \"status\": \"locked\",\n    \"scope\": \"pages 1-2\",\n    \"expected_note_count\": 128,\n    \"unresolved_note_count\": 0,\n    \"review_confidence_threshold\": 0.8,\n    \"confidence_policy\": {\n      \"require_independent_passes\": 2,\n      \"require_measure_region_coverage\": true,\n      \"require_measure_symbol_checks\": true,\n      \"require_rest_inventory\": true,\n      \"require_direct_notehead_anchors\": true,\n      \"require_dense_event_checks\": true,\n      \"dense_notehead_threshold\": 8,\n      \"require_notehead_shape_evidence\": true,\n      \"require_sparse_rest_checks\": true,\n      \"sparse_event_threshold\": 1,\n      \"require_same_position_evidence\": true,\n      \"require_tie_evidence\": true\n    },\n    \"event_count_checks\": [\n      {\"page\": 1, \"measure\": 12, \"hand\": \"RH\", \"expected_noteheads\": 9,\n       \"source\": \"independent_visual_count\", \"verified\": true}\n    ],\n    \"measure_scope\": [\n      {\"page\": 1, \"measure_start\": 1, \"measure_end\": 23, \"hands\": [\"RH\", \"LH\"]}\n    ],\n    \"measure_regions\": [\n      {\"region_id\": \"p1-m12-rh\", \"page\": 1, \"measure\": 12, \"hand\": \"RH\",\n       \"bbox\": [80, 210, 270, 310], \"evidence_crop\": \"crops/p1-m12-rh.png\"}\n    ],\n    \"measure_symbol_checks\": [\n      {\"region_id\": \"p1-m12-rh\", \"page\": 1, \"measure\": 12, \"hand\": \"RH\",\n       \"expected_noteheads\": 9, \"expected_rests\": 0, \"duration_verified\": true,\n       \"source\": \"independent_visual_review\", \"evidence_crop\": \"crops/p1-m12-rh.png\",\n       \"verified\": true}\n    ],\n    \"delivery_level\": \"complete\",\n    \"review_queue\": [],\n    \"fact_lock\": {\n      \"algorithm\": \"sha256-score-facts-v2\",\n      \"digest\": \"generated by manage_recognition.py freeze\",\n      \"note_count\": 128\n    },\n    \"verification\": {\n      \"scope_complete\": true,\n      \"staff_geometry\": true,\n      \"pitch_geometry\": true,\n      \"accidentals\": true,\n      \"rhythm\": true,\n      \"ties\": true,\n      \"chords\": true,\n      \"anchors\": true\n    },\n    \"systems\": [\n      {\"system_id\": \"p1-system1-rh\", \"page\": 1, \"staff\": 1, \"clef\": \"treble\",\n       \"staff_line_y\": [246, 256, 266, 276, 286]}\n    ]\n  },\n  \"notes\": [],\n  \"rests\": []\n}\n```\n\n`source.type` is `pdf`, `image`, or `musicxml`. With `lookahead=0`, the generator selects 3–8 events automatically; use `--max-auto-depth 9` for a slow final search or set `lookahead=3–9` explicitly.\n\n`recognition.delivery_level` is `complete`, `review`, or `partial`. Before image/PDF fingering generation, all eight verification gates must be true and `unresolved_note_count` must be zero. Record `systems[].staff_line_y` from v"},{"path":"references/professional-fingering-rules.md","content":"# Professional Piano Fingering Rules\n\nUse this document as the musical rule hierarchy for draft generation, human review, and exception explanations. `common-fingering-errors.md` contains only counterexamples.\n\n## Evidence scope\n\nOnly full primary papers, author manuscripts, and upstream source code were used. The rules below are original summaries; no paper text or tables are redistributed.\n\n### Sources\n\n- **[P97]** Parncutt, Sloboda, Clarke, Raekallio, and Desain. *An Ergonomic Model of Keyboard Fingering for Melodic Fragments*. Music Perception 14(4), 1997, 341–382. [Author manuscript](https://static.uni-graz.at/fileadmin/_Persoenliche_Webseite/parncutt_richard/Pdfs/PaSlClRaDe97_FingeringModel.pdf). Supports playable/comfortable spans, stretch and compression, position changes, weak fingers, black/white keys, crossings, rhythm, tempo, articulation, register, repetition, and phrase boundaries. The model focuses mainly on monophonic legato fragments and its provisional average-hand weights are not universal.\n- **[AK07]** Al Kasimi, Nichols, and Raphael. *A Simple Algorithm for Automatic Generation of Polyphonic Piano Fingerings*. ISMIR 2007, 355–356. [Full paper](https://archives.ismir.net/ismir2007/paper/000355.pdf). Supports hard constraints for polyphony/chords and joint vertical chord comfort plus horizontal chord-to-chord motion, adjustable by hand size. It does not model substitutions, black/white-key differences, or automatic hand assignment.\n- **[N14]** Nakamura, Ono, and Sagayama. *Merged-output HMM for Piano Fingering of Both Hands*. ISMIR 2014. [Author manuscript](https://eita-nakamura.github.io/articles/Nakamura_etal_MergedOutputHMMForPianoFingering_ISMIR2014.pdf). Supports preserving within-hand voice continuity instead of assigning hands from an instantaneous pitch split. It is a statistical architecture, not a teaching rulebook.\n- **[N19]** Nakamura, Saito, and Yoshii. *Statistical Learning and Estimation of Piano Fingering*. Information Sciences 517, 2020; [open preprint](https://arxiv.org/pdf/1904.10237). Supports multi-event context, systematic performer variation, simultaneous/sustained-note constraints, and multiple acceptable answers. Statistical fit alone does not equal musical quality.\n- **[PP]** Marco Musy. [PianoPlayer](https://github.com/marcomusy/pianoplayer). Engineering basis for hand geometry, motion/duration cost, lookahead, and anchors. It is not a pedagogical authority and has limitations in ornamentation, hand interaction, and crossing cases.\n\nExclude paywalled books, abstract-only papers, previews, blogs, and secondary summaries from the formal evidence base.\n\n## Priority hierarchy\n\nResolve conflicts in this order:\n\n1. user-locked fingering, explicit composer instructions, and established musical intent;\n2. playability and safety hard constraints;\n3. articulation, voice, sustain, and phrase continuity;\n4. relaxed hand shape, motion economy, and preparation;\n5. consistency of repeated structures;\n6. general pref"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Verify score facts, then generate and review two-hand fingering Skill: Piano Score Fingering Arrangement Owner: yannxinn Summary: Verify score facts, then generate and review two-hand fingering Tags: latest:0.1.0 Version history: v0.1.0 | 2026-08-16T08:22:14.885Z | auto Piano Score Fingering v0.1.0 - Initial release with support for piano score recognition from images, PDFs, MusicXML, MXL, or MuseScore files. - Preserves exact page coordinates of every notehead and delivers coord","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1713,"uniquenessScore":53,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T09:30:11.553Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T09:30:11.553Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T11:54:55.752Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}