Realign spec and plan with implementation; add spec case 28 E2E

Three review findings:

- JSON contract drift: spec/plan documented `path, line, host, url`
  but `url` actually carried the full line excerpt. Update spec and
  plan to match the implemented shape: `path, line_no, host, line`.
  The new names describe what the fields contain.

- Stale resolved-gix section: spec previously declared "No tree-vs-
  tree Platform machinery is used" and prescribed manual path-to-
  blob map walking. That approach silently broke renames, so the
  implementation now uses `old_tree.changes()` with `track_rewrites`
  and `for_each_to_obtain_tree`. Update the spec to describe the
  current approach and explain why the earlier resolution was
  reversed. Also refresh the staged/changed-vs pseudocode sketches.

- Spec case 28 coverage gap: add an E2E test for the "feature branch
  behind base" topology where merge-base(base, HEAD) == HEAD, so the
  diff is empty even when the base ref has introduced a violation.

Author: aram356

crates/trusted-server-cli/tests/lint_domains_cli.rs

@@ -306,6 +306,79 @@ fn changed_vs_reports_feature_branch_lines() {
         .stdout(predicate::str::contains("disallowed host test.com"));
 }
 
+/// Spec case 28: when HEAD is behind the base ref, the merge-base
+/// is HEAD itself and the diff is empty — so no violations are
+/// reported even if the base ref has introduced one. This exercises
+/// the merge-base path with an "anti-symmetric" topology.
+#[test]
+fn changed_vs_branch_behind_base_reports_nothing() {
+    let temp = tempfile::tempdir().expect("should create tempdir");
+    let repo = common::init_repo(temp.path());
+
+    // Base: a single clean commit on `main`.
+    std::fs::write(temp.path().join("a.rs"), "let ok = 1;\n").expect("should write base");
+    common::stage_all(&repo);
+    common::commit_all(&repo, "base");
+
+    // Branch from `main` at the base commit (no further commits on
+    // the feature branch — HEAD is at the merge-base).
+    common::create_and_checkout_branch(&repo, "feature");
+
+    // Advance `main` past the merge-base with a commit that, if
+    // wrongly attributed to the feature branch, would be a
+    // violation. Then move HEAD back to `feature`.
+    use gix::refs::transaction::{Change, LogChange, PreviousValue, RefEdit, RefLog};
+    use gix::refs::{FullName, Target};
+    let main_ref: FullName = "refs/heads/main".try_into().expect("valid ref name");
+    let head_edit = RefEdit {
+        change: Change::Update {
+            log: LogChange {
+                mode: RefLog::AndReference,
+                force_create_reflog: false,
+                message: gix::bstr::BString::from("switch to main"),
+            },
+            expected: PreviousValue::Any,
+            new: Target::Symbolic(main_ref),
+        },
+        name: "HEAD".try_into().expect("HEAD"),
+        deref: false,
+    };
+    repo.edit_reference(head_edit)
+        .expect("should switch HEAD to main");
+    std::fs::write(
+        temp.path().join("a.rs"),
+        "let ok = 1;\nlet ahead = \"https://test.com\";\n",
+    )
+    .expect("should write main-ahead change");
+    common::stage_all(&repo);
+    common::commit_all(&repo, "main: ahead of feature");
+
+    // Move HEAD back to feature.
+    let feature_ref: FullName = "refs/heads/feature".try_into().expect("valid ref name");
+    let head_edit = RefEdit {
+        change: Change::Update {
+            log: LogChange {
+                mode: RefLog::AndReference,
+                force_create_reflog: false,
+                message: gix::bstr::BString::from("switch to feature"),
+            },
+            expected: PreviousValue::Any,
+            new: Target::Symbolic(feature_ref),
+        },
+        name: "HEAD".try_into().expect("HEAD"),
+        deref: false,
+    };
+    repo.edit_reference(head_edit)
+        .expect("should switch HEAD back to feature");
+
+    // `--changed-vs main`: merge-base(main, feature) == feature, so
+    // diff is empty. The `main`-introduced violation must NOT appear.
+    ts_in(&temp)
+        .args(["dev", "lint", "domains", "--changed-vs", "main"])
+        .assert()
+        .code(0);
+}
+
 /// A `--changed-vs` ref that doesn't resolve in any of the four
 /// fallback locations is an environment error (exit 2), not a
 /// violation (exit 1).

docs/superpowers/plans/2026-05-18-ts-dev-lint-domains.md

@@ -2422,7 +2422,7 @@ pub fn run(args: crate::dev::lint::DomainsArgs)
                 path: line.path.clone(),
                 line: line.line_no,
                 host: v.host,
-                url_excerpt: line.content.clone(),
+                line_excerpt: line.content.clone(),
             });
         }
     }
