docs(adr): add ADR-0026 three-id order identity

[NotAProfDev]

Summary

Closes #46.

Adds ADR-0026, closing the open client-order-id question from
ADR-0006 with a three-id
order-identity model, plus glossary updates. Produced in a /grill-with-docs
session.

What's decided

• Order Id (internal, lifecycle-stable) · Order Instruction Id (per
  place/amend/cancel; the idempotent-submit + reconciliation join key) · Broker
  Order Id (venue-assigned, learned from acks).
• Internal ids = derived-deterministic (EnvironmentId, generation, counter);
  generation is logged as an IncarnationStarted marker and reproduced by folding
  (never recomputed on replay).
• Env-wide order-counter; Account / Source stays off the id; two many-to-one
  resolution indexes; Core-owned chaining via supersedes in the canonical
  OrderInstruction (the adapter renders it to the venue).

Changes

• docs/adr/0026-order-identity-three-ids-deterministic.md (new) — the decision,
  rationale, rejected alternatives, ADR cross-refs.
• CONTEXT.md — sharpen Order; add Order Instruction, Order Id, Order Instruction Id, Broker Order Id, EnvironmentId.
• grilling spec — parked question marked resolved; new amend-before-ack
  sub-question noted; markdown emphasis/list style normalized.

Notes

• Docs-only — the crates remain skeletons. Pre-commit gate (fmt / taplo / typos
  / clippy -D warnings / nextest compile) is green.
• Follow-ups: the order state machine (the amend-before-ack edge), and the
  persistence substrate (the next grilling branch).

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added a new glossary term for environment identifiers and expanded order-related terminology.
  • Published a new architecture decision record explaining the updated order identity model.
  • Updated the architecture notes to reflect the revised order ID approach and a new edge-case question.
  • Made minor formatting and wording updates in the architecture spec for readability.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 4954a3ba-bbc2-451d-b7a0-e3f7e3ec4718

📥 Commits

Reviewing files that changed from the base of the PR and between 797a70c and 1ce04c2.

📒 Files selected for processing (3)

• CONTEXT.md
• docs/adr/0026-order-identity-three-ids-deterministic.md
• docs/superpowers/specs/2026-06-23-from-scratch-architecture-grilling.md

---

📝 Walkthrough

Walkthrough

Adds ADR-0026 documenting a three-role deterministic order identity scheme (Order Id, Order Instruction Id, Broker Order Id), expands the CONTEXT.md glossary with EnvironmentId and all new ID terms, and updates the architecture grilling spec to mark the client-order-id parked question resolved with a new amend-before-ack sub-question.

Order Identity Model Documentation

Layer / File(s)	Summary
CONTEXT.md glossary additions CONTEXT.md	Adds EnvironmentId entry and expands Order, Order Instruction, Order Id, Order Instruction Id, and Broker Order Id glossary definitions with lifecycle semantics, replay-stability notes, and avoidance guidance.
ADR-0026: three-ID model, construction, and chaining docs/adr/0026-order-identity-three-ids-deterministic.md	Defines the three ID roles, deterministic (EnvironmentId, generation, counter) construction with IncarnationStarted logging, crash-idempotence constraints, two replay-rebuilt resolution indexes, Core-owned supersession chaining via supersedes, wire-format rendering rules, and rejected alternatives (UUIDv7, content-hash, raw sequence numbers, per-Account counters).
Grilling spec update docs/superpowers/specs/2026-06-23-from-scratch-architecture-grilling.md	Replaces terse client-order-id resolution bullet with ADR-0026 summary, adds amend-before-ack as a new parked sub-question, and applies minor Markdown emphasis normalization.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• NotAProfDev/oath#45: Introduced the same architecture documentation corpus (CONTEXT.md, grilling spec) that this PR extends with the order-identity ADR and new glossary terms.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The grilling spec also includes unrelated typography and reflow edits outside the ADR-0026 scope.	Split incidental formatting cleanup into a separate docs-only PR and keep this change focused on the order-identity ADR and glossary updates.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title follows Conventional Commits and matches the ADR-0026 three-id order-identity change.
Linked Issues check	✅ Passed	The PR delivers the three-id model, deterministic ID scheme, replay markers, resolution indexes, glossary updates, and the grilling-spec closure required by #46.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/adr-0026-order-identity

---

_{Comment @coderabbitai help to get the list of available commands.}