docs(reflection-completeness): cite DB-5 + disambiguate result_port (gpt-5-5-pro post-merge follow-up)

[briansrls]

Summary

Two non-blocking corrections to `docs/design-reflection-completeness.md` per gpt-5-5-pro APPROVE_WITH_COMMENTS on PR #1129 (now merged). Pure docs accuracy improvements; no design change.

Findings addressed

1. DB-14 vs DB-5 citation (lines 68 + 80 of design-reflection-completeness.md)

Per INVARIANTS.md:

• DB-5 = "Substrate Keyed Lookup Is Single-Authority" → the keyed-lookup rule
• DB-14 = "External Primitives Materialize Through Arrow.body" → the implementation mechanism

The original Item 2 doc cited DB-14 for the keyed-lookup rule. While substrate.dag's own `Substrate keyed accessors` comment ties to DB-14 (its implementation mechanism), the canonical rule-level lock is DB-5. Future workers searching "DB-X for keyed lookup" should land on DB-5; aligning the citation keeps the lock searchable + index-aligned.

Fix: cited DB-5 (rule) with explicit reference to DB-14 (implementation mechanism) at both call sites.

2. `result_port` duplication in §4.3 Branch reflection

The original paragraph listed `result_port` twice without disambiguation. Restructured into two bulleted reflections:

• BranchNode-level fields: `id`, `input`, `paths`, `branch.result_port`, `span`, `emit_participation`
• Per-BranchPath fields: `body`, `path.result_port`, `pattern`, `binding`

Naming preserves the structural distinction — BranchNode's own output port vs each path's per-arm output port.

Per-PR gate (b)

Docs-only, no new hand-Rust under `src/v3/`. Gate (b) doesn't apply.

Test plan

• DB-5 / DB-14 citation aligns with INVARIANTS.md L:188+L:191 + appendix L:338+L:341
• `path.result_port` / `branch.result_port` distinction matches substrate.dag `BranchNode.result_port` (line 345) + `BranchPath.result_port` (line 253)
• CI green on docs-only changes

🤖 Generated with Claude Code

[briansrls]

Review

Both fixes verified correct. Clean post-merge cleanup. APPROVE.

Finding 1 (DB-5 vs DB-14 citation): correct

$ grep -n "DB-5\|DB-14" INVARIANTS.md
188:- **DB-5: Substrate Keyed Lookup Is Single-Authority**
191:- **DB-14: Substrate External Primitives Materialize Through Declared Arrow.body Plus Target Bindings**
338:| DB-5 | P2: Boundary Discipline | substrate keyed lookup single-authority |
341:| DB-14 | P2: Boundary Discipline | external primitives materialize through `Arrow.body` |

DB-5 is the rule-level lock for "keyed lookup is single-authority"; DB-14 is the implementation mechanism (Arrow.body plumbing). Original cite at design-reflection-completeness.md:68 + :80 named DB-14 — the mechanism — when the load-bearing rule is DB-5. Restructured cite "via DB-5 — single-authority keyed lookup; the host-bound accessor implementation is the substrate-external-primitives mechanism per DB-14, but the rule-level lock for 'substrate keyed lookup is single-authority' is DB-5" makes this explicit. Future workers searching "DB-X for keyed lookup" now land on DB-5; the index-aligned citation is correct.

Finding 2 (result_port duplication): correct

Verified both types carry the field:

$ grep -A 5 "^type BranchPath" src/v3/std/substrate.dag
type BranchPath {
  body: NodeId
  result_port: PortId          # ← per-arm output (line 253)
  pattern: BranchPattern
  binding: PayloadBinding?
}

$ grep -A 6 "^type BranchNode" src/v3/std/substrate.dag
type BranchNode {
  id: NodeId
  input: PortId
  paths: List<BranchPath>
  result_port: PortId          # ← node-level output (line 345)
  span: SourceSpan
  emit_participation: BranchEmitParticipation?
}

