docs(#1744): portability architecture guide + ADR-1703 acceptance (Phase 7 closeout) (#1745)

ADR-1703 Phase 7 / epic #1702 closeout. The mechanical teardown is already
complete across phases 1-6 (regex scanner retired P3, ratchet deleted P4,
allowlist portability-usage gone, windows-portability-ok comments swept,
every DEFECT.WINDOWS-* predicate rewritten per-phase). This phase delivers the
two remaining ADR-mandated closeout items:

- docs/contributing/adding-a-portability-rule.md: the forward architecture
  recipe (Diátaxis Explanation) — the five seams (rule / portability-vocab /
  platform-guard / disable-ban / ci-test-scope), the zero-escape-hatch contract,
  the shipped-rule catalog, and the step-by-step checklist for adding a new
  local/* portability rule.

- docs/adr/1703: Status Proposed -> Accepted (all seven phases shipped); a
  Phase 7 as-built note recording the two deviations from the Phase 0 catalog —
  Phase 6's rename-only scope decision (#1740) and the codex-review precision
  tightening on require-fs-op-fallback.

- docs/contributing/cross-platform-portability-rules.md: cross-link to the new
  guide from the rule reference.

No code, no test, no runtime change. Epic #1702 Phase 6 box checked; Phase 7
box + epic closure to follow at PR merge.

Closes #1744

Co-authored-by: review-bot <review-bot@gsd>
This commit is contained in:
Tom Boucher
2026-06-26 00:19:44 -04:00
committed by GitHub
parent 871621c3c8
commit 83685ea7a3
3 changed files with 182 additions and 2 deletions

View File

@@ -7,6 +7,10 @@ Windows-only defect is caught before it ships — not after it reaches the `wind
lane. The architecture and rationale are in [ADR-1703](../adr/1703-portability-enforcement-architecture.md);
this page is the practical reference + how-to.
> **Adding a new rule?** See [`adding-a-portability-rule.md`](./adding-a-portability-rule.md) —
> the five seams (rule / vocab / platform-guard / disable-ban / ci-scope), the zero-escape-hatch
> contract, and the step-by-step recipe.
These rules are **hard-fail with zero escape hatches**: there is no `// windows-portability-ok:`
comment and no `eslint-disable` for them (a `tests/portability-rule-disable-ban.test.cjs` check,
running outside ESLint, fails the build if you try). Legitimately platform-specific code must be