docs: update systems engineering roadmap

[div0rce]

Summary

Documentation-only roadmap audit after PR #112 (2369f84). This updates future systems-engineering scope and agent guidance without changing code, benchmark artifacts, completed milestone requirements, or merged PR references.

Final Dependency Order

• M43 — NUMA awareness study with CPU affinity, scheduler migration, core pinning, and cache-locality caveats.
• M44 — Ingress queue memory-ordering and false-sharing study.
• M45 — Exchange-grade persistence prototype.
• M46 — Recovery benchmarking.
• M47 — Contiguous order-book storage and cache-locality study.
• M48 — DPDK research and prototype.
• M49 — NIC offload and low-latency networking study.

Placement Decisions

• M43 expansion: the existing NUMA milestone is the right owner for CPU affinity, taskset / pthread_setaffinity_np experiments, scheduler migration measurements, core pinning docs, cache-locality caveats, and unsupported-host labeling.
• M44 decision: existing M44 already owned ingress contention/backpressure work, so it is expanded in place into ingress memory-ordering and false-sharing validation instead of adding a duplicate concurrency milestone.
• M47 insertion: contiguous order-book storage is a distinct remaining storage-architecture gap after M32 PMR and PR feat: close storage flow and tcp follow-ups #112 intrusive pooled storage. It is inserted before DPDK/NIC because it exercises the current simulator directly.
• M48/M49 shift: DPDK and NIC offload remain in the roadmap, but intentionally late-stage after CPU locality, false sharing, storage architecture, Linux profiling, and external-review visibility.

Rejected Proposals

• mmap artifact logging: too much complexity for the current value; replay/artifact-bundle work is sufficient.
• Bitwise float sanitization: integer ticks intentionally avoid the problem.
• constexpr string hashing: low systems signal relative to concurrency, storage, Linux evidence, and review.
• SIMD liquidation engine: no liquidation engine exists; this would be synthetic optimization work.

Agent Guidance

• Expanded AGENTS.md and CLAUDE.md with architecture map, testing philosophy, performance philosophy, roadmap philosophy, and known constraints.
• Expanded docs/architecture.md with the concise Client -> Gateway -> Risk -> Matching Engine -> Replay Log -> Recovery -> Verification flow.
• Kept issue External technical review request #94 / external review visible in AGENTS.md, CLAUDE.md, HANDOFF.md, docs/review_request.md, and the review-request issue template.

History And Numbering

Completed milestone history was not rewritten. PR #112 is recorded as merged and #95/#28/#26 are recorded as closed. Numbering continuity is preserved by inserting M47 and shifting old M47/M48 to M48/M49.

Verification

• git diff --check
• make check (204/204 tests passed)

Note: local untracked changes.md was intentionally not included.

Summary by CodeRabbit

Release Notes

• Documentation
  • Expanded and clarified roadmap through M49 with focus on CPU affinity, cache-locality studies, and external review positioning.
  • Updated gateway limitations and benchmark scope in README.
  • Added architecture flow summary and performance measurement guidance.
  • Enhanced artifact documentation requirements for future benchmark results.

[div0rce]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 53b5e47f35

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[codescene-delta-analysis]

Our agent can fix these. Install it.

No application code in the PR — skipped Code Health checks.

Quality Gate Profile: Pay Down Tech Debt
Install CodeScene MCP: safeguard and uplift AI-generated code. Catch issues early with our IDE extension and CLI tool.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@PROGRESS.md`:
- Line 285: Update the markdown table row for "Docs | Systems-engineering
roadmap audit | `docs/systems-roadmap-audit`" so the PR column shows the active
PR number instead of "—"; set it to "`#113`" to match the PR referenced earlier in
the file (line showing PR `#113`) and keep the milestone row consistent with the
rest of the document.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 4dca2502-ff6f-4509-b7cc-f4b93545aa8b

📥 Commits

Reviewing files that changed from the base of the PR and between 2369f84 and 583a130.

📒 Files selected for processing (15)

• .github/ISSUE_TEMPLATE/review_request.md
• AGENTS.md
• CHANGELOG.md
• CLAUDE.md
• HANDOFF.md
• MILESTONES.md
• PROGRESS.md
• README.md
• docs/architecture.md
• docs/linux_performance.md
• docs/pool_backed_storage.md
• docs/recruiting_notes.md
• docs/release_readiness.md
• docs/review_request.md
• results/README.md

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Fill the active PR number in the docs-audit milestone row.

Line 285 leaves PR as —, but Line 35 already states PR #113 is open. Keep these in sync to avoid resume-state drift.

Suggested patch

-| Docs | Systems-engineering roadmap audit | `docs/systems-roadmap-audit` | ◐ in progress | — | Docs-only update to future systems roadmap and agent guidance |
+| Docs | Systems-engineering roadmap audit | `docs/systems-roadmap-audit` | ◐ in progress | `#113` | Docs-only update to future systems roadmap and agent guidance |

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	| Docs | Systems-engineering roadmap audit | `docs/systems-roadmap-audit` | ◐ in progress | — | Docs-only update to future systems roadmap and agent guidance |
	| Docs | Systems-engineering roadmap audit | `docs/systems-roadmap-audit` | ◐ in progress | `#113` | Docs-only update to future systems roadmap and agent guidance |

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@PROGRESS.md` at line 285, Update the markdown table row for "Docs |
Systems-engineering roadmap audit | `docs/systems-roadmap-audit`" so the PR
column shows the active PR number instead of "—"; set it to "`#113`" to match the
PR referenced earlier in the file (line showing PR `#113`) and keep the milestone
row consistent with the rest of the document.