@@ -2451,10 +2451,11 @@ pub fn run(args: crate::dev::lint::DomainsArgs)
 #[derive(Debug, serde::Serialize)]
 pub struct FileViolation {
     pub path: std::path::PathBuf,
+    #[serde(rename = "line_no")]
     pub line: usize,
     pub host: String,
-    #[serde(rename = "url")]
-    pub url_excerpt: String,
+    #[serde(rename = "line")]
+    pub line_excerpt: String,
 }
 
 fn emit_human(violations: &[FileViolation])

docs/superpowers/specs/2026-05-18-check-domains-design.md

@@ -806,48 +806,40 @@ fn staged_added_lines(repo_path: &Path)
     -> Result<Vec<DiffLine>, Report<DomainsLintError>>
 {
     let repo = gix::open(repo_path).change_context(DomainsLintError::OpenRepo)?;
-    let head_tree = repo
-        .head_commit().change_context(DomainsLintError::OpenRepo)?
-        .tree_id().change_context(DomainsLintError::OpenRepo)?;
-    let head_tree = repo.find_tree(head_tree).change_context(DomainsLintError::OpenRepo)?;
-    let index = repo.index().change_context(DomainsLintError::Index)?;
-
-    // Walk both sides into path -> blob_id maps.
-    let head_map = tree_blob_map(&head_tree)?;       // breadthfirst.files()
-    let index_map = index_blob_map(&index);          // entries() filtered to FILE
-
-    let mut out = Vec::new();
-    for (path, head_id, index_id) in classify_changes(&head_map, &index_map) {
-        if !path_is_scanned(&path) { continue; }
-        let old = head_id.map(|id| read_blob(&repo, id)).transpose()?;
-        let new = match index_id {
-            Some(id) => read_blob(&repo, id)?,
-            None => continue,            // deletion — no added lines
-        };
-        for (line_no, content) in added_lines(old.as_deref(), &new) {
-            out.push(DiffLine { path: path.clone(), line_no, content });
-        }
-    }
-    Ok(out)
+    let head_tree = match repo.head_commit() {
+        Ok(c) => repo.find_tree(c.tree_id()?.detach())?,
+        Err(_) => repo.empty_tree(),                 // unborn HEAD
+    };
+    // Materialise the index as a tree so we can diff trees uniformly
+    // with rename detection enabled.
+    let index_tree_id = write_index_to_tree(&repo)?;
+    let index_tree = repo.find_tree(index_tree_id)?;
+    collect_added_from_trees(&repo, &head_tree, &index_tree)
 }
 ```
 
-**The `gix` API surface is RESOLVED by the Phase 2 spike** — see
-`crates/trusted-server-cli/tests/spike_gix_staged_diff.rs` for the
-reference implementation and the
-[Resolved by the Phase 2 spike](#resolved-by-the-phase-2-spike)
-section for the full entry-point list. The conceptual operations:
+**The `gix` API surface is RESOLVED by the implementation** — see
+`crates/trusted-server-cli/src/dev/lint/domains.rs` for
+`collect_added_from_trees` and `write_index_to_tree`. The conceptual
+operations:
 
 1. Open the repository — `gix::open(path)`.
 2. Resolve the HEAD commit's tree — `repo.head_commit()?.tree_id()?`
-   then `repo.find_tree(id)?`.
-3. Read the index — `repo.index()?`.
-4. Walk the HEAD tree (`tree.traverse().breadthfirst.files()`) and
-   the index (`index.entries()`) into `path → blob_id` maps, then
-   compare the maps directly to classify Added / Modified / Deleted.
-   **No tree-vs-tree `Platform`/`for_each_to_obtain_tree` machinery
-   is used** — the direct map comparison is simpler and sidesteps
-   the index→tree conversion gix 0.83 does not expose cleanly.
+   then `repo.find_tree(id)?`. On an unborn HEAD use
+   `repo.empty_tree()`.
+3. Materialise the index as a tree — iterate `index.entries()`
+   filtered to `Mode::FILE`, `editor.upsert(entry.path(&index),
+EntryKind::Blob, entry.id)` on `repo.edit_tree(empty)`, then
+   `editor.write()`. This lets the same tree-vs-tree machinery
+   serve both staged and `--changed-vs` modes.
+4. Run a tree-vs-tree diff with rename detection —
+   `old_tree.changes()?` →
+   `Platform::for_each_to_obtain_tree(&new_tree, callback)` with
+   `track_rewrites(Some(Rewrites { copies: None, percentage:
+Some(0.5), limit: 1000, track_empty: false }))`. The callback
+   matches `Change::{Addition, Modification, Rewrite, Deletion}` —
+   pure renames (same blob, new path) yield no added lines, and
+   rename + edit diffs the matched old blob vs the new blob.
 5. Read each blob's content — `repo.find_object(id)?.data`.
 6. Run a line-level diff — `gix::diff::blob::Diff::compute(
 Algorithm::Myers, &InternedInput::new(old, new))`, then walk
@@ -859,8 +851,10 @@ Algorithm::Myers, &InternedInput::new(old, new))`, then walk
 - No diff-text parsing — line numbers and content come from typed
   hunk structs.
 - No locale / quote-path / `b/` prefix / `/dev/null` edge cases.
