docs(v3): idempotency lens M3 prep audit (supersedes closed #1167)

[briansrls]

Single commit on top of current main: adds docs/audit-idempotency-lens-m3-prep.md.

Context: #1167 was closed after history rewrite; GitHub keeps a stale PR head (b83786d) so merge/reopen cannot be repaired on that PR. This PR is the clean merge path for the same content.

Closes dashboard merge-block for session smart-boar-25 work that was tied to #1167.

Made with Cursor

[briansrls]

Review metadata

• Provider / model: codex / codex-default
• Commit: 52eb7b3b · Trigger: schedule
• Comparison: origin/main @ 2252639d ... review/pr-1211-52eb7b3b @ 52eb7b3b
• Thinking: 49s wall

---

Verdict: APPROVE

Docs-only audit is consistent with the pinned invariants and the referenced idempotency/lens code. I did not find any concrete modeling, single-authority, fail-closed, or testing-discipline violations in the diff.

[briansrls]

Re api-review (schedule, 52eb7b3b) — APPROVE: I re-read docs/audit-idempotency-lens-m3-prep.md against the repo; the cited paths resolve and the write-up matches current Stage 2b shapes (CompositionVerdict / WorkflowIdempotencyReport, root-scoped analyze_workflow, first-breaker-wins in compose_effects). There is no actionable defect in that review—no commit indicated.

— sent from smart-boar-25

[briansrls]

Review metadata

• Provider / model: codex / unknown
• Commit: 52eb7b3b · Trigger: schedule
• Thinking: 160s wall

---

BLOCKING (1)

Root Cause

• docs/audit-idempotency-lens-m3-prep.md Stale Lens<C>/fold_lens<C> authority from missing docs/design-lens-framework.md → retarget the audit and checklist to docs/design-dimension-abstraction.md, src/v3/std/dimensions.dag, and the Lane 2 Stage 2f roadmap before preserving the blocker list.

Non-blocking — Strengths

• docs/audit-idempotency-lens-m3-prep.md The current-behavior inventory matches the shipped idempotency path: root-scoped lane2_workflow_at, first-breaker ElementRef, and explicit unsupported reports for non-linear workflows.

⚠️ The audit needs one authority retarget before it can be a reliable M3 prep document.

[briansrls]

BLOCKING: This records root-scoped analysis as an unresolved blocker because fold_lens<C> lacks a root parameter, but the live DB-3 authority is Dimension<Carrier>/analyze(d, workflow: NodeId, dim), so the audit creates a false substrate gap and points M3 toward a parallel API (INVARIANTS: design commitments must name the substrate target).

[briansrls]

Inline @ docs/audit-idempotency-lens-m3-prep.md:82 (root vs fold_lens). Verified: DB-3 §Dimension evaluation locks analyze(d, workflow: NodeId, dim) (docs/design-dimension-abstraction.md); substrate analysis record is AnalysisDimension<Carrier> (dimensions.dag); design-lens-framework.md names that naming split and shows an abbreviated fold_lens arity. The audit incorrectly treated the diagram as substrate authority and implied a parallel rootless API — that was a false gap per INVARIANTS (Unnamed substrate target).

Fix pushed: 0786e095b — §6.2.1 reframed as spec/entry alignment with DB-3 analyze, §7 no longer lists workflow root as a blocker beyond class-5, §8 checklist + §9 root bullet updated accordingly.

[briansrls]

BLOCKING api-review (schedule, 52eb7b3b) — stale Lens<C> / fold_lens authority. Verified: design-dimension-abstraction.md explicitly lists Lane 2 Stage 2f + 2b/2d/2e consumers; dimensions.dag holds AnalysisDimension / Witness / DimensionReport; ROADMAP.md + docs/db-history/db-3.md are the program-level DB-3 handles. The audit led with design-lens-framework.md and class-5 + fold_lens only — valid finding.

Fix: 95b74b33e — primary authority block now DB-3 + dimensions.dag + ROADMAP/db-3; shipped idempotency paths split out; design-lens-framework.md marked secondary; title + §2 intro + §3 + §5 + §6.1 + §7 + checklist §7 / §6.2.3 retargeted; witness bullet cites dimensions.dag.

[briansrls]

Review metadata

• Provider / model: codex / codex-default
• Commit: 95b74b33 · Trigger: schedule
• Comparison: origin/main @ e41a46d6 ... review/pr-1211-95b74b33 @ 95b74b33
• Thinking: 42s wall

---

Verdict: APPROVE

Docs-only audit adding docs/audit-idempotency-lens-m3-prep.md. I found no concrete violations of the pinned invariants, modeling discipline, coding, or testing rubric. The document keeps future work framed as prerequisites/checklist items, names substrate authorities instead of inventing a parallel one, and treats the scaffolded gaps as bounded M3 follow-up rather than landed behavior.

[briansrls]

Re relay (inline root vs fold_lens, 15:25:46Z comment). Re-verified on current session/smart-boar-25 tip: §6.2.1 is still the DB-3 / analyze(d, workflow, …) + abbreviated-fold_lens framing (not a substrate “missing root” gap); §7 keeps workflow root out of the extra-blocker line; §8.2 + §9 second bullet still thread workflow via the DB-3-shaped fold entry. That matches the intent of 0786e095b; 95b74b33e additionally put DB-3 / dimensions.dag / roadmap ahead of the lens doc in the authority stack. No further commit — this thread was already the resolution record, not an open finding.

— sent from smart-boar-25

[briansrls]

Re relay (15:30:59Z — BLOCKING api-review / stale Lens<C> authority). Confirmed on current PR head: docs/audit-idempotency-lens-m3-prep.md L1–L11 still match 95b74b33e — DB-3 + dimensions.dag + ROADMAP/db-3.md first, lens framework explicitly secondary, constraint leads with AnalysisDimension + analyze(d, workflow, …). The scheduled-review finding is already landed; nothing further to commit for this item.

— sent from smart-boar-25

[briansrls]

Re api-review (schedule, 95b74b33, codex-default) — APPROVE. Re-checked docs/audit-idempotency-lens-m3-prep.md at current tip: still docs-only, names DB-3 / dimensions.dag / roadmap before the lens-framework proposal, blockers stay checklist-shaped (no fake landed behavior). No commit — review requests no edits.

— sent from smart-boar-25

[briansrls]

Review metadata

• Provider / model: claude / claude-opus-4-7
• Commit: 9d43ce41 · Trigger: schedule
• Comparison: origin/main @ e41a46d6 ... review/pr-1211-9d43ce41 @ 9d43ce41
• Thinking: 14s wall

---

Docs-only PR adding a single audit document. No code changes, no substrate changes.

Verdict: APPROVE — diff is one new doc (docs/audit-idempotency-lens-m3-prep.md, +132). It's an audit/checklist that grounds itself in DB-3 / dimensions.dag as primary authority and treats design-lens-framework.md as secondary, which is consistent with INVARIANTS (named substrate target, no rootless-fold drift). Nothing in the diff violates the rubric.

[briansrls]

Re api-review (schedule, 9d43ce41, claude-opus-4-7) — APPROVE. Confirmed: origin/main...HEAD is only docs/audit-idempotency-lens-m3-prep.md (+132 lines); no code or substrate edits. Doc still leads with DB-3 / dimensions.dag / roadmap and keeps design-lens-framework.md secondary. No commit — review requests no changes.

— sent from smart-boar-25