add-mps-concept-encoding: §1, §3-§7 — hierarchical polysemy example, demo, docs

[jascal]

Summary

Lands the rung-1 companion to larql-polysemantic-clusters: a 12-concept two-level hierarchy (3 super-groups × 2 sub-clusters × 2 concepts) prepared as bond-dimension-2 matrix product states via a Ry; CNOT; Ry; CNOT; Ry staircase on a 3-qubit register.

The CNOT staircase entangles adjacent qubits, lifting the flat block diagonal of rung 0 into a graded two-level hierarchy. The Gram matrix splits into four ordered tiers — self 1.000 / sub-cluster-mate 0.882 / super-group-sibling [0.47, 0.54] / cross-group [0.12, 0.25] — one tier richer than rung 0.

This PR completes the implementation phase of the add-mps-concept-encoding change started by #45 (which shipped the compute_concept_gram_mps helper in §2). Sections 1, 3, 4, 5, 6, 7 are now landed; only §8 (archive) remains for after merge.

What ships

• examples/larql-polysemantic-hierarchical.q.orca.md — 15 states, 25 transitions, 2 parametric actions. 13 query/prepare call sites stamped from a single bond-2 MPS template. Leading paragraph documents the angle design, analytic per-tier band table, an ASCII Gram heatmap, and the polysemy column for |f⟩ = |dog⟩. Uses measurement_collapse_allowed for the convergent done [final] state.

• demos/larql_polysemantic_hierarchical/demo.py — parse + verify → compile (Mermaid + QASM + Qiskit) → 12 independent Qiskit circuits at 1024 shots each. Prints the analytic Gram matrix as a 4-tier ASCII heatmap, compares empirical vs. analytic polysemy, prints a side-by-side rung-0 vs rung-1 comparison.

• tests/test_examples.py — test_larql_polysemantic_hierarchical_pipeline pins parametric-action signature shape on both prepare_concept and query_concept (three angle params each), 12 query call sites, qubit[3] q; in QASM, QuantumCircuit(3) plus 39 ry / 26 cx in the Qiskit script, diagonal == 1, and the four off-diagonal tiers with strict sub→super (≥ 0.20) and super→cross (≥ 0.15) separation.

• README.md — new "Hierarchical polysemy" sub-heading under "Parametric actions" linking the example, demo, and back to larql-polysemantic-clusters as the flat-tier variant. Examples table grows the new entry.

• CHANGELOG.md — Unreleased / Added bullet covering the new example, demo, and compute_concept_gram_mps helper coverage.

• openspec/changes/add-mps-concept-encoding/tasks.md — marks tasks 1.1–1.3, 3.1–3.3, 4.1–4.3, 5.1–5.4, 6.1–6.3, 7.1–7.4 done with measured-result completion notes (per the §5.1 convention from tech-debt-backlog).

Test plan

• pytest — 771 passed, 6 skipped (full suite, including the new pipeline test)
• Ruff clean across touched files
• openspec validate add-mps-concept-encoding --strict passes
• Demo run locally PASSes (max_err 0.0225 < threshold 0.0469 = 3·MC-std bound at 1024 shots)
• Four-tier Gram structure recovered with the expected separation gaps (sub→super 0.347, super→cross 0.222)
• CI green on the PR

🤖 Generated with Claude Code