[HC-014] Hard cutover docs and spec to one truthful capability matrix

[doublemover]

Hard cutover policy: documentation states implemented behavior, rejected behavior, and reserved behavior through one capability matrix. No stale roadmap comments in source headers, no old-anchor redirect surface in active docs, no claim wording unsupported by executable evidence.

Source facts already established:

• README is honest about incomplete runtime behavior, ARC automation, errors, async, actors, metaprogramming, and interop.
• Source headers and docs repeatedly use milestone, lane, anchor, proof, and readiness wording.
• native/objc3c/CMakeLists.txt still describes a monolithic src/main.cpp state despite split target libraries.
• docs/reference/legacy_spec_anchor_index.md remains linked from active navigation.
• Spec files contain fallback, compatibility, old mode, and deferred runtime notes.

Required documentation tree:

• docs/support/
  • capability_matrix.md: sole public support matrix.
  • capability_matrix.schema.json: matrix schema.
  • evidence_map.md: executable evidence mapping.
• docs/compiler/
  • architecture.md
  • parser.md
  • semantic_analysis.md
  • lowering_and_ir.md
  • runtime.md
  • public_c_api.md
• docs/workflows/
  • commands.md
  • ci.md
  • validation.md
• docs/spec/
  • language_core.md
  • object_model.md
  • ownership.md
  • runtime_dispatch.md
  • modules.md
  • errors.md
  • concurrency_reserved.md

Required capability states:

• implemented: parser, sema, lowering, runtime, docs, and executable tests exist.
• rejected: parser or sema emits a canonical diagnostic.
• reserved: syntax or concept remains unavailable and documented as unavailable.
• internal: implementation helper not part of public Objective-C 3.0 behavior.

Required work:

• Create the capability matrix and schema.
• Move active docs to the tree above.
• Delete old-anchor redirect links from active docs and generated site navigation.
• Delete stale comments from CMake, public headers, AST, runtime headers, and pipeline headers.
• Replace milestone/lane/proof language with behavior contracts and evidence links.
• Update generated docs to consume the capability matrix.
• Make docs fail validation on unsupported support claims.

Maximum effort shared hoist pass:

• Hoist support claim parsing to one docs validation helper.
• Hoist evidence link validation to one helper.
• Hoist command docs generation to the workflow registry.
• Hoist spec capability statuses to the matrix schema.

Acceptance criteria:

• Active docs contain no stale monolithic-main comment, old-anchor navigation, runtime fallback claim, or old mode support claim.
• Every implemented capability links to an executable test.
• Every reserved capability links to a canonical diagnostic or reserved-status entry.
• Public docs read as product docs, not milestone logs.

[doublemover]

Current checkout evaluation after the hard-cutover integration commits: PARTIAL, keep open.

Landed work:

• New documentation support structure exists under docs/support, docs/compiler, docs/workflows, and docs/spec.
• The capability-doc validation command passed during the integration checkpoint.

Remaining blockers from the current checkout:

• Large legacy/stale-claim docs remain: spec/LOWERING_AND_RUNTIME_CONTRACTS.md is 6,541 lines, spec/MODULE_METADATA_AND_ABI_TABLES.md is 6,455 lines, and docs/objc3c-native.md is 1,869 lines.
• Direct audits still find legacy_spec_anchor, lane, milestone, proof, runtime fallback, and old runtime dispatch claims in docs/spec content.
• The repo does not yet have one clean canonical capability matrix and evidence map as the only truthful docs surface.

This should close after the docs/spec residue is deleted or rewritten into the canonical matrix, not while stale capability claims still live in the required roots.

[doublemover]

Checkpoint pushed: ac31f1519.

Capability docs progress:

• Added support_claims to the capability matrix schema and matrix rows for current implemented parser, sema, lowering, IR, runtime, and e2e behavior.
• Tied implemented support claims to tests/fixtures/canonical/manifest.json and executable npm run objc3c -- test-behavior-matrix evidence.
• Strengthened scripts/validate_capability_docs.py so implemented rows must link canonical support claims, every manifest support claim must appear exactly once in the matrix, and support docs cannot mention undeclared support claim IDs.
• Updated docs/support/capability_matrix.md, docs/support/evidence_map.md, and docs/spec/runtime_dispatch.md to point runtime-dispatch support through the canonical matrix/evidence surface.
• Added tests/tooling/test_capability_docs_validator.py coverage for report-only command rejection and missing behavior-matrix evidence.

Validation:

• python scripts/validate_capability_docs.py --check PASS
• $env:PYTHONPATH='scripts'; python -m pytest tests/tooling/test_objc3c_shared_json_schema.py tests/tooling/test_capability_docs_validator.py -q PASS (13 passed)
• npm run objc3c -- check-documentation-surface PASS
• npm run objc3c -- check-site PASS
• npm run objc3c -- lint PASS

Keeping this open. The canonical evidence rule is now executable, but broader stale wording and legacy docs/spec residue still need removal or migration into the capability matrix.

[doublemover]

Docs/capability checkpoint (May 6, 2026): landed and pushed 893a4af12.

Completed in this checkpoint:

• Reclassified the archived spec index as historical instead of a compatibility redirect.
• Replaced public-site compatibility route/gate wording with capability/importer/evidence wording.
• Updated spec/INTRODUCTION.md from opt-in compatibility-mode framing to canonical-only language surface plus capability-matrix evidence.

Validation evidence:

• python scripts/validate_capability_docs.py --check PASS.
• npm run objc3c -- check-documentation-surface PASS.
• npm run objc3c -- check-site PASS.
• python -m scripts.source_hygiene PASS after the final wording cleanup, active_findings 0.

Current closure status: still open. Capability docs validate, but broader docs/spec residue cleanup and final evidence map consolidation are not complete.

[doublemover]

Docs/capability checkpoint (May 6, 2026): landed and pushed 1455128eb.

Completed in this checkpoint:

• Reframed Part 1 around canonical-only Objective-C 3 support, capability states, evidence-backed conformance, and rejected-form diagnostics.
• Removed public site routing to archived spec anchors and routed support truth through the capability matrix and evidence map.
• Reclassified tutorial wording from migration/public proof framing toward canonicalization, checked-in examples, and executable evidence.
• Regenerated site/index.md from site/src/index.body.md.

Validation evidence:

• python -m scripts.source_hygiene PASS, active_findings 0.
• npm run objc3c -- check-site PASS.
• git diff --cached --check PASS.

Current closure status: still open. More broad docs/spec cleanup may remain before final capability-truth closure.