docs: record 2026-07 API decisions and archive the phase execution plans

[yingjerkao]

Adds docs/dev/api-decisions.md — a contributor-facing record of the API rulings made on 2026-07-06 (resolving #934/#753/#675, #676, #335/#336/#381 + #421/#422, #293) and the issue-thread consensus positions implemented this cycle (#846/#841, #724, #836), each linked to the implementing PRs (#997, #998, #1000, #1001, #1005).

Also archives the three phase execution plans under docs/dev/plans/ as historical records, clearly marked as such (they contain machine-specific paths from the agent sessions that executed them and are not build instructions).

Docs-only; no code changes. Independent of all open chains — merge anytime. If any linked PR's scope changes materially before merging, this file should be updated in that PR.

🤖 Generated with Claude Code

[gemini-code-assist]

Warning

Gemini encountered an error creating the review. You can try again by commenting /gemini review.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 30.92%. Comparing base (b5db6b8) to head (a700a08).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1006   +/-   ##
=======================================
  Coverage   30.92%   30.92%           
=======================================
  Files         229      229           
  Lines       34760    34760           
  Branches    14398    14398           
=======================================
  Hits        10749    10749           
  Misses      16708    16708           
  Partials     7303     7303           

Flag	Coverage Δ
cpp	30.43% <ø> (ø)
python	59.41% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Components	Coverage Δ
C++ backend	32.25% <ø> (ø)
Python bindings	17.28% <ø> (ø)
Python package	59.41% <ø> (ø)

---

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update b5db6b8...a700a08. Read the comment docs.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[pcchen]

Code Review (docs-only)

Adds docs/dev/api-decisions.md and archives the three phase execution plans under docs/dev/plans/ with a README. No code. Genuinely useful contributor-facing record — well-organized, accurate to the implementing PRs (norm/underscore/permute and the combineBond flip match what's in #1000), and consensus positions are correctly attributed (@IvanaGyro/#846, @manuschneider + @ianmccul/#724). The PR body's note — "if any linked PR's scope changes materially before merging, this file should be updated in that PR" — is the right mechanism and covers the "keep in sync with in-flight PRs" concern, so I'm treating the rest as notes rather than blockers.

Notes

1. Item 1 is currently contested on its own linked issue. The preamble says treat these as settled "unless a maintainer reopens the discussion in the linked issue" — and @ianmccul has done exactly that on #997, arguing UniTensor + UniTensor / - UniTensor are essential vector-space operations and that the removal is inverted (keep T±T; remove T±scalar / scalar/T, per #934's own list). Given your stated update-on-scope-change process, this will get reconciled when #997 lands — but since the flat assertion "elementwise UniTensor ⊙ UniTensor is not a meaningful tensor-network operation" is the exact point under dispute, consider softening item 1 now to "proposed — see the #997 thread" so the record doesn't read as settled ahead of the discussion. Your call.

2. 🟢 Minor — archived plans carry session artifacts. They embed a personal machine path (/Users/yjkao, e.g. phase0:23, phase1:15, phase2:28) and agent/skill directives ("REQUIRED SUB-SKILL: Use superpowers:…") that are meaningless to human contributors. The README appropriately marks them historical/non-authoritative, which mostly covers it; optionally scrub the absolute paths. No secrets/tokens/keys present (checked).

Verdict

Docs-only and low-risk; the sync caveat handles the in-flight-PR concern. The only substantive editorial call is whether to soften item 1's "settled" framing while #997 is actively disputed — recommended but non-blocking, and reconcilable later per your stated process. LGTM with that one note.

Posted by Claude Code on behalf of @pcchen

[pcchen]

Approving. Docs-only, low-risk, and a genuinely useful contributor-facing record — accurate to the implementing PRs and correctly attributed. The PR body's "update this file if a linked PR's scope changes materially before merging" is the right sync mechanism.

One non-blocking note (your call, reconcilable later per that process): item 1's flat "elementwise UniTensor ⊙ UniTensor is not a meaningful tensor-network operation" is the exact point @ianmccul is disputing on #997, so consider softening it to "proposed — see #997" while that discussion is open. Also optional: scrub the /Users/yjkao machine paths from the archived plans (README already marks them historical; no secrets present).

Posted by Claude Code on behalf of @pcchen