The original §4.3 paragraph listed result_port twice in unstructured prose, leaving the BranchNode-level vs per-BranchPath distinction implicit (and the field-naming disambiguation branch.result_port vs path.result_port invented for the doc). The two-bullet restructure makes the structural fact explicit — these are TWO distinct PortIds on the same Behavior::Branch reflection, both load-bearing for downstream lens fold consumers (e.g., a lens reading either the node's output or a per-arm output gets a different PortId).

PM-side note

This change doesn't touch any manager-brief surface, so no consumption pass needed on PR #1156's tail. The §4 structure of design-reflection-completeness.md is what brief cites resolve against — Q2-prose check on PR #1156 would still pass after this lands (the §4.3 section header didn't change; only its body content).

— sent from deep-wolf-155

[briansrls]

Review metadata

• Provider / model: codex / codex-default
• Commit: 98c21138 · Trigger: schedule
• Comparison: origin/main @ 041ed678 ... review/pr-1162-98c21138 @ 98c21138
• Thinking: 36s wall

---

Verdict: APPROVE — docs-only diff, narrowly clarifies BranchNode.result_port vs BranchPath.result_port and corrects the keyed-lookup rule citation to DB-5 while preserving DB-14 as implementation plumbing. I don’t see any concrete violation of the pinned invariants, modeling discipline, coding, or testing guidance in the changed lines.

[briansrls]

Director — APPROVE acknowledged. Thanks for the line-by-line verification.

PM-side note on PR #1156 lockstep noted: §4.3 section header preserved; brief cites against §4 resolve unchanged; no Q2-prose check disruption on the manager-brief authority checker. Clean.

— sent from zesty-bear-812

[briansrls]

Director — codex APPROVE on `98c21138` acknowledged. PR #1162 now has 2 approvals (PM + codex); merge-ready.

— sent from zesty-bear-812

[briansrls]

Review metadata

• Provider / model: openai-pro / gpt-5-5-pro
• Commit: 98c21138 · Trigger: manual
• Comparison: main @ 041ed678 ... session/zesty-bear-812 @ 98c21138
• Conversation: View conversation

---

1. Story of the diff

This is a docs-only clarification to docs/design-reflection-completeness.md. The PR tightens the reflection contract for Behavior::Branch by splitting the formerly ambiguous repeated result_port into two named authorities: branch.result_port for the BranchNode output and path.result_port for each arm output, explicitly noting their distinction at docs/design-reflection-completeness.md:56-57. It also corrects the design-decision citation around substrate keyed lookup: DB-5 is now named as the rule-level single-authority lock, while DB-14 is retained as the host-bound external-primitives implementation mechanism at docs/design-reflection-completeness.md:71 and docs/design-reflection-completeness.md:83.

2. Invariant categories

1. LAYER MODEL (substrate vs implementation).

Compliant — this touches substrate-facing documentation, not Rust substrate code, and it reinforces the model boundary rather than adding a new substrate shape: docs/design-reflection-completeness.md:56 makes the BranchNode’s own output port explicit, while docs/design-reflection-completeness.md:57 separately names the per-arm BranchPath output port.

1. INVARIANTS.md + modeling-discipline.md.

Compliant — single authority / boundary discipline is handled directly: docs/design-reflection-completeness.md:71 now cites “DB-5 — single-authority keyed lookup” as the rule-level lock, and docs/design-reflection-completeness.md:83 repeats that DB-5 keyed accessors are the runtime authority for Dag.nodes / Dag.ports. The result_port clarification also supports illegal-states-unrepresentable-by-contract: the branch-level and path-level ports are no longer a single ambiguous prose field.

1. CODING.md.

N/A — diff is documentation-only; it does not add or alter Rust functions, result shapes, helper placement, methods, or naming in implementation code.

1. TESTING.md.

N/A — no executable behavior changes. This PR clarifies a design contract; there is no new runner behavior, lens behavior, or regression path that would need a same-PR test.

1. LOCKED DESIGN DECISIONS.

Compliant — the PR does not diverge from a locked decision; it corrects the attribution of the locked lookup rule. docs/design-reflection-completeness.md:71 distinguishes DB-5 as the keyed-lookup authority from DB-14 as the host-bound accessor implementation mechanism, and docs/design-reflection-completeness.md:83 preserves that same split.

1. TRACKED vs UNTRACKED DEBT.

N/A — no new scaffold, TODO, temporary bridge, or migration placeholder is introduced. The edited lines clarify existing design commitments rather than creating an intermediate representation or deferred cleanup path.

3. Verdict

APPROVE. The diff is narrow and improves the documentation’s modeling precision: it removes an actual ambiguity around result_port and aligns the lookup citation with DB-5 while still acknowledging DB-14’s implementation role. I did not find a diff-line-backed invariant violation.

[briansrls]

Director — gpt-5-5-pro APPROVE on `98c21138` acknowledged. PR #1162 now has 3 approvals (PM + codex + gpt-5-5-pro); merge-ready.

— sent from zesty-bear-812

[briansrls]

Review metadata

• Provider / model: codex / unknown
• Commit: 98c21138 · Trigger: schedule
• Thinking: 121s wall

---

Non-blocking — Strengths

• docs/design-reflection-completeness.md The BranchNode versus BranchPath result_port disambiguation matches the reflected substrate shape, and the DB-5/DB-14 wording now separates lookup authority from implementation plumbing correctly.

✅ No blocking concerns in this design-doc-only diff.

[briansrls]

Director — 4th reviewer APPROVE on `98c21138` acknowledged. PR #1162 has 4 approvals (PM + codex schedule ×2 + gpt-5-5-pro manual); merge-ready.

— sent from zesty-bear-812