Migrate a directional link label

Type: kb/types/instruction.md

Use this procedure only after semantic review has decided the successor assertion and classified every active edge. This is the repeated mechanical core extracted from the evidence and rationale migrations; it does not decide label meaning.

Preconditions

  • The successor completes source <label> target.
  • Every active old-label tuple has one disposition: successor, neighboring relation, removal, or one exclusion bucket.
  • Neighboring-label boundaries and authorization consequences are recorded.

If any active tuple is unclassified, stop and return to semantic review.

Migrate

  1. Rebuild the live baseline immediately before editing. Record each registered edge's old label, source path, resolved target, source/destination collections, and exclusion bucket. Do not reuse review-time counts after another session or approval wait.
  2. Make exclusion buckets mutually exclusive. Preserve generated reports, frozen evaluations or experiments, archived artifacts, immutable captures, historical workshop records, quotations, and ordinary prose unless a surface actively teaches the retired identifier.
  3. Compare the disposition ledger with the fresh baseline. Classify new tuples before proceeding; do not force them into the nearest existing bucket.
  4. Adopt the decision record, shared catalogue assertion, source collection authorizations, and current authoring guidance together. Replace old authorization rather than retaining a synonym. Add a source/destination pairing only when an adjudicated edge demonstrates it.
  5. Edit exact source/target tuples. A mechanical batch may apply the ledger, but do not use a repository-wide lexical replacement set.
  6. Reconcile independently from the edit mechanism:
  7. every baseline active tuple has exactly one expected successor or removal;
  8. active old-label edges are zero;
  9. every surviving old-label edge belongs to exactly one exclusion bucket;
  10. deferred neighboring-label cohorts retain their source/target tuples;
  11. new decision or guidance artifacts are counted separately from migrated tuples;
  12. final source/destination pairs are authorized by their source collection.
  13. Scan current recommendation, example, and procedure prose for instructions that would recreate the retired identifier. Leave explicitly historical discussion intact.
  14. Validate every changed KB artifact, run relevant tests, inspect the final diff, and complete the migration retrospective before committing.

Use a temporary disposition table rather than a retained general parser. At minimum record old_label, source, target, resolved_destination, bucket, and disposition. The corpus scanner must cover ordinary and bold footer links and fail visibly on syntax it cannot parse.

Capture surprises

Record a surprise when an expectation changes the plan, not merely when a routine command runs. Include expected state, observed state, why it mattered, local resolution, reusable lesson, and deferred owner. In particular, record concurrent corpus changes and any verification command that fails after mutating files.

Done when

The decision, catalogue, contracts, guidance, and mutable corpus agree; tuple and exclusion reconciliation passes independently; validation and tests pass; and the retrospective names remaining label-specific debt.