[M331][Lane-C][C002] Migration guides, comparison matrix, and onboarding implementation

[doublemover]

[M331][Lane-C][C002] Migration guides, comparison matrix, and onboarding implementation

Outcome

Implement the migration, comparison, and onboarding surfaces using the real package/app/tooling outputs from earlier milestones.

Why this matters

This issue exists inside M331 Adoption program, migration playbooks, and ecosystem legibility because it advances the milestone focus: turn technical completeness into practical adoption: migration playbooks from ObjC2 and adjacent ecosystems, capability narratives, performance and interoperability guidance, educational paths, and ecosystem-facing documentation that explains when and why to choose Objective-C 3. The milestone exit gate is: A serious external evaluator can understand the language, compare it honestly, migrate incrementally, and judge fit without relying on private maintainer context.

Design corrections folded in

• Treat adoption as a disciplined product/documentation program rather than scattered tutorials and showcase blurbs.
• Base migration and evaluator guidance on the real outputs from canonical apps, package workflows, and support claims.
• Keep public comparison language narrower than the actual support matrix and evidence.

Required deliverables

• Canonical schema, artifact, lowering, or tooling surfaces under schemas/, scripts/, tests/tooling/fixtures/, or tmp/reports/ as appropriate.
• Replayable generation path for any new machine-owned output.
• Generated publication artifacts kept in sync with the planning source of truth.

Acceptance criteria

• Onboarding and migration guidance are derived from live, runnable surfaces.
• Make the milestone's machine-owned artifact, schema, lowering, or tooling surface canonical and replayable.
• Avoid duplicate transitional outputs when one stable artifact surface will do.
• Preserve determinism across generated evidence, packaging, and public workflow entrypoints.

Primary implementation surfaces

• README, site, tutorials, migration guides, showcase, and stdlib program docs
• performance, interoperability, and support-matrix reporting surfaces
• canonical applications, templates, and package ecosystem workflows
• docs/runbooks/ and public command surfaces where external users need legible entry points
• tmp/reports/ adoption, migration, and documentation evidence

Useful repo references

• README.md, docs/tutorials/getting_started.md, docs/tutorials/objc2_to_objc3_migration.md, showcase/README.md, and site/ are the primary evaluator-facing narrative surfaces to tighten.
• docs/runbooks/objc3c_public_conformance_reporting.md, objc3c_performance_governance.md, and the release/distribution runbooks already carry the evidence-backed public claims this milestone should reuse.
• scripts/render_objc3c_public_command_surface.py and docs/runbooks/objc3c_public_command_surface.md are the canonical entrypoint index external evaluators will hit first.

Implementation guidance

• Prefer extending an existing generator, validator, schema, or runner over creating a new milestone-local tool unless the old one is structurally wrong.

Dependencies

• M331-C001

Notes

• Lane C is where the design becomes machine-checkable and replayable.
• Prefer integrating with existing compiler/runtime/tooling/package surfaces rather than creating milestone-specific parallel scaffolds.
• Store transient validation captures under tmp/ and make closeout evidence replayable.
• Keep public and internal claims narrower than the evidence wherever uncertainty remains.

Execution Order

• Direct milestone blockers: M328
• Direct issue blockers: M331-C001
• Directly unblocks: M331-D001
• Execution instruction: Complete the direct blockers for M331-C002 and keep the work on the canonical implementation path for M331.

[doublemover]

Implemented in commit f03db1aed.

Validation:

• python scripts/build_adoption_legibility_artifact_contract_summary.py
• python scripts/build_objc3c_adoption_legibility_evidence.py
• npm run build:site
• npm run check:docs:surface