@@ -8,6 +8,38 @@ While the major version is 0, minor version bumps may contain breaking changes.
 
 ## [Unreleased]
 
+### Added
+
+- `lash migrate-ids` rewrites `@depends-on` references left dangling by a
+  task-ID derivation change. It reports by default and writes only with
+  `--write`; `--forget` discards the pending renames for a project that would
+  rather repair by hand. Only whole references on `@depends-on:` lines are
+  rewritten — prose mentioning an old ID is left alone, and so is the
+  unqualified `old-id` form, since a bare token can name a file as readily as
+  a task.
+
+### Fixed
+
+- Stale task IDs no longer survive `lash index`. A task's ID is derived from
+  its title and is not written to the Markdown unless pinned with `@id:`, so a
+  release that changes the derivation rules moves every unpinned ID while every
+  content hash stays identical — and incremental indexing, which keys off those
+  hashes, never re-derives. A file nobody had edited kept serving IDs from
+  rules no longer in force: `lash show` printed the stored ID, `lash lint`
+  derived a different one and refused to resolve it, and `lash check-index`
+  called the index in sync throughout. The index now records the derivation
+  version it was built under and re-derives every file when that does not
+  match, so an upgrade repairs itself on the next `lash index`. The IDs that
+  moved are reported, and recorded for `lash migrate-ids` — the re-derive is
+  the only moment both spellings exist.
+- `lash check-index` compares stored task IDs against freshly derived ones
+  instead of only comparing content hashes, which by construction cannot see a
+  change in how IDs are derived from unchanged content.
+- `lash lint` now says when an unresolved reference points at a task ID that a
+  derivation change moved, rather than at a task that is missing. Without it
+  the error reads as a false positive: the ID it names is exactly the one
+  `lash show` prints back.
+
 ## [0.3.1] - 2026-08-11
 
 Two fixes to the root cause the 0.3.0 sweep left standing. The parsed model
 
@@ -123,6 +123,8 @@ lash format [PATH...]           # Normalize formatting
 # Indexing
 lash index                      # Update SQLite index after changes
 lash check-index                # Verify database consistency
+lash migrate-ids                # Show references left dangling by an ID rule change
+lash migrate-ids --write        # Rewrite those references
 
 # Dependencies & Links
 lash graph                      # Show dependency graph (ascii)
