feat(diff): identify a repository by remote, not by absolute path

A baseline is only useful in CI if it can be pinned on one machine and
graded on another. Comparability answered "are these the same repository?"
by comparing absolute RepoPath, which answers a question about location
instead. A baseline pinned at /home/runner/work/app/app and restored
against /Users/dev/src/app always raised different_repo, which the gate
treats as blocking — so a restored baseline artifact could never grade.
The delta underneath was correct the whole time; only the verdict was wrong.

Record the origin remote on GitInfo, normalized to host/path with scheme,
credentials, port and a trailing .git removed, and decide sameness from it
when both sides have one, falling back to the checkout directory name.
Normalization is what makes this work in practice: a runner cloning over
HTTPS with an injected token and a developer cloning over SSH are looking
at one repository, and an unnormalized comparison would decline to grade
every CI diff.

A remote rather than the root commit. `git rev-list --max-parents=0` is the
purer identity and works locally, but it is unreachable in a shallow clone,
which is what CI checkouts default to — it would fail in exactly the
environment this targets. Git stays a witness: one more read-only call
beside the three already there, degrading to empty the same way.

Two details that only show up across machines:

- Remotes are normalized again on read, not just at capture, so a baseline
  written by an older build — carrying a raw URL, or no remote at all —
  still compares correctly. A baseline outliving the build that wrote it is
  the point of a portable artifact.
- The directory-name fallback accepts either separator. A baseline written
  on a Linux runner and read on Windows carries the separator of the machine
  that wrote it, while filepath.Base uses the reader's, so one direction
  would compare a whole path against a single segment and always mismatch.

The mismatch message names which signal decided and keeps both paths: a
remote mismatch means the wrong baseline was fetched, a name mismatch on one
repository means a checkout was renamed, and the remedies differ.

Also:
- CI gains an advisory `architecture` job: enola grading enola on every PR,
  reporting the verdict to the step summary and never failing the build
- the example workflow becomes publish-on-main / restore-on-PR, so the base
  branch is never re-indexed and no merge-base checkout is needed
- baseline show reports the remote — after a restore, "which repo is this?"
  is no longer obvious from the path

Author: dejo1307

.github/workflows/ci.yml

@@ -53,6 +53,93 @@ jobs:
       - name: Golden + determinism
         run: go test -count=1 -run 'TestGolden|TestDeterminism' ./internal/engine/...
 
+  # Enola grading Enola: the gate this repo ships, run on this repo's own changes.
+  #
+  # ADVISORY — this job reports the verdict and always succeeds. It is here to prove the
+  # gate works on a real PR stream and to surface structural regressions for a human to
+  # judge, not to block merges yet. To make it enforcing, delete the `exit 0` at the end
+  # of "Grade the change" (see the comment there).
+  #
+  # The baseline comes from the PR's own merge base rather than a published artifact.
+  # That costs one extra index — which for this repo is ~200ms — and in exchange needs no
+  # cross-workflow artifact plumbing, no third-party action, and no push trigger. A repo
+  # large enough for that trade to hurt should use the publish/restore shape in
+  # examples/ci/architecture-gate.yml instead.
+  architecture:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # merge-base needs history; the default depth-1 clone has none
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      # Built ONCE, from the PR head, and kept outside the tree so it survives the
+      # checkouts below. Using one binary for both snapshots keeps the enola version and
+      # config hash identical on the two sides — rebuilding at the merge base would make
+      # them differ and the gate would (correctly) decline to grade.
+      - name: Build enola from this PR
+        run: go build -o /tmp/enola ./cmd/enola
+
+      - name: Pin a baseline from the merge base
+        run: |
+          # Be explicit about fetching the base branch: actions/checkout leaves a PR on a
+          # merge ref, and origin/<base> is not guaranteed to be present.
+          git fetch --no-tags --quiet origin \
+            "+refs/heads/${{ github.base_ref }}:refs/remotes/origin/${{ github.base_ref }}"
+
+          # Record the head as an explicit SHA: `git checkout -` is unreliable after a
+          # --detach, and returning to the wrong commit would grade the base against
+          # itself and always report clean.
+          head=$(git rev-parse HEAD)
+          base=$(git merge-base "$head" "origin/${{ github.base_ref }}")
+          echo "Baseline: $base"
+          echo "PR head:  $head"
+
+          git checkout --quiet --detach "$base"
+          /tmp/enola baseline pin
+          # .enola/ is gitignored, so the pinned baseline survives the checkout back.
+          git checkout --quiet --detach "$head"
+
+      - name: Grade the change
+        run: |
+          # Run without --warn-only so the verdict text stays honest about what the
+          # policy WOULD do; the job's advisory status comes from the exit 0 below.
+          set +e
+          /tmp/enola check 2>/dev/null | tee verdict.txt
+          code=${PIPESTATUS[0]}
+          set -e
+
+          {
+            echo '### Architecture'
+            case "$code" in
+              0) echo 'No structural regression.' ;;
+              1) echo '**Structural regression introduced** — advisory for now, see the verdict below.' ;;
+              2) echo 'The gate could not run (exit 2).' ;;
+              3) echo 'Declined to grade: the baseline was not comparable (exit 3). Not a statement about this change.' ;;
+              *) echo "Unexpected exit $code." ;;
+            esac
+            echo '```'
+            cat verdict.txt
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"
+
+          # Advisory: report, never block. Delete this line to make the gate enforcing —
+          # the exit code above is already the verdict.
+          exit 0
+
+      - name: Upload the verdict
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: architecture-verdict
+          path: verdict.txt
+          if-no-files-found: ignore
+
   # golangci-lint v2 (action @v8). The repo baseline is clean, so this gates the
   # whole tree — any new finding fails the build. Linter set in .golangci.yml.
   lint:

