docs: record that the concaveEdges fix will not be backported to 1.x

[gsdali]

What & why

Upstream have confirmed there will be no backport for OCCTSwift#695, the concaveEdges() / convexEdges() reentrant-edge misclassification.

The docs described the geometric-selection workaround as "a 1.x workaround with a known end date", which reads as though a patch release might arrive. It will not, and that difference matters: it is the difference between "wait" and "this is the shape of the code until we migrate".

Documentation only, no behaviour change. The one Swift edit is a comment.

What changed

Five files:

file	change
okf/decisions/concave-edge-classifier-can-select-wrong-edges.md	Version-scope section rewritten: no 1.x fix will land, why neither route to the fix is open to this package, the upstream escape hatch, and the root cause.
okf/log.md	The **Update**: line the standing rule asks for alongside an OKF entry.
CLAUDE.md	The OCCTSwiftViewport paragraph said that dependency "is currently revision-pinned to a main commit"; Package.swift:88 has carried from: "1.0.4" for some time. Put into past tense and kept as the standing reason this repo avoids revision pins.
recipes/01-mounting-bracket/README.md	Gotchas given the version scope, so the cookbook's own three files carry the whole record.
recipes/01-mounting-bracket/main.swift	Header comment matched to the above; dangling clause fixed.

The backport account, corrected