@@ -196,6 +198,22 @@ lash index --force    # Force full reindex
 lash check-index      # Verify consistency
 ```
 
+### Task IDs That Moved
+
+A task without an explicit `@id:` gets its ID derived from its title, so a
+release that changes the derivation rules moves every such ID. `lash index`
+detects this, re-derives the stored IDs, and records what each one used to be.
+References written against the old IDs stop resolving at that moment:
+
+```bash
+lash migrate-ids            # Show what changed and which references it affects
+lash migrate-ids --write    # Rewrite the references, then re-index
+```
+
+`lash check-index` reports stored IDs that no longer match the current rules,
+and `lash lint` says when an unresolved reference is one of these rather than a
+typo. Pin an ID with `@id:` to keep it stable across future changes.
+
 ### Broken References
 
 If `@depends-on` or `@doc` references are broken:
@@ -340,6 +358,7 @@ pub const TOP_LEVEL_SUBCOMMANDS: &[&str] = &[
     "init",
     "lint",
     "list",
+    "migrate-ids",
     "playground",
     "search",
     "show",
 
@@ -203,6 +203,18 @@ pub enum Commands {
         diff: bool,
     },
 
+    /// Rewrite references to task IDs that a derivation change moved
+    #[command()]
+    MigrateIds {
+        /// Rewrite the references (without this, only reports what would change)
+        #[arg(long)]
+        write: bool,
+
+        /// Discard the pending renames without rewriting anything
+        #[arg(long, conflicts_with = "write")]
+        forget: bool,
+    },
+
     /// List tasks matching specified criteria
     List {
         /// Filter by task ID (supports fuzzy matching)
 
@@ -95,6 +95,11 @@ pub fn execute(args: CheckIndexArgs) -> Result<i32> {
         verifier_config = verifier_config.with_paths(absolute_paths);
     }
 
+    // Re-deriving task IDs has to use the project's own parser settings, or
+    // the IDs compared against are not the ones this project would get.
+    let parser_config = lash_types::LashConfig::from_root(&project_root).unwrap_or_default();
+    verifier_config = verifier_config.with_parser_config(parser_config);
+
     let verifier = IndexVerifier::new(&conn, verifier_config);
 
     // Run verification
@@ -159,6 +164,7 @@ fn output_json_report(report: &lash_db::VerificationReport) -> Result<()> {
             "hash_mismatches": report.count_by_kind(lash_db::IssueKind::HashMismatch),
             "orphaned_tasks": report.count_by_kind(lash_db::IssueKind::OrphanedTasks),
             "orphaned_dependencies": report.count_by_kind(lash_db::IssueKind::OrphanedDependencies),
+            "stale_task_ids": report.count_by_kind(lash_db::IssueKind::StaleTaskIds),
         }),
     });
 
@@ -224,6 +230,11 @@ fn output_text_report(
         report.count_by_kind(lash_db::IssueKind::OrphanedDependencies),
         theme,
     );
+    print_issue_count_if_any(
+        "Stale task IDs (derived under older ID rules)",
+        report.count_by_kind(lash_db::IssueKind::StaleTaskIds),
+        theme,
+    );
 
     // Detailed issue list if requested
     if show_diff {
 
@@ -239,6 +239,13 @@ fn output_json_report(report: &lash_db::IndexReport, error_reporter: &ErrorRepor
         "files_deleted": report.files_deleted,
         "files_unchanged": report.files_unchanged,
         "has_changes": report.has_changes,
+        "id_derivation_rebuild": report.id_derivation_rebuild,
+        "id_renames": report.id_renames.iter().map(|r| json!({
+            "file": r.file_path.display().to_string(),
+            "old_id": r.old_full_id(),
+            "new_id": r.new_full_id(),
+            "title": r.title,
+        })).collect::<Vec<_>>(),
         "errors": {
             "count": summary.error_count,
             "files_affected": summary.files_affected.len(),
@@ -253,6 +260,12 @@ fn output_json_report(report: &lash_db::IndexReport, error_reporter: &ErrorRepor
     Ok(())
 }
 
+/// How many renamed IDs `lash index` spells out before summarising the rest
+///
+/// Past a handful the list stops being readable in a terminal, and
+/// `lash migrate-ids` shows the whole thing anyway.
+const MAX_LISTED_RENAMES: usize = 10;
+
 /// Output indexing report as human-readable text
 fn output_text_report(
     report: &lash_db::IndexReport,
@@ -308,6 +321,46 @@ fn output_text_report(
         println!("  Unchanged: {}", report.files_unchanged);
     }
 
+    // A re-derive that actually moved IDs is not a routine reindex: every
+    // reference written against one of the old IDs stopped resolving in this
+    // same moment. Say so here rather than letting `lash lint` be the first
+    // thing that mentions it, several commands later, without the context.
+    //
+    // Keyed on renames rather than on the re-derive itself, because a rule
+    // change need not affect any title in a given project, and warning about
+    // a repair that changed nothing would train people to ignore it.
+    if !report.id_renames.is_empty() {
+        println!();
+        let notice = format!(
+            "{} task ID{} changed: this index was built under older ID rules.",
+            report.id_renames.len(),
+            if report.id_renames.len() == 1 {
+                ""
+            } else {
+                "s"
+            }
+        );
+        if let Some(t) = theme {
+            println!("{}", t.style_warning(&notice));
+        } else {
+            println!("{notice}");
+        }
+        for rename in report.id_renames.iter().take(MAX_LISTED_RENAMES) {
+            println!("  {} → {}", rename.old_full_id(), rename.new_full_id());
+        }
+        if report.id_renames.len() > MAX_LISTED_RENAMES {
+            println!(
+                "  … and {} more",
+                report.id_renames.len() - MAX_LISTED_RENAMES
+            );
+        }
+        println!();
+        println!("Stored IDs now match what lash derives today. References written");
+        println!("against the old IDs will not resolve until they are updated:");
+        println!("  lash migrate-ids            # show what would change");
+        println!("  lash migrate-ids --write    # rewrite the references");
+    }
+
     // Print error summary
     let summary = error_reporter.summary();
     if summary.error_count > 0 {
@@ -433,6 +486,8 @@ mod tests {
                 error: "Parse error".to_string(),
             }],
             has_changes: true,
+            id_derivation_rebuild: false,
+            id_renames: vec![],
             profile: None,
         };
 
@@ -1023,6 +1078,8 @@ mod tests {
                 error: "Unexpected token".to_string(),
             }],
             has_changes: false,
+            id_derivation_rebuild: false,
+            id_renames: vec![],
             profile: None,
         };
 
@@ -1528,6 +1585,8 @@ mod tests {
             files_skipped: 0,
             errors: vec![],
             has_changes: false,
+            id_derivation_rebuild: false,
+            id_renames: vec![],
             profile: None,
         };
         output_text_report(&report_zero, false, &reporter, None);
@@ -1546,9 +1605,72 @@ mod tests {
                 files_skipped: 0,
                 errors: vec![],
                 has_changes: added > 0 || updated > 0 || deleted > 0,
+                id_derivation_rebuild: false,
+                id_renames: vec![],
                 profile: None,
             };
             output_text_report(&r, false, &reporter, None);
         }
     }
+
+    /// Build a report carrying `count` renamed IDs.
+    fn report_with_renames(count: usize) -> lash_db::IndexReport {
+        let id_renames = (0..count)
+            .map(|i| lash_db::TaskIdRename {
+                file_path: PathBuf::from("tasks.md"),
+                file_id: "tasks".to_string(),
+                old_local_id: format!("old-{i}"),
+                new_local_id: format!("new-{i}"),
+                title: format!("Task {i}"),
+            })
+            .collect();
+
+        lash_db::IndexReport {
+            files_processed: 1,
+            files_added: 0,
+            files_updated: 1,
+            files_deleted: 0,
+            files_unchanged: 0,
+            files_skipped: 0,
+            errors: vec![],
+            has_changes: true,
+            id_derivation_rebuild: true,
+            id_renames,
+            profile: None,
+        }
+    }
+
+    #[test]
+    fn test_json_report_carries_the_renamed_ids() {
+        // Machine consumers need the mapping, not just the count: it is the
+        // only record of what a reference used to mean.
+        let report = report_with_renames(2);
+        let reporter = ErrorReporter::new(ErrorReporterConfig {
+            verbosity: Verbosity::Normal,
+            output_format: OutputFormat::JsonPretty,
+            display_mode: ErrorDisplayMode::Batch,
+            theme: None,
+            show_summary: false,
+        });
+
+        assert!(output_json_report(&report, &reporter).is_ok());
+    }
+
+    #[test]
+    fn test_a_long_rename_list_is_truncated_not_dropped() {
+        // Silently printing only the first ten would read as "that was all".
+        let report = report_with_renames(MAX_LISTED_RENAMES + 3);
+        assert!(report.id_renames.len() > MAX_LISTED_RENAMES);
+
+        // Exercised for panics and for the truncation arithmetic; the text
+        // itself is asserted end-to-end in the integration tests.
+        output_text_report(&report, false, &text_reporter(), None);
+    }
+
+    #[test]
+    fn test_report_with_no_renames_is_the_quiet_path() {
+        let report = report_with_renames(0);
+        assert!(report.id_renames.is_empty());
+        output_text_report(&report, false, &text_reporter(), None);
+    }
 }
@@ -240,11 +240,21 @@ pub fn execute(args: LintArgs) -> anyhow::Result<i32> {
     }
 
     // Convert LintDiagnostic to Diagnostic for output
-    let diagnostics: Vec<Diagnostic> = filtered_diagnostics
+    let mut diagnostics: Vec<Diagnostic> = filtered_diagnostics
         .iter()
         .map(lint_diagnostic_to_diagnostic)
         .collect();
 
+    // An unresolved reference whose target the index still recognises is not
+    // an ordinary broken link; it is the signature of a task-ID derivation
+    // change. Saying so here saves the reader from concluding lint is wrong,
+    // which is the natural reading when `lash show` prints the very ID lint
+    // just rejected (GitHub issue #54).
+    let id_drift = project_root.as_deref().map_or_else(
+        crate::commands::migrate_ids::IdDriftNotice::default,
+        |root| crate::commands::migrate_ids::annotate_id_drift(&mut diagnostics, root),
+    );
+
     // Output results
     if args.json {
         // JSON output to stdout
@@ -258,6 +268,12 @@ pub fn execute(args: LintArgs) -> anyhow::Result<i32> {
             args.verbosity,
             args.suggest,
         )?;
+
+        // The per-diagnostic help only surfaces under `-v`. This note is not
+        // routine help — it is the reason the errors above are not the typos
+        // they look like — so it goes after the summary, once, at normal
+        // verbosity.
+        print_id_drift_notice(id_drift, theme.as_ref());
     }
 
     // Determine exit code based on errors
@@ -266,6 +282,37 @@ pub fn execute(args: LintArgs) -> anyhow::Result<i32> {
     Ok(if has_errors { 2 } else { 0 })
 }
 
+/// Print the ID-drift footer, if any references were explained by one
+///
+/// Kept out of `print_summary` because it is not a count of anything — it
+/// reframes errors already printed, and only appears when there is something
+/// to reframe.
+fn print_id_drift_notice(
+    notice: crate::commands::migrate_ids::IdDriftNotice,
+    theme: Option<&CliTheme>,
+) {
+    let Some(advice) = notice.advice() else {
+        return;
+    };
+
+    // The references above were correct when they were written; the rules
+    // moved underneath them. Saying which of the two it is turns a list of
+    // apparent typos into one known problem with one known fix.
+    let explained = notice.pending_migration + notice.stale_index;
+    let headline = format!(
+        "{explained} of these reference(s) point at task IDs that a derivation change \
+         moved, not at tasks that are missing."
+    );
+
+    println!();
+    if let Some(t) = theme {
+        println!("{}", t.style_warning(&headline));
+    } else {
+        println!("{headline}");
+    }
+    println!("  {advice}");
+}
+
 /// Output diagnostics in JSON format to stdout
 fn output_json_diagnostics(
     diagnostics: &[Diagnostic],