docs: constitution status drift — .2dm write + Phase-5 mutation API shipped but constitution says "future"

[domattioli]

Problem

.specify/memory/constitution.md (the supreme governance doc — CLAUDE.md defers to it) has two factual status statements that are now wrong, plus one overstated claim:

1. L67 — Principle VI: SMS 2DM: Secondary; read support mandatory, write support future

   • Wrong. _write_2dm ships (src/chilmesh/CHILmesh.py:2508) and save(".2dm") dispatches to it (:2472). Write support is shipped, and as of this rotation tested (tests/test_2dm_roundtrip.py, 12 round-trip cases, development 158c018).

2. L26 — Mutation API: Topology changes (split, merge, insert_vertex) are explicitly opt-in via future Phase 5: Mutation API

   • Wrong (status). src/chilmesh/mutations.py ships the full API (split_triangle, swap_edge, merge_elements, remove_vertex, collapse_edge, move_boundary_node, split_triangles, smooth_topology) — Phase 5: Mesh mutation API (split, merge, swap, insert) #94 closed/shipped, also reflected in the README roadmap. The read-only-default semantics may still hold, but "future Phase 5" is stale.

3. Overstated claim (surfaced by the new round-trip test): the constitution describes .2dm roundtrip as lossless, but _write_2dm serializes only node coords + element connectivity — not boundary-segment metadata. Lossless for geometry/topology; boundary records are dropped. The wording should qualify this.

Why this is filed, not fixed

Per the per-repo operator directive, autonomous routine sessions do not unilaterally rewrite governance docs (the constitution outranks CLAUDE.md). The sanctioned fix is an operator pass or speckit-constitution update that keeps dependent templates in sync. First flagged for the 2dm half on #201 (2026-06-09); still present, hence this focused record.

Suggested edits (for the operator/speckit pass)

• L67 → SMS 2DM: Secondary; read + write support shipped (write drops boundary metadata).
• L26 → drop "future"; mark Phase 5 Mutation API as shipped (Phase 5: Mesh mutation API (split, merge, swap, insert) #94), keep the read-only-default framing.
• Qualify any ".2dm roundtrip lossless" wording to "lossless for geometry + topology; boundary metadata not serialized".

Filed by the CHILmesh hour-10 rotation (maintenance track). Not auto-fixable — governance-doc edit.

[model: claude-opus-4-8, repo: CHILmesh, session: 2026-06-22T10Z-rotation, refs: #94, #201]

[domattioli]

Code-docstring half addressed on development (22c6565, rolls into PR #227).

• Class docstring L41 roundtrip lossless → now qualifies .2dm as geometry+topology only (boundary/nodestring metadata dropped).
• _write_2dm docstring expanded to state the limitation + ref this issue.

Verified: _write_2dm writes only ND coords + E3T/E4Q connectivity — no boundary records. Doc-only change (py_compile clean; no executable delta).

Still operator-gated → the constitution edits (L67 Principle VI, L26 Mutation API "future Phase 5", "lossless" qualifier). Autonomous sessions don't rewrite the supreme governance doc — needs an operator / speckit-constitution pass keeping dependent templates in sync. Leaving this issue open for that half.

[model: claude-opus-4-8, repo: CHILmesh, session: 2026-06-22T18Z-rotation, refs: #94, #201]

---

Generated by Claude Code

[domattioli]

LABEL-FLIP PROPOSAL — status: brainstorming → status: needs-operator

• Why flip now

  ▸ All three drifts re-verified live this session against v1.4.1

    a. `constitution.md:26` + `:123` — "future **Phase 5: Mutation API**" / "opt-in via Phase-5 mutation APIs (#94) after v1.0", but `src/chilmesh/mutations.py` ships (40 `def`s, #94 closed) and the repo is v1.4.1, already past v1.0.
  
    b. `constitution.md:67` — "SMS 2DM: Secondary; read support mandatory, **write support future**", but `_write_2dm` ships (`CHILmesh.py:2541`, dispatched from `:2505`) and `.2dm` write is tested (`test_2dm_roundtrip.py`).
  
    c. the ".2dm roundtrip lossless" wording is overstated — `_write_2dm` serializes node coords + connectivity only, dropping boundary-segment metadata (lossless for geometry+topology, not boundary records).
  

  ▸ Not routine-fixable — this is why it is not a brainstorm-in-progress

    ↪ the fix edits `.specify/memory/constitution.md`, the supreme governance doc CLAUDE.md defers to; per the per-repo directive autonomous sessions do not rewrite governance docs, so the sanctioned path is an operator pass or `/speckit-constitution` (which keeps dependent templates in sync).
  

• What is needed from the operator

  ↪ Apply the three edits docs: constitution status drift — .2dm write + Phase-5 mutation API shipped but constitution says "future" #228 already specifies — drop "future" on :26/:67, mark the Phase-5 Mutation API shipped (Phase 5: Mesh mutation API (split, merge, swap, insert) #94), and qualify the ".2dm lossless" wording to "lossless for geometry + topology; boundary metadata not serialized" — ideally via /speckit-constitution so dependent templates stay in sync. No code change; governance-doc edit only.

[model: claude-opus-4-8, repo: CHILmesh, session: 013NhKuhHJwC9wmmysELCufc]

---

Generated by Claude Code