The first version of this PR said the fix was "too involved to backport". That contradicted the upstream record and was corrected in the second commit. What actually happened: a backport was built, merged and measured (OCCTSwift PR #700, all 4646 tests green on both CI jobs), then reverted, not for any defect in it but for what it costs the release branch. Merging main into refactor/381-pass1b, which carries the whole of v2.0.0, conflicted in 8 files across 18 regions, and those are not all mechanical.

The backport is not lost: re-landing means reverting the revert.

Root cause, recorded because it generalises

An edge or vertex index crossing the bridge addressed a topology occurrence rather than a position in the deduplicated enumeration that edges() / edgeCount / edge(at:) return. A 20 mm box has 12 distinct edges but 24 edge occurrences, so the two diverge from the first repeat onwards on any ordinary solid, and edgeConcavities() zips one against the other. Upstream root cause OCCTSwift#613, fix #650.

The durable lesson is broader than concaveEdges(): treat any bridge-crossing index with the same suspicion until 2.0.0.

Why neither route to the fix is open here

The fix is reachable from the refactor/381-pass1b branch and from the published v2.0.0-kernel.1 prerelease tag. Neither works for this package: from: "1.17.0" means >=1.17.0 <2.0.0, so it cannot resolve a 2.x version at all without a major bump, and a revision pin would propagate an unstable dependency to every downstream consumer.

Checklist

• New or changed behavior is covered by a unit test in the same PR

Not applicable: documentation only. No Swift behaviour changes; the recipe edit is a comment.

Notes for the reviewer

Scripts/policy-check.sh passes, no em-dashes in the diff, and recipes CI re-executes recipe 01.

The workaround itself is unchanged and still correct. This only fixes what the docs claim about its lifetime and its cause, so a future reader does not defer work waiting for a 1.x patch that is never coming.

🤖 Generated with Claude Code

[secondmouseAU-bot]

Review of this PR, verified against upstream OCCTSwift#695, Package.swift, CLAUDE.md, and the CI runs.

Verdict: approve. Documentation only, both CI workflows (policies, recipes) are green, no em-dashes in the diff, and the central claims check out. The maintainer confirmation on OCCTSwift#695 ("no backport to 1.x will happen") matches the new OKF wording, the from: "1.17.0" semver-floor claim matches Package.swift, and a sweep of the other places that discuss this workaround (recipe 03, the revolve-seams decision, the recipe READMEs, okf/index.md, okf/log.md) found no leftover "temporary workaround" wording. The two files touched are the right and only places with that phrasing.

A few polish suggestions, none blocking:

1. "Too involved to backport" contradicts the upstream record. The closing comment on OCCTSwift#695 records that a backport was built, merged, and green (upstream PR #700, all 4646 tests), then reverted for what it would cost the 2.0.0 refactor branch (8 files, 18 conflict regions), not for infeasibility. That comment also preserves the escape hatch: PR #700 can be re-landed by reverting the revert if the situation becomes untenable before 2.0.0. Since this PR exists to make this record accurate, worth correcting the inherited clause and capturing the escape hatch. (Strictly, the fix is also reachable via the published v2.0.0-kernel.1 prerelease tag this entry verifies against, not only a branch pin; equally unsuitable for a released library, so the conclusion stands.)

2. Missing okf/log.md line. The standing rule (CLAUDE.md, okf/index.md) is to record durable changes as OKF entries plus a log.md line, and every prior okf/ change has one there. A one-line **Update**: under the existing 2026-08-05 group would fit the pattern.

3. The new cross-reference points at a stale CLAUDE.md paragraph. The OCCTSwiftViewport note still says that dependency "is currently revision-pinned to a main commit", but Package.swift already carries from: "1.0.4". The reference is historically valid, but a reader following it lands on a description of a state that no longer exists. Consider freshening that paragraph in this same docs-only PR, or phrasing the pointer in past tense.

4. Optional: the Gotchas section of recipes/01-mounting-bracket/README.md describes the workaround without any version scope. A line noting this is a 1.x defect with no backport coming, pointing at the OKF entry, would complete the cookbook's "open one folder, read three files" record.

5. Nit: the recipe comment ends "...re-run the check in the OKF entry then rather than assuming." The dangling "assuming" reads abrupt next to the OKF entry's fuller "rather than assuming the migration carried the fix".

Risk is effectively nil: docs plus one code comment, no behaviour change, recipes CI re-executes recipe 01 and passes, mergeable clean.

[gsdali]

All five addressed in 76749be. Item 1 was a real error on my part, not a polish item.

1. "Too involved to backport" was wrong

I checked OCCTSwift#695's closing comment rather than taking it on faith, and you are right. The backport was built, merged and measured (PR #700, all 4646 tests green on both CI jobs), then reverted, not for any defect in it but for what it costs the release branch: merging main into refactor/381-pass1b conflicted in 8 files across 18 regions, and those are not all mechanical, since main and the refactor branch made genuinely different, individually correct decisions on the same lines.

That is a materially different fact from "too involved", and this PR existed specifically to make the record accurate, so thank you for catching it. Corrected, with the escape hatch captured: re-landing means reverting the revert.

I also pulled in the root cause, because it generalises past this one call. An edge or vertex index crossing the bridge addressed a topology occurrence rather than a position in the deduplicated enumeration that edges() / edgeCount / edge(at:) return. A 20 mm box has 12 distinct edges but 24 occurrences, so the two diverge from the first repeat onwards on any ordinary solid, and edgeConcavities() zips one against the other. Upstream root cause #613, fix #650. The durable lesson is to treat any bridge-crossing index with the same suspicion until 2.0.0, which is worth more than the specific concaveEdges() finding.

Your parenthetical is in too: the fix is reachable from the published v2.0.0-kernel.1 tag as well as the branch. Neither is open to this package, and I sharpened why: from: "1.17.0" means >=1.17.0 <2.0.0, so it cannot resolve a 2.x version at all without a major bump. That is a stronger reason than the revision-pin argument I originally gave.

2. Missing okf/log.md line

Added under the existing 2026-08-05 group. You are right that every prior okf/ change has one and this should not have been the exception.

3. Stale cross-reference

Confirmed: CLAUDE.md:83 said the OCCTSwiftViewport dep "is currently revision-pinned to a main commit", while Package.swift:88 has carried from: "1.0.4". Put into past tense and kept as the standing reason this repo avoids revision pins, which is what the new cross-reference was pointing at. Good catch that I had pointed a reader at a description of a state that no longer exists.

4. README Gotchas

Added the version scope, so the cookbook's own three files carry the whole record without needing the OKF entry to complete it.

5. Nit

Fixed: "re-run the check in the OKF entry at that point rather than assuming the migration carried the fix."

Verification

policy-check passes, no em-dashes in the diff, recipes CI re-executes recipe 01. Diff is 5 files, +37/-9, still documentation plus one code comment.

[secondmouseAU-bot]

Second-pass review on head 76749be (commit 2: "docs: correct the backport account, add the missing log line and cross-references").

Verdict: approve. All five first-pass findings are addressed, and every new claim was verified against the primary sources. CI (policies, recipes) is green on the new head, no em-dashes introduced.

Per item:

1. Backport account corrected. Now records that the backport was built, merged and green upstream (PR #700, 4646 tests) and then reverted for what it costs the 2.0.0 release branch, and captures the escape hatch: re-landing means reverting the revert. Checked against OCCTSwift#695's closing comment and PR #700's own body.
2. okf/log.md line added, under the 2026-08-05 group, in the log's established format.
3. CLAUDE.md OCCTSwiftViewport paragraph rewritten in past tense, states the resolution (from: "1.0.4", confirmed in Package.swift), and is kept as the standing reason this repo avoids revision pins.
4. Recipe README gotcha now carries the version scope, with a pointer to the OKF entry's repro.
5. Dangling "rather than assuming" fixed in the recipe comment.

Verification of the new content (root-cause paragraph): the occurrence-vs-deduplicated-enumeration account, the 12-distinct-vs-24-occurrence box count, and the edgeConcavities() zip mismatch all check out against upstream #613 (open, root cause) and #650 (closed, "Closes #613"); both exist and match their cited roles. #700 is the 1.x backport and reports the same test count. The semver claim (from: "1.17.0" means >=1.17.0 <2.0.0, cannot resolve a 2.x without a major bump) is correct SwiftPM semantics and matches PR #700's own account of why the fix was unreachable from this package. #613 remaining open is consistent: #650 landed on the refactor branch, not the default branch.

Consistency: the five files now tell one coherent story: no 1.x fix will land; the geometric selection is permanent while this repo is on 1.x; it becomes removable at a 2.0.0 migration, with the repro to re-run at that point.

Remaining nit, optional: the PR body's "What changed" section still lists only the original two files; the PR now touches five, so it could be refreshed (commit 2's message already records the additions).

No behaviour change, no new risks. Ready to merge.