-- Renamed files are handled by `gix`'s change-detection (provides both
-  old and new path).
+- Renamed files are handled by `gix`'s built-in rename detection
+  (`track_rewrites` on the tree-diff `Platform`) — pure renames
+  introduce no added lines; rename + edit reports only the truly new
+  lines.
 - Filenames with spaces or non-UTF8 characters: `gix` paths are
   `BString` (byte strings). The script lossy-converts to UTF-8 for
   output and emits a stderr warning for non-UTF-8 paths.
@@ -881,31 +875,12 @@ fn changed_vs_added_lines(repo_path: &Path, reference: &str)
         .merge_base(base_id, head_id)
         .change_context_lazy(|| DomainsLintError::MergeBase { base: reference.into() })?
         .detach();
-    let base_tree = repo.find_tree(
-        repo.find_commit(merge_base)?.tree_id()?.detach()
-    )?;
-    let head_tree = repo.find_tree(
-        repo.find_commit(head_id)?.tree_id()?.detach()
-    )?;
+    let base_tree = commit_tree(&repo, merge_base)?;
+    let head_tree = commit_tree(&repo, head_id)?;
 
-    // Same map-comparison approach as staged_added_lines: walk both
-    // trees into path -> blob_id maps, classify, blob-diff each
-    // changed path. See the spike at tests/spike_gix_changed_vs.rs.
-    let base_map = tree_blob_map(&base_tree)?;
-    let head_map = tree_blob_map(&head_tree)?;
-    let mut out = Vec::new();
-    for (path, base_blob, head_blob) in classify_changes(&base_map, &head_map) {
-        if !path_is_scanned(&path) { continue; }
-        let old = base_blob.map(|id| read_blob(&repo, id)).transpose()?;
-        let new = match head_blob {
-            Some(id) => read_blob(&repo, id)?,
-            None => continue,
-        };
-        for (line_no, content) in added_lines(old.as_deref(), &new) {
-            out.push(DiffLine { path: path.clone(), line_no, content });
-        }
-    }
-    Ok(out)
+    // Same tree-vs-tree diff with rename tracking as staged mode;
+    // the index is just swapped for the merge-base tree.
+    collect_added_from_trees(&repo, &base_tree, &head_tree)
 }
 ```
 
@@ -1170,9 +1145,9 @@ Run `ts dev lint domains` (no args) for a full-repo audit.
   "violations": [
     {
       "path": "crates/trusted-server-core/src/foo.rs",
-      "line": 42,
+      "line_no": 42,
       "host": "test.com",
-      "url": "https://test.com/path"
+      "line": "let x = \"https://test.com/path\";"
     }
   ],
   "count": 1,
@@ -1899,15 +1874,35 @@ the question.
 InternedInput}` — `Diff::compute(Algorithm::Myers, &input)`,
      then `diff.hunks()`; each `Hunk.after` is the new-side token
      (line) range.
-   - **No tree-vs-tree `Platform` machinery is used.** Both the
-     staged and `--changed-vs` collectors walk the two trees into
-     `path → blob_id` maps and compare directly — simpler than
-     `for_each_to_obtain_tree` and avoids the index→tree conversion
-     gix 0.83 does not expose cleanly.
+   - **Tree-vs-tree diff with rename detection.** Both the staged
+     and `--changed-vs` collectors call `old_tree.changes()` →
+     `Platform::for_each_to_obtain_tree(&new_tree, ...)` with
+     `track_rewrites(Some(Rewrites { copies: None, percentage:
+Some(0.5), limit: 1000, track_empty: false }))`. The callback
+     iterates `Change::{Addition, Modification, Rewrite,
+Deletion}` — pure renames (same blob, new path) yield no
+     added lines; rename + edit diffs the matched old blob vs the
+     new blob.
+
+     **Resolution note:** an earlier revision of this spec rejected
+     `Platform`/`for_each_to_obtain_tree` and prescribed a manual
+     map-walk. That approach silently broke renames: a renamed file
+     hit `(None, Some(new_id))` and was diffed against an empty
+     blob, reporting every line of the renamed file as added
+     (including pre-existing violations the author never touched).
+     The current spec uses the `Platform` API so rename detection
+     is correct by construction.
+
+     For staged mode, the index is first materialised as a tree
+     via `Repository::edit_tree` → per-entry `Editor::upsert(path,
+EntryKind::Blob, entry.id)` → `Editor::write()`, then the
+     same tree-vs-tree path serves both modes.
+
    - **gix-config:** `File::from_path_no_includes(path,
 Source::Local)`, `File::set_raw_value` (dotted `AsKey` form —
      avoids the `File<'event>` invariance that bites
      `set_raw_value_by`), `File::raw_value`, `File::to_bstring`.
+
 2. **`gix` / `gix-config` version pins — RESOLVED.** `gix = 0.83`,
    `gix-config = 0.56`, same gitoxide release family. See
    [Cargo dependencies](#cargo-dependencies) for the full feature