docs(phy): scaffold phy-options.md skeleton + directory README #37

Merged

navigator merged 1 commit from auto/issue-32-20260524T183617Z_issue32 into main

2026-05-24 15:41:04 -03:00

navigator commented

2026-05-24 15:39:30 -03:00

Owner

Summary

Replaces docs/phy/phy-options.md with a structural skeleton (executive summary, why-PHY-is-hard, three options, comparison matrix, deferred recommendation, open questions) per PLAN.md Section 13.4.
Every section carries a TODO marker; the comparison matrix has headers but empty rows; the recommendation is explicitly deferred to outreach issue #6.
Adds docs/phy/README.md so the directory is self-describing, matching docs/spec/README.md.

No fabricated vendor- or speed-specific claims — those are deferred to the outreach work in #6.

Acceptance criteria (from #32)

docs/phy/phy-options.md exists with the required structure.
Each section has a TODO marker indicating what is missing.
Comparison matrix is a markdown table with headers but mostly empty rows.
Document explicitly references the PHY outreach issue (#6) for fill-in work.
No fabricated technical claims about specific vendors or speeds.
docs/phy/README.md added (was previously absent) and briefly describes the directory.

Closes #32.

## Summary - Replaces `docs/phy/phy-options.md` with a structural skeleton (executive summary, why-PHY-is-hard, three options, comparison matrix, deferred recommendation, open questions) per PLAN.md Section 13.4. - Every section carries a `TODO` marker; the comparison matrix has headers but empty rows; the recommendation is explicitly deferred to outreach issue #6. - Adds `docs/phy/README.md` so the directory is self-describing, matching `docs/spec/README.md`. No fabricated vendor- or speed-specific claims — those are deferred to the outreach work in #6. ## Acceptance criteria (from #32) - [x] `docs/phy/phy-options.md` exists with the required structure. - [x] Each section has a `TODO` marker indicating what is missing. - [x] Comparison matrix is a markdown table with headers but mostly empty rows. - [x] Document explicitly references the PHY outreach issue (#6) for fill-in work. - [x] No fabricated technical claims about specific vendors or speeds. - [x] `docs/phy/README.md` added (was previously absent) and briefly describes the directory. Closes #32.

navigator added 1 commit

2026-05-24 15:39:31 -03:00

docs(phy): scaffold phy-options.md skeleton + directory README

build / scalafmt-check (pull_request) Successful in 7s

Details

build / sbt-compile (pull_request) Successful in 8s

Details

build / shell-lint (pull_request) Successful in 1m7s

Details

1c166e8967

PLAN.md Section 13.4 calls for a research report at docs/phy/phy-options.md as
one of the three Phase 1 PHY deliverables. The prior content asserted vendor-
and speed-specific claims that pre-empted the outreach work tracked in #6.

Replace it with a structural skeleton (executive summary, why-PHY-is-hard,
three options, comparison matrix, deferred recommendation, open questions).
Every section carries a TODO marker; the comparison matrix is headers-only;
the recommendation is explicitly deferred to the outreach issue.

Also add docs/phy/README.md so the directory is self-describing, matching the
pattern used by docs/spec/README.md.

Closes #32.