ARCHITECTURE.md

@@ -595,7 +595,7 @@ The engine lives in [`internal/diff`](internal/diff/diff.go) (pure `Compute` + d
 
 | Kind | Raised when | Treated as |
 |------|-------------|-----------|
-| `different_repo` | the two snapshots are of different repositories | blocking |
+| `different_repo` | the two snapshots are of different repositories (see [Repository identity](#repository-identity-portable-baselines) — *not* merely a different path) | blocking |
 | `version_mismatch` | different enola versions (extractor changes read as churn) | blocking |
 | `extractor_set` | a language present on one side only | blocking |
 | `ignore_globs` | the set of files parsed changed | blocking |
@@ -608,6 +608,19 @@ The engine lives in [`internal/diff`](internal/diff/diff.go) (pure `Compute` + d
 
 > Note on timestamps: `GeneratedAt` is RFC3339, i.e. **second** resolution, so a baseline pinned and then diffed inside the same second yields a zero gap. Zero is *simultaneous*, not inverted — `inverted_pair` requires a strictly negative gap. Treating zero as inverted made a no-op check on an untouched repository report "the current snapshot does not contain your change".
 
+#### Repository identity (portable baselines)
+
+A baseline is only useful in CI if it can be **pinned on one machine and graded on another**. That makes "are these the same repository?" a question about *identity*, not *location* — and comparing absolute `RepoPath` answered it with location. A baseline pinned at `/home/runner/work/app/app` and restored against `/Users/dev/src/app` always tripped `different_repo`, which the gate treats as blocking, so a downloaded baseline artifact could never grade. (The delta underneath was correct the whole time; only the verdict was wrong.)
+
+`facts.SameRepo` ([`internal/facts/repoidentity.go`](internal/facts/repoidentity.go)) decides it from two signals, strongest first:
+
+1. **Normalized git remotes**, when both snapshots have one. `facts.NormalizeRemote` reduces a remote URL to `host/path` — scheme, credentials, port and a trailing `.git` removed, lowercased — so every way of cloning one repository collapses to one identity: `git@github.com:org/app.git`, `https://github.com/org/app`, and a CI URL carrying an injected token all normalize to `github.com/org/app`. Without that, a runner cloning over HTTPS and a developer over SSH would read as two repositories.
+2. **The checkout directory name**, otherwise. Weaker — two unrelated repositories both checked out as `api/` look alike — but it is what exists for a repo with no remote, and it is strictly better than the absolute path it replaces. It compares the last segment across *either* separator, because a baseline written on a Linux runner and read on Windows carries the separator of the machine that **wrote** it.
+
+`GitInfo.Remote` is populated by one more read-only `git remote get-url origin` alongside the three calls already in `gitInfo()`, and degrades to empty exactly as they do (no git, no repo, no origin). It is normalized again on read, so a baseline written by an older build — carrying a raw URL, or no remote at all — still compares correctly. **A remote rather than the root commit**: `git rev-list --max-parents=0` looks like the purer identity, but it is unreachable in a shallow clone, which is what `actions/checkout` does by default.
+
+Both absolute paths stay in the warning text, and it names which signal decided, because the remedies differ: differing remotes mean the wrong baseline was fetched; differing directory names on one repository mean a checkout was renamed.
+
 ---
 
 ### The gate (`pkg/check`) — `diff_snapshot` as an exit code

README.md

@@ -697,7 +697,9 @@ New coupling (4):
 
 Lists cap at 12 entries with a `--detail` pointer, and `declares` edges - the mechanical one-per-new-symbol link to their module - always sort last, since they say nothing about what got coupled.
 
-Ready-made wiring: [`examples/hooks/pre-commit`](examples/hooks/pre-commit) (blocks only on exit `1`; a missing or incomparable baseline skips the gate rather than blocking someone over setup they haven't done) and [`examples/ci/architecture-gate.yml`](examples/ci/architecture-gate.yml) (a GitHub Action that pins a baseline from the PR's merge base).
+**Baselines are portable.** A baseline is identified by the repository's normalized git remote (falling back to the checkout directory name), not by the absolute path it was pinned at - so one pinned on a CI runner grades against a checkout anywhere else. That's what makes the CI shape cheap: the default branch publishes `.enola/baseline/` once, every PR restores it and diffs against it, and no job ever indexes the base a second time.
+
+Ready-made wiring: [`examples/hooks/pre-commit`](examples/hooks/pre-commit) (blocks only on exit `1`; a missing or incomparable baseline skips the gate rather than blocking someone over setup they haven't done) and [`examples/ci/architecture-gate.yml`](examples/ci/architecture-gate.yml) (publish-on-main, restore-on-PR).
 
 ### What it saved you - `--status`
 

cmd/enola/check.go

@@ -324,6 +324,12 @@ func describeBaseline(snap *facts.Snapshot) {
 			state = "dirty (uncommitted changes)"
 		}
 		fmt.Printf("  Git:       %s @ %s — %s\n", orUnknown(r.Git.Ref), shortCommit(r.Git.Commit), state)
+		// The repository identity a restored baseline is matched on. Shown because
+		// "which repo does this baseline describe?" is the question `show` exists to
+		// answer, and after an import the answer is no longer obvious from the path.
+		if r.Git.Remote != "" {
+			fmt.Printf("  Remote:    %s\n", r.Git.Remote)
+		}
 	}
 	fmt.Printf("  Facts:     %d · Insights: %d\n", len(snap.Facts), len(snap.Insights))
 	fmt.Printf("  Snapshot:  %s\n", orUnknown(m.Receipt().SnapshotID))

examples/ci/architecture-gate.yml

@@ -6,68 +6,98 @@
 #
 # HOW THE BASELINE GETS HERE
 # --------------------------
-# The gate needs something to compare against. This workflow pins a baseline from the PR's
-# own merge-base checkout, which requires no artifact plumbing and works on a fresh clone.
+# The gate needs a "before" to compare against. The default branch publishes its snapshot
+# once; every PR restores that artifact and diffs against it. The PR job therefore indexes
+# the tree ONCE — it never re-indexes the base — and needs no merge-base checkout and no
+# full-history clone.
 #
-# `fetch-depth: 0` is required. actions/checkout defaults to a depth-1 clone, which has no
-# merge-base to check out, and the gate would silently have nothing to compare against.
+# This works because a baseline is portable: `enola check` identifies a repository by its
+# normalized git remote (falling back to the checkout directory name), not by the absolute
+# path it was snapshotted at, so a baseline pinned on one runner grades against a checkout
+# anywhere else.
 #
-# A faster arrangement — publish the snapshot from the default branch once and restore it
-# here instead of re-indexing the base — needs baselines to survive moving between
-# machines, which they do not yet: comparability compares the absolute repo path, so a
-# baseline pinned under one checkout path declines to grade under another.
+# Sizing: roughly 550 KB of gzipped artifact per ~17k facts. For a very large monorepo,
+# prefer actions/cache over a per-run artifact.
 name: architecture
 
 on:
+  push:
+    branches: [main]
   pull_request:
 
 jobs:
-  gate:
+  # Publishes the baseline every time the default branch moves. PRs consume the most
+  # recent successful run of this job.
+  publish-baseline:
+    if: github.event_name == 'push'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
 
       - name: Install enola
         run: |
           curl -fsSL https://raw.githubusercontent.com/enola-labs/enola/main/install.sh | sh
           echo "$HOME/.local/bin" >> "$GITHUB_PATH"
 
-      - name: Pin a baseline from the merge base
-        run: |
-          # Record the PR head as an explicit SHA before moving: `git checkout -` is
-          # unreliable after a --detach, and returning to the wrong commit would make the
-          # gate grade the base branch against itself and always report clean.
-          head=$(git rev-parse HEAD)
-          base=$(git merge-base "$head" "origin/${{ github.base_ref }}")
-          echo "Baseline commit: $base"
-          echo "PR head:         $head"
+      - name: Pin the baseline
+        run: enola baseline pin
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: enola-baseline
+          path: .enola/baseline/
+          retention-days: 30
+
+  gate:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
 
-          git checkout --quiet --detach "$base"
-          enola --generate
-          enola baseline pin
+      - name: Install enola
+        run: |
+          curl -fsSL https://raw.githubusercontent.com/enola-labs/enola/main/install.sh | sh
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
 
-          # .enola/ is untracked, so the pinned baseline survives the checkout back.
-          git checkout --quiet --detach "$head"
+      # The baseline comes from the newest successful publish-baseline run on the default
+      # branch. `continue-on-error` covers the first-ever run, before any baseline has been
+      # published — see the next step.
+      - name: Fetch the published baseline
+        id: baseline
+        continue-on-error: true
+        uses: dawidd6/action-download-artifact@v6
+        with:
+          workflow: architecture.yml
+          branch: main
+          name: enola-baseline
+          path: baseline
+          if_no_artifact_found: fail
 
       - name: Grade the change
-        run: enola check
+        run: |
+          if [ "${{ steps.baseline.outcome }}" != "success" ]; then
+            echo "No published baseline yet — skipping the gate."
+            echo "It will start enforcing once publish-baseline has run on the default branch."
+            exit 0
+          fi
+          enola check --baseline baseline
 
       # `enola check` exit codes:
       #   0 clean · 1 regression (job fails) · 2 error · 3 declined (not comparable)
       #
-      # Codes 2 and 3 fail the job here by design: in CI they mean the gate did not
-      # actually run, and a gate that silently passes when it could not run is worse than
-      # no gate. Add `|| [ $? -eq 3 ]` if you would rather treat "declined" as a pass
-      # while rolling this out.
+      # Codes 2 and 3 fail the job by design: in CI they mean the gate did not actually
+      # run, and a gate that silently passes when it could not run is worse than no gate.
+      # Add `|| [ $? -eq 3 ]` if you would rather treat "declined" as a pass while rolling
+      # this out — a stale baseline does NOT produce 3, it warns and still grades, so 3
+      # really does mean the comparison was unsound.
 
       - name: Publish the verdict as JSON
-        if: always()
-        run: enola check --json > architecture-verdict.json || true
+        if: always() && steps.baseline.outcome == 'success'
+        run: enola check --baseline baseline --json > architecture-verdict.json || true
 
       - uses: actions/upload-artifact@v4
         if: always()
         with:
           name: architecture-verdict
           path: architecture-verdict.json
+          if-no-files-found: ignore

internal/diff/diff.go

@@ -296,6 +296,31 @@ func Compute(baseline, current *facts.Snapshot) *SnapshotDiff {
 	return d
 }
 
+// repoMismatchDetail says which signal decided that two snapshots are of different
+// repositories, and always carries both absolute paths.
+//
+// Naming the signal matters because the remedy differs: differing remotes mean the wrong
+// baseline was fetched, while differing directory names on the same repository mean a
+// checkout was renamed — recoverable by giving the checkout the expected name, or by
+// pushing a remote so the stronger signal applies. A bare "different repositories" left
+// the reader to guess which.
+func repoMismatchDetail(base, cur facts.SnapshotMeta) string {
+	baseRemote, curRemote := remoteOf(base), remoteOf(cur)
+	if baseRemote != "" && curRemote != "" {
+		return fmt.Sprintf("remote %s vs %s; paths %s vs %s",
+			baseRemote, curRemote, orDash(base.RepoPath), orDash(cur.RepoPath))
+	}
+	return fmt.Sprintf("%s vs %s — no git remote recorded on both sides, so the checkout "+
+		"directory name was compared", orDash(base.RepoPath), orDash(cur.RepoPath))
+}
+
+func remoteOf(m facts.SnapshotMeta) string {
+	if m.Git == nil {
+		return ""
+	}
+	return facts.NormalizeRemote(m.Git.Remote)
+}
+
 // compareMeta checks that two snapshots were generated over equivalent inputs and
 // returns comparability warnings for each mismatch that would distort the delta.
 // An auto-loaded baseline carries an empty Meta (only RepoPath) — its unknown
@@ -304,10 +329,14 @@ func Compute(baseline, current *facts.Snapshot) *SnapshotDiff {
 func compareMeta(base, cur facts.SnapshotMeta) Comparability {
 	var c Comparability
 
-	if base.RepoPath != "" && cur.RepoPath != "" && base.RepoPath != cur.RepoPath {
+	// Identity, not location. Comparing absolute paths made a baseline taken on a CI
+	// runner incomparable with the same repository on a workstation, which blocked the
+	// whole point of a portable baseline artifact. facts.SameRepo prefers the normalized
+	// git remote and falls back to the checkout directory name.
+	if !facts.SameRepo(base, cur) {
 		c.add(WarnDifferentRepo,
-			"baseline and current are different repositories (%s vs %s) — the delta is unlikely to be meaningful",
-			base.RepoPath, cur.RepoPath)
+			"baseline and current are different repositories (%s) — the delta is unlikely to be meaningful",
+			repoMismatchDetail(base, cur))
 	}
 
 	if base.EnolaVersion == "" || cur.EnolaVersion == "" {