[Birfy]

Summary

Closes #805.

• New contributor page: docs/algorithm-decision-tree.md — when to use Algorithm card vs MethodPolicy vs full examples/ port vs aggregator_factory, with fidelity labels and one example each.
• Cross-links from algorithm-authoring / port-fidelity / aggregator-factory / porting-checklist; mkdocs nav entry.
• plan warns when acceptance / promotion (as well as conflict/fusion) are installed on a factory path and will be ignored — points at the decision tree and evolve: aggregator_factory should compose with merge Policies instead of dropping them #807 (no silent drop / compose factory ⊕ merge Policies). Does not change evolve core.

Test plan

• test_plan_names_merge_policies_a_factory_algorithm_replaces
• test_plan_warns_when_acceptance_is_ignored_on_factory_path
• CI required checks on the tip

Closes #805

[Birfy]

Self-review (Birfy)

Tip SHA: c8e083c
Ran:

• pytest -q tests/test_algorithms.py tests/test_mcp.py → pass (local; focused on plan warning + MCP unrelated)
• python -m tools.changelog_fragments check → pass
• risk_gate → T2
  Not run:
• full pytest -q suite — docs/plan-warning only; CI covers 3.9–3.13
• Ark real-model run — no model path changed
  Findings:
• none actionable; evolve: aggregator_factory should compose with merge Policies instead of dropping them #807 remains the engine follow-up for composing factory ⊕ merge Policies
  Verdict: PASS

[Birfy]

Verdict: PASS
Tip SHA: c8e083c
Ran: risk_gate.py → T2; full gh pr diff + tip test hunks for plan warnings
Not run: local pytest (defer to required CI build + test 3.9–3.13)

What this does

Closes #805 with a contributor-facing decision tree (docs/algorithm-decision-tree.md) for Algorithm card vs MethodPolicy vs full examples/ port vs aggregator_factory, including fidelity labels and four worked miniatures. Cross-links from algorithm-authoring / port-fidelity / aggregator-factory / porting-checklist + mkdocs nav are coherent and match the usability priority (call any algorithm / quickly implement a new one).

plan warning _merge_policies_replaced correctly widens the ignored merge-side slots from conflict/fusion to also acceptance/promotion on an aggregator_factory path, points at the decision tree and #807 (compose without silent drop), and does not change evolve core — right scope for a docs+plan PR.

Correctness

• Dropped-name filter and sorted list still produce a stable policies […] substring; existing test still asserts [conflict, 'fusion'] and the new acceptance-only case is covered by test_plan_warns_when_acceptance_is_ignored_on_factory_path.
• Negative path (gepa with no merge Policies) still asserts no factory-path warning after the string change from "replaced by" → "aggregator_factory path".
• Message text matches docs: factory replaces shipped merge pipeline; pass rules into constructor or drop from bundle until evolve: aggregator_factory should compose with merge Policies instead of dropping them #807.

Design fit

Aligns with in-flight #805/#807 and the #384 fidelity story (card ≠ examples/ port). Changelog fragment is accurate. No SKILL/integrations / host surface — T2 is appropriate.

Nits (non-blocking)

• Decision-tree ASCII diagram is clear; optional later: link each leaf to a concrete algorithms list --kind filter once fix(algorithms): kind filter + card vs examples/ port fidelity #810 lands.
• Warning still says evolve() may also RuntimeWarning — fine; when evolve: aggregator_factory should compose with merge Policies instead of dropping them #807 lands, both plan and evolve copy should be updated together.

Ready to squash-merge once required CI is green on this tip.

[Birfy]

Self-review (Birfy)

Tip SHA: 742e3e1
Ran:

• pytest -q tests/test_example_entrypoints.py::test_porting_checklist_stays_short tests/test_algorithms.py::test_plan_warns_when_acceptance_is_ignored_on_factory_path → pass
• risk_gate still T2 (docs + cli plan warning)
  Not run:
• full suite — CI re-run on this tip
• Ark real-model run — no model path changed
  Findings:
• none (prior tip failed only on checklist length)
  Verdict: PASS

[Birfy]

Verdict: PASS
Tip SHA: 742e3e1
Ran: risk_gate.py → T2; pytest tests/test_example_entrypoints.py::test_porting_checklist_stays_short tests/test_algorithms.py::test_plan_warns_when_acceptance_is_ignored_on_factory_path tests/test_changelog_fragments.py; python -m tools.changelog_fragments check
Not run: full pytest -q (defer to required CI build + test 3.9–3.13)

What this does

Closes #805 with the algorithm decision tree + plan warning when Policies(acceptance=) is ignored on a factory path. Tip advanced from c8e083c → 742e3e1 (porting-checklist / fidelity doc sync); prior PASS was on the old tip so this re-PASS matches current head.

Risk: T2. Will arm --auto --squash while required CI finishes.