Skip to content

Markdown fence migration

Jerry Holland edited this page Sep 29, 2026 · 3 revisions

Fence-aware Markdown indexing and migration

The ADR-0026 contract defines parser v2 and manifest v4, delivered for #51.

Supported backtick and tilde fences suppress heading and requirement entities. Historical manifests retain their original parser view until explicitly indexed. The planner blocks legacy inputs whose corrected boundaries differ, including an affected historical base; migrating branch tips alone does not repair that base.

Migrate a document

  1. Save the document and its existing sidecar in Git before migration. Work from a clean checkout and retain ordinary Git recovery.
  2. Run cst spec index <document.md> with the original repository history available. The writer verifies the original source, preserves surviving real entity IDs, removes false fence entities, and writes manifest v4. Unknown parser/schema versions or unavailable original bytes refuse before writing.
  3. Review both document and sidecar diffs. Run cst spec show <document.md> and check that code-example declarations are absent from the entity list while real entities retain their IDs. Commit the reviewed migration as a common baseline before starting new branches.
  4. Regenerate old semantic forecasts. Abort and restart pending operations with old semantic decisions; abort recovery remains available.
  5. If an existing merge has an affected legacy base, review an ordinary Git merge and reindex its result. Do not treat tip-only migration as permission to apply the blocked semantic plan.

If original source cannot be recovered, stop and restore the required history or source before retrying. --force does not bypass verification. Do not delete a sidecar to manufacture a migration with new identities. Review recovery against the saved commit; never discard unrelated work.

Shared conformance fixtures cover both corrected parser v2 behavior and historical views.

Home

Clone this wiki locally